文档开发者中心
我的
|

ArkUI (方舟UI框架)

元服务

@Link 迁移到 @Param + @Event 后,双向同步失效

已解决

V1 中 @Link 是天然双向绑定,迁移到 V2 后发现 @Param 是只读的,必须手动加 @Event 回调通知父组件更新。代码量翻了一倍不说,嵌套组件层级深的时候,事件层层传递非常痛苦。有没有更优雅的方案?

点赞
1
收藏
回复
18
分享
举报
浏览135 发布于2026-09-15 05:49湖南
全部评论
最多点赞
最新发布
最早发布
|
采纳答复

这不是双向同步失效,而是 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,它支持跨层双向同步,能避免事件逐层透传。不过官方也提示该方案会增强组件耦合,不建议泛化成全局状态。

官方参考:

展开全部
18楼回复于2026-09-17 03:37 来自湖南

父子组件用 !! 简化绑定,深层组件用 @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 使用自己的默认值。官方说明

展开全部
4楼回复于2026-09-15 06:25 来自广东

这个场景 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 本身提供了对应的简化机制。

展开全部
11楼回复于2026-09-15 08:37 来自辽宁
父子双向同步,V1到V2迁移。
  1. 如果是简单类型@Link -> @Param/@Event 虽然写法复杂,但是符合状态影响最小范围,效率最高的选择。语法糖!!可以代替函数传递的写法,但不建议用。
    ·  !!双向绑定语法不支持多层父子组件传递。
    ·  不支持与@Event混用。从API version 18开始,当使用!!双向绑定语法给子组件传递参数时,给对应的@Event方法传参会编译报错。
    ·  当使用3个或更多感叹号(!!!、!!!!、!!!!!等)时,不支持双向绑定功能。误写难找错。
  2. 如果是对象类型,@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;
            })
        }
      }
    }
    
  3. 至于@Provider和@Consumer,只建议复杂的多层或深层同步使用。它俩是全局广播,消耗大。
展开全部
9楼编辑于2026-09-15 08:27 来自北京

开发者你好:

针对直接父子组件间的双向绑定,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 回调更新
      })
  }
}
19楼回复于2026-09-18 09:15 来自北京

@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 属性,两层问题一起解掉。

参考文档

真机验证截图

展开全部
17楼回复于2026-09-16 10:10 来自广东

有。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 更容易维护。

展开全部
15楼回复于2026-09-15 15:31 来自陕西

直接父子组件可以用 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。

 

14楼回复于2026-09-15 13:47 来自四川
方案有两个,且都能显著减少代码量:
一、直接父子组件:用 !!,一行恢复成类似 @Link 的写法
V2 的 !! 是专门用来简化 @Param + @Event 双向同步的语法糖。
你只需要:
子组件仍然写:
收起
自动换行
深色代码主题
复制
@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 / @Consumer,彻底消灭事件层层传递
官方原文:  
深层组件用 @Provider/@Consumer,就不需要层层传事件了。
祖先组件:
收起
自动换行
深色代码主题
复制
@Provider('count')
count: number = 0
任意层级的后代组件:
收起
自动换行
深色代码主题
复制
@Consumer('count')
count: number = 0

build() {
  Button(`${this.count}`)
      .onClick(() => this.count++)
      }

中间层完全不用写任何 @Param 或 @Event。
你直接在后代组件里 this.count++,会自动同步到最近的 Provider。
这就是跨层级双向同步方案。
1. 父子组件:用 !!,一行替代 @Param + @Event,写法最接近 V1 的 @Link。  
2. 深层嵌套:用 @Provider / @Consumer,彻底避免事件层层传递。
这两种是、能显著减少代码量的唯一优雅方案。你不需要继续机械地写大量 @Event。
展开全部
13楼回复于2026-09-15 09:16 来自陕西

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 项目里可组合使用。

展开全部
12楼回复于2026-09-15 08:39 来自北京
共2页
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。