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

程序员黑黑

44人浏览 · 2026-07-08 14:00:00

程序员黑黑 · 2026-07-08 14:00:00 发布

文章目录

在 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++ })
    }
  }
}