harmony 鸿蒙Custom Property

2025-06-12
浏览 (6)

Custom Property

You can set custom properties on components. These custom properties can be obtained on their corresponding FrameNodes, allowing for more flexible component management.

NOTE

The initial APIs of this module are supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version.

customProperty

customProperty(name: string, value: Optional<Object>)

Sets a custom property for this component. This API does not work for custom components.

Widget capability: This API can be used in ArkTS widgets since API version 12.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Name of the custom property.
value	Optional<Object>	Yes	Value of the custom property.

Optional¹²⁺

Optional<T>

Defines the Optional type. The value can be undefined.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Widget capability: This API can be used in ArkTS widgets since API version 12.

Example

This example demonstrates how to set custom properties on a Column component and obtain these properties from its corresponding FrameNode.

// xxx.ets
import { FrameNode, UIContext } from '@kit.ArkUI';

@Entry
@Component
struct CustomPropertyExample {
  build() {
    Column() {
      Text('text')
      Button('print').onClick(() => {
        const uiContext: UIContext = this.getUIContext();
        if (uiContext) {
          const node: FrameNode|null = uiContext.getFrameNodeById("Test_Column")||null;
          if (node) {
            for (let i = 1; i < 4; i++) {
              const key = 'customProperty' + i;
              const property = node.getCustomProperty(key);
              console.log(key, JSON.stringify(property));
            }
          }
        }
      })
    }
    .id('Test_Column')
    .customProperty('customProperty1', {
      'number': 10,
      'string': 'this is a string',
      'bool': true,
      'object': {
        'name': 'name',
        'value': 100
      }
    })
    .customProperty('customProperty2', {})
    .customProperty('customProperty2', undefined)
    .width('100%')
    .height('100%')
  }
}