刚接触 ArkTS 的人十有八九会被那一堆装饰器劝退。我最初也一样觉得它不是让我写 UI而是在教我做“依赖分析”。等真的把一个页面从命令式改造成声明式之后才发现这套写法真正的价值UI 只是状态的投影状态一变界面会自己跟着变。这篇我从零拆 ArkTS 声明式语法和状态管理适合刚入门、或者想系统理解 State/Prop/Link 区别的开发同学读完至少能少踩一半常见的刷新坑。1. 先搞懂声明式语法UI 不是“做”出来的是“算”出来的1.1 命令式界面开发为什么越写越累早期写界面最典型的一套流程是先在布局文件里定义控件然后在逻辑代码里拿着控件实例手动设置内容、显示或隐藏。比如一个登录页输入框有没有内容、登录按钮能不能点、错误提示显示什么这三个状态互相影响我得在多个回调里分别调用setText、setEnabled、setVisibility。一旦需求加一个“密码框为空时提示不同文案”就要再找几个地方补逻辑。这种写法的痛点在于UI 的状态被人为地拆散到了不同代码块里改一个业务规则必须在所有涉及的地方同步修改漏一处就是线上 bug。后来出现了声明式 UI核心思想非常朴素把界面看成状态的函数UI f(state)。你只需要描述“状态长什么样时界面长什么样”剩下的刷新、对比、更新交给框架。ArkTS 的声明式语法走的也是这条路。你在build()方法里用Column、Row、Text、Button这些组件搭出页面结构用if、ForEach表达条件和列表再通过状态变量驱动它们。当某个被装饰器标记的变量变化时框架会自动找到依赖它的组件并刷新不再需要手动去改控件。1.2 ArkTS 和 TypeScript戴着安全带的动态语言刚看名字会以为 ArkTS 就是 TypeScript 换了个名字实际体验下来它更像是 TS 的一个安全子集。TypeScript 本身允许很多灵活的动态写法但 ArkTS 为了支持 UI 框架在编译期分析状态依赖做了一些约束比如弱化any要求成员变量在使用前有明确类型限制部分动态反射能力。对 UI 层面来说这些约束其实是好事。比如定义数据模型我会用一个普通的class或interfaceinterface Task { id: number; title: string; done: boolean; }强类型能让编辑器提前告诉你哪里类型对不上也能让状态管理在传递数据时有个清晰的边界。入门阶段不需要把 TypeScript 的全部特性学完先掌握interface、class、基本类型、数组方法、箭头函数就够了。后面写组件参数、处理列表数据都会反复用到。1.3 装饰器声明式语法的“魔法入口”ArkTS 里最显眼的语法元素就是装饰器比如Component、State、Prop、Link。很多新手会误以为它只是给类加个标记实际上它是整个状态管理系统的“接线口”。以State为例它修饰一个成员变量后这个变量就变成了可观察的 UI 状态。框架会记录在build()过程中哪些组件读取过这个变量当变量重新赋值时框架只通知这些组件刷新。如果没有装饰器普通成员变量变了UI 不会有一丝反应。我习惯把装饰器理解成“黑板上的公告”和“便签纸”的区别。普通变量是便签贴在自己桌上改不改没人关心State是黑板写了什么全办公室都看得到。你写State不是为了炫技而是明确告诉 UI 框架这个值值得被关注变化时必须通知界面。2. 状态管理入门先给状态分分类2.1 状态不是数据库而是 UI 的数据源状态管理听起来很玄实际上就一句话状态是那些“变了之后界面要跟着变”的数据。包括业务数据比如用户列表、详情内容也包括视图状态比如当前选中的 Tab、是否加载中、筛选项。有一个常见误区刚接触 ArkTS看到装饰器就想给所有变量都加上把数据全部变成状态。结果界面频繁刷新性能变差定位问题也变得很困难。我的原则是写变量之前先问自己一句这个值变了UI 会变吗如果不会就让它当普通字段或外部变量如果会才考虑用状态装饰器。比如一个页面只展示用户名用户名本身肯定要放在状态里因为网络请求后它的变化要反映到界面。但一个临时计算用的中间变量就不要加State否则无端增加更新负担。2.2 State 与组件内状态的最小闭环State是每个组件自己内部的“私有状态”最典型的例子是计数器或展开收起标记。看一段最小示例Component struct Counter { State count: number 0; build() { Row() { Button(-) .onClick(() { this.count--; }) Text(${this.count}) Button() .onClick(() { this.count; }) } } }这里不需要像传统框架那样调用setState()或update()直接对this.count赋值即可。因为编译阶段已经识别出build()里的Text读取了count赋值后框架会触发局部刷新。使用State有个重要习惯不要在build()方法里面直接修改状态。build()是描述 UI 的地方不是执行逻辑的地方。你一旦在里面写this.count每次刷新可能都会再触发一次修改轻则死循环重则页面卡死。需要修改状态时放到按钮回调、事件监听或普通方法里。2.3 父子组件通信Prop 和 Link 怎么选组件不可能永远不通信。父组件要把数据传给子组件最常见的有两个装饰器Prop和Link。装饰器数据流向子组件能否修改适用场景Prop父 - 子能修改但不会同步回父组件纯展示型子组件Link父 - 子能修改且同步回父组件子组件需要操作父组件状态用Prop时父组件传的是一份快照子组件内部改了父组件感知不到。很多新人在这里踩坑子组件里给Prop赋值界面刷新了但父组件一看原数据没变以为 bug 了。其实不是 bug是选错了装饰器。如果子组件要修改数据且希望父组件知道就用Link。Link不是拷贝关系它和父组件的状态变量共享同一个数据源子组件赋值父组件随即同步。比较典型的场景是筛选栏筛选条件定义在父组件子组件点击按钮修改条件父组件根据条件重新渲染列表。还有一点要注意Link要求父组件传的是状态变量的引用不能传字面量。写Child({ count: 1 })是错的必须先有State count 1然后传Child({ count: this.count })。2.4 跨层级共享状态Provide / Consume有些状态在组件树里隔了很多层如果每一层都用Prop往下传中间层就要转发一堆与自己无关的数据非常啰嗦。这种时候用Provide和Consume更合适。父组件用Provide提供数据任意后代组件用Consume注入同一个数据。两者之间靠 key 匹配也可以让类型自动匹配。Provide(themeColor) themeColor: string #007AFF; // 后代组件 Consume(themeColor) themeColor: string;这样中间层完全不用感知这个数据。适合放主题色、用户信息、默认筛选条件这类全局性较强的状态。但我不建议把所有状态都Provide出去全局状态一旦多了排查问题时要顺着组件树找来源反而更累。局部能解决的就局部解决。2.5 观察“对象内部”Observed 与 ObjectLinkState观察的是“变量本身”的变化比如重新赋值、数组整体变化。但如果你有一个对象修改对象的某个属性会不会刷新直接修改一个普通对象里的字段大多数情况下是不会触发 UI 刷新的。这时候需要两个装饰器配合在类上标Observed在子组件接收该对象时用ObjectLink。Observed class TodoItem { title: string; done: boolean; constructor(title: string, done: boolean false) { this.title title; this.done done; } }子组件里用ObjectLink item: TodoItem接收后直接修改item.done true界面就能感知到。这个组合特别适合列表项组件列表数据由父组件持有列表项的交互行为又要直接修改对象内部属性用ObjectLink既避免了把整个数组传来传去又能拿到精确的刷新粒度。2.6 生命周期钩子状态初始化别放错位置ArkTS 组件常用生命周期包括aboutToAppear、aboutToDisappear以及页面级的onPageShow、onPageHide。简单说aboutToAppear相当于页面要被展示前的准备阶段适合拉取数据、初始化状态aboutToDisappear适合清理定时器、解绑监听。我见过不少人在声明属性时直接写State list: Item[] [];然后就在aboutToAppear里发请求往list塞数据这个思路没问题。关键是不要在build()里面直接触发网络请求或修改状态。因为build()可能在状态变化后多次执行你会在渲染过程中埋下不稳定的改动源。3. 从零写一个待办列表把声明式和状态管理串起来3.1 项目结构与数据模型设计先规划一个入门级待办应用顶部输入框中间待办列表底部三个筛选按钮全部 / 未完成 / 已完成外加一个剩余数量统计。虽然功能简单但足够覆盖State、Prop、Link、ObjectLink这几个核心知识点。我习惯先定数据模型再写页面。因为状态管理的关键在数据数据结构定了装饰器才能决定放在哪里。Observed class TodoItem { id: number; title: string; done: boolean; constructor(id: number, title: string, done: boolean false) { this.id id; this.title title; this.done done; } }这里id必须给一个稳定且唯一的标识后面ForEach渲染列表时会用到。3.2 父页面状态定义和基础布局主组件用Entry标记为页面入口内部维护四个状态待办列表、当前输入内容、筛选条件、剩余数量。Entry Component struct TodoPage { State todos: TodoItem[] []; State inputValue: string ; State filter: string all; State remaining: number 0; build() { Column({ space: 12 }) { Row({ space: 8 }) { TextInput({ placeholder: 输入待办事项, text: this.inputValue }) .onChange((value: string) { this.inputValue value; }) Button(新增) .onClick(() this.addTodo()) } Text(剩余 ${this.remaining} 项未完成) ForEach(this.filteredTodos(), (item: TodoItem) { TodoItemView({ item: item, onDelete: (todo: TodoItem) this.deleteTodo(todo) }) }, (item: TodoItem) item.id.toString()) FilterBar({ filter: this.filter }) } .padding(16) } }注意ForEach的第三参数是 key 生成器。我直接用item.id.toString()而不是用数组 index。用 index 当 key在删除中间项时后面所有项的 index 都会变列表复用时容易产生状态错乱。filteredTodos()是一个方法根据filter返回过滤后的数组。这个方法只做计算不修改状态可以安全地在build()中调用。3.3 新增待办用不可变方式更新数组新增逻辑比较简单但有一个习惯很关键更新数组时尽量生成新数组而不是修改原数组。private addTodo(): void { const title this.inputValue.trim(); if (title.length 0) { return; } const newTodo new TodoItem(Date.now(), title, false); this.todos [...this.todos, newTodo]; this.inputValue ; this.refreshRemaining(); }为什么用[...this.todos, newTodo]而不是this.todos.push(newTodo)直接push理论上也能被观察但在复杂的列表结构和ObjectLink混用场景下重新赋值更稳定。它明确地让State todos指向一个新数组框架能可靠地识别到变化。空字符串直接提前返回避免创建一堆空任务。这个判断虽然基础但很多人会忘。3.4 子组件用 ObjectLink 展示和修改待办列表项组件TodoItemView接收一个ObjectLink修饰的TodoItem加上一个删除回调。Component struct TodoItemView { ObjectLink item: TodoItem; onDelete: (item: TodoItem) void () {}; build() { Row({ space: 12 }) { Checkbox({ select: this.item.done }) .onChange((checked: boolean) { this.item.done checked; }) Text(this.item.title) .decoration({ type: this.item.done ? TextDecorationType.LineThrough : TextDecorationType.None }) Blank() Button(删除) .onClick(() { this.onDelete(this.item); }) } .padding(12) .width(100%) } }因为TodoItem是Observed类ObjectLink能够观察到item.done的属性变化所以Text的删除线会立刻更新。这里省去了手动通知父组件的功夫代码看起来也很直观。删除操作因为要修改父组件的todos数组所以通过回调传到父组件处理。这符合“谁持有数据谁负责修改数据”的原则。3.5 删除和筛选状态变更与统计删除逻辑要生成一个新数组并过滤掉对应项private deleteTodo(todo: TodoItem): void { this.todos this.todos.filter((item: TodoItem) item.id ! todo.id); this.refreshRemaining(); } private refreshRemaining(): void { this.remaining this.todos.filter((item: TodoItem) !item.done).length; }FilterBar组件用Link直接双向绑定筛选条件Component struct FilterBar { Link filter: string; build() { Row({ space: 8 }) { Button(全部) .onClick(() { this.filter all; }) Button(未完成) .onClick(() { this.filter todo; }) Button(已完成) .onClick(() { this.filter done; }) } } }父组件使用FilterBar({ filter: this.filter })此时Link生效。点击子组件里的按钮父组件的filter会同步变化列表自动重新筛选。这个模式比“子组件发出事件、父组件手动赋值”简洁得多。3.6 计算列表筛选逻辑放在哪里filteredTodos()是列表渲染的数据源private filteredTodos(): TodoItem[] { if (this.filter todo) { return this.todos.filter((item: TodoItem) !item.done); } if (this.filter done) { return this.todos.filter((item: TodoItem) item.done); } return this.todos; }不需要在这里加State因为它是一个派生值是从todos和filter两个状态计算出来的。如果加上State反而要维护一份缓存搞不好还要在每次修改todos时同步它属于多余的复杂度。如果未来列表很大、过滤很慢可以把filteredTodos的结果缓存起来再配合Watch监听依赖状态更新缓存。入门阶段先不用过度设计保持直接计算反而更容易理解。4. 状态管理高频问题与排查经验4.1 UI 死活不刷新先查这四件事状态不刷新是入门阶段遇到最多的现象通常不是框架问题而是观察粒度没覆盖到。检查顺序这个字段是不是真的加了装饰器普通字段不会触发刷新。是不是修改了对象内部属性但类没有加Observed是不是修改了数组里某一项的某个属性整个数组没重新赋值是不是在build()里用了状态但修改的时候组件已经脱离组件树其中第三点最隐蔽。常见写法是this.todos[0].title 新标题;如果todos只是State而TodoItem不是Observed这个变更大概率不会刷新页面。正确做法是重新生成对象并替换数组或者使用ObservedObjectLink。4.2 Prop 修改不同步父组件这不是 bugProp的本质决定了它是单向的。子组件内部对Prop赋值UI 上可以立刻看到变化但一旦子组件重新收到父组件的传参本地修改就会被覆盖父组件的数据也不会变。如果你真的希望子组件改完父组件能同步就换Link。如果担心双向绑定会让数据流难追也可以保持单向子组件通过回调把“要改的值”传给父组件由父组件统一修改。两种方案没有绝对对错但“谁的数据谁负责改”在大型项目中更省心。4.3 Link 绑定时的几个硬性限制Link不是随便哪里都能用的。我整理过几个典型报错错误写法说明Child({ count: 1 })不能直接传字面量Child({ count: this.count 1 })不能传表达式Child({ count: someNumber })目标必须是父组件的状态变量普通字段不行要让Link正常工作父组件侧必须有一个可观察的状态变量作为数据源。一旦子组件里this.filter done修改会立即同步到父组件。如果你用变量名排版觉得怪异可以打开 DevTools 状态面板看同步路径通常能直接定位。4.4 异步回调里的状态页面可能已经不存在状态管理不止 UI 刷新还关系到异步任务的安全。网络请求是比较典型的高频场景用户进入详情页请求还没回来就返回上一页等回调执行时组件可能已经销毁。这时再去修改状态轻则日志报警重则内存泄漏。我的习惯是在aboutToDisappear里做标记或取消订阅比如维护一个isActive标志异步回调先判断它aboutToDisappear(): void { this.isActive false; } // 网络回调里 if (this.isActive) { this.data result; }另外还有一种竞态问题快速切换两个条件后发出的请求先返回旧请求后返回导致界面显示的是过期结果。前端圈通常用请求序号或时间戳解决只接受最新一次请求的结果。4.5 装饰器用错位置编译器会直接报错ArkTS 对装饰器的使用位置限制很明确装饰器只能作用于组件类内的成员变量不能修饰局部变量、全局变量、函数参数。看到State写在方法里的代码基本都是编译不过的。还有一个容易出错的是Provide和Consume的 key 匹配。如果提供方写的是字符串 key消费方也必须要同一个 key大小写也要完全一致。用类型自动匹配时要确保两边的类型完全一样否则运行时找不到对应数据源。遇到编译报错先别慌ArkTS 的静态检查已经能拦截大部分问题按提示把装饰器挪到正确位置大多数情况能解决。4.6 状态方案速查表最后一个实战总结遇到具体场景可以直接参考场景推荐方案组件内部独立的 UI 状态State父传子子组件只展示Prop子组件修改父组件状态并同步Link跨多层组件共享全局数据Provide / Consume修改对象内部属性需要刷新Observed ObjectLink页面级共享、应用级共享AppStorage StorageLink / StorageProp需要监听状态变化并执行逻辑Watch 配合状态装饰器这个表格不是死规定但它可以帮你快速起步。状态管理最重要的不是把所有装饰器都用上而是想清楚“谁来改数据、改完谁要知道”。设计清楚了声明式语法会自动帮你处理剩下的大量界面刷新工作。我在实际开发里养成的一个习惯是写组件之前先在纸上画一条数据流几号组件负责展示几号组件负责交互改动最终由谁落地。然后再决定用哪个装饰器。很多“页面不刷新”“父子不同步”的问题其实在动手前就能避免。ArkTS 的状态管理入门并不复杂复杂的是状态一多人容易忘掉数据是从哪里来、往哪里去。只要始终记得“UI 是状态的投影”你就能在这个体系里站稳脚跟。
刚接触 ArkTS 的人十有八九会被那一堆装饰器劝退。我最初也一样觉得它不是让我写 UI而是在教我做“依赖分析”。等真的把一个页面从命令式改造成声明式之后才发现这套写法真正的价值UI 只是状态的投影状态一变界面会自己跟着变。这篇我从零拆 ArkTS 声明式语法和状态管理适合刚入门、或者想系统理解 State/Prop/Link 区别的开发同学读完至少能少踩一半常见的刷新坑。1. 先搞懂声明式语法UI 不是“做”出来的是“算”出来的1.1 命令式界面开发为什么越写越累早期写界面最典型的一套流程是先在布局文件里定义控件然后在逻辑代码里拿着控件实例手动设置内容、显示或隐藏。比如一个登录页输入框有没有内容、登录按钮能不能点、错误提示显示什么这三个状态互相影响我得在多个回调里分别调用setText、setEnabled、setVisibility。一旦需求加一个“密码框为空时提示不同文案”就要再找几个地方补逻辑。这种写法的痛点在于UI 的状态被人为地拆散到了不同代码块里改一个业务规则必须在所有涉及的地方同步修改漏一处就是线上 bug。后来出现了声明式 UI核心思想非常朴素把界面看成状态的函数UI f(state)。你只需要描述“状态长什么样时界面长什么样”剩下的刷新、对比、更新交给框架。ArkTS 的声明式语法走的也是这条路。你在build()方法里用Column、Row、Text、Button这些组件搭出页面结构用if、ForEach表达条件和列表再通过状态变量驱动它们。当某个被装饰器标记的变量变化时框架会自动找到依赖它的组件并刷新不再需要手动去改控件。1.2 ArkTS 和 TypeScript戴着安全带的动态语言刚看名字会以为 ArkTS 就是 TypeScript 换了个名字实际体验下来它更像是 TS 的一个安全子集。TypeScript 本身允许很多灵活的动态写法但 ArkTS 为了支持 UI 框架在编译期分析状态依赖做了一些约束比如弱化any要求成员变量在使用前有明确类型限制部分动态反射能力。对 UI 层面来说这些约束其实是好事。比如定义数据模型我会用一个普通的class或interfaceinterface Task { id: number; title: string; done: boolean; }强类型能让编辑器提前告诉你哪里类型对不上也能让状态管理在传递数据时有个清晰的边界。入门阶段不需要把 TypeScript 的全部特性学完先掌握interface、class、基本类型、数组方法、箭头函数就够了。后面写组件参数、处理列表数据都会反复用到。1.3 装饰器声明式语法的“魔法入口”ArkTS 里最显眼的语法元素就是装饰器比如Component、State、Prop、Link。很多新手会误以为它只是给类加个标记实际上它是整个状态管理系统的“接线口”。以State为例它修饰一个成员变量后这个变量就变成了可观察的 UI 状态。框架会记录在build()过程中哪些组件读取过这个变量当变量重新赋值时框架只通知这些组件刷新。如果没有装饰器普通成员变量变了UI 不会有一丝反应。我习惯把装饰器理解成“黑板上的公告”和“便签纸”的区别。普通变量是便签贴在自己桌上改不改没人关心State是黑板写了什么全办公室都看得到。你写State不是为了炫技而是明确告诉 UI 框架这个值值得被关注变化时必须通知界面。2. 状态管理入门先给状态分分类2.1 状态不是数据库而是 UI 的数据源状态管理听起来很玄实际上就一句话状态是那些“变了之后界面要跟着变”的数据。包括业务数据比如用户列表、详情内容也包括视图状态比如当前选中的 Tab、是否加载中、筛选项。有一个常见误区刚接触 ArkTS看到装饰器就想给所有变量都加上把数据全部变成状态。结果界面频繁刷新性能变差定位问题也变得很困难。我的原则是写变量之前先问自己一句这个值变了UI 会变吗如果不会就让它当普通字段或外部变量如果会才考虑用状态装饰器。比如一个页面只展示用户名用户名本身肯定要放在状态里因为网络请求后它的变化要反映到界面。但一个临时计算用的中间变量就不要加State否则无端增加更新负担。2.2 State 与组件内状态的最小闭环State是每个组件自己内部的“私有状态”最典型的例子是计数器或展开收起标记。看一段最小示例Component struct Counter { State count: number 0; build() { Row() { Button(-) .onClick(() { this.count--; }) Text(${this.count}) Button() .onClick(() { this.count; }) } } }这里不需要像传统框架那样调用setState()或update()直接对this.count赋值即可。因为编译阶段已经识别出build()里的Text读取了count赋值后框架会触发局部刷新。使用State有个重要习惯不要在build()方法里面直接修改状态。build()是描述 UI 的地方不是执行逻辑的地方。你一旦在里面写this.count每次刷新可能都会再触发一次修改轻则死循环重则页面卡死。需要修改状态时放到按钮回调、事件监听或普通方法里。2.3 父子组件通信Prop 和 Link 怎么选组件不可能永远不通信。父组件要把数据传给子组件最常见的有两个装饰器Prop和Link。装饰器数据流向子组件能否修改适用场景Prop父 - 子能修改但不会同步回父组件纯展示型子组件Link父 - 子能修改且同步回父组件子组件需要操作父组件状态用Prop时父组件传的是一份快照子组件内部改了父组件感知不到。很多新人在这里踩坑子组件里给Prop赋值界面刷新了但父组件一看原数据没变以为 bug 了。其实不是 bug是选错了装饰器。如果子组件要修改数据且希望父组件知道就用Link。Link不是拷贝关系它和父组件的状态变量共享同一个数据源子组件赋值父组件随即同步。比较典型的场景是筛选栏筛选条件定义在父组件子组件点击按钮修改条件父组件根据条件重新渲染列表。还有一点要注意Link要求父组件传的是状态变量的引用不能传字面量。写Child({ count: 1 })是错的必须先有State count 1然后传Child({ count: this.count })。2.4 跨层级共享状态Provide / Consume有些状态在组件树里隔了很多层如果每一层都用Prop往下传中间层就要转发一堆与自己无关的数据非常啰嗦。这种时候用Provide和Consume更合适。父组件用Provide提供数据任意后代组件用Consume注入同一个数据。两者之间靠 key 匹配也可以让类型自动匹配。Provide(themeColor) themeColor: string #007AFF; // 后代组件 Consume(themeColor) themeColor: string;这样中间层完全不用感知这个数据。适合放主题色、用户信息、默认筛选条件这类全局性较强的状态。但我不建议把所有状态都Provide出去全局状态一旦多了排查问题时要顺着组件树找来源反而更累。局部能解决的就局部解决。2.5 观察“对象内部”Observed 与 ObjectLinkState观察的是“变量本身”的变化比如重新赋值、数组整体变化。但如果你有一个对象修改对象的某个属性会不会刷新直接修改一个普通对象里的字段大多数情况下是不会触发 UI 刷新的。这时候需要两个装饰器配合在类上标Observed在子组件接收该对象时用ObjectLink。Observed class TodoItem { title: string; done: boolean; constructor(title: string, done: boolean false) { this.title title; this.done done; } }子组件里用ObjectLink item: TodoItem接收后直接修改item.done true界面就能感知到。这个组合特别适合列表项组件列表数据由父组件持有列表项的交互行为又要直接修改对象内部属性用ObjectLink既避免了把整个数组传来传去又能拿到精确的刷新粒度。2.6 生命周期钩子状态初始化别放错位置ArkTS 组件常用生命周期包括aboutToAppear、aboutToDisappear以及页面级的onPageShow、onPageHide。简单说aboutToAppear相当于页面要被展示前的准备阶段适合拉取数据、初始化状态aboutToDisappear适合清理定时器、解绑监听。我见过不少人在声明属性时直接写State list: Item[] [];然后就在aboutToAppear里发请求往list塞数据这个思路没问题。关键是不要在build()里面直接触发网络请求或修改状态。因为build()可能在状态变化后多次执行你会在渲染过程中埋下不稳定的改动源。3. 从零写一个待办列表把声明式和状态管理串起来3.1 项目结构与数据模型设计先规划一个入门级待办应用顶部输入框中间待办列表底部三个筛选按钮全部 / 未完成 / 已完成外加一个剩余数量统计。虽然功能简单但足够覆盖State、Prop、Link、ObjectLink这几个核心知识点。我习惯先定数据模型再写页面。因为状态管理的关键在数据数据结构定了装饰器才能决定放在哪里。Observed class TodoItem { id: number; title: string; done: boolean; constructor(id: number, title: string, done: boolean false) { this.id id; this.title title; this.done done; } }这里id必须给一个稳定且唯一的标识后面ForEach渲染列表时会用到。3.2 父页面状态定义和基础布局主组件用Entry标记为页面入口内部维护四个状态待办列表、当前输入内容、筛选条件、剩余数量。Entry Component struct TodoPage { State todos: TodoItem[] []; State inputValue: string ; State filter: string all; State remaining: number 0; build() { Column({ space: 12 }) { Row({ space: 8 }) { TextInput({ placeholder: 输入待办事项, text: this.inputValue }) .onChange((value: string) { this.inputValue value; }) Button(新增) .onClick(() this.addTodo()) } Text(剩余 ${this.remaining} 项未完成) ForEach(this.filteredTodos(), (item: TodoItem) { TodoItemView({ item: item, onDelete: (todo: TodoItem) this.deleteTodo(todo) }) }, (item: TodoItem) item.id.toString()) FilterBar({ filter: this.filter }) } .padding(16) } }注意ForEach的第三参数是 key 生成器。我直接用item.id.toString()而不是用数组 index。用 index 当 key在删除中间项时后面所有项的 index 都会变列表复用时容易产生状态错乱。filteredTodos()是一个方法根据filter返回过滤后的数组。这个方法只做计算不修改状态可以安全地在build()中调用。3.3 新增待办用不可变方式更新数组新增逻辑比较简单但有一个习惯很关键更新数组时尽量生成新数组而不是修改原数组。private addTodo(): void { const title this.inputValue.trim(); if (title.length 0) { return; } const newTodo new TodoItem(Date.now(), title, false); this.todos [...this.todos, newTodo]; this.inputValue ; this.refreshRemaining(); }为什么用[...this.todos, newTodo]而不是this.todos.push(newTodo)直接push理论上也能被观察但在复杂的列表结构和ObjectLink混用场景下重新赋值更稳定。它明确地让State todos指向一个新数组框架能可靠地识别到变化。空字符串直接提前返回避免创建一堆空任务。这个判断虽然基础但很多人会忘。3.4 子组件用 ObjectLink 展示和修改待办列表项组件TodoItemView接收一个ObjectLink修饰的TodoItem加上一个删除回调。Component struct TodoItemView { ObjectLink item: TodoItem; onDelete: (item: TodoItem) void () {}; build() { Row({ space: 12 }) { Checkbox({ select: this.item.done }) .onChange((checked: boolean) { this.item.done checked; }) Text(this.item.title) .decoration({ type: this.item.done ? TextDecorationType.LineThrough : TextDecorationType.None }) Blank() Button(删除) .onClick(() { this.onDelete(this.item); }) } .padding(12) .width(100%) } }因为TodoItem是Observed类ObjectLink能够观察到item.done的属性变化所以Text的删除线会立刻更新。这里省去了手动通知父组件的功夫代码看起来也很直观。删除操作因为要修改父组件的todos数组所以通过回调传到父组件处理。这符合“谁持有数据谁负责修改数据”的原则。3.5 删除和筛选状态变更与统计删除逻辑要生成一个新数组并过滤掉对应项private deleteTodo(todo: TodoItem): void { this.todos this.todos.filter((item: TodoItem) item.id ! todo.id); this.refreshRemaining(); } private refreshRemaining(): void { this.remaining this.todos.filter((item: TodoItem) !item.done).length; }FilterBar组件用Link直接双向绑定筛选条件Component struct FilterBar { Link filter: string; build() { Row({ space: 8 }) { Button(全部) .onClick(() { this.filter all; }) Button(未完成) .onClick(() { this.filter todo; }) Button(已完成) .onClick(() { this.filter done; }) } } }父组件使用FilterBar({ filter: this.filter })此时Link生效。点击子组件里的按钮父组件的filter会同步变化列表自动重新筛选。这个模式比“子组件发出事件、父组件手动赋值”简洁得多。3.6 计算列表筛选逻辑放在哪里filteredTodos()是列表渲染的数据源private filteredTodos(): TodoItem[] { if (this.filter todo) { return this.todos.filter((item: TodoItem) !item.done); } if (this.filter done) { return this.todos.filter((item: TodoItem) item.done); } return this.todos; }不需要在这里加State因为它是一个派生值是从todos和filter两个状态计算出来的。如果加上State反而要维护一份缓存搞不好还要在每次修改todos时同步它属于多余的复杂度。如果未来列表很大、过滤很慢可以把filteredTodos的结果缓存起来再配合Watch监听依赖状态更新缓存。入门阶段先不用过度设计保持直接计算反而更容易理解。4. 状态管理高频问题与排查经验4.1 UI 死活不刷新先查这四件事状态不刷新是入门阶段遇到最多的现象通常不是框架问题而是观察粒度没覆盖到。检查顺序这个字段是不是真的加了装饰器普通字段不会触发刷新。是不是修改了对象内部属性但类没有加Observed是不是修改了数组里某一项的某个属性整个数组没重新赋值是不是在build()里用了状态但修改的时候组件已经脱离组件树其中第三点最隐蔽。常见写法是this.todos[0].title 新标题;如果todos只是State而TodoItem不是Observed这个变更大概率不会刷新页面。正确做法是重新生成对象并替换数组或者使用ObservedObjectLink。4.2 Prop 修改不同步父组件这不是 bugProp的本质决定了它是单向的。子组件内部对Prop赋值UI 上可以立刻看到变化但一旦子组件重新收到父组件的传参本地修改就会被覆盖父组件的数据也不会变。如果你真的希望子组件改完父组件能同步就换Link。如果担心双向绑定会让数据流难追也可以保持单向子组件通过回调把“要改的值”传给父组件由父组件统一修改。两种方案没有绝对对错但“谁的数据谁负责改”在大型项目中更省心。4.3 Link 绑定时的几个硬性限制Link不是随便哪里都能用的。我整理过几个典型报错错误写法说明Child({ count: 1 })不能直接传字面量Child({ count: this.count 1 })不能传表达式Child({ count: someNumber })目标必须是父组件的状态变量普通字段不行要让Link正常工作父组件侧必须有一个可观察的状态变量作为数据源。一旦子组件里this.filter done修改会立即同步到父组件。如果你用变量名排版觉得怪异可以打开 DevTools 状态面板看同步路径通常能直接定位。4.4 异步回调里的状态页面可能已经不存在状态管理不止 UI 刷新还关系到异步任务的安全。网络请求是比较典型的高频场景用户进入详情页请求还没回来就返回上一页等回调执行时组件可能已经销毁。这时再去修改状态轻则日志报警重则内存泄漏。我的习惯是在aboutToDisappear里做标记或取消订阅比如维护一个isActive标志异步回调先判断它aboutToDisappear(): void { this.isActive false; } // 网络回调里 if (this.isActive) { this.data result; }另外还有一种竞态问题快速切换两个条件后发出的请求先返回旧请求后返回导致界面显示的是过期结果。前端圈通常用请求序号或时间戳解决只接受最新一次请求的结果。4.5 装饰器用错位置编译器会直接报错ArkTS 对装饰器的使用位置限制很明确装饰器只能作用于组件类内的成员变量不能修饰局部变量、全局变量、函数参数。看到State写在方法里的代码基本都是编译不过的。还有一个容易出错的是Provide和Consume的 key 匹配。如果提供方写的是字符串 key消费方也必须要同一个 key大小写也要完全一致。用类型自动匹配时要确保两边的类型完全一样否则运行时找不到对应数据源。遇到编译报错先别慌ArkTS 的静态检查已经能拦截大部分问题按提示把装饰器挪到正确位置大多数情况能解决。4.6 状态方案速查表最后一个实战总结遇到具体场景可以直接参考场景推荐方案组件内部独立的 UI 状态State父传子子组件只展示Prop子组件修改父组件状态并同步Link跨多层组件共享全局数据Provide / Consume修改对象内部属性需要刷新Observed ObjectLink页面级共享、应用级共享AppStorage StorageLink / StorageProp需要监听状态变化并执行逻辑Watch 配合状态装饰器这个表格不是死规定但它可以帮你快速起步。状态管理最重要的不是把所有装饰器都用上而是想清楚“谁来改数据、改完谁要知道”。设计清楚了声明式语法会自动帮你处理剩下的大量界面刷新工作。我在实际开发里养成的一个习惯是写组件之前先在纸上画一条数据流几号组件负责展示几号组件负责交互改动最终由谁落地。然后再决定用哪个装饰器。很多“页面不刷新”“父子不同步”的问题其实在动手前就能避免。ArkTS 的状态管理入门并不复杂复杂的是状态一多人容易忘掉数据是从哪里来、往哪里去。只要始终记得“UI 是状态的投影”你就能在这个体系里站稳脚跟。
