从TypeScript到ArkTS的适配指导

---

一、ArkTS语法适配背景

ArkTS在保持TypeScript（简称TS）基本语法风格的基础上，进一步通过规范强化静态检查和分析，使得在程序开发期能检测更多错误，提升程序稳定性，并实现更好的运行性能。本文将进一步解释为什么建议将TS代码适配为ArkTS代码。

程序稳定性

动态类型语言，例如JavaScript（简称JS），可以使得开发者非常快速地编写代码，但是同时，它也使得程序容易在运行时产生非预期的错误。例如在代码中，如果开发者没有检查一个值是否为undefined，那么程序有可能在运行时崩溃，给开发者造成不便。如果能在代码开发阶段检查此类问题是更有好处的。TS通过标注类型帮助开发者检查错误，许多错误在编译时可以被编译器检测出来，不用等到程序运行时。但是，即使是TS也有局限性，它不强制要求对变量进行类型标注，导致很多编译时检查无法开展。ArkTS尝试克服这些缺点，它强制使用静态类型，旨在通过更严格的类型检查以减少运行时错误。

下面这个例子展示了ArkTS通过强制严格的类型检查来提高代码稳定性和正确性。

显式初始化类的属性

ArkTS要求类的所有属性在声明时或者在构造函数中显式地初始化，这和TS中的strictPropertyInitialization检查一致。以下的代码片段是非严格模式下的TS代码。

class Person {name: string // undefinedsetName(n: string): void {this.name = n}getName(): string {// 开发者使用"string"作为返回类型，这隐藏了name可能为"undefined"的事实。// 更合适的做法是将返回类型标注为"string | undefined"，以告诉开发者这个API所有可能的返回值的类型。return this.name}
}let buddy = new Person()
// 假设代码中没有对name的赋值，例如没有调用"buddy.setName('John')"
buddy.getName().length; // 运行时异常：name is undefined

由于ArkTS要求属性显式初始化，代码应该像下面这样写。

class Person {name: string = ''setName(n: string): void {this.name = n}// 类型为"string"，不可能为"null"或者"undefined"getName(): string {return this.name}
}let buddy = new Person()
// 假设代码中没有对name的赋值，例如没有调用"buddy.setName('John')"
buddy.getName().length; // 0, 没有运行时异常

如果name可以是undefined，那么它的类型应该在代码中被精确地标注。

class Person {name?: string // 可能为undefinedsetName(n: string): void {this.name = n}// 编译时错误：name可能为"undefined"，所以不能将这个API的返回类型标注为"string"getNameWrong(): string {return this.name}getName(): string | undefined { // 返回类型匹配name的类型return this.name}
}let buddy = new Person()
// 假设代码中没有对name的赋值，例如没有调用"buddy.setName('John')"// 编译时错误：编译器认为下一行代码有可能访问"undefined"的属性，报错
buddy.getName().length;  // 编译失败buddy.getName()?.length; // 编译成功，没有运行时错误

程序性能

为了保证程序的正确性，动态类型语言不得不在运行时检查对象的类型。例如，JS不允许访问undefined的属性。但是检查一个值是否为undefined的唯一的办法是在运行时进行一次类型检查。所有的JS引擎都会做如下的事：如果一个值不是undefined，那么可以访问其属性，否则抛出异常。现代JS引擎可以很好地对这类操作进行优化，但是总有一些运行时的检查是无法被消除的，这就使得程序变慢了。由于TS总是先被编译成JS，所以在TS代码中，也会面临相同的问题。ArkTS解决了这个问题。由于使能了静态类型检查，ArkTS代码将会被编译成方舟字节码文件，而不是JS代码。因此，ArkTS运行速度更快，更容易被进一步地优化。

Null Safety

function notify(who: string, what: string) {console.log(`Dear ${who}, a message for you: ${what}`)
}notify('Jack', 'You look great today')

在大多数情况下，函数notify会接受两个string类型的变量作为输入，产生一个新的字符串。但是，如果将一些特殊值作为输入，例如notify(null, undefined)，情况会怎么样呢？

程序仍会正常运行，输出预期值：Dear null, a message for you: undefined。一切看起来正常，但是请注意，为了保证该场景下程序的正确性，引擎总是在运行时进行类型检查，执行类似以下的伪代码。

function __internal_tostring(s: any): string {if (typeof s === 'string')return sif (s === undefined)return 'undefined'if (s === null)return 'null'// ...
}

现在想象一下，如果函数notify是某些复杂的负载场景中的一部分，而不仅仅是打印日志，那么在运行时执行像__internal_tostring的类型检查将会是一个性能问题。

如果可以保证在运行时，只有string类型的值（不会是其他值，例如null或者undefined）可以被传入函数notify呢？在这种情况下，因为可以确保没有其他边界情况，像__internal_tostring的检查就是多余的了。对于这个场景，这样的机制叫做“null-safety”，也就是说，保证null不是一个合法的string类型变量的值。如果ArkTS有了这个特性，类型不符合的代码将无法编译。

function notify(who: string, what: string) {console.log(`Dear ${who}, a message for you: ${what}`)
}notify('Jack', 'You look great today')
notify(null, undefined) // 编译时错误

TS通过打开编译选项strictNullChecks来实现此特性。但是TS是被编译成JS的，而JS没有这个特性，因此严格null检查只在编译时起作用。从程序稳定性和性能角度考虑，ArkTS将“null-safety”视为一个重要的特性。这就是为什么ArkTS强制进行严格null检查，在ArkTS中，上面的代码总是编译报错。作为交换，这样的代码可以给ArkTS引擎带来更多的信息和有关值的类型保证，这有助于更好地优化性能。

.ets代码兼容性

在API version 10之前，ArkTS（.ets文件）完全采用了标准TS的语法。从API version 10 Release起，ArkTS的语法规则基于上述设计考虑进行了明确定义，同时，SDK增加了在编译流程中对.ets文件的ArkTS语法检查，通过编译告警或编译失败提示开发者适配新的ArkTS语法。

根据工程的compatibleSdkVersion，具体策略如下：

• compatibleSdkVersion >= 10 为标准模式。在该模式下，对.ets文件，违反ArkTS语法规则的代码会导致工程编译失败，需要完全适配ArkTS语法后方可编译成功。
• compatibleSdkVersion < 10 为兼容模式。在该模式下，对.ets文件，以warning形式提示违反ArkTS语法规则的所有代码。尽管违反ArkTS语法规则的工程在兼容模式下仍可编译成功，但是需要完全适配ArkTS语法后方可在标准模式下编译成功。

支持与TS/JS的交互

ArkTS支持与TS/JS的高效互操作，在当前版本上，ArkTS运行时兼容动态类型对象语义。在与TS/JS交互的场景下，将TS/JS的数据和对象在ArkTS中当作ArkTS的数据和对象使用时，可能会绕过ArkTS的静态编译检查，造成非预期的行为或引入额外的开销。

// lib.ts
export class C {v: string
}export let c = new C()// app.ets
import { C, c } from './lib'function foo(c: C) {c.v.length
}foo(c)  //  运行时异常：v is undefined

方舟运行时兼容TS/JS

在API version 11上，HarmonyOS SDK中的TypeScript版本为4.9.5，target字段为es2017。在应用中，开发者可以使用ECMA2017+的语法进行TS/JS开发。

应用环境限制

1. 强制使用严格模式（use strict）
2. 禁止使用eval()
3. 禁止使用with() {}
4. 禁止以字符串为代码创建函数

与标准TS/JS的差异

标准TS/JS中，JSON的数字格式，小数点后必须跟着数字，如2.e3这类科学计数法不被允许，报出SyntaxError。在方舟运行时中，允许使用这类科学计数法。

二、从TypeScript到ArkTS的适配规则

ArkTS通过规范约束了TypeScript（简称TS）中过于灵活而影响开发正确性或者给运行时带来不必要额外开销的特性。本文罗列了所有在ArkTS中限制的TS特性，并提供了重构代码的建议。ArkTS保留了TS大部分的语法特性，对于本文中没有约束的TS特性，则说明ArkTS完全支持它们。例如：ArkTS支持自定义装饰器，语法上和TS一致。按照本文提供的约束进行代码重构后的代码仍为合法有效的TS代码。

示例

包含关键字var的原始TypeScript代码：

function addTen(x: number): number {var ten = 10;return x + ten;
}

重构后的代码：

function addTen(x: number): number {let ten = 10;return x + ten;
}

级别

约束分为两个级别：错误、警告。

• 错误: 必须要遵从的约束。如果不遵从该约束，将会导致程序编译失败。
• 警告: 推荐遵从的约束。尽管现在违反该约束不会影响编译流程，但是在将来，违反该约束可能将会导致程序编译失败。

不支持的特性

目前，不支持的特性主要包括：

• 与降低运行时性能的动态类型相关的特性。
• 需要编译器额外支持从而导致项目构建时间增加的特性。
  根据开发者的反馈以及更多实际场景的数据，我们将来可能进一步缩小不支持特性的范围。

概述

本节罗列了ArkTS不支持或部分支持的TypeScript特性。完整的列表以及详细的代码示例和重构建议，请参考约束说明。更多案例请参考适配指导案例。

强制使用静态类型

静态类型是ArkTS最重要的特性之一。如果程序采用静态类型，即所有类型在编译时都是已知的，那么开发者就能够容易理解代码中使用了哪些数据结构。同时，由于所有类型在程序实际运行前都是已知的，编译器可以提前验证代码的正确性，从而可以减少运行时的类型检查，有助于提升性能。

基于上述考虑，ArkTS中禁止使用any类型。

示例

// 不支持：
let res: any = some_api_function('hello', 'world');
// `res`是什么？错误代码的数字？字符串？对象？
// 该如何处理它？
// 支持：
class CallResult {public succeeded(): boolean { ... }public errorMessage(): string { ... }
}let res: CallResult = some_api_function('hello', 'world');
if (!res.succeeded()) {console.log('Call failed: ' + res.errorMessage());
}

any类型在TypeScript中并不常见，只有大约1%的TypeScript代码库使用。一些代码检查工具（例如ESLint）也制定一系列规则来禁止使用any。因此，虽然禁止any将导致代码重构，但重构量很小，有助于整体性能提升。

禁止在运行时变更对象布局

为实现最佳性能，ArkTS要求在程序执行期间不能更改对象的布局。换句话说，ArkTS禁止以下行为：

• 向对象中添加新的属性或方法。
• 从对象中删除已有的属性或方法。
• 将任意类型的值赋值给对象属性。

TypeScript编译器已经禁止了许多此类操作。然而，有些操作还是有可能绕过编译器的，例如，使用as any转换对象的类型，或者在编译TS代码时关闭严格类型检查的配置，或者在代码中通过@ts-ignore忽略类型检查。

在ArkTS中，严格类型检查不是可配置项。ArkTS强制进行部分严格类型检查，并通过规范禁止使用any类型，禁止在代码中使用@ts-ignore。

示例

class Point {public x: number = 0public y: number = 0constructor(x: number, y: number) {this.x = x;this.y = y;}
}// 无法从对象中删除某个属性，从而确保所有Point对象都具有属性x
let p1 = new Point(1.0, 1.0);
delete p1.x;           // 在TypeScript和ArkTS中，都会产生编译时错误
delete (p1 as any).x;  // 在TypeScript中不会报错；在ArkTS中会产生编译时错误// Point类没有定义命名为z的属性，在程序运行时也无法添加该属性
let p2 = new Point(2.0, 2.0);
p2.z = 'Label';           // 在TypeScript和ArkTS中，都会产生编译时错误
(p2 as any).z = 'Label';   // 在TypeScript中不会报错；在ArkTS中会产生编译时错误// 类的定义确保了所有Point对象只有属性x和y，并且无法被添加其他属性
let p3 = new Point(3.0, 3.0);
let prop = Symbol();      // 在TypeScript中不会报错；在ArkTS中会产生编译时错误
(p3 as any)[prop] = p3.x; // 在TypeScript中不会报错；在ArkTS中会产生编译时错误
p3[prop] = p3.x;          // 在TypeScript和ArkTS中，都会产生编译时错误// 类的定义确保了所有Point对象的属性x和y都具有number类型，因此，无法将其他类型的值赋值给它们
let p4 = new Point(4.0, 4.0);
p4.x = 'Hello!';          // 在TypeScript和ArkTS中，都会产生编译时错误
(p4 as any).x = 'Hello!'; // 在TypeScript中不会报错；在ArkTS中会产生编译时错误// 使用符合类定义的Point对象：
function distance(p1: Point, p2: Point): number {return Math.sqrt((p2.x - p1.x) * (p2.x - p1.x) + (p2.y - p1.y) * (p2.y - p1.y));
}
let p5 = new Point(5.0, 5.0);
let p6 = new Point(6.0, 6.0);
console.log('Distance between p5 and p6: ' + distance(p5, p6));

修改对象布局会影响代码的可读性以及运行时性能。从开发者的角度来说，在某处定义类，然后又在其他地方修改实际的对象布局，很容易引起困惑乃至引入错误。此外，这点还需要额外的运行时支持，增加了执行开销。这一点与静态类型的约束也冲突：既然已决定使用显式类型，为什么还需要添加或删除属性呢？

当前，只有少数项目允许在运行时变更对象布局，一些常用的代码检查工具也增加了相应的限制规则。这个约束只会导致少量代码重构，但会提升性能。

限制运算符的语义

为获得更好的性能并鼓励开发者编写更清晰的代码，ArkTS限制了一些运算符的语义。

示例

// 一元运算符`+`只能作用于数值类型：
let t = +42;   // 合法运算
let s = +'42'; // 编译时错误

使用额外的语义重载语言运算符会增加语言规范的复杂度，而且，开发者还被迫牢记所有可能的例外情况及对应的处理规则。在某些情况下，产生一些不必要的运行时开销。

当前只有不到1%的代码库使用该特性。因此，尽管限制运算符的语义需要重构代码，但重构量很小且非常容易操作，并且，通过重构能使代码更清晰、具备更高性能。

不支持 structural typing

假设两个不相关的类T和U拥有相同的publicAPI：

class T {public name: string = ''public greet(): void {console.log('Hello, ' + this.name);}
}class U {public name: string = ''public greet(): void {console.log('Greetings, ' + this.name);}
}

能把类型为T的值赋给类型为U的变量吗？

let u: U = new T(); // 是否允许？

能把类型为T的值传递给接受类型为U的参数的函数吗？

function greeter(u: U) {console.log('To ' + u.name);u.greet();
}let t: T = new T();
greeter(t); // 是否允许？

换句话说，我们将采取下面哪种方法呢：

• T和U没有继承关系或没有implements相同的接口，但由于它们具有相同的publicAPI，它们“在某种程度上是相等的”，所以上述两个问题的答案都是“是”；
• T和U没有继承关系或没有implements相同的接口，应当始终被视为完全不同的类型，因此上述两个问题的答案都是“否”。

采用第一种方法的语言支持structural typing，而采用第二种方法的语言则不支持structural typing。目前TypeScript支持structural typing，而ArkTS不支持。

structural typing是否有助于生成清晰、易理解的代码，关于这一点并没有定论。那为什么ArkTS不支持structural typing呢？

因为对structural typing的支持是一个重大的特性，需要在语言规范、编译器和运行时进行大量的考虑和仔细的实现。另外，由于ArkTS使用静态类型，运行时为了支持这个特性需要额外的性能开销。

约束说明

对象的属性名必须是合法的标识符

规则：arkts-identifiers-as-prop-names

级别：错误

在ArkTS中，对象的属性名不能为数字或字符串。例外：ArkTS支持属性名为字符串字面量和枚举中的字符串值。通过属性名访问类的属性，通过数值索引访问数组元素。

TypeScript

var x = { 'name': 'x', 2: '3' };console.log(x['name']);
console.log(x[2]);

ArkTS

class X {public name: string = ''
}
let x: X = { name: 'x' };
console.log(x.name);let y = ['a', 'b', 'c'];
console.log(y[2]);// 在需要通过非标识符（即不同类型的key）获取数据的场景中，使用Map<Object, some_type>。
let z = new Map<Object, string>();
z.set('name', '1');
z.set(2, '2');
console.log(z.get('name'));
console.log(z.get(2));enum Test {A = 'aaa',B = 'bbb'
}let obj: Record<string, number> = {[Test.A]: 1,   // 枚举中的字符串值[Test.B]: 2,   // 枚举中的字符串值['value']: 3   // 字符串字面量
}

不支持Symbol()API

规则：arkts-no-symbol

级别：错误

TypeScript中的Symbol()API用于在运行时生成唯一的属性名称。由于该API的常见使用场景在静态类型语言中没有意义，因此，ArkTS不支持Symbol()API。在ArkTS中，对象布局在编译时就确定了，且不能在运行时被更改。

ArkTS只支持Symbol.iterator。

不支持以#开头的私有字段

规则：arkts-no-private-identifiers

级别：错误

ArkTS不支持使用#符号开头声明的私有字段。改用private关键字。

TypeScript

class C {#fo