About

Imported from ximing/harmonyos-skills (skills/harmonyos-arkui/SKILL.md). Install upstream with npx skills add ximing/harmonyos-skills --skill harmonyos-arkui. Copyright stays with the author.

鸿蒙 ArkUI 声明式 UI

Name: harmonyos-arkui
Author: ximing

何时使用本 skill

用 ArkTS 声明式范式写页面和自定义组件：@Component 拆分、@Builder/@BuilderParam 复用、@Styles/@Extend 抽样式
状态管理选型拿不准：@State/@Prop/@Link/@Provide/@Consume/@ObjectLink，或 V2 的 @Local/@Param/@Event/@ObservedV2/@Trace 该用哪个
长列表/网格/瀑布流卡顿，要上 LazyForEach、cachedCount、@Reusable 组件复用
页面导航：Navigation 路由栈、分栏自适应、转场动效（新项目不要再用 @ohos.router）
动画与手势：属性动画、共享元素转场（一镜到底）、gesture/priorityGesture/parallelGesture 与手势冲突
多端适配：断点、栅格（GridRow/GridCol）、媒体查询、折叠屏/平板分栏、深浅色主题、UI Design Kit 精品样式

核心方法论

ArkUI 的核心心智模型一句话：UI 是状态的函数。build() 描述 UI 长什么样，状态变量驱动它刷新——所以 ArkUI 开发的绝大多数问题（不刷新、卡顿、数据不同步）都出在状态管理和渲染控制上。以下七节按真实开发顺序组织。

① 声明式语法与自定义组件

页面即组件：@Entry 标记入口、@Component 声明组件、build() 返回 UI 描述。复杂页面按"拆小组件 → 抽复用"演进：

@Builder：组件内的自定义构建函数，抽重复 UI 片段；全局复用配合 wrapBuilder。
@BuilderParam：组件的"插槽"，让调用方传入 UI 内容（类似 Vue slot）。
@Styles：复用通用属性（width/height 等）；@Extend：封装某个具体组件的样式+事件组合。
生命周期：组件级 aboutToAppear/onDidBuild/aboutToDisappear；页面级（@Entry）另有 onPageShow/onPageHide/onBackPress。详见自定义组件生命周期。

@Component
struct TitleBar {
  title: string = '';
  @BuilderParam actions: () => void;  // 调用方注入右侧操作区

  build() {
    Row() {
      Text(this.title).fontSize(18).fontWeight(FontWeight.Bold)
      Blank()
      this.actions()
    }
    .width('100%').padding(12)
  }
}

② 状态管理选型（最高频问题，先看这里）

先记住两条铁律，再查表选型：

只有被装饰器装饰的变量才是状态变量，且只有"框架能观察到的修改"才触发刷新——@State 观察一层赋值，嵌套属性（this.a.b.c = x）观察不到。
状态管理仅支持 UI 主线程，Worker/TaskPool 里不能用。

场景	V1（存量项目）	V2（新应用推荐）
组件内部状态	`@State`	`@Local`
父 → 子单向（子可本地改）	`@Prop`（深拷贝）	`@Param` + `@Once`
父子双向	`@Link`	`@Param` + `@Event`（`!!` 语法糖）
跨层级双向（爷孙）	`@Provide` / `@Consume`	`@Provider` / `@Consumer`
嵌套 class 对象属性级观测	`@Observed` + `@ObjectLink` / `@Track`	`@ObservedV2` + `@Trace`
变更监听回调	`@Watch`	`@Monitor`
计算属性	无（getter 模拟）	`@Computed`
应用全局 / 页面级 / 持久化	AppStorage / LocalStorage / PersistentStorage	AppStorageV2 / LocalStorage / PersistenceV2

官方建议：新开发的应用直接用 V2；存量 V1 项目满足需求不必急着迁。每个装饰器的代码示例、数据流方向图与迁移要点见 references/state-management.md；权威说明读状态管理概述。

③ 渲染控制与列表性能

条件渲染 if/else；循环渲染按数据量选：ForEach（小数据量、非滚动容器）→ LazyForEach（长列表懒加载）→ Repeat（可复用循环渲染，V2 场景替代方案）。
LazyForEach 只在 List/ListItemGroup/Grid/Swiper/WaterFlow 中生效（这些容器可配 cachedCount 缓存屏外项）；其他容器会一次性全量创建。
LazyForEach 三条硬规则：数据源实现 IDataSource 接口；键值生成器对每项生成唯一且稳定的键值；数据变更通过 DataChangeListener 通知——整体重赋值 dataSource 会异常，直接改数组不会触发刷新。
滚动场景叠加 @Reusable（V1）/@ReusableV2（V2）组件复用，划出屏幕的节点进缓存池、复用代替重建。
布局层面：减少嵌套层级、优先扁平容器，嵌套过深直接拖慢布局测量。

List({ space: 8 }) {
  LazyForEach(this.dataSource, (item: Message) => {
    ListItem() {
      MessageRow({ msg: item })   // MessageRow 用 @Reusable 装饰可进复用池
    }
  }, (item: Message) => item.id)  // 键值唯一稳定，别用 index
}
.cachedCount(5)

性能调优的完整流程（Profiler 抓 trace → 定位 → 优化）见 UI高性能开发。

④ 页面导航：用 Navigation，别再用 router

Navigation + NavPathStack（API 10 起推荐）：Navigation 作为 @Entry 页面的根容器，子页面是 NavDestination，路由栈（NavPathStack）负责 push/pop/replace 与传参；自带转场动效与标题栏联动。
多端红利：mode(NavigationMode.Auto) 默认自适应——窗口宽度 ≥600vp 自动切分栏（左列表右详情），一次开发天然适配折叠屏/平板。
@ohos.router 已不推荐，仅存量维护；迁移按 Router切换Navigation。

// 主页持有路由栈，跳转传参
this.pageStack.pushPath({ name: 'Detail', param: { id: 42 } });
// Detail 页（NavDestination）构建时通过 ready 回调的 NavDestinationContext 取 param

⑤ 动画与手势

动画按场景选型：

场景	接口
状态变化附带过渡	属性动画：`.animation()` 绑定 / `animateTo()` 显式闭包
组件出现/消失	转场动画：`.transition()`（配合 if 渲染）
跨页面元素延续	共享元素转场（一镜到底，`geometryTransition`）
逐帧驱动	帧动画（`@ohos.animator`）
节奏感	动画曲线：传统曲线（线性/ease/贝塞尔）、弹簧曲线

手势三件套：gesture（常规，父子竞争）、priorityGesture（优先响应，解决子组件抢手势）、parallelGesture（并行响应，父子都收到）。Tap/LongPress/Pan/Pinch/Rotation/Swipe 可组合成组合手势；滚动容器内手势冲突见手势冲突处理。注意：这三个绑定方法不支持用三目运算符切换手势。

⑥ 布局与多端适配

容器选型：Row/Column（线性，配 justifyContent/alignItems）、Stack（层叠）、Flex（弹性换行）、RelativeContainer（复杂相对关系）、GridRow/GridCol（栅格）、Tabs（页签）、List/Grid/WaterFlow（滚动容器）。选型对照见 references/arkui-cheatsheet.md。

多端适配三板斧：

断点：栅格默认断点 xs [0,320) / sm [320,600) / md [600,840) / lg [840,+∞)（vp），可扩展 xl/xxl；不同断点给不同栅格 span 与布局结构。
媒体查询：@ohos.mediaquery 监听屏幕宽度/横竖屏/深浅色变化，驱动布局切换。
系统级自适应：Navigation 的 Auto 分栏、智慧多窗声明与避让、沉浸式效果。

"一次开发，多端部署"官方文档已迁移到在线最佳实践（体验设计 → 页面开发 → 功能开发端到端指导），本地留存路径调整说明；本地可落地的实操篇目是栅格布局 (GridRow/GridCol) 与媒体查询 (@ohos.mediaquery)。

⑦ 主题、弹窗与 UI Design Kit

主题：深浅色适配（资源走 resources/dark 目录或 WithTheme）、应用内换肤；图标优先用 SymbolGlyph/SymbolSpan（矢量符号，支持分层动效）。
弹窗体系按场景选：即时反馈 Toast；固定样式弹窗 AlertDialog；自定义弹窗 CustomDialog 或不依赖 UI 组件的全局 openCustomDialog；气泡 Popup/openPopup；菜单 Menu/openMenu；半模态 bindSheet、全模态 bindContentCover；浮层 OverlayManager。全景见弹窗概述。
UI Design Kit：符合 HarmonyOS Design 规范的扩展样式套件——侧边栏、底部页签（模糊/出血/分割线）、核心操作栏、列表卡片、流光/点光源/按压阴影等视效。要做"精致感"界面先看 UI Design Kit简介，比手写样式快得多。

常见坑

改了嵌套属性界面不刷新 ❌ this.user.address.city = 'x'（@State 只观测一层赋值） ✅ 嵌套对象用 @Observed+@ObjectLink（V1）或 @ObservedV2+@Trace（V2）；简单场景整体替换对象。定位套路见状态变量改变不触发组件刷新问题常用定位方法。
@Prop 传大对象/深层数据 ❌ @Prop 初始化时深拷贝，嵌套超 5 层会因深拷贝与 GC 引发性能问题，且 PixelMap、RegExp 等类型深拷贝后丢失原类型 ✅ 深层嵌套数据改用 @ObjectLink，或 V2 的 @Param（不做深拷贝）。
长列表用 ForEach 全量渲染 ❌ 几千条数据一次性建组件，首帧卡、内存爆 ✅ 换 LazyForEach + cachedCount + @Reusable；键值必须唯一稳定（别直接用 index），数据更新走 DataChangeListener，整体重赋值 dataSource 会直接异常。
新页面还在用 @ohos.router ❌ router 官方已标记不推荐 ✅ 新页面上 Navigation + NavPathStack，顺手套餐分栏自适应与转场动效。
拿 PersistentStorage 当数据库 ❌ 持久化大对象、高频变化的变量（持久化是慢操作） ✅ 它只适合持久化少量 UI 状态（如设置项开关）；结构化数据、大对象请走 harmonyos-network-data 的首选项/关系型数据库。
在 Worker/TaskPool 里读写状态变量 ❌ 状态管理仅支持 UI 主线程 ✅ 子线程算完把结果 postMessage 回 UI 线程再改状态（并发选型见 harmonyos-ability）。

决策树：我要做 XX 该去哪

我要做…	去哪
状态管理装饰器逐个对比 + 代码示例	references/state-management.md
常用组件/属性一行速查	references/arkui-cheatsheet.md
Ability 生命周期、Want 跳转传参、卡片、并发	harmonyos-ability
网络请求、首选项/数据库/跨设备数据	harmonyos-network-data
Canvas 自绘、图片/音视频、相机	harmonyos-media
掉帧卡顿定位、Profiler 使用	harmonyos-testing + UI高性能开发
页面跳转、路由栈、单双栏自适应	组件导航(Navigation) (推荐)
长列表/网格/瀑布流搭建	列表与网格概述、LazyForEach：数据懒加载
动画、转场、一镜到底	动画概述
手势绑定与冲突、统一拖拽	绑定手势方法、支持统一拖拽
弹窗/半模态/气泡/菜单	弹窗概述
深浅色、换肤、图标符号	应用深浅色适配
平板/折叠屏/多窗适配	应用声明支持智慧多窗、栅格布局 (GridRow/GridCol)
精品样式：侧边栏/页签栏/光影视效	UI Design Kit简介
界面显示异常、白屏闪烁排查	UI显示异常调试
帧率/时延/内存等体验是否达标	应用UX体验建议

参考速查

references/state-management.md — 状态管理 V1/V2 装饰器决策表：每种的数据流方向、代码示例、选型与迁移要点
references/arkui-cheatsheet.md — 常用组件速查：容器/基础/表单/导航/媒体/弹窗，一行一个含关键属性

下方路由区列出本 skill 认领的全部 399 篇文档（由脚本生成，请勿手改）。

本区由 scripts/gen-routes.py 生成，请勿手改。本 skill 认领文档共 399 篇。

应用框架/ArkUI（方舟UI框架）（319 篇）

应用框架/UI Design Kit（UI设计套件）（32 篇）

一次开发，多端部署（1 篇）

一次开发，多端部署文档路径调整

应用体验建议（47 篇）

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/ximing-harmonyos-skills-harmonyos-arkui/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

ximing-harmonyos-skills-harmonyos-arkui.ocm.jsonjson

{
  "ocm": "1",
  "id": "ximing-harmonyos-skills-harmonyos-arkui",
  "kind": "skill",
  "name": "harmonyos-arkui",
  "description": "HarmonyOS ArkUI 声明式 UI 开发 skill：ArkTS 声明式页面、状态管理 V1/V2、列表导航动画手势、多端自适应的方法论与文档路由。 TRIGGERS: \"ArkUI声明式UI\", \"ArkUI组件\", \"@State @Prop @Link状态管理\", \"@Provide @Consume跨层级\", \"List列表/Grid网格\", \"Navigation导航\", \"Tabs页签\", \"ArkUI动画animation\", \"手势gesture拖拽\", \"一次开发多端部署\", \"响应式布局断点\", \"自定义组件component\", \"@Builder\", \"declarative UI\", \"ArkUI layout布局\", \"state management状态管理\", \"UI component\", \"animation动画\", \"multi-device adaptive多端自适应\". USE WHEN: 构建 ArkUI 页面与自定义组件、状态管理装饰器选型、列表/导航/动画/手势、 深浅色主题、弹窗体系、多端自适应布局，或排查 UI 不刷新/长列表卡顿问题。",
  "publisher": "ximing",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "math"
    ],
    "tags": [
      "skill-md",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "HarmonyOS ArkUI 声明式 UI 开发 skill：ArkTS 声明式页面、状态管理 V1/V2、列表导航动画手势、多端自适应的方法论与文档路由。 TRIGGERS: \"ArkUI声明式UI\", \"ArkUI组件\", \"@State @Prop @Link状态管理\", \"@Provide @Consume跨层级\", \"List列表/Grid网格\", \"Navigation导航\", \"Tabs页签\", \"ArkUI动画animation\", \"手势gesture拖拽\", \"一次开发多端部署\", \"响应式布局断点\", \"自定义组件component\", \"@Builder\", \"declarative UI\", \"ArkUI layout布局\", \"state management状态管理\", \"UI component\", \"animation动画\", \"multi-device adaptive多端自适应\". USE WHEN: 构建 ArkUI 页面与自定义组件、状态管理装饰器选型、列表/导航/动画/手势、 深浅色主题、弹窗体系、多端自适应布局，或排查 UI 不刷新/长列表卡顿问题。"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/ximing/harmonyos-skills",
      "path": "skills/harmonyos-arkui/SKILL.md",
      "ref": "d8cd1bca67ad10f2f5d884a0ffdfad656f07b252",
      "url": "https://github.com/ximing/harmonyos-skills/blob/d8cd1bca67ad10f2f5d884a0ffdfad656f07b252/skills/harmonyos-arkui/SKILL.md",
      "key": "ximing/harmonyos-skills/skills/harmonyos-arkui/SKILL.md"
    }
  },
  "instructions": "# 鸿蒙 ArkUI 声明式 UI\n\n## 何时使用本 skill\n\n- 用 ArkTS 声明式范式写页面和自定义组件：`@Component` 拆分、`@Builder`/`@BuilderParam` 复用、`@Styles`/`@Extend` 抽样式\n- 状态管理选型拿不准：`@State`/`@Prop`/`@Link`/`@Provide`/`@Consume`/`@ObjectLink`，或 V2 的 `@Local`/`@Param`/`@Event`/`@ObservedV2`/`@Trace` 该用哪个\n- 长列表/网格/瀑布流卡顿，要上 `LazyForEach`、`cachedCount`、`@Reusable` 组件复用\n- 页面导航：Navigation 路由栈、分栏自适应、转场动效（新项目不要再用 @ohos.router）\n- 动画与手势：属性动画、共享元素转场（一镜到底）、gesture/priorityGesture/parallelGesture 与手势冲突\n- 多端适配：断点、栅格（GridRow/GridCol）、媒体查询、折叠屏/平板分栏、深浅色主题、UI Design Kit 精品样式\n\n## 核心方法论\n\nArkUI 的核心心智模型一句话：**UI 是状态的函数**。`build()` 描述 UI 长什么样，状态变量驱动它刷新——所以",
  "cost": {
    "context_tokens": 12016
  }
}

Fetch it by URL: GET /api/v1/registry/ximing-harmonyos-skills-harmonyos-arkui/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.