重要说明

ArkTS中的$和this与TypeScript/JavaScript中的同名关键字有显著差异，具有ArkTS特有的语义和使用限制，开发者必须严格遵循ArkTS的使用规范。

@ComponentV2
struct UserProfile {
  // 组件属性
  @Param userId: number;
  @Local userName: string = "";
  @Local userAvatar: string = "";

  // 组件方法
  async loadUserInfo() {
    const userInfo = await UserApi.getInfo(this.userId);
    this.userName = userInfo.name;
    this.userAvatar = userInfo.avatar;
  }

  // 生命周期
  aboutToAppear() {
    this.loadUserInfo(); // 调用组件方法
  }

  build() {
    Column() {
      // 访问组件状态
      Image(this.userAvatar)
        .width(80)
        .height(80)
        .borderRadius(40)
      
      Text(this.userName)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
      
      Button("刷新")
        .onClick(() => {
          this.loadUserInfo(); // 回调中访问组件方法
        })
    }
  }
}

// ✅ 正确：this自动绑定
Button("点击")
  .onClick(() => {
    this.loadUserInfo(); // this正确指向组件实例
  })

// ✅ 正确：普通方法中this自动绑定
handleClick() {
  this.loadUserInfo(); // this正确指向组件实例
}

// ❌ 错误：不支持修改this指向
this.loadUserInfo.call(otherInstance); // 编译报错

// ❌ 错误：不支持bind方法
const boundFn = this.loadUserInfo.bind(this); // 编译报错

// V1组件体系
@Component
struct Parent {
  @State count: number = 0;

  build() {
    Column() {
      Text(`父组件count: ${this.count}`)
      // 通过$传递引用，实现双向绑定
      Child({ count: $count })
    }
  }
}

@Component
struct Child {
  @Link count: number; // 接收引用

  build() {
    Button(`子组件count: ${this.count}`)
      .onClick(() => {
        this.count += 1; // 直接修改父组件状态
      })
  }
}

@ComponentV2
struct SearchPage {
  @Local searchText: string = "";
  @Local isChecked: boolean = false;

  build() {
    Column() {
      // TextInput的text属性双向绑定
      TextInput({ text: $searchText, placeholder: "请输入搜索内容" })
        .width('90%')
        .height(44)
      
      Text(`搜索内容: ${this.searchText}`)
        .margin({ top: 20 })
      
      // Toggle的isOn属性双向绑定
      Toggle({ type: ToggleType.Switch, isOn: $isChecked })
        .margin({ top: 20 })
      
      Text(`开关状态: ${this.isChecked ? "开" : "关"}`)
    }
    .width('100%')
    .padding(20)
  }
}

// 父组件
@ComponentV2
struct Grandparent {
  @Local theme: string = "light";

  build() {
    Parent({ theme: $theme })
  }
}

// 中间层组件，不需要关心theme的具体值，只需透传
@ComponentV2
struct Parent {
  @Param theme: Writable; // 接收引用类型 build() { Child({ theme: this.theme }) // 直接透传引用 } } // 子组件，可以修改theme状态 @ComponentV2 struct Child { @Param theme: Writable; build() { Button(`切换到${this.theme.value === "light" ? "深色" : "浅色"}主题`) .onClick(() => { this.theme.value = this.theme.value === "light" ? "dark" : "light"; }) } }

// Writable类型定义（简化版）
interface Writable { value: T; // 访问和修改状态值 } // 使用示例 @ComponentV2 struct Parent { @Local count: number = 0; build() { Column() { Text(`Count: ${this.count}`) Child({ count: $count }) // $count返回Writable类型 } } } @ComponentV2 struct Child { @Param count: Writable; // 接收Writable类型 build() { Button(`Increment: ${this.count.value}`) .onClick(() => { this.count.value += 1; // 通过.value修改值 }) } }

@ComponentV2
struct FormPage {
  @Local formData: {
    username: string;
    password: string;
    remember: boolean;
  } = {
    username: "",
    password: "",
    remember: false
  };

  handleSubmit() {
    console.log("表单数据", this.formData);
    // 提交表单逻辑
  }

  build() {
    Column({ space: 20 }) {
      TextInput({ text: $this.formData.username, placeholder: "用户名" })
        .width('90%')
        .height(44)
      
      TextInput({
        text: $this.formData.password,
        placeholder: "密码",
        type: InputType.Password
      })
        .width('90%')
        .height(44)
      
      Toggle({ type: ToggleType.Checkbox, isOn: $this.formData.remember }) {
        Text("记住密码")
      }
      
      Button("提交")
        .width('90%')
        .height(44)
        .onClick(() => {
          this.handleSubmit();
        })
    }
    .width('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center)
  }
}

@ComponentV2
struct UserProfile {
  @Local userInfo: {
    name: string;
    address: {
      city: string;
      street: string;
    }
  } = {
    name: "",
    address: {
      city: "",
      street: ""
    }
  };

  build() {
    Column({ space: 20 }) {
      // 直接创建嵌套属性的引用
      TextInput({ text: $this.userInfo.name, placeholder: "姓名" })
      TextInput({ text: $this.userInfo.address.city, placeholder: "城市" })
      TextInput({ text: $this.userInfo.address.street, placeholder: "街道" })
    }
  }
}

V2特性优势

在V2体系中，嵌套对象的响应式是自动支持的，无需额外的@Observed装饰器，直接使用$即可创建任意层级嵌套属性的引用。

官方建议

HarmonyOS官方推荐在V2组件体系中尽量减少双向绑定的使用，采用单向数据流模式，状态变更逻辑更加清晰，更容易调试和维护，长期来看可大幅降低大型项目的维护成本。