!23181 更新ArkTS文档

Merge pull request !23181 from huoqingyi/arkts_docs_v2

en/application-dev/quick-start/typescript-to-arkts-migration-guide.md

@@ -779,7 +779,9 @@ interface Employee extends Identity,  Contact {}
 
 **Severity: error**
 
-ArkTS does not support the returning `this` type. Use explicit type instead.
+ArkTS does not support type notation using the `this` keyword (for example,
+specifying a method's return type `this` is not allowed). Use explicit type
+instead.
 
 **TypeScript**
 
@@ -959,7 +961,9 @@ type N = number
 **Severity: error**
 
 ArkTS does not support indexed access for class fields. Use dot notation
-instead.
+instead. An exception are all typed arrays from the standard library
+(for example, `Int32Array`), which support access to their elements through
+`container[index]` syntax.
 
 **TypeScript**
 
@@ -975,6 +979,9 @@ let x = p["x"]
 class Point {x: number = 0; y: number = 0}
 let p: Point = {x: 1, y: 2}
 let x = p.x
+
+let arr = new Int32Array(1)
+console.log(arr[0])
 ```
 
 ## Recipe: Structural identity is not supported
@@ -1541,33 +1548,6 @@ let a2: C[] = [{n: 1, s: "1"}, {n: 2, s : "2"}]      // ditto
 * Recipe: Object literal must correspond to some explicitly declared class or interface
 * Recipe: Object literals cannot be used as type declarations
 
-## Recipe: Lambdas require explicit type annotation for parameters
-
-**Rule `arkts-explicit-param-types-in-lambdas`**
-
-**Severity: error**
-
-Currently, ArkTS requires the types of lambda parameters
-to be explicitly specified.
-
-**TypeScript**
-
-```typescript
-// Compile-time error only with noImplicitAny:
-let f = (s /* type any is assumed */) => {
-    console.log(s)
-}
-```
-
-**ArkTS**
-
-```typescript
-// Explicit types for lambda parameters are mandatory:
-let f = (s: string) => {
-    console.log(s)
-}
-```
-
 ## Recipe: Use arrow functions instead of function expressions
 
 **Rule `arkts-no-func-expressions`**
@@ -1989,9 +1969,9 @@ let f = "string" + true // "stringtrue"
 
 let g = (new Object()) + "string" // "[object Object]string"
 
-let i = true + true // JS: 2, TS: compile-time error
-let j = true + 2 // JS: 3, TS: compile-time error
-let k = E.E1 + true // JS: 1, TS: compile-time error
+let i = true + true // compile-time error
+let j = true + 2    // compile-time error
+let k = E.E1 + true // compile-time error
 ```
 
 **ArkTS**
@@ -2011,7 +1991,7 @@ let g = (new Object()).toString() + "string"
 
 
 let i = true + true // compile-time error
-let j = true + 2 // compile-time error
+let j = true + 2    // compile-time error
 let k = E.E1 + true // compile-time error
 ```
 
@@ -2341,7 +2321,8 @@ iterate over data.
 **Severity: error**
 
 ArkTS supports the iteration over arrays and strings by the `for .. of` loop,
-but does not support the iteration of objects content.
+but does not support the iteration of objects content. All typed arrays from
+the standard library (for example, `Int32Array`) are also supported.
 
 **TypeScript**
 
@@ -2433,7 +2414,8 @@ console.log("Area: ", Math.PI * r * r)
 
 **Severity: error**
 
-ArkTS supports `case` statements that contain only compile-time values.
+ArkTS supports `case` statements that contain only compile-time values,
+top-level scope `const` values, and `static readonly` class fields.
 Use `if` statements as an alternative.
 
 **TypeScript**
@@ -2907,7 +2889,8 @@ function main(): void {
 
 The only supported scenario for the spread operator is to spread an array into
 the rest parameter. Otherwise, manually “unpack” data from arrays and objects,
-where necessary.
+where necessary. All typed arrays from the standard library (for example,
+`Int32Array`) are also supported.
 
 **TypeScript**
 
@@ -3880,34 +3863,6 @@ let ce = new CustomError()
 
 * Recipe: Prototype assignment is not supported
 
-## Recipe: Runtime import expressions are not supported
-
-**Rule `arkts-no-runtime-import`**
-
-**Severity: error**
-
-ArkTS does not support such “runtime” import expressions as `await import...`
-because in the language import is a compile-time, not a runtime feature.
-Use regular import syntax instead.
-
-**TypeScript**
-
-```typescript
-const zipUtil = await import("utils/create-zip-file")
-```
-
-**ArkTS**
-
-```typescript
-import { zipUtil } from "utils/create-zip-file"
-```
-
-**See also**
-
-* Recipe: Wildcards in module names are not supported
-* Recipe: Universal module definitions (UMD) are not supported
-* Recipe: Import assertions are not supported
-
 ## Recipe: Definite assignment assertions are not supported
 
 **Rule `arkts-no-definite-assignment`**
@@ -4065,8 +4020,7 @@ M.abc = 200
 **Severity: error**
 
 Currently ArkTS does not support utility types from TypeScript extensions to the
-standard library (`Omit`, `Pick`, etc.). Exceptions are: `Partial`,
-`Record`.
+standard library, except following: `Partial`, `Record`.
 
 For the type *Record<K, V>*, the type of an indexing expression *rec[index]* is
 of the type *V | undefined*.
@@ -4349,7 +4303,6 @@ import { something } from "module"
 
 * Recipe: Wildcards in module names are not supported
 * Recipe: Universal module definitions (UMD) are not supported
-* Recipe: Runtime import expressions are not supported
 
 ## Recipe: Usage of standard library is restricted
 
@@ -4364,9 +4317,7 @@ the following APIs is prohibited:
 
 Properties and functions of the global object: `eval`,
 `Infinity`, `NaN`, `isFinite`, `isNaN`, `parseFloat`, `parseInt`,
-`encodeURI`, `encodeURIComponent`, `Encode`,
-`decodeURI`, `decodeURIComponent`, `Decode`,
-`escape`, `unescape`, `ParseHexOctet`
+`Encode`, `Decode`, `ParseHexOctet`
 
 `Object`: `__proto__`, `__defineGetter__`, `__defineSetter__`,
 `__lookupGetter__`, `__lookupSetter__`, `assign`, `create`,
@@ -4561,3 +4512,54 @@ class BugReport {
 }
 ```
 
+## Recipe: Classes cannot be used as objects
+
+**Rule `arkts-no-classes-as-obj`**
+
+**Severity: error**
+
+ArkTS does not support using classes as objects (assigning them to variables,
+etc.) because in ArkTS, a `class` declaration introduces a new type,
+not a value.
+
+**TypeScript**
+
+```typescript
+class C {
+    s: string = ""
+    n: number = 0
+}
+
+let c = C
+```
+
+## Recipe: `import` statements after other statements are not allowed
+
+**Rule `arkts-no-misplaced-imports`**
+
+**Severity: error**
+
+In ArkTS, all `import` statements should go before all other statements
+in the program.
+
+**TypeScript**
+
+```typescript
+class C {
+    s: string = ""
+    n: number = 0
+}
+
+import foo from "module1"
+```
+
+**ArkTS**
+
+```typescript
+import foo from "module1"
+
+class C {
+    s: string = ""
+    n: number = 0
+}
+```

zh-cn/application-dev/quick-start/typescript-to-arkts-migration-guide.md

@@ -837,6 +837,7 @@ type N = number
 **级别：错误**
 
 ArkTS不支持通过索引访问对象的字段。改用点操作符。
+ArkTS支持通过索引访问`TypedArray`（例如`Int32Array`）中的元素。
 
 **TypeScript**
 
@@ -852,6 +853,9 @@ let x = p["x"]
 class Point {x: number = 0; y: number = 0}
 let p: Point = {x: 1, y: 2}
 let x = p.x
+
+let arr = new Int32Array(1)
+console.log(arr[0])
 ```
 
 ### 不支持structural identity
@@ -1305,7 +1309,7 @@ class Point {
     y: number = 0
 
     // 在字面量初始化之前，使用constructor()创建一个有效对象。
-    // 由于Point没有其它构造函数，编译器将自动添加一个默认构造函数。
+    // 由于没有为Point定义构造函数，编译器将自动添加一个默认构造函数。
 }
 
 function id_x_y(o: Point): Point {
@@ -1392,32 +1396,6 @@ let a2: C[] = [{n: 1, s: "1"}, {n: 2, s : "2"}]      // a2的类型为“C[]”
 * 对象字面量必须对应某些显式声明的类或接口
 * 对象字面量不能用于类型声明
 
-### 显式标注Lambda函数的参数类型
-
-**规则：**`arkts-explicit-param-types-in-lambdas`
-
-**级别：错误**
-
-当前ArkTS要求显式标注lambda函数的参数的类型。
-
-**TypeScript**
-
-```typescript
-// 只有在开启noImplicitAny选项时会产生编译时错误
-let f = (s /* type any is assumed */) => {
-    console.log(s)
-}
-```
-
-**ArkTS**
-
-```typescript
-// 显式标注Lambda函数的参数类型
-let f = (s: string) => {
-    console.log(s)
-}
-```
-
 ### 使用箭头函数而非函数表达式
 
 **规则：**`arkts-no-func-expressions`
@@ -1814,9 +1792,9 @@ let f = "string" + true // "stringtrue"
 
 let g = (new Object()) + "string" // "[object Object]string"
 
-let i = true + true // JS: 2, TS: 编译时错误
-let j = true + 2 // JS: 3, TS: 编译时错误
-let k = E.E1 + true // JS: 1, TS: 编译时错误
+let i = true + true // 编译时错误
+let j = true + 2    // 编译时错误
+let k = E.E1 + true // 编译时错误
 ```
 
 **ArkTS**
@@ -1835,7 +1813,7 @@ let f = "string" + true // "stringtrue"
 let g = (new Object()).toString() + "string"
 
 let i = true + true // 编译时错误
-let j = true + 2 // 编译时错误
+let j = true + 2    // 编译时错误
 let k = E.E1 + true // 编译时错误
 ```
 
@@ -2142,7 +2120,7 @@ ArkTS不支持`Symbol`API、`Symbol.iterator`和最终可迭代的接口。请
 
 **级别：错误**
 
-ArkTS支持通过`for .. of`迭代数组和字符串，但不支持迭代对象。
+ArkTS支持通过`for .. of`迭代数组、字符串和`TypedArray`（例如`Int32Array`），但不支持迭代对象。
 
 **TypeScript**
 
@@ -2232,7 +2210,7 @@ console.log("Area: ", Math.PI * r * r)
 
 **级别：错误**
 
-在ArkTS中，`case`语句仅支持编译期值。若值无法在编译期确定，请使用`if`语句。
+在ArkTS中，`case`语句仅支持编译期值，支持`const`常量和`class`的`static readonly`属性。若值无法在编译期确定，请使用`if`语句。
 
 **TypeScript**
 
@@ -2689,7 +2667,7 @@ function main(): void {
 
 **级别：错误**
 
-展开运算符唯一支持的场景是函数剩余参数为数组类型。
+展开运算符唯一支持的场景是函数剩余参数为数组类型，包括`TypedArray`（例如`Int32Array`）。
 
 **TypeScript**
 
@@ -3273,7 +3251,7 @@ import "path/to/module"
 **ArkTS**
 
 ```typescript
-import * from "path/to/module"
+import * as ns from "path/to/module"
 ```
 
 ### 不支持`import default as ...`
@@ -3326,7 +3304,7 @@ import * as m from "mod"
 
 **级别：错误**
 
-ArkTS支持大多数场景下的重导出，比如命名导出和重命名导出，重导出import的。不支持`export * as ...`。
+ArkTS支持大多数场景下的重导出，例如命名重导出和重命名重导出。不支持`export * as ...`。
 
 **TypeScript**
 
@@ -3512,7 +3490,7 @@ declare namespace N {
     function foo(x: number): number
 }
 
-import * from "module"
+import * as m from "module"
 console.log("N.foo called: ", N.foo(42))
 ```
 
@@ -3622,32 +3600,6 @@ let ce = new CustomError()
 
 * 不支持在原型上赋值
 
-### 不支持动态导入
-
-**规则：**`arkts-no-runtime-import`
-
-**级别：错误**
-
-由于在ArkTS中，导入是编译时而非运行时特性，因此，ArkTS不支持动态导入，如`await import...`。改用静态`import`语法。
-
-**TypeScript**
-
-```typescript
-const zipUtil = await import("utils/create-zip-file")
-```
-
-**ArkTS**
-
-```typescript
-import { zipUtil } from "utils/create-zip-file"
-```
-
-**相关约束**
-
-* 不支持在模块名中使用通配符
-* 不支持通用模块定义(UMD)
-* 不支持导入断言
-
 ### 不支持确定赋值断言
 
 **规则：**`arkts-no-definite-assignment`
@@ -3796,7 +3748,7 @@ M.abc = 200
 
 **级别：错误**
 
-当前ArkTS不支持从TypeScript扩展到标准库的utility类型（例如`Omit`、`Pick`等）。支持`Partial`和`Record`。
+ArkTS仅支持`Partial`和`Record`，不支持TypeScript中其他的`Utility Types`。
 
 对于*Record<K, V>*类型，表达式*rec[index]*的类型是*V | undefined*。
 对于`Record`类型，键-值中的值的类型必须是可选类型或者包含`undefined`的联合类型。
@@ -4079,9 +4031,7 @@ ArkTS不允许使用TypeScript或JavaScript标准库中的某些接口。大部
 
 全局对象的属性和方法：`eval`、
 `Infinity`、`NaN`、`isFinite`、`isNaN`、`parseFloat`、`parseInt`、
-`encodeURI`、`encodeURIComponent`、`Encode`、
-`decodeURI`、`decodeURIComponent`、`Decode`、
-`escape`、`unescape`、`ParseHexOctet`
+`Encode`、`Decode`、`ParseHexOctet`
 
 `Object`：`__proto__`、`__defineGetter__`、`__defineSetter__`、
 `__lookupGetter__`、`__lookupSetter__`、`assign`、`create`、
@@ -4267,3 +4217,52 @@ function classDecorator(x: number, y: number): void {
 class BugReport {
 }
 ```
+
+### `class`不能被用作对象
+
+**规则：**`arkts-no-classes-as-obj`
+
+**级别：错误**
+
+在ArkTS中，`class`声明的是一个新的类型，不是一个值。因此，不支持将`class`用作对象（例如将`class`赋值给一个对象）。
+
+**TypeScript**
+
+```typescript
+class C {
+    s: string = ""
+    n: number = 0
+}
+
+let c = C
+```
+
+### 不支持在`import`语句前使用其他语句
+
+**规则：**`arkts-no-misplaced-imports`
+
+**级别：错误**
+
+在ArkTS中，除动态`import`语句外，所有`import`语句需要放在所有其他语句之前。
+
+**TypeScript**
+
+```typescript
+class C {
+    s: string = ""
+    n: number = 0
+}
+
+import foo from "module1"
+```
+
+**ArkTS**
+
+```typescript
+import foo from "module1"
+
+class C {
+    s: string = ""
+    n: number = 0
+}
+```