We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
GuidesApplication FrameworkArkUIWindow ManagerOther Development ScenariosControlling Window Appearance (ArkTS)

Controlling Window Appearance (ArkTS)

Last updated: 2026-09-04 06:52
Content overview

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:

  • Display a subwindow or global floating window as a shaped window by setting the window mask.

  • Adjust the shadow effect of a subwindow or global floating window by setting the blur radius of the window edge shadow.

  • Adjust the edge display effect of a subwindow or global floating window by setting window rounded corners.

  • Make the window background consistent with the app page or theme style by setting the window background color.

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.

  • Use the setWindowMask() API to set the mask for a shaped window.

    The mask only supports a two-dimensional array input with integer values of 0 and 1. The number of rows in the array corresponds to the window height, and the number of columns corresponds to the window width. 0 indicates that the corresponding pixel is transparent and non-interactive, while 1 indicates that the corresponding pixel is opaque and interactive.

  • Starting from API version 26.0.0, the setWindowMaskWithAlpha() API is supported for setting the mask of a shaped window.

The mask supports array input with values in the range [0, 255], where the array length equals the window width multiplied by the window height. An integer value of 0 indicates that the corresponding pixel is transparent and non-interactive, 255 indicates that the corresponding pixel is opaque and interactive, and values between 0 and 255 indicate that the corresponding pixel is partially transparent and interactive. This API offers better performance than setWindowMask() and is recommended.

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.

Collapse
Word wrap
Dark theme
Copy code
  1. import { window } from '@kit.ArkUI';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. 

  4. @Entry
  5. @Component
  6. struct Index {
  7.   // ...
  8.   private windowMaskSub: window.Window | undefined = undefined;
  9. 

  10.   // ...
  11.   setWindowMask(window: window.Window) {
  12.     let windowMask: Uint8Array = new Uint8Array(this.winWidth * this.winHeight);
  13.     for (let i = 0; i < this.winHeight; i++) {
  14.       for (let k = 0; k < this.winWidth; k++) {
  15.         if ((i + k) < (this.winHeight + this.winWidth) / 2) {
  16.           windowMask[i * this.winWidth + k] = 0;
  17.         } else {
  18.           windowMask[i * this.winWidth + k] = 255;
  19.         }
  20.       }
  21.     }
  22.     window.setWindowMaskWithAlpha(windowMask, this.winWidth, this.winHeight);
  23.   }
  24. 

  25.   build() {
  26.     Row() {
  27.       Scroll(){
  28.         Column() {
  29.           // ...
  30.           Row() {
  31.             Button('setWindowMask for Sub Window')
  32.               .width('90%')
  33.               .type(ButtonType.Capsule)
  34.               .margin({
  35.                 top: 10
  36.               }).fontSize(18)
  37.               .onClick(() => {
  38.                 if(this.windowMaskSub) {
  39.                   this.setWindowMask(this.windowMaskSub);
  40.                 }
  41.               })
  42.           }
  43.         }
  44.         .width('100%')
  45.       }
  46.     }
  47.     .height('100%')
  48.   }
  49. 

  50. }
Index.ets

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.

  • You can use the setWindowShadowRadius() API to set the blur radius of the window edge shadow. This is only supported for subwindows and global floating windows.

    Here, a global floating window is used as an example to set the blur radius of its window shadow.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. // pages/page1.ets
    2. import { window } from '@kit.ArkUI';
    3. 

    4. @Entry
    5. @Component
    6. struct SliderDemo {
    7.   // ...
    8. 

    9.   // Set the blur radius of the window edge shadow.
    10.   setShadowRadius(val: number) {
    11.     const floatWindowObj = AppStorage.get<window.Window>('floatWindow');
    12.     floatWindowObj?.setWindowShadowRadius(val);
    13.   }
    14. 

    15.   build() {
    16.     // ...
    17.   }
    18. }
    Page1.ets

Setting Window Corner Radius

  • You can use the setWindowCornerRadius() API to set the corner radius of a window. This is only supported for subwindows and global floating windows.

    Here, a global floating window is used as an example to set its window corner radius.

    Collapse
    Word wrap
    Dark theme
    Copy code
    1. // pages/page1.ets
    2. import { window } from '@kit.ArkUI';
    3. 

    4. @Entry
    5. @Component
    6. struct SliderDemo {
    7.   // ...
    8. 

    9.   // Set the corner radius.
    10.   setCornerRadius(val: number) {
    11.     const floatWindowObj = AppStorage.get<window.Window>('floatWindow');
    12.     floatWindowObj?.setWindowCornerRadius(val);
    13.   }
    14. 

    15.   build() {
    16.     // ...
    17.   }
    18. }
    Page1.ets

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.

  • You can use the setWindowBackgroundColor() API to adjust the background color of the window content area, which primarily affects the part of the window that carries UI content. You can pass a case-insensitive hexadecimal RGB or ARGB color to adjust the background color. Starting from API version 18, the ColorMetrics type is supported.

  • You can use the setWindowContainerColor() API to set the background color of the main window container area on PCs, 2-in-1 devcies, or tablets. The window container background color covers the entire window area, including the title bar and content area. If not in the freeform window state, the effect is equivalent to setWindowBackgroundColor(). This API does not support setting the main window background to transparent when it is not in focus.

  • When both setWindowContainerColor() and setWindowBackgroundColor() are used, the content area displays the color set by setWindowBackgroundColor(), while the title bar displays the color set by setWindowContainerColor().

  • Starting from API version 26.0.0, the setWindowContainerModalColor() interface is supported for setting the background color of the main window container area on PCs or 2-in-1 devices to accommodate different UI design requirements. The background color set through this API applies to the entire window container area, including the title bar and content area. This API supports setting the main window background to transparent when it is not in focus.

NOTE

The sample code is as follows:

Collapse
Word wrap
Dark theme
Copy code
  1. import { ColorMetrics, window } from '@kit.ArkUI';
  2. import { hilog } from '@kit.PerformanceAnalysisKit';
  3. 

  4. const DOMAIN = 0x0000;
  5. 

  6. @Entry
  7. @Component
  8. struct Index {
  9.   @StorageLink('mainWindow') mainWindow: window.Window | undefined = undefined;
  10. 

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

  18.   aboutToAppear(): void {
  19.     this.applyWindowBackgroundColor();
  20.   }
  21. 

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

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

  39.     try {
  40.       const alpha = Math.round(this.alpha) / 255;
  41.       const colorMetrics = ColorMetrics.rgba(Math.round(this.red), Math.round(this.green),
  42.                             Math.round(this.blue), alpha);
  43.       this.mainWindow.setWindowBackgroundColor(colorMetrics);
  44.       this.applyModeText = 'Current mode: ColorMetrics.rgba(...)';
  45.       this.statusText = `setWindowBackgroundColor(ColorMetrics.rgba(${Math.round(this.red)}, ${Math.round(this.green)}, ${Math.round(this.blue)}, ${alpha.toFixed(2)})) success`;
  46.       hilog.info(DOMAIN, 'backgroundColor', this.statusText);
  47.     } catch (err) {
  48.       this.statusText = `setWindowBackgroundColor by ColorMetrics failed: ${JSON.stringify(err)}`;
  49.       hilog.error(DOMAIN, 'backgroundColor', this.statusText);
  50.     }
  51.   }
  52. 

  53.  // ...
  54. }
Index.ets
Setting Window Animation Effects (ArkTS)
Using WindowManager to Manage Multimodal Input Events (C/C++)
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in Guides
Enter a keyword.