HarmonyOS Next 开发系列：Local 状态管理实践

月未央2025-02-23 11:27

一、V1 版本中 @State 的局限性

在 ArkTS 的 V1 版本中，@State 用于修饰状态变量。当状态变量发生变化时，依赖该变量的组件会自动更新。然而，@State 存在一个明显的局限性：状态变量可以从外部初始化，但组件内部无法感知到外部初始化的变化。

以下是一个示例：

less 复制代码 
@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Column({ space: 10 }) {
      ChildComponent({ msg: '这是外部给到的初始化信息'})
    }
    .height('100%')
    .width('100%')
  }
}

@Component
struct ChildComponent {
  @State msg: string = '这个信息是在组件内部初始化';

  build() {
    Column() {
      Text(this.msg)
    }
  }
}

在这个例子中，ChildComponent 的 msg 属性虽然从外部初始化，但组件内部无法感知到外部传入的值。

二、@Local 修饰器概述

在 V2 版本中，ArkTS 引入了 @Local 修饰器，用于管理组件内部的状态变量。与 @State 不同，@Local 修饰的状态变量仅在组件内部有效，且当状态变量发生变化时，依赖该变量的组件会自动重新渲染。

需要注意的是：

  • @Local 只能在 ComponentV2 中使用。
  • V2 版本的状态修饰器与 V1 版本的状态修饰器不能混用。

三、@Local 的约束

  1. 显式类型声明 ：@Local 修饰的状态变量必须显式指定类型，不支持类型推断。
less 复制代码 
@Local message = 'Hello World'; // 错误：必须指定类型
//上述代码会报错： The property 'message' must specify a type.

@Local message: string = 'Hello World'; // 正确
  1. 初始化要求 ：@Local 修饰的状态变量必须"初始化"。

@Local 的语法与特性

@Local 修饰的变量称为状态变量。与普通变量的区别在于，状态变量的变化会触发 UI 的自动更新，从而实现响应式编程。

less 复制代码 
@Entry
@ComponentV2
struct Index {
  @Local message: string = '这是一条信息'; // 状态变量
  name: string = '这是另一条信息';         // 普通变量
}

五、实践探索

5.1 修饰基础类型

@Local 可以直接修饰基础类型（如 string、number、boolean、null、undefined），并在变量变化时更新关联的 UI 组件。

typescript 复制代码 
message: string = "Hello World"
@Local name: string = "孙膑"
@Local age: number = 25
@Local isMaimed: boolean = true
@Local occupation: undefined = undefined
@Local consort: null = null
@Local skillCount: any = 4
@Local skill: unknown = 3

❌ 报错： Use explicit types instead of "any", "unknown" (arkts-no-any-unknown)

所以，@Local修饰的基础类型不能包含: any和unknow

完整代码：

kotlin 复制代码 
@Entry
@ComponentV2
struct Index {
  message: string = "Hello World"
  @Local name: string = "孙膑"
  @Local age: number = 25
  @Local isMaimed: boolean = true
  @Local occupation: undefined | string = undefined
  @Local consort: null | string = null

  build() {
    Column({ space: 10 }) {
      Text(`将军:(${this.name}),年龄:${this.age},被刑否:${this.isMaimed},
            职业:${this.occupation},配偶:${this.consort}`)
        .fontSize(18)
        .fontStyle(FontStyle.Italic)
      Button('更新数据')
        .onClick(() => {
          this.message = this.message + "ab"
          this.name = this.name == "孙膑" ? "庞涓" : "孙膑"
          this.age++
          this.isMaimed = !this.isMaimed
          this.occupation = this.occupation === undefined ? "军师" : undefined
          this.consort = this.consort === null ? "王氏" : null
        })
    }
    .height('100%')
    .width('100%')
  }
}

关键点：

  • 非 @Local 修饰的变量即使变更也不会引起 UI 刷新。
  • @Local 修饰的基础变量变化后会触发 UI 刷新。
  • undefined 和 null 需要结合联合类型使用。

5.2 修饰容器类型

@Local 可以修饰容器类型（如 Array、Tuple、Set、Map），并在容器变化时触发 UI 更新。

less 复制代码 
@Entry
@ComponentV2
struct Index {
  @Local scholars: string[] = ["孙膑", "苏秦"]
  @Local profile: [string, number] = ["孙膑", 25]
  @Local swords: Set<string> = new Set(["轩辕", "太阿"])
  @Local owners: Map<string, string> = new Map([["皇帝", "轩辕"], ["勾践", "湛卢"]])

  build() {
    Column({ space: 10 }) {
      Text('人物:' + `${this.scholars}`)
      Text('人物信息:' + `${this.profile[0]}, 年龄:${this.profile[1]}`)
      Text('名剑山庄')
      ForEach(Array.from(this.swords), (sword: string) => {
        Text(sword)
      })
      Text('名册')
      ForEach(Array.from(this.owners.entries()), (item: [string, string]) => {
        Text(`持有者: ${item[0]} 兵器: ${item[1]}`)
      })
      Button('增加数据')
        .onClick(() => {
          this.scholars.push("庞涓")
          this.swords.add("龙泉")
          this.owners.set("不详", "龙泉")
        })
      Button('删除数据')
        .onClick(() => {
          this.scholars.pop()
          this.profile = ["", -1]
          this.swords.delete("龙泉")
          this.owners.delete("不详")
        })
      Button('替换数据')
        .onClick(() => {
          this.scholars[0] = "扶苏"
          this.profile = ["张三丰", 200]
          this.swords.delete("轩辕")
          this.swords.add("鱼肠")
          this.owners["皇帝"] = "圣剑"
        })
      Button('清除数据')
        .onClick(() => {
          this.scholars = []
          this.profile = [String(), Number()]
          this.swords.clear()
          this.owners.clear()
        })
      Button('新创建')
        .onClick(() => {
          this.scholars = ["孙膑", "苏秦"]
          this.profile = ["孙膑", 25]
          this.swords = new Set(["轩辕", "太阿"])
          this.owners = new Map([["皇帝", "轩辕"], ["勾践", "湛卢"]])
        })
    }
    .height('100%')
    .width('100%')
  }
}

关键点：

  • @Local 修饰的容器对象在增删改查时会触发 UI 刷新。

5.3 修饰对象类型

@Local 修饰的对象类型在属性变化时不会触发 UI 刷新，只有重新赋值时才会触发。

typescript 复制代码 
class Country {
  name: string
  code: string

  constructor(name: string, code: string) {
    this.name = name
    this.code = code
  }
}

class UserInfo {
  name: string
  age: number
  nationality: Country

  constructor(name: string, age: number, nationality: Country) {
    this.name = name
    this.age = age
    this.nationality = nationality
  }
}

@Entry
@ComponentV2
struct Index {
  @Local userInfo: UserInfo = new UserInfo("孙膑", 22, new Country("中国", "156"))

  build() {
    Column({ space: 10 }) {
      Text(`姓名:${this.userInfo.name},年龄:${this.userInfo.age},
            国籍:${this.userInfo.nationality.name},国家码:${this.userInfo.nationality.code}`)
      Button('更新姓名')
        .onClick(() => {
           this.userInfo.name = "庞涓"
        })
      Button('更新国家名称')
        .onClick(() => {
          this.userInfo.nationality.name = "CHN"
        })
      Button('更新国籍')
        .onClick(() => {
          this.userInfo.nationality = new Country("CHN", "156")
        })
      Button('更新用户')
        .onClick(() => {
          this.userInfo = new UserInfo("孟尝君", 30, new Country("齐国", "156"))
        })
    }
    .height('100%')
    .width('100%')
  }
}

关键点：

  • @Local修饰的实例对象的属性变化不会触发UI的刷新
  • @Local修饰的实例对象的嵌套对象以及嵌套对象的属性变化均不会触发UI的刷新
  • @Local修饰的实例对象的赋值会触发UI的刷新
    那么如何监听类的属性变化，从而来更新UI呢，会使用到后面说的 @ObservedV2和@Trace这两个状态修饰器。

5.4 容器对象类型

这里以数组容器包含类对象来研究，分别尝试怎删改查对于UI的作用

typescript 复制代码 
class Country {
  name: string
  code: string

  constructor(name: string, code: string) {
    this.name = name
    this.code = code
  }
}

class UserInfo {
  name: string
  age: number
  nationality: Country

  constructor(name: string, age: number, nationality: Country) {
    this.name = name
    this.age = age
    this.nationality = nationality
  }
}

@Entry
@ComponentV2
struct Index {
  @Local userInfos: UserInfo[] = [new UserInfo("孙膑", 22, new Country("中国", "156"))]

  build() {
    Column({ space: 10 }) {
      ForEach(this.userInfos, (userInfo: UserInfo) => {
        Text(`${userInfo.name},年龄:${userInfo.age},国籍:${userInfo.nationality.name},国家码:${userInfo.nationality.code}`)
      })
      Button('增加用户')
        .onClick(() => {
          this.userInfos.push(new UserInfo("孟尝君", 30, new Country("齐国", "156")))
        })
      Button('删除用户')
        .onClick(() => {
          this.userInfos.shift()
        })
      Button('清空用户')
        .onClick(() => {
          this.userInfos = []
        })
      Button('更新用户姓名')
        .onClick(() => {
          this.userInfos[0].name = ""
        })
      Button('更新用户国籍')
        .onClick(() => {
          this.userInfos[0].nationality.name = "CHN"
        })
    }
    .height('100%')
    .width('100%')
  }
}
  • @Local修饰的容器数组本身的增删改查会触发UI的刷新，与其内容器元素类型无关
  • @Local修饰的容器数组，元素是实例，那么对于实例的操作均不会触发UI的刷新；若想要触发UI的刷新，需要结合@ObservedV2和@Trace来达到目标效果

5.3 可选类型

arkts支持可选类型，并使用?来标记。不同于其他语言的可选类型标记，arkts中可选类型的问号标记在变量名之后，如下码所示。

c 复制代码 
name?: string

对于可选类型的普通变量，容器变量和实例变量，使用@Local是否会触发UI刷新呢？

typescript 复制代码 
class Country {
  name: string
  code: string

  constructor(name: string, code: string) {
    this.name = name
    this.code = code
  }
}

class UserInfo {
  name: string
  age: number
  nationality: Country

  constructor(name: string, age: number, nationality: Country) {
    this.name = name
    this.age = age
    this.nationality = nationality
  }
}

@Entry
@ComponentV2
struct Index {
  @Local userInfos?: UserInfo[]
  @Local msgs?: string[]
  @Local brandName?: string
  @Local address?: string = ""

  build() {
    Column({ space: 10 }) {
      Text(`乐队名称:${this.brandName}`)
      Text(`地址:${this.address}`)
      Text(`用户信息: ${typeof this.userInfos}`)
      ForEach(this.userInfos, (userInfo: UserInfo) => {
        Text(`${userInfo.name},年龄:${userInfo.age},国籍:${userInfo.nationality.name},国家码:${userInfo.nationality.code}`)
      })
      Text(`消息数组: ${typeof this.msgs}`)
      ForEach(this.msgs, (msg: string) => {
        Text('msg:' + `${msg}`)
      })
      Button('修改组合名称:')
        .onClick(() => {
          this.brandName = (this.brandName == undefined ? "海尔兄弟" : undefined)
        })
      Button('修改地址:')
        .onClick(() => {
          this.address = (this.address == undefined ? "大秦古道" : undefined)
        })
      Button('修改用户')
        .onClick(() => {
          if (this.userInfos == undefined) {
            this.userInfos = [new UserInfo("孙膑", 22, new Country("中国", "156"))]
          } else {
            this.userInfos = undefined
          }
        })
      Button('修改消息')
        .onClick(() => {
          this.msgs = (this.msgs == undefined ? [`${Math.round(Math.random() * 1000)}`] : undefined)
        })
    }
    .height('100%')
    .width('100%')
  }
}
  • @Local修饰的变量是非可选类型的情况下，一定需要初始化。所以在文章的开头，对于@Local的变量"初始化"是加了引号的，需要了解到这个点。
  • @Local修饰的可选类型变量默认指是undefined
  • 对于容器和对象的可选类型约束同之前的容器和对象类型

六、总结

通过本文的实践探索，我们深入了解了 @Local 修饰器的使用场景和约束条件：

  1. 基础类型 ：@Local 可以直接修饰基础类型，并在变化时触发 UI 刷新。
  2. 容器类型 ：@Local 修饰的容器类型在增删改查时会触发 UI 刷新。
  3. 对象类型 ：@Local 修饰的对象类型只有在重新赋值时才会触发 UI 刷新。
  4. 可选类型 ：@Local 支持修饰可选类型，并在变化时触发 UI 刷新。

对于更复杂的场景（如监听对象属性的变化），可以结合 @ObservedV2 和 @Trace 来实现。

参考文献：

1、鸿蒙开发者官方文档

相关推荐
写雨.07 小时前
鸿蒙定位开发服务
华为·harmonyos·鸿蒙
goto_w12 小时前
uniapp上使用webview与浏览器交互，支持三端（android、iOS、harmonyos next）
android·vue.js·ios·uni-app·harmonyos
别说我什么都不会1 天前
ohos.net.http请求HttpResponse header中set-ccokie值被转成array类型
网络协议·harmonyos
码是生活1 天前
鸿蒙开发排坑：解决 resourceManager.getRawFileContent() 获取文件内容为空问题
前端·harmonyos
鸿蒙场景化示例代码技术工程师1 天前
基于Canvas实现选座功能鸿蒙示例代码
华为·harmonyos
小脑斧爱吃鱼鱼1 天前
鸿蒙项目笔记（1）
笔记·学习·harmonyos
鸿蒙布道师1 天前
鸿蒙NEXT开发对象工具类（TS）
android·ios·华为·harmonyos·arkts·鸿蒙系统·huawei
zhang1062091 天前
HarmonyOS 基础组件和基础布局的介绍
harmonyos·基础组件·基础布局
马剑威（威哥爱编程）1 天前
在HarmonyOS NEXT 开发中，如何指定一个号码，拉起系统拨号页面
华为·harmonyos·arkts
GeniuswongAir1 天前
Flutter极速接入IM聊天功能并支持鸿蒙
flutter·华为·harmonyos
热门推荐
01我决定放弃搞 Java 了02DeepSeek各版本说明与优缺点分析03如何在WPS和Word/Excel中直接使用DeepSeek功能04RAG 实践- Ollama+RagFlow 部署本地知识库05本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程06从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑07如何本地部署AI智能体平台，带你手搓一个AI Agent08苍穹外卖面试总结09DeepSeek RAGFlow构建本地知识库系统10【芯片封测学习专栏 -- D2D 和 C2C 之间的区别】