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 的对象像标准集装箱,箱格出厂就焊死了。你确实需要多一个字段,正确做法是新做一个箱子——新类或子类,而不是在旧箱子上开洞。
反例很短:
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')。
反例是路由取参数的常见写法:
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 聚合包:
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 模板,进到工程根目录执行:
# 工程根目录;SDK 6.0.0(20)
$ hvigorw clean --no-daemon
$ hvigorw assembleHap --mode module -p product=default --no-daemon运行结果(节选):
> 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:
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。
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 建可跳过这步)。
// 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 之后,这段循环才开始跑。
宿主侧:
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 层变成了帮手:组件参数写错,编译期就拦住,不用等真机跑起来才发现。