将属性直接设置给组件，无需标记为状态变量即可直接触发UI更新。

说明

从API version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

## 导入模块

PhonePC/2in1TabletTVWearable



```
1. import { AttributeUpdater } from '@kit.ArkUI';
```

说明

1. 由于与属性方法同时设置或者在AttributeUpdater中实现applyNormalAttribute等方法时，涉及到与状态管理更新机制同时使用，易出现混淆，因此不建议在同一组件上同时用两种方法设置相同属性。
2. 当与属性方法同时设置时，属性生效的原则为：后设置的生效。

   若先进行属性直通更新，后通过状态管理机制更新属性方法，则后更新的属性方法生效；

   若先通过状态管理机制更新属性方法，后进行属性直通更新，则属性直通更新生效。
3. 一个AttributeUpdater对象只能同时关联一个组件，否则将出现设置的属性只在一个组件上生效的现象。
4. 开发者需要自行保障AttributeUpdater中T和C的类型匹配。比如T为ImageAttribute，C要对应为ImageInterface，否则可能导致

   使用updateConstructorParams时功能异常。
5. updateConstructorParams当前只支持Button，Image，Text，Span，SymbolSpan和ImageSpan组件。
6. AttributeUpdater不支持深浅色切换等状态管理相关的操作。
7. 在[UI上下文不明确](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-global-interface#ui上下文不明确)的场景中调用[AttributeUpdater](/consumer/cn/doc/harmonyos-references/js-apis-arkui-attributeupdater#attributeupdatert-c--initializert)对象的接口时，建议使用[UIContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext)的[runScopedTask](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#runscopedtask)接口明确UI上下文，参考[执行绑定UI实例的闭包](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-global-interface#执行绑定ui实例的闭包)示例。

## Initializer<T>

PhonePC/2in1TabletTVWearable

type Initializer<T> = () => T

可以将属性更新到本地的修饰器。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| T | 返回当前组件。 |

## AttributeUpdater<T, C = Initializer<T>>

PhonePC/2in1TabletTVWearable

为[AttributeModifier](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-attribute-modifier#attributemodifiert)的实现类，开发者需要自定义class继承AttributeUpdater。

其中C代表组件的构造函数类型，比如Text组件的TextInterface，Image组件的ImageInterface等，仅在使用updateConstructorParams时才需要传递C类型。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

### applyNormalAttribute

PhonePC/2in1TabletTVWearable

applyNormalAttribute?(instance: T): void

定义正常态更新属性函数。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| instance | T | 是 | 组件的属性类，用来标识进行属性设置的组件的类型，比如Button组件的ButtonAttribute，Text组件的TextAttribute等。 |

### initializeModifier

PhonePC/2in1TabletTVWearable

initializeModifier(instance: T): void

AttributeUpdater首次设置给组件时提供的样式。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| instance | T | 是 | 组件的属性类，用来标识进行属性设置的组件的类型，比如Button组件的ButtonAttribute，Text组件的TextAttribute等。 |

**示例：**

通过initializeModifier方法初始化设置属性值。



```
1. // xxx.ets
2. import { AttributeUpdater } from '@kit.ArkUI';

4. class MyButtonModifier extends AttributeUpdater<ButtonAttribute> {
5. // 该AttributeUpdater对象第一次使用的时候触发的回调
6. initializeModifier(instance: ButtonAttribute): void {
7. instance.backgroundColor('#ffd5d5d5')
8. .labelStyle({ maxLines: 3 })
9. .width('80%')
10. }

12. // 该AttributeUpdater对象后续使用或者更新的时候触发的回调
13. applyNormalAttribute(instance: ButtonAttribute): void {
14. instance.borderWidth(1);
15. }
16. }

18. @Entry
19. @Component
20. struct Index {
21. modifier: MyButtonModifier = new MyButtonModifier();
22. @State flushTheButton: string = 'Button';

24. build() {
25. Row() {
26. Column() {
27. Button(this.flushTheButton)
28. .attributeModifier(this.modifier)
29. .onClick(() => {
30. // 通过AttributeUpdater的attribute对属性进行修改
31. // 需要注意先通过组件的attributeModifier属性方法建立组件与AttributeUpdater绑定关系
32. this.modifier.attribute?.backgroundColor('#ff2787d9').labelStyle({ maxLines: 5 });
33. })
34. .margin('10%')
35. Button('Trigger Button Update')
36. .width('80%')
37. .labelStyle({ maxLines: 2 })
38. .onClick(() => {
39. this.flushTheButton = this.flushTheButton + ' Updated';
40. })
41. }
42. .width('100%')
43. }
44. .height('100%')
45. }
46. }
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1/v3/ZjDfvSJCSr-WLZ5-qdnWyg/zh-cn_image_0000002599478295.gif?HW-CC-KV=V1&HW-CC-Date=20260511T034114Z&HW-CC-Expire=86400&HW-CC-Sign=85D5CB28DFA0425D8996EF2F7FAEC948F88B2100C6E5A85D0068612C4BF36507)

### attribute

PhonePC/2in1TabletTVWearable

get attribute(): T | undefined

获取AttributeUpdater中组件对应的属性类实例，通过该实例实现属性直通更新的功能。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**返回值：**

展开

| 类型 | 说明 |
| --- | --- |
| T | undefined | 如果AttributeUpdater中组件的属性类实例存在，则返回对应组件的属性类实例，否则返回undefined。 |

**示例：**

通过属性直通设置方式更新属性值。



```
1. // xxx.ets
2. import { AttributeUpdater } from '@kit.ArkUI';

4. class MyButtonModifier extends AttributeUpdater<ButtonAttribute> {
5. initializeModifier(instance: ButtonAttribute): void {
6. instance.backgroundColor('#ffd5d5d5')
7. .width('50%')
8. .height(30);
9. }
10. }

12. @Entry
13. @Component
14. struct updaterDemo2 {
15. modifier: MyButtonModifier = new MyButtonModifier();

17. build() {
18. Row() {
19. Column() {
20. Button("Button")
21. .attributeModifier(this.modifier)
22. .onClick(() => {
23. this.modifier.attribute?.backgroundColor('#ff2787d9').width('30%');
24. })
25. }
26. .width('100%')
27. }
28. .height('100%')
29. }
30. }
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/13/v3/1VlojJItR7-cNRIwAc-4mw/zh-cn_image_0000002568759106.gif?HW-CC-KV=V1&HW-CC-Date=20260511T034114Z&HW-CC-Expire=86400&HW-CC-Sign=6FF0297D57E76FA13AF6AF477781DA66E06E1F19FFBDF887956FE5A5202794F5)

### 属性

PhonePC/2in1TabletTVWearable

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

展开

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| updateConstructorParams | [C](/consumer/cn/doc/harmonyos-references/js-apis-arkui-attributeupdater#attributeupdatert-c--initializert) | 否 | 否 | C代表组件的构造函数类型，比如Text组件的TextInterface，Image组件的ImageInterface等。用于更改组件的构造函数入参。 |

**示例：**

使用updateConstructorParams更新组件的构造入参。



```
1. // xxx.ets
2. import { AttributeUpdater } from '@kit.ArkUI';

4. class MyTextModifier extends AttributeUpdater<TextAttribute, TextInterface> {
5. initializeModifier(instance: TextAttribute) {
6. }
7. }

9. @Entry
10. @Component
11. struct attributeDemo3 {
12. private modifier: MyTextModifier = new MyTextModifier();

14. build() {
15. Row() {
16. Column() {
17. Text("Initialize")
18. .attributeModifier(this.modifier)
19. .fontSize(14).border({ width: 1 }).textAlign(TextAlign.Center).lineHeight(20)
20. .width(200).height(50)
21. .backgroundColor('#fff7f7f7')
22. .onClick(() => {
23. this.modifier.updateConstructorParams("Updated");
24. })
25. }
26. .width('100%')
27. }
28. .height('100%')
29. }
30. }
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/84/v3/iX3B5ZuVTbmNd7FFiICC3Q/zh-cn_image_0000002599358349.gif?HW-CC-KV=V1&HW-CC-Date=20260511T034114Z&HW-CC-Expire=86400&HW-CC-Sign=38E281F4CB1C79880441E3A5AF4074AE19C49C83EAA84B4996E91895CDA45999)

### onComponentChanged

PhonePC/2in1TabletTVWearable

onComponentChanged(component: T): void

绑定相同的自定义的Modifier对象，组件发生切换时，通过该接口通知到应用。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

展开

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| component | T | 是 | 组件的属性类，用来标识进行属性设置的组件的类型，比如Button组件的ButtonAttribute，Text组件的TextAttribute等。 |

**示例：**



```
1. // xxx.ets
2. import { AttributeUpdater } from '@kit.ArkUI';

4. class MyButtonModifier extends AttributeUpdater<ButtonAttribute> {
5. initializeModifier(instance: ButtonAttribute): void {
6. instance.backgroundColor('#ff2787d9')
7. .width('50%')
8. .height(30);
9. }

11. onComponentChanged(instance: ButtonAttribute): void {
12. instance.backgroundColor('#ff519db4')
13. .width('50%')
14. .height(30);
15. }
16. }

18. @Entry
19. @Component
20. struct updaterDemo4 {
21. @State btnState: boolean = false;
22. modifier: MyButtonModifier = new MyButtonModifier();

24. build() {
25. Row() {
26. Column() {
27. Button("Test")
28. .onClick(() => {
29. this.btnState = !this.btnState;
30. }).margin({ bottom: 20 })

32. if (this.btnState) {
33. Button("Button")
34. .attributeModifier(this.modifier)
35. } else {
36. Button("Button")
37. .attributeModifier(this.modifier)
38. }
39. }
40. .width('100%')
41. }
42. .height('100%')
43. }
44. }
```

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/5b/v3/cemwA2NnSPmaALVG7YJU-Q/zh-cn_image_0000002568918754.gif?HW-CC-KV=V1&HW-CC-Date=20260511T034114Z&HW-CC-Expire=86400&HW-CC-Sign=313846DD2E240D8E9373CB7C9855764101C7C860E97D07BAE1EEDDA84DE76E76)