• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Custom Property
2
3You can set custom properties on components. These custom properties can be obtained on their corresponding FrameNodes, allowing for more flexible component management.
4
5>  **NOTE**
6>
7>  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.
8
9## customProperty
10
11customProperty(name: string, value: Optional\<Object>): T
12
13Sets a custom property for this component. This API does not work for [custom components](../../../ui/state-management/arkts-create-custom-components.md#creating-a-custom-component).
14
15**Widget capability**: This API can be used in ArkTS widgets since API version 12.
16
17**Atomic service API**: This API can be used in atomic services since API version 12.
18
19**System capability**: SystemCapability.ArkUI.ArkUI.Full
20
21**Parameters**
22
23| Name| Type                                                | Mandatory| Description                                                        |
24| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
25| name  | string | Yes  | Name of the custom property.|
26| value  | Optional\<Object> | Yes  | Value of the custom property.|
27
28**Return value**
29
30| Type| Description|
31| --- | --- |
32| T | Current component.|
33
34
35## Optional<sup>12+</sup>
36
37Optional\<T>
38
39Defines the Optional type. The value can be **undefined**.
40
41**Atomic service API**: This API can be used in atomic services since API version 12.
42
43**System capability**: SystemCapability.ArkUI.ArkUI.Full
44
45**Widget capability**: This API can be used in ArkTS widgets since API version 12.
46
47## Example
48
49This example demonstrates how to set custom properties on a **Column** component and obtain these properties from its corresponding FrameNode.
50
51```ts
52// xxx.ets
53import { FrameNode, UIContext } from '@kit.ArkUI';
54
55@Entry
56@Component
57struct CustomPropertyExample {
58  build() {
59    Column() {
60      Text('text')
61      Button('print').onClick(() => {
62        const uiContext: UIContext = this.getUIContext();
63        if (uiContext) {
64          const node: FrameNode | null = uiContext.getFrameNodeById("Test_Column") || null;
65          if (node) {
66            for (let i = 1; i < 4; i++) {
67              const key = 'customProperty' + i;
68              const property = node.getCustomProperty(key);
69              console.log(key, JSON.stringify(property));
70            }
71          }
72        }
73      })
74    }
75    .id('Test_Column')
76    .customProperty('customProperty1', {
77      'number': 10,
78      'string': 'this is a string',
79      'bool': true,
80      'object': {
81        'name': 'name',
82        'value': 100
83      }
84    })
85    .customProperty('customProperty2', {})
86    .customProperty('customProperty2', undefined)
87    .width('100%')
88    .height('100%')
89  }
90}
91```
92