hmos-arkui-statemgt-migration

name	hmos-arkui-statemgt-migration
description	帮助开发者将ArkUI状态管理从V1迁移到V2。触发场景：(1) V1项目升级到V2；(2) 迁移@Component/@State/@Prop/@Link/@Observed/@ObjectLink/@Provide/@Consume/@Watch/@Reusable装饰器；(3) 迁移LocalStorage/AppStorage/PersistentStorage/Environment应用级状态；(4) 将ForEach/LazyForEach迁移到Repeat；(5) 解决animateTo在V2中的兼容问题；(6) 处理V1与V2混用场景；(7) 询问V1和V2装饰器对应关系或差异。

状态管理 V1-V2 迁移

核心迁移映射

组件装饰器

V1	V2	说明
@Component	@ComponentV2	组件装饰器
@State	@Local / @Param @Once	内部状态；需外部初始化用@Param @Once
@Prop	@Param	父→子单向传递；V2的@Param只读，@Param需要给初始值
@Link	@Param + @Event	双向同步需手动实现
@Observed	@ObservedV2	标记可观察类
@ObjectLink	@ObservedV2 + @Trace	深度观测嵌套对象
@Track	@Trace	属性级精确观测
@Provide/@Consume	@Provider/@Consumer	跨组件状态共享
@Watch	@Monitor	状态变化监听
@Reusable	@ReusableV2	组件复用
无	@Computed	计算属性（V2新增）

详细迁移示例参考：references/arkts-v1-v2-migration-inner-component.md

应用级状态

V1	V2	说明
LocalStorage	@ObservedV2 + @Trace 单例	页面间状态共享
@LocalStorageLink	@Local + 单例引用	双向同步LocalStorage数据
@LocalStorageProp	@Local + @Monitor	单向接收，本地修改不同步
AppStorage	AppStorageV2+@ObservedV2+@Trace`提供存储单例	+跨Ability状态共享
AppStorage.setOrCreate	AppStorageV2.connect()+借助类传递变量	创建共享状态
@StorageLink	AppStorageV2.connect() + @Local 需要借助类	双向同步AppStorage数据
@StorageProp	@Local + @Monitor需要借助类传递	单向接收，本地修改不同步
PersistentStorage	PersistenceV2	持久化存储
Environment	UIAbilityContext.config	系统环境变量

详细迁移示例参考：references/arkts-v1-v2-migration-application.md

渲染控制

V1	V2	说明
ForEach	Repeat	全量加载循环渲染
LazyForEach	Repeat + .virtualScroll()	懒加载循环渲染
$$	!!	双向绑定语法糖

详细迁移示例参考：references/arkts-v1-v2-migration-rendering-control-repeat.md

核心差异

特性	V1	V2
观测深度	@State可观测第一层属性	@Local只观测本身，需@ObservedV2+@Trace深度观测
初始化	@State支持外部初始化	@Local禁止外部初始化，需用@Param @Once
双向绑定	@Link内置双向同步	无内置，需@Param+@Event手动实现
参数传递	@Prop可本地修改	@Param只读，修改需@Once或@Event

迁移工作流程

阶段一：环境准备

1. 版本检查 - 确认API版本≥12，低于api12需先升级版本
2. 依赖评估 - 确认三方库兼容性
3. 备份代码 - 创建迁移前备份分支

阶段二：代码分析

1. 扫描装饰器 - 使用grep扫描@Component|@State|@Prop|@Link|@Observed|@ObjectLink|@Provide|@Consume|@Watch|@Reusable|@StorageLink|@StorageProp|@LocalStorageLink|@LocalStorageProp
2. 识别组件 - 列出所有使用V1装饰器的组件文件
3. 分析依赖 - 识别组件间的父子关系和数据流向
4. 生成清单 - 按文件生成迁移清单

阶段三：制定计划

1. 优先级排序 - 叶子组件优先，逐层向上迁移
2. 批次划分 - 按功能模块分批次迁移
3. 风险评估 - 识别混用风险点

阶段四：执行迁移（按类型顺序）

4.1 组件装饰器迁移

@Entry保持不变
@Component → @ComponentV2
@State → @Local
@Prop → @Param // 狐疑@Params要给初始值，或者给@Require
@Link → @Param + @Event

参考：references/arkts-v1-v2-migration-inner-component.md

4.2 数据对象迁移

@Observed → @ObservedV2
@ObjectLink → @ObservedV2 + @Trace
@Track → @Trace

参考：references/arkts-v1-v2-migration-inner-class.md

4.3 跨组件状态迁移

@Provide/@Consume → @Provider/@Consumer
@Watch → @Monitor

参考：references/arkts-v1-v2-migration-inner-component.md

4.4 应用级状态迁移

LocalStorage → @ObservedV2单例
@LocalStorageLink → @Local + 单例引用
@LocalStorageProp → @Local + @Monitor
AppStorage → AppStorageV2
@StorageLink → 参考`references/arkts-v1-v2-migration-application.md`中的storageLink迁移
@StorageProp → 参考`references/arkts-v1-v2-migration-application.md`中的storageProp迁移
PersistentStorage → PersistenceV2
Environment → UIAbilityContext.config

参考：references/arkts-v1-v2-migration-application.md

4.5 渲染控制迁移

ForEach → Repeat
LazyForEach → Repeat + .virtualScroll()

参考：references/arkts-v1-v2-migration-rendering-control-repeat.md

4.6 组件复用迁移

@Reusable → @ReusableV2

参考：references/arkts-v1-v2-migration-reusable.md

阶段五：特殊场景处理

滚动组件内置对象

List/WaterFlow的ChildrenMainSize/WaterFlowSections需用UIUtils.makeObserved()包装：

import { UIUtils } from '@kit.ArkUI';
listChildrenSize = UIUtils.makeObserved(new ChildrenMainSize(100));

参考：references/arkts-v1-v2-migration-inner-object.md

animateTo兼容

V2中animateTo前的状态修改可能不生效，需用UIUtils.applySync()：

import { UIUtils } from '@kit.ArkUI';
UIUtils.applySync(() => { this.w = 100; });
this.getUIContext().animateTo({ duration: 1000 }, () => { this.w = 200; });

参考：references/arkts-v1-v2-migration-animateTo.md

双向绑定

$$语法替换为!!

参考：references/arkts-v1-v2-migration-inner-component.md

阶段六：验证测试

1. 编译检查 - 确保无语法错误
2. 功能测试 - 验证组件交互正常
3. 性能测试 - 检查渲染性能
4. 回归测试 - 全功能覆盖验证

详细迁移指南

按迁移阶段查阅

迁移阶段	参考文档	核心内容
阶段一：环境准备	references/arkts-v1-v2-migration.md	V1/V2差异对比、API版本要求、混用规则
阶段四：执行迁移
4.1 组件装饰器	references/arkts-v1-v2-migration-inner-component.md	@State/@Prop/@Link/@Provide/@Consume/@Watch迁移完整示例
4.2 数据对象	references/arkts-v1-v2-migration-inner-class.md	@Observed/@ObjectLink/@Track → @ObservedV2/@Trace，嵌套对象观测
4.4 应用级状态	references/arkts-v1-v2-migration-application.md	LocalStorage/AppStorage/PersistentStorage/Environment完整示例
4.5 渲染控制	references/arkts-v1-v2-migration-rendering-control-repeat.md	ForEach/LazyForEach → Repeat，数据更新、拖拽排序
4.6 组件复用	references/arkts-v1-v2-migration-reusable.md	@Reusable → @ReusableV2，aboutToReuse变化
阶段五：特殊场景
内置对象	references/arkts-v1-v2-migration-inner-object.md	List/WaterFlow滚动组件、Modifier迁移、makeObserved用法
animateTo	references/arkts-v1-v2-migration-animateTo.md	V2中animateTo兼容问题、applySync用法

文档查阅建议

首次迁移：按顺序阅读所有文档，建立整体认知

快速查阅：

• 组件迁移问题 → inner-component.md
• 嵌套对象观测 → inner-class.md
• 滚动列表异常 → inner-object.md + rendering-control-repeat.md
• 动画不生效 → animateTo.md
• 状态持久化 → application.md

关键注意事项

初始值

@Param 和 @Consumer 需要有初始值：

@Consumer('navPathStack') navPathStack: NavPathStack = new NavPathStack();
@Param todo: Todo = new Todo();

无法给初始值时，使用@Require装饰器：

@Require @Consumer('navPathStack') navPathStack: NavPathStack;
@Require @Param todo: Todo;

观测能力差异

• V1的@State可观测第一层属性
• V2的@Local只观测本身，需配合@ObservedV2+@Trace实现深度观测

迁移检查清单

• @Component → @ComponentV2
• @State → @Local 或 @Param @Once
• @Prop → @Param
• @Link → @Param + @Event
• @Observed/@ObjectLink → @ObservedV2/@Trace
• @Provide/@Consume → @Provider/@Consumer
• @Watch → @Monitor
• @Reusable → @ReusableV2
• LocalStorage → @ObservedV2单例
• @LocalStorageLink → @Local + 单例引用
• @LocalStorageProp → @Local + @Monitor
• PersistentStorage → PersistenceV2
• ForEach → Repeat
• LazyForEach → Repeat + .virtualScroll()
• $$ → !!
• 滚动组件内置对象使用makeObserved
• animateTo前的状态修改使用applySync

参考资料

1、Appstorev2的使用：AppStorageV2: 应用全局UI状态存储-管理应用拥有的状态-状态管理（V2）-学习UI范式状态管理-UI开发 (ArkTS声明式开发范式)-ArkUI（方舟UI框架）-应用框架 - 华为HarmonyOS开发者