Harmonyos-属性修改器和更新器

概述

ArkUI框架提供一系列基于Modifier的自定义扩展能力，通过与UI分离的方式，对已有UI组件的属性、手势、内容进行扩展修改，以满足开发者在不改变UI组件底层实现的情况下，快速调整UI组件外观、行为等需求。

属性修改器 (AttributeModifier)

概述

声明式语法引入了@Styles和@Extend两个装饰器，可以解决复用相同自定义样式的问题，但是存在以下受限场景：

• @Styles和@Extend均是编译期处理，不支持跨文件的导出复用。
• @Styles仅能支持通用属性、事件，不支持组件特有的属性。
• @Styles虽然支持在多态样式下使用，但不支持传参，无法对外开放一些属性。
• @Extend虽然能支持特定组件的私有属性、事件，但同样不支持跨文件导出复用。
• @Styles、@Extend对于属性设置，无法支持业务逻辑编写，动态决定是否设置某些属性，只能通过三元表达式对所有可能设置的属性进行全量设置，设置大量属性时效率较低。

为了解决上述问题，ArkUI引入了AttributeModifier机制，可以通过Modifier对象动态修改属性。能力对比如下：

可以看出，与@Styles和@Extend相比，AttributeModifier提供了更强的能力和灵活性，且在持续完善全量的属性和事件设置能力，因此推荐优先使用AttributeModifier。

接口定义

declare interface AttributeModifier<T> {applyNormalAttribute?(instance: T): void;applyPressedAttribute?(instance: T): void;applyFocusedAttribute?(instance: T): void;applyDisabledAttribute?(instance: T): void;applySelectedAttribute?(instance: T): void;}

AttributeModifer是一个接口，开发者需要实现其中applyXxxAttribute方法， 来实现对应场景的属性设置。

Xxx表示多态的场景，支持默认态（Normal）、按压态（Pressed）、焦点态（Focused）、禁用态（Disabled）、选择态（Selected）。T是组件的属性类型，开发者可以在回调中获取到属性对象，通过该对象设置属性

declare class CommonMethod<T> {attributeModifier(modifier: AttributeModifier<T>): T;
}

组件的通用方法增加了attributeModifier方法，支持传入自定义的Modifier。由于组件在实例化时会明确T的类型，所以调用该方法时，T必须指定为组件对应的Attribute类型，或者是CommonAttribute。

使用说明

• 组件通用方法attributeModifier支持传入一个实现AttributeModifier接口的实例，T必须指定为组件对应的Attribute类型，或者是CommonAttribute。
• 在组件首次初始化或者关联的状态变量发生变化时，如果传入的实例实现了对应接口，会触发applyNormalAttribute。
• 回调applyNormalAttribute时，会传入组件属性对象，通过该对象可以设置当前组件的属性/事件。
• 暂未支持的属性/事件，执行时会抛异常。
• 属性变化触发applyXxxAttribute函数时，该组件之前已设置的属性，在本次变化后未设置的属性会恢复为属性的默认值。
• 可以通过该接口使用多态样式的功能，例如如果需要在组件进入按压态时设置某些属性，就可以通过自定义实现applyPressedAttribute方法完成。
• 一个组件上同时使用属性方法和applyNormalAttribute设置相同的属性，遵循属性覆盖原则，即后设置的属性生效。
• 一个Modifier实例对象可以在多个组件上使用。
• 一个组件上多次使用applyNormalAttribute设置不同的Modifier实例，每次状态变量刷新均会按顺序执行这些实例的方法属性设置，同样遵循属性覆盖原则。

设置和修改组件属性

AttributeModifier可以分离UI与样式，支持参数传递及业务逻辑编写，并且通过状态变量触发刷新。

下面以Text组件的一些属性为示例：

SkinManager.ets的代码：

@Observed
export class SkinManager {// 是否黑板isDrak: boolean = false// 是否使用大字体isLargeFont: boolean = false
}

SkinTextAttributeModifier.ets代码：

import { SkinManager } from "./SkinManage";export class SkinTextAttributeModifier implements AttributeModifier<TextAttribute> {private skinManger: SkinManagerprivate _fontSize?: number = 20private _fontColor?: ResourceColor = Color.Blackprivate _backgroundColor?: ResourceColor = Color.Orangeconstructor(skinManage: SkinManager) {this.skinManger = skinManage}fontSize(fontSize?: number): SkinTextAttributeModifier {this._fontSize = fontSizereturn this}fontColor(fontColor?: ResourceColor): SkinTextAttributeModifier {this._fontColor = fontColorreturn this}backgroundColor(backgroundColor?: ResourceColor): SkinTextAttributeModifier {this._backgroundColor = backgroundColorreturn this}applyNormalAttribute(instance: TextAttribute): void {// 这里可以进项皮肤的更换逻辑， 示例中是一个简单的例子if (this._fontColor) {// 这里传参应该传递现在的设置颜色， 然后或去对应皮肤的对应的颜色instance.fontColor(this.getColor(this.skinManger.isDrak))}if (this._fontSize) {// 这里传参应该传递现在设置的字体大小， 然后或去计算对应字体大小在重新设置instance.fontSize(this.getSize(this.skinManger.isLargeFont))}if (this._backgroundColor) {instance.backgroundColor(this._backgroundColor)}}getColor(isDark: boolean) {return isDark ? Color.White : Color.Black}getSize(isLarge: boolean) {return isLarge ? 40 : 20}
}

demo示例代码：

import { SkinManager } from './SkinManage';
import { SkinTextAttributeModifier } from './SkinTextAttributeModifier';@Entry
@Component
struct Index {@State message: string = 'Hello World';@State skinManager: SkinManager = new SkinManager()build() {Column() {Text(this.message).fontWeight(FontWeight.Bold)// 通过属性修改器来设置属性.attributeModifier(new SkinTextAttributeModifier(this.skinManager).fontSize(20).fontColor(Color.White).backgroundColor(Color.Gray))Button("换肤").onClick((event: ClickEvent) => {this.skinManager.isDrak = !this.skinManager.isDrak})Button("更改字体大小").onClick((event: ClickEvent) => {this.skinManager.isLargeFont = !this.skinManager.isLargeFont})}.height('100%').width('100%')}
}

上述例子只是介绍了下使用applyNormalAttribute方法， 如果你想设置更多状态的UI变化，你可以实现其他的接口。

属性更新器（AttributeModifier）

概述

在大量频繁更新的场景下，使用状态变量可能会导致前端状态管理的计算量过大，并且需要对单个组件进行全量属性更新。尽管可以通过AttributeModifier机制实现按需更新属性，但前端仍会采用一定的diff和reset策略，这可能带来性能问题。

AttributeUpdater作为一个特殊的AttributeModifier，不仅继承了AttributeModifier的功能，还提供了直接获取属性对象的能力。通过属性对象，开发者能够直接更新对应属性，无需经过状态变量。开发者可以利用AttributeUpdater实现自定义的更新策略，从而进一步提升属性更新的性能。

由于AttributeUpdater提供了较高的灵活性，无法限制“单一数据源”的规则，因此在与状态变量同时更新同一属性时，存在相互覆盖的情况。这要求开发者必须确保属性设置的合理性。

接口定义

export declare class AttributeUpdater<T, C = Initializer<T>> implements AttributeModifier<T> {applyNormalAttribute?(instance: T): void;initializeModifier(instance: T): void;get attribute(): T | undefined;updateConstructorParams: C;
}

AttributeUpdater实现了AttributeModifier接口，并额外提供了initializeModifier，可以对组件的属性进行初始化。通过attribute属性方法可以获取属性对象，直接更新对应组件的属性。另外也可以直接通过updateConstructorParams更新组件的构造参数。

使用说明

• 开发者可以继承AttributeUpdater<T>类，并通过组件的通用方法attributeModifier设置，首次绑定时会触发initializeModifier方法，进行属性的初始化，后续其它的生命周期和AttributeModifier保持一致。
• 组件初始化完成之后，开发者可以通过AttributeUpdater实例的attribute属性方法，获取到属性对象，若获取不到则为undefined。
• 通过attribute属性对象直接修改属性，会将最新设置的属性记录在当前对象中，并立即触发组件属性的更新。
• 如果将AttributeUpdater实例标记为状态变量进行修改，或者通过其它状态变量更新对应组件的属性，会触发applyNormalAttribute的流程，如果开发者没有复写该逻辑，默认会将属性对象记录的所有属性，进行一次批量更新。
• 如果开发者复写applyNormalAttribute的逻辑，并且不调用super的该方法，将会失去获取attribute属性对象的能力，不会调用initializeModifier方法。
• 一个AttributeUpdater对象只能同时关联一个组件，否则只会有一个组件的属性设置生效。

通过modifier直接修改属性和更新构造参数

组件初始化完成之后，开发者可以通过AttributeUpdater实例的attribute属性方法，获取到属性对象。通过属性对象直接修改属性，会立即触发组件属性的更新

SkinButtonModifier.ets:

import { AttributeUpdater } from "@kit.ArkUI";export class SkinButtonModifier extends AttributeUpdater<ButtonAttribute, ButtonInterface> {// 首次绑定时触发initializeModifier方法，进行属性初始化initializeModifier(instance: ButtonAttribute): void {instance.backgroundColor(Color.Orange).width('50%').height(30)}
}

示例代码：

import { SkinButtonModifier } from './SkinButtonModifier';@Entry
@Component
struct Index {// 创建一个update修改器private modifier: SkinButtonModifier = new SkinButtonModifier()build() {Column() {Button('test attributeModifier').attributeModifier(this.modifier).onClick((event: ClickEvent) => {// 通过attribute，直接修改组件属性，并立即触发组件属性更新this.modifier.attribute?.backgroundColor(Color.Red).width('80%').height(44)// 调用updateConstructorParams方法，直接更新组件的构造参数this.modifier.updateConstructorParams('update Title')})}.height('100%').width('100%')}
}

修改前效果：

点击修改后的效果：

参考资料

官方文档：自定义扩展