Back to Details

hmos-arkui-scenario-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ArkUI Scenario Development

ArkUI 场景开发

Skill Definition

Skill 定义

FieldContent
skill_id
arkui-scenario-development
skill_name
ArkUI Scenario Development
one_line_purpose
Covers ArkUI basic syntax, UI framework logic, state management, compilation and runtime. Uses route documents for interaction, focus, navigation, page construction, V1/V2 state management, component synchronization, dialogs, menus, animation, custom components, layouts, images, lists, and text.
not_in_scope
Native development unrelated to ArkUI, non-HarmonyOS development, and CI/CD configuration.
primary_outputs
primary_scene
, 
implementation_notes
, 
code_touchpoints
, 
verification_matrix
字段内容
skill_id
arkui-scenario-development
skill_name
ArkUI 场景开发
one_line_purpose
涵盖 ArkUI 基础语法、UI 框架逻辑、状态管理、编译与运行时。通过路由文档处理交互、焦点、导航、页面构建、V1/V2 状态管理、组件同步、对话框、菜单、动画、自定义组件、布局、图片、列表和文本。
not_in_scope
与 ArkUI 无关的原生开发、非 HarmonyOS 开发，以及 CI/CD 配置。
primary_outputs
primary_scene
, 
implementation_notes
, 
code_touchpoints
, 
verification_matrix

Core Constraints

核心约束

  • Handle only ArkUI / ArkTS 
    .ets
    pages, components, interactions, state, navigation, dialogs, animation, layout, images, lists, text, compilation, and runtime tasks.
  • Do not handle unrelated native system capabilities, back-end APIs, databases, CI/CD, release workflows, or non-HarmonyOS development. Classify requests limited to those areas as 
    not_in_scope
    .
  • When 
    ARKUI-02
    or 
    ARKUI-03
    is matched, read its route document and complete the secondary routing. If several secondary scenes match, record and read all of them.
  • Before presenting a solution or code, provide the routing result, phase, matched scenes, and resource paths to be read. Do not skip routing and go directly to implementation.
  • Base the solution or code on the matched resource documents, including their APIs, component structure, callbacks, lifecycle rules, and verification points. Explicitly state any uncovered boundary.
  • 仅处理 ArkUI / ArkTS 
    .ets
    页面、组件、交互、状态、导航、对话框、动画、布局、图片、列表、文本、编译和运行时任务。
  • 不处理无关的原生系统能力、后端 API、数据库、CI/CD、发布工作流或非 HarmonyOS 开发。将仅限于这些领域的请求归类为 
    not_in_scope
    。
  • 匹配到 
    ARKUI-02
    或 
    ARKUI-03
    时，读取其路由文档并完成次级路由。如果匹配到多个次级场景，则记录并读取所有场景。
  • 在给出方案或代码之前，先提供路由结果、阶段、匹配场景和待读取的资源路径。不得跳过路由而直接实现。
  • 基于匹配的资源文档给出方案或代码，包括其中规定的 API、组件结构、回调、生命周期规则和验证点。明确说明任何未覆盖的边界。

Execution Steps

执行步骤

Every ArkUI request must follow these steps in order. Do not write code before completing them.
每个 ArkUI 请求都必须按顺序执行以下步骤。编写代码前不得跳过这些步骤。

Step 1: Determine the Route

第 1 步：确定路由

Use the decision tree and output:
yaml
active_phases: [REQ / DEV / FIX / VAL]
primary_phase: <primary phase>
primary_scene: <primary scene ID, such as ARKUI-02>
secondary_scenes: [<related scene IDs>]
route_reason: <brief routing reason>
next_scene_refs: [<primary and related resource paths>]
Rules:
  • Include every 
    resource_refs
    entry for 
    secondary_scenes
    in 
    next_scene_refs
    .
  • Find primary scene resources from the scene index.
  • Resolve 
    resource_ref
    , 
    resource_refs
    , and 
    resource_files
    in secondary ROUTE documents.
使用决策树并输出：
yaml
active_phases: [REQ / DEV / FIX / VAL]
primary_phase: <primary phase>
primary_scene: <primary scene ID, such as ARKUI-02>
secondary_scenes: [<related scene IDs>]
route_reason: <brief routing reason>
next_scene_refs: [<primary and related resource paths>]
规则：
  • 将 
    secondary_scenes
    中的每个 
    resource_refs
    条目加入 
    next_scene_refs
    。
  • 从场景索引中查找主要场景资源。
  • 解析次级 ROUTE 文档中的 
    resource_ref
    、
    resource_refs
    和 
    resource_files
    。

Step 2: Read All Scene References

第 2 步：读取所有场景参考文档

Use the Read tool to read every file in 
next_scene_refs
. Do not replace document-specific guidance with assumptions.
Read in this order:
  1. Primary scene reference documents.
  2. Related scene reference documents.
  3. Cascaded route documents. If a reference is a ROUTE document, continue through its scene index until all leaf documents have been read.
Do not skip a referenced file, assume a file is empty from its name, or replace a documented API pattern with prior knowledge.
使用 Read 工具读取 
next_scene_refs
中的每个文件。不得用假设替代文档中的专项指导。
按以下顺序读取：
  1. 主要场景参考文档。
  2. 相关场景参考文档。
  3. 级联路由文档。如果某个引用是 ROUTE 文档，则继续沿其场景索引向下读取，直至读取所有叶子文档。
不得跳过被引用的文件，不得仅根据文件名认定文件为空，也不得用既有知识替代文档规定的 API 模式。

Step 3: Confirm the Route

第 3 步：确认路由

Before implementation, output:
markdown
undefined
实现前输出：
markdown
undefined

Route Confirmation

Route Confirmation

Routing result:
  • primary_phase: ...
  • primary_scene: ...
  • secondary_scenes: [...]
Documents read:
  1. [file path] - [one-sentence summary]
  2. [file path] - [one-sentence summary]
Implementation points:
  • [API, pattern, or constraint extracted from the documents]
undefined
Routing result:
  • primary_phase: ...
  • primary_scene: ...
  • secondary_scenes: [...]
Documents read:
  1. [file path] - [one-sentence summary]
  2. [file path] - [one-sentence summary]
Implementation points:
  • [API, pattern, or constraint extracted from the documents]
undefined

Step 4: Implement

第 4 步：实现

Implement according to the constraints, API usage, callbacks, lifecycle rules, and configuration formats in the scene documents.
  • Use the documented API patterns; do not replace them with undocumented alternatives.
  • When a document provides a complete code example, adapt that example instead of rewriting it from scratch.
  • When several examples exist, choose the one that best matches the request.
根据场景文档中的约束、API 用法、回调、生命周期规则和配置格式进行实现。
  • 使用文档规定的 API 模式，不得用未记录的替代方案取代。
  • 当文档提供完整代码示例时，应基于该示例进行调整，而不是从头重写。
  • 当存在多个示例时，选择与请求最匹配的示例。

Phase Labels

阶段标签

LabelPhaseFocus
REQ
Requirements and designScene recognition, interaction design, state-management selection, animation selection, and page-flow design
DEV
DevelopmentArkUI implementation, component usage, state management, gesture handling, animation APIs, and route configuration
FIX
TroubleshootingCompilation errors, runtime exceptions, failed animations, state desynchronization, navigation failures, and broken interactions
VAL
Functional validationUI rendering, interaction events, state management, animation effects, and page-flow validation
标签阶段重点
REQ
需求与设计场景识别、交互设计、状态管理方案选择、动画选择和页面流设计
DEV
开发ArkUI 实现、组件使用、状态管理、手势处理、动画 API 和路由配置
FIX
故障排查编译错误、运行时异常、动画失败、状态不同步、导航失败和交互异常
VAL
功能验证UI 渲染、交互事件、状态管理、动画效果和页面流验证

Unified Output Fields

统一输出字段

  • REQ
    : 
    device_constraints
    , 
    capability_boundary
    , 
    acceptance_focus
  • DEV
    : 
    code_touchpoints
    , 
    reuse_resources
    , 
    implementation_notes
    , 
    integration_risks
  • FIX
    : 
    problem_profile
    , 
    root_cause_hypothesis
    , 
    fix_plan
    , 
    regression_watchlist
  • VAL
    : 
    verification_matrix
    , 
    evidence_requirements
    , 
    pass_criteria
    , 
    residual_risks
  • REQ
    ：
    device_constraints
    、
    capability_boundary
    、
    acceptance_focus
  • DEV
    ：
    code_touchpoints
    、
    reuse_resources
    、
    implementation_notes
    、
    integration_risks
  • FIX
    ：
    problem_profile
    、
    root_cause_hypothesis
    、
    fix_plan
    、
    regression_watchlist
  • VAL
    ：
    verification_matrix
    、
    evidence_requirements
    、
    pass_criteria
    、
    residual_risks

Field Definitions

字段定义

  • device_constraints
    : Constraints caused by device type, screen size, system version, or similar environment differences.
  • capability_boundary
    : The API versions, device types, and system states where the plan is valid, plus cases requiring fallback or extra handling.
  • acceptance_focus
    : UI behavior, interaction behavior, and animation effects that must receive special attention during acceptance.
  • The fields listed for a phase are required after the corresponding scene is matched. Output is determined by the phase, not separately by each scene.
  • device_constraints
    ：由设备类型、屏幕尺寸、系统版本或类似环境差异引起的约束。
  • capability_boundary
    ：方案适用的 API 版本、设备类型和系统状态，以及需要降级处理或额外处理的情况。
  • acceptance_focus
    ：验收期间需要重点关注的 UI 行为、交互行为和动画效果。
  • 匹配到相应场景后，必须提供该阶段列出的字段。输出由阶段决定，而不是由每个场景分别决定。

Scenario Decision Tree

场景决策树

Step 1: Determine the Phase

第 1 步：确定阶段

Decide whether the user describes an existing implementation with an incorrect result.
  • FIX
    : An existing implementation produces an error, crash, blank screen, failed animation, desynchronized state, failed navigation, unresponsive gesture, or missing dialog; the user explicitly requests troubleshooting or fixing; or the prompt includes an API/code sample and an abnormal result.
  • DEV
    : The user describes a new feature without an existing abnormal result, using signals such as "implement", "development plan", or "build". A design constraint such as "must not be covered" is not the same as an existing obstruction.
  • REQ
    : The user asks for requirements analysis, evaluation, or solution selection.
判断用户是否在描述一个结果不正确的现有实现。
  • FIX
    ：现有实现出现错误、崩溃、白屏、动画失败、状态不同步、导航失败、手势无响应或对话框缺失；用户明确要求排查或修复；或者提示中包含 API/代码示例和异常结果。
  • DEV
    ：用户描述一项没有现有异常结果的新功能，并使用了“实现”“开发计划”或“构建”等信号。诸如“不得涵盖”的设计约束，不等同于现有障碍。
  • REQ
    ：用户要求进行需求分析、评估或方案选择。

Step 2: Match Primary Scenes

第 2 步：匹配主要场景

Match all primary scenes in parallel. Use 
metadata.keywords
, each scene's 
intent_signals
, the user's prompt, code, error, screenshot, and context.
  • Strong signals such as API names, decorators, component names, and error symptoms take priority over generic words.
  • Check 
    applies_when
    for every candidate.
  • Check 
    not_applies_when
    and move excluded candidates to a more suitable scene or to 
    secondary_scenes
    .
  • A scene that matches only 
    intent_signals
    but not 
    applies_when
    cannot be 
    primary_scene
    .
  • primary_scene
    is the strongest scene satisfying the signals, applicability, and current phase.
  • secondary_scenes
    capture dependencies, related behavior, troubleshooting prerequisites, and validation supplements. Multiple applicable scenes may be retained.
并行匹配所有主要场景。使用 
metadata.keywords
、每个场景的 
intent_signals
、用户提示、代码、错误、截图和上下文。
  • API 名称、装饰器、组件名称和错误症状等强信号优先于通用词语。
  • 检查每个候选场景的 
    applies_when
    。
  • 检查 
    not_applies_when
    ，并将不符合条件的候选场景移至更合适的场景或 
    secondary_scenes
    。
  • 仅匹配 
    intent_signals
    而不满足 
    applies_when
    的场景不能成为 
    primary_scene
    。
  • primary_scene
    是同时满足信号、适用性和当前阶段的最强场景。
  • secondary_scenes
    用于涵盖依赖关系、关联行为、故障排查前提和验证补充。可以保留多个适用场景。

Step 3: Apply Phase Decisions

第 3 步：应用阶段决策

Read the matching scene's 
REQ
, 
DEV
, 
FIX
, or 
VAL
decisions according to 
primary_phase
:
  • REQ
    clarifies scope and acceptance priorities.
  • DEV
    determines the implementation path and code skeleton.
  • FIX
    identifies diagnostic checkpoints and regression risks.
  • VAL
    generates the validation matrix and evidence requirements.
  • If the decisions do not fully cover the request, keep the matched scene and explicitly state the uncovered boundary.
根据 
primary_phase
读取匹配场景的 
REQ
、
DEV
、
FIX
或 
VAL
决策：
  • REQ
    明确范围和验收重点。
  • DEV
    确定实现路径和代码骨架。
  • FIX
    识别诊断检查点和回归风险。
  • VAL
    生成验证矩阵和证据要求。
  • 如果这些决策无法完全覆盖请求，则保留已匹配场景，并明确说明未覆盖的边界。

Step 4: Resolve Resources

第 4 步：解析资源

Add every primary and secondary 
resource_refs
entry to 
next_scene_refs
. Expand every ROUTE reference through its own decision tree. If no scene matches, classify the request as 
not_in_scope
; do not skip field-based routing and implement directly.
将所有主要和次要 
resource_refs
条目加入 
next_scene_refs
。通过每个 ROUTE 引用自身的决策树进行展开。如果没有任何场景匹配，将请求归类为 
not_in_scope
；不得跳过基于字段的路由而直接实现。

Scene Index

场景索引

ARKUI-01
ArkUI Basic Syntax

ARKUI-01
ArkUI 基础语法

yaml
scene_id: ARKUI-01
scene_name: ArkUI Basic Syntax
resource_refs:
  - ./references/arkui-basic/ROUTE.md
intent_signals:
  - declarative UI / conditional rendering / visibility switching / expand and collapse
  - custom components / @Component / @ComponentV2 / @Builder / @LocalBuilder / @BuilderParam
  - AttributeModifier / @Reusable / @ReusableV2 / LazyForEach / Repeat / virtualScroll / UI slots / style reuse / component reuse
applies_when:
  - The request concerns ArkUI's declarative paradigm, component definitions, build(), decorators, or basic syntax.
  - The request concerns if rendering, dynamic visibility, expand/collapse, or login-state switching.
  - The request concerns @Builder, @BuilderParam, @LocalBuilder, AttributeModifier, @Reusable, @ReusableV2, LazyForEach, Repeat, reuseId, or reuse.
not_applies_when:
  - The core request is page structure, layout, navigation, interaction, dialogs, animation, images, lists, or text (`ARKUI-02`).
  - The core request is state transfer, synchronization, observation, or V1/V2 mixing (`ARKUI-03`).
  - The core request is a compilation/runtime error, blank screen, crash, or SDK compatibility issue (`ARKUI-04`).
yaml
scene_id: ARKUI-01
scene_name: ArkUI Basic Syntax
resource_refs:
  - ./references/arkui-basic/ROUTE.md
intent_signals:
  - declarative UI / conditional rendering / visibility switching / expand and collapse
  - custom components / @Component / @ComponentV2 / @Builder / @LocalBuilder / @BuilderParam
  - AttributeModifier / @Reusable / @ReusableV2 / LazyForEach / Repeat / virtualScroll / UI slots / style reuse / component reuse
applies_when:
  - The request concerns ArkUI's declarative paradigm, component definitions, build(), decorators, or basic syntax.
  - The request concerns if rendering, dynamic visibility, expand/collapse, or login-state switching.
  - The request concerns @Builder, @BuilderParam, @LocalBuilder, AttributeModifier, @Reusable, @ReusableV2, LazyForEach, Repeat, reuseId, or reuse.
not_applies_when:
  - The core request is page structure, layout, navigation, interaction, dialogs, animation, images, lists, or text (`ARKUI-02`).
  - The core request is state transfer, synchronization, observation, or V1/V2 mixing (`ARKUI-03`).
  - The core request is a compilation/runtime error, blank screen, crash, or SDK compatibility issue (`ARKUI-04`).

ARKUI-02
UI Framework and Page Logic

ARKUI-02
UI 框架与页面逻辑

yaml
scene_id: ARKUI-02
scene_name: UI Framework and Page Logic
resource_refs:
  - ./references/arkui-02-route.md
intent_signals:
  - gestures / keyboard / touch / stylus / focus / focusable / requestFocus / nextFocus / focus box
  - navigation / Navigation / Router / page stack / dialogs / menus / Toast / Popup / Sheet / Dialog / animation / transitions / animateTo / TransitionEffect / geometryTransition
  - Column / Row / Stack / Flex / RelativeContainer / GridRow / Tabs / List / Grid / WaterFlow / ArcList / Scroll / Swiper / page skeleton / responsive layout / breakpoints / FrameNode / Modifier / RenderNode / BuilderNode / XComponent / Image / ImageAnimator / Text / TextInput / RichEditor / SymbolGlyph
applies_when:
  - The request builds pages, flows, interactions, temporary interfaces, or animations using ArkUI components and framework capabilities.
  - The request handles navigation, gestures, focus, dialogs, menus, animation transitions, layouts, images, lists, text, custom nodes, or page skeletons.
not_applies_when:
  - The request only confirms basic syntax, conditional rendering, Builder, or basic reuse (`ARKUI-01`).
  - The main issue is state decorators, state synchronization, or V1/V2 mixing (`ARKUI-03`).
  - The main issue is compilation/runtime failure rather than UI logic (`ARKUI-04`).
yaml
scene_id: ARKUI-02
scene_name: UI Framework and Page Logic
resource_refs:
  - ./references/arkui-02-route.md
intent_signals:
  - gestures / keyboard / touch / stylus / focus / focusable / requestFocus / nextFocus / focus box
  - navigation / Navigation / Router / page stack / dialogs / menus / Toast / Popup / Sheet / Dialog / animation / transitions / animateTo / TransitionEffect / geometryTransition
  - Column / Row / Stack / Flex / RelativeContainer / GridRow / Tabs / List / Grid / WaterFlow / ArcList / Scroll / Swiper / page skeleton / responsive layout / breakpoints / FrameNode / Modifier / RenderNode / BuilderNode / XComponent / Image / ImageAnimator / Text / TextInput / RichEditor / SymbolGlyph
applies_when:
  - The request builds pages, flows, interactions, temporary interfaces, or animations using ArkUI components and framework capabilities.
  - The request handles navigation, gestures, focus, dialogs, menus, animation transitions, layouts, images, lists, text, custom nodes, or page skeletons.
not_applies_when:
  - The request only confirms basic syntax, conditional rendering, Builder, or basic reuse (`ARKUI-01`).
  - The main issue is state decorators, state synchronization, or V1/V2 mixing (`ARKUI-03`).
  - The main issue is compilation/runtime failure rather than UI logic (`ARKUI-04`).

ARKUI-03
State Management

ARKUI-03
状态管理

yaml
scene_id: ARKUI-03
scene_name: State Management
resource_refs:
  - ./references/arkui-03-route.md
intent_signals:
  - @State / @Prop / @Link / @Provide / @Consume / @Watch / @Track / @ObjectLink / @Observe
  - @Local / @Param / @Event / @Monitor / @Provider / @Consumer / @Computed / @ObservedV2 / @Trace
  - AppStorage / AppStorageV2 / state management / component synchronization / application state / V1/V2 mixing
applies_when:
  - The request passes or shares state between components.
  - The request uses V1 or V2 state management, state observation, computed state, two-way binding, state-driven animation, component reuse, freezing, or loop rendering.
  - The request explicitly concerns V1/V2 mixing or using V2 components with V1 components, or vice versa.
not_applies_when:
  - The request is only layout, navigation, interaction, dialogs, animation, focus, images, lists, or text (`ARKUI-02`).
  - The request is only basic syntax, Builder, conditional rendering, or basic reuse (`ARKUI-01`).
  - The issue is a compilation/runtime failure whose root cause is not yet tied to state management; start with `ARKUI-04`.
yaml
scene_id: ARKUI-03
scene_name: State Management
resource_refs:
  - ./references/arkui-03-route.md
intent_signals:
  - @State / @Prop / @Link / @Provide / @Consume / @Watch / @Track / @ObjectLink / @Observe
  - @Local / @Param / @Event / @Monitor / @Provider / @Consumer / @Computed / @ObservedV2 / @Trace
  - AppStorage / AppStorageV2 / state management / component synchronization / application state / V1/V2 mixing
applies_when:
  - The request passes or shares state between components.
  - The request uses V1 or V2 state management, state observation, computed state, two-way binding, state-driven animation, component reuse, freezing, or loop rendering.
  - The request explicitly concerns V1/V2 mixing or using V2 components with V1 components, or vice versa.
not_applies_when:
  - The request is only layout, navigation, interaction, dialogs, animation, focus, images, lists, or text (`ARKUI-02`).
  - The request is only basic syntax, Builder, conditional rendering, or basic reuse (`ARKUI-01`).
  - The issue is a compilation/runtime failure whose root cause is not yet tied to state management; start with `ARKUI-04`.

ARKUI-04
Compilation and Runtime

ARKUI-04
编译与运行时

yaml
scene_id: ARKUI-04
scene_name: Compilation and Runtime
resource_refs:
  - ./references/compilation-runtime-scenario-development.md
intent_signals:
  - compilation error / build failure / ArkTS type error / import / export / module path
  - runtime exception / blank screen / crash / abnormal lifecycle / resource-load failure
  - hvigor / oh-package.json5 / module.json5 / SDK compatibility / API compatibility
applies_when:
  - The request troubleshoots ArkTS compilation, build, dependency, module, or SDK/API compatibility problems.
  - The request troubleshoots runtime exceptions, blank screens, crashes, lifecycle issues, or resource loading failures.
  - The request checks whether an ArkUI pattern is constrained by language, compilation, runtime, or version rules.
not_applies_when:
  - The issue is explicitly a UI page, interaction, navigation, dialog, animation, focus, layout, image, list, or text implementation issue (`ARKUI-02`).
  - The issue is explicitly a state decorator, state synchronization, or V1/V2 mixing issue (`ARKUI-03`).
  - The request only asks about basic ArkUI syntax or reuse (`ARKUI-01`).
yaml
scene_id: ARKUI-04
scene_name: Compilation and Runtime
resource_refs:
  - ./references/compilation-runtime-scenario-development.md
intent_signals:
  - compilation error / build failure / ArkTS type error / import / export / module path
  - runtime exception / blank screen / crash / abnormal lifecycle / resource-load failure
  - hvigor / oh-package.json5 / module.json5 / SDK compatibility / API compatibility
applies_when:
  - The request troubleshoots ArkTS compilation, build, dependency, module, or SDK/API compatibility problems.
  - The request troubleshoots runtime exceptions, blank screens, crashes, lifecycle issues, or resource loading failures.
  - The request checks whether an ArkUI pattern is constrained by language, compilation, runtime, or version rules.
not_applies_when:
  - The issue is explicitly a UI page, interaction, navigation, dialog, animation, focus, layout, image, list, or text implementation issue (`ARKUI-02`).
  - The issue is explicitly a state decorator, state synchronization, or V1/V2 mixing issue (`ARKUI-03`).
  - The request only asks about basic ArkUI syntax or reuse (`ARKUI-01`).

Additional Guidance

补充指导

  • For detailed implementation decisions, continue into the matched scene's 
    decisions
    section and reference documents.
  • Do not mix V1 and V2 decorators in the same component without an explicit requirement and documented bridge strategy.
  • When a root cause crosses scene boundaries, retain the original scene and add the related scene to 
    secondary_scenes
    .
  • Always report unresolved API/version boundaries instead of inventing unsupported code.
  • 如需详细的实现决策，继续查看匹配场景的 
    decisions
    部分及相关参考文档。
  • 除非有明确要求和有文档记录的桥接策略，否则不要在同一个组件中混用 V1 和 V2 装饰器。
  • 当根因跨越场景边界时，保留原场景，并将相关场景加入 
    secondary_scenes
    。
  • 始终报告尚未解决的 API/版本边界，不要杜撰不受支持的代码。