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 ManagerWindow Metadata Configuration

Window Metadata Configuration

Last updated: 2026-04-09 08:42
Content overview

metadata

The metadata tag represents custom metadata of a HAP. The tag value is an array and contains three subtags: name, value, and resource.

Table 1 metadata tag description

Expand
Subtag Description Data Type Optional
name Name of the data item. The value is a string with a maximum of 255 bytes. String Optional, defaults to an empty array
value Value of the data item. The value is a string with a maximum of 255 bytes. String Optional, defaults to an empty array
resource Custom data, which is a resource index. The value is a string with a maximum of 255 bytes. For example, $profile:shortcuts_config indicates that the data points to the /resources/base/profile/shortcuts_config.json file. String Optional, defaults to an empty array

Below are several use cases and examples for the metadata tag. You can customize the settings based on service requirements.

  1. Use the metadata tag to configure the default size and position (in vp) of the main window. The following name options are available:

    • ohos.ability.window.height: specifies the default height of the main window. value indicates the height.
    • ohos.ability.window.width: specifies the default width of the main window. value indicates the width.
    • ohos.ability.window.left: specifies the default left position of the main window. value indicates the configuration format: alignment mode +/- offset. The alignment mode can be center, left, or right. The default value is left. It can be omitted when the offset is 0.
    • ohos.ability.window.top: specifies the default top position of the main window. value indicates the configuration format: alignment mode +/- offset. The alignment mode can be center, top, or bottom. The default value is top. If both the alignment mode and offset are omitted, the default stacking specifications are used.

  2. Use the metadata tag to configure the enabled status of the removeStartingWindow API. Set name to enable.remove.starting.window, and set value to true to enable the API, or to false to disable it. The default value is false.

  3. Use the metadata tag to configure whether the main window is maximized upon startup. Set name to ohos.ability.window.isMaximize, and set value to true to maximize the main window upon startup, or to false to start in a non-maximized state. The default value is false. This configuration has the following restrictions:

    • The configuration takes effect only on PCs/2-in-1 devices.
    • If the supportWindowModes property in startOptions is used, the FULL_SCREEN option must be configured. In this case, the metadata tag can be used to configure the main window to start in maximized mode; otherwise, it does not take effect.
    • If the supportWindowMode property in the module.json5 file is used, the fullscreen option must be configured. In this case, the metadata tag can be used to configure the main window to start in maximized mode; otherwise, it does not take effect.
    • The priorities of the main window display settings are as follows: full-screen display > using startOptions to specify the size and position > using setWindowRectAutoSave() to enable window size memory > using the metadata tag to configure maximization > using the metadata tag to configure the size and position. You can configure full-screen display in any of the following ways:
      1. Set the windowMode property in startOptions to WINDOW_MODE_FULLSCREEN.
      2. Set the supportWindowModes property in startOptions only to FULL_SCREEN.
      3. Set the supportWindowMode property in module.json5 only to fullscreen.

  4. Use the metadata tag to configure the supported window modes in free windows mode. Set name to ohos.ability.window.supportWindowModeInFreeMultiWindow, and set value to fullscreen (full-screen mode), split (split-screen mode), floating (floating window mode), or any of their combinations (separated by commas, with no space), for example, fullscreen,split. This configuration takes effect only on a device that supports freeform windows and is in the freeform window state. If the device supports freeform windows but is not in the freeform window state, or if the device does not support freeform windows, this configuration does not take effect and no error is reported.

    In free windows mode, the supported window modes can be configured using multiple methods. The configuration priorities are as follows: using SetSupportedWindowModes to configure the window modes > using StartAbility to configure the SupportWindowMode property in StartOption > using the metadata tag to configure the window modes > configuring the SupportWindowMode property in the abilities tag of the module.json5 file.

    In non-free windows mode, only the SupportWindowMode property in the abilities tag of the module.json5 file can be used to configure the window modes. Other methods do not take effect.

Collapse
Word wrap
Dark theme
Copy code
  1. {
  2.   "module": {
  3.     "abilities": [{
  4.       "metadata": [{
  5.         "name": "ability_metadata",
  6.         "value": "a test demo for ability",
  7.         "resource": "$profile:config_file"
  8.       },
  9.       {
  10.         "name": "ability_metadata_2",
  11.         "value": "a string test",
  12.         "resource": "$profile:config_file"
  13.       },
  14.       {
  15.         "name": "ohos.ability.window.height",
  16.         "value": "987"
  17.       },
  18.       {
  19.         "name": "ohos.ability.window.width",
  20.         "value": "1300"
  21.       },
  22.       {
  23.         "name": "ohos.ability.window.left",
  24.         "value": "right-50"
  25.       },
  26.       {
  27.         "name": "ohos.ability.window.top",
  28.         "value": "center+50"
  29.       },
  30.       {
  31.         "name": "ohos.ability.window.isMaximize",
  32.         "value": "true"
  33.       },
  34.       {
  35.         "name": "enable.remove.starting.window",
  36.         "value": "true"
  37.       }
  38.       {
  39.         "name": "ohos.ability.window.supportWindowModeInFreeMultiWindow",
  40.         "value": "fullscreen,split,floating",
  41.       }],
  42.     }],
  43. 

  44.     "extensionAbilities": [{
  45.       "metadata": [{
  46.         "name": "extensionAbility_metadata",
  47.         "value": "a test for extensionAbility",
  48.         "resource": "$profile:config_file"
  49.       },
  50.       {
  51.         "name": "extensionAbility_metadata_2",
  52.         "value": "a string test",
  53.         "resource": "$profile:config_file"
  54.       }],
  55.     }]
  56.   }
  57. }
Window Rotation
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.