一、开篇：ArkTS 不是“换了个框架的 TypeScript”

从 Web 前端或 React Native 转到鸿蒙 ArkTS 的开发者，通常会经历一个相似的曲线：第一周觉得“语法差不多，很快能上手”，第二周开始遇到“数据变了但 UI 不动”，第三周发现长列表滚起来像幻灯片，一个月后开始怀疑自己到底会不会写声明式 UI。

问题的根源不在于某几个 API 没记住。ArkTS 表面上保留了 TypeScript 的语法外形，但它的运行时模型、更新机制和并发模型与 Web 前端有结构性差异。ArkTS 是 TypeScript 的严格子集外加 UI 装饰器扩展，它的核心约束不是“少几个语法糖”，而是为了让 ArkCompiler 做 AOT 编译——一切运行时不可静态分析的特性都被禁掉。这意味着 any、动态索引、解构赋值、eval、@ts-ignore 这些在前端随手就用的东西，在 ArkTS 里从语言层就不存在。

这篇文章不打算罗列 API 清单。它按开发者真实遇到问题的顺序，从语言层、状态层、渲染层、并发层、原生层、架构层六个维度展开，每一层都回答同一个问题：你从前端带来的哪些默认假设，在 ArkTS 里是错的，以及为什么错、怎么改。

二、语言层：严格类型不是建议，是编译前提

2.1 被禁掉的不是“语法糖”，是运行时的动态性

ArkTS 与 TypeScript 的差异，最容易被低估的是类型系统从“可选约束”变成了“编译前提” 。TypeScript 的 any 是一个逃生舱口，允许你在不确定类型时先让代码跑起来；ArkTS 里 any 和 unknown 被完全禁用，对象字面量必须先声明 class 或 interface 才能使用，索引签名 {[k:string]:T} 不被支持，动态访问 obj['key'] 仅在 Record 或 Map 上合法。

这些限制的直接后果是迁移不是“改几个类型声明”，而是重新设计数据边界。一个在 TypeScript 里用 any 接收后端响应、再按字段动态取值的 Service，在 ArkTS 里必须显式定义响应模型，用 as 或判空来处理 .find() 可能返回的 undefined。这不是“鸿蒙麻烦”，而是 ArkTS 不允许你把类型不确定性留到运行时——因为 AOT 编译需要静态可分析的调用图。

实用策略：迁移时先把所有 any 标注为“待建模”，用 unknown 接收原始响应，然后在边界处用显式的 interface 做一次转换和校验。不要把 any 简单替换成 Object 或 Record<string, any> 来“通过编译”，那只是把运行时错误推迟到了更难排查的地方。

2.2 解构和动态属性的缺失，逼你改变写法

ArkTS 不支持解构赋值（部分场景），不支持 delete obj.key，不支持 for...in，不支持一元 + 转数字。这些限制在写业务代码时会频繁遇到：从对象里取几个字段、删除一个可选属性、遍历键名。

正确的适应方式不是找“替代语法”，而是把数据操作收敛到明确的函数或类方法里。取字段就一行一行赋值，删属性就重建对象或设 null，遍历用 Object.keys() 返回数组再 for...of。这些写法在 TypeScript 里显得“啰嗦”，但在 ArkTS 里是让编译器能静态确定对象形状的必要代价。

三、状态层：变量级订阅，不是虚拟 DOM 对比

3.1 核心机制差异：ArkUI 不做整树 Diff

React 的心智模型是“状态变了 → 重新执行组件函数 → 生成新虚拟树 → 与旧树 Diff → 更新真实 DOM”。ArkUI 的机制不同：它在编译期就建立了状态变量与 UI 节点之间的依赖关系，状态变更时直接定位到依赖该变量的节点，只更新那部分。ArkUI 的更新代价只和真正依赖该变量的 UI 节点数量相关，避免了创建和对比整棵虚拟 DOM 树的成本。

这意味着两件事。第一，状态的作用域直接决定更新代价。把一个包含上万条数据的数组放在父组件的 @State 里，任何一条数据的任何字段变化，都可能触发父组件 build() 的重新执行，连带所有子组件重算。这不是“框架慢”，而是你把依赖关系建在了过大的粒度上。第二，状态装饰器的选型不是“风格问题”，是更新粒度的设计问题。

3.2 @Prop 的深拷贝代价：一个被低估的性能陷阱

@Prop 的语义是“父到子的单向同步”，子组件拿到的是父状态的一份副本。问题在于 @Prop 对复杂对象执行的是深拷贝。如果子组件只是展示数据、并不修改它，这个深拷贝就是纯开销，而且对象越大、层级越深，组件创建时间越长。

华为官方的最佳实践明确给出了替代方案：子组件不需要修改父状态时，优先使用 @ObjectLink 而不是 @Prop，因为 @ObjectLink 不会深拷贝，它持有的是对 @Observed 对象的引用。一个典型的误用场景是列表项组件用 @Prop 接收一个对象模型，父组件每次数据更新都触发一次深拷贝，列表项越多、对象越复杂，卡顿越明显。改成 @ObjectLink 配合 @Observed，拷贝开销直接消失。

但 @ObjectLink 不是无条件更优。它要求对象被 @Observed 装饰，且观察粒度是对象级的——修改对象的任何一个属性，依赖该对象的 UI 都会刷新，即使只改了一个字段。如果需要字段级的精确更新，状态管理 V2 的 @ObservedV2 + @Trace 才是正确的工具。

3.3 V1 与 V2 不能混用：迁移必须是“整条数据链”级别的

状态管理 V2 引入了 @Local、@Param、@Event、@ObservedV2、@Trace 等一套新装饰器，语义更清晰、观察粒度更细。但从 V1 迁移到 V2 有一个硬约束：V1 和 V2 是两套独立的状态系统，默认互不观察，不能在同一条父子组件链上混用。

最常见的踩坑方式是“只把父组件的 @State 改成 @Local，子组件还是 @Prop”，结果数据变了但子组件不刷新。正确的做法是以一条完整的数据链为单位迁移：父组件和它传递数据的所有子组件一起切到 V2，中间不混用。@Link 不能直接换成 @Param——@Param 是只读的，双向绑定需要配 @Event。

对于大型应用，官方建议分批次、分组件逐步迁移，但同一个数据链路上的组件必须一起迁。不要试图在一个页面里一半 V1 一半 V2，订阅链断裂后的表现是“数据变了但 UI 不动”，排查成本极高。

四、渲染层：长列表的“该变的变，不该变的不变”

4.1 ForEach 一次性建完所有节点，是长列表卡顿的第一因

ForEach 在组件挂载时会一次性创建全部子节点。一万条数据意味着首屏就要构建上万个 item 组件实例，UI 线程被长时间占用，结果是白屏一到两秒、滚动掉帧、内存随滚动持续上涨。

LazyForEach 配合实现了 IDataSource 的数据源，只构建当前视口加缓冲区内的组件，滚动时按需“上屏/下屏”，视口外的节点被销毁或回收。这是长列表的第一道优化，但它的收益是条件收益：只有当数据变化时只通知变化的那部分，已经渲染的节点才不会被作废。如果分页追加时调用 notifyDataReload() 做全量重载，懒加载省下来的创建开销会在每次翻页时被原样还回去，表现为“平时丝滑、翻页必卡”。

正确的数据通知方式是增量操作：追加用 notifyDataAdd，更新单条用 notifyDataChange，删除用 notifyDataDelete。让框架只处理真正变化的那一段，而不是整批重建。

4.2 @Reusable 复用的是组件实例，不是数据

@Reusable 让滑出屏幕的组件实例进入复用池，新数据进屏时直接复用，省去 build() 的重建成本。但复用的只是组件实例，状态变量不会自动回到初值，aboutToAppear 也不会再触发。凡是“数据里没有、但 UI 上会变”的东西——展开态、选中态、动画进度、输入框内容——如果不显式处理，就会从上一张卡片“串”到下一张卡片上。

正确做法是在 aboutToReuse 生命周期里把所有 UI 状态重置为基于新数据的初始值。不要把复用理解成“白捡了一个组件”，它是一份需要你手动清理的“二手状态”。

4.3 Key 的稳定性决定节点是复用还是重建

Diff 算法通过 key 来判断节点身份。用索引作为 key，删除第一项后所有后续项的索引都变了，框架认为它们全是新节点，会销毁旧组件并重建——输入框里用户已经输入的内容会丢失，展开态会重置。key 必须是稳定的业务唯一标识，不是数组下标，也不是会变化的字段。这不是“最佳实践建议”，是 Diff 正确工作的前提。

4.4 V2 体系下用 Repeat 替代 LazyForEach

在状态管理 V2 体系中，官方推荐使用 Repeat + .virtualScroll() 替代 LazyForEach。Repeat 自身默认具备组件复用能力，API 更简洁，不需要额外维护 IDataSource 实现和 @Reusable 装饰器。如果项目已经在 V2 体系下，新列表页优先用 Repeat；存量 V1 列表可以在迁移到 V2 时一并替换。

五、并发层：TaskPool 是默认答案，Worker 是例外

5.1 两种并发模型的定位差异

TaskPool 和 Worker 都基于 Actor 消息模型，但 TaskPool 在 Worker 之上实现了调度器和 Worker 线程池，开发者不需要管理线程生命周期。TaskPool 根据任务数量和优先级自动扩容缩容，任务结果以 Promise 形式返回主线程；Worker 则需要手动创建、复用和销毁，每个 Worker 有独立的运行环境、消息队列和事件循环。

选型的核心判断不是“任务长短”，而是“任务是否需要保持线程状态” 。一次性 JSON 解析、图片处理、加密解密、数据库查询后的数据加工，全部走 TaskPool；需要长期驻留、反复接收消息的长连接或定时轮询，才用 Worker。超过 3 分钟的单个计算任务可以用 TaskPool.LongTask 或 Worker，但Worker 本身不等于后台任务，真正的后台持续运行需要结合 BackgroundTasks Kit。

5.2 Sendable：大数据跨线程传递的分界线

默认的结构化拷贝在跨线程传递大对象时开销显著。@Sendable 对象通过共享堆实现引用传递，官方数据表明 100KB 数据用 Sendable 跨线程传递的效率约为序列化拷贝的 20 倍，1MB 数据约为 100 倍。但 Sendable 的收益随数据量放大，小对象反而看不出差别，选型分界线一般在“单次传递超过 1 万条或 1MB”这个量级。

常见的误用是以为 Sendable 会让任务本身变快。@Sendable 解决的是对象可在线程间共享/传递的约束，不意味着一次 TaskPool 调度比主线程同步循环更快。任务创建和调度本身有开销，把任务做粗、批量处理，比把一个小循环拆成很多 task 更划算。

5.3 UI 对象和 @Local 不能进子线程

子线程只应该做计算和 IO，不要传 @Local、UI 对象或带方法的状态对象进子线程。子线程返回纯数据，UI 的更新在主线程完成。这条边界如果模糊，会带来难以排查的竞态和刷新异常。

六、原生层：系统能力接入的“生命周期”比 API 签名更重要

6.1 连续扫码：rescan 是硬约束，不是可选项

Scan Kit 的默认扫码界面一次只返回一个结果，适合登录和绑定。流水线式的连续扫码必须用 customScan 自建预览，并且在 start 的回调中调用 customScan.rescan() 触发下一帧。反复 stop 再 start 会触发错误码 7400201（相机服务异常），甚至页面卡死；rescan 也只在 start 的回调中生效，Promise 方式调用无效。

连续扫码的另一个必答题是去重。同一张码在视口内停留时，相机以约 30fps 持续识别，回调会反复触发。华为社区推荐 “内容 + 位置 + TTL”三维联合去重：ScanResult.scanCodeRect 提供码在画面中的外接矩形，用“内容 + 量化后的位置中心点”作为去重键，TTL 取 2000–3000ms；位置信息缺失时降级为纯内容去重。只靠“内容 + 时间窗”会把“同一商品多件连续扫码”误判为重复，去重策略必须区分“同一张码的重复回调”和“用户真的扫了两次同内容码”。

6.2 蓝牙打印：指令层与分包写入是两个独立问题

BLE 打印的失败通常不在“连不上”，而在“连上了但打不出来”。指令层有三个跨平台通用的硬约束：CPCL 指令必须以 \r\n 结尾，否则打印机不走纸；中文内容必须用 GBK 编码，UTF-8 会输出乱码；写入必须是字节数组，字符串直传在部分平台静默失败。

分包写入是另一个问题。BLE 的 MTU 决定了单次可写负载的上限，大数据量打印必须分包。自研 GATT 封装时要按协商后的 MTU 减去 ATT 头来计算分包大小，并等上一次写入的完成回调后再发下一包，不能连续快速写入冲垮打印机缓冲区。鸿蒙生态中已有厂商 SDK 提供 enableChunkWrite 和 chunkSize 配置来处理分包，并内置 GBK 转换，打印机型号在支持范围内时优先用 SDK，比从零封装 GATT 更稳。

七、架构层：先定模块边界，再谈代码复用

7.1 HAR、HSP、HAP 的选择是“代码在包里出现几份”的问题

Stage 模型下，HAP 是能力入口，HAR 是静态共享库（编译期打包进使用方），HSP 是动态共享库（运行时共享一份）。选择的实质是公共代码在最终安装包里出现一份还是 N 份。

务实的拆分策略是 “默认 HAR，少量 HSP，谨慎多 HAP” ：业务内的静态复用（基础 UI 组件、工具函数、数据模型）优先 HAR；只有多个 HAP 确实需要在运行时共享同一套稳定公共能力时才上 HSP。HSP 的问题是版本依赖——不要把变化频繁的业务页面逻辑放进 HSP，否则每次改动都影响所有依赖方。应用间共享的 HAR 原则上不允许依赖 HSP，这条依赖规则如果破坏，包管理和加载时序都会出问题。

7.2 模块化不是为了“看起来整齐”，是为了编译边界和团队协作

官方模块化最佳实践的立论起点是团队协作：多团队开发时通过契约化接口定义业务之间的交互，而不是靠“大家不要互相引用”的口头约定。模块拆分如果只做了目录隔离、没有做依赖约束，最终会退化成“一个大 HAP 里分了几个文件夹”，编译时间和耦合度都不会改善。

八、性能诊断：先定位是 UI 线程、渲染线程还是计算，再改代码

8.1 DevEco Profiler 的 Frame 模板是卡顿定位的起点

DevEco Profiler 的 Frame 场景专门用于分析卡顿丢帧，关注 Lost Frames 和 Hitch Time 泳道，可以区分是 UI 线程的组件创建慢、布局计算重，还是渲染线程的绘制指令提交慢。关键限制是：必须用真机 + Debug 包，模拟器不采集 ArkTS Callstack 和 Snapshot 数据。

8.2 排查顺序：先排除“非 UI 线程的同步计算”

卡顿的第一嫌疑往往不是渲染本身，而是主线程上执行了本应放进 TaskPool 的同步计算——大 JSON 解析、批量数据转换、加密、复杂字符串处理。先用 Profiler 的 ArkTS Callstack 确认丢帧区间内主线程在做什么，再决定是“改渲染”还是“搬计算”。把计算搬进 TaskPool 之后仍然卡，才需要检查 LazyForEach、@Reusable、key 稳定性和状态作用域。

8.3 布局性能的真正变量是节点数量

ArkUI 的布局性能与“平铺还是嵌套”关系不大，参与布局的节点数量才是线性劣化的驱动因素。与其纠结“用 Row 还是 Flex”，不如先减少不必要的包装节点、把长列表的 item 做薄、把大对象拆分成多个小组件以缩小状态更新的波及范围。

九、避坑清单

坑1：用 Record<string, any> 绕过 any 禁令。 编译过了，但对象形状在运行时仍然不可控，AOT 优化收益丢失，错误被推迟到更难排查的位置。正确做法是显式定义 interface。

坑2：子组件用 @Prop 接收只读的大对象。 每次父状态更新都触发深拷贝，列表项越多越慢。子组件不修改父状态时改用 @ObjectLink。

坑3：V1 和 V2 在同一条父子链上混用。 表现为“数据变了但 UI 不动”，排查成本极高。迁移以完整数据链为单位，不半迁半留。

坑4：分页追加调用 notifyDataReload()。 全量重载让 LazyForEach 的懒加载收益归零，每次翻页都整批重建。用增量通知。

坑5：@Reusable 不复位 UI 状态。 展开态、选中态、输入内容从上一张卡片串到下一张。在 aboutToReuse 里显式重置。

坑6：连续扫码用 stop/start 代替 rescan。 触发 7400201 相机服务异常。回调里只做业务处理，然后 rescan()。

坑7：把 @Local 或 UI 对象传进 TaskPool 子线程。 线程安全边界被打破。子线程只传纯数据，UI 更新回主线程。

十、总结

ArkTS 开发的认知重构，可以浓缩为六层：

语言层，严格类型不是建议，是编译前提——any、动态索引、解构的缺失要求你重新设计数据边界，而不是找语法替代品。状态层，变量级订阅意味着状态作用域直接决定更新代价，@Prop 的深拷贝和 V1/V2 的不可混用是两个必须绕开的陷阱。渲染层，长列表的流畅度取决于“增量通知 + 组件复用 + 稳定 key + 状态下沉”四件事的配合，任何一环缺失都会让其他优化归零。并发层，TaskPool 是默认答案，Worker 是“需要保持线程状态”时的例外，Sendable 的收益在数据量超过 1MB 时才显著。原生层，rescan 和分包写入的完成回调是生命周期约束，不是可选的优化项。架构层，HAR/HSP 的选择是“代码出现几份”的工程决策，模块化的价值在编译边界和团队契约，不在目录整齐。

> 本文作者：深圳＋Eyf•半字节科技▪技术产品团队
> 物流、快递、快运作业管理系统，让每一票，都清晰可控。从任务分配到签收回传，一站式管理每个作业环节。

你在 ArkTS 开发中卡得最久的问题是状态不刷新、列表卡顿，还是原生能力的生命周期？欢迎在评论区分享具体场景。