Skip to content

ArkTS 语言基础:从 TypeScript 到 ArkTS ​

本篇要点:能把一段 TypeScript 代码改写成能通过 ArkTS 编译的等价写法,并在 TaskPool 与 Worker 之间给出有理由的选择。 前置:会 TypeScript 的类型标注、装饰器与 ESM 模块即可。这一章是整个类目的起点,《声明式 UI:组件、布局与样式》的声明式 UI 与《状态管理:@State 家族与 V2 状态管理》的状态管理都跑在这套约束之上。

为什么需要它 ​

23 条错误,出现在把 .ts 改成 .ets 的第一次编译上。

2026 年 3 月,一个做记账的团队把 Web 端的对账逻辑搬进鸿蒙工程,遇到的就是这件事。最扎眼的两条长这样:10605069,规则 arkts-no-destruct-assignment,指向 const { amount, date } = bill;;10605099,规则 arkts-no-spread,指向 return { ...bill, amount: 0 };。

他们先怀疑工具链。换 SDK、删 oh_modules、关掉 ESLint,报错一条没少。第 3 个小时才有人去读规则名,发现这两条和工具链毫无关系,是语言层不让写。

{...bill, amount: 0} 在 TypeScript 里会新建一个对象、逐字段抄过去,对象布局在运行时被改变了;ArkTS 要求布局在编译期就固定,于是这条路被直接封死。换成 new Bill(bill.id, 0, bill.note) 就过了。

固定布局换来的是可预测的开销:对象形状不变,编译器能按偏移量取字段,AOT(Ahead-of-Time,提前编译)产物不必每次读属性都查一张表。这条因果链是理解后面所有限制的钥匙——每一条禁令背后,都对应一处"运行时才能决定"的开销被提前到了编译期。

基线先钉住。截至 2026 年 11 月,HarmonyOS 6.0.0 对应 API 20,配套 DevEco Studio 6.0.0,SDK 基于 OpenHarmony 6.0.0.47。本篇结论以这套版本为准。工程若还停在 API 9 到 API 18 之间,装饰器和并发接口的细节会有出入,改之前先看文档的版本标注。

核心概念 ​

固定布局:为什么连删一个字段都算错 ​

定义:ArkTS 要求一个对象的属性集合在编译期确定,运行期间不能增删属性,也不能把别的类型塞进已有字段。

拿集装箱打比方。TypeScript 的对象像散装货,随时能往里再塞一箱;ArkTS 的对象像标准集装箱,箱格出厂就焊死了。你确实需要多一个字段,正确做法是新做一个箱子——新类或子类,而不是在旧箱子上开洞。

反例很短:

arkts
class Point {
  x: number = 0;
  y: number = 0;
}

let p = new Point();
(p as any).z = 1;   // any 本身被禁,属性也不存在
delete p.x;         // arkts-no-delete

运行结果:(p as any).z = 1 报 any 被禁用,delete p.x 报 arkts-no-delete,两条都停在编译期,不会留到运行时。

配套的禁令还有一串:属性名必须是合法标识符(obj['a-b'] 不行)、不支持 index signature、不支持 Symbol() 当键、不能给原型赋值、不支持 in 运算符。这些在 TypeScript 里都合法。

有一条从 TS 过来最容易吃亏,叫不支持 structural typing(结构化类型)。两个类只要形状一样,TS 就允许互相赋值;ArkTS 只认继承和 implements 关系,没有这层关系就是两个完全不同的类型。把接口返回的 Object 直接 as User 还能编过,但传参给接受 User 的函数时就会被拦下——它认的是"你从哪儿来"。

空安全:把 undefined 提前到编译期 ​

ArkTS 强制开启四项 TypeScript 严格检查:noImplicitReturns、strictFunctionTypes、strictNullChecks、strictPropertyInitialization,而且不能通过配置关掉,也不接受 @ts-ignore。

三个直接后果。

一,类的属性必须在声明处或构造函数里显式初始化,name: string; 这种写法编译不过。

二,不支持确定赋值断言 let x!: number,只能改成声明即赋值,或者让初始化函数直接返回。

三,throw 只能抛 Error 及其派生类。throw 'token expired' 是编译错误,得写成 throw new Error('token expired')。

反例是路由取参数的常见写法:

arkts
const params = this.pageStack.getParamByName('detail');
const bill = params[0] as Bill;   // 返回的是数组,长度可能是 0
const id = bill.id;               // 运行时才崩

运行结果:编译通过;当栈里没有 detail 时 params.length 为 0,最后一行抛 TypeError: Cannot read property 'id' of undefined。

编译期不报错,因为 as Bill 让编译器信了。这类地方要用判空加类型守卫收窄,《页面导航与路由:Navigation、路由与参数》讲路由参数时会给出完整写法。

装饰器与模块:语法保留,语义分级 ​

ArkTS 保留装饰器语法,自定义装饰器也能写,和 TypeScript 一致。但要分清两类。

@Entry、@Component、@State 这一组由 ArkUI 和编译器特判,它们参与组件树构建、参与渲染,普通装饰器模拟不出来。自定义装饰器只能作用在普通类、方法、属性上,适合放日志、校验、埋点这类横切逻辑。

模块层用标准 ESM:import 与 export。静态 import 必须排在其他语句之前(动态 import() 不受这条限制,它可以写在函数里)。require、export =、import x = require(...)、给 import 赋值,这些 CommonJS 时期的手法全部不支持。现在统一走 Kit 聚合包:

arkts
import { taskpool, worker } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

运行结果:编译通过,两个 Kit 包各自解析,不需要逐个声明 @ohos.* 依赖。

老代码里的 @ohos.taskpool 还能编,新代码别再这么写。还有一处分工常被忽略:.ets 才能写 ArkUI 的声明式语法,纯逻辑可以放 .ts;但 @Concurrent 标注的并发函数只能在 .ets 里,放进 .ts 过不了校验。

并发:TaskPool 管任务,Worker 管线程 ​

定义:TaskPool 是任务级线程池,你提交函数和参数,系统挑一个工作线程执行完把结果送回;Worker 是线程级,你显式创建一条长期存在的子线程,双方靠消息通信。

如图 1-1 所示,同一份 .ets 源码会在编译期分成三条路径:碰了动态特性的直接编译失败,静态可判定的进入 ArkCompiler,再按任务形态分流到 UI 主线程、TaskPool 或 Worker。

图 1-1 一条源码路径分成三条执行路径

TaskPool 的硬约束,每一条都对应一次具体的失败:

  • 函数必须用 @Concurrent 标注,且不能是箭头函数、类方法、generator。
  • 函数体内只能用入参、局部变量和 import 进来的东西,不能用闭包变量。连"调用同文件里的另一个函数"都算违规,报错只说违反闭包原则,不指行号。
  • 单次同步执行不超过 3 分钟,超时会占死线程,后续任务排队。
  • 参数和返回值要能序列化,单次传输上限 16MB;ArrayBuffer 默认转移而非拷贝,要多次复用同一个 buffer 得用 setCloneList() 改成拷贝。
  • 工作线程没有 UI 上下文,碰 UI 的模块一律不可用。

Worker 的两个易错点。文件必须放在 {module}/src/main/ets/ 之下,并登记进 build-profile.json5 的 buildOption.sourceOption.workers,否则不打包,运行时直接说找不到文件。它和宿主线程内存隔离,@State 装饰的对象传不过去,只能传可序列化的数据。

选择标准:一次性的、可并行的计算进 TaskPool;要常驻、状态会累积、反复交互的放 Worker。选错的表现不是报错,是内存上涨或者任务排队。

工程目录:改动落点 ​

先知道每个文件管什么,动手时才不会改错地方。

路径管什么什么时候会打开它
AppScope/app.json5包名 bundleName、versionCode改包名、发版本
build-profile.json5工程级与模块级构建配置、SDK 版本、workers 登记加模块、升降 API、注册 Worker
hvigorfile.ts构建脚本入口接 hvigor 插件
oh-package.json5依赖声明装三方库
entry/src/main/module.json5模块能力、Ability、权限、routerMap加页面路由表、申请权限
entry/src/main/ets/源码日常
entry/src/main/resources/base/字符串、颜色、图标、profile改文案与资源

bundleName 有格式要求:字母开头,只含字母、数字、下划线和点号,长度 7 到 128 字节,通常是反向域名。它在应用市场里唯一,上架后不能改,起名时别用 com.example。

动手实践 ​

四步,每步都有可验证的产物。

第一步,编一次空工程。 DevEco Studio 6.0.0 新建 Empty Ability 模板,进到工程根目录执行:

bash
# 工程根目录;SDK 6.0.0(20)
$ hvigorw clean --no-daemon
$ hvigorw assembleHap --mode module -p product=default --no-daemon

运行结果(节选):

text
> hvigor Finished :entry:default@CompileArkTS... after 3 s 118 ms
> hvigor BUILD SUCCESSFUL in 11 s 402 ms

产物在 entry/build/default/outputs/default/entry-default-signed.hap。这一步的意义是先确认工具链是干净的,后面再报错就只能是代码问题。

第二步,把解构和展开改掉。 新建 entry/src/main/ets/model/Bill.ets:

arkts
export class Bill {
  id: string = '';
  amount: number = 0;
  note: string = '';

  constructor(id: string, amount: number, note: string) {
    this.id = id;
    this.amount = amount;
    this.note = note;
  }
}

export function zeroed(b: Bill): Bill {
  return new Bill(b.id, 0, b.note);   // 不写 { ...b, amount: 0 }
}

export function parse(json: string): Bill {
  const raw = JSON.parse(json) as Bill;
  // 断言只影响编译期,raw 上没有方法,必须拷进新实例
  return new Bill(raw.id, raw.amount, raw.note);
}

运行结果:zeroed(new Bill('B-1', 12.5, '午餐')) 返回 Bill { id: 'B-1', amount: 0, note: '午餐' };把 zeroed 的函数体换回 { ...b, amount: 0 },编译立刻报 arkts-no-spread。

第三步,把一段重计算丢进 TaskPool。

arkts
import { taskpool } from '@kit.ArkTS';

@Concurrent
function sumOfSquares(n: number): number {
  let sum = 0;
  for (let i = 1; i <= n; i++) {
    sum += i * i;
  }
  return sum;
}

async function run(): Promise<void> {
  const t0 = Date.now();
  const total = await taskpool.execute(sumOfSquares, 100000) as number;
  console.info(`total=${total} cost=${Date.now() - t0}ms`);
}

运行结果:控制台打印 total=333338333350 cost=12ms(耗时随设备浮动,结果固定)。把循环体换成调用同文件里的另一个函数,编译就会报违反闭包原则——@Concurrent 函数只能碰入参、局部变量和 import 进来的东西。

第四步,同一个计算换成 Worker。 手动建 entry/src/main/ets/workers/SumWorker.ets,并在 entry/build-profile.json5 的 buildOption.sourceOption.workers 里登记 ./src/main/ets/workers/SumWorker.ets(用右键 New > Worker 建可跳过这步)。

arkts
// entry/src/main/ets/workers/SumWorker.ets
import { MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const port: ThreadWorkerGlobalScope = worker.workerPort;
port.onmessage = (e: MessageEvents) => {
  const n = e.data as number;
  let sum = 0;
  for (let i = 1; i <= n; i++) {
    sum += i;
  }
  port.postMessage(sum);
};

运行结果:SumWorker.ets 会被编译进包,但此刻它还没启动——要等宿主侧 postMessage 之后,这段循环才开始跑。

宿主侧:

arkts
import { MessageEvents, worker } from '@kit.ArkTS';

const w = new worker.ThreadWorker('entry/ets/workers/SumWorker.ets');
w.onmessage = (e: MessageEvents) => {
  console.info(`sum=${e.data}`);
  w.terminate();
};
w.postMessage(100000);

运行结果:控制台打印 sum=5000050000,随后 Worker 被终止。把 w.terminate() 注释掉再跑一次,DevEco Profiler 里能看到那条子线程一直挂着——这就是"Worker 要自己收尾"的成本。

常见误解 ​

"ArkTS 是 TypeScript 的超集,老代码能直接跑。" 反过来,它是子集:TS 的动态能力被删掉了,能跑的是"恰好没用到那些特性"的那部分。判据不是语法长得像不像,而是对象布局会不会在运行时改变。

"as any 能绕过检查。" any 本身就在禁用列表里,as any 一样报错,@ts-ignore 也不被接受。ArkTS 的严格检查不是可配置项,这一条没有后门。

"并发就是把函数丢进 TaskPool。" 丢之前先看两件事:函数有没有捕获闭包,参数能不能序列化。用了闭包报的是原则性错误,不说哪一行,得从函数体第一行开始往上找。

"Worker 和 TaskPool 只是两套 API。" 一个共享线程池、按任务调度、可扩缩容;一个独立实例、按线程常驻、有内存开销。选错不报错,只在压测时表现为内存上涨或调度排队。

小结 ​

  • ArkTS 删掉的是动态特性:any、运行时增删字段、结构化类型、解构、对象展开、in / delete、Symbol 当键。
  • 空安全四项严格检查强制开启,类属性必须显式初始化,throw 只能抛 Error 派生类。
  • 装饰器语法保留但语义分级;模块是标准 ESM,导入走 @kit.*;@Concurrent 只能在 .ets 文件里。
  • TaskPool 的边界是四条:无闭包、可序列化、同步 3 分钟内、单次 16MB;Worker 要登记到构建配置并自己 terminate()。
  • app.json5 管包名版本,module.json5 管模块与路由表,hvigorfile.ts 管构建,改之前先确认落在哪个文件。

相关主题 ​

语言这层定完,相关文章开始画界面。《声明式 UI:组件、布局与样式》讲 声明式 UI:组件、布局与样式,从 Column / Row 的约束怎么传给子组件讲到自定义组件与构建函数。你会看到本篇这些类型约束在 UI 层变成了帮手:组件参数写错,编译期就拦住,不用等真机跑起来才发现。