企业官网建设流程全解析

做鸿蒙应用开发这段时间，我最大的感受是：凡是写过几行ArkTS页面的人，八成都在状态管理上栽过跟头。特别是@State/@Prop/@Link这三个装饰器，官方文档写得很简洁，但真正上手之后，会发现一堆文档里没写明白的细节和坑。这篇文章我不打算复述文档，而是把自己实际项目中遇到的场景、踩过的坑、以及最后沉淀下来的用法经验一次性说完，希望能帮你少走弯路。

我默认你已经建过 HarmonyOS 工程，知道怎么用 DevEco Studio 跑起来一个页面。如果刚接触 ArkTS，我也尽量把原理讲得直白一些，因为理解这三个装饰器的设计意图，比背语法更重要。

1. 为什么状态管理是 ArkTS 开发的第一道坎

1.1 先理解 ArkTS 状态管理的本质

做过 Web 前端的朋友应该很熟悉 Vue 的响应式系统，或者 React 的 setState。ArkTS 的装饰器体系，本质上是类似的"数据驱动 UI"方案：你不需要手动去修改某个 Text 组件的文字内容，只需要修改背后的数据变量，框架会自动把变化同步到界面上。

ArkTS 的响应式原理，简单来说就是框架在编译期和运行期对变量做了一层观测代理。当你用 @State、@Prop、@Link 装饰一个变量时，这个变量就不再是普通数据了：

• 框架会记录谁在读取这个变量（依赖收集）
• 当你修改变量时，框架会通知所有依赖它的组件去重新渲染

听起来很简单？实际开发中复杂的地方在于：数据共享的粒度和数据流向的控制。一个页面里往往有多个子组件，子组件里又有孙组件，数据要从顶层传到最底层，还要保证底层的修改能正确反馈到顶层，这时候装饰器的选型就变得至关重要。

我见过不少新手直接把所有变量都声明成 @State，不管它需不需要跨组件传递。结果就是：组件之间数据相互影响、刷新逻辑混乱、有的变量改了 UI 不刷新，有的变量不该刷新的地方疯狂刷新。这个问题的根源，就是对三个装饰器的职责边界没有清晰认知。

1.2 三个装饰器对应三种不同的数据需求

用一句话概括：

• @State管的是"组件自己内部的状态"
• @Prop管的是"从外部传入、子组件只能读不能回写"的状态
• @Link管的是"父子组件共享、任意一方修改都会同步到另一方"的状态

我画过一张很土的类比图：@State 是你自己钱包里的钱，花多少自己说了算，跟别人没关系；@Prop 是公司给你的工牌，你能用，但不能自己改上面的字；@Link 是你们合租的公共账户，任何一个人存钱取钱，另一个人的账单马上就会变。

把这个类比记住，后面的用法基本不会搞反。

2. 三个装饰器的完整用法与关键特性

2.1 @State：组件级状态的基础设施

@State 的用法非常简单：

@Component export struct Counter { @State count: number = 0; build() { Column() { Text(`当前计数: ${this.count}`) .fontSize(20) Button('加一') .onClick(() => { this.count++; }) } } }

点击按钮，text 会自动从 0 变成 1。这个基本示例没什么好讲的，真正要注意的是 @State 的几个隐藏特性，这些都是踩坑高发区：

• @State 只能装饰组件自身的变量，它的初始化必须在该组件内部完成，不能通过构造函数从外部传入初始值覆盖它（除非配合 @Prop/@Link 的父传子机制来做）。
• @State 对普通类型（number、string、boolean）的观察最灵敏，直接赋值就会刷新 UI。
• @State 对数组和对象的观察有限制，这个问题我后面第三节会专门讲，这里先记住：不是所有数据变化都能被观测到。
• @State 变量的修改要整体赋值，不要试图用"局部更新"的思路去改，否则很容易触发不了刷新。

还有一个被很多人忽略的点：@State 不只可以装饰组件内置的普通变量，还可以配合 @Observed 去装饰类对象。这样一来，类内部的属性变化也能被观测到，这是处理复杂数据类型的关键手段。

2.2 @Prop：单向数据流的"只读"通道

@Prop 的定位是从父组件接收初始值，并且在父组件数据变化时同步更新到子组件。但子组件自己对这个值的修改，不会传回父组件。

看个例子：

@Component export struct ChildComponent { @Prop title: string; build() { Text(this.title) .fontSize(16); } } @Entry @Component struct ParentComponent { @State parentTitle: string = '初始标题'; build() { Column() { ChildComponent({ title: this.parentTitle }) Button('修改父组件标题') .onClick(() => { this.parentTitle = '父组件改的新标题'; }) } } }

当父组件的parentTitle变化时，子组件里的title会跟着变；但如果子组件内部某处执行了this.title = 'xxx'，这个修改只会影响子组件本地的显示，父组件完全感知不到。

这里有个非常关键的细节：@Prop 是值拷贝，而不是引用传递。也就是说，子组件拿到的是一份独立的拷贝。它的内存地址跟父组件的变量不是同一个。之所以要做成值拷贝，是因为框架需要隔离父子和子组件之间的单向数据流，防止子组件意外修改父组件的数据。

这个特性在页面转场和组件复用时有坑。比如你在子组件里改了 @Prop 的值，然后切到别的页面再切回来，你会发现子组件里的值又变回了父组件传来的那个值。因为每次页面重建，@Prop 都会用父组件当前的数据重新初始化。这不是 bug，是设计如此，但新手经常在这里怀疑人生。

2.3 @Link：双向绑定的"引用"通道

和 @Prop 不同，@Link 是引用传递。父子组件共享同一个数据源，任意一方修改，另一方都会同步刷新。

@Component export struct ChildComponent { @Link count: number; build() { Button(`子组件计数: ${this.count}`) .onClick(() => { this.count++; }) } } @Entry @Component struct ParentComponent { @State count: number = 0; build() { Column() { ChildComponent({ count: $count }) Text(`父组件计数: ${this.count}`) .fontSize(20) } } }

注意一个语法细节：父组件传参给 @Link 时，必须用$符号，写成ChildComponent({ count: $count })。这是 @Link 和 @Prop 在调用方式上最直观的区别。$的本质是创建一个引用传递给子组件，而不是传值。

这个"双向同步"的能力，在需要多个组件共享同一份数据的场景下非常强大。比如一个设置页面，父组件控制开关状态，多个子组件都要读取并修改它，用 @Link 就省去了层层回调的麻烦。

但也有一个对应的问题：双向绑定会让数据流变得难以追踪。当你的页面有七八个 @Link 关联到同一个状态时，任何一个组件里改了这个值，所有关联组件都会刷新。出了 bug 排查起来相当头大。我现在的习惯是：能不用 @Link 就不用，必须用时，提前约定好数据流向。

2.4 一份很直接的选型对比

我把常用的对比项放在表格里，做技术选型的时候对照着看就行：

这张表我建议你存下来，每次封装组件之前问自己三个问题：这个数据是本组件独有还是外部传入？子组件需要回写吗？数据被多少组件共享？答案自然会把选型指向某一个装饰器。

3. 实操过程：一个完整的父子组件状态同步示例

3.1 从封装一个表单输入组件开始

光讲概念容易懵，我拿一个真实场景来演示：封装一个带校验功能的输入框组件，父页面用它接收用户输入的用户名和密码，并且实时显示校验结果。

这种场景特别适合演示 @Prop 和 @Link 的配合，因为输入框组件本身需要控制内部的一些状态，同时又要把用户输入的内容同步回父页面。

先看子组件：

@Component export struct ValidInput { // 从父组件传入的标签文字 @Prop label: string; // 和父组件共享输入内容，实现双向同步 @Link value: string; // 组件内部状态：当前是否聚焦 @State isFocus: boolean = false; // 组件内部状态：校验错误信息 @State errorMsg: string = ''; private validate(text: string): string { if (!text) { return '内容不能为空'; } if (text.length < 6) { return '长度不能少于6位'; } return ''; } build() { Column() { Text(this.label) .fontSize(14) .fontColor('#666666') TextInput({ text: this.value }) .onFocus(() => { this.isFocus = true; }) .onBlur(() => { this.isFocus = false; // 失去焦点时做校验，错误信息只影响组件内部 this.errorMsg = this.validate(this.value); }) .onChange((newText: string) => { // 关键步骤：修改 @Link 变量，父组件会自动同步 this.value = newText; }) .border({ color: this.isFocus ? '#007DFF' : '#E5E5E5', width: 1 }) if (this.errorMsg !== '') { Text(this.errorMsg) .fontSize(12) .fontColor('#FF0000') } } .alignItems(HorizontalAlign.Start) .width('100%') } }

这个组件里，三个装饰器各司其职：

• label用 @Prop，父组件传什么就显示什么，子组件不会去改它。
• value用 @Link，用户在 TextInput 输入的内容实时同步到父组件，父组件如果程序化修改 value，输入框也会跟着变。
• isFocus和errorMsg用 @State，这两个状态纯粹属于输入框组件自己，外部不需要感知，也不应该被外部修改。

再看父组件怎么用：

@Entry @Component struct RegisterPage { @State username: string = ''; @State password: string = ''; @State isValid: boolean = false; build() { Column() { ValidInput({ label: '用户名', value: $username }) ValidInput({ label: '密码', value: $password }) Button('提交') .enabled(this.isValid) .onClick(() => { // 这里拿到的 this.username 和 this.password 已经是最新值 console.info(`开始提交: ${this.username} / ${this.password}`); }) if (this.username !== '' && this.password !== '') { Text(`当前输入: ${this.username} - ${this.password}`) .fontSize(14) } } .padding(24) } }

注意这里有个细节：ValidInput({ value: $username })用了$，而label参数是普通传值。这段代码跑起来你会发现，每敲一个字符，Text 里的内容都会实时变化，不需要任何额外的事件处理。这就是 @Link 的响应式威力。

3.2 数组和对象：为什么改了内容 UI 却没反应

这是新人最容易崩溃的场景。比如你有这样一个 @State 数组：

@State list: string[] = ['鸿蒙', 'ArkTS']; build() { Button('添加元素') .onClick(() => { this.list.push('状态管理'); }) List() { ForEach(this.list, (item: string) => { ListItem() { Text(item) } }) } }

表面上看起来，push确实往数组里加了数据，但 UI有时候不刷新，或者刷新不完整。原因是：@State 默认只能观察到数组本身的赋值操作，以及数组方法的调用（如 push、pop、splice 等），但深度嵌套的层级变化不一定能捕获。

我遇到的实际问题是：当数组里的元素是对象时，修改某个对象的属性，UI 完全不响应。比如：

@State userList: UserInfo[] = []; // UserInfo 有 name, age, address 等属性 this.userList[0].name = '新的名字'; // 这种写法，UI 很可能不刷新

这不是偶然的，而是 ArkTS 状态观察机制的限制。解决办法有两个方向：

第一个方向：给数组整体赋值一个新的实例，而不是就地修改。因为整体赋值一定能被 @State 捕获：

// 先拷贝一份，修改后再整体赋值 let newList = this.userList.map((item, index) => { if (index === 0) { return { ...item, name: '新的名字' }; } return item; }); this.userList = newList;

第二个方向：对复杂的嵌套数据使用 @Observed 和 @ObjectLink，让类的属性级变化也能被观测。

3.3 处理深度嵌套的数据结构：@Observed/@ObjectLink 补位

当数据是嵌套的类对象时，@State 和 @Prop 的观测能力是不够的。官方提供的方案是 @Observed 和 @ObjectLink。

@Observed class AddressInfo { province: string = ''; city: string = ''; } @Observed class UserInfo { name: string = ''; address: AddressInfo = new AddressInfo(); } @Component export struct UserCard { @ObjectLink user: UserInfo; build() { Column() { Text(this.user.name) Text(`城市: ${this.user.address.city}`) Button('修改城市') .onClick(() => { // 加了 @Observed 之后，这种深层次属性修改能被捕获 this.user.address.city = '深圳'; }) } } }

@ObjectLink 必须搭配 @Observed 使用，且它只能装饰被 @Observed 修饰的类实例。这就像给对象内部装了监听器，任何一级属性变化都能触发刷新。

这里的经验教训是：永远不要在项目里大量使用多层嵌套的普通对象加 @State。数据模型设计阶段就应该把需要响应式的数据定义成 @Observed 的类，否则后期为了刷 UI 各种拷贝数组、手动触发更新，代码会烂得很快。

3.4 参数选择：为什么我把状态提升到页面级

还是上面那个表单例子，你可能发现了：username和password是定义在页面组件里的，而不是每个输入框组件自己内部。这就是状态管理一个非常重要的设计原则：状态提升（Lifting State Up）。

为什么不能把用户名密码直接放在输入框内部？因为提交按钮需要读取这两个值。如果存在子组件里，父组件拿不到，又要通过事件回调一层层传回来，非常麻烦。谁需要数据，数据就放到谁那儿。两个输入框共享的数据（用户名密码）属于页面级状态，放在页面组件里；输入框的聚焦状态、错误提示只属于输入框自己，放在子组件里。这样数据边界清晰，调试也容易。

4. 踩坑实录：我遇到过的典型问题与排查思路

4.1 @Prop 的"值拷贝"导致的子组件更新陷阱

之前做一个详情页，有个自定义 TabBar 组件，高亮索引通过 @Prop 传入。页面滑动切换 Tab 时，逻辑上要改变高亮位置。结果发现一个诡异现象：滑动后 TabBar 的内部索引变了（打印日志发现变了），但 UI 没有刷新高亮。

排查了很久才发现，我在子组件里把 @Prop 声明成了普通变量再进行赋值，然后又试图通过修改本地变量来强制刷新 UI。@Prop 的值拷贝机制导致本地修改和父组件传入的数据脱节。最终的解决方案是：把高亮索引改成 @Link，从父组件控制数据源，子组件只负责展示和触发修改。这个坑让我明白：@Prop 更适合纯展示型数据，凡是需要"父子联动"的场景，优先考虑 @Link。

4.2 @Link 类型不匹配导致的运行时错误

@Link 有一个很严格的要求：传入变量的类型必须和 @Link 声明的类型完全一致。注意是"完全一致"，不是"结构兼容"。

我曾经把一个number类型的 @State 传给一个@Link num: number | undefined的子组件，编译不报错，但运行到页面渲染时直接崩溃，报错信息大概是"@Link property type does not match"。因为父组件传的是确定值，子组件声明的是可空类型，两者的初始化和观察机制不匹配。

排查方法也很土：把子组件里的类型改成和父组件一模一样，什么联合类型、可选类型，一律别用在 @Link 上。如果确实需要处理空值，在子组件内部用一个普通变量做空值兜底，而不是直接改 @Link 的类型声明。

4.3 循环渲染 ForEach 里的状态隔离问题

ForEach 渲染列表项时，如果列表项的组件里用了 @State，你会踩一个特别隐蔽的坑：列表项复用时的状态互相污染。

比如动态列表里每一项有一个"展开/收起"的按钮，点击展开当前项。如果你把这个展开状态声明成 @State，这个状态是跟着组件的实例走的。在 ArkUI 的列表机制里，当列表滚动、数据更新时，列表项组件实例可能会被复用，实例上的 @State 状态就会带到下一个数据项上。结果就是：你展开了第一项，往下滚两屏再回来，第一项居然还是展开的，或者别的项莫名其妙也展开了。

我的经验是：列表项的展开、选中、编辑态，全部提升到列表数据对象里，通过 @Prop/@Link 传入子组件，不要在列表项内部用 @State 存"跟具体数据相关的状态"。列表项组件的 @State 只用来存焦点、动画这些纯 UI 相关的临时状态。

4.4 页面转场后状态丢失

有两个页面：A 是列表页，B 是详情页。在 B 页面里，我通过 @Link 修改了列表项的标题，返回 A 页面时，列表竟然没有变化。这又是怎么回事？

根本原因在于：页面路由栈中，A 页面和 B 页面不在同一个组件树层级。页面间传参不能直接用 @Link，页面路由传参本质上是"一次性的值传递"。B 页面修改的 @Link 数据，只活在 B 页面的组件树里，跟 A 页面没有任何关系。

正确的做法是：页面间需要共享的数据，放到全局的 AppStorage或LocalStorage里。这不是这三个装饰器的能力范围，但遇到"页面跳转后数据不互通"的问题时，不要纠结 @Link，果断用 AppStorage 来管理跨页面状态。我在项目里常用的模式是：

// 全局存储 AppStorage.SetOrCreate('globalUserInfo', new UserInfo()); // 任意页面读取 @StorageLink('globalUserInfo') userInfo: UserInfo = new UserInfo(); // 任意页面修改 this.userInfo.name = '新的名字';

只要页面组件用了@StorageLink('key')绑定同一个 key，修改就能跨页面同步。这个方案用来管理登录态、用户信息、全局配置非常稳。

4.5 多个 @Link 共享状态的竞态踩坑

当一个变量被多个子组件用 @Link 共享，而且多个子组件在同一帧事件里同时修改它时，会出现"最后一次赋值覆盖前面赋值"的竞态现象。

我做过一个拖拽排序的页面，左右两个面板都绑定同一个 @Link 列表。左边往右边拖一个元素时，左边删、右边加，两个操作几乎同时触发，结果数据错乱，元素要么消失要么重复。

排查后发现是：两个 @Link 引用同一个数组，左侧删操作和右侧加操作都直接修改了原数组引用，框架刷新时序不确定。最终方案是：让操作独占化，用一个状态锁变量，或者把所有修改集中到父组件的一个方法里处理，不要让两个子组件直接同时操作同一个 @Link。这也是我为什么反复强调：@Link 虽方便，但使用时要时刻记住"数据流可追踪性"，修改越集中，bug 越少。

4.6 状态更新导致的卡顿问题

这个不算 bug，但是性能优化里很常见：一个 @State 变量被过度共享，导致无意义的全页面刷新。

比如页面上有个时间戳，每秒钟变一次，如果这个时间戳被顶层组件 @State 持有，并且传给很多个不依赖时间的子组件，那么每一秒所有依赖它的组件全部重新渲染。页面一复杂，明显掉帧。

ArkTS 的响应式是细粒度的，理论上只有读取了该变量的组件才会刷新。但实际操作中，因为组件树层次深、@Prop 层层透传，你会不自觉地让很多中间组件"被动读取"了时间戳。我后来做了优化：把高频变化的数据隔离在一个专门的组件里，只让真正需要它的少量组件订阅，不要从页面顶层一路传到底。高频状态往下分发要谨慎，低频的配置数据可以随便传。

5. 状态管理的进阶设计思路

5.1 划分状态层级，别让局部状态"升天"

我见过一个项目，页面里几乎所有数据都定义在 @Entry 组件上，子组件全部 @Link 直连。代码看起来简单粗暴，但页面稍微大一点，一个状态改动牵动 20 多个组件刷新，性能直接崩。

正确的思路是，把状态划分成三个层级：

• 页面级状态：影响整个页面的数据，比如列表数据、筛选条件、用户操作结果。
• 组件级状态：只影响单个组件及其子组件，比如弹窗显隐、Tab 索引、组件内部动画。
• 全局级状态：跨页面共享，比如登录态、主题配置。

状态能放在组件内部，就不要提升到页面级；能放在页面级，就不要放到全局级。这样做的好处是：状态变更的影响范围可控，排查问题时能快速定位。

5.2 数据流向要"单向优先，双向兜底"

虽然 @Link 很好用，但我在项目里逐渐养成一个习惯：组件间优先用 @Prop 加回调事件来实现单向数据流，只用 @Link 处理真正需要实时双向同步的场景。

什么意思呢？比如一个子组件里有个删除按钮，删除操作会改父组件的列表数据。用 @Link 的话，子组件直接操作共享数组；用回调事件的方式，则是子组件this.onDelete(), 父组件收到事件后统一修改数据。

两种方式都能实现效果，但后者的好处是：数据修改的代码集中在父组件，逻辑清晰，出了问题一眼就能看到是谁改的。尤其是多人协作的项目里，代码可读性比代码简洁重要得多。

5.3 使用 @Builder 和自定义组件封装时特别要注意装饰器传递

用@Builder封装一段 UI 逻辑时，状态传递的方式和自定义组件不太一样。@Builder参数默认是值传递，如果参数里有 @State 组件，要想让 @Builder 内部响应数据变化，需要做到按引用传递：

@Builder function renderTextBuilder($$: { text: string }) { Text($$.text) } @Entry @Component struct IndexPage { @State message: string = 'hello'; build() { Column() { renderTextBuilder({ text: this.message }) } } }

注意$$的写法，这是 @Builder 的按引用传递标记。如果不写$$，参数就是值拷贝，父组件 data 变了，@Builder 里不会同步。这个细节特别容易踩，而且在官方文档里不太起眼。

5.4 从服务端拿到的数据模型怎么接入状态体系

接口返回的 JSON 数据，通常是深嵌套的普通对象。直接塞给 @State，你会发现修改嵌套属性不刷新 UI。

我的标准做法是：定义 @Observed 的模型类，把接口数据映射成类实例。虽然多一步转换，但换来的是全链路响应式。如果你嫌麻烦，也可以采用"整体赋值 + 不可变更新"策略：每次服务端数据变更，重新组装一个全新的对象整体赋值给 @State。这两种方案都能跑，看你项目对实时交互的要求高不高。

6. 最后分享几个调试状态的小技巧

调试状态管理相关问题，我平时会用几个很土但很有效的方法：

第一，在关键状态变更处打印日志。不要小看这个笨办法，配合console.info的日志过滤，你很快能定位数据是在哪个环节变的。ArkTS 里也可以直接打印对象结构，JSON.stringify(this.someObj)很方便。

第二，打开 DevEco Studio 的 ArkUI Inspector 工具，查看实时组件树和绑定状态。它会显示当前页面组件的层级关系，还能看到组件绑定的属性值，排查 UI 不刷新问题时非常直观。

第三，把状态变更收敛到方法里，不要散落在各个 onClick 里。我习惯在每个页面组件里定义一个updateState方法，所有涉及状态修改的逻辑都走这个方法。这样一来，一旦状态异常，打断点只需要看一个方法。

第四，利用 DevEco Studio 的断点调试。ArkTS 的响应式更新是框架自动触发的，你可以在变更状态的那一行打断点，一步步看数据如何传递，比凭空猜高效得多。

我对 @State/@Prop/@Link 的理解，总结成一句话：它们是 ArkTS 数据驱动的基石，但用好的关键不在于记住语法，而在于想清楚数据的归属和流向。状态放在该放的地方，流向保持清晰简单，页面再复杂也不容易乱。希望这篇文章能帮你少踩几个我踩过的坑。