鸿蒙应用开发之双向绑定实战：从 V1 到 V2 的完整迁移指南

这是一个使用鸿蒙技术开发的本地原生记账应用，非常适合大家用来练手。相关源码已上传至 Github，点击此处查看项目。欢迎大家交流、指正，也欢迎提交 PR。

在 ArkTS 状态管理中，V1 和 V2 对双向绑定的实现方式有显著差异。本文将深入剖析这两种方案的核心区别，并通过完整的代码示例，带你掌握从 V1 到 V2 的迁移技巧。

一、什么是双向绑定

双向绑定是一种数据同步机制，它让数据模型 与UI 视图之间建立自动的双向关联：当数据发生变化时，视图会自动更新；当用户在视图中操作（如输入文本、切换开关）时，数据也会自动同步。

在 ArkTS 中，双向绑定主要解决以下痛点：

• 减少样板代码：无需手动监听输入事件、手动更新状态变量，框架自动完成同步。
• 提升开发效率：开发者只需关注数据本身，UI 的刷新由框架接管。
• 降低出错概率：避免因忘记手动同步导致的数据与视图不一致问题。

二、核心概念对比

在开始编码之前，我们先快速了解 V1 和 V2 在双向绑定上的核心差异：

场景	V1 方案	V2 方案
内置组件双向绑定	$$ 运算符	!! 语法糖
自定义组件双向绑定	@Link 装饰器	@Param + @Event 组合
数据流向	框架自动双向同步	单向数据流 + 事件驱动

V2 的 @Param + @Event 方案将数据传递和事件回调显式分离，使数据流向更清晰，避免了 @Link 隐式同步带来的维护困难，同时支持更细粒度的状态控制。

三、内置组件双向绑定

3.1 V1 实现（使用 $$）

在 V1 中，$$ 运算符用于将 @State 装饰的变量与系统内置组件（如 TextInput）进行双向绑定。当用户在输入框中输入内容时，text 变量会自动更新，同时 Text 组件也会实时显示最新值。

@Entry
@Component
struct TextInputExample {
  @State text: string = '';

  build() {
    Column({ space: 20 }) {
      Text(this.text).fontSize(20)
      TextInput({ text: $$this.text, placeholder: 'input your word...' })
        .width(300)
        .fontSize(20)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

3.2 V2 实现（使用 !!）

@Entry
@ComponentV2
struct TextInputExampleV2 {
  @Local text: string = '';

  build() {
    Column({ space: 20 }) {
      Text(this.text)
      .fontSize(20)
      TextInput({ text: this.text!!, placeholder: 'input your word...' })
        .width(300)
        .fontSize(20)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

迁移要点 ：V1 的 $$ 直接替换为 V2 的 !!，同时组件装饰器从 @Component 改为 @ComponentV2，状态装饰器从 @State 改为 @Local。

四、自定义组件双向绑定

4.1 V1 实现（使用 @Link）

在 V1 中，父组件通过 @State 定义状态，子组件通过 @Link 建立双向绑定。子组件内部对 val 的修改会直接同步到父组件的 myVal。

const INITIAL_MYVAL = 10;

@Component
struct Child {
  @Link val: number;

  build() {
    Column() {
      Text('child: ' + this.val.toString())
      Button('+1').onClick(() => {
        this.val++;
      })
    }
  }
}

@Entry
@Component
struct Parent {
  @State myVal: number = INITIAL_MYVAL;

  build() {
    Column() {
      Text('parent: ' + this.myVal.toString())
      Child({ val: this.myVal })
    }
  }
}

运行效果：

4.2 V2 实现（使用 @Param + @Event）

在 V2 中，@Link 被拆分为 @Param（接收数据）和 @Event（回调事件）。子组件不再直接修改父组件的数据，而是通过调用 @Event 回调来通知父组件更新。

const INITIAL_MYVAL = 10;

@ComponentV2
struct Child {
  @Param val: number = 0;
  @Event addOne: () => void;

  build() {
    Column({space: 20}) {
      Text('child: ' + this.val.toString())
        .fontSize(20)
      Button('+1').onClick(() => {
        this.addOne()
      })
        .width("50%")
    }
    .width("100%")
  }
}

@Entry
@ComponentV2
struct Parent {
  @Local myVal: number = INITIAL_MYVAL;

  build() {
    Column() {
      Text('parent: ' + this.myVal.toString())
        .fontSize(20)
      Child({ val: this.myVal, addOne: () => this.myVal++ })
    }
  }
}

运行效果：

五、总结

通过以上对比可以看出，V2 的双向绑定方案更加清晰和可控：

• 内置组件 ：$$ → !!，语法更简洁。
• 自定义组件 ：@Link → @Param + @Event，数据流从隐式同步变为显式事件驱动，降低了复杂状态管理下的维护成本。

在实际开发中，建议优先采用 V2 方案，以获得更好的代码可读性和可维护性。