开发 HarmonyOS NEXT（API 12+）应用时…

在构建 HarmonyOS NEXT（API 12+）应用并使用 ArkTS、ArkUI、Stage 模型和分布式能力时，按严格类型、不可变状态和组件化模式开发。

适用场景

解决思路

1. 使用 ArkTS 并保持严格类型安全，不写 `any` 或动态类型。
2. 使用 ArkUI 的声明式组件和状态管理构建 UI。
3. 使用现代 Stage 模型（UIAbility），不要用旧 FA 模型（PageAbility）。
4. 从设计开始利用分布式跨设备能力。
5. 考虑原子化服务和卡片来实现轻量体验。
6. 面向手机、平板、手表、TV 做多设备适配，一次开发多端部署。
7. 禁止动态类型：不要使用 `any`、类型断言 `(someVar as SomeType).method()` 或动态属性访问 `obj['dynamicKey']`；用 `interface` 定义数据结构，用 `Record<string, string>` 处理动态键。
8. 禁止直接修改 @State/@Prop 变量，尤其嵌套对象；对象更新用 `this.user = { ...this.user, age: 26 }`，数组更新用 `this.items = [...this.items, 'c']`；不要写 `this.user.age = 26` 或 `this.items.push('c')`。
9. 仅使用 Stage 模型：用 `module.json5` 配置 abilities；用 `import { UIAbility } from '@kit.AbilityKit'` 并继承 `UIAbility`，实现 `onCreate(want, launchParam)` 和 `onWindowStageCreate(windowStage)`，在后者调用 `windowStage.loadContent('pages/Index')`；不要用 `config.json` 的 pages 数组或 `PageAbility` 生命周期。
10. 将可复用 UI 抽取为 `@Component`：不要在 `build()` 中写复杂内联 UI；把大段 UI 拆成 `UserCard` 等组件，用 `@Prop user: User` 传数据，并在父组件 `build()` 中调用 `UserCard({ user: this.user })`。
11. 按场景选择状态管理：组件本地状态用 `@State`（如 Counter、表单输入）；父传子只读数据用 `@Prop`；双向绑定用 `@Link`；跨组件状态用 `@Provide/@Consume`（如主题、用户上下文）；持久化状态用 `PersistentStorage`（如用户偏好）；应用级状态用 `AppStorage`；复杂状态逻辑用 `@Observed/@ObjectLink`（嵌套对象更新）。
12. 按状态装饰器语义选择：`@State` 组件拥有状态并在变更时触发重渲染；`@Prop` 父传值子拷贝且单向；`@Link` 父传引用子可修改且双向；`@Provide` 祖先向所有后代提供值；`@Consume` 后代消费祖先值；`@StorageLink` 与 `AppStorage` 同步且双向绑定；`@StorageProp` 与 `AppStorage` 同步且单向绑定；`@Observed` 是用于可观察对象的类装饰器；`@ObjectLink` 链接父级中的 `@Observed` 对象。
13. 按推荐架构组织项目：`entry/` 主入口模块；`src/main/ets/entryability/` 放 UIAbility 定义；`pages/` 放页面组件；`components/common/` 和 `components/business/` 放可复用 UI；`viewmodel/` 放 ViewModel（MVVM）；`model/` 放数据模型；`service/` 放业务逻辑服务；`repository/` 放数据访问层；`utils/` 放工具函数；`constants/` 放常量配置；`resources/` 放资源；`module.json5` 放模块配置；`build-profile.json5` 放构建配置。
14. 将项目拆成模块：`common/` 作为共享库模块；`features/feature_home/`、`features/feature_profile/` 等功能模块；项目根用 `build-profile.json5` 做项目配置。
15. 按层分离代码：UI Layer（Pages，ArkUI 组件）→ ViewModel Layer（状态管理和 UI 逻辑）→ Service Layer（业务逻辑）→ Repository Layer（数据访问抽象）→ Data Sources（Local/Remote：Preferences、RDB、Network）。
16. 编写基本 ArkUI 组件：在 `.ets` 中 `import { router } from '@kit.ArkUI'`；用 `@Component export struct ProductCard`；用 `@Prop product: Product` 和 `@Prop onAddToCart: (product: Product) => void` 接收父级数据/回调；用 `@State isExpanded: boolean = false` 管理局部状态；用 getter 如 `get formattedPrice(): string` 计算值；实现 `aboutToAppear()` 和 `aboutToDisappear()`；写 `handleTap()` 调用 `router.pushUrl({ url: 'pages/ProductDetail', params: { id: this.product.id } })`；写 `handleAddToCart()` 调用 `this.onAddToCart(this.product)`；在 `build()` 中用 `Column`、`Image`、`Text`、`Button`，并设置 `.width('100%')`、`.aspectRatio(1)`、`.objectFit(ImageFit.Cover)`、`.fontSize(16)`、`.fontWeight(FontWeight.Medium)`、`.fontColor('#FF6B00')`、`.padding(12)`、`.backgroundColor(Color.White)`、`.borderRadius(8)`，按钮 `.onClick(() => this.handleAddToCart())`，容器 `.onClick(() => this.handleTap())`。
17. 用 `LazyForEach` 实现长列表：定义继承 `BasicDataSource<Product>` 的 `ProductDataSource`，实现 `totalCount()`、`getData(index)`、`addData(product)` 并在添加后调 `notifyDataAdd(this.products.length - 1)`，实现 `updateData(index, product)` 并调 `notifyDataChange(index)`；在 `List` 内使用 `LazyForEach(this.dataSource, (product: Product, index: number) => { ListItem() { ProductCard({ product: product }) } }, (product: Product) => product.id)`；设置 `.lanes(2)` 做两列网格，`.cachedCount(4)` 缓存 4 项。
18. 用 `@CustomDialog` 实现自定义弹窗：声明 `controller: CustomDialogController`、`title`、`message`、`onConfirm`；在 `build()` 中放标题、消息、Cancel 和 Confirm 按钮；Cancel 调 `this.controller.close()`；Confirm 调 `this.onConfirm()` 后 `this.controller.close()`；使用时创建 `new CustomDialogController({ builder: ConfirmDialog({ title: 'Delete Item', message: 'Are you sure you want to delete this item?', onConfirm: () => this.deleteItem() }), autoCancel: true })`；通过 `this.dialogController.open()` 打开。
19. 当任务需要被移走的详细示例、命令目录、检查清单、平台细节或实现模板时，加载 `reference/extended.md`。

适用边界 · 注意事项

• 不适用于非 HarmonyOS/ArkTS 项目，例如 Android、iOS、Web 或纯 TypeScript 项目。
• 不适用于必须维护或兼容 legacy FA 模型（PageAbility、config.json 的 pages 数组）的旧项目。
• 不适用于没有 HarmonyOS SDK/DevEco Studio 或无法使用 HarmonyOS NEXT（API 12+）的环境。