diff --git a/zh-cn/application-dev/reference/apis-arkui/Readme-CN.md b/zh-cn/application-dev/reference/apis-arkui/Readme-CN.md index 49d26a62ce2274b9f81c798736b86748172d38d9..fd2d4c918ff0527e347c47be77a277c84e078e9f 100644 --- a/zh-cn/application-dev/reference/apis-arkui/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis-arkui/Readme-CN.md @@ -38,6 +38,7 @@ - [NodeController](js-apis-arkui-nodeController.md) - [RenderNode](js-apis-arkui-renderNode.md) - [XComponentNode](js-apis-arkui-xcomponentNode.md) + - [AttributeUpdater](js-apis-arkui-AttributeUpdater.md) - 图形图像 - [@ohos.display (屏幕属性)](js-apis-display.md) - [@ohos.PiPWindow (画中画窗口)](js-apis-pipWindow.md) @@ -122,7 +123,6 @@ - [事件独占控制](arkui-ts/ts-universal-attributes-monopolize-events.md) - [鼠标光标控制](arkui-ts/ts-universal-attributes-cursor.md) - [特效绘制合并](arkui-ts/ts-universal-attributes-use-effect.md) - - [属性直通更新 (系统接口)](arkui-ts/ts-universal-attributes-attribute-updater-sys.md) - 手势处理 - [绑定手势方法](arkui-ts/ts-gesture-settings.md) - 基础手势 diff --git a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/figures/attribute-updater1.PNG b/zh-cn/application-dev/reference/apis-arkui/arkui-ts/figures/attribute-updater1.PNG deleted file mode 100644 index 572a83bd45b2039e30ffbde12427db63be8870b6..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/figures/attribute-updater1.PNG and /dev/null differ diff --git a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/figures/attribute-updater2.gif b/zh-cn/application-dev/reference/apis-arkui/arkui-ts/figures/attribute-updater2.gif deleted file mode 100644 index d8ee097d2e46cfde85aa54863d11fbaf371e7d0d..0000000000000000000000000000000000000000 Binary files a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/figures/attribute-updater2.gif and /dev/null differ diff --git a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-updater-sys.md b/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-updater-sys.md deleted file mode 100644 index 80b792541d40c851feba2098efd8707ff5bcd104..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-attribute-updater-sys.md +++ /dev/null @@ -1,126 +0,0 @@ -# 属性直通更新（系统接口） - -将属性直接设置给组件，无需标记为状态变量即可直接触发UI更新。 - -> **说明：** -> -> 从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 -> -> 当前页面仅包含本模块的系统接口，其他公开接口及支持范围参见[动态属性设置](ts-universal-attributes-attribute-modifier.md)。 - - - -## AttributeUpdater\ - -为[AttributeModifier](ts-universal-attributes-attribute-modifier.md#AttributeModifier)的实现类，开发者需要自定义class继承AttributeUpdater。 - -### initializeModifier -initializeModifier(instance: T): void - -AttributeUpdater首次设置给组件时提供的样式。 - - -**参数：** - -| 参数 | 描述 | -| -------------------- | ------------------------------------------------------------ | -| instance |组件的属性类，用来标识进行属性设置的组件的类型，比如Button组件的ButtonAttribute，Text组件的TextAttribute等。| - - -### attribute -get attribute(): T | undefined - -获取AttributeUpdater中组件对应的属性类实例，通过该实例实现属性直通更新的功能。 - -**返回值：** - -| 类型 | 描述 | -| -------------------- | ------------------------------------------------------------ | -| T \| undefined |如果AttributeUpdater中组件的属性类实例存在，则返回对应组件的属性类实例，否则返回undefined。| - -> **使用说明：** -> -> 1. 由于与属性方法同时设置或者在AttributeUpdater中实现applyNormalAttribute等方法时，涉及到与状态管理更新机制同时使用，易出现混淆，因此不建议在同一组件上同时用两种方法设置相同属性。 -> -> 2. 当与属性方法同时设置时，属性生效的原则为：后设置的生效。 -> 若先进行属性直通更新，后通过状态管理机制更新属性方法，则后更新的属性方法生效； -> 若先通过状态管理机制更新属性方法，后进行属性直通更新，则属性直通更新生效。 -> -> 3. 一个AttributeUpdater对象只能同时关联一个组件，否则将出现设置的属性只在一个组件上生效的现象。 -> - -## 示例 - -### 示例1 - -通过initializeModifier方法初始化设置属性值。 - -```ts -// xxx.ets -import { AttributeUpdater } from '@ohos.arkui.modifier' - -class MyButtonModifier extends AttributeUpdater { - initializeModifier(instance: ButtonAttribute): void { - instance.backgroundColor(Color.Red) - .width('50%') - .height(30) - } -} - -@Entry -@Component -struct updaterDemo1 { - modifier: MyButtonModifier = new MyButtonModifier() - - build() { - Row() { - Column() { - Button("Button") - .attributeModifier(this.modifier) - } - .width('100%') - } - .height('100%') - } -} -``` -![attributeUpdater1](figures/attribute-updater1.PNG) - - -### 示例2 - -通过属性直通设置方式更新属性值。 - -```ts -// xxx.ets -import { AttributeUpdater } from '@ohos.arkui.modifier' - -class MyButtonModifier extends AttributeUpdater { - initializeModifier(instance: ButtonAttribute): void { - instance.backgroundColor(Color.Red) - .width('50%') - .height(30) - } -} - -@Entry -@Component -struct updaterDemo2 { - modifier: MyButtonModifier = new MyButtonModifier() - - build() { - Row() { - Column() { - Button("Button") - .attributeModifier(this.modifier) - .onClick(() => { - this.modifier.attribute?.backgroundColor(Color.Green).width('30%') - }) - } - .width('100%') - } - .height('100%') - } -} -``` -![attributeUpdater2](figures/attribute-updater2.gif) diff --git a/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater1.PNG b/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater1.PNG new file mode 100644 index 0000000000000000000000000000000000000000..72ee0d911da4f0c65e195ef4eb7faadb3d7a1aeb Binary files /dev/null and b/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater1.PNG differ diff --git a/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater2.gif b/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater2.gif new file mode 100644 index 0000000000000000000000000000000000000000..989ace023995af514bcc799e81e3e068280be4e0 Binary files /dev/null and b/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater2.gif differ diff --git a/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater3.gif b/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater3.gif new file mode 100644 index 0000000000000000000000000000000000000000..63ded29b504dc455faacebe7ea07083db1950339 Binary files /dev/null and b/zh-cn/application-dev/reference/apis-arkui/figures/attribute-updater3.gif differ diff --git a/zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-AttributeUpdater.md b/zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-AttributeUpdater.md new file mode 100644 index 0000000000000000000000000000000000000000..67e9b6f5f22b7c9c5cb29828d69d77952b625ac5 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-AttributeUpdater.md @@ -0,0 +1,206 @@ +# AttributeUpdater + +将属性直接设置给组件，无需标记为状态变量即可直接触发UI更新。 + +> **说明：** +> +> 从API Version 12开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 +> + + +## 导入模块 + +```ts +import { AttributeUpdater } from '@ohos.arkui.modifier' +``` + +> **使用说明：** +> +> 1. 由于与属性方法同时设置或者在AttributeUpdater中实现applyNormalAttribute等方法时，涉及到与状态管理更新机制同时使用，易出现混淆，因此不建议在同一组件上同时用两种方法设置相同属性。 +> +> 2. 当与属性方法同时设置时，属性生效的原则为：后设置的生效。 +> 若先进行属性直通更新，后通过状态管理机制更新属性方法，则后更新的属性方法生效； +> 若先通过状态管理机制更新属性方法，后进行属性直通更新，则属性直通更新生效。 +> +> 3. 一个AttributeUpdater对象只能同时关联一个组件，否则将出现设置的属性只在一个组件上生效的现象。 +> +> 4. 开发者需要自行保障AttributeUpdater中T和C的类型匹配。比如T为ImageAttribute，C要对应为ImageInterface，否则可能导致 +> 使用updateConstructorParams时功能异常。 +> +> 5. updateConstructorParams当前只支持Image，Text和Span组件。 + +## Initializer +type Initializer\ = () => T + +可以将属性更新到本地的修饰器。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +## AttributeUpdater +AttributeUpdater> + +为[AttributeModifier](arkui-ts/ts-universal-attributes-attribute-modifier.md#AttributeModifier)的实现类，开发者需要自定义class继承AttributeUpdater。 + +其中C代表组件的构造函数类型，比如Text组件的TextInterface，Image组件的ImageInterface等，需要使用updateConstructorParams时才需要传递C类型。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +### applyNormalAttribute +applyNormalAttribute?(instance: T): void + +定义正常态更新属性函数。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------------------ | +| instance | T | 是 | 组件的属性类，用来标识进行属性设置的组件的类型，比如Button组件的ButtonAttribute，Text组件的TextAttribute等。| + +### initializeModifier +initializeModifier(instance: T): void + +AttributeUpdater首次设置给组件时提供的样式。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------------------ | +| instance | T | 是 | 组件的属性类，用来标识进行属性设置的组件的类型，比如Button组件的ButtonAttribute，Text组件的TextAttribute等。| + +**示例：** + +通过initializeModifier方法初始化设置属性值。 + +```ts +// xxx.ets +import { AttributeUpdater } from '@ohos.arkui.modifier' + +class MyButtonModifier extends AttributeUpdater { + initializeModifier(instance: ButtonAttribute): void { + instance.backgroundColor('#ff2787d9') + .width('50%') + .height(30) + } +} + +@Entry +@Component +struct updaterDemo1 { + modifier: MyButtonModifier = new MyButtonModifier() + + build() { + Row() { + Column() { + Button("Button") + .attributeModifier(this.modifier) + } + .width('100%') + } + .height('100%') + } +} +``` +![attributeUpdater1](figures/attribute-updater1.PNG) + + +### attribute +get attribute(): T | undefined + +获取AttributeUpdater中组件对应的属性类实例，通过该实例实现属性直通更新的功能。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +**返回值：** + +| 类型 | 描述 | +| -------------------- | ------------------------------------------------------------ | +| T \| undefined |如果AttributeUpdater中组件的属性类实例存在，则返回对应组件的属性类实例，否则返回undefined。| + +**示例：** + +通过属性直通设置方式更新属性值。 + +```ts +// xxx.ets +import { AttributeUpdater } from '@ohos.arkui.modifier' + +class MyButtonModifier extends AttributeUpdater { + initializeModifier(instance: ButtonAttribute): void { + instance.backgroundColor('#ffd5d5d5') + .width('50%') + .height(30) + } +} + +@Entry +@Component +struct updaterDemo2 { + modifier: MyButtonModifier = new MyButtonModifier() + + build() { + Row() { + Column() { + Button("Button") + .attributeModifier(this.modifier) + .onClick(() => { + this.modifier.attribute?.backgroundColor('#ff2787d9').width('30%') + }) + } + .width('100%') + } + .height('100%') + } +} +``` +![attributeUpdater2](figures/attribute-updater2.gif) + +### updateConstructorParams +updateConstructorParams: C + +用来更改组件的构造入参。C代表组件的构造函数类型。 + +其中C代表组件的构造函数类型，比如Text组件的TextInterface，Image组件的ImageInterface等。 + +**系统能力：** SystemCapability.ArkUI.ArkUI.Full + +**示例：** + +使用updateConstructorParams更新组件构造入参。 + +```ts +// xxx.ets +import { AttributeUpdater } from '@ohos.arkui.modifier' + +class MyTextModifier extends AttributeUpdater { + initializeModifier(instance: TextAttribute) { + } +} + +@Entry +@Component +struct attributeDemo3 { + private modifier: MyTextModifier = new MyTextModifier() + + build() { + Row() { + Column() { + Text("Initialize") + .attributeModifier(this.modifier) + .fontSize(14).border({ width: 1 }).textAlign(TextAlign.Center).lineHeight(20) + .width(200).height(50) + .backgroundColor('#fff7f7f7') + .onClick(() => { + this.modifier.updateConstructorParams("Updated") + }) + } + .width('100%') + } + .height('100%') + } +} +``` +![attributeUpdater3](figures/attribute-updater3.gif)