arkts-syntax-assistant

ArkTS 语法助手

中文文档

---

概述

ArkTS 是 OpenHarmony 应用的默认开发语言。它基于 TypeScript 构建，并增强了静态类型，以提高程序的稳定性和性能。

核心特性

• 静态类型：所有类型都在编译时确定，减少运行时检查
• 无动态对象布局：对象结构在编译时固定，无法在运行时修改
• 受限运算符：部分运算符的行为受到限制，以鼓励更清晰的代码语义
• 无结构化类型：目前不支持结构化类型

参考文档

场景	文档
语法学习	references/en/introduction-to-arkts.md
快速概览	references/en/arkts-get-started.md
TS 迁移	references/en/typescript-to-arkts-migration-guide.md
迁移背景	references/en/arkts-migration-background.md
性能	references/en/arkts-high-performance-programming.md
更多示例	references/en/arkts-more-cases.md

工作流

1. 语法问题

User Question -> Identify Question Type -> Consult Documentation -> Provide Code Example

常见语法问题：

• 变量声明 -> 使用 let/const 并显式指定类型或使用类型推断
• 函数定义 -> 支持可选参数、默认值、剩余参数和箭头函数
• 类和接口 -> 必须初始化字段，支持继承和实现
• 泛型 -> 支持约束和默认值
• 空值安全 -> 可空类型（(T | null)）、非空断言（(!)）、可选链（(?.)）

2. TypeScript 迁移

Identify TS Code -> Check Incompatible Features -> Consult Migration Rules -> Provide ArkTS Alternative

关键迁移规则速查：

TypeScript	ArkTS 替代方案
var x	let x
any/unknown	具体类型
{n: 42} 对象字面量	先定义类/接口
[index: T]: U 索引签名	Record<T, U>
A & B 交叉类型	interface C extends A, B
function(){} 函数表达式	() => {} 箭头函数
<Type>value 类型断言	value as Type
解构 [a, b] = arr	单独访问 arr[0]、arr[1]
for..in	for 循环或 for..of
构造函数参数属性	显式声明字段

3. 性能优化

Analyze Code -> Identify Performance Issues -> Consult Optimization Guide -> Provide Solutions

高性能编程要点：

• 声明：不变量使用 const；避免混用整数和浮点数
• 循环：提取循环不变量；避免数值溢出
• 函数：优先传递参数而非使用闭包；避免使用可选参数
• 数组：数值使用 TypedArray；避免稀疏数组和联合类型数组
• 异常：避免在循环中抛出异常；改用返回值

4. 编译错误解决

Get Error Message -> Search Migration Rules -> Find Related Case -> Provide Fix

常见问题

Q：如何处理 JSON.parse 的返回值？

// Error
let data = JSON.parse(str);

// Correct
let data: Record<string, Object> = JSON.parse(str);

Q：如何定义对象类型？

// TypeScript syntax (not supported in ArkTS)
type Person = { name: string, age: number }

// ArkTS syntax
interface Person {
  name: string;
  age: number;
}

// Using object literal
let p: Person = { name: 'John', age: 25 };

Q：如何替换 globalThis？

// Error
globalThis.value = 'xxx';

// Use singleton pattern
export class GlobalContext {
  private constructor() {}
  private static instance: GlobalContext;
  private _objects = new Map<string, Object>();

  public static getContext(): GlobalContext {
    if (!GlobalContext.instance) {
      GlobalContext.instance = new GlobalContext();
    }
    return GlobalContext.instance;
  }

  getObject(key: string): Object | undefined {
    return this._objects.get(key);
  }

  setObject(key: string, value: Object): void {
    this._objects.set(key, value);
  }
}

Q：如何处理 catch 中的错误类型？

// Error
try {} catch (e: BusinessError) {}

// Correct
try {} catch (error) {
  let e: BusinessError = error as BusinessError;
}

Q：如何使用 Record 类型？

// TypeScript index signature
function foo(data: { [key: string]: string }) {}

// ArkTS Record
function foo(data: Record<string, string>) {}

// Usage example
let map: Record<string, number> = {
  'John': 25,
  'Mary': 21,
};

Q：如何用工厂函数替换构造函数签名？

// TypeScript constructor signature
type ControllerCtor = {
  new (value: string): Controller;
}

// ArkTS factory function
type ControllerFactory = () => Controller;

class Menu {
  createController: ControllerFactory = () => {
    return new Controller('default');
  }
}

禁用的标准库 API

以下 API 在 ArkTS 中被禁用：

• 全局：eval
• Object：__proto__、defineProperty、freeze、getPrototypeOf 等
• Reflect：apply、construct、defineProperty 等
• Proxy：所有处理器方法

构建脚本

scripts 目录提供用于 ArkTS 项目的快速编译脚本 （包括安装依赖项）：

平台	脚本	用途
macOS/Linux	scripts/run.sh	执行 ohpm install + hvigorw assembleApp
Windows	scripts/run.ps1	执行 ohpm install + hvigorw assembleApp

用法：

# macOS/Linux
bash scripts/run.sh

# Windows PowerShell
.\scripts\run.ps1

脚本执行步骤：

1. 安装依赖项（ohpm install --all）
2. 构建项目（hvigorw assembleApp）

强制要求

重要：此技能生成 ArkTS 代码时，必须遵循以下工作流：

1. 编译验证：生成代码后，必须使用构建脚本编译项目：

   • macOS/Linux：bash scripts/run.sh
   • Windows：.\scripts\run.ps1

2. 重试策略：如果编译失败：

   • 分析错误输出
   • 修复问题并重试编译
   • 最多进行 3 次编译尝试

3. 用户介入：3 次编译尝试均失败后，使用 AskUserQuestion：

   Question: Compilation failed after 3 attempts. How would you like to proceed?
   Options:
   - Continue retrying (attempt another fix)
   - Manual intervention (I'll wait for your guidance)
   - Skip compilation (proceed without verification)
   

4. 错误报告：发生编译失败时，始终显示完整的编译错误输出。

答复指南

1. 优先提供代码示例：展示正确与错误语法的对比
2. 引用官方文档：如需详细说明，引导用户查阅 references/ 中的相应文档
3. 解释原因：说明 ArkTS 为何有此限制（性能、稳定性）
4. 提供替代方案：对于不支持的功能，提供可行的替代方案

许可证

MIT 许可证——详见 LICENSE.txt