arkts-development

ArkTS 开发

使用 ArkTS 和 ArkUI 声明式 UI 框架构建 HarmonyOS 应用。

快速入门

创建一个基本组件：

@Entry
@Component
struct HelloWorld {
  @State message: string = 'Hello, ArkTS!';

  build() {
    Column() {
      Text(this.message)
        .fontSize(30)
        .fontWeight(FontWeight.Bold)
      Button('Click Me')
        .onClick(() => { this.message = 'Button Clicked!'; })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

状态管理装饰器

V1（传统方式）

装饰器	用法	说明
@State	@State count: number = 0	组件内部状态
@Prop	@Prop title: string	父级 → 子级（单向）
@Link	@Link value: number	父级 ↔ 子级（双向，使用 $varName）
@Provide/@Consume	跨层级	祖先 → 后代
@Observed/@ObjectLink	嵌套对象	深度对象观测

V2（推荐 - API 12+）

装饰器	用法	说明
@ComponentV2	@ComponentV2 struct MyComp	启用 V2 状态管理
@Local	@Local count: number = 0	内部状态（无外部初始化）
@Param	@Param title: string = ""	父级 → 子级（单向，高效）
@Event	@Event onChange: () => void	子级 → 父级（回调）
@ObservedV2	@ObservedV2 class Data	类观测
@Trace	@Trace name: string	属性级跟踪
@Computed	@Computed get value()	缓存计算属性
@Monitor	@Monitor('prop') onFn()	监视变更，包含变更前后状态
@Provider/@Consumer	跨层级	在树中进行双向同步

完整的 V2 指南请参阅 references/state-management-v2.md。

常见布局

// Vertical
Column({ space: 10 }) { Text('A'); Text('B'); }
  .alignItems(HorizontalAlign.Center)

// Horizontal
Row({ space: 10 }) { Text('A'); Text('B'); }
  .justifyContent(FlexAlign.SpaceBetween)

// Stack (overlay)
Stack({ alignContent: Alignment.Center }) {
  Image($r('app.media.bg'))
  Text('Overlay')
}

// List with ForEach
List({ space: 10 }) {
  ForEach(this.items, (item: string) => {
    ListItem() { Text(item) }
  }, (item: string) => item)
}

组件生命周期

@Entry
@Component
struct Page {
  aboutToAppear() { /* Init data */ }
  onPageShow() { /* Page visible */ }
  onPageHide() { /* Page hidden */ }
  aboutToDisappear() { /* Cleanup */ }
  build() { Column() { Text('Page') } }
}

导航

import { router } from '@kit.ArkUI';

// Push
router.pushUrl({ url: 'pages/Detail', params: { id: 123 } });

// Replace
router.replaceUrl({ url: 'pages/New' });

// Back
router.back();

// Get params
interface RouteParams {
  id: number;
  title?: string;
}
const params = router.getParams() as RouteParams;

网络请求

import { http } from '@kit.NetworkKit';

const req = http.createHttp();
const res = await req.request('https://api.example.com/data', {
  method: http.RequestMethod.GET,
  header: { 'Content-Type': 'application/json' }
});
if (res.responseCode === 200) {
  const data = JSON.parse(res.result as string);
}
req.destroy();

本地存储

import { preferences } from '@kit.ArkData';

const prefs = await preferences.getPreferences(this.context, 'store');
await prefs.put('key', 'value');
await prefs.flush();
const val = await prefs.get('key', 'default');

ArkTS 语言限制

为确保性能和安全性，ArkTS 的规则比 TypeScript 更严格：

禁止使用	替代方案
any、unknown	显式类型、接口
var	let、const
动态属性访问 obj['key']	固定对象结构
for...in、delete、with	for...of、数组方法
#privateField	private 关键字
结构化类型	显式使用 implements/extends

完整的 TypeScript → ArkTS 迁移详情请参阅 references/migration-guide.md。

命令行测试（hvigorw）

构建、清理、打包和设备安装由 harmonyos-build-deploy 技能负责；这些工作流请使用该技能。完整的 hvigorw 标志参考请参阅 references/hvigor-commandline.md。

测试命令：

# Run all tests for a module
hvigorw onDeviceTest -p module=entry -p coverage=true --no-daemon   # On-device
hvigorw test -p module=entry --no-daemon                            # Local (host-side)

# Run a single test suite or single test (on-device)
hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName\"}" --no-daemon
hvigorw onDeviceTest -p module=entry -p testParam="{\"unittest\":\"TestClassName#testMethodName\"}" --no-daemon

代码检查工具（codelinter）

codelinter 是用于检查和修复 ArkTS/TS 文件的工具。

# Basic usage
codelinter                           # Check current project
codelinter /path/to/project          # Check specified project
codelinter -c ./code-linter.json5    # Use custom rules

# Check and auto-fix
codelinter --fix
codelinter -c ./code-linter.json5 --fix

# Output formats
codelinter -f json -o ./report.json  # JSON report
codelinter -f html -o ./report.html  # HTML report

# Incremental check (Git changes only)
codelinter -i

# CI/CD with exit codes
codelinter --exit-on error,warn      # Non-zero exit on error/warn

参数	说明
-c, --config <file>	指定规则配置文件
--fix	自动修复支持的问题
-f, --format	输出格式：default/json/xml/html
-o, --output <file>	将结果保存到文件
-i, --incremental	仅检查 Git 更改的文件
-p, --product <name>	指定产品
-e, --exit-on <levels>	退出代码级别：error,warn,suggestion

完整参考请参阅 references/codelinter.md。

堆栈跟踪解析器（hstack）

hstack 可将 Release 构建中经过混淆的崩溃堆栈还原为源代码位置。

# Parse crash files directory
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir

# Parse with C++ symbols
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir

# Parse single crash stack
hstack -c "at func (entry|entry|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir

参数	说明
-i, --input	崩溃文件目录
-c, --crash	单个崩溃堆栈字符串
-o, --output	输出目录（与 -c 搭配时为文件）
-s, --sourcemapDir	Sourcemap 文件目录
--so, --soDir	共享对象（.so）文件目录
-n, --nameObfuscation	NameCache 文件目录

要求：

• 必须提供 -i 或 -c（不能同时提供）
• 必须至少提供 -s 或 --so
• 若要还原方法名称，请同时提供 -s 和 -n

完整参考请参阅 references/hstack.md。

代码混淆（ArkGuard）

在 build-profile.json5 中启用：

"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["./obfuscation-rules.txt"]
    }
  }
}

obfuscation-rules.txt 中的常用规则：

-enable-property-obfuscation      # Property name obfuscation
-enable-toplevel-obfuscation      # Top-level scope obfuscation
-enable-filename-obfuscation      # Filename obfuscation
-keep-property-name apiKey        # Whitelist specific names

完整指南请参阅 references/arkguard-obfuscation.md。

参考文件

• 状态管理 V2：references/state-management-v2.md - V2 状态管理完整指南（@ComponentV2、@Local、@Param、@Event、@ObservedV2、@Trace、@Computed、@Monitor、@Provider、@Consumer）
• 从 V1 迁移到 V2：references/state-management-v2-migration.md - 从 V1 装饰器逐步迁移到 V2
• V2 最佳实践：references/state-management-v2-practices.md - V2 最佳实践和故障排查
• 迁移指南：references/migration-guide.md - TypeScript 到 ArkTS 的完整迁移规则和示例
• 组件模式：references/component-patterns.md - 高级组件模式和最佳实践
• API 参考：references/api-reference.md - 常用 HarmonyOS API
• ArkGuard 混淆：references/arkguard-obfuscation.md - 代码混淆配置和故障排查
• Hvigor 命令行：references/hvigor-commandline.md - 完整的 hvigorw 构建工具参考
• CodeLinter：references/codelinter.md - 代码检查和修复工具
• Hstack：references/hstack.md - Release 构建的崩溃堆栈跟踪解析器

开发环境

• IDE：DevEco Studio
• SDK：HarmonyOS SDK
• 模拟器：DevEco Studio 内置模拟器

相关技能

• 构建和部署：构建、打包和安装到设备，请参阅 harmonyos-build-deploy 技能