openharmonyinsight/arkts-static-spec

ArkTS Static Language Specification

Complete reference for the ArkTS programming language, including official specification and TypeScript migration guide.

⚠️ 使用原则（重要）

在使用本 skill 回答问题时，必须严格遵守以下原则：

1. 严格按照 skill 文档内容回答

   • 所有回答必须基于 spec/ 和 cookbook/ 目录下的文档内容
   • 不添加文档之外的假设或推断

2. 明确标注文档未说明的内容

   • 如果 skill 文档中没有明确说明某个特性，必须在回答中标注：
     • "⚠️ skill 文档未明确说明，待使用者自行确认"
   • 不要基于 TypeScript 或其他语言的特性进行假设

3. 将 ArkTS 视为独立的静态语言

   • ArkTS 是一个独立的静态语言，不是 TypeScript 的超集
   • 不要假设 TypeScript 的特性在 ArkTS 中都支持
   • 以 ArkTS 官方规范为准，不以 TypeScript 语法为准

---

目录结构

本技能分为两个主要部分：

arkts-static-spec/
├── spec/              # ArkTS 语言规范
│   ├── types.md       # 类型系统
│   ├── classes.md     # 类声明
│   ├── expressions.md # 表达式和运算符
│   ├── statements.md  # 语句和控制流
│   ├── generics.md    # 泛型
│   ├── annotations.md # 注解和装饰器
│   ├── modules.md     # 模块系统
│   ├── lexical.md     # 词法结构
│   ├── names.md       # 声明和作用域
│   ├── conversions.md # 类型转换
│   ├── interfaces.md  # 接口
│   ├── enums.md       # 枚举
│   ├── errors.md      # 错误处理
│   ├── concurrency.md # 并发和异步
│   ├── stdlib.md      # 标准库
│   └── experimental.md# 实验性特性
│
└── cookbook/          # TypeScript 迁移指南
    ├── index.md       # 迁移指南总览
    ├── recipes.md     # 详细迁移食谱（144+ 项）
    └── compatibility.md # TypeScript vs ArkTS 兼容性详情

---

第一部分：ArkTS 语言规范 (spec/)

官方 ArkTS 语言规范参考，按主题组织。

核心规范文件

| 文件 | 内容 | 适用场景 | |------|------|---------| | types.md | 类型系统、预定义类型 | 查询类型、类型推断、默认值 | | classes.md | 类声明、访问修饰符、继承 | 定义类、实现接口、继承 | | expressions.md | 运算符、优先级 | 表达式求值、运算符使用 | | statements.md | 控制流、循环、try-catch | if/else、for、while、异常处理 | | generics.md | 泛型类型和函数 | 编写泛型代码、类型约束 | | annotations.md | 装饰器和元数据 | 使用 @Decorator | | modules.md | Import/export、命名空间 | 模块组织、导入导出 | | lexical.md | 标识符、关键字、字面量 | 词法分析、语法规则 | | names.md | 声明、作用域、可见性 | 变量作用域、命名冲突 | | conversions.md | 类型转换和上下文 | 类型转换规则 | | interfaces.md | 接口声明和实现 | 定义接口、实现契约 | | enums.md | 枚举类型 | 使用枚举 | | errors.md | 错误处理和 try 语句 | 异常处理、throw 语句 | | concurrency.md | Async/await、TaskPool | 异步编程、并发 | | stdlib.md | 标准库 API | 内置对象和函数 | | experimental.md | 实验性特性 | FixedArray、char、函数重载等 |

---

第二部分：TypeScript 迁移指南 (cookbook/)

从 TypeScript 迁移到 ArkTS 的完整指南，包含 144+ 个详细迁移食谱和兼容性说明。

迁移指南文件

| 文件 | 内容 | 适用场景 | |------|------|---------| | index.md | 迁移指南总览 | 了解迁移原因、设计原则、快速入门 | | recipes.md | 144+ 详细迁移食谱 | 查询具体语法如何转换、常见问题解决 | | compatibility.md | TypeScript vs ArkTS 兼容性详情 | 了解行为差异、数值语义、数组赋值等 |

---

快速开始

ArkTS 类型注解

let num: number = 42
const str: string = "hello"
let arr: number[] = [1, 2, 3]

ArkTS 类声明

class Person {
  private name: string
  public age: number

  constructor(name: string, age: number) {
    this.name = name
    this.age = age
  }

  public introduce(): string {
    return `I'm ${this.name}, ${this.age} years old`
  }
}

泛型函数

function identity<T>(value: T): T {
  return value
}

let num = identity<number>(42)
let str = identity<string>("hello")

异步函数

async function fetchData(): Promise<string> {
  const response = await fetch("https://example.com")
  return await response.text()
}

---

类型系统速查

预定义类型

| 分类 | 类型 | 说明 | |------|------|------| | 数值 | byte, short, int, long, float, double, number, bigint | 整数和浮点数 | | 布尔 | boolean | true/false | | 字符 | char | 实验性，使用 c'A' 语法 | | 字符串 | string | 文本数据 | | 特殊 | void, null, undefined, never | 特殊用途 | | 对象 | Object, object | 对象类型 |

注意：any 和 unknown 在 ArkTS 中不支持，必须使用显式类型。

类型运算符

• 联合类型：T | U
• 交集类型：T & U
• 数组类型：T[] 或 Array<T>
• 只读数组：readonly T[]

---

TypeScript 迁移速查

常见转换

| TypeScript | ArkTS | 说明 | |-----------|-------|------| | var x = 10 | let x: number = 10 | 必须使用 let，明确类型 | | let x: any | let x: SpecificType | 禁止 any，使用具体类型 | | let {a, b} = obj | let a = obj.a; let b = obj.b | 不支持对象解构 | | "prop" in obj | obj instanceof Class | 不支持 in 运算符 | | import m = require("mod") | import * as m from "mod" | 使用 ES6 import |

代码保持率

• 完全支持（无需修改）：90% - 97%
• 部分支持（少量重构）：约 2% - 8%
• 不支持（需要重构）：约 1%

---

查找指南

查询 ArkTS 语言规范

根据主题选择对应的规范文件：

• 类型相关问题：查看 spec/types.md、spec/conversions.md
• 面向对象特性：查看 spec/classes.md、spec/interfaces.md、spec/enums.md
• 语法相关问题：查看 spec/lexical.md、spec/expressions.md、spec/statements.md
• 泛型编程：查看 spec/generics.md
• 模块系统：查看 spec/modules.md
• 并发编程：查看 spec/concurrency.md
• 装饰器和注解：查看 spec/annotations.md
• 标准库 API：查看 spec/stdlib.md
• 实验性特性：查看 spec/experimental.md

查询 TypeScript 迁移问题

• 迁移概述和原则：查看 cookbook/index.md
• 具体语法如何转换：查看 cookbook/recipes.md
• 行为差异和兼容性：查看 cookbook/compatibility.md

---

ArkTS vs TypeScript 关键差异

1. 静态类型强制执行

| 特性 | TypeScript | ArkTS | |------|-----------|-------| | 静态类型 | 可选 | 强制 | | any 类型 | 允许 | 禁止 | | unknown 类型 | 允许 | 禁止 | | 类型推断 | 可选 | 必须 |

2. 对象布局固定

| 特性 | TypeScript | ArkTS | |------|-----------|-------| | 运行时添加属性 | 允许（用 as any 绕过） | 禁止 | | 删除属性 | 允许（用 as any 绕过） | 禁止 | | 对象布局 | 可变 | 固定 |

3. Null 安全

| 特性 | TypeScript | ArkTS | |------|-----------|-------| | null 赋值给非空类型 | 可选模式下禁止 | 强制禁止 | | undefined 作为值 | 允许 | 严格限制 |

4. 数值语义

let n = 1
console.log(n / 2)

// TypeScript: 0.5（浮点除法）
// ArkTS: 0（整数除法）

---

访问修饰符

| 修饰符 | 可访问性 | |--------|---------| | public | 任何地方（默认） | | private | 仅类内部 | | protected | 类和子类 | | readonly | 初始化后不可变 | | static | 类级别，非实例级别 |

---

常见设计模式

单例模式

class Singleton {
  private static instance: Singleton
  private constructor() {}

  public static getInstance(): Singleton {
    if (!Singleton.instance) {
      Singleton.instance = new Singleton()
    }
    return Singleton.instance
  }
}

工厂模式

interface Product {
  operation(): string
}

class ConcreteProductA implements Product {
  operation(): string {
    return "Product A"
  }
}

class Factory {
  static create(type: string): Product {
    if (type === "A") {
      return new ConcreteProductA()
    }
    throw new Error("Unknown product type")
  }
}

---

为什么选择 ArkTS？

优势

1. 程序稳定性

   • 严格类型检查，减少运行时错误
   • 编译时类型验证
   • 字段必须初始化

2. 程序性能

   • 编译为字节码，执行更快
   • 消除运行时类型检查开销
   • 针对移动设备优化

3. 代码可读性

   • 静态类型让代码意图清晰
   • 对象布局固定，行为可预测

迁移成本

• 代码保持率：90% - 97%（遵循最佳实践）
• 主要调整：移除 any、使用 let 代替 var
• 学习曲线：TypeScript 开发者易于上手

---

控制流速查

if-else

if (condition) {
  // ...
} else {
  // ...
}

循环

// while 循环
while (condition) {
  // ...
}

// for 循环
for (let i: int = 0; i < 10; i++) {
  // ...
}

// for-of 循环
for (const item of array) {
  // ...
}

错误处理

try {
  // 可能抛出错误的代码
} catch (e: Error) {
  // 处理错误
} finally {
  // 清理（总是执行）
}

---

迁移检查清单

优先级 1：必须修复（ERROR 级别）

• [ ] 替换所有 var 为 let
• [ ] 移除所有 any / unknown 类型
• [ ] 移除 Symbol() API 使用
• [ ] 移除私有 # 标识符
• [ ] 确保类型和命名空间名称唯一
• [ ] 移除非标识符属性名
• [ ] 移除调用签名和构造签名类型
• [ ] 移除 in 运算符
• [ ] 移除对象解构
• [ ] 替换 require 为标准 import
• [ ] 移除 export = 语法

优先级 2：代码改进建议（WARNING 级别）

• [ ] 检查字段初始化
• [ ] 审查对象属性访问模式
• [ ] 确保类型安全

---

完整参考

• ArkTS 语言规范：spec/
• TypeScript 迁移指南：cookbook/
• 原始规范文档：D:\arkcompiler\runtime_core\static_core\plugins\ets\doc\spec\
• 原始 Cookbook：D:\arkcompiler\runtime_core\static_core\plugins\ets\doc\cookbook\