北墨NoLimitArkUI (方舟UI框架)
元服务
@Link 迁移到 @Param + @Event 后,双向同步失效
V1 中 @Link 是天然双向绑定,迁移到 V2 后发现 @Param 是只读的,必须手动加 @Event 回调通知父组件更新。代码量翻了一倍不说,嵌套组件层级深的时候,事件层层传递非常痛苦。有没有更优雅的方案?
MoonInk
这不是双向同步失效,而是 V2 的设计变化:@Param 只负责父→子传递,子组件必须调用 @Event,并由父组件修改同一个 @Local 数据源,之后新值才会再次传给子组件。注意不要加 @Once,否则只会初始化同步一次。
@ComponentV2
struct Child {
@Param value: number = 0;
@Event change: (value: number) => void;
build() {
Button(`${this.value}`)
.onClick(() => this.change(this.value + 1))
}
}
@Entry
@ComponentV2
struct Parent {
@Local value: number = 0;
build() {
Child({
value: this.value,
change: (value: number) => {
this.value = value;
}
})
}
}如果只是直接父子通信,建议继续使用 @Param + @Event;如果状态需要跨越多层组件,可在同一业务组件树内使用 @Provider/@Consumer,它支持跨层双向同步,能避免事件逐层透传。不过官方也提示该方案会增强组件耦合,不建议泛化成全局状态。
官方参考:
蓝瘦的蜕变
父子组件用 !! 简化绑定,深层组件用 @Provider/@Consumer,就不需要层层传事件了。
父子组件这样写:
// 父组件(@ComponentV2)
@Local count: number = 0;
// build 内
Child({ count: this.count!! })@ComponentV2
struct Child {
@Param count: number = 0;
@Event $count: (value: number) => void = () => {};
build() {
Button(`${this.count}`)
.onClick(() => this.$count(this.count + 1))
}
}@Event 必须命名为 $ + 参数名。!! 自动生成父组件的回写回调,但子组件仍通过 $count() 更新,不能直接 this.count++。
层级深时,祖先和后代分别声明:
// 祖先组件
@Provider('count') count: number = 0;
// 任意层级的后代组件
@Consumer('count') count: number = 0;后代可以直接 this.count++,会双向同步。
注意 key、类型一致;找不到对应 Provider 时,Consumer 使用自己的默认值。官方说明
不羁的木木这个场景 V2 有一个比较省代码的方案:用 !! 双向绑定语法糖。
V2 的 !! 就是专门用来简化 @Param + @Event 双向同步的。子组件仍然声明 @Param 和对应的 @Event,父组件传参时直接写 this.xxx!!,框架会自动生成对应的事件绑定。
例如:
@ComponentV2
struct Child {
@Param value: number = 0
@Event $value: (value: number) => void = () => {}
build() {
Button(`${this.value}`)
.onClick(() => {
this.$value(this.value + 1)
})
}
}父组件直接:
@Local value: number = 0
Child({
value: this.value!!
})等价于手动写:
Child({
value: this.value,
$value: (value: number) => {
this.value = value
}
})所以从 V1 @Link 迁移时,可以优先考虑 @Param + @Event + !!,调用侧基本恢复成类似双向绑定的写法。
不过有一个限制需要注意:!! 不支持多层父子组件传递。嵌套组件很多时,V2 更适合用 @Provider + @Consumer 做跨层级双向同步,这样就不用每一层都定义 @Param + @Event 再往上传。官方目前也把 @Provider/@Consumer 定位为跨组件层级双向同步方案。
简单选型:
- 直接父子组件:
@Param + @Event + !! - 多层组件共享状态:
@Provider + @Consumer - 复杂对象属性同步:
@ObservedV2 + @Trace,很多情况下也不需要额外的@Event。
所以没必要把 V1 的 @Link 全部机械改成一堆手写回调,V2 本身提供了对应的简化机制。
慢行
- 如果是简单类型@Link -> @Param/@Event 虽然写法复杂,但是符合状态影响最小范围,效率最高的选择。语法糖!!可以代替函数传递的写法,但不建议用。
· !!双向绑定语法不支持多层父子组件传递。
· 不支持与@Event混用。从API version 18开始,当使用!!双向绑定语法给子组件传递参数时,给对应的@Event方法传参会编译报错。
· 当使用3个或更多感叹号(!!!、!!!!、!!!!!等)时,不支持双向绑定功能。误写难找错。 - 如果是对象类型,
@ObservedV2装饰的对象,且子组件只需修改对象的某个@Trace属性时,修改会自动触发关联组件刷新,不用@Event。收起自动换行深色代码主题复制@ObservedV2 class User { @Trace boy: boolean = false; @Trace name: string = ''; } @ComponentV2 struct TaskItem { @Param user: User = new User(); // 接收对象引用 build() { Row() { Text(this.user.name) Toggle({ type: ToggleType.Checkbox, isOn: this.user.boy }) .onChange((isOn: boolean) => { // 直接修改 @Trace 属性,自动触发父子组件关联 UI 刷新 // 无需 @Event 回调 this.user.boy = isOn; }) } } } - 至于@Provider和@Consumer,只建议复杂的多层或深层同步使用。它俩是全局广播,消耗大。
小草飞上天开发者你好:
针对直接父子组件间的双向绑定,V2 提供了 !! 语法糖,它能自动完成 @Param 和 @Event 的绑定,是替代 @Link 最直接的方式。
// 父组件
@Entry
@ComponentV2
struct Parent {
@Local value: number = 0;
build() {
Column() {
// 使用 !! 语法糖
Child({ value: this.value!! })
}
}
}
// 子组件
@ComponentV2
struct Child {
@Param value: number = 0;
// 命名必须是 $ + 属性名
@Event $value: (val: number) => void = () => {};
build() {
Button('子组件 +1')
.onClick(() => {
this.$value(this.value + 1); // 通过 $value 回调更新
})
}
}
6Jerries

@Link 迁到 @Param + @Event 后怎么少写代码:三种方案实测对比(附真机验证)
原问题链接:查看原帖
验证设备:HUAWEI Mate 80 Pro Max,HarmonyOS 7.0
@Param 只读、@Event 手动回传这套确实比 V1 的 @Link 啰嗦,但 V2 里有三个更省事的写法,按场景选就行,不用每次都手写回调。
方案一:!! 语法糖,代码量和 @Link 基本持平
!! 是 V2 的双向绑定语法糖,API 12 起支持。规则是子组件的 @Event 方法名必须叫 $ + @Param 属性名,父组件传参时在变量后面加 !!:
@ComponentV2
struct ChildComp {
@Param value: number = 0;
// 命名必须是 $ + @Param 属性名
@Event $value: (val: number) => void = (val: number) => {};
build() {
Row({ space: 8 }) {
Text(`子组件 value=${this.value}`)
Button('子组件+1')
.onClick(() => {
this.$value(this.value + 1);
})
}
}
}
@Entry
@ComponentV2
struct Index {
@Local value: number = 0;
build() {
Column() {
Text(`父组件 value=${this.value}`)
// !! 等价于 { value: this.value, $value: (v) => this.value = v }
ChildComp({ value: this.value!! })
}
}
}ChildComp({ value: this.value!! }) 这一行等价于手动写 { value: this.value, $value: (v: number) => { this.value = v } },样板代码全省了。限制是只支持直接父子之间,不能穿透多层。
方案二:@Provider + @Consumer,解决层级深的问题
层级深的时候事件层层传递确实难受,这个场景官方给的方案就是 @Provider/@Consumer(API 12+):祖先组件 @Provider 提供数据,任意深度的后代 @Consumer 直接消费,中间层一个参数都不用传,而且天然双向:
@ComponentV2
struct DeepChild {
@Consumer('deepCount') count: number = 0;
build() {
Button('深层+1')
.onClick(() => {
this.count++; // 直接改,自动同步回 @Provider
})
}
}
@ComponentV2
struct MiddleLayer {
build() {
DeepChild() // 中间层完全不需要感知这个数据
}
}
@Entry
@ComponentV2
struct Index {
@Provider('deepCount') count: number = 0;
build() {
MiddleLayer()
}
}@Consumer 找不到匹配的 @Provider 时会用自己的初始值兜底。V2 里 @Provider 默认支持重载,@Consumer 向上找最近的一个,也不用像 V1 @Provide 那样配 allowOverride。
方案三:传对象时用 @ObservedV2 + @Trace
如果传的是对象,父子共享同一个引用,子组件直接改属性就行,连 @Event 都不用:
@ObservedV2
class FormData {
@Trace username: string = '';
@Trace age: number = 0;
}
@ComponentV2
struct FormItem {
@Param data: FormData = new FormData();
build() {
Button('子组件改age+1')
.onClick(() => {
this.data.age++; // 直接改 @Trace 属性,父组件自动刷新
})
}
}@Trace 是属性级监听,只有用到这个属性的 UI 节点会刷新,比 V1 @Observed + @ObjectLink 粒度更细。
真机验证结果
三种写法我在 Mate 80 Pro Max 上都跑了,子组件侧点按钮父组件数字同步变,父组件侧点按钮子组件跟着变,双向都通:
- !!:子组件 +1 后父组件 value 从 0 变 1;父组件 +1 后子组件显示 2。
- @Provider/@Consumer:深层子组件 +1 后根组件 count 变 1;根组件 +1 后深层显示 2,中间层没有传任何参数。
- @Trace:子组件改 data.age 后父组件显示 19;父组件改后子组件显示 29。
截图见下方,图 1 是子组件侧触发后的同步结果,图 2 是父组件侧触发后的结果。
选型建议
直接父子传简单类型,用 !!,最省代码。嵌套深、要跨多层共享,用 @Provider + @Consumer。传的是对象模型、子组件要改内部属性,用 @ObservedV2 + @Trace。复杂场景可以叠加,@Provider 提供一个 @ObservedV2 对象,深层 @Consumer 拿到后直接改 @Trace 属性,两层问题一起解掉。
参考文档
真机验证截图
飞b6有。V2 迁移时如果把所有 @Link 都机械改成:
@Param value
+
@Event onValueChange深层组件确实很容易变成“事件打洞”。更合理的做法是根据状态的所有权选择 @Event、@Once、@ObservedV2/@Trace 或 @Provider/@Consumer,而不是所有场景都使用回调。
1. 普通父子组件:@Param + @Event 仍然是首选
例如 V1:
@Component
struct Child {
@Link count: number
}V2:
@ComponentV2
struct Child {
@Param count: number = 0
@Event onCountChange: (value: number) => void = () => {}
build() {
Button(`${this.count}`)
.onClick(() => {
this.onCountChange(this.count + 1)
})
}
}父组件:
@ComponentV2
struct Parent {
@Local count: number = 0
build() {
Child({
count: this.count,
onCountChange: (value: number) => {
this.count = value
}
})
}
}它看起来比 @Link 啰嗦,但好处是数据流非常明确:
Parent
│
│ @Param
▼
Child
│
│ @Event
▼
Parent 修改真正状态尤其通用组件,比如 NumberStepper、筛选器、输入组件,这种模式最合适。
2. 如果只是想保留 V1 @Link 风格,可以关注 @Param + @Once
但要注意,@Once 解决的主要是参数初始化/更新策略,并不是把 @Param 重新变成真正的双向绑定。
所以不要把:
@Param + @Once理解成:
V2版 @Link它们语义不一样。
3. 深层组件不要层层透传 Event
比如:
Page
↓
Container
↓
Panel
↓
Form
↓
NumberInput真正拥有状态的是 Page,最下面 NumberInput 修改值。
如果写成:
NumberInput
→ onChange
Form
→ onChange
Panel
→ onChange
Container
→ onChange
Page
→ 修改状态这种确实没必要。
如果这几个组件属于同一个业务域,更适合共享一个 @ObservedV2 状态对象。
例如:
@ObservedV2
class EditorState {
@Trace fontSize: number = 16
@Trace lineHeight: number = 1.5
@Trace bold: boolean = false
}父层创建:
@ComponentV2
struct EditorPage {
@Local state: EditorState = new EditorState()
build() {
EditorPanel({
state: this.state
})
}
}中间:
@ComponentV2
struct EditorPanel {
@Param state: EditorState
build() {
Toolbar({
state: this.state
})
}
}底层:
@ComponentV2
struct Toolbar {
@Param state: EditorState
build() {
Button('+')
.onClick(() => {
this.state.fontSize++
})
Text(`${this.state.fontSize}`)
}
}这里虽然:
@Param state本身不能:
this.state = new EditorState()但 state 指向的是一个:
@ObservedV2对象,其中:
@Trace fontSize本身具有响应式能力。
因此修改:
this.state.fontSize++可以通知依赖该字段的 UI。
这就解决了很多:
@Link
↓
@Param + @Event
↓
事件层层上传的问题。
4. 层级非常深时,用 @Provider/@Consumer
如果结构已经变成:
EditorPage
↓
Layout
↓
SideBar
↓
PropertyPanel
↓
FontPanel
↓
NumberStepper中间 5 层其实完全不关心 EditorState。
那就不应该:
Page
→ state
→ Layout
→ state
→ SideBar
→ state
→ PropertyPanel
→ state
→ ...这种叫典型的 prop drilling。
V2 更适合:
上层
@Provider
↓ 跨层提供
深层
@Consumer概念上:
EditorPage
@Provider EditorState
│
│
├──── Layout
│ └──── SideBar
│ └──── Panel
│
└──────────────────────→ @Consumer
NumberStepper这样中间组件完全不需要知道这个状态。
对于:
主题
编辑器上下文
表单上下文
当前文档
播放器 Session
窗口级 UI 状态这种“一个组件子树共享”的状态,Provider/Consumer 通常比 Event 一层层传漂亮得多。
5. 更复杂业务:传 Store,不要传几十个字段
例如原来 V1:
@Link title
@Link content
@Link fontSize
@Link lineHeight
@Link color
@Link alignment迁 V2 后如果全部变:
@Param title
@Event onTitleChange
@Param content
@Event onContentChange
@Param fontSize
@Event onFontSizeChange
...代码当然会爆炸。
更适合聚合:
@ObservedV2
class DocumentEditorStore {
@Trace title: string = ''
@Trace content: string = ''
@Trace fontSize: number = 16
@Trace lineHeight: number = 1.5
@Trace color: string = '#000000'
setFontSize(value: number): void {
this.fontSize = value
}
}然后整个编辑器子树围绕:
DocumentEditorStore工作。
这实际上就是:
把双向绑定升级成“共享可观察业务状态”。
6. 但不要因此把所有东西都做成全局 Store
这是另一个极端。
例如一个通用组件:
Switch
Slider
NumberStepper
DatePicker不应该直接:
@Consumer globalStore然后偷偷改全局状态。
这种组件仍然应该:
@Param value
@Event onChange这样才能真正复用。
可以按这个原则选:
| 场景 | V2 推荐 |
|---|---|
| 普通父 → 子 | @Param |
| 子 → 父修改 | @Event |
| 通用表单控件 | @Param + @Event |
| 嵌套业务对象 | @ObservedV2 + @Trace |
| 同一业务子树共享状态 | Store |
| 跨很多层级 | @Provider + @Consumer |
| 应用级状态 | AppStorageV2 / Store |
| 窗口级状态 | Window Store,不要全局化 |
一个很实用的判断方法
问一句:
“这个状态到底是谁的?”
如果答案是:
父组件的。
就:
@Param + @Event如果答案是:
整个 Editor 模块共同拥有。
就:
@ObservedV2 Store如果答案是:
整棵组件子树都需要,但中间组件不关心。
就:
@Provider / @Consumer如果答案是:
整个应用都需要。
才考虑:
AppStorageV2所以 V2 并不是要求把:
@Link全部机械翻译成:
@Param + @Event真正的迁移思路应该是:
V1
大量双向绑定
↓
V2
明确状态所有权
↓
┌─────┼──────────────┐
↓ ↓ ↓
Param ObservedV2 Provider
Event Store Consumer浅层通用组件用 @Param + @Event;深层业务状态用 @ObservedV2 + @Trace 聚合成 Store;跨很多层再用 @Provider/@Consumer 消除事件透传。
这样迁完代码量未必比 V1 多,复杂页面反而会比到处 @Link 更容易维护。
橙动创意直接父子组件可以用 V2 的 !! 双向绑定语法糖,省掉手写事件传参;子组件的事件名必须是 $ 加参数名:
@ComponentV2
struct Child {
@Param value: number = 0;
@Event $value: (value: number) => void = () => {};
build() {
Button(`${this.value}`).onClick(() => this.$value(this.value + 1))
}
}
@Local count: number = 0;
Child({ value: this.count!! })跨很多层不要继续逐层透传,改用 @Provider/@Consumer;对象内部属性共享则用 @ObservedV2 + @Trace。
心系天下@ComponentV2
struct Child {
@Param value: number = 0
@Event $value: (v: number) => void = (v: number) => {}
build() {
Button(`${this.value}`)
.onClick(() => this.$value(this.value + 1))
}
}
Child({ value: this.value!! })
Child({
value: this.value,
$value: (v: number) => { this.value = v }
})
})
@Provider('count')
count: number = 0@Consumer('count')
count: number = 0
build() {
Button(`${this.count}`)
.onClick(() => this.count++)
}
星桥似海V2 里 @Param 只读是刻意的设计(数据流必须显式单向),但针对“代码膨胀”和“深层传递”两个痛点,官方给了三把武器,按场景选,不必全改成手写 @Event:
1. 直接父子:!! 语法糖(一行替代 @Link)
@Event 命名必须是 $ + @Param 名,父组件传参末尾加 !! 即可自动回写:
@ComponentV2
struct Child {
@Param value: number = 0;
@Event $value: (v: number) => void = (v: number) => {};
build() {
Button(`${this.value}`).onClick(() => this.$value(this.value + 1))
}
}
@Entry @ComponentV2
struct Parent {
@Local value: number = 10;
build() { Child({ value: this.value!! }) } // 等价于手写 $value 回调
}注意:!! 仅支持直接父子,不支持多层透传。
2. 深层嵌套:@Provider + @Consumer(跳过中间层)
@ObservedV2
class Counter { @Trace count: number = 0; }
@Entry @ComponentV2
struct Root {
@Provider('counter') counter: Counter = new Counter();
build() { Column(){ Text(`${this.counter.count}`); Middle() } }
}
@ComponentV2
struct Middle { build() { Child() } } // 中间层完全不用碰数据
@ComponentV2
struct Child {
@Consumer('counter') counter: Counter = new Counter();
build() { Button('+1').onClick(() => this.counter.count++) } // 直接改,自动回写 Provider
}3. 对象属性级:@ObservedV2 + @Trace
传对象引用时,子组件改 @Trace 属性自动同步,无需 @Event:
@ObservedV2 class FormData { @Trace name: string = ''; @Trace age: number = 0; }
@ComponentV2 struct Field {
@Param data: FormData = new FormData();
build() { Button('改名').onClick(() => this.data.name = '张三') } // 父子自动刷新
}选型:简单父子用 !!;跨层级用 @Provider/@Consumer;对象属性修改用 @ObservedV2+@Trace;全局用 AppStorageV2。三者在同一个 V2 项目里可组合使用。
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS 父子组件,想要实现数据同步,@Link需要如何使用?(API12+)
HarmonyOS @Link没传为什么不会在编译期报错 (API12+)
HarmonyOS $$符号对于@Link @Objectlink 不同装饰器之间的区别 (API12+)
HarmonyOS 原来arm的neon汇编代码,迁移到HarmonyOS后还能使用吗? (API12+)
HarmonyOS ComponentV2组件使用V1组件,V1组件中有个@Link变量,会编译报错?(API12+)
HarmonyOS ComponentV2中有一个子组件属性是@Component,同时存在@Link属性 (API12+)
HarmonyOS Repeat与@Builder混合使用时,无法使用Builder代理直接完成代码适配 (API12+)
HarmonyOS Builder引用组件内部的State不会响应自动更新UI,也无法改变组件的State(API12+)




































苏公安网备 32011402010933号