• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 自定义属性设置
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @xiang-shouxing-->
5<!--Designer: @xiang-shouxing-->
6<!--Tester: @sally__-->
7<!--Adviser: @HelloCrease-->
8
9当开发者希望在组件上设置自定义的属性时，可以使用自定义属性设置功能，在组件上设置自定义的属性。而这些自定义属性可以在其对应的FrameNode上获取，从而实现更自由的组件管理。
10
11>  **说明：**
12>
13>  从API version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
14
15## customProperty
16
17customProperty(name: string, value: Optional\<Object>): T
18
19设置组件的自定义属性。[自定义组件](../../../ui/state-management/arkts-create-custom-components.md)不支持设置自定义属性。
20
21**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
22
23**系统能力：** SystemCapability.ArkUI.ArkUI.Full
24
25**参数：**
26
27| 参数名 | 类型                                                 | 必填 | 说明                                                         |
28| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
29| name  | string | 是   | 自定义属性的名称。 |
30| value  | Optional\<Object> | 是   | 自定义属性的值。 |
31
32**返回值：**
33
34| 类型 | 说明 |
35| --- | --- |
36| T | 返回当前组件。 |
37
38
39## Optional\<T><sup>12+</sup>
40
41type Optional\<T> = T | undefined
42
43定义可选类型，其值可以是undefined。
44
45**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
46
47**系统能力：** SystemCapability.ArkUI.ArkUI.Full
48
49**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
50
51| 类型 | 说明                       |
52| ---- | -------------------------- |
53| T \| undefined | 定义可选类型，其值可以是undefined。 |
54
55## 示例
56
57在Column组件上设置自定义属性，并在其对应的FrameNode上获取所设置的自定义属性。
58
59```ts
60// xxx.ets
61import { FrameNode, UIContext } from '@kit.ArkUI';
62
63@Entry
64@Component
65struct CustomPropertyExample {
66  build() {
67    Column() {
68      Text('text')
69      Button('print').onClick(() => {
70        const uiContext: UIContext = this.getUIContext();
71        if (uiContext) {
72          const node: FrameNode | null = uiContext.getFrameNodeById("Test_Column") || null;
73          if (node) {
74            for (let i = 1; i < 4; i++) {
75              const key = 'customProperty' + i;
76              const property = node.getCustomProperty(key);
77              console.log(key, JSON.stringify(property));
78            }
79          }
80        }
81      })
82    }
83    .id('Test_Column')
84    .customProperty('customProperty1', {
85      'number': 10,
86      'string': 'this is a string',
87      'bool': true,
88      'object': {
89        'name': 'name',
90        'value': 100
91      }
92    })
93    .customProperty('customProperty2', {})
94    .customProperty('customProperty2', undefined)
95    .width('100%')
96    .height('100%')
97  }
98}
99```
100