ECC 工程规范实战HarmonyOS / ArkTS 开发模式完全指南状态管理 V2、Navigation 路由、MVVM 与性能优化【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文依据 ECC 仓库中 docs/ja-JP/rules/arkts/patterns.md 的规则骨架展开并结合 rules/arkts/ 目录下的编码风格、Hook、测试、安全规范以及 agents/harmonyos-app-resolver.md 专家 Agent 与 examples/harmonyos-app-CLAUDE.md 工程模板系统讲解 HarmonyOS / ArkTS 应用开发的强制性技术选型与落地模式。本文是面向 HarmonyOS / ArkTS 应用开发的工程规范级技术指南聚焦 ECC 仓库中为 Claude Code、Codex 等 Agent 制定的 ArkTS 规则体系。它规定了三条不可妥协的硬性约束——状态管理只用 V2禁用 V1 装饰器、路由只用 Navigation禁用ohos.router、架构统一采用 MVVM并在此基础上给出动画、性能、资源引用的可复用模式。读完本文你将掌握一套可以直接落地到实际 HarmonyOS 工程中的开发模式如何用ComponentV2/Local/Param/Provider/Consumer构建响应式 UI如何用NavPathStack管理页面栈如何用LazyForEach处理大数据列表以及如何配合构建 Hook 与测试清单完成自动化校验。一、规则体系概览谁在强制这些模式在 ECC 仓库中HarmonyOS / ArkTS 的工程约束并非零散建议而是一套完整的、由 Agent 强制执行的分层规则体系核心规则文件docs/ja-JP/rules/arkts/patterns.md 定义模式选型状态管理、路由、架构、动画、性能、资源引用配套规则文件同目录下的 coding-style.mdArkTS 语法约束与命名、hooks.md构建命令与自动化 Hook、testing.md测试框架与 TDD 流程、security.md权限与安全基线执行主体agents/harmonyos-app-resolver.md 定义的 HarmonyOS 应用开发专家 Agent其核心职责就是审查代码是否符合 V2 状态管理、Navigation 路由模式、API 用法与性能最佳实践并在审查中主动标记 V1 装饰器与ohos.router的使用并要求迁移工程落点examples/harmonyos-app-CLAUDE.md 给出了可直接放到 HarmonyOS 项目根目录的CLAUDE.md模板把上述规则固化为Tech Stack Constraints技术栈约束。所有规则文件均通过 front-matter 声明了适用范围如**/*.ets、**/*.ts、**/module.json5、**/oh-package.json5确保只对 ArkTS 工程生效。二、状态管理V2 Only核心硬性约束2.1 为什么必须使用 V2规则文件的第一条、也是最严苛的一条ArkUI 状态管理 V2 必须使用V1 装饰器已废弃禁止使用。原因可以从 V2 的设计目标推断V1 的State、Prop、Link等装饰器依赖深层拷贝与逐属性观察在复杂对象、数组更新场景下容易产生多余刷新或观察不到的变化V2 引入的ObservedV2Trace提供精确到属性的观察能力配合Monitor、Computed能更高效地驱动 UI 更新。专家 Agent 在 agents/harmonyos-app-resolver.md 中明确要求Explain best practices即解释ComponentV2相对 V1 的性能优势。2.2 V2 装饰器速查表装饰器用途ComponentV2将 struct 标记为 V2 组件Local组件内的本地状态Param从父组件接收的属性只读Event子组件向父组件的回调事件Provider向后代组件提供状态Consumer从祖先的Provider获取状态Monitor监听状态变化替代 V1 的WatchComputed派生/计算值ObservedV2使类成为 V2 可观察类Trace标记ObservedV2类中的可观察属性2.3 绝对禁止的 V1 装饰器以下 V1 装饰器在任何情况下都不得使用State、Prop、Link、ObjectLink、Observed、Provide、Consume、Watch、Component改用ComponentV2。Agent 的审查输出格式见 agents/harmonyos-app-resolver.md会以[REVIEW]形式指出 V1 用法并给出迁移建议例如[REVIEW] src/main/ets/pages/HomePage.ets:15 Issue: Uses V1 State decorator Fix: Migrate to ComponentV2 with Local for local state2.4 V2 组件完整示例ObservedV2 class UserModel { Trace name: string Trace age: number 0 } ComponentV2 struct UserCard { Param user: UserModel new UserModel() Event onDelete: () void () {} build() { Column() { Text(this.user.name) .fontSize($r(app.float.font_size_title)) Text(${this.user.age}) .fontSize($r(app.float.font_size_body)) Button($r(app.string.delete)) .onClick(() this.onDelete()) } } }要点拆解ObservedV2Trace让UserModel的属性级变化可被观察任何name或age的修改都会精准触发依赖该属性的 UI 刷新Param user表示从父组件传入的数据只读方向子组件不直接修改Event onDelete把删除这类操作以回调形式抛给父组件保持单向数据流字体与按钮文案均通过$r()引用资源而非硬编码详见第七章。2.5 状态同步Provider / Consumer当状态需要跨越多个层级传递时例如全局用户信息使用Provider/Consumer替代逐层透传 propsComponentV2 struct ParentPage { Provider(userState) userModel: UserModel new UserModel() build() { Column() { ChildComponent() // 自动接收 Consumer(userState) } } } ComponentV2 struct ChildComponent { Consumer(userState) userModel: UserModel new UserModel() build() { Text(this.userModel.name) } }Provider以字符串 key如userState命名提供的状态任意层级的后代组件用同名Consumer即可获取无需中间组件参与转发显著降低耦合。三、路由Navigation Only禁用 ohos.router规则第二条硬性约束必须使用基于NavPathStack的Navigation组件绝对禁止使用ohos.router。原因可归纳为Navigation是声明式路由与 V2 状态管理和NavDestination页面容器深度集成支持路径参数、转场动画、路由替换等能力而ohos.router是命令式 API页面间传参依赖router.getParams()与声明式范式割裂且不便于统一管理页面栈。3.1 Navigation 基础搭建ComponentV2 struct MainPage { Local navPathStack: NavPathStack new NavPathStack() build() { Navigation(this.navPathStack) { // 首页内容 } .navDestination(this.routerMap) } Builder routerMap(name: string, param: ESObject) { if (name detail) { DetailPage() } else if (name settings) { SettingsPage() } } }navDestination绑定一个Builder路由映射函数根据路由 name 分发到对应页面组件路由参数统一由param承载。3.2 页面导航操作// 压入新页面 this.navPathStack.pushPath({ name: detail, param: { id: 123 } }) // 替换当前页面 this.navPathStack.replacePath({ name: settings }) // 返回上一页 this.navPathStack.pop() // 回到根页面 this.navPathStack.clear()四种操作覆盖了日常导航的完整场景pushPath携带参数进入新页、replacePath替换当前页适用于登录后跳转等场景、pop返回、clear清空栈回到根。3.3 NavDestination 子页面子页面必须用NavDestination作为根容器ComponentV2 struct DetailPage { build() { NavDestination() { Column() { Text($r(app.string.detail_title)) } } .title($r(app.string.detail_nav_title)) } }NavDestination自动提供页面标题栏.title()并继承Navigation的转场与返回行为是子页面的标准外壳。四、架构模式MVVM 分层HarmonyOS 应用推荐采用 MVVM 架构目录结构如下feature/ |-- model/ # 数据模型ObservedV2 类 |-- viewmodel/ # 业务逻辑ViewModel 类 |-- view/ # UI 组件ComponentV2 结构体 |-- service/ # API 调用、数据访问各层职责边界View只包含渲染逻辑build()内不得出现业务逻辑ViewModel封装所有业务逻辑表单校验、状态转换、调用 Service 等Model使用ObservedV2与Trace的纯数据类Service网络请求、数据库操作、文件 I/O 等数据访问层。该分层与 examples/harmonyos-app-CLAUDE.md 中View renders only, all business logic in ViewModel的约束一致也与 rules/common/patterns.md 中Repository Pattern通过统一接口封装数据访问业务逻辑依赖抽象接口而非存储机制相互呼应——Service 层正是 Repository 模式在 HarmonyOS 侧的落点便于替换数据源和用 mock 简化测试。文件组织上rules/arkts/coding-style.md 进一步要求组件文件.ets一个文件只放一个ComponentV2ViewModel 文件一个类一个文件Model 文件可共享单文件控制在 400 行以内接近 800 行时必须抽取辅助代码。五、ArkUI 动画模式5.1 状态驱动动画示例ComponentV2 struct AnimatedCard { Local isExpanded: boolean false Local cardScale: number 0.8 build() { Column() { // 内容 } .scale({ x: this.cardScale, y: this.cardScale }) .animation({ duration: 300, curve: Curve.EaseInOut }) .onClick(() { this.isExpanded !this.isExpanded this.cardScale this.isExpanded ? 1.0 : 0.8 }) } }核心思路是改状态而不是直接驱动动画点击事件只修改cardScale状态变量.animation()声明式地将状态变化映射为 300ms 的EaseInOut过渡UI 由系统自动补间。5.2 动画规则清单优先使用原生 HarmonyOS 动画 API 与官方高级模板使用声明式 UI 状态驱动动画通过改变状态变量触发动画复杂子组件动画设置renderGroup(true)减少渲染批次动画期间不得频繁修改width、height、padding、margin—— 会触发布局重算严重影响性能需要显式控制动画时使用animateTo优先使用transformtranslate、scale、rotate与opacity这类不触发重排的属性做高性能动画。上述规则在 agents/harmonyos-app-resolver.md 的 ArkUI Animation Guidelines 一节中被专家 Agent 原样强制执行属于代码审查的必查项。六、性能模式6.1 大数据列表LazyForEach列表数据量较大时禁止在List中直接ForEach渲染全部条目必须使用LazyForEach按需创建ComponentV2 struct LargeList { Local dataSource: MyDataSource new MyDataSource() build() { List() { LazyForEach(this.dataSource, (item: ItemModel) { ListItem() { ItemComponent({ item: item }) } }, (item: ItemModel) item.id) } } }LazyForEach的第三个参数是键生成函数此处用item.id用于唯一标识条目、复用已有组件并精准定位增量更新是列表滚动的关键性能保障。6.2 组件复用可复用组件抽取到独立文件一个文件一个ComponentV2组件内的轻量 UI 片段使用Builder封装可配置组件使用Param暴露输入属性。配合 rules/arkts/coding-style.md 的命名规范组件文件PascalCase如HomePage.ets工具类camelCase保证组件库的整洁与可检索性。七、资源引用一律走 $r()UI 常量文案、字号、颜色、图片必须定义为资源通过$r()引用严禁硬编码字面量// BAD: 硬编码 Text(Hello) .fontSize(16) .fontColor(#333333) // GOOD: 资源引用 Text($r(app.string.greeting)) .fontSize($r(app.float.font_size_body)) .fontColor($r(app.color.text_primary))资源化带来的收益在 rules/arkts/hooks.md 的校验清单中得到呼应所有资源字符串必须同步到全部 i18n 语言目录新增颜色资源必须提供深色主题取值。也就是说资源化不只是代码整洁问题更是国际化和深色模式适配的硬性工程要求。八、配合 ArkTS 语法约束编译级保障patterns.md 中的模式代码必须在 ArkTS 严格静态类型子集下可编译。这意味着编写上述任何模式时都要规避 coding-style.md 列出的编译阻断项例如类型系统禁止any/unknown、索引访问类型、交叉类型、映射类型、as const、结构类型只用Partial/Required/Readonly/Record四个工具类型函数与类禁止函数表达式用箭头函数、生成器函数、Function.apply/call/bind、new.target类字段必须在类体中声明而非构造函数内对象访问禁止obj[field]动态访问用obj.field、delete运算符、in运算符用instanceof、globalThis、Symbol()Symbol.iterator除外解构与展开禁止解构赋值/解构参数展开运算符仅用于数组展开进 rest 参数或数组字面量模块禁止require()、export 、导入断言、UMD、模块名通配符所有import必须位于其他语句之前其他禁止var、for...in、with、JSX、#私有标识符用private、声明合并、索引签名catch子句省略类型标注。同时遵循命名约定变量/函数camelCase、类/接口PascalCase、常量UPPER_SNAKE_CASE字符串用双引号、语句末尾加分号、所有方法/参数/返回值必须完整标注类型错误处理统一try/catch并配合hilog记录、抛出对用户友好的错误信息坚持不可变性——更新数据时创建新实例而非直接改原对象。九、把模式固化为自动化构建命令与 Hook模式要落地离不开自动化校验。rules/arkts/hooks.md 给出了一整套可接入 Claude Code / Codex 等 Agent 工具链的 Hook 方案。9.1 构建命令# 构建 HAP 包全局 hvigor 环境 hvigorw assembleHap -p productdefault # 指定模块构建 hvigorw assembleHap -p moduleentry -p productdefault # 清理构建 hvigorw clean # 检查项目结构 / 版本 hvigorw --version # 安装 / 更新依赖 ohpm install ohpm update每次实现完成都应执行hvigorw assembleHap验证编译这也与 examples/harmonyos-app-CLAUDE.md 中Run build after every implementation的要求一致。9.2 PostToolUse Hook编辑 .ets/.ts 后自动构建{ type: PostToolUse, matcher: { tool: [Edit, Write], filePath: [**/*.ets, **/*.ts] }, hooks: [ { command: hvigorw assembleHap -p productdefault 21 | tail -20, async: true, timeout: 60000 } ] }9.3 PostToolUse Hook修改 module.json5 后校验权限{ type: PostToolUse, matcher: { tool: Edit, filePath: **/module.json5 }, hooks: [ { command: echo [HarmonyOS] module.json5 modified - verify permissions and abilities, async: false } ] }9.4 PostToolUse Hook修改 oh-package.json5 后重装依赖{ type: PostToolUse, matcher: { tool: Edit, filePath: **/oh-package.json5 }, hooks: [ { command: ohpm install 21 | tail -10, async: true, timeout: 30000 } ] }9.5 PreToolUse HookV1 装饰器防线在写入.ets文件前Hook 主动提示禁止使用 V1 装饰器{ type: PreToolUse, matcher: { tool: [Write, Edit], filePath: **/*.ets }, hooks: [ { command: echo [HarmonyOS] Reminder: Use ComponentV2 / Local / Param - V1 decorators (State, Prop, Link) are prohibited } ] }9.6 每个实现周期的校验清单hvigorw assembleHap无错误完成新增/修改的.ets文件中无 V1 装饰器新增/修改的文件中无ohos.router导入所有 API 权限已在module.json5中声明所有依赖已列入oh-package.json5资源字符串已同步到所有 i18n 目录新增颜色资源已提供深色主题取值十、测试与 TDD验证模式正确性模式是否被正确实现最终由测试兜底。rules/arkts/testing.md 给出了 HarmonyOS 专属的测试体系测试框架内置ohos.test能力单测位于src/ohosTest/ets/test/UI 测试用ohos.UiTest仪器测试运行在设备/模拟器上运行命令hvigorw testHap -p productdefault设备上执行hdc shell aa test -b com.example.app -m entry_test -s unittest /ets/TestRunner/OpenHarmonyTestRunnerTDD 循环RED在ohosTest/ets/test/写失败测试→ GREEN在main/ets/实现最简代码→ REFACTOR保持测试通过的前提下重构→ BUILDhvigorw assembleHap验证编译→ VERIFY设备/模拟器上运行测试覆盖率要求关键应用代码ViewModel、Service、工具类最低 80% 覆盖V2 专属测试要点验证Trace属性变化能触发 UI 更新验证NavPathStack的 push/pop/replace 导航流程。单测示例hypium 框架import { describe, it, expect } from ohos/hypium; export default function UserViewModelTest() { describe(UserViewModel, () { it(should_initialize_with_empty_state, 0, () { const vm new UserViewModel(); expect(vm.userName).assertEqual(); expect(vm.isLoading).assertFalse(); }); it(should_update_user_name, 0, () { const vm new UserViewModel(); vm.updateUserName(Alice); expect(vm.userName).assertEqual(Alice); }); it(should_handle_empty_input, 0, () { const vm new UserViewModel(); vm.updateUserName(); expect(vm.userName).assertEqual(); expect(vm.hasError).assertFalse(); }); }); }UI 测试示例import { describe, it, expect } from ohos/hypium; import { Driver, ON } from ohos.UiTest; export default function HomePageUITest() { describe(HomePage_UI, () { it(should_display_title, 0, async () { const driver Driver.create(); await driver.delayMs(1000); const title await driver.findComponent(ON.text(Home)); expect(title ! null).assertTrue(); }); it(should_navigate_to_detail_on_click, 0, async () { const driver Driver.create(); const button await driver.findComponent(ON.id(detailButton)); await button.click(); await driver.delayMs(500); const detailTitle await driver.findComponent(ON.text(Detail)); expect(detailTitle ! null).assertTrue(); }); }); }十一、安全基线模式之外的硬要求虽然不是 patterns 文档的主体但 rules/arkts/security.md 与上述模式直接相关落地时应一并遵守权限所有系统 API 调用所需权限必须在module.json5的requestPermissions中声明敏感权限相机、定位等必须实现运行时请求且调用前检查、拒绝时优雅降级密钥严禁在.ets/.ts中硬编码 API Key/Token/密码非敏感配置走 Preferences API敏感凭据走 HUKSUniversal KeystoreKit加解密输入校验处理前校验所有用户输入深链参数在导航前必须校验例如校验 path 是否属于允许列表后再pushPath网络一律 HTTPS、校验服务端证书、设置超时与重试、禁止在日志中输出令牌等敏感数据依赖只使用官方 ohpm 仓库的受信来源固定依赖版本定期排查已知漏洞。这与 examples/harmonyos-app-CLAUDE.md 中No hardcoded secrets / Verify permissions in module.json5 / Use HTTPS三条约束完全对应。十二、总结一套可复制、可校验的 ArkTS 工程范式回到 ECC 仓库的视角docs/ja-JP/rules/arkts/patterns.md 提供的并非零散技巧而是一套选型强制 模式示例 自动化校验三位一体的工程范式选型强制状态管理 V2 Only禁用全部 V1 装饰器、路由 Navigation Only禁用ohos.router、架构 MVVM Only三个Only消灭了技术选型分歧模式示例ObservedV2/Trace数据模型、ComponentV2/Param/Event组件、Provider/Consumer跨层状态、NavPathStack导航、LazyForEach大列表、$r()资源引用每个模式都给出可直接复制的代码自动化校验通过 hooks.md 的 PreToolUse/PostToolUse Hook 在 Agent 工作流中自动执行构建、V1 装饰器提醒、依赖重装与清单核验再叠加 testing.md 的 TDD 与 80% 覆盖率红线把写对变成可验证的工程事实。对于任何 HarmonyOS 项目都可以直接以 examples/harmonyos-app-CLAUDE.md 为模板生成项目级规范并让 agents/harmonyos-app-resolver.md 这类专家 Agent 在开发与审查循环中强制执行本文所述的全部模式从而实现高质量、可持续维护的 ArkTS 代码库。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考