HarmonyOS Application Development

⚠️ CRITICAL: Source Attribution Required

You MUST NOT fabricate or hallucinate any information. Every piece of technical guidance, API usage, code pattern, or best practice MUST be traceable to official HarmonyOS documentation.

Mandatory Rules

Always cite sources: When providing guidance, include the official documentation URL or reference path
No guessing: If you cannot find information in official docs, explicitly state "未在官方文档中找到相关说明" and suggest searching the official docs
Verify before claiming: Never claim an API exists or works in a certain way without verification from official sources
Distinguish facts from suggestions: Clearly mark when something is:
- 官方文档规定 (official docs requirement)
- 推荐实践 (recommended practice)
- 常见模式 (common pattern)
- 个人建议 (personal suggestion - use sparingly)

Citation Format

When referencing official documentation:

来源: [文档标题](URL)
> 引用原文（如适用）

Example:

来源: [API参考-组件生命周期](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/...)
> aboutToDisappear函数在组件销毁前调用，适合做资源清理。

When Documentation is Unavailable

If you cannot find information in official docs:

State clearly: "⚠️ 未在官方文档中找到关于 [topic] 的明确说明"
Suggest user check: official docs, DevEco Studio hints, or community resources
Do NOT fabricate or assume based on similar frameworks (React, Flutter, etc.)

Pre-Development Checklist

Confirm before starting a new project or first-time development:

API version: Default API 20+; state explicitly if backward compatibility needed
Target device: PC / Phone / Tablet / Wearable / Multi-device
Scenario: Greenfield / Iteration / Architecture design
Project structure: HAP package layout, module organization

Core Technology Stack

ArkTS Language

TypeScript-based extension
State decorators: @ObservedV2, @Trace, @Local, @Provider
Component decorators: @Component, @ComponentV2, @Entry, @Builder
Rendering: on-demand updates, minimal re-renders

ArkUI Component System

Declarative UI construction
Layout containers: Column / Row / Stack / Flex / Grid
List rendering: ForEach / LazyForEach
Animation: property animation, transition, shared element transition

Common Patterns

State Management

Component-local: @Local
Cross-component: @Provider + @Consumer
Deep reactivity: @ObservedV2 + @Trace

Page Navigation

Router.pushUrl() - push page
Router.replaceUrl() - replace page
Router.back() - go back

Data Persistence

Preferences: lightweight key-value storage
RDB: relational database
Distributed data: cross-device sync

Network

@kit.NetworkKit http - HTTP requests
WebSocket - persistent connections
Upload/Download: @kit.BasicServicesKit request

Official Documentation

Primary Documentation Source (MANDATORY)

Use context7 MCP tool to fetch the latest HarmonyOS documentation before providing any guidance.

# Example workflow:
1. Use mcp__context7__resolve-library-id with query "harmonyos arkts"
2. Use mcp__context7__query-docs to fetch relevant documentation
3. Cite the documentation source in your response

Official Documentation Links

Release notes: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/overview-allversion
Dev guide: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/application-dev-guide
API reference: https://developer.huawei.com/consumer/cn/doc/harmonyos-references/development-intro-api
Best practices: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-best-practices-overview
FAQ: https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-multi-device-scenario

Documentation Query Protocol

When answering HarmonyOS development questions:

First: Query context7 for relevant documentation
Then: If context7 doesn't have the answer, search official docs links above
Finally: If no official documentation found, explicitly state:
⚠️ 未在官方文档中找到关于 [topic] 的明确说明，建议查阅：
- Dev guide
- API reference
- DevEco Studio 内置提示
Never fabricate API signatures, method names, or behavior patterns

References

Load detailed docs as needed (all include source citations):

State management: references/state-management.md
UI components: references/ui-components.md
Data persistence: references/data-persistence.md
Network: references/network.md
Permissions: references/permissions.md
Performance: references/performance.md

harmonyos-dev