目录

Controlling Window Appearance (ArkTS)

When to Use

Window appearance describes the display form and visual effect of a window on the screen. Currently, you can set the window appearance by configuring shaped windows, window shadows, window rounded corners, as well as the window background color.

You can customize the window appearance based on UI design and interaction requirements. For example:

Shaped Window

A shaped window is a window with a non-rectangular shape, and a mask is used to describe the shape of the shaped window. Only app subwindows and global floating windows can be set as shaped windows.

You can set the mask of a shaped window through the setWindowMask() or setWindowMaskWithAlpha() API to define the visible region of the window.

After setting the mask, the window will be displayed according to the mask shape, the window shadow will be disabled, and the corner radius of the window will become 0.

The following takes setting a shaped window for a subwindow as an example.

  1. Tap Create Sub Window to create a subwindow.

  2. After the subwindow is created, tap setWindowMask for Sub Window to set the subwindow mask using the setWindowMaskWithAlpha() API. The subwindow undergoes the following changes:

    • The subwindow becomes a triangle.
    • The shadow and rounded corners of the subwindow disappear.
    • The upper-left part of the subwindow's rectangular area becomes transparent and non-interactive. Tapping the Create Test Window button allows the event to pass through to that button, creating a green test window.
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  // ...
  private windowMaskSub: window.Window | undefined = undefined;

  // ...
  setWindowMask(window: window.Window) {
    let windowMask: Uint8Array = new Uint8Array(this.winWidth * this.winHeight);
    for (let i = 0; i < this.winHeight; i++) {
      for (let k = 0; k < this.winWidth; k++) {
        if ((i + k) < (this.winHeight + this.winWidth) / 2) {
          windowMask[i * this.winWidth + k] = 0;
        } else {
          windowMask[i * this.winWidth + k] = 255;
        }
      }
    }
    window.setWindowMaskWithAlpha(windowMask, this.winWidth, this.winHeight);
  }

  build() {
    Row() {
      Scroll(){
        Column() {
          // ...
          Row() {
            Button('setWindowMask for Sub Window')
              .width('90%')
              .type(ButtonType.Capsule)
              .margin({
                top: 10
              }).fontSize(18)
              .onClick(() => {
                if(this.windowMaskSub) {
                  this.setWindowMask(this.windowMaskSub);
                }
              })
          }
        }
        .width('100%')
      }
    }
    .height('100%')
  }

}

Window Shadow

A window shadow is a projection effect displayed at the window edge, which enhances the sense of depth between the window and the background, creating a visual effect of the window floating above the background.

Setting Window Corner Radius

Window Background Color

The window background color is used to control the background display effect of the window content area or the window container area.

You can choose to set the background color of the app content area or the window container area including the title bar based on business scenarios, to achieve effects such as transparent page backgrounds and unified overall window color schemes.

The sample code is as follows:

import { ColorMetrics, window } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0000;

@Entry
@Component
struct Index {
  @StorageLink('mainWindow') mainWindow: window.Window | undefined = undefined;

  @State alpha: number = 0;
  @State red: number = 0;
  @State green: number = 0;
  @State blue: number = 0;
  @State statusText: string = 'Move the sliders to change the current window background color.';
  @State applyModeText: string = 'Current mode: string (#AARRGGBB)';

  // Convert channel values from 0 to 255 into two-digit hexadecimal strings for concatenating #AARRGGBB.
  private toHex(value: number): string {
    return Math.round(value).toString(16).padStart(2, '0').toUpperCase();
  }

  // Generate a hexadecimal string of the current window background color in ARGB order.
  private getColorValue(): string {
    return `#${this.toHex(this.alpha)}${this.toHex(this.red)}${this.toHex(this.green)}${this.toHex(this.blue)}`;
  }
  // ...
  // Set the window background color directly using ColorMetrics.rgba(...).
  private applyByColorMetrics(): void {
    if (!this.mainWindow) {
      this.statusText = 'Current window is unavailable.';
      return;
    }

    try {
      const alpha = Math.round(this.alpha) / 255;
      const colorMetrics = ColorMetrics.rgba(Math.round(this.red), Math.round(this.green),
                            Math.round(this.blue), alpha);
      this.mainWindow.setWindowBackgroundColor(colorMetrics);
      this.applyModeText = 'Current mode: ColorMetrics.rgba(...)';
      this.statusText = `setWindowBackgroundColor(ColorMetrics.rgba(${Math.round(this.red)}, ${Math.round(this.green)}, ${Math.round(this.blue)}, ${alpha.toFixed(2)})) success`;
      hilog.info(DOMAIN, 'backgroundColor', this.statusText);
    } catch (err) {
      this.statusText = `setWindowBackgroundColor by ColorMetrics failed: ${JSON.stringify(err)}`;
      hilog.error(DOMAIN, 'backgroundColor', this.statusText);
    }
  }

  // ...
}