메뉴
编写、审查或改进ArkUI代码，遵循状态管理(V1/V2)、组件结构、布局选择、性能优化的最佳实践。触发场景：构建新页面或组件、实现状态管理、开发布局(列表/网格/瀑布流)、添加动画手势、搭建导航路由、处理弹窗模态、MVVM架构设计、V1迁移V2。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
**MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, 鸿蒙开发文档, skills). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, or skills.
检查 HarmonyOS 项目中的废弃 SDK 接口并提供修复建议。当需要清理废弃 API、升级 API 版本、优化代码质量或进行静态语法检查时使用。提供详细的迁移方案、修复优先级分类和代码示例。
检索 ArkTS 语言指南文档，为代码开发、审查和调试提供语法参考。当需要查找 ArkTS 语法规则、库使用方法或代码示例时使用。提供基于索引的高效检索和可追溯的文档引用。
检查并修复 HarmonyOS 项目的 ArkTS 语法错误，自动化构建项目。当需要编译项目、修复编译错误、生成 HAP/App 产物时使用。提供静态语法检查、错误自动修复、循环构建直到成功的完整工作流程。支持错误优先级分类（P0/P1/P2）、最大重试机制、构建产物自动定位。
帮助开发者将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装饰器对应关系或差异。
Handle HarmonyOS avoid-area adaptation through a declarative scene and resource index. Use when the task involves safe area expansion, status bar or navigation bar avoidance, notch or cutout handling, immersive full-screen layouts, or soft keyboard overlap handling.
| name | hmos-arkui-develop-skill |
| description | 编写、审查或改进ArkUI代码，遵循状态管理(V1/V2)、组件结构、布局选择、性能优化的最佳实践。触发场景：构建新页面或组件、实现状态管理、开发布局(列表/网格/瀑布流)、添加动画手势、搭建导航路由、处理弹窗模态、MVVM架构设计、V1迁移V2。 |
references/02-state-management/v2-state-management.md）根据当前任务查阅相关参考文档：
| 主题 | 参考文档 |
|---|---|
| V2状态管理 | references/02-state-management/v2-state-management.md |
| V1状态管理 | references/02-state-management/v1-state-management.md |
| 应用级状态管理 | references/02-state-management/app-state-management.md |
| 状态管理最佳实践 | references/02-state-management/best-practices.md |
| 自定义组件 | references/01-basic-development/custom-components.md |
| 声明式UI | references/01-basic-development/declarative-ui.md |
| 渲染控制 | references/01-basic-development/rendering-control.md |
| 资源使用 | references/01-basic-development/resource-usage.md |
| 通用属性 | references/01-basic-development/common-attribute.md |
| 视觉效果 | references/01-basic-development/visual-effects.md |
| 基础布局 | references/03-layout/basic-layout.md |
| List列表 | references/03-layout/scroll-container/list.md |
| Grid网格 | references/03-layout/scroll-container/grid.md |
| WaterFlow瀑布流 | references/03-layout/scroll-container/waterflow.md |
| UI组件 | references/04-ui-components/ui-components.md |
| 文本处理 | references/04-ui-components/text-handling.md |
| 动画基础 | references/05-animation/animation.md |
| 转场动画 | references/05-animation/transition-animation.md |
| 事件交互 | references/06-events-interaction/events-interaction.md |
| 手势交互 | references/06-events-interaction/gesture-interaction.md |
| 弹窗菜单 | references/07-dialogs/dialogs-menus.md |
| 模态页面 | references/07-dialogs/modals-pages.md |
| 导航路由 | references/08-navigation-routing/navigation-routing.md |
| 导航完整示例 | references/08-navigation-routing/navigation-complete-example.md |
| Tabs标签 | references/08-navigation-routing/tabs.md |
| 自定义节点 | references/09-custom-nodes/custom-node.md |
| 自定义渲染 | references/09-custom-nodes/custom-rendering.md |
| 图形绘制 | references/09-custom-nodes/graphics-drawing.md |
| 自定义能力 | references/09-custom-nodes/custom-capabilities.md |
| UIContext | references/10-common-ui-func/uicontext.md |
| 国际化 | references/11-i18n-adaptation/internationalization.md |
| 主题适配 | references/11-i18n-adaptation/theming-adaptation.md |
| 无障碍 | references/11-i18n-adaptation/accessibility.md |
| 稳定性 | references/12-stability-performance/stability.md |
| 调试与性能 | references/12-stability-performance/debugging-performance.md |
| MVVM架构 | references/13-mvvm-architecture/MVVM_Architecture_Guide.md |
这些是硬规则 - 违反即为错误：
| 装饰器 | 使用场景 |
|---|---|
@Local | 组件内部状态（替代@State） |
@Param | 父→子数据传递（只读） |
@Param @Once | 父→子传递，允许本地更新 |
@Event | 子→父通信 |
@ObservedV2 | 类需要深度观测 |
@Trace | 标记@ObservedV2类中的可观测属性 |
@Provider/@Consumer | 跨组件状态共享 |
@Monitor | 监听特定属性变化 |
@Computed | 派生/缓存计算值 |
| 装饰器 | 使用场景 |
|---|---|
@State | 组件内部状态 |
@Prop | 父→子单向绑定 |
@Link | 父↔子双向绑定 |
@Observed/@ObjectLink | 嵌套对象观测（必须配合使用） |
@Provide/@Consume | 跨组件状态（祖先↔后代） |
@Watch | 观察状态变化 |
| 布局类型 | 组件 | 使用场景 |
|---|---|---|
| 线性 | Row/Column | 简单水平/垂直排列 |
| 弹性 | Flex | 弹性尺寸、换行、对齐 |
| 层叠 | Stack | 重叠元素、分层 |
| 相对 | RelativeContainer | 复杂相对定位 |
| 列表 | List | 长列表滚动（使用LazyForEach/Repeat） |
| 网格 | Grid | 规则网格项 |
| 瀑布流 | WaterFlow | 不等高项（Pinterest风格） |
| 标签 | Tabs | 标签导航与内容 |
基础组件（V2）
@ComponentV2
struct MyComponent {
@Local count: number = 0;
@Param title: string = '';
@Event onCountChange: (value: number) => void = () => {};
build() {
Column() {
Text(this.title)
Button(`计数: ${this.count}`)
.onClick(() => {
this.count++;
this.onCountChange(this.count);
})
}
}
}
可观测类（V2）
@ObservedV2
class TaskModel {
@Trace name: string = '';
@Trace isDone: boolean = false;
toggle() {
this.isDone = !this.isDone;
}
}
MVVM目录结构
src/main/ets/
├── model/ # 数据结构
│ └── TaskModel.ets
├── viewmodel/ # 状态与逻辑
│ └── TaskViewModel.ets
├── view/ # UI组件
│ └── TaskItemView.ets
└── pages/ # 页面入口
└── TaskPage.ets
references/01-basic-development/custom-components.md - 组件创建、@Builder、@BuilderParamreferences/01-basic-development/declarative-ui.md - 声明式UI语法和基础references/01-basic-development/rendering-control.md - 条件渲染、ForEach、LazyForEachreferences/01-basic-development/resource-usage.md - 资源访问、$r、$rawfilereferences/02-state-management/v2-state-management.md - V2装饰器：@Local、@Param、@Event、@ObservedV2references/02-state-management/v1-state-management.md - V1装饰器：@State、@Prop、@Link、@Observedreferences/02-state-management/app-state-management.md - AppStorage、LocalStorage、PersistentStoragereferences/02-state-management/best-practices.md - 状态管理模式与反模式references/03-layout/basic-layout.md - Row、Column、Flex、Stack、RelativeContainerreferences/03-layout/scroll-container/list.md - List组件、LazyForEach、Repeatreferences/03-layout/scroll-container/grid.md - Grid组件和模式references/03-layout/scroll-container/waterflow.md - WaterFlow瀑布流布局references/04-ui-components/ui-components.md - 基础和高级组件references/04-ui-components/text-handling.md - 文本处理和格式化references/05-animation/animation.md - 属性动画、显式动画references/05-animation/transition-animation.md - 页面和组件转场references/06-events-interaction/events-interaction.md - 触摸、点击、按键事件references/06-events-interaction/gesture-interaction.md - 手势识别与处理references/07-dialogs/dialogs-menus.md - AlertDialog、ActionSheet、Menu、Popupreferences/07-dialogs/modals-pages.md - 模态页面、自定义弹窗references/08-navigation-routing/navigation-routing.md - Navigation、NavPathStackreferences/08-navigation-routing/navigation-complete-example.md - 导航完整示例references/08-navigation-routing/tabs.md - Tabs组件references/09-custom-nodes/custom-node.md - FrameNode、RenderNode自定义references/09-custom-nodes/custom-rendering.md - 自定义渲染references/09-custom-nodes/graphics-drawing.md - Canvas、绑图APIreferences/09-custom-nodes/custom-capabilities.md - 自定义能力references/10-common-ui-func/uicontext.md - UIContext、路由、overlayreferences/11-i18n-adaptation/internationalization.md - 国际化references/11-i18n-adaptation/theming-adaptation.md - 主题换肤references/11-i18n-adaptation/accessibility.md - 无障碍references/12-stability-performance/stability.md - 常见问题与解决方案references/12-stability-performance/debugging-performance.md - 调试与优化references/13-mvvm-architecture/MVVM_Architecture_Guide.md - MVVM项目结构