diff --git a/zh-cn/application-dev/distributedservice/distributedextension-duidelines.md b/zh-cn/application-dev/distributedservice/distributedextension-guidelines.md similarity index 75% rename from zh-cn/application-dev/distributedservice/distributedextension-duidelines.md rename to zh-cn/application-dev/distributedservice/distributedextension-guidelines.md index e7e82225cb6e02b2ab2884aafbadc19db5c8ee35..ae8531e8dfa2d8faaf7a474de3999da21458025f 100644 --- a/zh-cn/application-dev/distributedservice/distributedextension-duidelines.md +++ b/zh-cn/application-dev/distributedservice/distributedextension-guidelines.md @@ -1,4 +1,4 @@ -# UIAbility与Extension连接开发指南 +# 分布式Extension开发指南 ## 简介 @@ -36,7 +36,7 @@ ## 实现原理 -设备A应用集成**DistributedExtension**，当设备A侧分布式软总线收到应用的消息时，通过DistributedExterntion拉起设备A侧应用后台服务，设备A侧应用后台服务将设备B侧应用消息发送到应用服务。 +设备A应用集成**DistributedExtension**，当设备A侧分布式软总线收到应用的消息时，通过DistributedExtension拉起设备A侧应用后台服务，设备A侧应用后台服务将设备B侧应用消息发送到应用服务。 ![实现原理](figures/distributedextension.png) @@ -54,7 +54,7 @@ ### 搭建环境 1. 在PC上安装[DevEco Studio](https://gitee.com/link?target=https%3A%2F%2Fdeveloper.huawei.com%2Fconsumer%2Fcn%2Fdownload%2Fdeveco-studio)，要求版本在4.1及以上。 -2. 将public-SDK更新到API 18或以上，更新SDK的具体操作可参见[更新指南](../tools/openharmony_sdk_upgrade_assistant.md)。 +2. 将public-SDK更新到API 20或以上，更新SDK的具体操作可参见[更新指南](../tools/openharmony_sdk_upgrade_assistant.md)。 3. 打开设备A和设备B的蓝牙，互相识别，实现组网。 ### 检验环境是否搭建成功 @@ -109,49 +109,38 @@ hidumper -s 4700 -a "buscenter -l remote_device_info" 2. 导入开发所需模块。 ```ts - import { AbilityConstant } from '@kit.AbilityKit'; - import { connection } from '@kit.NetworkKit'; - import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit'; - import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit' - import {DistributedExtensionAbility} from '@kit.DistributedServiceKit'; + import { AbilityConstant, Want } from '@kit.AbilityKit'; + import { abilityConnectionManager, DistributedExtensionAbility } from '@kit.DistributedServiceKit'; ``` 3. 开发者可以自定义 `MDSExtension.ets`文件，类中继承 `DistributedExtensionAbility`，通过重写其 `onCreate、onDestroy`和 `onCollaborate`方法，使其达到在分布式能力扩展的创建、销毁和连接回调的使用。 - 下面的示例展示了一个空实现的 `MDSExtension.ets`文件，根据对应Logger可观测其生命周期： + 下面的示例展示了一个空实现的 `MDSExtension.ets`文件，根据对应日志可观测其生命周期： ```ts - import DistributedExtensionAbility from '@ohos.application.DistributedExtensionAbility'; - import Logger from '../common/Logger' - import abilityConnectionManager from '@ohos.distributedsched.abilityConnectionManager'; - import { AbilityConstant } from '@kit.AbilityKit'; - import { connection } from '@kit.NetworkKit'; - import { AsyncCallback,BusinessError } from '@kit.BasicServicesKit'; - import { abilityAccessCtrl, bundleManager, Permissions } from '@kit.AbilityKit' + import { AbilityConstant, Want } from '@kit.AbilityKit'; + import { abilityConnectionManager, DistributedExtensionAbility } from '@kit.DistributedServiceKit'; - - const TAG = `FileDistributedExtensionAbility`; - - export default class DistributedExtension extends DistributedExtensionAbility { - onCreate (want) { - Logger.info(TAG, `DistributedExterntion Create ok`); - Logger.info(TAG, `DistributedExterntion on Create want ： ${JSON.stringify(want)}`); - Logger.info(TAG, `DistributedExterntion on Create end`); + export default class DistributedExtension extends DistributedExtensionAbility { + onCreate(want: Want) { + console.info(`DistributedExtension Create ok`); + console.info(`DistributedExtension on Create want: ${JSON.stringify(want)}`); + console.info(`DistributedExtension on Create end`); } - onCollaborate (wantParam: Record) { - Logger.info(TAG, `DistributedExterntionon onCollabRequest Accept to the result of Ability collaborate`); + onCollaborate(wantParam: Record) { + console.info(`DistributedExtension onCollabRequest Accept to the result of Ability collaborate`); let sessionId = -1; - const collabrationType = wantParam["CollaborationKeys.COLLABORATE_TYPE"] as abilityConnectionManager.CollabrationType; - if (collabrationType == undefined) { + const collaborationValues = wantParam["CollaborationValues"] as abilityConnectionManager.CollaborationValues; + if (collaborationValues == undefined) { return sessionId; } - Logger.info(TAG, `onCollab, peerInfo: ${JSON.stringify(collabrationType)}`); + console.info(`onCollab, collaborationValues: ${JSON.stringify(collaborationValues)}`); return AbilityConstant.CollaborateResult.ACCEPT; } - onDestroy () { - Logger.info(TAG, `DistributedExterntion onDestroy ok`); + onDestroy() { + console.info(`DistributedExtension onDestroy ok`); } } ``` diff --git a/zh-cn/application-dev/quick-start/Readme-CN.md b/zh-cn/application-dev/quick-start/Readme-CN.md index 2b4b5a8a7b0ceaf346b3f9b62a9ce81c862cff26..e4f533b47111761f4e8570724c6df35dd94f1f1a 100755 --- a/zh-cn/application-dev/quick-start/Readme-CN.md +++ b/zh-cn/application-dev/quick-start/Readme-CN.md @@ -41,6 +41,32 @@ - [ArkTS语法适配背景](arkts-migration-background.md) - [从TypeScript到ArkTS的适配规则](typescript-to-arkts-migration-guide.md) - [适配指导案例](arkts-more-cases.md) + - 从ArkTS1.1到ArkTS1.2的适配指导 + - [ArkTS1.2用户指导](arkts-v1.2-user-guide.md) + - [ArkTS1.2语法迁移规则](arkts-v1.1-v1.2-migration-rules.md) + - [ArkTS1.2并发迁移规则](arkts-v1.1-v1.2-concurrency-rules.md) + - [ArkTS1.2与ArkTS1.1互操作迁移规则](arkts-v1.1-v1.2-interop-rules.md) + - [ArkTS1.2互操作概述](arkts-interop-overview.md) + - [ArkTS1.2互操作类型映射规则](arkts-interop-type-mapping.md) + - [ArkTS1.2互操作场景](arkts-interop-more.md) + - [ArkTS1.2互操作特性规范](arkts-interop-spec.md) + - [ArkTS1.2 builtin变更文档-Array](arkts-builtin-api-Array.md) + - [ArkTS1.2 builtin变更文档-Constructor](arkts-builtin-api-Constructor.md) + - [ArkTS1.2 builtin变更文档-ReadOnly](arkts-builtin-api-ReadOnly.md) + - [ArkTS1.2 builtin变更文档-stdlib1](arkts-builtin-api-stdlib1.md) + - [ArkTS1.2 builtin变更文档-stdlib2](arkts-builtin-api-stdlib2.md) + - [ArkTS1.2 builtin变更文档-stdlib3](arkts-builtin-api-stdlib3.md) + - [ArkTS1.2 builtin变更文档-BigUint64Array](arkts-builtin-api-BigUint64Array.md) + - [ArkTS1.2 builtin变更文档-BigInt64Array](arkts-builtin-api-BigInt64Array.md) + - [ArkTS1.2 builtin变更文档-Float32Array](arkts-builtin-api-Float32Array.md) + - [ArkTS1.2 builtin变更文档-Float64Array](arkts-builtin-api-Float64Array.md) + - [ArkTS1.2 builtin变更文档-Int8Array](arkts-builtin-api-Int8Array.md) + - [ArkTS1.2 builtin变更文档-Int16Array](arkts-builtin-api-Int16Array.md) + - [ArkTS1.2 builtin变更文档-Int32Array](arkts-builtin-api-Int32Array.md) + - [ArkTS1.2 builtin变更文档-Uint8Array](arkts-builtin-api-Uint8Array.md) + - [ArkTS1.2 builtin变更文档-Uint16Array](arkts-builtin-api-Uint16Array.md) + - [ArkTS1.2 builtin变更文档-Uint32Array](arkts-builtin-api-Uint32Array.md) + - [ArkTS1.2 builtin变更文档-Uint8ClampedArray](arkts-builtin-api-Uint8ClampedArray.md) - [ArkTS高性能编程实践](arkts-high-performance-programming.md) - UI范式基本语法 - [基本语法概述](arkts-basic-syntax-overview.md) diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Array.md new file mode 100644 index 0000000000000000000000000000000000000000..c56e8b3ae9701b0f8783ffc530a4828853fd68c2 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Array.md @@ -0,0 +1,946 @@ +# Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [concat方法参数变更](#concat方法参数变更) +- [every方法签名变更](#every方法签名变更) +- [filter方法签名变更](#filter方法签名变更) +- [find方法签名变更](#find方法签名变更) +- [findIndex方法签名变更](#findindex方法签名变更) +- [flat方法移除](#flat方法移除) +- [flatMap方法移除](#flatmap方法移除) +- [forEach方法签名变更](#foreach方法签名变更) +- [map方法签名变更](#map方法签名变更) +- [from方法签名变更](#from方法签名变更) +- [some方法签名变更](#some方法签名变更) +- [数组长度构造函数变更](#数组长度构造函数变更) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Array([1, 2, 3]); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 数组的迭代器对象。 | + +**示例：** + ```typescript + let a: Array = new Array(1, 2, 3); + let iter: IterableIterator = a.$_iterator(); + ``` + +- 适配建议： + 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### concat方法参数变更 +**ArkTS1.1版本签名：** + `concat(...items: (T | ConcatArray)[]): T[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | items | (T \| ConcatArray\)[] | 是 | 要连接的项或数组。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 连接后的新数组。 | + +**示例：** + ```typescript + let arr1=new Array(); + let arr2=new Array(); + arr1.concat(1, arr2) + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +- 适配建议： + 将单个成员改成数组再使用concat。 + ```typescript + let arr1=new Array(); + let arr2=new Array(); + let arr3=new Array(); + arr3.push(1); + arr1.concat(arr3, arr2); + ``` + +### every方法签名变更 +**ArkTS1.1版本签名：** + - `every(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): boolean` + - `every(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any): this is S[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为当前实例对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否通过所有元素都测试，true表示全部通过，false表示全部不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Array) { + return value < this.base; + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); // false + arr.every(a.compare, b); // true + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: T, index: number, array: Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + + predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否通过所有元素都测试，true表示全部通过，false表示全部不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Array): boolean { + return arr.every((value: number, index: number, arr: Array)=>{return value < this.base}); + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法签名变更 +**ArkTS1.1版本签名：** + - `filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T[]` + - `filter(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any): S[]` + - `filter(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: any): S[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Array) { + return value < this.base; + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + arr.every(a.compare, a); // [1] + arr.every(a.compare, b); // [1, 2] + ``` + +**ArkTS1.2版本签名：** + `filter(fn: (v: T, i: number, self: Array) => boolean): Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | fn | function | 是 | 测试函数。 | + +fn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | i | number | 是 | 当前元素的索引。 | + | self | Array\ | 是 | 调用的原始数组。 | + | boolean | 是 | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Array\ | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Array): Array { + return arr.filter((value: number, index: number, arr: Array)=>{return value < this.base}); + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法签名变更 +**ArkTS1.1版本签名：** + - `find(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): T | undefined` + - `find(predicate: (this: void, value: T, index: number, obj: T[]) => value is S, thisArg?: any): S | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，判断当前是否找到匹配项。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T | undefined | 第一个通过测试的元素，未找到则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Array) { + return value >= this.base + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); // 2 + arr.find(a.compare, b); // 3 + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: T, index: number, arr: Array) => boolean): T | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Array\ | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T | undefined | 第一个通过测试的元素，未找到则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Array) { + return arr.find((value: number, index: number, arr: Array)=>{return value >= this.base}); + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2) + let b = new C(3) + a.call(arr); // 2 + b.call(arr); // 3 + + console.info(a.call(arr)); + console.info(b.call(arr)); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法签名变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 第一个通过测试元素的索引，未找到则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Array) { + return value >= this.base; + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); // 1 + arr.findIndex(a.compare, b); // 2 + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: T, index: number, array: Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Array\ | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 第一个通过测试元素的索引，未找到则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Array): number { + return arr.findIndex((value: number, index: number, arr: Array)=>{return value >= this.base}); + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### flat方法移除 +**ArkTS1.1版本签名：** + `flat(this: A,depth?: D): FlatArray[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | depth | D | 否 | 指定要提取嵌套数组的结构深度，默认值为1。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | FlatArray\[] | 包含所有子数组元素的新数组。 | + +**示例：** + ```typescript + type T = number | T[]; + let arr:Array = [[1, [2]], 3, [4, 5]]; + arr.flat(2); // [1, 2, 3, 4, 5] + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +- 适配建议： + 不使用flat，对于有明确返回值类型的具体的场景自己实现算法。 + +### flatMap方法移除 +**ArkTS1.1版本签名：** + `flatMap (callback: (this: This, value: T, index: number, array: T[]) => U | ReadonlyArray,thisArg?: This): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | function | 是 | 生成新数组元素的函数。 | + | thisArg | This | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callback函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | this | This | 是 | 由 thisArg 指定的上下文默认undefined。 | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Array\ | 是 | 调用的原始数组。 | + +callback函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U\|ReadonlyArray\ | 可返回单个值U或U类型的数组。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 新数组。 | + +**示例：** + ```typescript + let arr = [[1, 2], 3, [4, 5]] + arr.flatMap( + (value, index, array) =>{ + return value; + } + ) + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +- 适配建议： + 不使用flatMap。 + +### forEach方法签名变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 为每个元素执行的函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Array) { + console.info(value + this.base) + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: T, index: number, array: Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 为每个元素执行的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Array\ | 是 | 调用的原始数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Array) { + return arr.forEach((value: number, index: number, arr: Array)=>{console.info(value + this.base)}); + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法签名变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 生成新数组元素的函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U | 映射后的值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Array) { + return value + this.base; + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: T, index: number, arr: Array) => U): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 生成新数组元素的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Array\ | 是 | 调用的原始数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U | 映射后的值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Array): Array { + return arr.map((value: number, index: number, arr: Array)=>{return value + this.base}) + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from方法签名变更 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => U, thisArg?: any): U[]` + `static from(iterable: Iterable | ArrayLike, mapfn: (v: T, k: number) => U, thisArg?: any): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 要转换为数组的对象。 | + | mapfn | function | 是 | map函数。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U | 返回的一个值，作为新Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base; + } + } + + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + let arr2 = Array.from(arr, a.foo, a); + let arr3 = Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => U): U[]` + `static from(iterable: Iterable, mapfn: (v: T, k: number) => U): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 要转换为数组的对象。 | + | mapfn | function | 是 | map函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U | 返回的一个值，作为新Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Array): Array { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + + function main() { + let arr: Array = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法签名变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，判断当前元素是否满足predicate。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否通过所有元素都测试，true表示全部通过，false表示全部不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: ReadonlyArray) { + return value > this.base; + } + } + + let arr: ReadonlyArray = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: T, index: number, array: T[]) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否通过所有元素都测试，true表示全部通过，false表示全部不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: ReadonlyArray) { + return arr.some( + (value: number, index: number, arr: ReadonlyArray)=>{return value > this.base} + ); + } + } + let arr: ReadonlyArray = new Array(1, 2, 3); + let a = new C(2); + let b = new C(3); + console.info(a.call(arr)); + console.info(b.call(arr)); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### 数组长度构造函数变更 +**ArkTS1.1版本签名：** + `(arrayLength?: number): T[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLength | number | 否 | 数组长度，默认值为0。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 新创建的数组。 | + +**示例：** + ```typescript + let a = Array(10) + function f(a:ArrayConstructor) { + a(10); + } + ``` + +**ArkTS1.2版本签名：** + `static Array.invoke(arrayLength?: number): T[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLength | number | 否 | 数组长度，默认值为0。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 新创建的数组。 | + +**示例：** + ```typescript + let a = Array(10); + function f() { + Array(10); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-BigInt64Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-BigInt64Array.md new file mode 100644 index 0000000000000000000000000000000000000000..823b94ac82254e0f1b5819011cd0d03c9e3ca354 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-BigInt64Array.md @@ -0,0 +1,719 @@ +# BigInt64Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更](#from静态方法变更) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | BigInt64Array的迭代器。 | + +**示例：** + ```typescript + let a = new BigInt64Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | BigInt64Array的迭代器。 | + +**示例：** + ```typescript + let a = new BigInt64Array(3); + let iter = a.$_iterator; + ``` + +- 适配建议： + 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | function | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的bigint值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示数组中的所有元素是否都满足`predicate`，`true`表示全部满足，`false`表示全部不满足。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array): boolean { + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.every(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的bigint值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示数组中的所有元素是否都满足`predicate`，`true`表示全部满足，`false`表示全部不满足。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.every((element: bigint, index: number, array: BigInt64Array) => { + return element > o.base; + }); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: bigint, index: number, array: BigInt64Array) => any, thisArg?: any): BigInt64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `BigInt64Array` | 包含所有满足`predicate`的元素的新数组。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array): boolean { + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.filter(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean): BigInt64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `BigInt64Array` | 包含所有满足`predicate`的元素的新数组。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.filter((element: bigint, index: number, array: BigInt64Array) => { + return element > o.base; + }); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean, thisArg?: any): bigint | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `bigint | undefined` | 如果找到满足`predicate`的元素，则返回该元素，否则返回`undefined`。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array): boolean { + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.find(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean): bigint | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `bigint | undefined` | 如果找到满足`predicate`的元素，则返回该元素，否则返回`undefined`。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.find((element: bigint, index: number, array: BigInt64Array) => { + return element > o.base; + }); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### findIndex方法变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number` | 如果找到满足`predicate`的元素，则返回该元素的索引，否则返回`-1`表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array): boolean { + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.findIndex(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number` | 如果找到满足`predicate`的元素，则返回该元素的索引，否则返回 `-1`表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.findIndex(new C(1n).comp); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: bigint, index: number, array: BigInt64Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素执行的函数。 | + | `thisArg` | `any` | 否 | 执行`callbackfn`时`this`指向的对象，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array): boolean { + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.forEach(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: bigint, index: number, array: BigInt64Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `(value: bigint, index: number, array: BigInt64Array) => void` | 是 | 为数组中的每个元素执行的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + + function main() { + let o = new C(2n); + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + arr.forEach((element: bigint, index: number, array: BigInt64Array) => { + console.info(element, index); + }); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: bigint, index: number, array: BigInt64Array) => bigint, thisArg?: any): BigInt64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素调用的函数，返回新数组中的元素。 | + | `thisArg` | `any` | 否 | 执行`callbackfn`时`this`指向的对象，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 当前函数计算后新得到的bigint值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `BigInt64Array` | 一个新的 BigInt64Array，包含`callbackfn`对每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + map(element: bigint, index: number, array: BigInt64Array): bigint { + return this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.map(new C(1n).map, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: bigint, index: number, array: BigInt64Array) => bigint): BigInt64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素调用的函数，返回新数组中的元素。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 当前函数计算后新得到的bigint值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `BigInt64Array` | 一个新的BigInt64Array，包含`callbackfn`对每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.map((element: bigint, index: number, array: BigInt64Array) => { + return o.base; + }); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### some方法变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行 `predicate` 时 `this` 指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示数组中至少有一个元素满足`predicate`，`true`表示有，`false`表示没有。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigInt64Array): boolean { + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.some(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: bigint, index: number, array: BigInt64Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigInt64Array | 是 | 调用的原始BigInt64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示数组中至少有一个元素满足`predicate`，`true`表示有，`false`表示没有。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigInt64Array = new BigInt64Array([1n, 2n, 3n]); + let result = arr.some((element: bigint, index: number, array: BigInt64Array) => { + return element > o.base; + }); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: U, k: number) => bigint, thisArg?: any): BigInt64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `ArrayLike` | 是 | 类似数组或可迭代的对象。 | + | `mapfn` | `function` | 是 | 为`arrayLike`中的每个元素调用的函数，返回新数组中的元素。 | + | `thisArg` | `any` | 否 | 执行`mapfn`时`this`指向的对象，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | U | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 返回的一个bigint类型值，作为新BigInt64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `BigInt64Array` | 一个新的BigInt64Array，包含`mapfn`对`arrayLike`中每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + add(v: number, k: number): bigint { + return BigInt(v + this.offset); + } + offset: number; + constructor(offset: number) { + this.offset = offset; + } + } + + const newArr = BigInt64Array.from([1, 2, 3], new C(1).add, new C(2)); // [3,4,5] + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: U, k: number) => bigint): BigInt64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `ArrayLike` | 是 | 类似数组或可迭代的对象。 | + | `mapfn` | `function` | 是 | 为`arrayLike`中的每个元素调用的函数，返回新数组中的元素。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | U | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 返回的一个bigint类型值，作为新BigInt64Array的元素 | + + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `BigInt64Array` | 一个新的BigInt64Array，包含`mapfn` 对`arrayLike`中每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + offset: number; + constructor(offset: number) { + this.offset = offset; + } + } + + function main() { + const origArr: Array = new Array(1,2,3); + let o = new C(2); + const newArr: BigInt64Array = BigInt64Array.from(origArr, (v: number, k: number) => { + return new BigInt(v + o.offset); + }); // [3,4,5] + console.info(newArr); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-BigUint64Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-BigUint64Array.md new file mode 100644 index 0000000000000000000000000000000000000000..6b1c6984e8010351efafb2b18e7db65f9bcdaaaa --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-BigUint64Array.md @@ -0,0 +1,694 @@ +# BigUint64Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更](#from静态方法变更) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | BigUint64Array的迭代器对象。 | + +**示例：** + ```typescript + let a = new BigUint64Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | BigUint64Array的迭代器对象。 | + +**示例：** + ```typescript + let arr: BigUint64Array = new BigUint64Array([1n]); + let result: IterableIterator = arr.$_iterator(); + ``` + +- 适配建议： + 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的bigint值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示通过，false表示不通过。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigUint64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.every(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的bigint值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示通过，false表示不通过。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.every((element: bigint, index: number, array: BigUint64Array) => { + return element > o.base; + }) + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: bigint, index: number, array: BigUint64Array) => any, thisArg?: any): BigUint64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | BigUint64Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigUint64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.filter(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean): BigUint64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | BigUint64Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.filter((element: bigint, index: number, array: BigUint64Array) => { + return element > o.base; + }) + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean, thisArg?: any): bigint | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | bigint \| undefined | 第一个通过测试的元素，未找到则返回undefined。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigUint64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.find(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean): bigint | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | bigint \| undefined | 第一个通过测试的元素，未找到则返回undefined。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.find((element: bigint, index: number, array: BigUint64Array) => { + return element > o.base; + }) + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 第一个通过测试元素的索引，未找到返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigUint64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.findIndex(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 第一个通过测试元素的索引，未找到返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.findIndex((element: bigint, index: number, array: BigUint64Array) => { + return element > o.base; + }) + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: bigint, index: number, array: BigUint64Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 为每个元素执行的函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigUint64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.forEach(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: bigint, index: number, array: BigUint64Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 为每个元素执行的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +**示例：** + ```typescript + function main() { + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + arr.forEach((element: bigint, index: number, array: BigUint64Array) => { + console.info(element, index); + }) + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: bigint, index: number, array: BigUint64Array) => bigint, thisArg?: any): BigUint64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 生成新数组元素的函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 当前函数计算后新得到的bigint值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | BigUint64Array | 新数组。 | + +**示例：** + ```typescript + class C { + map(element: bigint, index: number, array: BigUint64Array) :bigint{ + return this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.map(new C(1n).map, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: bigint, index: number, array: BigUint64Array) => bigint): BigUint64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 生成新数组元素的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 当前函数计算后新得到的bigint值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | BigUint64Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let o = new C(2n); + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.map((element: bigint, index: number, array: BigUint64Array) => { + return o.base; + }) + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示有，false表示没有。 | + +**示例：** + ```typescript + class C { + comp(element: bigint, index: number, array: BigUint64Array) :boolean{ + return element > this.base; + } + base: bigint; + constructor(base: bigint) { + this.base = base; + } + } + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result = arr.some(new C(1n).comp, new C(2n)); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: bigint, index: number, array: BigUint64Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。| + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | BigUint64Array | 是 | 调用的原始BigUint64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示有，false表示没有。 | + +**示例：** + ```typescript + let arr: BigUint64Array = new BigUint64Array([1n, 2n, 3n]); + let result: BigUint64Array = arr.reverse(); + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: U, k: number) => bigint, thisArg?: any): BigUint64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 要转换的对象。 | + | mapfn | function | 是 | map函数。 | + | thisArg | any | 否 | 执行mapfn时使用的this值。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | U | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 返回的一个bigint类型值，作为新BigUint64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | BigUint64Array | 新数组。 | + +**示例：** + ```typescript + class C { + add(v: number, k: number): bigint { + return BigInt(v + this.offset); + } + offset: number; + constructor(offset: number) { + this.offset = offset; + } + } + const newArr = BigUint64Array.from([1, 2, 3], new C(1).add, new C(2)); // [3,4,5] + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike): BigUint64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 要转换的对象。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | U | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | bigint | 返回的一个bigint类型值，作为新BigUint64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | BigUint64Array | 新数组。 | + +**示例：** + ```typescript + class C { + offset: number; + constructor(offset: number) { + this.offset = offset; + } + } + + function main() { + const origArr: Array = new Array(1, 2, 3); + let o = new C(2); + const newArr = BigUint64Array.from(origArr, (v: number, k: number) => { + return new BigInt(v + o.offset); + }); + console.info(newArr.toString()); + } + ``` + +- 适配建议： + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Constructor.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Constructor.md new file mode 100644 index 0000000000000000000000000000000000000000..f10625c7914213bae7f7d9e252e4e5d4ccf392d6 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Constructor.md @@ -0,0 +1,687 @@ +# Constructor + +## 变更梗概 +- [BigIntConstructor](#bigintconstructor) +- [BooleanConstructor](#booleanconstructor) +- [DateConstructor](#dateconstructor) +- [ErrorConstructor](#errorconstructor) +- [EvalErrorConstructor](#evalerrorconstructor) +- [RangeErrorConstructor](#rangeerrorconstructor) +- [SyntaxErrorConstructor](#syntaxerrorconstructor) +- [TypeErrorConstructor](#typeerrorconstructor) +- [URIErrorConstructor](#urierrorconstructor) +- [ReferenceErrorConstructor](#referenceerrorconstructor) +- [RegExpConstructor](#regexpconstructor) + +## BigIntConstructor + +### 变更梗概 +- [BigIntConstructor-构造函数调用变更](#bigintconstructor-构造函数调用变更) + +### 变更详情 + +#### BigIntConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(value: bigint | boolean | number | string): bigint` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint \| boolean \| number \| string | 是 | 要转换的值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | bigint | 转换后的BigInt值。 | + +**示例：** + ```typescript + function createBigInt(ctor: BigIntConstructor) { + return ctor(1); + } + function createBigIntDirect() { + return BigInt(1); + } + ``` + +**ArkTS1.2版本签名：** + `static BigInt.invoke(value: bigint | boolean | number | string): bigint` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint \| boolean \| number \| string | 是 | 要转换的值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | bigint | 转换后的BigInt值。 | + +**示例：** + ```typescript + function creatBigInt() { + return new BigInt(1) + } + + function main() { + console.info(creatBigInt()); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式创建对象。 + +## BooleanConstructor + +### 变更梗概 +- [BooleanConstructor-构造函数调用变更](#booleanconstructor-构造函数调用变更) + +### 变更详情 + +#### BooleanConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(value?: T): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 否 | 要转换的值，默认值为false。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 转换后的布尔值。 | + +**示例：** + ```typescript + function createBigInt(ctor: BooleanConstructor) { + return ctor(true); + } + ``` + +**ArkTS1.2版本签名：** + `static Boolean.invoke(value?: T): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 否 | 要转换的值，默认值为false。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 转换后的布尔值。 | + +**示例：** + ```typescript + function createBigInt() { + return Boolean(true); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式创建对象。 + +## DateConstructor + +### 变更梗概 +- [DateConstructor-构造函数调用变更](#dateconstructo-构造函数调用变更) + +### 变更详情 + +#### DateConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(): string` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | string | 日期字符串。 | + +**示例：** + ```typescript + function createDate(ctor: DateConstructor) { + return ctor(); + } + ``` + +**ArkTS1.2版本签名：** + `static Date.invoke(): string` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | string | 日期字符串。 | + +**示例：** + ```typescript + function createDate() { + return Date(); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 + +## ErrorConstructor + +### 变更梗概 +- [ErrorConstructor-构造函数调用变更](#errorconstructor-构造函数调用变更) + +### 变更详情 + +#### ErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): Error` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"Error"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Error | 新创建的Error对象。 | + +**示例：** + ```typescript + function createError(ctor: ErrorConstructor) { + return ctor("some error"); + } + function createErrorDirect() { + return Error("some error"); + } + ``` + +**ArkTS1.2版本签名：** + `static invoke(message?: string): Error` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"Error"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Error | 新创建的Error对象。 | + +**示例：** + ```typescript + function createError() { + return Error("some error"); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 + +## EvalErrorConstructor + +### 变更梗概 +- [EvalErrorConstructor-构造函数调用变更](#evalerrorconstructor-构造函数调用变更) + +### 变更详情 + +#### EvalErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): EvalError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"EvalError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | EvalError | 新创建的EvalError对象。 | + +**示例：** + ```typescript + function createError(ctor: EvalErrorConstructor) { + return ctor("some error"); + } + function createErrorDirect() { + return EvalError("some error"); + } + ``` + +**ArkTS1.2版本签名：** + `static invoke(message?: string): EvalError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"EvalError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | EvalError | 新创建的EvalError对象。 | + +**示例：** + ```typescript + function createError() { + return EvalError("some error"); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 + +## RangeErrorConstructor + +### 变更梗概 +- [RangeErrorConstructor-构造函数调用变更](#rangeerrorconstructor-构造函数调用变更) + +### 变更详情 + +#### RangeErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): RangeError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"RangeError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | RangeError | 创建的RangeError对象。 | + +**示例：** + ```typescript + function create(ctor: RangeErrorConstructor) { + return ctor("invalid range"); + } + ``` + +**ArkTS1.2版本签名：** + `static RangeError.invoke(message?: string): RangeError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"RangeError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | RangeError | 创建的RangeError对象。 | + +**示例：** + ```typescript + RangeError("invalid range"); // 自动调用invoke + ``` + +- 适配建议： + 直接调用而非通过Constructor类型。 + +## ReferenceErrorConstructor + +### 变更梗概 +- [ReferenceErrorConstructor-构造函数调用变更](#referenceerrorconstructor-构造函数调用变更) + +### 变更详情 + +#### ReferenceErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): ReferenceError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"ReferenceError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | ReferenceError | 创建的ReferenceError对象。 | + +**示例：** + ```typescript + function create(ctor: ReferenceErrorConstructor) { + return ctor("undefined variable"); + } + ``` + +**ArkTS1.2版本签名：** + `static ReferenceError.invoke(message?: string): ReferenceError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"ReferenceError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | ReferenceError | 创建的ReferenceError对象。 | + +**示例：** + ```typescript + ReferenceError("undefined variable"); + ``` + +- 适配建议： + 直接创建对应类型的对象，不直接使用constructor类。 + +## RegExpConstructor + +### 变更梗概 +- [RegExpConstructor-构造函数调用单参数变更](#regexpconstructor-构造函数调用单参数变更) +- [RegExpConstructor-构造函数调用双参数变更](#regexpconstructor-构造函数调用双参数变更) +- [RegExpConstructor-构造函数调用双参数标志可选变更](#regexpconstructor-构造函数调用双参数标志可选变更) + +### 变更详情 + +#### RegExpConstructor-构造函数调用单参数变更 +- ArkTS1.1 版本签名： + `(pattern: RegExp | string): RegExp` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `pattern` | `RegExp | string` | 是 | 正则表达式模式或字符串形式的模式。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `RegExp` | 构造出的正则表达式对象。 | + +**示例：** + ```typescript + function create(ctor: RegExpConstructor) { + return ctor("regexp"); + } + ``` + +**ArkTS1.2版本签名：** + `static RegExp.invoke(pattern: RegExp | string): RegExp` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `pattern` | `RegExp | string` | 是 | 正则表达式模式或字符串形式的模式。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `RegExp` | 构造出的正则表达式对象。 | + +**示例：** + ```typescript + function createDirect() { + return RegExp("regexp"); + } + ``` + +- 适配建议： + 直接创建对应类型的对象，不直接使用constructor类。 + + +#### RegExpConstructor-构造函数调用双参数变更 +- ArkTS1.1 版本签名： + `(pattern: RegExp | string, flags?: string): RegExp` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `pattern` | `RegExp | string` | 是 | 正则表达式模式或字符串形式的模式。 | + | `flags` | `string` | 否 | 正则表达式的标志，默认值为null。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `RegExp` | 构造出的正则表达式对象。 | + +**示例：** + ```typescript + function create(ctor: RegExpConstructor) { + return ctor("regexp"); + } + ``` + +**ArkTS1.2版本签名：** + `static RegExp.invoke(pattern: RegExp | string, flags?: string): RegExp` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `pattern` | `RegExp | string` | 是 | 正则表达式模式或字符串形式的模式。 | + | `flags` | `string` | 否 | 正则表达式的标志，默认值为null。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `RegExp` | 构造出的正则表达式对象。 | + +**示例：** + ```typescript + function createDirect() { + return RegExp("regexp", "i"); + } + ``` + +- 适配建议： + 直接创建对应类型的对象，不直接使用constructor类。 + + +#### RegExpConstructor-构造函数调用双参数标志可选变更 +- ArkTS1.1 版本签名： + `(pattern: string, flags?: string): RegExp` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `pattern` | `string` | 是 | 字符串形式的正则表达式模式。 | + | `flags` | `string` | 否 | 正则表达式的标志，默认值为null。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `RegExp` | 构造出的正则表达式对象。 | + +**示例：** + ```typescript + function create(ctor: RegExpConstructor) { + return ctor("regexp"); + } + ``` + +**ArkTS1.2版本签名：** + `static RegExp.invoke(pattern: string, flags?: string): RegExp` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `pattern` | `string` | 是 | 字符串形式的正则表达式模式。 | + | `flags` | `string` | 否 | 正则表达式的标志，默认值为null。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `RegExp` | 构造出的正则表达式对象。 | + +**示例：** + ```typescript + function createDirect() { + return RegExp("regexp"); + } + ``` + +- 适配建议： + 直接创建对应类型的对象，不直接使用constructor类。 + +## SyntaxErrorConstructor + +### 变更梗概 +- [SyntaxErrorConstructor-构造函数调用变更](#syntaxerrorconstructor-构造函数调用变更) + +### 变更详情 + +#### SyntaxErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): SyntaxError` + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"SyntaxError"。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | SyntaxError | 返回SyntaxError对象。 | + +**示例：** + ```typescript + function createError(ctor: SyntaxErrorConstructor) { + return ctor("some error"); + } + function createErrorDirect() { + return SyntaxError("some error"); + } + ``` + +**ArkTS1.2版本签名：** + `static SyntaxError.invoke(message?: string): SyntaxError` + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"SyntaxError"。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | SyntaxError | 返回SyntaxError对象。 | + +**示例：** + ```typescript + function createError() { + return SyntaxError("some error"); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 + +## TypeErrorConstructor + +### 变更梗概 +- [TypeErrorConstructor-构造函数调用变更](#typeerrorconstructor-构造函数调用变更) + +### 变更详情 + +#### TypeErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): TypeError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"TypeError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | TypeError | 返回TypeError对象。 | + +**示例：** + ```typescript + function createError(ctor: TypeErrorConstructor) { + return ctor("some error"); + } + function createErrorDirect() { + return TypeError("some error"); + } + ``` + +**ArkTS1.2版本签名：** + `static TypeError.invoke(message?: string): TypeError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"TypeError"。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | TypeError | 返回TypeError对象。 | + +**示例：** + ```typescript + function createError() { + return TypeError("some error"); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 + +## URIErrorConstructor + +### 变更梗概 +- [URIErrorConstructor-构造函数调用变更](#urierrorconstructor-构造函数调用变更) + +### 变更详情 + +#### URIErrorConstructor-构造函数调用变更 +**ArkTS1.1版本签名：** + `(message?: string): URIError` + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"URIError"。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | URIError | 返回URIError对象。 | + +**示例：** + ```typescript + function createError(ctor: URIErrorConstructor) { + return ctor("some error"); + } + function createErrorDirect() { + return URIError("some error"); + } + ``` + +**ArkTS1.2版本签名：** + `static URIError.invoke(message?: string): URIError` + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | message | string | 否 | 错误信息，默认值为"URIError"。 | + +**返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | URIError | 返回URIError对象。 | + +**示例：** + ```typescript + function createError() { + return URIError("some error"); + } + ``` + +- 适配建议： + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Float32Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Float32Array.md new file mode 100644 index 0000000000000000000000000000000000000000..80303e65e56563d657d6d36159acf57ed8859b1e --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Float32Array.md @@ -0,0 +1,849 @@ +# Float32Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every变更](#every变更) +- [filter变更](#filter变更) +- [find变更](#find变更) +- [findIndex变更](#findindex变更) +- [forEach变更](#foreach变更) +- [map变更](#map变更) +- [some变更](#some变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | Float32Array的迭代器。 | + +**示例：** + ```typescript + let a = new Float32Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | Float32Array的迭代器。 | + +**示例：** + ```typescript + let a = new Float32Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** + 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + + +### every变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: number, index: number, array: Float32Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float32Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.every(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: number, index: number, array: Float32Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Float32Array) { + return arr.every((value: number, index: number, arr: Float32Array)=>{return value < this.base}) + } + } + function main() { + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(4) + a.callEvery(arr) // false + b.callEvery(arr) // true + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: number, index: number, array: Float32Array) => any, thisArg?: any): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行 `predicate` 时 `this` 指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 是 | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 包含所有满足`predicate`的元素的新数组。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float32Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.filter(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: number, index: number, array: Float32Array) => boolean): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 包含所有满足`predicate`的元素的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return arr.filter((value: number, index: number, arr: Float32Array)=>{return value < this.base}) + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) // [1] + b.call(arr) // [1, 2] + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### find变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: number, index: number, obj: Float32Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number | undefined` | 如果找到满足`predicate`的元素，则返回该元素，否则返回`undefined`。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float32Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.find(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: number, index: number, obj: Float32Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number | undefined` | 如果找到满足`predicate`的元素，则返回该元素，否则返回`undefined`。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return arr.find((value: number, index: number, arr: Float32Array)=>{return value >= this.base}) + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) // 2 + b.call(arr) // 3 + + console.info(a.call(arr)) + console.info(b.call(arr)) + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### findIndex变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: number, index: number, array: Float32Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number` | 如果找到满足`predicate`的元素，则返回该元素的索引，否则返回`-1`表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float32Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.findIndex(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: number, index: number, array: Float32Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number` | 如果找到满足`predicate`的元素，则返回该元素的索引，否则返回`-1`表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return arr.findIndex((value: number, index: number, arr: Float32Array)=>{return value >= this.base}) + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) // 1 + b.call(arr) // 2 + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### forEach变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Float32Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素执行的函数。 | + | `thisArg` | `any` | 否 | 执行`callbackfn`时`this`指向的对象，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float32Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.forEach(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Float32Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素执行的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return arr.forEach((value: number, index: number, arr: Float32Array)=>{console.info(value + this.base)}) + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### map变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: number, index: number, array: Float32Array) => number, thisArg?: any): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素调用的函数，返回新数组中的元素。 | + | `thisArg` | `any` | 否 | 执行`callbackfn`时`this`指向的对象，默认值为undefined，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 一个新的 Float32Array，包含`callbackfn`对每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + map(element: number, index: number, array: Float32Array): number { + return this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.map(new C(1).map, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: number, index: number, array: Float32Array) => number): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素调用的函数，返回新数组中的元素。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 一个新的Float32Array，包含`callbackfn`对每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return arr.map((value: number, index: number, arr: Float32Array)=>{return value + this.base}) + } + } + function main() { + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### some变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: number, index: number, array: Float32Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float32Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float32Array = new Float32Array([1, 2, 3]); + let result = arr.some(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: number, index: number) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float32Array | 是 | 调用的原始Float32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return arr.some((value: number, index: number, arr: Float32Array)=>{return value > this.base}) + } + } + function main() { + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更1 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `ArrayLike` | 是 | 类似数组或可迭代的对象。 | + | `mapfn` | `function` | 是 | 为`arrayLike`中的每个元素调用的函数，返回新数组中的元素。 | + | `thisArg` | `any` | 否 | 执行`mapfn`时`this`指向的对象，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 一个新的 Float32Array，包含`mapfn`对`arrayLike`中每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Float32Array.from(arr, a.foo, a) + let arr3 = Float32Array.from(arr, a.foo, b) + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `ArrayLike` | 是 | 类似数组或可迭代的对象。 | + | `mapfn` | `function` | 是 | 为`arrayLike`中的每个元素调用的函数，返回新数组中的元素。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 一个新的 Float32Array，包含`mapfn`对`arrayLike`中每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Float32Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + function main() { + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更2 +**ArkTS1.1版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `Iterable` | 是 | 可迭代的数值集合 | + | `mapfn` | `function` | 否 | 选映射函数，对每个元素进行转换处理，默认undefined。 | + | `thisArg` | `any` | 否 | 执行`mapfn`时`this`指向的对象，默认undefined。| + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 从指定数据源创建的新的 64 位浮点型数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Float32Array.from(arr, a.foo, a) + let arr3 = Float32Array.from(arr, a.foo, b) + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Float32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `Iterable` | 是 | 可迭代的数值集合 | + | `mapfn` | `function` | 否 | 选映射函数，对每个元素进行转换处理，默认undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float32Array` | 从指定数据源创建的新的 64 位浮点型数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float32Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + function main() { + let arr: Float32Array = new Float32Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Float64Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Float64Array.md new file mode 100644 index 0000000000000000000000000000000000000000..845c641adcbebc6556903a1bb4e68f70d75fce5e --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Float64Array.md @@ -0,0 +1,848 @@ +# Float64Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every变更](#every变更) +- [filter变更](#filter变更) +- [find变更](#find变更) +- [findIndex变更](#findindex变更) +- [forEach变更](#foreach变更) +- [map变更](#map变更) +- [some变更](#some变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | Float64Array的迭代器。 | + +**示例：** + ```typescript + let a = new Float64Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | Float64Array的迭代器。 | + +**示例：** + ```typescript + let a = new Float64Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** + 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + + +### every变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: number, index: number, array: Float64Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float64Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.every(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: number, index: number, array: Float64Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Float64Array) { + return arr.every((value: number, index: number, arr: Float64Array)=>{return value < this.base}) + } + } + function main() { + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(4) + a.callEvery(arr) // false + b.callEvery(arr) // true + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: number, index: number, array: Float64Array) => any, thisArg?: any): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行 `predicate` 时 `this` 指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 是 | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 包含所有满足`predicate`的元素的新数组。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float64Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.filter(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: number, index: number, array: Float64Array) => boolean): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 包含所有满足`predicate`的元素的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return arr.filter((value: number, index: number, arr: Float64Array)=>{return value < this.base}) + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) // [1] + b.call(arr) // [1, 2] + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### find变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: number, index: number, obj: Float64Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number | undefined` | 如果找到满足`predicate`的元素，则返回该元素，否则返回`undefined`。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float64Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.find(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: number, index: number, obj: Float64Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number | undefined` | 如果找到满足`predicate`的元素，则返回该元素，否则返回`undefined`。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return arr.find((value: number, index: number, arr: Float64Array)=>{return value >= this.base}) + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) // 2 + b.call(arr) // 3 + + console.info(a.call(arr)) + console.info(b.call(arr)) + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### findIndex变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: number, index: number, array: Float64Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number` | 如果找到满足`predicate`的元素，则返回该元素的索引，否则返回`-1`表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float64Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.findIndex(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: number, index: number, array: Float64Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `number` | 如果找到满足`predicate`的元素，则返回该元素的索引，否则返回`-1`表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return arr.findIndex((value: number, index: number, arr: Float64Array)=>{return value >= this.base}) + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) // 1 + b.call(arr) // 2 + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### forEach变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Float64Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素执行的函数。 | + | `thisArg` | `any` | 否 | 执行`callbackfn`时`this`指向的对象，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float64Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.forEach(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Float64Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素执行的函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return arr.forEach((value: number, index: number, arr: Float64Array)=>{console.info(value + this.base)}) + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### map变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: number, index: number, array: Float64Array) => number, thisArg?: any): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素调用的函数，返回新数组中的元素。 | + | `thisArg` | `any` | 否 | 执行`callbackfn`时`this`指向的对象，默认值为undefined，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 一个新的 Float64Array，包含`callbackfn`对每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + map(element: number, index: number, array: Float64Array): number { + return this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.map(new C(1).map, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: number, index: number, array: Float64Array) => number): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `callbackfn` | `function` | 是 | 为数组中的每个元素调用的函数，返回新数组中的元素。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 一个新的Float64Array，包含`callbackfn`对每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return arr.map((value: number, index: number, arr: Float64Array)=>{return value + this.base}) + } + } + function main() { + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### some变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: number, index: number, array: Float64Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + | `thisArg` | `any` | 否 | 执行`predicate`时`this`指向的对象，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + comp(element: number, index: number, array: Float64Array): boolean { + return element > this.base; + } + base: number; + constructor(base: number) { + this.base = base; + } + } + let arr: Float64Array = new Float64Array([1, 2, 3]); + let result = arr.some(new C(1).comp, new C(2)); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: number, index: number) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `predicate` | `function` | 是 | 用于测试每个元素的函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | bigint | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Float64Array | 是 | 调用的原始Float64Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `boolean` | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return arr.some((value: number, index: number, arr: Float64Array)=>{return value > this.base}) + } + } + function main() { + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更1 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `ArrayLike` | 是 | 类似数组或可迭代的对象。 | + | `mapfn` | `function` | 是 | 为`arrayLike`中的每个元素调用的函数，返回新数组中的元素。 | + | `thisArg` | `any` | 否 | 执行`mapfn`时`this`指向的对象，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 一个新的 Float64Array，包含`mapfn`对`arrayLike`中每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Float64Array.from(arr, a.foo, a) + let arr3 = Float64Array.from(arr, a.foo, b) + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `ArrayLike` | 是 | 类似数组或可迭代的对象。 | + | `mapfn` | `function` | 是 | 为`arrayLike`中的每个元素调用的函数，返回新数组中的元素。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 一个新的 Float64Array，包含`mapfn`对`arrayLike`中每个元素的调用结果。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Float64Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + function main() { + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更2 +**ArkTS1.1版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `Iterable` | 是 | 可迭代的数值集合 | + | `mapfn` | `function` | 否 | 选映射函数，对每个元素进行转换处理，默认undefined。 | + | `thisArg` | `any` | 否 | 执行`mapfn`时`this`指向的对象，默认undefined。| + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 从指定数据源创建的新的 64 位浮点型数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Float64Array.from(arr, a.foo, a) + let arr3 = Float64Array.from(arr, a.foo, b) + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Float64Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `arrayLike` | `Iterable` | 是 | 可迭代的数值集合 | + | `mapfn` | `function` | 否 | 选映射函数，对每个元素进行转换处理，默认undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Float64Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `Float64Array` | 从指定数据源创建的新的 64 位浮点型数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Float64Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + function main() { + let arr: Float64Array = new Float64Array([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + } + ``` + +**适配建议：** + 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Int16Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Int16Array.md new file mode 100644 index 0000000000000000000000000000000000000000..3fce085fb69a8fa2b72ee31405f2bee74a4b4890 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Int16Array.md @@ -0,0 +1,847 @@ +# Int16Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Int16Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Int16Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: number, index: number, array: Int16Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int16Array) { + return value < this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: number, index: number, array: Int16Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Int16Array) { + return arr.every((value: number, index: number, arr: Int16Array)=>{return value < this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: number, index: number, array: Int16Array) => any, thisArg?: any): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int16Array) { + return value < this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: number, index: number, array: Int16Array) => boolean): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return arr.filter((value: number, index: number, arr: Int16Array)=>{return value < this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: number, index: number, obj: Int16Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int16Array) { + return value >= this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: number, index: number, obj: Int16Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return arr.find((value: number, index: number, arr: Int16Array)=>{return value >= this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: number, index: number, obj: Int16Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int16Array) { + return value >= this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: number, index: number, obj: Int16Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return arr.findIndex((value: number, index: number, arr: Int16Array)=>{return value >= this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Int16Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int16Array) { + console.info(value + this.base) + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Int16Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return arr.forEach((value: number, index: number, arr: Int16Array)=>{console.info(value + this.base)}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: number, index: number, array: Int16Array) => number, thisArg?: any): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int16Array) { + return value + this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: number, index: number, array: Int16Array) => number): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return arr.map((value: number, index: number, arr: Int16Array)=>{return value + this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: number, index: number, array: Int16Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int16Array) { + return value > this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: number, index: number, array: Int16Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int16Array | 是 | 调用的原始Int16Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return arr.some((value: number, index: number, arr: Int16Array)=>{return value > this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int16Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Int16Array.from(arr, a.foo, a); + let arr3 = Int16Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int16Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int16Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更2 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int16Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Int16Array.from(arr, a.foo, a); + let arr3 = Int16Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Int16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int16Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Int16Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Int16Array = new Int16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Int32Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Int32Array.md new file mode 100644 index 0000000000000000000000000000000000000000..01e4f4df7fbb4e92a5c4491287028303a5442744 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Int32Array.md @@ -0,0 +1,847 @@ +# Int32Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Int32Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Int32Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: number, index: number, array: Int32Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int32Array) { + return value < this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: number, index: number, array: Int32Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Int32Array) { + return arr.every((value: number, index: number, arr: Int32Array)=>{return value < this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: number, index: number, array: Int32Array) => any, thisArg?: any): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int32Array) { + return value < this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: number, index: number, array: Int32Array) => boolean): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return arr.filter((value: number, index: number, arr: Int32Array)=>{return value < this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: number, index: number, obj: Int32Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int32Array) { + return value >= this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: number, index: number, obj: Int32Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return arr.find((value: number, index: number, arr: Int32Array)=>{return value >= this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: number, index: number, obj: Int32Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int32Array) { + return value >= this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: number, index: number, obj: Int32Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return arr.findIndex((value: number, index: number, arr: Int32Array)=>{return value >= this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Int32Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int32Array) { + console.info(value + this.base) + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Int32Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return arr.forEach((value: number, index: number, arr: Int32Array)=>{console.info(value + this.base)}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: number, index: number, array: Int32Array) => number, thisArg?: any): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int32Array) { + return value + this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: number, index: number, array: Int32Array) => number): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return arr.map((value: number, index: number, arr: Int32Array)=>{return value + this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: number, index: number, array: Int32Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int32Array) { + return value > this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: number, index: number, array: Int32Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int32Array | 是 | 调用的原始Int32Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return arr.some((value: number, index: number, arr: Int32Array)=>{return value > this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Int32Array.from(arr, a.foo, a); + let arr3 = Int32Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int32Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更2 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Int32Array.from(arr, a.foo, a); + let arr3 = Int32Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Int32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int32Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Int32Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Int32Array = new Int32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Int8Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Int8Array.md new file mode 100644 index 0000000000000000000000000000000000000000..ad6781ccf438556e03bc908e653bb059925e81d2 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Int8Array.md @@ -0,0 +1,847 @@ +# Int8Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Int8Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Int8Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int8Array) { + return value < this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: number, index: number, array: Int8Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Int8Array) { + return arr.every((value: number, index: number, arr: Int8Array)=>{return value < this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名：** + `filter(predicate: (value: number, index: number, array: Int8Array) => any, thisArg?: any): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int8Array) { + return value < this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: number, index: number, array: Int8Array) => boolean): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return arr.filter((value: number, index: number, arr: Int8Array)=>{return value < this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int8Array) { + return value >= this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: number, index: number, obj: Int8Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return arr.find((value: number, index: number, arr: Int8Array)=>{return value >= this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Int8Array) { + return value >= this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: number, index: number, obj: Int8Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return arr.findIndex((value: number, index: number, arr: Int8Array)=>{return value >= this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Int8Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int8Array) { + console.info(value + this.base) + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: number, index: number, array: Int8Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return arr.forEach((value: number, index: number, arr: Int8Array)=>{console.info(value + this.base)}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: number, index: number, array: Int8Array) => number, thisArg?: any): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int8Array) { + return value + this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: number, index: number, array: Int8Array) => number): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return arr.map((value: number, index: number, arr: Int8Array)=>{return value + this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Int8Array) { + return value > this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: number, index: number, array: Int8Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Int8Array | 是 | 调用的原始Int8Array数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return arr.some((value: number, index: number, arr: Int8Array)=>{return value > this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int8Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Int8Array.from(arr, a.foo, a); + let arr3 = Int8Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int8Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Int8Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + + +### from静态方法变更2 +**ArkTS1.1版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int8Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Int8Array.from(arr, a.foo, a); + let arr3 = Int8Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名：** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Int8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Int8Array的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Int8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Int8Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Int8Array = new Int8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-ReadOnly.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-ReadOnly.md new file mode 100644 index 0000000000000000000000000000000000000000..d0660f6ce3af3044877103204edcbaab25c5a794 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-ReadOnly.md @@ -0,0 +1,835 @@ +# StdLib1 + +## 变更梗概 +- [ReadonlyArray](#readonlyarray) +- [ReadonlyMap](#readonlymap) +- [ReadonlySet](#readonlyset) + +## ReadonlyArray + +### 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [concat方法参数限制](#concat方法参数限制) +- [every方法签名变更](#every方法签名变更) +- [filter方法签名变更](#filter方法签名变更) +- [find方法签名变更](#find方法签名变更) +- [findIndex方法签名变更](#findindex方法签名变更) +- [flat方法移除](#flat方法移除) +- [flatMap方法移除](#flatmap方法移除) +- [ReadonlyArray-forEach方法签名变更](#readonlyarray-foreach方法签名变更) +- [map方法签名变更](#map方法签名变更) +- [some方法签名变更](#some方法签名变更) + +### 变更详情 + +#### Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 只读数组迭代器。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = ["a"]; + Reflect.get(arr, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 只读数组迭代器。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = ["a"]; + arr.$_iterator(); + ``` + +**适配建议：** + 使用for...of替代直接迭代器访问。 + + +#### concat方法参数限制 +**ArkTS1.1版本签名：** + `concat(...items: (T | ConcatArray)[]): T[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | items | (T \| ConcatArray\)[] | 是 | 待连接元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 新数组。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1]; + arr.concat(2, [3]); // [1, 2, 3] + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 手动转换后连接： + ```typescript + let arr1: ReadonlyArray = [1]; + let temp = [2]; + arr1.concat(temp); // 先确保参数类型一致 + ``` + + +#### every方法签名变更 +**ArkTS1.1版本签名：** + `every(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): boolean` + `every(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: any): this is readonly S[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + test(v: number) { return v > this.limit; } + limit = 1; + } + let arr: ReadonlyArray = [2,3]; + arr.every(new C().test, {limit: 2}); + ``` + +**ArkTS1.2版本签名：** + `every(predicate: (value: T, index: number, array: readonly T[]) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [2,3]; + let limit = 2; + arr.every(v => v > limit); + ``` + +**适配建议：** + 使用闭包变量替代thisArg。 + + +#### filter方法签名变更 +**ArkTS1.1版本签名：** + - `filter(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): T[]` + - `filter(predicate: (value: T, index: number, array: readonly T[]) => value is S, thisArg?: any): S[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 过滤函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 过滤后的新数组。 | + +**示例：** + ```typescript + class Filter { + criteria(v: number) { return v > this.min; } + min = 2; + } + let arr: ReadonlyArray = [1,2,3]; + arr.filter(new Filter().criteria, {min: 1}); + ``` + +**ArkTS1.2版本签名：** + `filter(predicate: (value: T, index: number, array: readonly T[]) => boolean): T[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 过滤函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T[] | 过滤后的新数组。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1,2,3]; + let min = 1; + arr.filter(v => v > min); + ``` + +**适配建议：** + 通过外部变量传递上下文。 + + +#### find方法签名变更 +**ArkTS1.1版本签名：** + `find(predicate: (value: T, index: number, obj: readonly T[]) => unknown, thisArg?: any): T | undefined` + `find(predicate: (this: void, value: T, index: number, obj: readonly T[]) => value is S, thisArg?: any): S | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，判断当前是否找到匹配项。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T \| undefined | 找到的元素或undefined。 | + +**示例：** + ```typescript + class Matcher { + check(v: number) { return v === this.target; } + target = 2; + } + let arr: ReadonlyArray = [1,2,3]; + arr.find(new Matcher().check, {target: 3}); + ``` + +**ArkTS1.2版本签名：** + `find(predicate: (value: T, index: number, obj: readonly T[]) => boolean): T | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T \| undefined | 找到的元素或undefined。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1,2,3]; + let target = 3; + arr.find(v => v === target); + ``` + +**适配建议：** + 使用闭包捕获外部变量。 + + +#### findIndex方法签名变更 +**ArkTS1.1版本签名：** + `findIndex(predicate: (value: T, index: number, obj: readonly T[]) => unknown, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 元素索引或-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class Matcher { + check(v: number) { return v > this.limit; } + limit = 1; + } + let arr: ReadonlyArray = [1,2,3]; + arr.findIndex(new Matcher().check, {limit: 2}); + ``` + +**ArkTS1.2版本签名：** + `findIndex(predicate: (value: T, index: number, obj: readonly T[]) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 元素索引，-1表示未找到满足的元素。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1,2,3]; + let limit = 2; + arr.findIndex(v => v > limit); + ``` + +**适配建议：** + 通过外部变量传递条件参数。 + + +#### flat方法移除 +**ArkTS1.1版本签名：** + `flat(this: A, depth?: D): FlatArray[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | depth | D | 否 | 展开深度，默认值为1。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | FlatArray\[] | 展开后的数组。 | + +**示例：** + ```typescript + type Nested = number | Nested[]; + let arr: ReadonlyArray = [[1], 2, [3]]; + arr.flat(); // [1, 2, 3] + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 手动实现展开逻辑。 + ```typescript + function flatten(arr: any[]): number[] { + return arr.reduce((acc, val) => acc.concat(Array.isArray(val) ? flatten(val) : val), []); + } + ``` + + +#### flatMap方法移除 +**ArkTS1.1版本签名：** + `flatMap(callback: (this: This, value: T, index: number, array: T[]) => U | ReadonlyArray, thisArg?: This): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | function | 是 | 映射函数。 | + | thisArg | This | 否 | 执行上下文，默认值为undefined。 | + +**callback函数参数说明：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | this | This | 是 | 由 thisArg 指定的上下文默认undefined。 | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | T[] | 是 | 调用的原始数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U \| ReadonlyArray\ | 可返回单个值U或U类型的数组。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 映射并展开后的数组。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = ["a b", "c d"]; + arr.flatMap(s => s.split(" ")); // ["a", "b", "c", "d"] + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 不使用flatMap。 + + +#### ReadonlyArray-forEach方法签名变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: T, index: number, array: readonly T[]) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +**示例：** + ```typescript + class Logger { + log(v: number) { console.info(v + this.offset); } + offset = 10; + } + let arr: ReadonlyArray = [1,2]; + arr.forEach(new Logger().log, {offset: 20}); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: T, index: number, array: readonly T[]) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1,2]; + let offset = 20; + arr.forEach(v => console.info(v + offset)); + ``` + +**适配建议：** + 使用箭头函数捕获外部变量。 + + +#### map方法签名变更 +**ArkTS1.1版本签名：** + `map(callbackfn: (value: T, index: number, array: readonly T[]) => U, thisArg?: any): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U | 映射后的值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 映射后的新数组。 | + +**示例：** + ```typescript + class Transformer { + transform(v: number) { return v * this.factor; } + factor = 2; + } + let arr: ReadonlyArray = [1,2]; + arr.map(new Transformer().transform, {factor: 3}); + ``` + +**ArkTS1.2版本签名：** + `map(callbackfn: (value: T, index: number, array: readonly T[]) => U): U[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | U | 映射后的值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | U[] | 映射后的新数组。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1,2]; + let factor = 3; + arr.map(v => v * factor); + ``` + +**适配建议：** + 通过闭包传递上下文参数。 + + +#### some方法签名变更 +**ArkTS1.1版本签名：** + `some(predicate: (value: T, index: number, array: readonly T[]) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，判断当前元素是否满足predicate。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class Checker { + test(v: number) { return v > this.threshold; } + threshold = 2; + } + let arr: ReadonlyArray = [1,2,3]; + arr.some(new Checker().test, {threshold: 1}); + ``` + +**ArkTS1.2版本签名：** + `some(predicate: (value: T, index: number, array: readonly T[]) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | index | number | 是 | 当前元素的索引。 | + | array | readonly T[] | 是 | 调用的原始数组。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + let arr: ReadonlyArray = [1,2,3]; + let threshold = 1; + arr.some(v => v > threshold); + ``` + +**适配建议：** + 使用外部变量传递条件参数。 + +## ReadonlyMap + +### 变更梗概 +- [ReadonlyMap-Symbol_iterator变更](#readonlymap-symbol_iterator变更) +- [ReadonlyMap-forEach方法签名变更](#readonlmap-foreach方法签名变更) + +### 变更详情 +#### ReadonlyMap-Symbol_iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator<[K, V]>` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\<[K, V]\> | 只读Map的迭代器。 | + +**示例：** + ```typescript + let m: ReadonlyMap = new Map(); + let iter = Reflect.get(m, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator<[K, V]>` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\<[K, V]\> | 只读Map的迭代器。 | + +**示例：** + ```typescript + const m: ReadonlyMap = new Map(); + let iter = m.$_iterator(); + ``` + +**适配建议：** + 使用for...of替代直接迭代器访问。 + + +#### ReadonlyMap-forEach方法签名变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: V, key: K, map: ReadonlyMap) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | V | 是 | 当前遍历的键值对中的值。 | + | key | K | 是 | 当前遍历的键值对中的键。 | + | map | ReadonlyMap\ | 是 | 调用的原始Map。 | + +**示例：** + ```typescript + const m: ReadonlyMap = new Map(); + m.forEach((value, key) => {}, new Ctx()); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: V, key: K, map: ReadonlyMap) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | V | 是 | 当前被遍历的数组元素的值。 | + | key | K | 是 | 当前元素的索引。 | + | map | ReadonlyMap\ | 是 | 调用的原始Map。 | + +**示例：** + ```typescript + const m: ReadonlyMap = new Map(); + m.forEach((value, key) => console.info(key, value)); + ``` + +**适配建议：** + 使用闭包替代thisArg参数。 + +## ReadonlySet + +### 变更梗概 +- [ReadonlySet-Symbol.iterator变更](#readonlyset-symboliterator变更) +- [ReadonlySet-forEach方法签名变更](#readonlyset-foreach方法签名变更) + +### 变更详情 + +#### ReadonlySet-Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 只读Set的迭代器。 | + +**示例：** + ```typescript + let set: ReadonlySet = new Set(["a"]); + Reflect.get(set, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 只读Set的迭代器。 | + +**示例：** + ```typescript + let set: ReadonlySet = new Set(["a"]); + set.$_iterator(); + ``` + +**适配建议：** + 使用for...of替代直接迭代器访问。 + + +#### ReadonlySet-forEach方法签名变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: T, value2: T, set: ReadonlySet) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前遍历的键值对中的值。 | + | value2 | T | 是 | 与value相同。 | + | set | ReadonlySet\ | 是 | 调用的原始set。 | + +**示例：** + ```typescript + class Printer { + print(v: string) { console.info(v + this.suffix); } + suffix = "!"; + } + let set: ReadonlySet = new Set(["a"]); + set.forEach(new Printer().print, {suffix: "?"}); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: T, value2: T, set: ReadonlySet) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前被遍历的数组元素的值。 | + | value2 | T | 是 | 当前元素的索引。 | + | set | ReadonlySet\ | 是 | 调用的原始set。 | + +**示例：** + ```typescript + let set: ReadonlySet = new Set(["a"]); + let suffix = "?"; + set.forEach(v => console.info(v + suffix)); + ``` + +**适配建议：** + 使用闭包捕获外部变量。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint16Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint16Array.md new file mode 100644 index 0000000000000000000000000000000000000000..40d59cc7015cea7a4fc4969fd2f80f97a9d68ca4 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint16Array.md @@ -0,0 +1,845 @@ +# Uint16Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名:** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Uint16Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名:** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Uint16Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名:** + `every(predicate: (value: number, index: number, array: Uint16Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint16Array) { + return value < this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `every(predicate: (value: number, index: number, array: Uint16Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Uint16Array) { + return arr.every((value: number, index: number, arr: Uint16Array)=>{return value < this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名:** + `filter(predicate: (value: number, index: number, array: Uint16Array) => any, thisArg?: any): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint16Array) { + return value < this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `filter(predicate: (value: number, index: number, array: Uint16Array) => boolean): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return arr.filter((value: number, index: number, arr: Uint16Array)=>{return value < this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名:** + `find(predicate: (value: number, index: number, obj: Uint16Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint16Array) { + return value >= this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `find(predicate: (value: number, index: number, obj: Uint16Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return arr.find((value: number, index: number, arr: Uint16Array)=>{return value >= this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint16Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint16Array) { + return value >= this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint16Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return arr.findIndex((value: number, index: number, arr: Uint16Array)=>{return value >= this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint16Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint16Array) { + console.info(value + this.base) + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint16Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return arr.forEach((value: number, index: number, arr: Uint16Array)=>{console.info(value + this.base)}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint16Array) => number, thisArg?: any): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint16Array) { + return value + this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint16Array) => number): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return arr.map((value: number, index: number, arr: Uint16Array)=>{return value + this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名:** + `some(predicate: (value: number, index: number, array: Uint16Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint16Array) { + return value > this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `some(predicate: (value: number, index: number, array: Uint16Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint16Array | 是 | 调用的原始Uint16Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return arr.some((value: number, index: number, arr: Uint16Array)=>{return value > this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint16Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint16Array.from(arr, a.foo, a); + let arr3 = Uint16Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint16Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint16Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更2 +**ArkTS1.1版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint16Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint16Array.from(arr, a.foo, a); + let arr3 = Uint16Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Uint16Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint16Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint16Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Uint16Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint16Array = new Uint16Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint32Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint32Array.md new file mode 100644 index 0000000000000000000000000000000000000000..8f3f890ca58e4293ed7fe2774c595dcf8c8a2609 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint32Array.md @@ -0,0 +1,845 @@ +# Uint32Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名:** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Uint32Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名:** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Uint32Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名:** + `every(predicate: (value: number, index: number, array: Uint32Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint32Array) { + return value < this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `every(predicate: (value: number, index: number, array: Uint32Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Uint32Array) { + return arr.every((value: number, index: number, arr: Uint32Array)=>{return value < this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名:** + `filter(predicate: (value: number, index: number, array: Uint32Array) => any, thisArg?: any): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint32Array) { + return value < this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `filter(predicate: (value: number, index: number, array: Uint32Array) => boolean): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return arr.filter((value: number, index: number, arr: Uint32Array)=>{return value < this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名:** + `find(predicate: (value: number, index: number, obj: Uint32Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint32Array) { + return value >= this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `find(predicate: (value: number, index: number, obj: Uint32Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return arr.find((value: number, index: number, arr: Uint32Array)=>{return value >= this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint32Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint32Array) { + return value >= this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint32Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return arr.findIndex((value: number, index: number, arr: Uint32Array)=>{return value >= this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint32Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint32Array) { + console.info(value + this.base) + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint32Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return arr.forEach((value: number, index: number, arr: Uint32Array)=>{console.info(value + this.base)}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint32Array) => number, thisArg?: any): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint32Array) { + return value + this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint32Array) => number): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return arr.map((value: number, index: number, arr: Uint32Array)=>{return value + this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名:** + `some(predicate: (value: number, index: number, array: Uint32Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint32Array) { + return value > this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `some(predicate: (value: number, index: number, array: Uint32Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint32Array | 是 | 调用的原始Uint32Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return arr.some((value: number, index: number, arr: Uint32Array)=>{return value > this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint32Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint32Array.from(arr, a.foo, a); + let arr3 = Uint32Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint32Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint32Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更2 +**ArkTS1.1版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint32Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint32Array.from(arr, a.foo, a); + let arr3 = Uint32Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Uint32Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint32Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint32Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Uint32Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint32Array = new Uint32Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint8Array.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint8Array.md new file mode 100644 index 0000000000000000000000000000000000000000..4567ba43d76510f738b74aa62647a176638b6109 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint8Array.md @@ -0,0 +1,845 @@ +# Uint8Array + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 + +### Symbol.iterator变更 +**ArkTS1.1版本签名:** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Uint8Array(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名:** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 返回数组的迭代器对象。 | + +**示例：** + ```typescript + let a = new Uint8Array(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名:** + `every(predicate: (value: number, index: number, array: Uint8Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8Array) { + return value < this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `every(predicate: (value: number, index: number, array: Uint8Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Uint8Array) { + return arr.every((value: number, index: number, arr: Uint8Array)=>{return value < this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名:** + `filter(predicate: (value: number, index: number, array: Uint8Array) => any, thisArg?: any): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8Array) { + return value < this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `filter(predicate: (value: number, index: number, array: Uint8Array) => boolean): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return arr.filter((value: number, index: number, arr: Uint8Array)=>{return value < this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名:** + `find(predicate: (value: number, index: number, obj: Uint8Array) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8Array) { + return value >= this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `find(predicate: (value: number, index: number, obj: Uint8Array) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number \| undefined | 返回第一个符合条件的元素，否则返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return arr.find((value: number, index: number, arr: Uint8Array)=>{return value >= this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint8Array) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8Array) { + return value >= this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint8Array) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 返回第一个符合条件的元素的索引，否则返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return arr.findIndex((value: number, index: number, arr: Uint8Array)=>{return value >= this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint8Array) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint8Array) { + console.info(value + this.base) + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint8Array) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return arr.forEach((value: number, index: number, arr: Uint8Array)=>{console.info(value + this.base)}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint8Array) => number, thisArg?: any): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint8Array) { + return value + this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint8Array) => number): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 新数组，每个元素都是回调函数的返回值。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return arr.map((value: number, index: number, arr: Uint8Array)=>{return value + this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名:** + `some(predicate: (value: number, index: number, array: Uint8Array) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint8Array) { + return value > this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `some(predicate: (value: number, index: number, array: Uint8Array) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8Array | 是 | 调用的原始Uint8Array对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否满足`predicate`，`true`表示满足，`false`表示不满足。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return arr.some((value: number, index: number, arr: Uint8Array)=>{return value > this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint8Array.from(arr, a.foo, a); + let arr3 = Uint8Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | Iterable\ | 是 | 可迭代对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更2 +**ArkTS1.1版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时使用的this值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint8Array.from(arr, a.foo, a); + let arr3 = Uint8Array.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Uint8Array` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8Array的元素。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8Array | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Uint8Array) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint8Array = new Uint8Array([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint8ClampedArray.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint8ClampedArray.md new file mode 100644 index 0000000000000000000000000000000000000000..7320c93002d01a735910941cd1501df35cf22d5a --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-Uint8ClampedArray.md @@ -0,0 +1,852 @@ +# Uint8ClampedArray + +## 变更梗概 +- [Symbol.iterator变更](#symboliterator变更) +- [every方法变更](#every方法变更) +- [filter方法变更](#filter方法变更) +- [find方法变更](#find方法变更) +- [findIndex方法变更](#findindex方法变更) +- [forEach方法变更](#foreach方法变更) +- [map方法变更](#map方法变更) +- [some方法变更](#some方法变更) +- [from静态方法变更1](#from静态方法变更1) +- [from静态方法变更2](#from静态方法变更2) + +## 变更详情 +### Symbol.iterator变更 +**ArkTS1.1版本签名:** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + |------|------| + | IterableIterator\ | 返回一个迭代器。 | + +**示例：** + ```typescript + let a = new Uint8ClampedArray(3); + let iter = Reflect.get(a, Symbol.iterator); + ``` + +**ArkTS1.2版本签名:** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + |------|------| + | IterableIterator\ | 返回一个迭代器。 | + +**示例：** + ```typescript + let a = new Uint8ClampedArray(3); + let iter = a.$_iterator; + ``` + +**适配建议：** 建议仅使用for...of访问迭代器，不要显式访问迭代器。 + +### every方法变更 +**ArkTS1.1版本签名:** + `every(predicate: (value: number, index: number, array: Uint8ClampedArray) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行predicate时作为其this的值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是否通过检查。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8ClampedArray) { + return value < this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(4); + arr.every(a.compare, a); + arr.every(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `every(predicate: (value: number, index: number, array: Uint8ClampedArray) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前元素是否通过检查，true表示当前元素通过检查，false表示未通过。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否所有元素都通过测试。true表示全部都通过，false表示全部都不通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + callEvery(arr: Uint8ClampedArray) { + return arr.every((value: number, index: number, arr: Uint8ClampedArray)=>{ + return value < this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(4); + a.callEvery(arr); // false + b.callEvery(arr); // true + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### filter方法变更 +**ArkTS1.1版本签名:** + `filter(predicate: (value: number, index: number, array: Uint8ClampedArray) => any, thisArg?: any): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行predicate时作为其this的值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | any | 返回值会被隐式转换为boolean，决定当前元素是否会被过滤。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Uint8ClampedArray | 返回通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8ClampedArray) { + return value < this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.filter(a.compare, a); + arr.filter(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `filter(predicate: (value: number, index: number, array: Uint8ClampedArray) => boolean): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否过滤当前元素，true表示保留当前元素，false表示过滤掉当前元素。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Uint8ClampedArray | 返回通过测试的元素组成的新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return arr.filter((value: number, index: number, arr: Uint8ClampedArray)=>{ + return value < this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // [1] + b.call(arr); // [1, 2] + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### find方法变更 +**ArkTS1.1版本签名:** + `find(predicate: (value: number, index: number, obj: Uint8ClampedArray) => boolean, thisArg?: any): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行predicate时作为其this的值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | number \| undefined | 返回第一个符合条件的元素，未找到返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8ClampedArray) { + return value >= this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.find(a.compare, a); + arr.find(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `find(predicate: (value: number, index: number, obj: Uint8ClampedArray) => boolean): number | undefined` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | number \| undefined | 返回第一个符合条件的元素，未找到返回undefined。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return arr.find((value: number, index: number, arr: Uint8ClampedArray)=>{ + return value >= this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 2 + b.call(arr); // 3 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### findIndex方法变更 +**ArkTS1.1版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint8ClampedArray) => boolean, thisArg?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行predicate时作为其this的值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | number | 返回第一个符合条件的元素的索引，未找到返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + compare(value: number, index: number, arr: Uint8ClampedArray) { + return value >= this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.findIndex(a.compare, a); + arr.findIndex(a.compare, b); + ``` + +**ArkTS1.2版本签名:** + `findIndex(predicate: (value: number, index: number, obj: Uint8ClampedArray) => boolean): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | obj | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示当前是否找到匹配项，true表示找到，false表示没找到。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | number | 返回第一个符合条件的元素的索引，未找到返回-1表示未找到满足的元素。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return arr.findIndex((value: number, index: number, arr: Uint8ClampedArray)=>{ + return value >= this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); // 1 + b.call(arr); // 2 + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### forEach方法变更 +**ArkTS1.1版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint8ClampedArray) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | callbackfn | function | 是 | 回调函数。 | + | thisArg | any | 否 | 执行callbackfn时作为其this的值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint8ClampedArray) { + console.info(value + this.base) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.forEach(a.foo, a); + arr.forEach(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `forEach(callbackfn: (value: number, index: number, array: Uint8ClampedArray) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | callbackfn | function | 是 | 回调函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return arr.forEach((value: number, index: number, arr: Uint8ClampedArray)=>{ + console.info(value + this.base) + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### map方法变更 +**ArkTS1.1版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint8ClampedArray) => number, thisArg?: any): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | callbackfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callbackfn时作为其this的值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Uint8ClampedArray | 返回新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint8ClampedArray) { + return value + this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.map(a.foo, a); + arr.map(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `map(callbackfn: (value: number, index: number, array: Uint8ClampedArray) => number): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | callbackfn | function | 是 | 映射函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +callbackfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 当前函数计算后新得到的number值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Uint8ClampedArray | 返回新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return arr.map((value: number, index: number, arr: Uint8ClampedArray)=>{ + return value + this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### some方法变更 +**ArkTS1.1版本签名:** + `some(predicate: (value: number, index: number, array: Uint8ClampedArray) => unknown, thisArg?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + | thisArg | any | 否 | 执行predicate时作为其this的值，默认值为undefined。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | unknown | 返回值会被隐式转换为boolean，决定当前元素是都满足predicate函数。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number, arr: Uint8ClampedArray) { + return value > this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + arr.some(a.foo, a); + arr.some(a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `some(predicate: (value: number, index: number, array: Uint8ClampedArray) => boolean): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | predicate | function | 是 | 测试函数。 | + +predicate函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | number | 是 | 当前被遍历的number值。 | + | index | number | 是 | 当前元素的索引。 | + | array | Uint8ClampedArray | 是 | 调用的原始Uint8ClampedArray对象。 | + +predicate函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否至少有一个元素通过测试。true表示至少有一个元素通过测试，false表示没有任何元素通过。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return arr.some((value: number, index: number, arr: Uint8ClampedArray)=>{ + return value > this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更1 +**ArkTS1.1版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number, thisArg?: any): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | arrayLike | Iterable\ | 是 | 可迭代对象或类数组对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + | thisArg | any | 否 | 执行mapfn时作为其this的值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8ClampedArray的元素 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Uint8ClampedArray | 返回新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint8ClampedArray.from(arr, a.foo, a); + let arr3 = Uint8ClampedArray.from(arr, a.foo, b); + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: Iterable, mapfn?: (v: number, k: number) => number): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | arrayLike | Iterable\ | 是 | 可迭代对象或类数组对象。 | + | mapfn | function | 否 | 映射函数，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | number | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8ClampedArray的元素 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Uint8ClampedArray | 返回新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr: Uint8ClampedArray) { + return Array.from(arr, (value: number, index: number)=>{ + return value + this.base + }) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + a.call(arr); + b.call(arr); + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 + +### from静态方法变更2 +**ArkTS1.1版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number, thisArg?: any): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + | thisArg | any | 否 | 执行callback时用作this的值，默认值为undefined。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8ClampedArray的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8ClampedArray | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + foo(value: number, index: number) { + return value + this.base + } + } + + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2); + let b = new C(3); + let arr2 = Uint8ClampedArray.from(arr, a.foo, a) + let arr3 = Uint8ClampedArray.from(arr, a.foo, b) + ``` + +**ArkTS1.2版本签名:** + `static from(arrayLike: ArrayLike, mapfn: (v: T, k: number) => number): Uint8ClampedArray` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | arrayLike | ArrayLike\ | 是 | 类数组对象。 | + | mapfn | function | 是 | 映射函数。 | + +mapfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | v | T | 是 | 当前被遍历的数组元素的值。 | + | k | number | 是 | 当前元素的索引。 | + +mapfn函数返回值说明： + | 类型 | 说明 | + | -------- | -------- | + | number | 返回的一个number类型值，作为新Uint8ClampedArray的元素 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Uint8ClampedArray | 新数组。 | + +**示例：** + ```typescript + class C { + base: number; + constructor(base:number) { + this.base = base; + } + call(arr:Uint8ClampedArray) { + return Array.from(arr, (value: number, index: number)=>{return value + this.base}) + } + } + let arr: Uint8ClampedArray = new Uint8ClampedArray([1, 2, 3]); + let a = new C(2) + let b = new C(3) + a.call(arr) + b.call(arr) + ``` + +**适配建议：** 删除最后一个参数，不使用显式指定this的语义。若必须使用，可使用闭包。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib1.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib1.md new file mode 100644 index 0000000000000000000000000000000000000000..a0dd4aa7f0d6aaa5ababa992b2e0d46717a5fbb9 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib1.md @@ -0,0 +1,726 @@ +# StdLib1 + +## 变更梗概 +- [Map](#map) +- [Set](#set) +- [String](#string) +- [Symbol](#symbol) +- [Object](#object) +- [Number](#number) + +## Map +### 变更梗概 +- [Map-Symbol.iterator变更](#map-symboliterator变更) +- [Map-forEach方法签名变更](#map-foreach方法签名变更) + +### 变更详情 + +#### Map-Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator<[K, V]>` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\<[K, V]\> | Map的迭代器。 | + +**示例：** + ```typescript + let m: Map = new Map(); + let iter = Reflect.get(m, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator<[K, V]>` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\<[K, V]\> | Map的迭代器。 | + +**示例：** + ```typescript + const m: Map = new Map(); + let iter = m.$_iterator(); + ``` + +**适配建议：** + 建议仅使用for...of访问迭代器。 + + +#### Map-forEach方法签名变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: V, key: K, map: Map) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行callback时使用的this值，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | V | 是 | 当前遍历的键值对中的值。 | + | key | K | 是 | 当前遍历的键值对中的键。 | + | map | Map\ | 是 | 调用的原始数组。 | + + +**示例：** + ```typescript + const m: Map = new Map(); + class Ctx { + log(key: string, value: string) { + console.info(key, value); + } + } + m.forEach((value: string, key: string, map: Map) => { + this.log(key, value); // this无法在独立函数中使用 + }, new Ctx()); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: V, key: K, map: Map) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | V | 是 | 当前遍历的键值对中的值。 | + | key | K | 是 | 当前遍历的键值对中的键。 | + | map | Map\ | 是 | 调用的原始Map。 | + + +**示例：** + ```typescript + const m: Map = new Map(); + m.forEach((value: string, key: string, map: Map) => { + console.info("value=", value, "key=", key); + }); + ``` + +**适配建议：** + 使用闭包替代thisArg参数。 + +## Set + +### 变更梗概 +- [Set-Symbol.iterator变更](#set-symboliterator变更) +- [Set-forEach方法签名变更](#set-foreach方法签名变更) + +### 变更详情 + +#### Set-Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | Set的迭代器。 | + +**示例：** + ```typescript + let set = new Set(); + Reflect.get(set, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | Set的迭代器。 | + +**示例：** + ```typescript + let set = new Set(); + set.$_iterator(); + ``` + +**适配建议：** + 使用for...of进行迭代。 + +#### Set-forEach方法签名变更 +**ArkTS1.1版本签名：** + `forEach(callbackfn: (value: T, value2: T, set: Set) => void, thisArg?: any): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + | thisArg | any | 否 | 执行上下文，默认值为undefined。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前遍历的键值对中的值。 | + | value2 | T | 是 | 与value相同。 | + | set | Set\ | 是 | 调用的原始Set。 | + +**示例：** + ```typescript + class Counter { + count(v: string) { this.total++; } + total = 0; + } + let set = new Set(["a"]); + set.forEach(new Counter().count, {total: 10}); + ``` + +**ArkTS1.2版本签名：** + `forEach(callbackfn: (value: T, value2: T, set: Set) => void): void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callbackfn | function | 是 | 遍历函数。 | + +callbackfn函数参数说明： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 当前遍历的键值对中的值。 | + | value2 | T | 是 | 与value相同。 | + | set | Set\ | 是 | 调用的原始Set。 | + +**示例：** + ```typescript + let set = new Set(["a"]); + let total = 0; + set.forEach(() => {total++}); + ``` + +**适配建议：** + 通过外部变量维护状态。 + +## String + +### 变更梗概 +- [String-Symbol.iterator变更](#string-symboliterator变更) +- [raw方法变更](#raw方法变更) +- [string-构造函数变更为invoke方法](#string-构造函数变更为invoke方法) + +### 变更详情 + +#### String-Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 字符串迭代器。 | + +**示例：** + ```typescript + let str = "hello"; + Reflect.get(str, Symbol.iterator); + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | 字符串迭代器。 | + +**示例：** + ```typescript + let str = "hello"; + str.$_iterator(); + ``` + +**适配建议：** + 使用for...of遍历字符串。 + +#### raw方法变更 +**ArkTS1.1版本签名：** + `static raw(template: { raw: readonly string[] | ArrayLike}, ...substitutions: any[]): string` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | template | { raw: readonly string[] \| ArrayLike\ } | 是 | 模板对象。 | + | substitutions | any[] | 否 | 替换值，默认值为null。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | string | 原始字符串。 | + +**示例：** + ```typescript + let a = String.raw`a\nb\nc`; + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 使用普通字符串替代。 + +#### string-构造函数变更为invoke方法 +**ArkTS1.1版本签名：** + `(value?: any): string` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | any | 否 | 任意类型值，默认值为空。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | string | 字符串表示。 | + +**示例：** + ```typescript + function create(ctor: StringConstructor) { + return ctor({}); + } + ``` + +**ArkTS1.2版本签名：** + `static String.invoke(value?: Object | undefined | null): String` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | Object \| undefined \| null | 否 | 限定类型值，默认值为空。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | String | 字符串对象。 | + +**示例：** + ```typescript + String({}); // 需确保参数符合类型 + ``` + +**适配建议：** + 不要使用Constructor类型，使用invoke或new的方式直接创建对象。 + +## Symbol + +### 变更梗概 +- [iterator符号属性移除](#iterator符号属性移除) + +### 变更详情 + +#### iterator符号属性移除 +**ArkTS1.1版本签名：** + `static readonly iterator: unique symbol` + +**示例：** + ```typescript + let a = Symbol.iterator; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 使用字符串属性$_iterator访问迭代器。 + +## Object + +### 变更梗概 +- [getOwnPropertyNames方法变更](#getownpropertynames方法变更) +- [Object-构造函数变更](#object-构造函数变更) +- [Object-valueOf变更](#object-valueof变更) +- [ObjectConstructor无参调用变更](#objectconstructor无参调用变更) +- [ObjectConstructor带参调用变更](#objectconstructor带参调用变更) + +### 变更详情 + +#### getOwnPropertyNames方法变更 +- ArkTS1.1 版本签名： + `static getOwnPropertyNames(o: any): string[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `o` | `any` | 是 | 要获取属性名的对象。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `string[]` | 对象的属性名数组。 | + +**示例：** + ```typescript + class C { + a: number = 1; + b: number = 2; + } + const a = new C(); + Object.getOwnPropertyNames(a); + ``` + +- ArkTS1.2 版本签名: + 不支持。 + +**适配建议：** + 使用`Object.keys`代替。 + +#### Object-构造函数变更 +**ArkTS1.1版本签名：** + `constructor(value?: any): Object` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | any | 否 | 任意类型的值，默认值为空。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Object | 对象实例。 | + +**示例：** + ```typescript + let obj = new Object({}); + ``` + +**ArkTS1.2版本签名：** + `constructor(): Object` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Object | 空对象实例。 | + +**示例：** + ```typescript + let obj = new Object(); + ``` + +**适配建议：** + 使用具体类型替代泛型Object。 + +#### Object-valueOf变更 +**ArkTS1.1版本签名：** + `valueOf(): Object` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Object | 对象本身。 | + +**示例：** + ```typescript + let obj = new Object(); + obj.valueOf(); + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 直接使用对象本身，不需要调用valueOf。 + + +#### ObjectConstructor无参调用变更 +**ArkTS1.1版本签名：** + `(): any` + +**返回值：** + | 类型 | 说明 | + |------|------| + | any | 返回空对象。 | + +**示例：** + ```typescript + let a: Object = Object(); + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 使用具体类型替代泛型Object。 + + +#### ObjectConstructor带参调用变更 +**ArkTS1.1版本签名：** + `(value: any): any` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | value | any | 否 | 任意类型值，默认值为空。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | any | 返回包装后的对象。 | + +**示例：** + ```typescript + let a: Object = Object({}); + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 使用具体类型替代泛型Object。 + +## Number + +### 变更梗概 +- [Number-构造函数变更](#number-构造函数变更) +- [Number-isFinite方法变更](#number-isfinite方法变更) +- [Number-isInteger方法变更](#number-isinteger方法变更) +- [Number-isNaN方法变更](#number-isnan方法变更) +- [Number-isSafeInteger方法变更](#number-issafeinteger方法变更) +- [Number-调用签名变更为invoke方法](#number-调用签名变更为invoke方法) + +### 变更详情 + +#### Number-构造函数变更 +**ArkTS1.1版本签名：** + `constructor(value?: any): Number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | value | any | 否 | 任意类型值，默认值为0。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Number | 数字包装对象。 | + +**示例：** + ```typescript + let num = new Number(true); + ``` + +**ArkTS1.2版本签名：** + `constructor(value?: String|Number|BigInt): Number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | value | String \| Number \| BigInt | 否 | 可转换为数字的值，默认值为0。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | Number | 数字包装对象。 | + +**示例：** + ```typescript + let num = new Number(10); + ``` + +**适配建议：** + 仅使用String、Number或BigInt类型创建Number对象。 + +#### Number-isFinite方法变更 +**ArkTS1.1版本签名：** + `static isFinite(number: unknown): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | number | unknown | 是 | 待检测的值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为有限数，true表示是有限数，false表示不是有限数。 | + +**示例：** + ```typescript + Number.isFinite(true); + ``` + +**ArkTS1.2版本签名：** + `static isFinite(n: number): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | n | number | 是 | 待检测的数字 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为有限数，true表示是有限数，false表示不是有限数。 | + +**示例：** + ```typescript + Number.isFinite(1); + ``` + +**适配建议：** + 只对数字类型使用isFinite检查。 + +#### Number-isInteger方法变更 +**ArkTS1.1版本签名：** + `static isInteger(number: unknown): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | number | unknown | 是 | 待检测的值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为整数，true表示是整数，false表示不是整数。 | + +**示例：** + ```typescript + Number.isInteger(true); + ``` + +**ArkTS1.2版本签名：** + `static isInteger(n: number): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | n | number | 是 | 待检测的数字。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为整数，true表示是整数，false表示不是整数。 | + +**示例：** + ```typescript + Number.isInteger(1); + ``` + +**适配建议：** + 只对数字类型使用isInteger检查。 + +#### Number-isNaN方法变更 +**ArkTS1.1版本签名：** + `static isNaN(number: unknown): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | number | unknown | 是 | 待检测的值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为NaN，true表示是，false表示不是NaN。 | + +**示例：** + ```typescript + Number.isNaN(true); + ``` + +**ArkTS1.2版本签名：** + `static isNaN(number: number): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | number | number | 是 | 待检测的数字。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为NaN，true表示是，false表示不是NaN。 | + +**示例：** + ```typescript + Number.isNaN(1); + ``` + +**适配建议：** + 只对数字类型使用isNaN检查。 + +#### Number-isSafeInteger方法变更 +**ArkTS1.1版本签名：** + `static isSafeInteger(number: unknown): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | number | unknown | 是 | 待检测的值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为安全整数，true表示是，false表示不是安全整数。 | + +**示例：** + ```typescript + Number.isSafeInteger(true); + ``` + +**ArkTS1.2版本签名：** + `static isSafeInteger(n: number): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | n | number | 是 | 待检测的数字。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否为安全整数，true表示是安全整数，false表示不是安全整数。 | + +**示例：** + ```typescript + Number.isSafeInteger(1); + ``` + +**适配建议：** + 只对数字类型使用isSafeInteger检查。 + +#### Number-调用签名变更为invoke方法 +**ArkTS1.1版本签名：** + `(value?: any): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | any | 否 | 任意类型值，默认值为0。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 转换后的数字。 | + +**示例：** + ```typescript + console.info(Number(undefined)); + ``` + +**ArkTS1.2版本签名：** + `static Number.invoke(value?: String|Number|BigInt): number` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | String \| Number \| BigInt | 否 | 限定类型的值，默认值为0。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 转换后的数字。 | + +**示例：** + ```typescript + console.info(Number(0)); //0 + ``` + +**适配建议：** + 仅使用String/Number/BigInt类型作为参数。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib2.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib2.md new file mode 100644 index 0000000000000000000000000000000000000000..2673a4875a54b0d8458f7dc340371b39d8985bd8 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib2.md @@ -0,0 +1,716 @@ +# StdLib2 + +## 变更梗概 +- [__GLOBAL](#__global) +- [AggregateError](#aggregateerror) +- [ArrayBufferTypes](#arraybuffertypes) +- [IArguments](#iarguments) +- [Intl](#intl) +- [Iterable](#iterable) +- [Iterator](#iterator) +- [IterableIterator](#iterableiterator) + +## __GLOBAL + +### 变更梗概 +- [ClassDecorator类型变更](#classdecorator类型变更) +- [MethodDecorator类型变更](#methoddecorator类型变更) +- [ParameterDecorator类型变更](#parameterdecorator类型变更) +- [PropertyDecorator类型变更](#propertydecorator类型变更) +- [PropertyKey类型变更](#propertykey类型变更) +- [FlatArray类型变更](#flatarray类型变更) + +### 变更详情 + +#### ClassDecorator类型变更 +**ArkTS1.1版本签名：** + `declare type ClassDecorator = (target: TFunction) => TFunction | void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | target | TFunction | 是 | 被装饰的类构造函数。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | TFunction \| void | 返回修改后的构造函数或void。 | + +**示例：** + ```typescript + let classDecorator: ClassDecorator = (target) => { return target }; + @classDecorator + class A{} + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 使用注解 (Annotation) 替代装饰器功能。 + +#### MethodDecorator类型变更 +**ArkTS1.1版本签名：** + `declare type MethodDecorator = (target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor) => TypedPropertyDescriptor | void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | target | Object | 是 | 目标对象。 | + | propertyKey | string \| symbol | 是 | 方法名。 | + | descriptor | TypedPropertyDescriptor\ | 是 | 属性描述符。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | TypedPropertyDescriptor\ \| void | 返回修改后的描述符或void。 | + +**示例：** + ```typescript + let methodDecorator: MethodDecorator = (target, propertyKey, descriptor) => { + console.info(JSON.stringify(descriptor)); + } + class A{ + @methodDecorator + method(){} + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 使用注解(Annotation)替代装饰器功能。 + +#### ParameterDecorator类型变更 +**ArkTS1.1版本签名：** + `declare type ParameterDecorator = (target: Object, propertyKey: string | symbol, parameterIndex: number) => void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | target | Object | 是 | 目标对象。 | + | propertyKey | string \| symbol | 是 | 方法名。 | + | parameterIndex | number | 是 | 参数索引。 | + +**示例：** + ```typescript + let paramDecorator: ParameterDecorator = (target, methodName, paramIdx) => { + console.info(methodName as string); + } + class A{ + method(@paramDecorator param: string){} + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 使用注解(Annotation)替代装饰器功能。 + +#### PropertyDecorator类型变更 +**ArkTS1.1版本签名：** + `declare type PropertyDecorator = (target: Object, propertyKey: string | symbol) => void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | target | Object | 是 | 目标对象。 | + | propertyKey | string \| symbol | 是 | 属性名。 | + +**示例：** + ```typescript + let propertyDecorator: PropertyDecorator = (target, propKey) => { + console.info(propKey as string); + } + class A{ + @propertyDecorator + prop = 1 + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 使用注解(Annotation)替代装饰器功能。 + +#### PropertyKey类型变更 +**ArkTS1.1版本签名：** + `declare type PropertyKey = string | number | symbol` + +**示例：** + ```typescript + let a: PropertyKey = 1; + ``` + +**ArkTS1.2版本签名：** + `type PropertyKey = string` + +**示例：** + ```typescript + let a: PropertyKey = "a"; + ``` + +**适配建议：** + 仅使用字符串作为对象属性键。 + +#### FlatArray类型变更 +**ArkTS1.1版本签名：** + `type FlatArray = {"done": Arr,"recur": Arr extends ReadonlyArray ? FlatArray: Arr}[Depth extends -1 ? "done" : "recur"]` + +**示例：** + ```typescript + const arr1 = [0, 1, 2, [3, 4]]; + let arr: FlatArray = arr1.flat(); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 手动实现数组扁平化功能。 + +## AggregateError + +### 变更梗概 +- [AggregateError-构造函数参数类型变更](#aggregateerror-构造函数参数类型变更) +- [AggregateError-errors属性类型变更](#aggregateerror-errors属性类型变更) +- [AggregateError-Constructor变更](#aggregateerror-constructor变更) + +### 变更详情 + +#### AggregateError-构造函数参数类型变更 +**ArkTS1.1版本签名：** + `constructor(errors: Iterable, message?: string, options?: ErrorOptions): AggregateError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | errors | Iterable\ | 是 | 可迭代的错误集合。 | + | message | string | 否 | 错误消息，默认值为"AggregateError"。 | + | options | ErrorOptions | 否 | 错误选项，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | AggregateError | 新创建的AggregateError对象。 | + +**示例：** + ```typescript + let err: AggregateError = new AggregateError([1, 2]) + ``` + +**ArkTS1.2版本签名：** + `constructor(errors: Iterable, message?: string, options?: ErrorOptions): AggregateError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | errors | Iterable\ | 是 | 可迭代的错误集合(仅限Error类型)。 | + | message | string | 否 | 错误消息，默认值为"AggregateError"。 | + | options | ErrorOptions | 否 | 错误选项，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | AggregateError | 新创建的AggregateError对象。 | + +**示例：** + ```typescript + let err: AggregateError = new AggregateError([Error("first error"), Error("second error")]) + ``` + +**适配建议：** + 仅允许使用Error类型作为迭代器返回值的可迭代对象作为AggregateError构造器第一个参数，不建议使用其他类型对象作为参数传入。 + +#### AggregateError-errors属性类型变更 +**ArkTS1.1版本签名：** + `errors: any[]` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | any[] | 包含任意类型错误的数组。 | + +**示例：** + ```typescript + let err: AggregateError = new AggregateError([1， 2]) + let errors: Object[] = err.errors + ``` + +**ArkTS1.2版本签名：** + `errors: Error[]` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Error[] | 仅包含Error类型错误的数组。 | + +**示例：** + ```typescript + let err: AggregateError = new AggregateError([Error('first error'), Error('second error')]) + let errors = err.errors + ``` + +**适配建议：** + 仅允许使用Error类型作为迭代器返回值的可迭代对象作为AggregateError构造器第一个参数，不建议使用其他类型对象作为参数传入。 + +#### AggregateError-Constructor变更 +**ArkTS1.1版本签名：** + `(errors: Iterable, message?: string, options?: ErrorOptions): AggregateError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `errors` | `Iterable` | 是 | 可迭代的任意类型对象。 | + | `message` | `string` | 否 | 错误消息，默认值为"AggregateError"。 | + | `options` | `ErrorOptions` | 否 | 错误选项，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `AggregateError` | 聚合错误对象。 | + +**示例：** + ```typescript + function createAggregateError(ctor: AggregateErrorConstructor) { + return ctor([Error("first error"), Error("second error")]); + } + function createAggregateErrorDirect() { + return AggregateError([Error("first error"), Error("second error")]); + } + ``` + +**ArkTS1.2版本签名：** + `static AggregateError.invoke (errors: Iterable, message?: string, options?: ErrorOptions): AggregateError` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | `errors` | `Iterable` | 是 | 可迭代的错误对象。 | + | `message` | `string` | 否 | 错误消息，默认值为AggregateError。 | + | `options` | `ErrorOptions` | 否 | 错误选项，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `AggregateError` | 聚合错误对象。 | + +**示例：** + ```typescript + function createAggregateError() { + return AggregateError([Error("first error"), Error("second error")]); + } + ``` + +**适配建议：** + 直接创建对应类型的对象，不直接使用constructor类。 + +## ArrayBufferTypes + +### 变更梗概 +- [ArrayBufferTypes类型移除](#arraybuffertypes类型移除) +- [SharedArrayBuffer类型移除](#sharedarraybuffer类型移除) + +### 变更详情 + +#### ArrayBufferTypes类型移除 +**ArkTS1.1版本签名：** + `ArrayBuffer: ArrayBuffer` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | ArrayBuffer | ArrayBuffer对象。 | + +**示例：** + ```typescript + let c:ArrayBufferTypes = { + ArrayBuffer: new ArrayBuffer(10), + SharedArrayBuffer: new SharedArrayBuffer(10) + }; + c.ArrayBuffer; + c.SharedArrayBuffer; + ``` + +**ArkTS1.2版本签名：** + 不支持 + +**适配建议：** + 不使用ArrayBufferTypes，如果需要使用类似结构可以自定义类型。 + +#### SharedArrayBuffer类型移除 +**ArkTS1.1版本签名：** + `SharedArrayBuffer: SharedArrayBuffer` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | SharedArrayBuffer | SharedArrayBuffer对象。 | + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 不使用ArrayBufferTypes，如果需要使用类似结构可以自定义类型。 + +## IArguments + +### 变更梗概 +- [IArguments类型移除](#iarguments类型移除) +- [IArguments-callee属性移除](#iarguments-callee属性移除) +- [IArguments-length属性移除](#iarguments-length属性移除) + +### 变更详情 + +#### IArguments类型移除 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IterableIterator\ | arguments的迭代器。 | + +**示例：** + ```typescript + function f(a:number,b:string){ + Reflect.get(arguments, Symbol.iterator); + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + ArkTS1.2不能使用arguments，因此不需要使用IArguments。 + +#### IArguments-callee属性移除 +**ArkTS1.1版本签名：** + `callee: Function` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Function | 当前执行的函数。 | + +**示例：** + ```typescript + function f(a:number,b:string){ + arguments.callee; + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + ArkTS1.2不能使用arguments，因此不需要使用callee。 + +#### IArguments-length属性移除 +**ArkTS1.1版本签名：** + `length: number` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | number | 参数个数。 | + +**示例：** + ```typescript + function f(a:number,b:string){ + console.info(arguments.length); + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + ArkTS1.2不能使用arguments，因此不需要使用length属性。 + +## Intl + +### 变更梗概 +- [DateTimeFormat变更](#datetimeformat变更) +- [DateTimeFormatPartTypesRegistry变更](#datetimeformatparttypesregistry变更) +- [DisplayNames变更](#displaynames变更) +- [ListFormat访问变更](#listformat访问变更) +- [NumberFormat变更](#numberformat变更) + +### 变更详情 + +#### DateTimeFormat变更 +- ArkTS1.1 版本签名： + `readonly prototype: DateTimeFormat` + +**示例：** + ```typescript + Reflect.get(Intl.DateTimeFormat, "prototype") + ``` +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持去修改prototype，建议创建新的对象。 + +#### DateTimeFormatPartTypesRegistry变更 +**ArkTS1.1版本签名：** + `interface DateTimeFormatPartTypesRegistry { + day: any + dayPeriod: any + era: any + hour: any + literal: any + minute: any + month: any + second: any + timeZoneName: any + weekday: any + year: any + }` + +**示例：** + ```typescript + let o: Intl.DateTimeFormatPartTypesRegistry = { + day: undefined, + dayPeriod: undefined, + era: undefined, + hour: undefined, + literal: undefined, + minute: undefined, + month: undefined, + second: undefined, + timeZoneName: undefined, + weekday: undefined, + year: undefined, + unknown: undefined, + fractionalSecond: undefined + } + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 不使用Intl.DateTimeFormatPartTypesRegistry。 + +#### DisplayNames变更 +**ArkTS1.1版本签名：** + `prototype: DisplayNames` + +**示例：** + ```typescript + Reflect.get(Intl.DisplayNames, "prototype") + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持去修改prototype，建议创建新的对象。 + +#### ListFormat访问变更 +**ArkTS1.1版本签名：** + `prototype: ListFormat` + +**示例：** + ```typescript + Reflect.get(Intl.ListFormat, "prototype") + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持去修改prototype，建议创建新的对象。 + +#### NumberFormat变更 +**ArkTS1.1版本签名：** + `readonly prototype: NumberFormat` + +**示例：** + ```typescript + Reflect.get(Intl.NumberFormat, "prototype") + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持去修改prototype，建议创建新的对象。 + +## Iterable + +### 变更梗概 +- [Iterable-Symbol.iterator变更](#iterable-symboliterator变更) + +### 变更详情 + +#### Iterable-Symbol.iterator变更 +**ArkTS1.1版本签名：** + `[Symbol.iterator](): Iterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Iterator\ | 迭代器对象。 | + +**示例：** + ```typescript + function f(a: Iterable) { + Reflect.get(a, Symbol.iterator); + } + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): Iterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Iterator\ | 迭代器对象。 | + +**示例：** + ```typescript + class C implements Iterable { + $_iterator(): Iterator { + //.... + } + } + ``` + +**适配建议：** + 建议仅使用for...of访问迭代器，不要显示访问迭代器。 + +## Iterator + +### 变更梗概 +- [Iterator-return方法变更](#iterator-return方法变更) +- [Iterator-throw方法变更](#iterator-throw方法变更) + +### 变更详情 + +#### Iterator-return方法变更 +**ArkTS1.1版本签名：** + `return?(value?: TReturn): IteratorResult` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | TReturn | 否 | 可选的返回值，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IteratorResult\ | 迭代结果对象。 | + +**示例：** + ```typescript + class C implements Iterator { + a: number = 0; + b: number; + constructor (b: number) { + this.b = b; + } + next(): IteratorResult { + if (this.a >= this.b) { + return {value: undefined, done: true}; + } + this.a++; + return {value: this.a, done: false}; + } + return(): IteratorResult { + console.info("call return"); + this.a = 0; + return {value: undefined, done: true}; + } + } + let a = new C(5); + a.next(); + a.return(); + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 不使用return方法。 + +#### Iterator-throw方法变更 +**ArkTS1.1版本签名：** + `throw?(e?: any): IteratorResult` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | e | any | 否 | 可选的错误对象，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | IteratorResult\ | 迭代结果对象。 | + +**示例：** + ```typescript + class C implements Iterator { + throw(e: Error): IteratorResult { + console.error("Error: " + e); + return { value: undefined, done: true }; + } + } + let a = new C(); + a.throw(new Error("test")); + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 不使用throw方法。 + +## IterableIterator + +### 变更梗概 +- [IterableIterator-Symbol.iterator变更](#iterableiterator-symboliterator变更) + +### 变更详情 + +#### IterableIterator-Symbol.iterator变更 +- ArkTS1.1 版本签名： + `[Symbol.iterator](): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | 表示返回一个可迭代的迭代器对象。 | + +**示例：** + ```typescript + function f(a: IterableIterator) { + Reflect.get(a, Symbol.iterator); + } + ``` + +**ArkTS1.2版本签名：** + `$_iterator(): IterableIterator` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | `IterableIterator` | 表示返回一个可迭代的迭代器对象。 | + +**示例：** + ```typescript + class C implements IterableIterator { + $_iterator(): IterableIterator { + //.... + } + // ... + } + ``` + +**适配建议：** + 建议仅使用`for...of`访问迭代器，不要显示访问迭代器。 diff --git a/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib3.md b/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib3.md new file mode 100644 index 0000000000000000000000000000000000000000..ed9e964dd8928f289e960157139ec1d12939b3af --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-builtin-api-stdlib3.md @@ -0,0 +1,581 @@ +# StdLib3 + +## 变更梗概 +- [PropertyDescriptor](#propertydescriptor) +- [Reflect](#reflect) +- [RegExpExecArray](#regexpexecarray) +- [RegExpMatchArray](#regexpmatcharray) +- [TypedPropertyDescriptor](#typedpropertydescriptor) +- [TemplateStringsArray](#templatestringsarray) + +## PropertyDescriptor + +### 变更梗概 +- [configurable属性移除](#configurable属性移除) +- [enumerable属性移除](#enumerable属性移除) +- [value属性移除](#value属性移除) +- [writable属性移除](#writable属性移除) +- [get方法移除](#get方法移除) +- [set方法移除](#set方法移除) + +### 变更详情 + +#### configurable属性移除 +**ArkTS1.1版本签名：** + `configurable?: boolean` + +**示例：** + ```typescript + Object.defineProperty(obj, "prop", { configurable: true }); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 建议通过调整或创建新的类来达成效果。 + +#### enumerable属性移除 +**ArkTS1.1版本签名：** + `enumerable?: boolean` + +**示例：** + ```typescript + Object.defineProperty(obj, "prop", { enumerable: false }); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 建议通过调整或创建新的类来达成效果。 + +#### value属性移除 +**ArkTS1.1版本签名：** + `value?: any` + +**示例：** + ```typescript + Object.defineProperty(obj, "prop", { value: 1 }); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 建议通过调整或创建新的类来达成效果。 + +#### writable属性移除 +**ArkTS1.1版本签名：** + `writable?: boolean` + +**示例：** + ```typescript + Object.defineProperty(obj, "prop", { writable: false }); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 建议通过调整或创建新的类来达成效果。 + +#### get方法移除 +**ArkTS1.1版本签名：** + `get?(): any` + +**示例：** + ```typescript + Object.defineProperty(obj, "prop", { + get() { return this._value; } + }); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 建议通过调整或创建新的类来达成效果。 + +#### set方法移除 +**ArkTS1.1版本签名：** + `set?(v: any): void` + +**示例：** + ```typescript + Object.defineProperty(obj, "prop", { + set(v) { this._value = v; } + }); + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 建议通过调整或创建新的类来达成效果。 + +## RegExpExecArray + +### 变更梗概 +- [RegExpExecArray-groups类型变更](#regexpexecarray-groups类型变更) + +### 变更详情 + +#### RegExpExecArray-groups类型变更 +**ArkTS1.1版本签名：** + `groups?: { [key: string]: string }` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | { [key: string]: string } | 匹配结果的集合。 | + +**示例：** + ```typescript + const text = '2025-01-01'; + const regex = /(?\d{4})-(?\d{2})-(?\d{2})/; + const match = regex.exec(text); + console.info(match!.groups!.year) + ``` + +**ArkTS1.2版本签名：** + `groups?: Record` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Record\ | 命名捕获组。 | + +**示例：** + ```typescript + const text = '2025-01-01'; + const regex = new RegExp(`(?....)-(?..)-(?..)`); + const match = regex.exec(text); + console.info(match!.groups) + ``` + +**适配建议：** + 使用字符串索引访问捕获组。 + +## RegExpMatchArray + +### 变更梗概 +- [RegExpMatchArray-groups类型变更](#regexpmatcharray-groups类型变更) + +### 变更详情 + +#### RegExpMatchArray-groups类型变更 +**ArkTS1.1版本签名：** + `groups?: { [key: string]: string }` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | { [key: string]: string } | 匹配结果的集合。 | + +**示例：** + ```typescript + const text = '2025-01-01'; + const regex = /(?\d{4})-(?\d{2})-(?\d{2})/; + const match = text.match(regex); + console.info(match!.groups!.year); + ``` + +**ArkTS1.2版本签名：** + `groups?: Record` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | Record\ | 命名捕获组。 | + +**示例：** + ```typescript + const text = '2025-01-01'; + const regex = new RegExp(`(?....)-(?..)-(?..)`); + const match = text.match(regex); + console.info(match!.groups); + ``` + +**适配建议：** + 通过字符串键访问捕获组。 + +## TypedPropertyDescriptor + +### 变更梗概 +- [TypedPropertyDescriptor-configurable属性变更](#typedpropertydescriptor-configurable属性变更) +- [TypedPropertyDescriptor-enumerable属性变更](#typedpropertydescriptor-enumerable属性变更) +- [TypedPropertyDescriptor-get方法变更](#typedpropertydescriptor-get方法变更) +- [TypedPropertyDescriptor-set方法变更](#typedpropertydescriptor-set方法变更) +- [TypedPropertyDescriptor-value属性变更](#typedpropertydescriptor-value属性变更) +- [TypedPropertyDescriptor-writable属性变更](#typedpropertydescriptor-writable属性变更) + +### 变更详情 + +#### TypedPropertyDescriptor-configurable属性变更 +**ArkTS1.1版本签名：** + `configurable?: boolean` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否可配置，true表示是可配置，false表示不可配置。 | + +**示例：** + ```typescript + let desc: TypedPropertyDescriptor = { + configurable: false + }; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持修改属性，因此建议通过调整或创建新的类来达成效果。 + +#### TypedPropertyDescriptor-enumerable属性变更 +**ArkTS1.1版本签名：** + `enumerable?: boolean` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否可枚举，true表示是，false表示不可枚举。 | + +**示例：** + ```typescript + let desc: TypedPropertyDescriptor = { + enumerable: true + }; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持修改属性，因此建议通过调整或创建新的类来达成效果。 + +#### TypedPropertyDescriptor-get方法变更 +**ArkTS1.1版本签名：** + `get?: () => T` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T | 属性值。 | + +**示例：** + ```typescript + let desc: TypedPropertyDescriptor = { + get(): number { return this.value; } + }; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持修改属性，因此建议通过调整或创建新的类来达成效果。 + +#### TypedPropertyDescriptor-set方法变更 +**ArkTS1.1版本签名：** + `set?: (value: T) => void` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | value | T | 是 | 要设置的值。 | + +**示例：** + ```typescript + let desc: TypedPropertyDescriptor = { + set(v: number) { this.value = v; } + }; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持修改属性，因此建议通过调整或创建新的类来达成效果。 + +#### TypedPropertyDescriptor-value属性变更 +**ArkTS1.1版本签名：** + `value?: T` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | T | 属性值 | + +**示例：** + ```typescript + let desc: TypedPropertyDescriptor = { + value: 1 + }; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持修改属性，因此建议通过调整或创建新的类来达成效果。 + +#### TypedPropertyDescriptor-writable属性变更 +**ArkTS1.1版本签名：** + `writable?: boolean` + +**返回值：** + | 类型 | 说明 | + | -------- | -------- | + | boolean | 表示是否可写，true表示是，false表示不可写。 | + +**示例：** + ```typescript + let desc: TypedPropertyDescriptor = { + writable: true + }; + ``` + +**ArkTS1.2版本签名：** + 不支持。 + +**适配建议：** + 静态语言不支持修改属性，因此建议通过调整或创建新的类来达成效果。 + +## Reflect + +### 变更梗概 +- [Reflect-get方法变更](#reflect-get方法变更) +- [Reflect-has方法变更](#reflect-has方法变更) +- [Reflect-ownKeys方法变更](#reflect-ownkeys方法变更) +- [Reflect-set方法变更](#reflect-set方法变更) + +### 变更详情 + +#### Reflect-get方法变更 +**ArkTS1.1版本签名：** + `function get(target: T, propertyKey: P, receiver?: unknown): P extends keyof T ? T[P] : any` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | T | 是 | 目标对象。 | + | propertyKey | P | 是 | 属性键。 | + | receiver | unknown | 否 | 接收器对象，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | P extends keyof T ? T[P] : any | 返回属性值。 | + +**示例：** + ```typescript + class C { + a: number; + get x() { return this.a; } + } + Reflect.get(a, "x"); + ``` + +**ArkTS1.2版本签名：** + `function get(target: object, propertyKey: string): NullishType` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | object | 是 | 目标对象。 | + | propertyKey | string | 是 | 属性键。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | NullishType | 返回属性值、null或undefined。 | + +**示例：** + ```typescript + class C { +     a: number=1; + } + let a = new C() + Reflect.get(a, "a") + ``` + +**适配建议：** + 不使用泛型参数，属性名只能是字符串，不支持receiver参数。 + +#### Reflect-has方法变更 +**ArkTS1.1版本签名：** + `function has(target: object, propertyKey: PropertyKey): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | object | 是 | 目标对象。 | + | propertyKey | PropertyKey | 是 | 属性键。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否包含属性，true表示是，false表示不包含属性。 | + +**示例：** + ```typescript + let a = [1,2,3]; + Reflect.has(a, 0); + ``` + +**ArkTS1.2版本签名：** + `function has(target: object, propertyKey: string): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | object | 是 | 目标对象。 | + | propertyKey | string | 是 | 属性键。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示是否包含属性，true表示是，false表示不包含属性。 | + +**示例：** + ```typescript + class C{ +     a: number=1; + } + let a = new C() + Reflect.has(a, "a") + ``` + +**适配建议：** + 只使用字符串作为属性名。 + +#### Reflect-ownKeys方法变更 +**ArkTS1.1版本签名：** + `function ownKeys(target: object): (string | symbol)[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | object | 是 | 目标对象。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | (string \| symbol)[] | 属性键数组。 | + +**示例：** + ```typescript + let a = [1,2,3]; + Reflect.ownKeys(a); + ``` + +**ArkTS1.2版本签名：** + `function ownKeys(target: object): string[]` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | object | 是 | 目标对象。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | string[] | 属性键数组。 | + +**示例：** + ```typescript + class C{ +     a: number=1; + } + let a = new C(); + console.info(Reflect.ownKeys(a)); + ``` + +**适配建议：** + 只使用字符串作为属性名。 + +#### Reflect-set方法变更 +**ArkTS1.1版本签名：** + `function set(target: T, propertyKey: P, value: P extends keyof T ? T[P] : any, receiver?: any): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | T | 是 | 目标对象。 | + | propertyKey | P | 是 | 属性键。 | + | value | P extends keyof T ? T[P] : any | 是 | 属性值。 | + | receiver | any | 否 | 接收器对象，默认值为undefined。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示设置是否成功，true表示成功，false表示不成功。 | + +**示例：** + ```typescript + let a = [1,2,3]; + Reflect.set, number>(a, 0, 2); + ``` + +**ArkTS1.2版本签名：** + `function set(target: object, propertyKey: string, value: object): boolean` + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + |--------|------|------|------| + | target | object | 是 | 目标对象。 | + | propertyKey | string | 是 | 属性键。 | + | value | object | 是 | 属性值。 | + +**返回值：** + | 类型 | 说明 | + |------|------| + | boolean | 表示设置是否成功，true表示成功，false表示不成功。 | + +**示例：** + ```typescript + class C { +     a: number=1; + } + let a = new C() + Reflect.set(a, "a", Number(2)) + console.info(a.a) + ``` + +**适配建议：** + 不使用泛型参数，属性名只能是字符串，值必须是对象类型。 + + +## TemplateStringsArray + +### 变更梗概 +- [TemplateStringsArray-raw属性变更](#templatestringsarray-raw属性变更) + +### 变更详情 + +#### TemplateStringsArray-raw属性变更 +**ArkTS1.1版本签名：** + `readonly raw: readonly string[]` + +- 类型说明： + | 属性名 | 类型 | 说明 | + |--------|------|------| + | raw | readonly string[] | 原始字符串数组。 | + +**示例：** + ```typescript + function f(a: TemplateStringsArray) { + a.raw; + } + f`Hello`; + ``` + +**ArkTS1.2版本签名：** + N/A + +**适配建议：** + 不使用模板字符串标签函数。 + diff --git a/zh-cn/application-dev/quick-start/arkts-interop-more.md b/zh-cn/application-dev/quick-start/arkts-interop-more.md new file mode 100644 index 0000000000000000000000000000000000000000..9a9b8d4d0eb84b8bc94e06650badd00f8c193be5 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-interop-more.md @@ -0,0 +1,267 @@ +# ArkTS1.2互操作场景 + +## ArkTS1.2中使用ArkTS1.1或TS + +### 文件导入 + +在ArkTS1.2中使用`import`函数导入ArkTS1.1模块的对象。 + +```typescript +// file1.ets ArkTS1.1 +export function foo() {} +export class A { + field: number = 0; + test() {} +} +``` + +```typescript +// file2.ets ArkTS1.2 +import { foo, A } from "./file1"; +``` + +### 类实例化 + +在ArkTS1.2中使用从ArkTS1.1中导入的类，并用new来创建该类的实例。 + +```typescript +// file1.ets ArkTS1.1 +export class A { + id: number = 0; + constructor(arg: number) { + this.id = arg; + } +} +export class B extends A { + name: string = ""; + constructor(arg0: number, arg1: string) { + super(arg0); + this.name = arg1; + } +} +export interface Inface { + x: number; + y: number; + normSquare(): number; +} +export class C implements Inface { + x: number = 0; + y: number = 0; + normSquare(): number { + return x * x + y * y; + } +} +``` + +```typescript +// file2.ets ArkTS1.2 +import { A, B, C } from "./file1"; +let a = new A(123); +let b = new B(456, "Bob"); +let c = new C(); +``` + +### 属性读写 + +在ArkTS1.2中读写ArkTS1.1对象的属性。 + +```typescript +// file1.ets ArkTS1.1 +export class Person { + public id: number = 0; + private name_: string = ""; + constructor(name: string) { + this.name_ = name; + } + get name(): string { + return this.name_; + } + set name(name: string) { + this.name_ = name; + } +} +``` + +```typescript +// file2.ets ArkTS1.2 +import { Person } from "./file1"; +let p = new Person("John"); +console.log(p.name); // Output: John +p.name = "Alice"; +console.log(p.name); // Output: Alice +p.id = 123456; +console.log(p.id); // Output: 123456 +``` + +### 函数调用 + +在ArkTS1.2中直接调用从ArkTS1.1导入的函数。 + +```typescript +// file1.ets ArkTS1.1 +export let say = (msg: string) => { + console.log(msg); +}; +export function myAdd(a: number, b: number): number { + let ret = a + b; + console.log(ret); + return ret; +} +``` + +```typescript +// file2.ets ArkTS1.2 +import { say, myAdd } from "file1"; +say("Hello"); // Output: Hello +myAdd(3, 4); // Output: 7 +``` + +### 对象方法调用 + +在ArkTS1.2中直接调用ArkTS1.1导入对象的方法。 + +```typescript +// file1.ets ArkTS1.1 +export class A { + function log() { + console.log(123) + } +} +class B { + foo() : void {} +} +export class C extends B { + override foo() : void { console.log('D.foo') } +} +interface interA { + foo: () => void; +} +export let itA: InterA = { + foo: () => { console.log('interface log') } +} +export let arr = new Array(1, 2, 3); +``` + +```typescript +// file2.ets ArkTS.12 +import { A, C, itA, arr } from "file1"; +let a = new A(); +a.foo(); +let c = new C(); +c.foo(); // Output: D.foo +itA.foo(); +arr.push(4); +``` + +### 参数传递 + +可以将ArkTS1.2的对象直接作为参数传入到`import`来的ArkTS1.1函数。 + +```typescript +// file1.ets ArkTS1.1 +export function foo(a: Array) { + console.log(a[0]); +} +export class C { + static foo(a: Array) { + console.log(a[0]); + } + bar(a: Array) { + console.log(a[0]); + } +} +export interface Iface { + foo(a: Array): void; +} + +// file2.ets ArkTS1.2 +import { foo, C, Iface } from "file1"; + +foo(["Hi", "Bye"]); // Output: Hi +C.foo(["Hi", "Bye"]); // Output: Hi +new C().bar(["Hi", "Bye"]); // Output: Hi + +function baz(i: Iface) { + i.foo(["Hi", "Bye"]); // OK +} +``` + +### 异常处理 + +当在ArkTS1.1中定义一个异常的实例时，可以在ArkTS1.2中捕获这个异常。 + +```typescript +// file1.ets ArkTS1.1 +export let err = new Error("123"); +export function foo1() { + throw err; +} + +export let ranErr = new RangeError("456"); +export function foo2() { + throw err; +} + +export let refErr = new ReferenceError("789"); +export function foo3() { + throw err; +} + +export let synErr = new SyntaxError("111"); +export function foo4() { + throw err; +} + +export let uriErr = new URIError("222"); +export function foo5() { + throw err; +} + +// file2.ets ArkTS1.2 +import { + err, + ranErr, + refErr, + synErr, + uriErr, + foo1, + foo2, + foo3, + foo4, + foo5, +} from "1.1"; +err instanceof Error; // true +try { + foo(); +} catch (e) { + (e as Error).message; // OK, '123' +} + +ranErr instanceof RangeError; // true +try { + foo(); +} catch (e) { + (e as RangeError).message; // OK, '456' +} + +refErr instanceof ReferenceError; // true +try { + foo(); +} catch (e) { + (e as ReferenceError).message; // OK, '789' +} + +synErr instanceof SyntaxError; // true +try { + foo(); +} catch (e) { + (e as SyntaxError).message; // OK, '111' +} + +uriErr instanceof URIError; // true +try { + foo(); +} catch (e) { + (e as URIError).message; // OK, '222' +} +``` diff --git a/zh-cn/application-dev/quick-start/arkts-interop-overview.md b/zh-cn/application-dev/quick-start/arkts-interop-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..f06559259e3ef4af0799a265951eb183b18bde33 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-interop-overview.md @@ -0,0 +1,141 @@ +# ArkTS1.2互操作概述 + +## 背景 + +ArkTS1.2在ArkTS1.1版本的基础上增强了类型安全和并发能力，带来了基于静态类型系统的编译器和运行时实现。为了让开发者能够达到更好的并发性能等目的，可选择ArkTS1.2作为开发语言，或将存量应用逐步改造为ArkTS1.2版本。在此场景下，为了让开发者能够复用已有的生态资产，以及让存量应用的开发者可以便捷地逐步迁移到ArkTS1.2，我们需要提供ArkTS1.2和ArkTS1.1以及TS/JS代码的交互能力。 + +## 可交互方向 + +- ArkTS1.2可以导入ArkTS1.1, TS, JS。 +- ArkTS1.1可以导入ArkTS1.2。 +- TS/JS不可以导入ArkTS1.2/ArkTS1.1。 + +## ArkTS1.2 静态语义原则 + +- ArkTS1.2的对象的布局不能被修改，动态修改对象布局（包括新增或删除对象属性，以及修改对象属性的类型）将会出现编译时报错或者运行时报错。 +- ArkTS1.2的函数参数需要匹配声明的类型，否则会出现编译报错或运行时报错。 +- ArkTS1.2代码中的类型转换如果不能在运行时以合理的方式进行，将会出现编译报错或运行时报错。 + +## ArkTS1.2类型系统 + +- ArkTS1.2的顶层类型有：`undefined`，`null`和`Any`。 + - `Any`有子类`Object`，`Object`有子类`ESValue`。ArkTS1.2中的自定义类，标准库(`Array/Map/Set`等)等类型都是`Object`的子类型。 + +### ESValue + +- `ESValue`是`Object`的子类。 +- `ESValue`可用于封装来自于JS的对象。 +- `ESValue`提供了多种方法来对应对象的常见操作。比如：加载 JS 模块、实例化`new obj(x)`、函数调用`obj(x)`、属性访问`obj.prop`、方法调用`obj.foo(x)`、索引访问`obj[idx]`等。 +- ArkTS1.2的`ESValue`作为普通的类型，并无额外限制和额外特权。比如：ArkTS1.2中`ESValue`可以用于类型标注和泛型，但针对`ESValue`类型对象的操作也只能通过调用它的方法来进行。 + +```txt +AnyObject + | +Object + | +ESValue -|- (static) load(path: string): ESValue // 模块加载 + |- wrap(arg: Any) // 将对象包装成ESObject实例 + |- getProperty(key: string | number): ESValue // 读属性 + |- setProperty(key: string | number, newVal: ESValue): void // 写属性 + |- instantiate(...args: ESValue[]): ESValue // 实例化 + |- invoke(...args: ESValue[]): ESValue // 函数调用 + |- invokeMethod(methodName: string, ...args: ESValue[]): ESValue // 方法调用 + |- toString(): string // 将包装的对象转换为string + |- toNumber(): number // 将包装的对象转换为number + |- ... +``` + +（TODO：加链接）`ESValue`接口说明文档。 + +## 交互基本原则 + +- ArkTS1.2特有的语言特性不能用于和ArkTS1.1交互（比如：重载、注解、final、尾随闭包、function with receiver）。 +- ArkTS1.0特有的语言特性不能用于和ArkTS1.2交互（比如：@Sendable/@Concurrenct）。 +- TS特有的语言特性不能用于和ArkTS1.2交互（比如：decorator、call-signature）。 +- ArkTS1.2的对象属性在动态上下文使用时有如下特点： + - 没有自身属性（own property）。 + - 对象和对象的属性都是密封的（sealed）。 +- ArkTS1.2和JS的交互，需要开发者显式调用API来进行交互。 + +```javascript +// file1.js +export class A { + constructor() { + console.log("new A"); + } + msg = "hello"; + data = [1, 2, 3]; + say(arg) { + console.log(this.msg + arg); + } +} +export function foo(arg) { + return arg; +} +``` + +```typescript +// file2.ets ArkTS1.2 +// 加载模块 +let module: ESValue = ESValue.load('./file1') +let foo ESValue = module.getProperty('foo') +let A: ESValue = module.getProperty('A') +// 实例化 +let aa: ESValue = A.instantiate() +// 调用函数 +let a: ESValue = foo.invoke(aa) +// 读属性 +let msg: ESValue = a.getProperty('msg') +let msgStr: string = msg.toString() // 'hello' +let data: ESValue = a.getProperty('data') +// 写属性 +let newMsgValue: ESValue = ESValue.wrap('world') // 将对象包装成ESObject实例 +a.setProperty('msg', newMsgValue) +// 调用方法 +a.invokeMethod('say', ESValue.wrap(' cup')) // 打印'world cup' +// 读索引元素 +let element0 = data.getProperty(0) +element0.toNumber() // 1 +// 写索引元素 +data.setProperty(2, ESValue.wrap(4)) +``` + +- ArkTS1.2和ArkTS1.1/TS的交互，不需要开发者显式调用API来进行交互。 + +```typescript +// file1.ts +export class A { + constructor() { + console.log("new A"); + } + msg: string = "hello"; + data: Array = [1, 2, 3]; + say(arg: string): void { + console.log(this.msg + arg); + } +} +export function foo(arg: A): A { + return arg; +} +``` + +```typescript +// file2.ets ArkTS1.2 +// 加载模块 +import { A, foo } from "./file1"; +// 实例化 +let aa: A = new A(); +// 调用函数 +let a: A = foo(aa); +// 读属性 +let msg: string = a.msg; // 'hello' +let data: Array = a.data; +// 写属性 +a.msg = "world"; +// 调用方法 +a.say(" cup"); // 打印'world cup' +// 读索引元素 +let element0 = data[0]; // 1 +// 写索引元素 +data[2] = 4; +``` diff --git a/zh-cn/application-dev/quick-start/arkts-interop-spec.md b/zh-cn/application-dev/quick-start/arkts-interop-spec.md new file mode 100644 index 0000000000000000000000000000000000000000..e9a3bae21af2c408cf09c0f155b7e86c3d8c483c --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-interop-spec.md @@ -0,0 +1,3055 @@ +# ArkTS1.2互操作特性规范 + +## ArkTS1.2互操作场景 + +### ArkTS1.1中使用ArkTS1.2 + +#### 文件导入 + +在ArkTS1.2中使用`import`函数导入ArkTS1.1的文件相关的内容，包含函数，类，对象等。 + +```typescript +// file1.ets ArkTS1.2 +export function func(){} +export class A{} +export let a: A = new A(); + +// file2.ets ArkTS1.1 +import { func, A, a} from './file1' +``` + +#### 类实例化 + +在ArkTS1.1中可以使用从ArkTS1.2中导入的类，用new来创建该类的实例。 + +```typescript +// file1.ets ArkTS1.2 +export class A {} +export class B extends A {} +interface interA {} +export class C implements interA {} + +// file2.ets ArkTS1.1 +import { A, B, C } from "file1"; +let a = new A(); +let b = new B(); +let c = new C(); +``` + +#### 属性读写 + +在ArkTS1.1中可以读写ArkTS1.2中导入的对象的属性。 + +```typescript +// file1.ets ArkTS1.2 +export class Person { + name: string = "unknown" +} + +// file2.ets ArkTS1.1 +import { Person } from "file1"; +let a = new Person(); +let b = a.name; // "unknown" +a.name = "John"; +``` + +#### 函数调用 + +在ArkTS1.1中可以直接调用ArkTS1.2中导入的函数。 + +```typescript +// file1.ets ArkTS1.2 +export let func = () => { + console.log(123); +}; +export function foo1() {} +export function foo2(a: number, b: number): number { + return a + b; +} + +// file2.ets ArkTS1.1 +import { func, foo1, foo2 } from "file1"; +func(); +foo1(); +foo(1.5, 2.5); +``` + +#### 对象方法调用 + +在ArkTS1.2中可以直接访问ArkTS1.1导入对象的方法。 + +```typescript +// file1.ets ArkTS1.2 +export class A { + function log() { + console.log(123) + } +} +class B { + foo() : void {} +} +export class C extends B { + override foo() : void { console.log('D.foo') } +} +interface interA { + foo: () => void; +} +export let itA: InterA = { + foo: () => { console.log('interface log')) } +} +export let arr = new Array(1, 2, 3); + +// file2.ets ArkTS1.1 +import { A, C, itA, arr } from 'file1' +let a = new A() +a.foo() +let c = new C() +c.foo() // Output: D.foo +itA.foo() +arr.push(4) +``` + +#### 参数传递 + +在ArkTS1.1中可以将ArkTS1.1的参数传至导入的函数，从而回传至ArkTS1.2。 + +```typescript +// file1.ets ArkTS1.2 +export function foo(a: Array) { + console.log(a[0]); +} +export class C { + static foo(a: Array) { + console.log(a[0]); + } + bar(a: Array) { + console.log(a[0]); + } +} +export interface Iface { + foo(a: Array): void; +} + +// file2.ets ArkTS1.1 +import { foo, C, Iface } from "file1"; + +foo(["Hi", "Bye"]); // Output: Hi +C.foo(["Hi", "Bye"]); // Output: Hi +new C().bar(["Hi", "Bye"]); // Output: Hi + +function baz(i: Iface) { + i.foo(["Hi", "Bye"]); // OK +} +``` + +#### 异常处理 + +ArkTS1.1中定义一个异常的实例，可以在ArkTS1.2中捕获这个异常。 + +```typescript +// file1.ets ArkTS1.2 +export function foo() { + throw new Error("123"); +} + +// file2.ets ArkTS1.1 +import { foo } from "1.1"; + +try { + foo(); +} catch (e) { + (e as Error).message; // "123" +} +``` + +### ArkTS1.2中使用TS + +#### 文件导入 + +在ArkTS1.2中使用`import`函数导入ArkTS1.1的文件相关的内容，包含函数，类，对象等。 + +```typescript +// file1.ts +export function func(){} +export class A{} +export let a: A = new A(); + +// file2.ets ArkTS1.2 +import { func, A, a} from './file1' +``` + +#### 类实例化 + +在ArkTS1.1中可以使用从ArkTS1.2中导入的类，用new来创建该类的实例。可以访问实例的方法和属性。也可以使用ArkTS1.1的类扩展ArkTS1.2的类后创建实例对象。 + +```typescript +// file1.ts +export class A {} +export class B extends A {} +interface interA {} +export class C implements interA {} + +// file2.ets ArkTS1.2 +import { A, B, C } from "file1"; +let a = new A(); +let b = new B(); +let c = new C(); +``` + +#### 属性读写 + +在ArkTS1.2中可以读写从TS中导入对象。 + +```typescript +// file1.ts +export class Person { + name: string = "unknown" +} + +// file2.ets ArkTS1.2 +import { Person } from "file1"; +let a = new Person(); +let b = a.name; // "unknown" +a.name = "John"; +``` + +#### 函数调用 + +在ArkTS1.2中可以调用从TS中导入函数。 + +```typescript +// file1.ts +export let func = () => { + console.log(123); +}; +export function foo1() {} +export function foo2(a: number, b: number): number { + return a + b; +} + +// file2.ets ArkTS1.2 +import { func, foo1, foo2 } from "file1"; +func(); +foo1(); +foo(1.5, 2.5); +``` + +#### 对象方法调用 + +在ArkTS1.2中可以调用从TS中导入的对象，并调用该对象的方法。 + +```typescript +// file1.ts +export class A { + function log() { + console.log(123) + } +} +class B { + foo() : void {} +} +export class C extends B { + override foo() : void { console.log('D.foo') } +} +interface interA { + foo: () => void; +} +export let itA: InterA = { + foo: () => { console.log('interface log')) } +} +export let arr = new Array(1, 2, 3); + +// file2.ets ArkTS.12 +import { A, C, itA, arr } from 'file1' +let a = new A() +a.foo() +let c = new C() +c.foo() // Output: D.foo +itA.foo() +arr.push(4) +``` + +#### 参数传递 + +在ArkTS1.2中可以调用从TS中导入的函数，并将参数传递至TS。 + +```typescript +// file1.ts +export function foo(a: Array) { + console.log(a[0]); +} +export class C { + static foo(a: Array) { + console.log(a[0]); + } + bar(a: Array) { + console.log(a[0]); + } +} +export interface Iface { + foo(a: Array): void; +} + +// file2.ets ArkTS1.2 +import { foo, C, Iface } from "file1"; + +foo(["Hi", "Bye"]); // Output: Hi +C.foo(["Hi", "Bye"]); // Output: Hi +new C().bar(["Hi", "Bye"]); // Output: Hi + +function baz(i: Iface) { + i.foo(["Hi", "Bye"]); // OK +} +``` + +#### 异常处理 + +TS中定义一个异常的实例，可以在ArkTS1.2中捕获这个异常。 + +```typescript +// file1.ts +export function foo() { + throw new Error("123") +} + +// file2.ets ArkTS1.2 +import { foo } from "./file1"; + +try { + foo(); +} catch (e) { + (e as Error).message; // '123' +} +``` + +### ArkTS1.2中使用JS + +#### 文件导入 + +```typescript +// file1.js +export function func(){} +export class A{} +export let a: A = new A(); + +// file2.ets ArkTS1.2 +let mod: ESValue = ESValue.load('./file1') +let func: ESValue = mod.getProperty('func') +let A: ESValue = mod.getProperty('A') +let a: ESValue = mod.getProperty('a') +``` + +#### 类实例化 + +可以在ArkTS1.2中创建新的JS类，通过ESValue创建JS类的实例。 + +```typescript +// file1.js +export class A {} + +// file2.ets ArkTS1.2 +let mod: ESValue = ESValue.load("js"); +let A: ESValue = module.getProperty("A"); +let a: ESValue = A.instantiate(); // 创建A的实例，这个实例被包装在a中 +``` + +#### 属性读写 + +在ArkTS1.2中可以访问JS类实例的字段和方法。 + +```typescript +// file1.js +export class A { + name = "unknown" +} + +// file2.ets ArkTS1.2 +let module = ESValue.load('./file1') +let A = module.getProperty('A'); +let a = A.instantiate() +b.getProperty('name').toString() // "unknown" +a.setProperty('name', ESValue.wrap('John')) +b.getProperty('name').toString() // "John" +``` + +#### 函数调用 + +在ArkTS1.2中可以通过ESValue来调用JS的函数。 + +```typescript +// file1.js +export function foo() { + return 100 +} + +// file2.ets ArkTS1.2 +let foo: ESValue = ESValue.load("./file1").getProperty("foo"); +let res: ESValue = foo.invoke(); +let resNum: string = res.toNumber(); // 100 +``` + +#### 对象方法调用 + +在ArkTS1.2中可以通过ESValue来调用JS的对象的方法。 + +```typescript +//file1.js +export class A { + sayHi(msg: string) { + console.log(msg) + return msg + } + static getInstance() { + return new A() + } +} + +//file2.ets ArkTS1.2 +let A = ESValue.load('./file1').getProperty('A') +let a: ESValue = A.invokeMethod('getInstance') // 调用静态方法 +let msg: ESValue = a.invokeMethod('sayHi', ESValue.wrap('hello')) // 调用实例方法, 打印hello +msg.toString() // 'hello' +``` + +#### 参数传递 + +在ArkTS1.2中可以通过ESValue来调用JS的函数将参数传递至JS。 + +```typescript +// file1.js +export function foo(msg, count) { + for (let i = 0; i < count; ++i) { + console.log(msg) + } +} + +// file2.ets ArkTS1.2 +let foo = ESValue.load("./file1").getProperty("foo"); +foo.invoke(ESValue.wrap("hello"), ESValue.wrap(3)); // 打印3次hello +``` + +#### 异常处理 + +在JS中定义一个异常的实例，可以在ArkTS1.2中ESValue来获取这个异常。 + +```typescript +// file1.js +export function foo() { + throw new Error('123') +} + +// file2.ets ArkTS1.2 +let foo = ESValue.load('./file1').getProperty('foo') +try { + foo.invoke() +} catch(e) { + (e as Error).message // '123' +} +``` + +## 交互限制 + +### 在ArkTS1.2中使用ArkTS1.1 + +#### ArkTS1.1给ArkTS1.2传参或赋值给Object类型 + +- ArkTS1.1语法 + +```typescript +// fiel1.ets +export function foo(obj: Object) {} +export class A { + data: Object = 0; +} + +// file2.ets +import { foo, A } from "./file1"; + +class X {} +foo(new X()); +interface Y { + s: string; +} +let y: Y = { s: "Hi" }; +let a = new A(); +a.data = y; +``` + +- ArkTS1.2语法 + +```typescript +// fiel1.ets ArkTS1.2 +export function foo(obj: Object) {} +// solution: export function foo(obj: Any) {} +export class A { + data: Object = 0; +} +// solution: export class A { data: Any = ESValue.wrap(0) } + +// file2.ets ArkTS1.1 +import { foo, A } from "./file1"; + +class X {} +foo(new X()); // 运行时报错 +interface Y { + s: string; +} +let y: Y = { s: "Hi" }; +let a = new A(); +a.data = y; // 运行时报错 +``` + +- 编译报错信息： + nan +- 运行时报错信息： + runtime type cast error +- 适配建议： + nan +- 变更理由： + nan + +--- + +#### ArkTS1.1的Object内置方法作用在ArkTS1.2对象上 + +- ArkTS1.1语法 + +```typescript +// file2.ets +export class X { + a = 1; +} + +// file1.ets +import { X } from "./file2"; +function foo(prx: Object) { + Object.getOwnPropertyDescriptor(prx, "a"); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ['a'] + Object.hasOwn(prx, "a"); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty("a"); // true + prx.propertyIsEnumerable("a"); // true +} + +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file2.ets ArkTS1.2 +export class X { + a = 1; +} +// solution for Object.keys, case for Object.values is similar: +export function getKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { + return Object.keys(prx); + } + return undefined; +} +// file1.ets ArkTS1.1 +import { X, getKeys } from "./file2"; +function myGetKeys(prx: Object) { + let ret = getKeys(prx); + if (ret == undefined) { + // prx is dynamic + return Object.keys(prx); + } + return ret; +} +export function foo(prx: Object) { + Object.getOwnPropertyDescriptor(prx, "a"); // undefined + Object.getOwnPropertyDescriptors(prx); // {} + Object.getOwnPropertyNames(prx); // [] + Object.hasOwn(prx, "a"); // false + Object.isExtensible(prx); // false + Object.isFrozen(prx); // true + Object.isSealed(prx); // true + Object.keys(prx); // [] + myGetKeys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // 运行时报错 + Object.values(prx); // [] + prx.hasOwnProperty("a"); // false + prx.propertyIsEnumerable("a"); // false +} + +foo(new X()); +``` + +- 编译报错信息： + nan +- 运行时报错信息： + object is sealed +- 适配建议： + nan +- 变更理由： + nan + +--- + +#### ArkTS1.1的Reflect内置方法作用在ArkTS1.2对象上 + +- ArkTS1.1语法 + +```typescript +// file2.ets +export class X { + a: string = "hello"; + getName() { + return this.a; + } +} + +// file1.ets +import { X } from "./file2"; +function foo(prx: Object) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, "newField", { value: 7 }); // true + Reflect.deleteProperty(prx, "a"); // true + Reflect.getOwnPropertyDescriptor(prx, "a"); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, "newField", 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} + +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file2.ets ArkTS1.2 +export class X { + a: string = 'hello' + getName() { return this.a } +} + +// solution for static ownKeys: +export getOwnKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { return Reflect.ownKeys(prx) } + return undefined +} + +// file1.ets ArkTS1.1 +import {X, getOwnKeys} from './file2' +function myOwnKeys(prx: Object) { + let ret = getOwnKeys(prx) + if (ret == undefined) { // prx is dynamic + return Reflect.ownKeys(prx) + } + return ret +} + +function foo(prx: Object) { + Reflect.apply(prx.getName, {a: 12}) // 运行时报错 + Reflect.defineProperty(prx, 'newField', {value: 7}) // false + Reflect.deleteProperty(prx, 'a') // false + Reflect.getOwnPropertyDescriptor(prx, 'a') // undefined + Reflect.ownKeys(prx) // [] + myOwnKeys(prx) // ['a'] + Reflect.isExtensible(prx) // false + Reflect.set(prx, 'newField', 7) // false + Reflect.setPrototypeOf(prx, {}) // false +} + +foo(new X()) +``` + +- 编译报错信息： + nan +- 运行时报错信息： + runtime cast error +- 适配建议： + nan +- 变更理由： + nan + +--- + +#### ArkTS1.2的Object内置方法作用在ArkTS1.1对象上 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export function foo(prx: Object) { + Object.assign({}, prx); // OK + Object.entries(prx); // [a, 1] + Object.keys(prx); // ['a'] + Object.values(prx); // [1] + prx.hasOwnProperty("a"); // true +} + +// file2.ets +import { foo } from "./file1"; +class X { + a = 1; +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ArkTS1.2 +export function foo(prx: Object) { + Object.assign({}, prx); // OK + Object.entries(prx); // [a, 1] + Object.keys(prx); // ['a'] + Object.values(prx); // [1] + prx.hasOwnProperty("a"); // true +} + +// file2.ets ArkTS1.1 +import { foo } from "./file1"; +class X { + a = 1; +} +foo(new X()); // 运行时报错 +``` + +- 编译报错信息： + nan +- 运行时报错信息： + object is sealed +- 适配建议： + nan +- 变更理由： + nan + +--- + +#### ArkTS1.2 Reflect内置方法作用在ArkTS1.1对象 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export function foo(prx: Object) { + Reflect.get(prx, "a"); // 'hello' + Reflect.set(prx, "a", "world"); // true + Reflect.ownKeys(prx); // ['a'] +} + +// file2.ets +import { foo } from "./file1"; +class X { + a: string = "hello"; + getName() { + return this.a; + } +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ArkTS1.2 +export function foo(prx: Object) { + Reflect.get(prx, "a"); // 'hello' + Reflect.set(prx, "a", "world"); // true + Reflect.ownKeys(prx); // ['a'] +} + +// file2.ets ArkTS1.1 +import { foo } from "./file1"; +class X { + a: string = "hello"; + getName() { + return this.a; + } +} +foo(new X()); // 运行时报错 +``` + +- 编译报错信息： + nan +- 运行时报错信息： + runtime cast error +- 适配建议： + nan +- 变更理由： + nan + +### ArkTS1.1中使用ArkTS1.2 + +#### ArkTS1.1 Object内置方法作用在ArkTS1.2对象 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export function foo(prx: ESValue) { + Object.getOwnPropertyDescriptor(prx, "a"); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ['a'] + Object.hasOwn(prx, "a"); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty("a"); // true + prx.propertyIsEnumerable("a"); // true +} + +// file2.ets +import { foo } from "./file1"; +class X { + a = 1; +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// solution for Object.keys, case for Object.values is similar: +// file0.ets ArkTS1.2 +export function getKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { + return Object.keys(prx); + } + return undefined; +} + +// file1.ets ArkTS1.1 +import { getKeys } from "./file0"; +function myGetKeys(prx: ESValue) { + let ret = getKeys(prx); + if (ret == undefined) { + // prx is dynamic + return Object.keys(prx); + } + return ret; +} +export function foo(prx: Object) { + Object.getOwnPropertyDescriptor(prx, "a"); // undefined + Object.getOwnPropertyDescriptors(prx); // {} + Object.getOwnPropertyNames(prx); // [] + Object.hasOwn(prx, "a"); // false + Object.isExtensible(prx); // false + Object.isFrozen(prx); // true + Object.isSealed(prx); // true + Object.keys(prx); // [] + myGetKeys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // 运行时报错 + Object.values(prx); // [] + prx.hasOwnProperty("a"); // false + prx.propertyIsEnumerable("a"); // false +} + +// file2.ets ArkTS1.2 +import { foo } from "./file1"; +class X { + a = 1; +} +foo(new X()); +``` + +- 编译报错信息： + nan +- 运行时报错信息： + object is sealed +- 适配建议： + 根据这些变化重新适配代码，或者避免使用这些内置底层接口。 +- 变更理由： + ArkTS1.2对象在动态上下文中没有own property，表现为sealed，不能修改对象布局。 + +--- + +#### ArkTS1.1 Reflect内置方法作用在ArkTS1.2对象 + +- ArkTS1.1语法 + +```typescript +// file1.ets +import {foo} from './file1' +export class X { + a: string = 'hello' + getName() { return this.a } +} + +// file2.ets +improt {X} from './file1' +function foo(prx: ESValue) { + Reflect.apply(prx.getName, {a: 12}) // 12 + Reflect.defineProperty(prx, 'newField', {value: 7}) // true + Reflect.deleteProperty(prx, 'a') // true + Reflect.getOwnPropertyDescriptor(prx, 'a') // not undefined + Reflect.ownKeys(prx) // ['a'] + Reflect.isExtensible(prx) // true + Reflect.set(prx, 'newField', 7) // true + Reflect.setPrototypeOf(prx, {}) // true +} +foo(new X()) +``` + +- ArkTS1.2语法 + +```typescript +// solution for static ownKeys: +// file0.ets ArkTS1.2 +export getOwnKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { return Reflect.ownKeys(prx) } + return undefined +} + +// file1.ets ArkTS1.1 +import {getOwnKeys} from './file0' +export function myOwnKeys(prx: ESValue) { + let ret = getOwnKeys(prx) + if (ret == undefined) { // prx is dynamic + return Reflect.ownKeys(prx) + } + return ret +} + +export function foo(prx: ESValue) { + Reflect.apply(prx.getName, {a: 12}) // 运行时报错 + Reflect.defineProperty(prx, 'newField', {value: 7}) // false + Reflect.deleteProperty(prx, 'a') // false + Reflect.getOwnPropertyDescriptor(prx, 'a') // undefined + Reflect.ownKeys(prx) // [] + myOwnKeys(prx) // ['a'] + Reflect.isExtensible(prx) // false + Reflect.set(prx, 'newField', 7) // false + Reflect.setPrototypeOf(prx, {}) // false +} + +// file2.ets ArkTS1.2 +improt {foo} from './file1' +export class X { + a: string = 'hello' + getName() { return this.a } +} +foo(new X()) +``` + +- 编译报错信息： + nan +- 运行时报错信息： + runtime cast error +- 适配建议： + 根据这些变化重新适配代码，或者避免使用这些内置底层接口 +- 变更理由： + ArkTS1.2对象在动态上下文中没有own property，表现为sealed，不能修改对象布局。 + +--- + +#### ArkTS1.2动态import ArkTS1.1 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export class A {} + +// file2.ets +let mod = await import("./file1"); +let A: ESObject = mod.A; +let a = new A() as A; + +// 动态import class function enum 变量 +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ArkTS1.1 +export class A {} + +// file2.ets ArkTS1.2 +let mod = ESValue.load("./file1"); +let A: ESValue = mod.getProperty("A"); +let a = A.instantiate() as A; +``` + +- 编译报错信息： + SyntaxError: Unexpected token, expected an identifier. +- 运行时报错信息： + 不涉及 +- 适配建议： + 使用ESValue接口动态导入模块和调用接口 +- 变更理由： + ArkTS1.2没有动态import语法，使用ESValue接口动态导入动态模块。 + +--- + +#### ArkTS1.2创建ArkTS1.1的没有无参构造函数的类的对象字面量 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export class X { + name: string; + constructor(arg: string) { + this.name = arg; + } +} +// file2.ets +import { X } from "./file1"; +let x: X = { name: "hello" }; +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ArkTS1.1 +export class X { + name: string; + constructor(arg: string) { + this.name = arg; + } +} +// file2.ets ArkTS1.2 +import { X } from "./file1"; +let x: X = { name: "hello" }; // 编译报错 +``` + +- 编译报错信息 + type X has no parameterless constructor +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用new: + let x: X = new X('hello') +- 变更理由 + ArkTS1.2的语法限制 + +--- + +#### ArkTS1.2创建ArkTS1.1具有二义性的对象字面量 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export class X { + name: string = ""; +} +export interface Y { + name: string; + age?: number; +} + +// file2.ets +import { X, Y } from "./file1"; +let x: X | Y = { name: "hello" }; +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ArkTS1.1 +export class X { + name: string = ""; +} +export interface Y { + name: string; + age?: number; +} + +// file2.ets ArkTS1.2 +import { X, Y } from "./file1"; +let x: X | Y = { name: "hello" }; // 编译报错 +``` + +- 编译报错信息 + object literal is ambiguous for the type X | Y +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用 as确定类型 + let x: X | Y = {name: 'hello'} as X +- 变更理由 + ArkTS1.2的语法限制 + +--- + +#### ArkTS1.2创建ArkTS1.1的类的对象字面量 + +- ArkTS1.1语法 + +```typescript +// file1.ets +export class A { + name: string = ""; +} + +// file2.ets +import { A } from "./file1"; +let a: A = { name: "hello" }; // let a = {}， a.name = 'hello' + +a instanceof A; // false +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ArkTS1.1 +export class A { + name: string = ""; +} + +// file2.ets ArkTS1.2 +import { A } from "./file1"; +let a: A = { name: "hello" }; // let a = new A(), a.name = 'hello' + +a instanceof A; // true +``` + +- 编译报错信息 + 不涉及 +- 运行时报错信息 + 不涉及 +- 适配建议 + 不要使用instanceof 判断字面量类型 +- 变更理由 + ArkTS1.2的语义变更 + +### ArkTS1.2中使用TS + +#### ArkTS1.2访问TS独有类型的实体 + +实体类型如下所示: + +- any +- unknown +- symbol +- Function +- object literal (比如{x: number, y: string}) +- mixing enum (比如enum X {a = 0, b = '1'}) +- call signature (比如{(arg: number): string}) +- constructor signature (比如{new(): Object} +- index signature (比如{[index: number]: string}) +- intersection (比如TypeA & TypeB) +- keyof (比如interface X { props: keyof T}) +- typeof(比如let p = {x: 1, y: ''}, let q: typeof p) +- indexed access type( 比如 MyArray = [{ name: 'Alice', age: 15 }] type Person = typeof MyArray[number]) +- conditional types （比如 type Swap = T extends A ? B : A) +- mapped types (比如 type A = {[K in keyof T]: T[K]}) +- template literal types (比如type AB = 'A' | 'B', type AllLocaleIDs = `${AB}_id`) +- 工具类型如下所示： + - Pick + - Omit + - Exclude + - Extract + - NonNullable + - Parameters + - ConstructorParameters + - ReturnType + - InstanceType + - NoInfer + - ThisParameterType + - OmitThisParameter + - ThisType + - Uppercase + - Lowercase + - Capitalize + - Uncapitalize +- TS语法 + +```typescript +// file1.ts +export let obj: SomeType; // SomeType是某个TS独有类型 + +// file2.ets +import { obj } from "./file1"; +let val = obj.prop; +obj.prop = 1; +obj.foo(); +obj(); +let item = obj[0]; +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export let obj: SomeType; +// 从ArkTS1.2看来，这个声明为 +// export let obj: ESValue + +// file2.ets ArkTS1.2 +import { obj } from "./file1"; +obj.setProperty("prop", ESValue.wrap(1)); +``` + +- 编译报错信息： + - obj does not have property prop + - obj does not have property prop + - obj does not have method foo + - obj is not callable + - obj is not indexable +- 运行时报错信息： + 不涉及。 +- 适配建议： + 使用ESValue接口进行交互。 +- 变更理由： + ArkTS1.2中不支持这些类型。 + +--- + +#### ArkTS1.2 for-of遍历自定义TS可迭代对象 + +- TS语法 + +```typescript +// file1.ts +export class MyIter { + [Symbol.iterator](): IterableIterator {...} +} + +// file2.ets +import {MyIter} from './file1' +let m = new MyIter() +for (let a of m) { doSomething(a as number) } +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export class MyIter { + [Symbol.iterator](): IterableIterator {...} +} + +// file2.ets ArkTS1.2 +import {MyIter} from './file1' +let m = new MyIter(); +let eo = ESValue.wrap(m) +for (let a of eo) { + doSomething(a.toNumber()) +} +``` + +- 编译报错信息： + m is not iterable +- 运行时报错信息： + nan +- 适配建议： + 转换为ESValue再进行用for-of遍历 +- 变更理由： + ArkTS1.2和TS的可迭代的定义不同。ArkTS1.2中没有Symbol.iterator方法，无法识别自定义的ts可迭代对象 + +--- + +#### Object内置方法作用在ArkTS1.2对象 + +- TS语法 + +```typescript +// file1.ts +export function foo(prx: any) { + Object.getOwnPropertyDescriptor(prx, "a"); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ['a'] + Object.hasOwn(prx, "a"); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty("a"); // true + prx.propertyIsEnumerable("a"); // true +} + +// file2.ets +import { foo } from "./file1"; +class X { + a = 1; +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export function foo(prx: any) { + Object.getOwnPropertyDescriptor(prx, 'a') // undefined + Object.getOwnPropertyDescriptors(prx) // {} + Object.getOwnPropertyNames(prx) // [] + Object.getOwnPropertySymbols(prx)) // [] + Object.hasOwn(prx, 'a') // false + Object.isExtensible(prx) // false + Object.isFrozen(prx) // true + Object.isSealed(prx) // true + Object.keys(prx) // [] + Object.setPrototypeOf(prx, {}) // 运行时报错 + Object.values(prx) // [] + prx.hasOwnProperty('a') // false + prx.propertyIsEnumerable('a') // false +} + +// file2.ets +import {foo} from './file1' +class X { a = 1 } +foo(ESValue.wrap(new X())) +``` + +- 编译报错信息： + parameter type does not match +- 运行时报错信息： + object is sealed +- 适配建议： + 根据这些变化重新适配代码，或者避免使用这些内置底层接口 +- 变更理由： + ArkTS1.2对象在动态上下文中没有own property，表现为sealed，不能修改对象布局。 + +--- + +#### Reflect内置方法作用在ArkTS1.2对象 + +- TS语法 + +```typescript +// file1.ts +export function foo(prx: any) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, "newField", { value: 7 }); // true + Reflect.deleteProperty(prx, "a"); // true + Reflect.getOwnPropertyDescriptor(prx, "a"); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, "newField", 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} + +// file2.ets +import { foo } from "./file1"; +class X { + a: string = "hello"; + getName() { + return this.a; + } +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export function foo(prx: any) { + Reflect.apply(prx.getName, { a: 12 }); // 运行时报错 + Reflect.defineProperty(prx, "newField", { value: 7 }); // false + Reflect.deleteProperty(prx, "a"); // false + Reflect.getOwnPropertyDescriptor(prx, "a"); // undefined + Reflect.ownKeys(prx); // [] + Reflect.isExtensible(prx); // false + Reflect.set(prx, "newField", 7); // false + Reflect.setPrototypeOf(prx, {}); // false +} + +// file2.ets +import { foo } from "./file1"; +class X { + a: string = "hello"; + getName() { + return this.a; + } +} +foo(ESValue.wrap(new X())); +``` + +- 编译报错信息： + parameter type does not match +- 运行时报错信息： + runtime cast error +- 适配建议： + 根据这些变化重新适配代码，或者避免使用这些内置底层接口 +- 变更理由： + ArkTS1.2对象在动态上下文中没有own property，表现为sealed，不能修改对象布局。 + +--- + +#### ArkTS1.2处理ts非常规异常 + +- TS语法 + +```typescript +// file1.ts +export function foo() { + throw 123; +} + +// file2.ets +import { foo } from "./file1"; + +try { + foo(); +} catch (e) { + console.log(e as number); // 123 +} +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export function foo() { + throw 123; +} + +// file2.ets // ArkTS1.2 +import { foo } from "./file1"; + +try { + foo(); +} catch (e) { + let err: ESValue = (e as ESError).getValue(); + err.toNumber(); // 123 +} +``` + +- 编译报错信息： + ArkTS1.2 only catch a Error instance +- 运行时报错信息： + 不涉及 +- 适配建议： + ArkTS1.2只能catch Error实例，针对非常规的ts异常对象，交互是会被包装到ESError中，通过getValue()方法可以获取包装了原始异常对象的ESValue实例 +- 变更理由： + ArkTS1.2中throw和catch的对象只能是Error的实例 + +--- + +#### ArkTS1.2判断TS boxed type类型 + +- TS语法 + +```typescript +// file1.ts +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String("hello"); +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' + +//file2.ets +import { a, b, c, d, e } from "./fiel1"; +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String("hello"); +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' + +//file2.ets ArkTS1.2 +import { a, b, c, d, e } from "./fiel1"; +typeof a; // 'number' +typeof b; // 'boolean' +typeof c; // 'string' +``` + +- 编译报错信息： + 不涉及 +- 运行时报错信息： + 不涉及 +- 适配建议： + 避免使用boxed类型，或者避免对boxed类型进行typeof +- 变更理由： + ArkTS1.2不区分基本类型和boxed类型，因此js的boxed对象在interop时会被unboxed成基本类型的值 + +--- + +#### ArkTS1.2动态import TS + +- TS语法 + +```typescript +// file1.ts +export class A {} + +// file2.ets +let mod = await import("./file1"); +let A: ESObject = mod.A; +let a = new A() as A; +``` + +- ArkTS1.2语法 + +```typescript +// file1.ets ts +export class A {} + +// file2.ets ArkTS1.2 +let mod = ESValue.load("./file1"); +let A: ESValue = mod.getProperty("A"); +let a = A.instantiate() as A; +``` + +- 编译报错信息： + SyntaxError: Unexpected token, expected an identifier. +- 运行时报错信息： + 不涉及 +- 适配建议： + 使用ESValue接口动态导入模块和调用接口 +- 变更理由： + ArkTS1.2没有动态import语法，使用ESValue接口动态导入动态模块。 + +--- + +#### ArkTS1.2创建TS的类的对象字面量 + +- TS语法 + +```typescript +// file1.ts +export class A { + name: string = ""; +} + +// file2.ets +import { A } from "./file1"; +let a: A = { name: "hello" }; + +a instanceof A; // false +``` + +- ArkTS1.2语法 + +```typescript +// file1.ts +export class A { + name: string = ""; +} + +// file2.ets ArkTS1.2 +import { A } from "./file1"; +let a: A = { name: "hello" }; + +a instanceof A; // true +``` + +- 编译报错信息： + 不涉及 +- 运行时报错信息： + 不涉及 +- 适配建议： + 不要使用instanceof 判断字面量类型 +- 变更理由： + ArkTS1.2的语义变更 + +### ArkTS1.2中使用JS + +#### ArkTS1.2导出js实体 + +- JS语法 + +```typescript +// file1.js +export function foo() {} +export class A {} + +// file2.ets +import { foo } from "./file1"; +export { foo }; + +export { A } from "./file1"; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo() {} +export class A {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let A = mod.getProperty("A"); + +export { foo, A }; +``` + +- 编译报错信息： + ArkTS1.2 cannot export entities from js +- 运行时报错信息： + 不涉及 +- 适配建议： + 直接从js文件导入使用 +- 变更理由： + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2调用js函数和传参 + +- JS语法 + +```typescript +// file1.js +export function foo() {} +export function bar(a) {} + +// file2.ets +import { foo, bar } from "./file1"; +foo(); +bar(123); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo() {} +export function bar(a) {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let bar = mod.getProperty("bar"); +foo.invoke(); +bar.invoke(ESValue.wrap(123)); +``` + +- 编译报错信息： + - ArkTS1.2 cannot import js files directly + - foo is not callable +- 运行时报错信息： + 不涉及 +- 适配建议： + 调用ESValue的接口，接口接收参数为ESValue类型，传参时需要用wrap接口构造ESValue实例再传参。 +- 变更理由： + - ArkTS1.2中只能和有类型声明的文件进行交互。 + - ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景。 + +--- + +#### ArkTS1.2实例化js对象 + +- JS语法 + +```typescript +// file1.js +class foo { + constructor(a) {} +} +// file2.ets +import { foo } from "./file1"; +new foo(123); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +class foo { + constructor(a) {} +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +foo.instantiate(ESValue.wrap(123)); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not constructor +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口实例化，接口接收参数为ESValue类型，传参时需要用wrap接口构造ESValue实例再传参 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2访问js属性 + +- JS语法 + +```typescript +// file1.js +export let foo = { name: "123" }; +// file2.ets +import { foo } from "./file1"; +foo.name; +foo.name = "456"; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = {name: '123'} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let foo = mod.getProperty('foo') +foo.getProperty('name') +foo.setProperty('name', ESValue.wrap('456')） +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have property 'name' +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口访问属性，接口接收参数为ESValue类型，传参时需要用wrap接口构造ESValue实例再传参 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2调用js方法和传参 + +- JS语法 + +```typescript +// file1.js +class Foo { + bar(a) {} +} +export let foo = new Foo(); +// file2.ets +import { foo } from "./file1"; +foo.bar(123); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +class Foo { + bar(a) {} +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +foo.invokeMethod("bar", ESValue.wrap(123)); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have method 'bar' +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口调用方法，接口接收参数为ESValue类型，传参时需要用wrap接口构造ESValue实例再传参 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2访问js索引 + +- JS语法 + +```typescript +// file1.js +export let foo = { arr: [1, 2, 3] }; +// file2.ets +import { foo } from "./file1"; +let arr = foo.arr; +arr[1]; +arr[3] = 4; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = [1, 2, 3]; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let arr = foo.getProperty("arr"); +arr.getProperty(1); +arr.setProperty(3, ESValue.wrap(4)); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not indexable +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口访问索引，接口接收参数为ESValue类型，传参时需要用wrap接口构造ESValue实例再传参 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2转换js对象类型 + +- JS语法 + +```typescript +// file1.js +export let foo1 = { num: 123 }; +export let foo2 = { bool: true }; +export let foo3 = { str: "123" }; +export let foo4 = { big: 123n }; + +// file2.ets +import { foo } from "./file1"; +let a: number = foo1.num as number; +let a: boolean = foo2.bool as boolean; +let a: string = foo3.str as string; +let a: bigint = foo4.big as bigint; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo1 = { num: 123 }; +export let foo2 = { bool: true }; +export let foo3 = { str: "123" }; +export let foo4 = { big: 123n }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo1 = mod.getProperty("foo1"); +let num = foo.getProperty("num"); +let a1: number = num.toNumber(); + +let foo2 = mod.getProperty("foo2"); +let bool = foo.getProperty("bool"); +let a2: boolean = bool.toBoolean(); + +let foo3 = mod.getProperty("foo3"); +let str = foo3.getProperty("str"); +let a3: string = str.toString(); + +let foo4 = mod.getProperty("foo4"); +let big = foo.getProperty("big"); +let a4: bigint = big.toBigInt(); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + cannot cast ESValue to number + cannot cast ESValue to boolean + cannot cast ESValue to string + cannot cast ESValue to bigint +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口转换类型 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2获取js对象类型 + +- JS语法 + +```typescript +// file1.js +export let foo = { num: 123 }; + +// file2.ets +import { foo } from "./file1"; +typeof foo.num; // 'number' +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = 123; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let num = foo.getProperty("num"); + +num.typeOf(); // 'number' +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口获取类型 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2判断js对象类型 + +- JS语法 + +```typescript +// file1.js +export class Foo {} +export let foo = new Foo(); + +// file2.ets +import { Foo, foo } from "./file1"; +foo instanceof Foo; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export class Foo {} +export let foo = new Foo(); + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let Foo = mod.getProperty("Foo"); +let foo = mod.getProperty("foo"); + +foo.isInstanceOf(Foo); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + Foo is not a type +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口判断类型 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2对js对象自增自减 + +- JS语法 + +```typescript +// file1.js +export let foo = { num: 0 }; + +// file2.ets +import { foo } from "./file1"; +let a: number = 0; +a = foo.num++; +a = ++foo.num; +a = foo.num--; +a = --foo.num; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = { num: 0 }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let a: number = 0; + +// a = foo.num++ +let num = foo.getProperty("num"); +let tmp: number = num.toNumber(); +a = tmp; +foo.setProperty("num", ESValue(tmp + 1)); + +// a = ++foo.num +num = foo.getProperty("num"); +tmp = num.toNumber() + 1; +foo.setProperty("num", ESValue(tmp)); +a = tmp; +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have property 'num' + foo.num is not number +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口转换为数字后再操作 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2对js对象进行一元运算 + +- JS语法 + +```typescript +// file1.js +export let foo = { num: 0 }; +// file2.ets +import { foo } from "./file1"; ++foo.num - foo.num; +!foo.num; +~foo.num; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = { num: 0 }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let num = + foo.getProperty("num") + + // +foo.num + num.toNumber() - + // -foo.num + num.toNumber(); +// !foo.num +!num.toNumber(); +// ~foo.num +~num.toNumber(); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have property 'num' + foo.num is not number +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口转换为数字后再操作 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2对js对象进行二元运算 + +- JS语法 + +```typescript +// file1.js +export let foo = { a: 1, b: 2 }; + +// file2.ets +import { foo } from "./file1"; +let a = foo.a; +let b = foo.b; +a + b; +a - b; +a * b; +a / b; +a % b; +a ** b; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = { a: 1, b: 2 }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let a = foo.getProperty("a").toNumber(); +let b = foo.getProperty("b").toNumber(); +a + b; +a - b; +a * b; +a / b; +a % b; +a ** b; +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have property 'a' + foo does not have property 'b' + a is not number + b is not number +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口转换为数字后再操作 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2 await js Promise对象 + +- JS语法 + +```typescript +// file1.js +async function foo(){} +export p = foo() + +// file2.ets +import {p} from './file1' +async function bar() { + await p +} +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +async function foo(){} +export p = foo() + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let p = mod.getProperty('p') + +async function bar() { + await p.toPromise() +} +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + p is not Promise +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口转换为Promise对象后再await +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2对js数据进行比较 + +- JS语法 + +```typescript +// file1.js +export let foo = { a: 1, b: 2 }; + +// file2.ets +import { foo } from "./file1"; +let a = foo.a; +let b = foo.b; +a > b; +a < b; +a >= b; +a <= b; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let a = 1; +export let b = 2; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let a = foo.getProperty("a").toNumber(); +let b = foo.getProperty("b").toNumber(); + +a > b; +a < b; +a >= b; +a <= b; +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + a is not number + b is not number +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口转换为数字后再操作 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2对js数据进行相等判断 + +- JS语法 + +```typescript +// file1.js +class A {} +export let a = new A(); +export let b = new A(); + +// file2.ets +import { a, b } from "./file1"; +a == b; +a != b; +a === b; +a !== b; +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +class A {} +export let a = new A(); +export let b = new A(); + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let a = mod.getProperty("a"); +let b = mod.getProperty("b"); + +a.areEqual(b); +!a.areEqual(b); +a.areStrictlyEqual(b); +!a.areStrictlyEqual(b); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + a is not number + b is not number +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue的接口判断 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2对js对象进行条件判断 + +- JS语法 + +```typescript +// file1.js +export let foo = { isGood: true }; + +// file2.ets +import { foo } from "./file1"; + +if (foo.isGood) { +} +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = { isGood: true }; + +// file2.ets +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); + +let isGood = foo.getProperty("isGood").toBoolean(); +if (isGood) { +} +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have property 'isGood' +- 运行时报错信息 + nan +- 适配建议 + 使用ESValue的接口转换为boolean +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2继承js的类 + +- JS语法 + +```typescript +// file1.js +export class A {} + +// file2.ets +import { A } from "./file1"; +class B extends A {} +let b = new B(); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export class A {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let A = mod.getProperty("A"); + +let B: ESValue = ESValue.defineClass("B", () => {}, undefined, undefined, A); +let b = B.instantiate(); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + A is not a class +- 运行时报错信息 + nan +- 适配建议 + 使用ESValue的接口构造JS类并传递js父类 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### ArkTS1.2处理js非常规异常 + +- JS语法 + +```typescript +// file1.js +export function foo() { + throw 123; +} + +// file2.ets +import { foo } from "./file1"; + +try { + foo(); +} catch (e) { + console.log(e as number); //123 +} +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo() { + throw 123; +} + +// file2.ets +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); + +try { + foo.invoke(); +} catch (e) { + let err: ESValue = (e as ESError).getValue(); + err.toNumber(); // 123 +} +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + ArkTS1.2 only catch a Error instance +- 运行时报错信息 + 不涉及 +- 适配建议 + ArkTS1.2只能catch Error实例，针对非常规的js异常对象，交互是会被包装到ESError中，通过getValue()方法可以获取包装了原始异常对象的ESValue实例 +- 变更理由 + ArkTS1.2中throw和catch的对象只能是Error的实例 + +--- + +#### ArkTS1.2访问js的boxed对象 + +- JS语法 + +```typescript +// file1.js +export let foo = { + num: new Number(123), + bool: new Boolean(true), + str: new String("hello"), +}; + +// file2.ets +import { foo } from "./file1"; +typeof foo.num; // 'object' +typeof foo.bool; // 'object' +typeof foo.str; // 'object' +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = { + num: new Number(123), + bool: new Boolean(true), + str: new String("hello"), +}; + +// file2.ets +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); + +foo.getProperty("num").typeOf(); // 'number' +foo.getProperty("bool").typeOf(); // 'boolean' +foo.getProperty("str").typeOf(); // 'string' +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have properties 'num', 'bool', 'str' +- 运行时报错信息 + 不涉及 +- 适配建议 + 避免使用boxed类型，或者避免对boxed类型进行typeof +- 变更理由 + ArkTS1.2不区分基本类型和boxed类型，因此js的boxed对象在interop时会被unboxed成基本类型的值 + +--- + +#### ArkTS1.2遍历js对象 + +- JS语法 + +```typescript +// file1.js +export let foo = { arr: [1, 2, 3] }; +// file2.ets +import { foo } from "./file1"; +let arr = foo.arr; +let len = arr.length as number; +for (let i = 0; i < len; ++i) { + arr[i] as number; + arr[i] = 0; +} +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export let foo = { arr: [1, 2, 3] }; + +// file2.ets ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +let arr = foo.getProerptyByName("arr"); +let len = arr.getProerptyByName("length").toNumber(); +for (let i = 0; i < len; ++i) { + arr.getPropertyByIndex(i).toNumber(); + arr.setPropertyByIndex(i, ESValue.wrap(0)); +} +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo does not have property 'arr' + arr does not have property 'length' + arr is not indexable +- 运行时报错信息 + 不涉及 +- 适配建议 + 使用ESValue接口访问索引和属性 +- 变更理由 + ArkTS1.2中只能和有类型声明的文件进行交互。 + ArkTS1.2中限制ESValue的动态行为，形成动静态更清晰的界限，减少开发者滥用ESValue导致性能劣化的场景 + +--- + +#### js调用ArkTS1.2函数和传参 + +- JS语法 + +```typescript +// file1.js +export function handle(cb) { + let p = { name: "hello" }; + cb(p); +} + +// file2.ets +import { handle } from "./file1"; +interface Person { + name: string; +} + +function foo(p: Person) {} +let lambda = (p: Person) => {}; + +handle(foo); +handle(lambda); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function handle(cb) { + let p = { name: "hello" }; + cb(p); +} + +// file2.ets +let mod = ESValue.load("./file1"); +let handle = mod.getProperty("handle"); +interface Person { + name: string; +} +function foo(p: Person) {} +// solution: function foo(p: ESValue) {} +let lambda = (p: Person) => {}; +// solution: let lambda = (p: ESValue) => {} + +handle.invoke(ESValue.wrap(foo)); +handle.invoke(ESValue.wrap(lambda)); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not callable +- 运行时报错信息 + runtime cast error +- 适配建议 + 确保传参匹配参数声明的类型 +- 变更理由 + ArkTS1.2的函数运行时会检查参数类型，需要确保参数类型匹配 + +--- + +#### js增删改ArkTS1.2对象属性 + +- JS语法 + +```typescript +// file1.js +export function foo(obj) { + obj.newField = 1; // 增加属性 + delete obj.data; // 删除属性 + obj.name = "123"; // 修改属性值（同类型） + obj.name = { firstName: "456" }; // 修改属性值（不同类型） +} + +// file2.ets +import { foo } from "./file1"; +class X { + name: string = ""; + data: number = 0; +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo(obj) { + obj.newField = 1; // 增加属性 运行时报错 + delete obj.data; // 删除属性 运行时报错 + obj.name = "123"; // 修改属性值（同类型）OK + obj.name = { firstName: "456" }; // 修改属性值（不同类型）运行时报错 +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +class X { + name: string = ""; + data: number = 0; +} +foo.invoke(ESValue.wrap(new X())); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not callable +- 运行时报错信息 + object is sealed +- 适配建议 + 避免动态修改对象布局。需要新增的属性提前在类型中声明，需要删除的属性使用undefined置空。 +- 变更理由 + ArkTS1.2的对象布局在编译时就确定了，不能动态修改 + +--- + +#### js Object内置方法作用在ArkTS1.2对象 + +- JS语法 + +```typescript +// file1.js +export function foo(prx) { + Object.getOwnPropertyDescriptor(prx, "a"); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ['a'] + Object.hasOwn(prx, "a"); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty("a"); // true + prx.propertyIsEnumerable("a"); // true +} + +// file2.ets +import { foo } from "./file1"; +class X { + a = 1; +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo(prx) { + Object.getOwnPropertyDescriptor(prx, 'a') // undefined + Object.getOwnPropertyDescriptors(prx) // {} + Object.getOwnPropertyNames(prx) // [] + Object.getOwnPropertySymbols(prx)) // [] + Object.hasOwn(prx, 'a') // false + Object.isExtensible(prx) // false + Object.isFrozen(prx) // true + Object.isSealed(prx) // true + Object.keys(prx) // [] + Object.setPrototypeOf(prx, {}) // 运行时报错 + Object.values(prx) // [] + prx.hasOwnProperty('a') // false + prx.propertyIsEnumerable('a') // false +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let foo = mod.getProperty('foo') +class X { a = 1 } +foo.invoke(ESValue.wrap(new X())) +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not callable +- 运行时报错信息 + object is sealed +- 适配建议 + 根据这些变化重新适配代码，或者避免使用这些内置底层接口 +- 变更理由 + ArkTS1.2对象在动态上下文中没有own property，表现为sealed，不能修改对象布局。 + +--- + +#### jsReflect内置方法作用在ArkTS1.2对象 + +- JS语法 + +```typescript +// file1.js +export function foo(prx) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, "newField", { value: 7 }); // true + Reflect.deleteProperty(prx, "a"); // true + Reflect.getOwnPropertyDescriptor(prx, "a"); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, "newField", 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} + +// file2.ets +import { foo } from "./file1"; +class X { + a: string = "hello"; + getName() { + return this.a; + } +} +foo(new X()); +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo(prx) { + Reflect.apply(prx.getName, { a: 12 }); // 运行时报错 + Reflect.defineProperty(prx, "newField", { value: 7 }); // false + Reflect.deleteProperty(prx, "a"); // false + Reflect.getOwnPropertyDescriptor(prx, "a"); // undefined + Reflect.ownKeys(prx); // [] + Reflect.isExtensible(prx); // false + Reflect.set(prx, "newField", 7); // false + Reflect.setPrototypeOf(prx, {}); // false +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load("./file1"); +let foo = mod.getProperty("foo"); +class X { + a: string = "hello"; + getName() { + return this.a; + } +} +foo.invoke(ESValue.wrap(new X())); +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not callable +- 运行时报错信息 + runtime cast error +- 适配建议 + 根据这些变化重新适配代码，或者避免使用这些内置底层接口 +- 变更理由 + ArkTS1.2对象在动态上下文中没有own property，表现为sealed，不能修改对象布局。 + +--- + +#### js对ArkTS1.2对象进行展开语法 + +- JS语法 + +```typescript +// file1.js +export function foo(obj) { + let x = {...obj} // x will be { a = 1; b = 2; c = 3 } + let {a, b, ...rest} = obj // a will be 1, b will be 2, rest will be {c: 3} + +// file2.ets +import {foo} from './file1' +class X { a = 1; b = 2; c = 3 } +foo(new X()) + +// class interface Record +``` + +- ArkTS1.2语法 + +```typescript +// file1.js +export function foo(obj) { + let x = {...obj} // x will be empty object {}. because there is no own properties for static object + // solution: let x = {a: obj.a, b: obj.b, c: obj.c} + // keys + Reflect.get + let {a, b, ...rest} = obj + // a will be 1, b will be 2, rest will be empty object {}, because there is no own properties for static object + // solution: let rest = {c: obj.c} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let foo = mod.getProperty('foo') +class X { a = 1; b = 2; c = 3 } +foo.invoke(ESValue.wrap(new X())) +``` + +- 编译报错信息 + ArkTS1.2 cannot import js files directly + foo is not callable +- 运行时报错信息 + 不涉及 +- 适配建议 + 根据这些变化重新适配代码，或者避免使用解构语法。 +- 变更理由 + ArkTS1.2对象在动态上下文中没有own property，相关解构操作会失效。 + +--- + +#### ArkTS1.2动态import JS + +- JS语法 + +```typescript +ArkTS1.2动态导入JS +``` + +- ArkTS1.2语法 + +```typescript +不涉及; +``` + +- 编译报错信息 + SyntaxError: Unexpected token, expected an identifier. +- 运行时报错信息 + SyntaxError: Unexpected token, expected an identifier. +- 适配建议 + +```typescript +// file1.js +export class A {} + +// file2.ets ArkTS1.2 +let mod = ESValue.load("./file1"); +let A: ESValue = mod.getProperty("A"); +let a = A.instantiate(); +``` + +- 变更理由 + 使用ESValue接口动态导入模块和调用接口 + +## ArkTS1.2并发场景下的交互 + +并发执行ArkTS1.1&ArkTS1.2混合代码的主要方式通过ArkTS1.2的上下文；ArkTS1.1中需要执行ArkTS1.1&ArkTS1.2混合代码的场景需要迁移到ArkTS1.2来保证易用性和性能。 + +### ArkTS1.2使用ArkTS1.1的场景 + +#### ArkTS1.2与ArkTS1.1的Promise互操作 + +```typescript +// file1.ets ArkTS1.1 +export let p = new Promise((resolve, reject) => { + setTimeout(() => { + resolve("foo"); + }, 300); +}); +// file2.ets ArkTS1.2 +import { p } from "file1"; +// OK +p.then((s: String) => { + console.log(s); +}); +// OK +p.catch((e: Object) => { + console.error(e); +}); +// OK +p.finally(() => { + console.log("Completed"); +}); +// OK +async function foo() { + const result = await p; +} +``` + +#### ArkTS1.2与ArkTS1.1的async function互操作 + +```typescript +// file1.ets ArkTS1.1 +export async function foo() {} +// file2.ets ArkTS1.2 +import { foo } from "file1"; +// OK, call foo +function baz() { + foo(); +} +// OK, await foo +await foo(); +async function bar() { + await foo(); +} +// OK, use the return value as a 1.2 Promise +const p = foo(); +``` + +#### ArkTS1.2单线程异步上下文与ArkTS1.1对象互操作 + +- 使用当前线程的动态上下文，规格同主线程规格 + +```typescript +// file1.ets ArkTS1.1 +export let s = new String("123"); +export function foo(arg: Object) { + console.log(typeof arg); + return 42; +} +// file2.ets ArkTS1.2 +import { s, foo } from "file1"; +function bar() { + let p = new Promise( + (resolve: (v: number) => void, _: (error: Object) => void) => { + // OK + foo.invoke(s); + resolve(42); + } + ); +} +async function baz() { + // OK + foo.invoke(s); +} +``` + +#### ArkTS1.2多线程异步上下文与ArkTS1.1对象互操作 + +- 跨线程通信时，适用1.1线程间通信的规格，但sendData / onReceiveData不再支持，用1.2线程间通信代替 +- 使用当前线程的动态上下文，规格同主线程规格 + +```typescript +// file1.ets ArkTS1.1 +export let s = new String('123') +@concurrent +export function foo(arg: Object){ + console.log(typeof arg) + return 42; +} +export function bar() { + return foo(42); // 违反闭包原则，报错 +} +// file2.ets ArkTS1.2 +import { s, foo, bar } from 'file1' +// 1.2 Taskpool +function baz() { + // OK. print 'object' + taskpool.execute(foo, s); + // NO. not allowed to call 1.1 non-concurrenct function + taskpool.execute(bar); +} +// 1.2 EAWorker +let eaw : EAWorker = new EAWorker(); +// OK. print 'object' +let p = eaw.run(foo, s); +// NO. not allowed to call 1.1 non-concurrenct function +let q = eaw.run(bar) +cont result = p.Await(); +eaw.stop(); +``` + +#### 协程不支持互操作 + +```typescript +// file1.ets ArkTS1.1 +export let function foo() {} +export async function bar() {} +export let p = new Promise(...) +// file2.ets ArkTS1.2 +import {foo, bar, A, p} from 'file1' +async function baz() { + foo(); // NO + await bar(); // NO + await p; // NO +} +launch(baz) // NO +``` + +### ArkTS1.1使用ArkTS1.2的场景 + +#### ArkTS1.1与ArkTS1.2的Promise互操作 + +```typescript +// file1.ets ArkTS1.2 +export let p = new Promise( + (resolve: (v: number) => void, _: (error: Object) => void) => { + setTimeout(() => { + resolve("foo"); + }, 300); + } +); +// file2.ets ArkTS1.1 +import { p } from "file1"; +// OK +p.then((value) => { + console.log(value); +}); +// OK +p.catch((error) => { + console.error(error); +}); +// OK +p.finally(() => { + console.log("Completed"); +}); +// OK +await p; +``` + +#### ArkTS1.1与ArkTS1.2的async function互操作 + +```typescript +// file1.ets ArkTS1.2 +export async function foo() {} +// file2.ets ArkTS1.1 +import { foo } from "file1"; +// OK, call foo +function baz() { + foo(); +} +// OK, await foo +await foo(); +async function bar() { + await foo(); +} +// OK, use the return value as a 1.1 Promise +const p = foo(); +``` + +#### ArkTS1.1单线程异步上下文与ArkTS1.2对象互操作 + +- 主线程使用主线程规格，非主线程（Taskpool和Worker）不支持互操作 + +```typescript +// file1.ets ArkTS1.2 +export class A {} +export function foo(arg: Object) { + arg as A; +} +// file2.ets ArkTS1.1 +import { foo, A } from "file1"; +const p = new Promise((resolve, reject) => { + foo(123); // RTE + foo(new A()); // OK + resolve("foo"); +}); +async function bar() { + foo(123); // RTE + foo(new A()); // OK +} +``` + +#### ArkTS1.1多线程异步上下文不支持互操作 + +- Taskpool和Worker上下文不支持互操作 + +```typescript +// file1.ets ArkTS1.2 +export class A {} +export function foo(arg: Object) { + arg as A; +} +// file2.ets ArkTS1.1 +import { foo, A } from "file1"; +foo(new A()); // OK +// file3.ets ArkTS1.1 +import { foo, A } from "file1"; +function bar() { + // NO + taskpool.execute(foo, new A()); +} +// NO +let workerInstance = new worker.ThreadWorker("file2.ets"); +``` diff --git a/zh-cn/application-dev/quick-start/arkts-interop-type-mapping.md b/zh-cn/application-dev/quick-start/arkts-interop-type-mapping.md new file mode 100644 index 0000000000000000000000000000000000000000..7abeccb1bc3dfe2452ba4a686e5bea35fae5ad86 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-interop-type-mapping.md @@ -0,0 +1,552 @@ +# ArkTS1.2互操作类型映射规则 + +## 编译类型检查原则 + +- 可以使用ArkTS1.1和TS中的类型在ArkTS1.2的源码中用作类型标注，也可以使用ArkTS1.2中的类型在ArkTS1.1的源码中用作类型标注。 +- 编译类型检查将会根据源码文件的种类来进行： + - ArkTS1.2的文件按照ArkTS1.2的类型检查规则 + - ArkTS1.1的文件按照ArkTS1.1的类型检查规则 + - 针对源码中的交互部分，编译器会使用特定的类型映射规则将交互部分的类型映射到所在文件的类型后，再进行编译检查。 + +## 类型映射基本原则 + +- 基本类型映射为基本类型（比如`number <-> number`）。 +- 标准库类型映射为标准库类型（比如`Array <-> Array`）。 +- 组合类型映射为组合类型（比如`class <-> class`）。 +- 无法直接映射到ArkTS1.2的ArkTS1.1或TS类型，会被映射为`Any`（比如 TS `symbol -> 1.2 Any`）。 +- 无法直接映射到ArkTS1.1的ArkTS1.2类型，会被映射为空，即交互场景不可用（比如ArkTS1.2的`final class`）。 + +## 类型映射详细规则 + +ArkTS1.2采用递归的方式定义类型映射，例如以下的类型映射。 + +| **T** | **f(T)** | +| --------------- | --------------------- | +| `number/Number` | `number` | +| `(arg: A) => R` | `(arg: f(A)) => f(R)` | + +这表示： + +1. 第一行表示`Number`和`number`都被映射到`number`。 +2. 第二行 lambda 类型`(arg: A) => R`被映射为参数类型为`f(A)`且返回值类型为`f(R)`的 lambda 类型，即`(arg: f(A)) => f(R)`；比如`(arg: number) => Number`被映射到`(arg: f(number)) => f(Number)`，即`(arg: number) => number`。 + +### ArkTS1.2类型映射到ArkTS1.1类型 + +#### 基本类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| --------------------- | --------------------- | +| `number/Number` | `number` | +| `double/Double` | `number` | +| `float/Float` | `number` | +| `long/Long` | `number` | +| `int/Int` | `number` | +| `short/Short` | `number` | +| `byte/Byte` | `number` | +| `char/Char` | `string` | +| `string/String` | `string` | +| `literal type string` | `literal type string` | +| `boolean/Boolean` | `boolean` | +| `bigint/BigInt` | `bigint` | +| `null` | `null` | +| `undefined` | `undefined` | +| `void` | `void` | +| `never` | `never` | + +注：`literal type string`指字符串字面量类型，比如`type Alice = 'Alice'`。 + +#### 标准库 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ------------------- | ------------------- | +| `Array` | `Array` | +| `Map` | `Map` | +| `Set` | `Set` | +| `Promise` | `Promise` | +| `RegExp` | `RegExp` | +| `WeakMap` | `WeakMap` | +| `WeakSet` | `WeakSet` | +| `Object` | `Object` | +| `ArrayBuffer` | `ArrayBuffer` | +| `DataView` | `DataView` | +| `Date` | `Date` | +| `Error` | `Error` | +| `RangeError` | `RangeError` | +| `ReferenceError` | `ReferenceError` | +| `SyntaxError` | `SyntaxError` | +| `URIError` | `URIError` | +| `Float32Array` | `Float32Array` | +| `Float64Array` | `Float64Array` | +| `Int8Array` | `Int8Array` | +| `Int16Array` | `Int16Array` | +| `Int32Array` | `Int32Array` | +| `Uint8Array` | `Uint8Array` | +| `Uint16Array` | `Uint16Array` | +| `Uint32Array` | `Uint32Array` | +| `BigInt64Array` | `BigInt64Array` | +| `BigUint64Array` | `BigUint64Array` | +| `Uint8ClampedArray` | `Uint8ClampedArray` | + +#### 工具类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------- | +| `Readonly` | `Readonly` | +| `Record` | `Record` | +| `Required` | `Required` | +| `Partial` | `Partial` | + +#### 函数 + +| **类别** | **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------------- | ---------------------------------------------- | -------------------------------------------------------------- | +| 普通函数 | `function foo(arg1: K1, arg2: K2): R` | `function foo(arg1: f(K1), arg2: f(K2)): f(R)` | +| 可选参数 | `function foo(arg1: K1, arg2​?​: K2): R` | `function foo(arg1: f(K1), arg2​?​: f(K2)): f(R)` | +| 只读参数 | `function foo(arg1: K1, readonly arg2: K2): R` | `function foo(arg1: f(K1), readonly arg2: f(K2)): f(R)` | +| 剩余参数 | `function foo(arg1: K1, ...​arg2: K2): R` | `function foo(arg1: f(K1), ...​arg2: f1.2 type (T)(K2)): f(R)` | +| 普通lambda | `(arg1: K1, arg2: K2) => R` | `(arg1: f(K1), arg2: f(K2)) => f(R)` | +| function with receiver | `function foo(​this​: K1, arg2: K): R` | `function foo(this: f(K1), arg2: f(K2)): f(R)` | +| lambda with receiver | `(​this​: K1, arg2: K2) => R` | `(this: f(K1), arg2: f(K2)) => f(R)` | +| getter with receiver | `get fullName(​this​: K1, arg2: K): R` | map to nothing | +| setter with receiver | `set fullName(​this: K1, arg2: K): R` | map to nothing | + +#### 类 + +TODO: 美化表格 + +| **类别** | **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 普通类 | class A { field: F1m(arg: U1): M1static sf: F2static sm(arg: U2): M2get a(): Vset a(v: V): void} | class A { get field(): f(F1)set field(arg: f(F1)): voidm(arg: f(U1)): f(M1)static sf: f(F2)static sm(arg: f(U2)): f(M2)get a(): f(V)set a(v: f(V)): void} | +| public/private/protected/native/readonly | class A {public field: F1readonly r: F2private m(arg: U1): M1protect p(arg: U2): M2native n(arg: U3): M3} | class A {public field: f(F1)get r(): f(F2)private m(arg: f(U1)): f(M1)protect p(arg: f(U2)): f(M2)n(arg: U3): M3 // native will be ignored} | +| 抽象类 | abstract class A { ... } | abstract class A { ... } // 保留 abstract关键字，内部遵循相同的规则 | +| 继承类和override | class C extends A {override foo(arg: U1): M1} | class C extends A {override foo(arg: f(U1)): f(M1)} | +| 实现类 | class A implements Inface { ... } | class A implements Inface { ... } | +| final类 | final class A { ... } | map to**nothing ​**as it cannot be used in interop | + +#### 接口 + +TODO: 美化表格 + +| **类别** | **1.2 type (T)** | **1.1 type (f(T))** | +| -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | +| 普通接口 | inteface A {field: F1m(arg: U1): M1get a(): Vset a(v: V): void} | class A {field: f(F1)m(arg: f(U1)): f(M1)get a(): f(V)set a(v: f(V)): void} | +| 继承接口 | interface A extends B { ... } | interface A extends B { ... } | + +#### 枚举 + +| **类别** | **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------------------------ | ------------------------------------ | +| 枚举值都为整数 | `enum Color {Blue = 0, Red = 1}` | `enum Color {Blue = 0, Red = 1}` | +| 枚举值都为字符串 | `enum Some {A = 'Alice', B = 'Bob'}` | `enum Some {A = 'Alice', B = 'Bob'}` | + +#### 注解 + +注解不能用于交互，映射为空。 + +#### 命名空间 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| -------------------- | -------------------- | +| `namespace NS {...}` | `namespace NS {...}` | + +#### 联合类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------------- | +| `T1 \| T2 \| T3` | `f(T1) \| f(T2) \| f(T3)` | + +#### 元组类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ----------------------- | +| `[T1, T2, T3]` | `[f(T1), f(T2), f(T3)]` | + +#### 类型别名 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------- | +| `type alias = K` | `type alias = f(K)` | + +### 1.1类型映射到1.2类型 + +#### 基本类型 + +| **1.1 type (T)** | **1.2 type (f(T))** | +| --------------------- | --------------------- | +| `number/Number` | `number` | +| `string/String` | `string` | +| `literal type string` | `literal type string` | +| `boolean/Boolean` | `boolean` | +| `bigint/BigInt` | `bigint` | +| `null` | `null` | +| `undefined` | `undefined` | +| `void` | `void` | +| `never` | `never` | +| `literal type number` | `number` | +| `literal type bigint` | `bigint` | + +> **注意：** `literal type number`和`literal type bigint`分别表示数字字面量和bigint字面量的类型，比如`type PI = 3.14, type LightYear= 9460730472580800n`。 + +#### 标准库 + +| **1.1 type (T)** | **1.2 type (f(T))** | +| ------------------- | ------------------- | +| `Arrays` | `Arrays` | +| `Map` | `Map` | +| `Set` | `Set` | +| `Promise` | `Promise` | +| `RegExp` | `RegExp` | +| `WeakMap` | `WeakMap` | +| `WeakSet` | `WeakSet` | +| `Object` | `Object` | +| `ArrayBuffer` | `ArrayBuffer` | +| `DataView` | `DataView` | +| `Date` | `Date` | +| `Error` | `Error` | +| `RangeError` | `RangeError` | +| `ReferenceError` | `ReferenceError` | +| `SyntaxError` | `SyntaxError` | +| `URIError` | `URIError` | +| `Float32Array` | `Float32Array` | +| `Float64Array` | `Float64Array` | +| `Int8Array` | `Int8Array` | +| `Int16Array` | `Int16Array` | +| `Int32Array` | `Int32Array` | +| `Uint8Array` | `Uint8Array` | +| `Uint16Array` | `Uint16Array` | +| `Uint32Array` | `Uint32Array` | +| `BigInt64Array` | `BigInt64Array` | +| `BigUint64Array` | `BigUint64Array` | +| `Uint8ClampedArray` | `Uint8ClampedArray` | + +#### 工具类型 + +| **1.1 type (T)** | **1.2 type (f(T))** | +| ---------------- | ------------------- | +| `Readonly` | `Readonly` | +| `Record` | `Record` | +| `Required` | `Required` | +| `Partial` | `Partial` | + +#### 函数 + +| **类别** | **1.1 type (T)** | **1.2 type (f(T))** | +| ---------- | ---------------------------------------------- | ------------------------------------------------------- | +| 普通函数 | `function foo(arg1: K1, arg2: K2): R` | `function foo(arg1: f(K1), arg2: f(K2)): f(R)` | +| 可选参数 | `function foo(arg1: K1, arg2?​: K2): R` | `function foo(arg1: f(K1), arg2​​: f(K2)): f(R)` | +| 只读参数 | `function foo(arg1: K1, readonly arg2: K2): R` | `function foo(arg1: f(K1), readonly arg2: f(K2)): f(R)` | +| 剩余参数 | `function foo(arg1: K1, ...arg2: K2): R` | `function foo(arg1: f(K1), ...​arg2: f(K2)): f(R)` | +| 普通lambda | `(arg1: K1, arg2: K2) => R` | `(arg1: f(K1), arg2: f(K2)) => f(R)` | + +#### 类 + +TODO: 美化表格 + +| **类别** | **1.1 type (T)** | **1.2 type (f(T))** | +| --------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| 普通类 | class A {field: F1m(arg: U1): M1static sf: F2static sm(arg: U2): M2get a(): Vset a(v: V): void} | class A {field: f(F1)m(arg: f(U1)): f(M1)static sf: f(F2)static sm(arg: f(U2)): f(M2)get a(): f(V)set a(v: f(V)): void} | +| public/private/protected/readonly | class A {public field: F1readonly r: F2private m(arg: U1): M1protect p(arg: U2): M2} | class A {public field: f(F1)get r(): f(F2)private m(arg: f(U1)): f(M1)protect p(arg: f(U2)): f(M2)} | +| 抽象类 | abstract class A { ... } | abstract class A { ... } // 保留 abstract关键字，内部遵循相同的规则。 | +| 继承类和override | class C extends A {override foo(arg: U1): M1} | class C extends A {override foo(arg: f(U1)): f(M1)} | +| 实现类 | class A implements Inface { ... } | class A implements Inface { ... } | + +#### 接口 + +TODO: 美化表格 + +| **类别** | **1.1 type (T)** | **1.2 type (f(T))** | +| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| 普通接口 | interface A {field: F1m(arg: U1): M1get a(): Vset a(v: V): void} | interface A {field: f(F1)m(arg: f(U1)): f(M1)get a(): f(V)set a(v: f(V)): void} | +| 继承接口 | interface A extends B { ... } | interface A extends B { ... } | + +#### 枚举 + +| **类别** | **1.1 type (T)** | **1.2 type (f(T))** | +| ---------------- | ------------------------------------------------- | ------------------------------------ | +| 枚举值都为整数 | `enum Color {Blue = 0,- Red = 1}` | `enum Color {Blue = 0, Red = 1}` | +| 枚举值都为字符串 | `enum Some {A = 'Alice', B = 'Bob'}` | `enum Some {A = 'Alice', B = 'Bob'}` | +| 其它枚举 | `enum Mix {One = 1, Msg = 'hello', Double = 1.2}` | `Any` | + +#### 注解 + +注解不能用于交互，映射为空。 + +#### 装饰器 + +装饰器不能用于交互，映射为空。（ArkUI定义的装饰器会被特殊处理，映射为ArkTS1.2的注解） + +#### 命名空间 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| -------------------- | -------------------- | +| `namespace NS {...}` | `namespace NS {...}` | + +#### 联合类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------------- | +| `T1 \| T2 \| T3` | `f(T1) \| f(T2) \| f(T3)` | + +#### 元组类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ----------------------- | +| `[T1, T2, T3]` | `[f(T1), f(T2), f(T3)]` | + +#### 类型别名 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------- | +| `type alias = K` | `type alias = f(K)` | + +### TS类型映射到ArkTS1.2类型 + +#### 基本类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| --------------------- | --------------------- | +| `number/Number` | `number` | +| `string/String` | `string` | +| `literal type string` | `literal type string` | +| `boolean/Boolean` | `boolean` | +| `bigint/BigInt` | `bigint` | +| `null` | `null` | +| `undefined` | `undefined` | +| `void` | `void` | +| `never` | `never` | +| `literal type number` | `number` | +| `literal type bigint` | `bigint` | +| `any` | `Any` | +| `symbol/Symbol` | `Any` | +| `unknown` | `Any` | + +#### 标准库 + +| **TS type (T)** | **1.2 type (f(T))** | +| ------------------- | ------------------- | +| `Arrays` | `Arrays` | +| `Map` | `Map` | +| `Set` | `Set` | +| `Promise` | `Promise` | +| `RegExp` | `RegExp` | +| `WeakMap` | `WeakMap` | +| `WeakSet` | `WeakSet` | +| `Object` | `Object` | +| `ArrayBuffer` | `ArrayBuffer` | +| `DataView` | `DataView` | +| `Date` | `Date` | +| `Error` | `Error` | +| `RangeError` | `RangeError` | +| `ReferenceError` | `ReferenceError` | +| `SyntaxError` | `SyntaxError` | +| `URIError` | `URIError` | +| `Float32Array` | `Float32Array` | +| `Float64Array` | `Float64Array` | +| `Int8Array` | `Int8Array` | +| `Int16Array` | `Int16Array` | +| `Int32Array` | `Int32Array` | +| `Uint8Array` | `Uint8Array` | +| `Uint16Array` | `Uint16Array` | +| `Uint32Array` | `Uint32Array` | +| `BigInt64Array` | `BigInt64Array` | +| `BigUint64Array` | `BigUint64Array` | +| `Uint8ClampedArray` | `Uint8ClampedArray` | + +#### 工具类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| ------------------------ | ------------------- | +| `Readonly` | `Readonly` | +| `Record` | `Record` | +| `Required` | `Required` | +| `Partial` | `Partial` | +| `Pick` | `Any` | +| `Omit` | `Any` | +| `Exclude` | `Any` | +| `Extract` | `Any` | +| `NonNullable` | `Any` | +| `Parameters` | `Any` | +| `Constructor` | `Any` | +| `Parameters` | `Any` | +| `ReturnType` | `Any` | +| `InstanceType` | `Any` | +| `NoInfer` | `Any` | +| `This` | `Any` | +| `ParameterType` | `Any` | +| `OmitThisParameter` | `Any` | +| `ThisType` | `Any` | +| `Uppercase` | `Any` | +| `Lowercase` | `Any` | +| `CapitalizeUncapitalize` | `Any` | + +#### 函数 + +| **类别** | **TS type (T)** | **1.2 type (f(T))** | +| ---------- | ---------------------------------------------- | ------------------------------------------------------- | +| 普通函数 | `function foo(arg1: K1, arg2: K2): R` | `function foo(arg1: f(K1), arg2: f(K2)): f(R)` | +| 可选参数 | `function foo(arg1: K1, arg2​?​: K2): R` | `function foo(arg1: f(K1), arg2​?​: f(K2)): f(R)` | +| 只读参数 | `function foo(arg1: K1, readonly arg2: K2): R` | `function foo(arg1: f(K1), readonly arg2: f(K2)): f(R)` | +| 剩余参数 | `function foo(arg1: K1, ​...​arg2: K2): R` | `function foo(arg1: f(K1), ...​arg2: f(K2)): f(R)` | +| 普通lambda | `(arg1: K1, arg2: K2) => R` | `(arg1: f(K1), arg2: f(K2)) => f(R)` | + +#### 类 + +TODO: 美化表格 + +| **类别** | **TS type (T)** | **1.2 type (f(T))** | +| --------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| 普通类 | class A {field: F1m(arg: U1): M1static sf: F2static sm(arg: U2): M2get a(): Vset a(v: V): void} | class A {field: f(F1)m(arg: f(U1)): f(M1)static sf: f(F2)static sm(arg: f(U2)): f(M2)get a(): f(V)set a(v: f(V)): void} | +| public/private/protected/readonly | class A {public field: F1readonly r: F2private m(arg: U1): M1protect p(arg: U2): M2} | class A {public field: f(F1)get r(): f(F2)private m(arg: f(U1)): f(M1)protect p(arg: f(U2)): f(M2)} | +| 抽象类 | abstract class A { ... } | abstract class A { ... } // 保留 abstract关键字，内部遵循相同的规则 | +| 继承类和override | class C extends A {override foo(arg: U1): M1} | class C extends A {override foo(arg: f(U1)): f(M1)} | +| 实现类 | class A implements Inface { ... } | class A implements Inface { ... } | + +#### 接口 + +TODO: 美化表格 + +| **类别** | **TS type (T)** | **1.2 type (f(T))** | +| -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| 普通接口 | interface A {field: F1m(arg: U1): M1get a(): Vset a(v: V): void} | interface A {field: f(F1)m(arg: f(U1)): f(M1)get a(): f(V)set a(v: f(V)): void} | +| 继承接口 | interface A extends B { ... } | interface A extends B { ... } | + +#### 枚举 + +| **类别** | **TS type (T)** | **1.2 type (f(T))** | +| ---------------- | ------------------------------------------------- | ------------------------------------ | +| 枚举值都为整数 | `enum Color {Blue = 0, Red = 1}` | `enum Color {Blue = 0, Red = 1}` | +| 枚举值都为字符串 | `enum Some {A = 'Alice', B = 'Bob'}` | `enum Some {A = 'Alice', B = 'Bob'}` | +| 其它枚举 | `enum Mix {One = 1, Msg = 'hello', Double = 1.2}` | `Any` | + +#### 装饰器 + +装饰器不能用于交互，映射为空（ArkUI定义的装饰器会被特殊处理，映射为ArkTS1.2的注解）。 + +#### 命名空间 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| -------------------- | -------------------- | +| `namespace NS {...}` | `namespace NS {...}` | + +#### 联合类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------------- | +| `T1 \| T2 \| T3` | `f(T1) \| f(T2) \| f(T3)` | + +#### 元组类型 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ----------------------- | +| `[T1, T2, T3]` | `[f(T1), f(T2), f(T3)]` | + +#### 类型别名 + +| **1.2 type (T)** | **1.1 type (f(T))** | +| ---------------- | ------------------- | +| `type alias = K` | `type alias = f(K)` | + +#### 其它类型 + +##### 字面量类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| ----------------------------- | ------------------- | +| `{name: string, age: number}` | `Any` | + +##### 调用签名 + +| **TS type (T)** | **1.2 type (f(T))** | +| ---------------------------- | ------------------- | +| `{ (arg: T1): R }` | `Any` | +| `interface X {(arg): T1: R}` | `Any` | + +##### 构造签名 + +| **TS type (T)** | **1.2 type (f(T))** | +| -------------------------------- | ------------------- | +| `{ new (arg: T1): R }` | `Any` | +| `interface X {new (arg): T1: R}` | `Any` | + +##### 索引签名 + +| **TS type (T)** | **1.2 type (f(T))** | +| ----------------------------- | ------------------- | +| `{ [index: T]: R }` | `Any` | +| `interface X {[index: T]: R}` | `Any` | + +##### 相交类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| --------------- | ------------------- | +| `T1 & T2` | `Any` | + +##### keyof + +| **TS type (T)** | **1.2 type (f(T))** | +| ------------------------------- | -------------------- | +| `type My = keyof T` | `type My = Any` | +| `interface X { props: keyof T}` | `Any` | + +##### typeof + +| **TS type (T)** | **1.2 type (f(T))** | +| ---------------- | ------------------- | +| `typeof someVar` | `Any` | + +##### 索引访问类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| ------------------- | ------------------- | +| `someArray[number]` | `Any` | + +例子： + +```typescript +// ts +MyArray = [{ name: "Alice", age: 15 }]; +export type Person = (typeof MyArray)[number]; + +// declaration in ArkTS 1.2 is +export type Person = Any; +``` + +##### 条件类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| ------------------- | ------------------- | +| `condition ? A : B` | `Any` | + +##### 映射类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| --------------- | ------------------- | +| `SomeType[Key]` | `Any` | + +示例如下： + +```typescript +// ts +export type A = { [K in keyof T]: T[K] }; + +// declaration in 1.2 is +export type A = Any; +``` + +##### 模板字面量类型 + +| **TS type (T)** | **1.2 type (f(T))** | +| -------------------------- | ------------------- | +| `...${SomeLiteralType}...` | `Any` | + +示例如下： + +```typescript +// ts +export type AB = "A" | "B"; +export type AllLocaleIDs = `${AB}_id`; + +// declaration in 1.2 is +export type AB = "A" | "B"; +export type AllLocaleIDs = Any; +``` diff --git a/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-concurrency-rules.md b/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-concurrency-rules.md new file mode 100644 index 0000000000000000000000000000000000000000..b87f4527c62dec8975e7563de70217f71441173a --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-concurrency-rules.md @@ -0,0 +1,369 @@ +# ArkTS1.2并发特性变更 + +本指南旨在讲述ArkTS新的并发特性和使用方法。 + +## 共享对象不添加装饰器@Sendable + +**规则：** arkts-limited-stdlib-no-sendable-decorator + +**级别：** error + +新增对象天然共享特性，不再依赖Sendable特性，无需添加@Sendable装饰器。 + +**ArkTS1.1** +```typescript +@Sendable +class A {} +``` + +**ArkTS1.2** +```typescript +class A {} +``` + +## 共享函数不添加装饰器@Concurrent + +**规则：** arkts-limited-stdlib-no-concurrent-decorator + +**级别：** error + +新增对象天然共享特性，不再依赖Concurrent特性，无需添加@Concurrent装饰器。 + +**ArkTS1.1** +```typescript +@Concurrent +function func() {} +``` + +**ArkTS1.2** +```typescript +function func() {} +``` + +## 不支持Worker + +**规则：** arkts-no-need-stdlib-worker + +**级别：** error + +内存天然共享，不需要基于Actor模型实现ThreadWorker。使用ArkTS1.2提供的新线程api-EAWorker。 + +**ArkTS1.1** +```typescript +import { worker } from '@kit.ArkTS'; + +const workerInstance: worker.ThreadWorker = new worker.ThreadWorker('entry/ets/workers/Worker.ets') +``` + +**ArkTS1.2** +```typescript +let eaw = new EAWorker(); +eaw.run(() => { + console.info("hello, eaworker!"); +}); + +eaw.join(); +``` + +## 共享模块不需要use shared修饰 + +**规则：** arkts-limited-stdlib-no-use-shared + +**级别：** error + +新增对象天然共享特性，无需添加use shared。 + +**ArkTS1.1** +```typescript +"use shared" +export function test() {} +``` + +**ArkTS1.2** +```typescript +export function test() {} +``` + +## 共享函数不需要use concurrent修饰 + +**规则：** arkts-limited-stdlib-no-use-concurrent + +**级别：** error + +新增对象天然共享特性，无需添加use concurrent。 + +**ArkTS1.1** +```typescript +function func() { +"use concurrent" +} +``` + +**ArkTS1.2** +```typescript +function func() {} +``` + +## 原生容器默认共享，不需要Sendable容器 + +**规则：** arkts-no-need-stdlib-sendable-containers + +**级别：** error + +新增对象天然共享特性，不再依赖Sendable特性。可直接使用ArkTS1.2原生容器，删除collections.前缀。 + +**ArkTS1.1** +```typescript +import { collections } from '@kit.ArkTS'; + +let array = new collections.Array(); +``` + +**ArkTS1.2** +```typescript +let array = new Array(); +``` + +## 内存默认共享，不提供ASON + +**规则：** arkts-no-need-stdlib-ason + +**级别：** error + +新增对象天然共享特性，不再依赖Sendable特性，ASON可直接更改为JSON，且删除ArkTSUtils.前缀。 + +**ArkTS1.1** +```typescript +import { collections } from '@kit.ArkTS'; +import { ArkTSUtils } from '@kit.ArkTS'; +let arr = new collections.Array(1, 2, 3); +let str = ArkTSUtils.ASON.stringify(arr); +console.info(str); +``` + +**ArkTS1.2** +```typescript +let arr = new Array(1, 2, 3); +let str = JSON.stringify(arr); +console.info(str); +``` + +## 内存默认共享，不提供SharedArrayBuffer + +**规则：** arkts-no-need-stdlib-sharedArrayBuffer + +**级别：** error + +新增对象天然共享特性，ArrayBuffer默认共享，不需要SharedArrayBuffer。 + +**ArkTS1.1** +```typescript +let sab: SharedArrayBuffer = new SharedArrayBuffer(20); +let int32 = new Int32Array(sab); +``` + +**ArkTS1.2** +```typescript +let sab: ArrayBuffer = new ArrayBuffer(20); +let int32 = new Int32Array(sab); +``` + +## 不提供isConcurrent接口 + +**规则：** arkts-limited-stdlib-no-support-isConcurrent + +**级别：** error + +新增对象天然共享特性，所有函数都是共享的，不需要提供isConcurrent。 + +**ArkTS1.1** +```typescript +@Concurrent +function test() {} +let result: Boolean = taskpool.isConcurrent(test); +``` + +**ArkTS1.2** +不支持isConcurrent接口。 + +## taskpool不需要import + +**规则：** arkts-limited-stdlib-no-import-concurrency + +**级别：** error + +taskpool实现基于ArkTS提供，不依赖其他模块，不再需要import。 + +**ArkTS1.1** +```typescript +import { taskpool } from '@kit.ArkTS'; + +@Concurrent +function test() {} + +taskpool.execute(test); +``` + +**ArkTS1.2** +```typescript +function test() {} +taskpool.execute(test); +``` + +## AsyncLock不需要import + +**规则：** arkts-limited-stdlib-no-import-concurrency + +**级别：** error + +AsyncLock实现基于ArkTS提供，不依赖其他模块，不再需要import，且不需要添加ArkTSUtils.locks.前缀。 + +**ArkTS1.1** +```typescript +import { ArkTSUtils } from '@kit.ArkTS' + +let lock: ArkTSUtils.locks.AsyncLock = new ArkTSUtils.locks.AsyncLock(); +``` + +**ArkTS1.2** +```typescript +let lock: AsyncLock = new AsyncLock(); +``` + +## process更名为StdProcess，且不需要import + +**规则：** arkts-change-process-to-StdProcess + +**级别：** error + +StdProcess实现基于ArkTS提供，不依赖其他模块，不再需要import。为避免占用process关键字，更名为StdProcess。 + +**ArkTS1.1** +```typescript +import { process } from '@kit.ArkTS'; + +let result = process.is64Bit(); +let pro = new process.ProcessManager(); +let pres = pro.getUidForName("tool"); +``` + +**ArkTS1.2** +```typescript +let result = StdProcess.is64Bit(); +let pro = new StdProcess.ProcessManager(); +let pres = pro.getUidForName("tool"); +``` + +## 移除taskpool setCloneList接口 + +**规则：** arkts-limited-stdlib-no-setCloneList + +**级别：** error + +内存默认共享，不需要提供setCloneList来拷贝传递对象。 + +**ArkTS1.1** +```typescript +let baseInstance1: BaseClass = new BaseClass(); +let array1 = new Array(); +array1.push(baseInstance1); +let task1 = new taskpool.Task(testFunc, array1, 10); +task1.setCloneList(array1); +``` + +**ArkTS1.2** +```typescript +let baseInstance1: BaseClass = new BaseClass(); +let array1 = new Array(); +array1.push(baseInstance1); +let task1 = new taskpool.Task(testFunc, array1, 10); +``` + +## 移除taskpool setTransferList接口 + +**规则：** arkts-limited-stdlib-no-setTransferList + +**级别：** error + +内存默认共享，不需要提供setTransferList来跨线程传递ArrayBuffer对象。 + +**ArkTS1.1** +```typescript +let buffer: ArrayBuffer = new ArrayBuffer(8); +let view: Uint8Array = new Uint8Array(buffer); +let buffer1: ArrayBuffer = new ArrayBuffer(16); +let view1: Uint8Array = new Uint8Array(buffer1); +let task: taskpool.Task = new taskpool.Task(testTransfer, view, view1); +task.setTransferList([view.buffer, view1.buffer]); +``` + +**ArkTS1.2** +```typescript +let buffer: ArrayBuffer = new ArrayBuffer(8); +let view: Uint8Array = new Uint8Array(buffer); +let buffer1: ArrayBuffer = new ArrayBuffer(16); +let view1: Uint8Array = new Uint8Array(buffer1); +let task: taskpool.Task = new taskpool.Task(testTransfer, view, view1); +``` + +## 删除ISendable接口 + +**规则：** arkts-no-need-stdlib-ISendable + +**级别：** error + +新增对象天然共享特性，无需实现ISendable接口。 + +**ArkTS1.1** +```typescript +import { lang } from '@kit.ArkTS'; + +@Sendable +class CustomData implements lang.ISendable { + data1: number; + data2: string; + constructor(data1: number, data2: string) { + this.data1 = data1; + this.data2 = data2; + } +} +``` + +**ArkTS1.2** +```typescript +class CustomData { + data1: number; + data2: string; + constructor(data1: number, data2: string) { + this.data1 = data1; + this.data2 = data2; + } +} +``` + +## 删除isSendable接口 + +**规则：** arkts-no-need-stdlib-isSendable + +**级别：** error + +新增对象天然共享特性，无需判断是否为Sendable数据类型。 + +**ArkTS1.1** +```typescript +import { ArkTSUtils } from '@kit.ArkTS' + +@Sendable +function sendableFunc() { + console.info("sendableFunc") +} + +if (ArkTSUtils.isSendable(sendableFunc)) { + console.info("sendableFunc is Sendable"); +} else { + console.info("sendableFunc is not Sendable"); +} +``` + +**ArkTS1.2** +内存共享，不需要判断是否为Sendable对象。 \ No newline at end of file diff --git a/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-interop-rules.md b/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-interop-rules.md new file mode 100644 index 0000000000000000000000000000000000000000..6e58384cdf586b6f419d4dccbeb4147ca68c20c7 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-interop-rules.md @@ -0,0 +1,2270 @@ +# ArkTS1.2与ArkTS1.1互操作规范 + +## ArkTS1.2导出ArkTS1.1实体 + +**规则：** arkts-interop-d2s-export-entity + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export function foo() {} +export class X {} +export interface Y {} + +// file2.ets +import { foo } from './file1'; +export { foo }; + +export { X, Y } from './file1'; +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.1 +export function foo() {} +export class X {} +export interface Y {} + +// file2.ets ArkTS1.2 +import { foo } from './file1'; +export { foo }; // 编译报错 + +export { X, Y } from './file2'; // 编译报错 +``` + +## ArkTS1.2判断ArkTS1.1 boxed type类型 + +**规则：** arkts-interop-d2s-boxed-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String('hello'); +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' + +//file2.ets +import { a, b, c } from './fiel1'; +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.2 +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String('hello'); +typeof a; // 'number' +typeof b; // 'boolean' +typeof c; // 'string' + +//file2.ets ArkTS1.1 +import { a, b, c } from './fiel1'; +typeof a; // 'number' +typeof b; // 'boolean' +typeof c; // 'string' +``` + +### ArkTS1.2使用ArkTS1.1的@Sendable和@Concurrent + +**规则：** arkts-interop-d2s-no-concurrent-decorators + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +@Sendable +class X {} + +@Concurrent +function foo() {} +``` + +**ArkTS1.2** +```typescript +// file1.ets +class X {} + +function foo() {} +``` + +### ArkTS1.1 Object内置方法作用在ArkTS1.2对象 + +**规则：** arkts-interop-d2s-dynamic-object-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export function foo(prx: ESValue) { + Object.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ["a"] + Object.hasOwn(prx, 'a'); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ["a"] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true + prx.propertyIsEnumerable('a'); // true +} + +// file2.ets +import { foo } from './file1'; +class X { + a = 1; +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// Object.keys的解决方案，与Object.values的情况类似 +// file0.ets ArkTS1.2 +export function getKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { + return Object.keys(prx); + } + return undefined; +} + +// file1.ets ArkTS1.1 +import { getKeys } from './file0'; +function myGetKeys(prx: ESValue) { + let ret = getKeys(prx); + if (ret == undefined) { + // prx is dynamic + return Object.keys(prx); + } + return ret; +} +export function foo(prx: Object) { + Object.getOwnPropertyDescriptor(prx, 'a'); // undefined + Object.getOwnPropertyDescriptors(prx); // {} + Object.getOwnPropertyNames(prx); // [] + Object.hasOwn(prx, 'a'); // false + Object.isExtensible(prx); // false + Object.isFrozen(prx); // true + Object.isSealed(prx); // true + Object.keys(prx); // [] + myGetKeys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // 运行时报错 + Object.values(prx); // [] + prx.hasOwnProperty('a'); // false + prx.propertyIsEnumerable('a'); // false +} + +// file2.ets ArkTS1.2 +import { foo } from './file1'; +class X { + a = 1; +} +foo(new X()); +``` + +### ArkTS1.1 Reflect内置方法作用在ArkTS1.2对象 + +**规则：** arkts-interop-d2s-dynamic-reflect-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +import { foo } from './file1'; +export class X { + a: string = 'hello'; + getName() { + return this.a; + } +} + +// file2.ets +import { X } from './file1'; +function foo(prx: ESValue) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, 'newField', { value: 7 }); // true + Reflect.deleteProperty(prx, 'a'); // true + Reflect.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, 'newField', 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// static ownKeys的解决方案 +// file0.ets ArkTS1.2 +export getOwnKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { return Reflect.ownKeys(prx) } + return undefined +} + +// file1.ets ArkTS1.1 +import { getOwnKeys } from './file0' +export function myOwnKeys(prx: ESValue) { + let ret = getOwnKeys(prx) + if (ret == undefined) { // prx是动态对象 + return Reflect.ownKeys(prx) + } + return ret +} + +export function foo(prx: ESValue) { + Reflect.apply(prx.getName, { a: 12 }) // 运行时报错 + Reflect.defineProperty(prx, 'newField', { value: 7 }) // false + Reflect.deleteProperty(prx, "a") // false + Reflect.getOwnPropertyDescriptor(prx, "a") // undefined + Reflect.ownKeys(prx) // [] + myOwnKeys(prx) // ['a'] + Reflect.isExtensible(prx) // false + Reflect.set(prx, 'newField', 7) // false + Reflect.setPrototypeOf(prx, {}) // false +} + +// file2.ets ArkTS1.2 +import { foo } from './file1' +export class X { + a: string = 'hello' + getName() { return this.a } +} +foo(new X()) +``` + +### ArkTS1.2 Object内置方法作用在ArkTS1.2对象 + +**规则：** arkts-interop-d2s-static-object-on-dynamic-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export class X { + a = 1; +} + +// file2.ets +import { X } from 'file1'; +export function foo(prx: Object) { + Object.assign({}, prx); // OK + Object.entries(prx); // [a, 1] + Object.keys(prx); // ["a"] + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.1 +export class X { + a = 1; +} + +// file2.ets ArkTS 1.2 +import { X } from 'file1'; +export function foo(prx: Object) { + Object.assign({}, prx); // OK + Object.entries(prx); // [a, 1] + Object.keys(prx); // ["a"] + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true +} +foo(new X()); // 编译报错 +``` + +### 1.2 Reflect内置方法作用在ArkTS1.1对象 + +**规则：** arkts-interop-d2s-static-reflect-on-dynamic-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets ArkTS1.1 +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} + +// file2.ets ArkTS1.2 +import { X } from './file1'; +export function foo(prx: Object) { + Reflect.get(prx, 'a'); // 'hello' + Reflect.set(prx, 'a', 'world'); // true + Reflect.ownKeys(prx); // ['a'] +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.1 +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} + +// file2.ets ArkTS1.2 +import { X } from './file1'; +export function foo(prx: Object) { + Reflect.get(prx, 'a'); // 'hello' + Reflect.set(prx, 'a', 'world'); // true + Reflect.ownKeys(prx); // ['a'] +} +foo(new X()); // 编译报错 +``` + +### ArkTS1.2动态导入ArkTS1.1 + +**规则：** arkts-interop-d2s-dynamic-import + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export class A {} + +// file2.ets +let mod = await import('./file1'); +let A: ESValue = mod.A; +let a = new A() as A; + +// 动态导入class、function、enum变量 +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.1 +export class A {} + +// file2.ets ArkTS1.2 +let mod = ESValue.load('./file1'); +let A: ESValue = mod.getProperty('A'); +let a = A.instantiate() as A; +``` + +### ArkTS1.2创建ArkTS1.1的没有无参构造函数的类的对象字面量 + +**规则：** arkts-interop-d2s-object-literal-no-args-constructor + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export class X { + name: string; + constructor(arg: string) { + this.name = arg; + } +} +// file2.ets +import { X } from './file1'; +let x: X = { name: 'hello' }; +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.1 +export class X { + name: string; + constructor(arg: string) { + this.name = arg; + } +} +// file2.ets ArkTS1.2 +import { X } from './file1'; +let x: X = { name: 'hello' }; // 编译报错 +``` + +### ArkTS1.2创建ArkTS1.1具有二义性的对象字面量 + +**规则：** arkts-interop-d2s-object-literal-no-ambiguity + +**级别：** error + +当一个对象的类型被声明为联合类型，而右侧实际赋值的是一个类的实例时，会引发类型系统的二义性（对象可以是联合类型的任一类型，但实际运行时明确是一个类的实例，这种差异会导致类型检查或运行时的不确定性）。 + +**ArkTS1.1** +```typescript +// file1.ets +export class X { + name: string = ''; +} +export interface Y { + name: string; + age?: number; +} + +// file2.ets +import { X, Y } from './file1'; +let x: X | Y = { name: 'hello' }; +``` + +**ArkTS1.2** +```typescript +// file1.ets // 1.0 +export class X { + name: string = ''; +} +export interface Y { + name: string; + age?: number; +} + +// file2.ets // 1.2 +import { X, Y } from './file1'; +let x: X | Y = { name: 'hello' }; // 编译报错 +``` + +### ArkTS1.2创建ArkTS1.1的类的对象字面量 + +**规则：** arkts-interop-d2s-object-literal + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export class A { + name: string = ''; +} + +// file2.ets +import { A } from './file1'; +let a: A = { name: 'hello' }; // a是创建的对象自变量 + +a instanceof A; // false +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.1 +export class A { + name: string = ''; +} + +// file2.ets ArkTS1.2 +import { A } from './file1'; +let a: A = { name: 'hello' }; // a是创建的对象 + +a instanceof A; // true +``` + +### ArkTS1.1判断ArkTS1.2 boxed类型 + +**规则：** arkts-interop-s2d-boxed-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String('hello'); +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' + +//file2.ets +import { a, b, c } from './fiel1'; +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.2 +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String('hello'); +typeof a; // 'number' +typeof b; // 'boolean' +typeof c; // 'string' + +//file2.ets ArkTS1.1 +import { a, b, c } from './fiel1'; +typeof a; // 'number' +typeof b; // 'boolean' +typeof c; // 'string' +``` + +### ArkTS1.1创建ArkTS1.2对象字面量 + +**规则：** arkts-interop-s2d-object-literal + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export class X { + name: string = ''; + constructor(arg: string) { + this.name = arg; + } +} +export interface Y { + data: number; +} +export type MyRecord = Record; +export function foo(arg: X) {} +export function bar(arg: Y) {} + +// file2.ets +import { X, Y } from './file1'; +let x: X = { name: 'hello' }; +let y: Y = { data: 123 }; +foo({ name: 'world' }); +bar({ data: 456 }); +// 返回值 zoo(): X { return {..}} +// 嵌套场景 +interface Z { + x: X; +} +let z: Z = { x: { name: 'hello' } }; +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.2 +export class X { name: string = '' } +export interface Y { data: number } +export function foo(arg: X) { } +export function bar(arg: Y) { } +export createY(d: number): Y { + let y: Y = { data: d } + return y +} + +// file2.ets ArkTS1.1 +import { X, Y, createY } from "./file1" +let x: X = new X("hello") +let y: Y = createY(123) +foo(new X("world")) +bar(createY(456)) +``` + +### ArkTS1.1传参或赋值给ArkTS1.2 + +**规则：** arkts-interop-s2d-dynamic-args-to-static + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export function foo(obj: Object) {} +export class A { + data: Object = 0; +} + +// file2.ets +import { foo, A } from './file1'; + +class X {} +foo(new X()); +interface Y { + s: string; +} +let y: Y = { s: 'Hi' }; +let a = new A(); +a.data = y; +// 动态对象的来源：class/interface/对象字面量 +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.2 +export function foo(obj: Object) {} +// solution: export function foo(obj: ESValue | Object) {} +export class A { + data: Object = 0; +} +// solution: export class A { data: ESValue = ESValue.wrap(0) } + +// file2.ets ArkTS1.1 +import { foo, A } from './file1'; + +class X {} +foo(new X()); // 运行时报错 +interface Y { + s: string; +} +let y: Y = { s: 'Hi' }; +let a = new A(); +a.data = y; // 运行时报错 +``` + +### ArkTS1.1Object内置方法作用在ArkTS1.2对象 + +**规则：** arkts-interop-s2d-dynamic-object-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file2.ets +export class X { + a = 1; +} + +// file1.ets +import { X } from './file2'; +function foo(prx: Object) { + Object.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ["a"] + Object.hasOwn(prx, 'a'); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ["a"] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true + prx.propertyIsEnumerable('a'); // true +} + +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file2.ets ArkTS1.2 +export class X { + a = 1; +} +// Object.keys的解决方案，与Object.values的情况类似 +export function getKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { + return Object.keys(prx); + } + return undefined; +} +// file1.ets ArkTS1.1 +import { X, getKeys } from './file2'; +function myGetKeys(prx: Object) { + let ret = getKeys(prx); + if (ret == undefined) { + // prx is dynamic + return Object.keys(prx); + } + return ret; +} +export function foo(prx: Object) { + Object.getOwnPropertyDescriptor(prx, 'a'); // undefined + Object.getOwnPropertyDescriptors(prx); // {} + Object.getOwnPropertyNames(prx); // [] + Object.hasOwn(prx, 'a'); // false + Object.isExtensible(prx); // false + Object.isFrozen(prx); // true + Object.isSealed(prx); // true + Object.keys(prx); // [] + myGetKeys(prx); // ['a'] + Object.setPrototypeOf(prx, {}); // 运行时报错 + Object.values(prx); // [] + prx.hasOwnProperty('a'); // false + prx.propertyIsEnumerable('a'); // false +} + +foo(new X()); +``` + +### ArkTS1.1 Reflect内置方法作用在ArkTS1.2对象 + +**规则：** arkts-interop-s2d-dynamic-reflect-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file2.ets +export class X { + a: string = 'hello'; + getName() { + return this.a; + } +} + +// file1.ets +import { X } from './file2'; +function foo(prx: Object) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, 'newField', { value: 7 }); // true + Reflect.deleteProperty(prx, 'a'); // true + Reflect.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, 'newField', 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} + +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file2.ets ArkTS1.2 +export class X { + a: string = 'hello' + getName() { return this.a } +} + +// static ownKeys的解决方案 +export getOwnKeys(prx: Object | ESValue): string[] | undefined { + if (prx instanceof Object) { return Reflect.ownKeys(prx) } + return undefined +} + +// file1.ets ArkTS1.1 +import { X, getOwnKeys } from "./file2" +function myOwnKeys(prx: Object) { + let ret = getOwnKeys(prx) + if (ret == undefined) { // prx is dynamic + return Reflect.ownKeys(prx) + } + return ret +} + +function foo(prx: Object) { + Reflect.apply(prx.getName, { a: 12 }) // 运行时报错 + Reflect.defineProperty(prx, 'newField', { value: 7 }) // false + Reflect.deleteProperty(prx, "a") // false + Reflect.getOwnPropertyDescriptor(prx, "a") // undefined + Reflect.ownKeys(prx) // [] + myOwnKeys(prx) // ['a'] + Reflect.isExtensible(prx) // false + Reflect.set(prx, 'newField', 7) // false + Reflect.setPrototypeOf(prx, {}) // false +} + +foo(new X()) +``` + +### ArkTS1.2 Object内置方法作用在ArkTS1.1对象 + +**规则：** arkts-interop-s2d-static-object-on-dynamic-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export function foo(prx: Object) { + Object.assign({}, prx); // OK + Object.entries(prx); // [a, 1] + Object.keys(prx); // ["a"] + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true +} + +// file2.ets +import { foo } from './file1'; +class X { + a = 1; +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.2 +export function foo(prx: Object) { + Object.assign({}, prx); // OK + Object.entries(prx); // [a, 1] + Object.keys(prx); // ["a"] + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true +} + +// file2.ets ArkTS1.1 +import { foo } from './file1'; +class X { + a = 1; +} +foo(new X()); // 运行时报错 +``` + +### ArkTS1.2 Reflect内置方法作用在ArkTS1.1对象 + +**规则：** arkts-interop-s2d-static-reflect-on-dynamic-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ets +export function foo(prx: Object) { + Reflect.get(prx, 'a'); // 'hello' + Reflect.set(prx, 'a', 'world'); // true + Reflect.ownKeys(prx); // ['a'] +} + +// file2.ets +import { foo } from './file1'; +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS1.2 +export function foo(prx: Object) { + Reflect.get(prx, 'a'); // 'hello' + Reflect.set(prx, 'a', 'world'); // true + Reflect.ownKeys(prx); // ['a'] +} + +// file2.ets ArkTS1.1 +import { foo } from './file1'; +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} +foo(new X()); // 运行时报错 +``` + +### ArkTS1.1代码调用ArkTS1.2中废弃的方法 + +**规则：** arkts-interop-s2d-dynamic-call-builtin-api-not-in-static + +**级别：** error + +在ArkTS1.1代码中导入ArkTS1.2的Builtin类型对象，并调用一个在ArkTS1.2版本中已被移除（但在1.1中仍存在）的方法，导致潜在的兼容性问题出现。 + +**ArkTS1.1** +```typescript +// file1.ets ArkTS 1.1 +let arr: Array = new Array(1, 2, 3); +export arr1; + +// file2.ets ArkTS 1.1 +import {arr} from "./file1" + +class C { +base: number; +constructor(base:number) { +this.base = base; +} +compare(value: number, index: number, arr: Array) { +return value >= this.base +} +} +let a = new C(2); +let b = new C(3); +arr.find(a.compare, a) // Result: 2 +arr.find(a.compare, b) // Result: 3 +``` + +**ArkTS1.2** +```typescript +// file1.ets ArkTS 1.1 +let arr: Array = new Array(1, 2, 3); +export arr1; + +// file2.ets ArkTS 1.1 +import {arr} from "./file1" + +class C { +base: number; +constructor(base:number) { +this.base = base; +} +compare(value: number, index: number, arr: Array) { +return value >= this.base +} +} +let a = new C(2); +let b = new C(3); +arr.find(a.compare, a) // 运行时报错 +arr.find(a.compare, b) // 运行时报错 +``` + +### ArkTS1.2使用TS装饰器 + +**规则：** arkts-interop-ts2s-no-ts-decorator + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export function MyClassDecorator(klass: Object) {} + +// file2.ets +import { MyClassDecorator } from './file1'; +@MyClassDecorator +class K {} +``` + +**ArkTS1.2** +```typescript +NA; +``` + +### ArkTS1.2访问TS独有类型的实体 + +**规则：** arkts-interop-ts2s-static-access-ts-type + +TS独有类型包括如下类型： +- any +- unknown +- symbol +- Function +- object literal （例如 {x: number, y: string}） +- mixing enum （例如 enum X {a = 0, b = '1'}） +- call signature （例如 {(arg: number): string}） +- constructor signature （例如 {new(): Object}） +- index signature （例如 {[index: number]: string}） +- intersection （例如 TypeA & TypeB） +- keyof （例如 interface X { props: keyof T}） +- typeof（例如 let p = {x: 1, y: ''}, let q: typeof p） +- indexed access type（例如 MyArray = [{ name: "Alice", age: 15 }] type Person = typeof MyArray[number]） +- conditional types （例如 type Swap = T extends A ? B : A） +- mapped types （例如 type A = {[K in keyof T]: T[K]}） +- template literal types （例如 type AB = "A" | "B", type AllLocaleIDs = `${AB}_id`） +- Pick +- Omit +- Exclude +- Extract +- NonNullable +- Parameters +- ConstructorParameters +- ReturnType +- InstanceType +- NoInfer +- ThisParameterType +- OmitThisParameter +- ThisType +- Uppercase +- Lowercase +- Capitalize +- Uncapitalize + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export let obj: SomeType; // SomeType是某个TS独有类型 + +// file2.ets +import { obj } from './file1'; +let val = obj.prop; +obj.prop = 1; +obj.foo(); +let item = obj[0]; +``` + +**ArkTS1.2** +```typescript +// file1.ts +export let obj: SomeType; +// 从ArkTS1.2看来，这个声明为 +// export let obj: ESValue + +// file2.ets ArkTS1.2 +import { obj } from './file1'; +obj.setProperty('prop', ESValue.wrap(1)); +``` + +### Object内置方法作用在ArkTS对象 + +**规则：** arkts-interop-ts2s-ts-object-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export function foo(prx: any) { + Object.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ["a"] + Object.hasOwn(prx, 'a'); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ["a"] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true + prx.propertyIsEnumerable('a'); // true +} + +// file2.ets +import { foo } from './file1'; +class X { + a = 1; +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.ts +export function foo(prx: any) { +Object.getOwnPropertyDescriptor(prx, "a") // undefined +Object.getOwnPropertyDescriptors(prx) // {} +Object.getOwnPropertyNames(prx) // [] +Object.getOwnPropertySymbols(prx)) // [] +Object.hasOwn(prx, "a") // false +Object.isExtensible(prx) // false +Object.isFrozen(prx) // true +Object.isSealed(prx) // true +Object.keys(prx) // [] +Object.setPrototypeOf(prx, {}) // 运行时报错 +Object.values(prx) // [] +prx.hasOwnProperty("a") // false +prx.propertyIsEnumerable("a") // false +} + +// file2.ets +import {foo} from "./file1" +class X { a = 1 } +foo(ESValue.wrap(new X())) +``` + +### Reflect内置方法作用在ArkTS对象 + +**规则：** arkts-interop-ts2s-ts-reflect-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export function foo(prx: any) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, 'newField', { value: 7 }); // true + Reflect.deleteProperty(prx, 'a'); // true + Reflect.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, 'newField', 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} + +// file2.ets +import { foo } from './file1'; +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.ts +export function foo(prx: any) { + Reflect.apply(prx.getName, { a: 12 }); // 运行时报错 + Reflect.defineProperty(prx, 'newField', { value: 7 }); // false + Reflect.deleteProperty(prx, 'a'); // false + Reflect.getOwnPropertyDescriptor(prx, 'a'); // undefined + Reflect.ownKeys(prx); // [] + Reflect.isExtensible(prx); // false + Reflect.set(prx, 'newField', 7); // false + Reflect.setPrototypeOf(prx, {}); // false +} + +// file2.ets +import { foo } from './file1'; +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} +foo(ESValue.wrap(new X())); +``` + +### ArkTS处理TS非常规异常 + +**规则：** arkts-interop-ts2s-ts-exception + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export function foo() { + throw 123; +} + +// file2.ets +import { foo } from './file1'; + +try { + foo(); +} catch (e) { + console.log(e as number); // 123 +} +``` + +**ArkTS1.2** +```typescript +// file1.ts +export function foo() { + throw 123; +} + +// file2.ets // ArkTS1.2 +import { foo } from './file1'; + +try { + foo(); +} catch (e) { + let err: ESValue = (e as ESError).getValue(); + err.toNumber(); // 123 +} +``` + +### ArkTS1.2判断ArkTS1.1 boxed type类型 + +**规则：** arkts-interop-ts2s-boxed-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String('hello'); +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' + +//file2.ets +import { a, b, c, d, e } from './fiel1'; +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' +``` + +**ArkTS1.2** +```typescript +// file1.ts +export let a = new Number(123); +export let b = new Boolean(true); +export let c = new String('hello'); +typeof a; // 'object' +typeof b; // 'object' +typeof c; // 'object' + +//file2.ets ArkTS1.2 +import { a, b, c, d, e } from './fiel1'; +typeof a; // 'number' +typeof b; // 'boolean' +typeof c; // 'string' +``` + +### ArkTS1.2动态导入TS + +**规则：** arkts-interop-ts2s-dynamic-import-ts + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export class A {} + +// file2.ets +let mod = await import('./file1'); +let A: ESValue = mod.A; +let a = new A() as A; +``` + +**ArkTS1.2** +```typescript +// file1.ets ts +export class A {} + +// file2.ets ArkTS1.2 +let mod = ESValue.load('./file1'); +let A: ESValue = mod.getProperty('A'); +let a = A.instantiate() as A; +``` + +### ArkTS1.2创建TS的类的对象字面量 + +**规则：** arkts-interop-ts2s-object-literal + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.ts +export class A { + name: string = ''; +} + +// file2.ets +import { A } from './file1'; +let a: A = { name: 'hello' }; + +a instanceof A; // false +``` + +**ArkTS1.2** +```typescript +// file1.ts +export class A { + name: string = ''; +} + +// file2.ets ArkTS1.2 +import { A } from './file1'; +let a: A = { name: 'hello' }; + +a instanceof A; // true +``` + +### ArkTS1.2导入js文件 + +**规则：** arkts-interop-js2s-import-js + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo() {} + +// file2.ets +import { foo } from './file1'; +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo() {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +``` + +### ArkTS导出js实体 + +**规则：** arkts-interop-js2s-export-js + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo() {} +export class A {} + +// file2.ets +import { foo } from './file1'; +export { foo }; + +export { A } from './file1'; + +// 函数、类、变量、枚举 +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo() {} +export class A {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let A = mod.getProperty('A'); + +export { foo, A }; +``` + +### ArkTS调用js函数和传参 + +**规则：** arkts-interop-js2s-call-js-func + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo() {} +export function bar(a) {} + +// file2.ets +import { foo, bar } from './file1'; +foo(); +bar(123); +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo() {} +export function bar(a) {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let bar = mod.getProperty('bar'); +foo.invoke(); +bar.invoke(ESValue.wrap(123)); +``` + +### ArkTS实例化js对象 + +**规则：** arkts-interop-js2s-create-js-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +class foo { + constructor(a) {} +} +// file2.ets +import { foo } from './file1'; +new foo(123); +``` + +**ArkTS1.2** +```typescript +// file1.js +class foo { + constructor(a) {} +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +foo.instantiate(ESValue.wrap(123)); +``` + +### ArkTS访问js属性 + +**规则：** arkts-interop-js2s-access-js-prop + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { name: '123' }; +// file2.ets +import { foo } from './file1'; +foo.name; +foo.name = '456'; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = {name: "123"} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let foo = mod.getProperty('foo') +foo.getProperty('name') +foo.setProperty('name', ESValue.wrap("456")） +``` + +### ArkTS调用js方法和传参 + +**规则：** arkts-interop-js2s-call-js-method + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +class Foo { + bar(a) {} +} +export let foo = new Foo(); +// file2.ets +import { foo } from './file1'; +foo.bar(123); +``` + +**ArkTS1.2** +```typescript +// file1.js +class Foo { + bar(a) {} +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +foo.invokeMethod('bar', ESValue.wrap(123)); +``` + +### ArkTS访问js索引 + +**规则：** arkts-interop-js2s-access-js-index + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { arr: [1, 2, 3] }; +// file2.ets +import { foo } from './file1'; +let arr = foo.arr; +arr[1]; +arr[3] = 4; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = [1, 2, 3]; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let arr = foo.getProperty('arr'); +arr.getProperty(1); +arr.setProperty(3, ESValue.wrap(4)); +``` + +### ArkTS转换js对象类型 + +**规则：** arkts-interop-js2s-convert-js-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo1 = { num: 123 }; +export let foo2 = { bool: true }; +export let foo3 = { str: '123' }; +export let foo4 = { big: 123n }; + +// file2.ets +import { foo } from './file1'; +let a: number = foo1.num as number; +let a: boolean = foo2.bool as boolean; +let a: string = foo3.str as string; +let a: bigint = foo4.big as bigint; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo1 = { num: 123 }; +export let foo2 = { bool: true }; +export let foo3 = { str: '123' }; +export let foo4 = { big: 123n }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo1 = mod.getProperty('foo1'); +let num = foo.getProperty('num'); +let a1: number = num.toNumber(); + +let foo2 = mod.getProperty('foo2'); +let bool = foo.getProperty('bool'); +let a2: boolean = bool.toBoolean(); + +let foo3 = mod.getProperty('foo3'); +let str = foo3.getProperty('str'); +let a3: string = str.toString(); + +let foo4 = mod.getProperty('foo4'); +let big = foo.getProperty('big'); +let a4: bigint = big.toBigInt(); +``` + +### ArkTS获取js对象类型 + +**规则：** arkts-interop-js2s-typeof-js-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { num: 123 }; + +// file2.ets +import { foo } from './file1'; +typeof foo.num; // 'number' +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = 123; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let num = foo.getProperty('num'); + +num.typeOf(); // 'number' +``` + +### ArkTS判断js对象类型 + +**规则：** arkts-interop-js2s-instanceof-js-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export class Foo {} +export let foo = new Foo(); + +// file2.ets +import { Foo, foo } from './file1'; +foo instanceof Foo; +``` + +**ArkTS1.2** +```typescript +// file1.js +export class Foo {} +export let foo = new Foo(); + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let Foo = mod.getProperty('Foo'); +let foo = mod.getProperty('foo'); + +foo.isInstanceOf(Foo); +``` + +### ArkTS对js对象自增自减 + +**规则：** arkts-interop-js2s-self-addtion-reduction + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { num: 0 }; + +// file2.ets +import { foo } from './file1'; +let a: number = 0; +a = foo.num++; +a = ++foo.num; +a = foo.num--; +a = --foo.num; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = { num: 0 }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let a: number = 0; + +// a = foo.num++ +let num = foo.getProperty('num'); +let tmp: number = num.toNumber(); +a = tmp; +foo.setProperty('num', ESValue(tmp + 1)); + +// a = ++foo.num + +num = foo.getProperty('num'); +tmp = num.toNumber() + 1; +foo.setProperty('num', ESValue(tmp)); +a = tmp; + +// the cases "foo.num--" and "--foo.num" are similar +``` + +### ArkTS对js对象进行一元运算 + +**规则：** arkts-interop-js2s-binary-op + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { num: 0 }; +// file2.ets +import { foo } from './file1'; ++foo.num - foo.num; +!foo.num; +~foo.num; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = { num: 0 }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let num = + foo.getProperty('num') + + // +foo.num + num.toNumber() - + // -foo.num + num.toNumber(); +// !foo.num +!num.toNumber(); +// ~foo.num +~num.toNumber(); +``` + +### ArkTS对js对象进行二元运算 + +**规则：** arkts-interop-js2s-await-js-promise + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { a: 1, b: 2 }; + +// file2.ets +import { foo } from './file1'; +let a = foo.a; +let b = foo.b; +a + b; +a - b; +a * b; +a / b; +a % b; +a ** b; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = { a: 1, b: 2 }; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let a = foo.getProperty('a').toNumber(); +let b = foo.getProperty('b').toNumber(); +a + b; +a - b; +a * b; +a / b; +a % b; +a ** b; +``` + +### ArkTSawait js Promise对象 + +**规则：** arkts-interop-js2s-compare-js-data + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +async function foo(){} +export p = foo() + +// file2.ets +import {p} from "./file1" +async function bar() { + await p +} +``` + +**ArkTS1.2** +```typescript +// file1.js +async function foo(){} +export p = foo() + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let p = mod.getProperty('p') + +async function bar() { + await p.toPromise() +} +``` + +### ArkTS对js数据进行比较 + +**规则：** arkts-interop-js2s-equality-judgment + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { a: 1, b: 2 }; + +// file2.ets +import { foo } from './file1'; +let a = foo.a; +let b = foo.b; +a > b; +a < b; +a >= b; +a <= b; +``` + +**ArkTS1.2** +```typescript +// file1.js +export let a = 1; +export let b = 2; + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let a = foo.getProperty('a').toNumber(); +let b = foo.getProperty('b').toNumber(); + +a > b; +a < b; +a >= b; +a <= b; +``` + +### ArkTS对js数据进行相等判断 + +**规则：** arkts-interop-js2s-condition-judgment + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +class A {} +export let a = new A(); +export let b = new A(); + +// file2.ets +import { a, b } from './file1'; +a == b; +a != b; +a === b; +a !== b; +``` + +**ArkTS1.2** +```typescript +// file1.js +class A {} +export let a = new A(); +export let b = new A(); + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let a = mod.getProperty('a'); +let b = mod.getProperty('b'); + +a.areEqual(b); +!a.areEqual(b); +a.areStrictlyEqual(b); +!a.areStrictlyEqual(b); +``` + +### ArkTS对js对象进行条件判断 + +**规则：** arkts-interop-js2s-inherit-js-class + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { isGood: true }; + +// file2.ets +import { foo } from './file1'; + +if (foo.isGood) {} +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = { isGood: true }; + +// file2.ets +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); + +let isGood = foo.getProperty('isGood').toBoolean(); +if (isGood) {} +``` + +### ArkTS继承js的类 + +**规则：** arkts-interop-js2s-js-exception + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export class A {} + +// file2.ets +import { A } from './file1'; +class B extends A {} +let b = new B(); +``` + +**ArkTS1.2** +```typescript +// file1.js +export class A {} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let A = mod.getProperty('A'); + +let B: ESValue = ESValue.defineClass('B', () => {}, undefined, undefined, A); +let b = B.instantiate(); +``` + +### ArkTS处理js非常规异常 + +**规则：** arkts-interop-js2s-boxed-type + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo() { + throw 123; +} + +// file2.ets +import { foo } from './file1'; + +try { + foo(); +} catch (e) { + console.log(e as number); //123 +} +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo() { + throw 123; +} + +// file2.ets +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); + +try { + foo.invoke(); +} catch (e) { + let err: ESValue = (e as ESError).getValue(); + err.toNumber(); // 123 +} +``` + +### ArkTS访问js的boxed对象 + +**规则：** arkts-interop-js2s-traverse-js-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { + num: new Number(123), + bool: new Boolean(true), + str: new String('hello'), +}; + +// file2.ets +import { foo } from './file1'; +typeof foo.num; // 'object' +typeof foo.bool; // 'object' +typeof foo.str; // 'object' +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = { + num: new Number(123), + bool: new Boolean(true), + str: new String('hello'), +}; + +// file2.ets +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); + +foo.getProperty('num').typeOf(); // 'number' +foo.getProperty('bool').typeOf(); // 'boolean' +foo.getProperty('str').typeOf(); // 'string' +``` + +### ArkTS遍历js对象 + +**规则：** arkts-interop-js2s-js-call-static-func + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export let foo = { arr: [1, 2, 3] }; +// file2.ets +import { foo } from './file1'; +let arr = foo.arr; +let len = arr.length as number; +for (let i = 0; i < len; ++i) { + arr[i] as number; + arr[i] = 0; +} +``` + +**ArkTS1.2** +```typescript +// file1.js +export let foo = { arr: [1, 2, 3] }; + +// file2.ets ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +let arr = foo.getProerptyByName('arr'); +let len = arr.getProerptyByName('length').toNumber(); +for (let i = 0; i < len; ++i) { + arr.getProperty(i).toNumber(); + arr.setProperty(i, ESValue.wrap(0)); +} +``` + +### js调用ArkTS函数和传参 + +**规则：** arkts-interop-js2s-js-add-delete-static-prop + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function handle(cb) { + let p = { name: 'hello' }; + cb(p); +} + +// file2.ets +import { handle } from './file1'; +interface Person { + name: string; +} + +function foo(p: Person) {} +let lambda = (p: Person) => {}; + +handle(foo); +handle(lambda); +``` + +**ArkTS1.2** +```typescript +// file1.js +export function handle(cb) { + let p = { name: 'hello' }; + cb(p); +} + +// file2.ets +let mod = ESValue.load('./file1'); +let handle = mod.getProperty('handle'); +interface Person { + name: string; +} +function foo(p: Person) {} +// solution: function foo(p: ESValue) {} +let lambda = (p: Person) => {}; +// solution: let lambda = (p: ESValue) => {} + +handle.invoke(ESValue.wrap(foo)); +handle.invoke(ESValue.wrap(lambda)); +``` + +### js增删改ArkTS对象属性 + +**规则：** arkts-interop-js2s-js-add-delete-static-prop + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo(obj) { + obj.newField = 1; // 增加属性 + delete obj.data; // 删除属性 + obj.name = '123'; // 修改属性值（同类型） + obj.name = { firstName: '456' }; // 修改属性值（不同类型） +} + +// file2.ets +import { foo } from './file1'; +class X { + name: string = ''; + data: number = 0; +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo(obj) { + obj.newField = 1; // 增加属性 运行时报错 + delete obj.data; // 删除属性 运行时报错 + obj.name = '123'; // 修改属性值（同类型）OK + obj.name = { firstName: '456' }; // 修改属性值（不同类型）运行时报错 +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +class X { + name: string = ''; + data: number = 0; +} +foo.invoke(ESValue.wrap(new X())); +``` + +### js Object内置方法作用在ArkTS对象 + +**规则：** arkts-interop-js2s-js-object-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo(prx) { + Object.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Object.getOwnPropertyDescriptors(prx); // not {} + Object.getOwnPropertyNames(prx); // ["a"] + Object.hasOwn(prx, 'a'); // true + Object.isExtensible(prx); // true + Object.isFrozen(prx); // false + Object.isSealed(prx); // false + Object.keys(prx); // ["a"] + Object.setPrototypeOf(prx, {}); // OK + Object.values(prx); // [1] + prx.hasOwnProperty('a'); // true + prx.propertyIsEnumerable('a'); // true +} + +// file2.ets +import { foo } from './file1'; +class X { + a = 1; +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo(prx) { +Object.getOwnPropertyDescriptor(prx, "a") // undefined +Object.getOwnPropertyDescriptors(prx) // {} +Object.getOwnPropertyNames(prx) // [] +Object.getOwnPropertySymbols(prx)) // [] +Object.hasOwn(prx, "a") // false +Object.isExtensible(prx) // false +Object.isFrozen(prx) // true +Object.isSealed(prx) // true +Object.keys(prx) // [] +Object.setPrototypeOf(prx, {}) // 运行时报错 +Object.values(prx) // [] +prx.hasOwnProperty("a") // false +prx.propertyIsEnumerable("a") // false +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let foo = mod.getProperty('foo') +class X { a = 1 } +foo.invoke(ESValue.wrap(new X())) +``` + +### js Reflect内置方法作用在ArkTS对象 + +**规则：** arkts-interop-js2s-js-reflect-on-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo(prx) { + Reflect.apply(prx.getName, { a: 12 }); // 12 + Reflect.defineProperty(prx, 'newField', { value: 7 }); // true + Reflect.deleteProperty(prx, 'a'); // true + Reflect.getOwnPropertyDescriptor(prx, 'a'); // not undefined + Reflect.ownKeys(prx); // ['a'] + Reflect.isExtensible(prx); // true + Reflect.set(prx, 'newField', 7); // true + Reflect.setPrototypeOf(prx, {}); // true +} + +// file2.ets +import { foo } from './file1'; +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} +foo(new X()); +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo(prx) { + Reflect.apply(prx.getName, { a: 12 }); // 运行时报错 + Reflect.defineProperty(prx, 'newField', { value: 7 }); // false + Reflect.deleteProperty(prx, 'a'); // false + Reflect.getOwnPropertyDescriptor(prx, 'a'); // undefined + Reflect.ownKeys(prx); // [] + Reflect.isExtensible(prx); // false + Reflect.set(prx, 'newField', 7); // false + Reflect.setPrototypeOf(prx, {}); // false +} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1'); +let foo = mod.getProperty('foo'); +class X { + a: string = 'hello'; + getName() { + return this.a; + } +} +foo.invoke(ESValue.wrap(new X())); +``` + +### js对ArkTS对象进行展开语法 + +**规则：** arkts-interop-js2s-js-expand-static-instance + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export function foo(obj) { +let x = {...obj} // x会是{ a = 1; b = 2; c = 3 } +let {a, b, ...rest} = obj // a会是1, b会是2, rest会是{c: 3} + +// file2.ets +import {foo} from "./file1" +class X { a = 1; b = 2; c = 3 } +foo(new X()) + +// class interface Record +``` + +**ArkTS1.2** +```typescript +// file1.js +export function foo(obj) { +let x = {...obj} // x会是空对象{}，因为静态对象没有自有属性 +// 解决方案：let x = {a: obj.a, b: obj.b, c: obj.c} +// 或者使用keys + Reflect.get +let {a, b, ...rest} = obj // a会是1，b会是2，rest会是空对象{}，因为静态对象没有自有属性 +// 解决方案: let rest = {c: obj.c} + +// file2.ets // ArkTS1.2 +let mod = ESValue.load('./file1') +let foo = mod.getProperty('foo') +class X { a = 1; b = 2; c = 3 } +foo.invoke(ESValue.wrap(new X())) +``` + +### ArkTS1.2动态导入TS + +**规则：** arkts-interop-js2s-dynamic-import-js + +**级别：** error + +**ArkTS1.1** +```typescript +// file1.js +export class A {} + +// file2.ets ArkTS1.1 +let mod: ESObject = await import('./file1') +let A: ESObject = mod.A +new A() +``` + +**ArkTS1.2** +```typescript +// file1.js +export class A {} + +// file2.ets ArkTS1.1 +let mod: ESValue = ESValue.load('./file1') +let A: ESValue = mod.getProperty('A') +A.instantiate() +``` + diff --git a/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-migration-rules.md b/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-migration-rules.md new file mode 100644 index 0000000000000000000000000000000000000000..c976665f8b0964b58fcd2ae9871eb9ed3824cdb8 --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-v1.1-v1.2-migration-rules.md @@ -0,0 +1,1952 @@ +# ArkTS1.2迁移语法规范 + +ArkTS1.2在引入了静态类型系统、增强的并发能力的同时，也引入了与ArkTS1.1在语法和语义上的一部分差异。本文罗列了所有在ArkTS1.2中被限制的ArkTS1.1特性，并提供了重构代码的建议。 + +## 限定关键字 + +**规则：** `arkts-invalid-identifier` + +**级别：** error + +ArkTS1.2中对关键字和保留字做了严格定义。代码中不能使用这些关键字作为变量名称。 + +**ArkTS1.1** +```typescript +let as: number = 1; +const abstract: string = "abstract"; +``` + +**ArkTS1.2** +```typescript +let a = 1; +const abstract1: string = "abstract"; +``` + +## 数值类型语义变化 + +**规则：** `arkts-numeric-semantic` + +**级别：** error + +在ArkTS1.2中，为了获得更好的执行效率，整型数字字面量默认是int类型。 + +**ArkTS1.1** +```typescript +let n = 1; +console.log(n / 2) // output: 0.5 + +let arr = [1, 2, 3]; + +function multiply(x = 2, y = 3) { // 需要明确类型 + return x * y; +} + +function divide(x: number, y: number) { + return x / y; +} // 函数返回值 + +let num = Math.floor(4.8); // num 可能是 int +let value = parseInt("42"); // value 可能是 int + +function identity(value: T): T { + return value; +} +identity(42); // 42 可能推导为 int +``` + +**ArkTS1.2** +```typescript +let n: number = 1; +console.log(n / 2) // output: 0.5 + +let m = 1; +console.log(m / 2) // output: 0 + +let arr: number[] = [1, 2, 3]; + +function multiply(x: number = 2, y: number = 3): number { + return x * y; +} + +function divide(x: number, y: number): number { + return x / y; +} + +let num: number = Math.floor(4.8); +let value: number = parseInt("42"); + +function identity(value: T): T { + return value; +} +identity(42 as number); +``` + +## void类型只能用在返回类型的场景 + +**规则：** `arkts-limited-void-type` + +**级别：** error + +在ArkTS1.2中，void仅作为类型使用。void类型没有实体。 + +**ArkTS1.1** +```typescript +let s: void = foo(); +let t: void | number = foo(); + +function process(input: T): T { + return input; +} +let result = process(foo()); + +type VoidAlias = void; + +let { x }: { x: void } = { x: foo() }; + +function execute(callback: void) { + callback(); +} + +let x = fun() as void; +``` + +**ArkTS1.2** +```typescript +function foo(): void {} +foo(); + +function bar(): void {} + +function execute(callback: () => void) { + callback(); +} +fun(); +``` + +## 不支持void操作符 + +**规则：** `arkts-no-void-operator` + +**级别：** error + +在ArkTS1.2中，undefined作为关键字不能作为变量名称，因此不需要通过void操作符获取undefined。 + +**ArkTS1.1** +```typescript +let s = void 'hello'; +console.log(s); // output: undefined + +let a = 5; +let b = void (a + 1); + +function logValue(value: any) { + console.log(value); +} +logValue(void 'data'); + +let fn = () => void 0; +``` + +**ArkTS1.2** +```typescript +(() => { + 'hello' + return undefined; +})() + +let a = 5; +let b = (() => { + a + 1; + return undefined; +})(); // 替换为 IIFE + +logValue((() => { + 'data'; + return undefined; +})()); // 替换为 IIFE + +let fn = () => undefined; // 直接返回 `undefined` +``` + +## 限定使用字面量类型 + +**规则：** `arkts-limited-literal-types` + +**级别：** error + +ArkTS1.2不支持数字字面量类型，布尔字面量类型。 + +ArkTS1.2提供了更多细化的数值类型供开发者选择，更关注数值的范围而非某个特定的数字值，同时，为了更好的代码简洁性和避免引入歧义，不引入复杂的数值字面量类型语法。 + +**ArkTS1.1** +```typescript +let n1: 1 = 1; +let n2: 0.1 = 0.1; +let f: true = true; + +function getOne(): 1 { + return 1; +} +function isAvailable(): true { + return true; +} + +function setFlag(flag: true) { + console.log(flag); +} +function setPrecision(precision: 0.1) { + console.log(precision); +} + +interface Config { + readonly enable: true; + readonly threshold: 100; +} +``` + +**ArkTS1.2** +```typescript +let n1: int = 1; +let n2: number = 0.1; +let f: boolean = true; + +function getOne(): int { + return 1; +} +function isAvailable(): boolean { + return true; +} + +function setFlag(flag: boolean) { + console.log(flag); +} +function setPrecision(precision: number) { + console.log(precision); +} + +interface Config { + readonly enable: boolean; + readonly threshold: int; +} +``` + +## 不支持arguments对象 + +**规则：** `arkts-no-arguments-obj` + +**级别：** error + +ArkTS1.2对函数调用进行严格的参数检查，参数个数不符时编译报错，因此不需要在函数体内通过arguments机制获取参数。 + +**ArkTS1.1** +```typescript +function foo(u: string) { + console.log(arguments[0]); +} + +function bar(a: number, b?: number) { + if (arguments.length === 1) { + console.log("Only one argument passed"); + } +} + +function sum() { + let total = 0; + for (let i = 0; i < arguments.length; i++) { + total += arguments[i]; + } + return total; +} + +function test() { + console.log(arguments.callee); +} +``` + +**ArkTS1.2** +```typescript +function foo(u: string) { + console.log(u); +} + +function bar(a: number, b?: number) { + if (b === undefined) { + console.log("Only one argument passed"); + } +} + +function sum(...args: number[]) { + // 使用 `...rest` 替代 `arguments` + return args.reduce((acc, num) => acc + num, 0); +} + +function test() { + console.log(test); // 直接使用函数名 +} +``` + +## 数组索引必须是整型数据 + +**规则：**`arkts-array-index-expr-type` + +**级别：error** + +ArkTS1.2支持数值类型的细化，为了实现数组更快的访问，数组索引表达式必须是整数类型。 + +**ArkTS1.1** + +```typescript +function foo (index: number) { + let array = [1, 2, 3] + let element = array[index] +} + +function getIndex(): number { + return Math.random() * 10; // 可能返回小数 +} + +let array = [1, 2, 3]; +for (let i: number = 0; i < array.length; i++) { // 违反规则 + console.log(array[i]); +} +``` + +**ArkTS1.2** + +```typescript +function foo (index: int) { + let array = [1, 2, 3] + let element = array[index] +} + +function getIndex(): int { + return Math.floor(Math.random() * 10); // 转换为 `int` +} + +let array = [1, 2, 3]; +for (let i: int = 0; i < array.length; i++) { // 改为 `int` + console.log(array[i]); +} +``` + +## 不支持通过负数访问数组 + +**规则：**`arkts-array-index-negative` + +**级别：error** + +ArkTS1.2不支持使用负整数访问数组元素。 + +**ArkTS1.1** + +```typescript +let an_array = [1, 2, 3]; +let element = an_array [-1]; +console.log(getElement(an_array, -1)); // 违反规则 +for (let i: int = -1; i < an_array.length; i++) { // 违反规则 + console.log(an_array[i]); +} + +function getElement(arr: number[], index: int) { + return arr[index]; // 可能接收负数索引 +} +``` + +**ArkTS1.2** + +```typescript +let an_array = [1, 2, 3]; +let element = an_array [1]; +console.log(getElement(an_array, 1)); // 传递非负索引 +for (let i: int = 0; i < an_array.length; i++) { // 仅允许非负索引 + console.log(an_array[i]); +} + +function getElement(arr: number[], index: int) { + if (index < 0) throw new Error("Index must be a non-negative integer"); + return arr[index]; // 仅允许非负整数 +} +``` + +## 增加数组越界运行时检查 + +**规则：**`arkts-runtime-array-check` + +**级别：error** + +为了保证类型安全，在访问数组元素时，ArkTS1.2会对索引的合法性进行校验。 + +**ArkTS1.1** + +```typescript +let a: number[] = [] +a[100] = 5; // 可能越界 +``` + +**ArkTS1.2** + +```typescript +let a: number[] = [] +if (100 < a.length) { + a[100] = 5 // a[100]的值为5 +} +``` + +## arkts-no-tuples-arrays + +**规则：**`arkts-no-tuples-arrays` + +**级别：error** + +ArkTS1.2中数组和元组是不同的类型，运行时使用元组类型可以获得更好的性能。 + +**ArkTS1.1** + +```typescript +const tuple: [number, number, boolean] = [1, 3.14, true]; +const array: (number|boolean) [] = tuple; + +const tuple: Array = [1, 3.14, true]; // 违反规则 + +function getTuple(): (number | boolean)[] { // 违反规则 + return [1, 3.14, true]; +} +getTuple([1, 3.14, true]); // 传入元组 + +type Point = (number | boolean)[]; // 违反规则 +const p: Point = [3, 5, true]; +``` + +**ArkTS1.2** + +```typescript +const tuple: [number, number, boolean] = [1, 3.14, true]; +const array: [number, number, boolean] = tuple; + +const tuple: [number, number, boolean] = [1, 3.14, true]; // 正确使用元组 + +function getTuple(): [number, number, boolean] { // 正确使用元组 + return [1, 3.14, true]; +} +getTuple([1, 3.14, true]); + +type Point = [number, number, boolean]; // 使用元组 +const p: Point = [3, 5, true]; +``` + +## 函数类型 + +**规则：**`arkts-incompatible-function-types` + +**级别：error** + +TypeScript允许对函数类型的变量进行更宽松的赋值，而在ArkTS1.2中，将对函数类型的赋值进行更严格的检查。函数类型转换时，参数遵循逆变(Contravariance)规则，返回类型遵循协变(Covariance)规则。 + +**ArkTS1.1** + +```typescript +type FuncType = (p: string) => void; +let f1: FuncType = + (p: string): number => { + return 0 + } +let f2: FuncType = (p: any): void => {}; + +class Animal {} +class Dog extends Animal {} +type FuncType = () => Animal; +let f: FuncType = (): Dog => new Dog(); // 在 TypeScript 允许，但在 ArkTS 可能不允许 + +type FuncType2 = (dog: Dog) => void; +let f: FuncType2 = (animal: Animal) => {}; // 违反规则 +``` + +**ArkTS1.2** + +```typescript +type FuncType = (p: string) => void +let f1: FuncType = + (p: string) => { + ((p: string): number => { + return 0 + })(p) + } +let f2: FuncType = (p: string): void => {}; + +class Animal {} +class Dog extends Animal {} +type FuncType = () => Animal; +let f: FuncType = (): Animal => new Animal();// 返回 `Animal` + +type FuncType2 = (dog: Dog) => void; +let f: FuncType = (dog: Dog) => {}; // 参数类型严格匹配 +``` + +## 不支持指数操作符 + +**规则：**`arkts-no-exponent-op` + +**级别：error** + +ArkTS1.2不支持指数运算符（`**`和`**=`），采用语言基础库。 + +**ArkTS1.1** + +```typescript +let x = 2 ** 5; + +let y = 3; +y **= 4; // 违反规则 + +let result = (1 + 2) ** (3 * 2); // 违反规则 + +function power(base: number, exponent: number) { + return base ** exponent; // 违反规则 +} + +let values = [1, 2, 3]; +let squared = values.map(v => v ** 2); // 违反规则 +``` + +**ArkTS1.2** + +```typescript +let x = Math.pow(2, 5); + +let y = 3; +y = Math.pow(y, 4); // 直接使用 `Math.pow()` + +let result = Math.pow(1 + 2, 3 * 2); // 直接使用 `Math.pow()` + +function power(base: number, exponent: number) { + return Math.pow(base, exponent); // 使用 `Math.pow()` +} + +let values = [1, 2, 3]; +let squared = values.map(v => Math.pow(v, 2)); // 使用 `Math.pow()` +``` + +## 不支持正则表达式 + +**规则：**`arkts-no-regexp-literals` + +**级别：error** + +ArkTS1.2不支持正则表达式字面量。 + +**ArkTS1.1** + +```typescript +let regex: RegExp = /bc*d/; +let regex = /\d{2,4}-\w+/g; // 违反规则 +function matchPattern(str: string) { + return str.match(/hello\s+world/i); // 违反规则 +} + +let text = "Hello world!"; +let result = text.replace(/world/, "ArkTS"); // 违反规则 + +let items = "apple,banana, cherry".split(/\s*,\s*/); // 违反规则 +``` + +**ArkTS1.2** + +```typescript +let regex: RegExp = new RegExp('bc*d'); +let regex = new RegExp('\\d{2,4}-\\w+', 'g'); // 使用 `RegExp` 类 +function matchPattern(str: string) { + let regex = new RegExp('hello\\s+world', 'i'); // 使用 `RegExp` + return str.match(regex); +} + +let text = "Hello world!"; +let regex = new RegExp('world'); // 使用 `RegExp` 类 +let result = text.replace(regex, "ArkTS"); + +let regex = new RegExp('\\s*,\\s*'); // 使用 `RegExp` +let items = "apple,banana, cherry".split(regex); +``` + +## enum中不支持成员为不同类型数据 + +**规则：**`arkts-no-enum-mixed-types` + +**级别：error** + +enum用来表示一组离散的数据，使用浮点数据不符合enum的设计理念。使用浮点数据可能造成精度损失的问题。因此，ArkTS1.2中enum的值必须为整型数据。 + +**ArkTS1.1** + +```typescript +enum Size { + UP = 1.5, + MIDDLE = 1, + DOWN = 0.75 +} +``` + +**ArkTS1.2** + +```typescript +enum Size{ + UP = 1, + MIDDLE = 2, + DOWN = 3 +} +``` + +## 不支持为函数增加属性 + +**规则：**`arkts-no-func-props` + +**级别：error** + +ArkTS1.2上不支持在函数上动态添加属性。 + +**ArkTS1.1** + +```typescript +function foo(path: string): void { + console.log(path) +} +foo.baz = 1 + +const obj = { + foo(path: string): void { + console.log(path); + } +}; +obj.foo.baz = 2; // 违反规则 + +function createLogger() { + function log(message: string) { + console.log(message); + } + log.level = "debug"; // 违反规则 + return log; +} + +const logger = createLogger(); +console.log(logger.level); + +function counter() { + counter.count = (counter.count || 0) + 1; // 违反规则 + return counter.count; +} +console.log(counter()); +``` + +**ArkTS1.2** + +```typescript +class T { + static foo(path: string): void { + console.log(path) + } + static bar: number = 1 +} + +class T { + static foo(path: string): void { + console.log(path); + } + + static baz: number = 2; +} +T.foo("example"); +console.log(T.baz); + +class Logger { + static level = "debug"; + + static log(message: string) { + console.log(message); + } +} +Logger.log("test"); +console.log(Logger.level); + +class Counter { + static count = 0; + + static increment() { + this.count += 1; + return this.count; + } +} +console.log(Counter.increment()); +``` + +## 不支持TS装饰器 + +**规则：**`arkts-no-ts-decorators` + +**级别：error** + +ArkTS1.2中不支持将类作为对象，不能通过装饰器中对类做动态改变。 + +**ArkTS1.1** + +```typescript +function decorateKlass(target: Object) { + console.log("decorateKlass") +} + +@decorateKlass // 违反规则 +class Person { + age: number = 12 +} +``` + +**ArkTS1.2** + +```typescript +class Person { + age: number = 12 +} + +class PersonHelper { + static createPerson(): Person { + console.log("decorateKlass") + return new Person() + } +} +``` + +## 类实现接口时，不能用类方法替代对应interface属性 + +**规则：**`arkts-no-method-overriding-field` + +**级别：error** + +ArkTS1.2不支持structural type，属性和方法不能互相转换。 + +**ArkTS1.1** + +```typescript +interface Person { + cb: () => void +} + +class student implements Person{ + cb() {} +} + +interface Transformer { + transform: (value: T) => T; // 违反规则 +} + +class StringTransformer implements Transformer { + transform(value: string) { return value.toUpperCase(); } // 违反规则 +} +``` + +**ArkTS1.2** + +```typescript +interface Person { + cb(): void +} + +class student implements Person{ + cb() {} +} + +interface Transformer { + transform(value: T): T; // 变成方法 +} + +class StringTransformer implements Transformer { + transform(value: string) { return value.toUpperCase(); } // 正确 +} +``` + +## 限定switch语句中case语句类型 + +**规则：**`arkts-switch-expr` + +**级别：error** + +ArkTS1.2的switch表达式类型只能为number，string，enum。 + +**ArkTS1.1** + +```typescript +const isTrue = true; +switch (isTrue) { + case true: // 违反规则 + console.log('It\'s true'); break; + case false: // 违反规则 + console.log('It\'s false'); break; +} + +const obj = { value: 1 }; +switch (obj) { // 违反规则 + case { value: 1 }: + console.log('Matched'); break; +} + +const arr = [1, 2, 3]; +switch (arr) { // 违反规则 + case [1, 2, 3]: + console.log('Matched'); break; +} +``` + +**ArkTS1.2** + +```typescript +const isTrue = 'true'; +switch (isTrue) { + case 'true': + console.log('It\'s true'); break; + case 'false': + console.log('It\'s false'); break; +} + +const objValue = 1; // 仅存储值 +switch (objValue) { + case 1: + console.log('Matched'); break; +} + +const arrValue = '1,2,3'; // 变成字符串 +switch (arrValue) { + case '1,2,3': + console.log('Matched'); break; +} +``` + +## 不支持重复case语句 + +**规则：**`arkts-case-expr` + +**级别：error** + +ArkTS1.2不支持Switch语句的中case重复，便于提高代码可读性。 + +**ArkTS1.1** + +```typescript +const num = 1; +switch (num) { + case 1: + console.log('First match'); + case 1: + console.log('Second match'); + break; + default: + console.log('No match'); +} + +enum Status { + Active, + Inactive +} + +const state = Status.Active; +switch (state) { + case Status.Active: + console.log('User is active'); + break; + case Status.Active: // 违反规则 + console.log('Already active'); + break; +} +``` + +**ArkTS1.2** + +```typescript +const num = 1; +switch (num) { + case 1: + console.log('First match'); + console.log('Second match'); + break; + default: + console.log('No match'); +} + +switch (state) { + case Status.Active: + console.log('User is active'); + console.log('Already active'); // 代码合并 + break; +} +``` + +## 不支持lazy关键字 + +**规则：**`arkts-no-lazy-import` + +**级别：error** + +ArkTS1.2支持默认懒加载，无需lazy关键字。 + +**ArkTS1.1** + +```typescript +import lazy { m } from 'module' +import lazy { a, b } from 'module1'; // 违反规则 +import { c } from 'module2'; +``` + +**ArkTS1.2** + +```typescript +import { m } from 'module' +import { a, b } from 'module1'; // 移除 lazy +import { c } from 'module2'; +``` + +## 不支持动态import + +**规则：**`arkts-no-dynamic-import` + +**级别：error** + +ArkTS1.2中模块加载默认支持懒加载。 + +**ArkTS1.1** + +```typescript +function main(): void { + import('./file').then((m) => { + console.log(m.Data.name) + }) +} + +document.getElementById("btn")?.addEventListener("click", async () => { + const module = await import('./utils'); // 错误: 在ArkTS中动态`import()`是不支持的. + module.doSomething(); +}); + +function getModule() { + return import('./heavyModule') // 错误: 在ArkTS中动态`import()`是不支持的. + .then((m) => m.default); +} +``` + +**ArkTS1.2** + +```typescript +import { Data } from './file' +import { doSomething } from './utils'; // 静态import是可以的. +import heavyModule from './heavyModule'; // 静态import是可以的. + +function main(): void { + console.log(Data.name) +} + +document.getElementById("btn")?.addEventListener("click", () => { + doSomething(); +}); + +function getModule() { + return heavyModule; +} +``` + +## 不支持副作用导入 + +**规则：**`arkts-no-side-effect-import` + +**级别：error** + +ArkTS1.2中模块加载默认支持懒加载，无法实现导入副作用的功能。 + +**ArkTS1.1** + +```typescript +// logger.ets +console.log("Logger initialized!"); + +// main.ets +import "./logger"; +console.log("Main program running..."); +``` + +**ArkTS1.2** + +```typescript +// main.ets +console.log("Logger initialized!"); +console.log("Main program running..."); +``` + +## 不支持globalThis + +**规则：**`arkts-no-globalthis` + +**级别：error** + +由于ArkTS1.2不支持动态更改对象的布局，因此不支持全局作用域和globalThis。 + +**ArkTS1.1** + +```typescript +// 全局文件中 +var abc = 100; + +// 从上面引用'abc' +let x = globalThis.abc; +``` + +**ArkTS1.2** + +```typescript +// file1 +export let abc: number = 100; + +// file2 +import * as M from 'file1' + +let x = M.abc; +``` + +## 不支持Funcion.bind方法 + +**规则：**`arkts-no-func-bind` + +**级别：error** + +ArkTS不允许使用标准库函数Function.bind。标准库使用这些函数来显式设置被调用函数的this参数。 + +**ArkTS1.1** + +```typescript +class MyClass { + constructor(public name: string) {} + + greet() { + console.log(`Hello, my name is ${this.name}`); + } +} + +const instance = new MyClass("Alice"); +const boundGreet = instance.greet.bind(instance); // 违反规则，不允许使用 Function.bind +boundGreet(); +``` + +**ArkTS1.2** + +```typescript +class MyClass { + constructor(public name: string) {} + + greet() { + console.log(`Hello, my name is ${this.name}`); + } +} + +const instance = new MyClass("Alice"); +const boundGreet = () => instance.greet(); // 使用箭头函数 +boundGreet(); // Hello, my name is Alice +``` + +## 不支持将类作为对象 + +**规则：**`arkts-no-classes-as-obj` + +**级别：error** + +在ArkTS中，class声明的是一个新的类型，不是一个值。因此，不支持将class用作对象（例如将class赋值给一个对象）。 + +**ArkTS1.1** + +```typescript +class MyClass { + constructor(public name: string) {} +} + +let obj = MyClass; // 违反规则 +``` + +**ArkTS1.2** + +```typescript +class MyClass { + constructor(public name: string) {} +} + +let obj = new MyClass("Alice"); +console.log(obj.name); // Alice +``` + +## arkts-limited-stdlib + +**规则：**`arkts-limited-stdlib` + +**级别：error** + +由于TypeScript或JavaScript标准库中的大部分接口与动态特性有关，所以在ArkTS中禁止使用以下接口： + +Object: getPrototypeOf + +## 不支持structural typing + +**规则：**`arkts-no-structural-typing` + +**级别：error** + +ArkTS1.2不支持structural typing，编译器无法比较两种类型的publicAPI并决定它们是否相同。使用其他机制，例如继承、接口或类型别名。 + +**ArkTS1.1** + +```typescript +// case1 +class A { + v: number = 0 +} + +class B { + v: number = 0 +} + +let a = new B() as A + +// case2 +class C { + u: T +} + +let b: C = new C() + +// case3 +class A { + u: number = 0 +} + +class B { + u: number = 0 +} + +(): A => { return new B() } + +class A { + v: number = 0 +} + +class B { + v: number = 0 +} +class C { + u: T; +} + +let b: C = new C(); // 违反规则 +``` + +**ArkTS1.2** + +```typescript +// case1 +class A { + v: number = 0 +} + +class B { + v: number = 0 +} + +let a = new B() + +// case2 +class C { + u: T +} + +let b: C = new C() + +// case3 +class A { + u: number = 0 +} + +class B { + u: number = 0 +} + +(): B => { return new B() } + +class A { + v: number = 0 +} + +class B { + v: number = 0 +} +let b: C = new C(); // 使用相同的泛型类型 + +``` + +## 禁止extends/implements表达式 + +**规则：**`arkts-no-extends-expression` + +**级别：error** + +ArkTS1.2中规范了类的继承，类不能作为对象来继承一个表达式。 + +**ArkTS1.1** + +```typescript +class A { + v: number = 0 +} + +let a = A; + +class B extends a { // 违反规则 + u: number = 0 +} + +function getBase() { + return class { + w: number = 0; + }; +} + +class B extends getBase() { // 违反规则 + u: number = 0; +} + +interface I { + w: number; +} + +let i = I; + +class B implements i { // 违反规则 + w: number = 0; +} + +class A { + v: number = 0; +} + +class B extends new A() { // 违反规则 + u: number = 0; +} +``` + +**ArkTS1.2** + +```typescript +class A { + v: number = 0 +} + +class B extends A { // 直接继承类 + u: number = 0 +} + +class Base { + w: number = 0; +} + +class B extends Base { // 直接继承类 + u: number = 0; +} + +interface I { + w: number; +} + +class B implements I { // 直接使用接口 + w: number = 0; +} + +class A { + v: number = 0; +} + +class B extends A { // 直接继承类 + u: number = 0; +} +``` + +## 不支持类TS重载 + +**规则：**`arkts-no-ts-overload` + +**级别：error** + +ArkTS1.2不支持TS-like的重载，使用不同的函数体可以提高执行效率。 + +**ArkTS1.1** + +```typescript +function foo(): void +function foo(x: string): void +function foo(x?: string): void { // 违反规则 + /*body*/ +} + +function sum(x: number, y: number): number; +function sum(x: number, y: number, z: number): number; +function sum(x: number, y: number, z?: number): number { // 违反规则 + return z ? x + y + z : x + y; +} + +function foo(): string; +function foo(x: number): number; +function foo(x?: number): string | number { // 违反规则 + return x !== undefined ? x * 2 : "default"; +} +``` + +**ArkTS1.2** + +```typescript +function foo(x?: string): void { + /*body*/ +} + +function sumTwo(x: number, y: number): number { // 独立实现 + return x + y; +} + +function sumThree(x: number, y: number, z: number): number { // 独立实现 + return x + y + z; +} + +function fooString(): string { // 独立实现 + return "default"; +} + +function fooNumber(x: number): number { // 独立实现 + return x * 2; +} +``` + +## enum的key不能是字符串 + +**规则：**`arkts-identifiers-as-prop-names` + +**级别：error** + +ArkTS1.2不支持将字符串作为class、interface、enum等属性或元素的名称，需要使用标识符来表示。 + +**ArkTS1.1** + +```typescript +enum A{ + 'red' = '1' +} +``` + +**ArkTS1.2** + +```typescript +enum A{ + red = '1' +} +``` + +## 创建泛型实例需要类型实参 + +**规则：**`arkts-no-inferred-generic-params` + +**级别：error** + +ArkTS1.2中，创建泛型实例时需要类型实参。 + +**ArkTS1.1** + +```typescript +new Array() // 违反规则 + +new Map(); // 违反规则 + +class Box { + value: T; + constructor(value: T) { + this.value = value; + } +} + +let box = new Box(42); // 违反规则 +``` + +**ArkTS1.2** + +```typescript +new Array() // 指定类型 + +new Map(); // 显式指定键值类型 + +let box = new Box(42); // 明确指定类型 +``` + +## 不支持[]访问对象属性 + +**规则：**`arkts-no-props-by-index` + +**级别：error** + +在ArkTS1.2中，对象结构在编译时已确定。为避免运行时出现错误和更好地提升性能，在ArkTS1.2中不能使用[]的方式动态访问object类型对象的属性。 + +**ArkTS1.1** + +```typescript +function foo(u: object) { + u['key'] // 违反规则 +} + +const person = { name: "Alice", age: 30 }; +console.log(person['name']); // 违反规则 + +const data = JSON.parse('{ "name": "Alice" }'); +console.log(data['name']); // 违反规则 +``` + +**ArkTS1.2** + +```typescript +function foo(m: Map) { + m.get('key') // 使用 `Map` +} + +console.log(person.name); // 直接使用 `.` 访问 + +interface UserData { + name: string; +} +const data: UserData = JSON.parse('{ "name": "Alice" }'); +console.log(data.name); // 直接使用点访问符 +``` + +## 对象字面量只包含属性不包含方法 + +**规则：**`arkts-obj-literal-props` + +**级别：error** + +ArkTS1.2中不支持在对象字面量中定义方法。因为静态语言中类的方法被所有实例所共享，无法通过对象字面量重新定义方法。 + +**ArkTS1.1** + +```typescript +class A { + foo: () => void = () => {} +} + +let a: A = { + foo() { // 违反规则 + console.log('hello') + } +} + +interface Person { + sayHello: () => void; +} + +let p: Person = { + sayHello() { // 违反规则，方法定义方式错误 + console.log('Hi'); + } +}; + +type Handler = { + foo(): void; +}; + +let handler: Handler = { + foo() { // 违反规则 + console.log("Executing handler"); + } +}; +``` + +**ArkTS1.2** + +```typescript +class A { + foo : () => void = () => {} +} + +let a: A = { + foo: () => { + console.log('hello') + } +} + +let p: Person = { + sayHello: () => { // 使用属性赋值方式 + console.log('Hi'); + } +}; + +type Handler = { + foo: () => void; +}; + +let handler: Handler = { + foo: () => { // 修正方法定义方式 + console.log("Executing handler"); + } +}; +``` + +## 对象字面量生成类的实例 + +**规则：**`arkts-obj-literal-generate-class-instance` + +**级别：error** + +ArkTS1.2中对象字面量会生成类的实例。 + +**ArkTS1.1** + +```typescript +class A { + v: number = 0 +} + +let a: A = { v: 123 } +console.log(a instanceof A) // false + +class A { + v: number = 0; + hello() { + return "Hello"; + } +} + +let a: A = { v: 123 }; +console.log(a.hello()); // 报错，a 没有 hello() 方法 + +class A { + v: number = 0; +} + +let a: A = { v: 123 }; +console.log(Object.getPrototypeOf(a) === A.prototype); // false + +``` + +**ArkTS1.2** + +```typescript +class A { + v: number = 0 +} + +let a: A = { v: 123 } +console.log(a instanceof A) // true + +class A { + v: number = 0; + hello() { + return "Hello"; + } +} + +let a: A = { v: 123 }; +console.log(a.hello()); // 正常执行 "Hello" + +class A { + v: number = 0; +} + +let a: A = { v: 123 }; +console.log(Object.getPrototypeOf(a) === A.prototype); // true + +``` + +## 增强对联合类型属性访问的编译时检查 + +**规则：**`arkts-common-union-member-access` + +**级别：error** + +在ArkTS1.2中，对象的结构在编译时就确定了。为了避免访问联合类型后出现运行时错误，ArkTS1.2在编译时会对联合类型的同名属性进行编译检查，要求同名属性具有相同的类型。 + +**ArkTS1.1** + +```typescript +class A { + v: number = 1 +} + +class B { + u: string = '' +} + +function foo(a: A | B) { + console.log(a.v) // 违反规则 + console.log(a.u) // 违反规则 +} +``` + +**ArkTS1.2** + +```typescript +class A { + v: number = 1 +} + +class B { + u: string = '' +} + +function foo(a: A) { + console.log(a.v) +} + +function foo(a: B) { + console.log(a.u) +} +``` + +## 类的静态属性需要有初始值 + +**规则：**`arkts-class-static-initialization` + +**级别：error** + +ArkTS1.2遵循null-safety，需要为属性赋上初始值。 + +**ArkTS1.1** + +```typescript +class B {} + +class A { + static b: B +} + +class A { + static count: number; // 违反规则，必须初始化 +} + +class A { + static config: { theme: string }; // 违反规则，必须初始化 +} + +class A { + static name: string; + + constructor() { + A.name = "default"; // 违反规则，静态属性必须在定义时初始化 + } +} +``` + +**ArkTS1.2** + +```typescript +class B {} + +class A { + static b? : B + static b: B | undefined = undefined +} + +class A { + static count: number = 0; // 提供初始值 +} + +class A { + static config: { theme: string } = { theme: "light" }; // 提供初始值 +} + +class A { + static name: string = "default"; // 在定义时初始化 +} + +``` + +## 不支持TS-like `Function`类型的调用方式 + +**规则：**`arkts-no-ts-like-function-call` + +**级别：error** + +ArkTS1.2会对函数类型进行更严格的编译器检查。函数返回类型需要严格定义来保证类型安全，因此不支持TS-like`Function`类型。 + +**ArkTS1.1** + +```typescript +let f: Function = () => {} // 违反规则 + +function run(fn: Function) { // 违反规则 + fn(); +} + +let fn: Function = (x: number) => x + 1; // 违反规则 + +class A { + func: Function = () => {}; // 违反规则 +} + +function getFunction(): Function { // 违反规则 + return () => {}; +} +``` + +**ArkTS1.2** + +```typescript +type F = () => R; +type F1 = (p: P) => R + +let f: F = () => {} + +function run(fn: () => void) { // 指定返回类型 + fn(); +} + +let fn: (x: number) => number = (x) => x + 1; // 明确参数类型 + +class A { + func: () => void = () => {}; // 明确类型 +} + +function getFunction(): () => void { // 明确返回类型 + return () => {}; +} +``` + +## 不支持可选方法 + +**规则：**`arkts-optional-methods` + +**级别：error** + +ArkTS1.2中类的方法被所有类的实例所共享，增加可选方法的支持会增加开发者判断空值的成本，影响性能。 + +**ArkTS1.1** + +```typescript +interface InterfaceA { + aboutToDisappear?(): void +} +class ClassA { + aboutToDisappear?(): void {} +} +``` + +**ArkTS1.2** + +```typescript +interface InterfaceA { + aboutToDisappear?: () => void +} +class ClassA { + aboutToDisappear?: () => void = () => {} +} +``` + +## 实例方法当作对象时会绑定this + +**规则：**`arkts-instance-method-bind-this` + +**级别：error** + +ArkTS1.2中实例方法被当作lambda对象传递时，会捕获上下文的this，避免类型不安全的行为。 + +**ArkTS1.1** + +```typescript +class A { + n: string = 'a' + foo() { console.log (this.n) } +} +let a = new A() +const method = a.foo +method() // 无法读取未定义的属性'n'. +``` + +**ArkTS1.2** + +```typescript +class A { + n: string = 'a' + foo() { console.log (this.n) } +} +let a = new A() +const method = a.foo +method() // 输出a +``` + +## namespace内方法不能重名 + +**规则：**`arkts-no-duplicate-function-name` + +**级别：error** + +由于ArkTS1.2中会将多个名称相同的namespace合并成一个namespace，所以namespace内方法不能重名，否则会导致冲突。 + +**ArkTS1.1** + +```typescript +namespace A { + export function foo() { // 错误：命名空间 'A' 中重复导出函数 'foo'. + console.log('test1'); + } +} + +namespace A { + export function foo() { // 错误：命名空间 'A' 中重复导出函数 'foo'. + console.log('test2'); + } +} + +``` + +**ArkTS1.2** + +```typescript +namespace A { + export function foo1() { // 重命名导出函数 + console.log('test1'); + } +} + +namespace A { + export function foo2() { + console.log('test2'); + } +} +``` + +## arkts-no-ctor-prop-decls + +**规则：**`arkts-no-ctor-prop-decls` + +**级别：error** + +ArkTS1.2不支持在constructor中声明类字段。在class中声明这些字段。 + +**ArkTS1.1** + +```typescript +class A { + constructor(readonly a: string) { + } +} + +class Base { + readonly b: string = "base"; +} + +class A extends Base { + constructor(override readonly b: string) { // 违反规则 + super(); + } +} +``` + +**ArkTS1.2** + +```typescript +class A { + readonly a: string + constructor(a: string) { + this.a = a + } +} + +class Base { + readonly b: string = "base"; +} + +class A extends Base { + override readonly b: string; // 显式声明字段 + constructor(b: string) { + super(); + this.b = b; + } +} + +``` + +## 不支持tagged templates + +**规则：**`arkts-no-tagged-templates` + +**级别：error** + +ArkTS1.2规范函数调用方式，支持字符串相加的用法，不支持Tagged templates（标签模板字符串）。 + +**ArkTS1.1** + +```typescript +function myTag(strings: TemplateStringsArray, value: string): string { + return strings[0] + value.toUpperCase() + strings[1]; +} + +const name = 'john'; +const result = myTag`Hello, ${name}!`; +console.log(result); + +function formatTag(strings: TemplateStringsArray, first: string, last: string): string { + return `${strings[0]}${first.toUpperCase()} ${last.toUpperCase()}${strings[1]}`; +} + +const firstName = 'john'; +const lastName = 'doe'; +const result = formatTag`Hello, ${firstName} ${lastName}!`; // 违反规则 +console.log(result); +``` + +**ArkTS1.2** + +```typescript +function myTagWithoutTemplate(strings: string, value: string): string { + return strings + value.toUpperCase(); +} + +const name = 'john'; + +const part1 = 'Hello, '; +const part2 = '!'; +const result = myTagWithoutTemplate(part1, name) + part2; +console.log(result); + +function formatWithoutTemplate(greeting: string, first: string, last: string, end: string): string { + return greeting + first.toUpperCase() + ' ' + last.toUpperCase() + end; +} + +const firstName = 'john'; +const lastName = 'doe'; +const result = formatWithoutTemplate('Hello, ', firstName, lastName, '!'); // 直接使用函数参数 +console.log(result); +``` + +## 不支持确定赋值断言 + +**规则：**`arkts-no-definite-assignment` + +**级别：error** + +ArkTS1.2不支持确定赋值断言。改为在声明变量的同时为变量赋值。 + +**ArkTS1.1** + +```typescript +let x!: number // 提示：在使用前将x初始化 + +initialize(); + +function initialize() { + x = 10; +} + +console.log('x = ' + x); +``` + +**ArkTS1.2** + +```typescript +function initialize(): number { + return 10; +} + +let x: number = initialize(); + +console.log('x = ' + x); +``` diff --git a/zh-cn/application-dev/quick-start/arkts-v1.2-user-guide.md b/zh-cn/application-dev/quick-start/arkts-v1.2-user-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..e584b44fe9b964564e268bc55a099d656319668f --- /dev/null +++ b/zh-cn/application-dev/quick-start/arkts-v1.2-user-guide.md @@ -0,0 +1,21 @@ +# ArkTS1.2概述 + +## 介绍 + +ArkTS1.2版本引入了多项重要特性，例如： +- 静态类型系统。 +- 对象天然共享特性，不再依赖Sendable特性，无需添加@Sendable装饰器。 +- 互操作特性，提供ArkTS1.2和ArkTS1.1以及TS/JS代码的交互能力。 + + +## 规范指引 + +详细的规范文档请参考：[ArkTS1.2规范](https://gitee.com/openharmony/arkcompiler_runtime_core/releases) + +## ArkTS 迁移指南 + +为帮助开发者顺利迁移到ArkTS1.2，特提供以下迁移指南。 + +- 了解ArkTS1.2的基础语法和规则变更：[ArkTS基础规则变更](./arkts-v1.1-v1.2-migration-rules.md)。 +- 了解新的并发特性和使用方法：[并发特性变更](./ArkTSConcurrencyRules1.2.md)。 +- 了解与其他系统交互的规则变更：[ArkTS互操作规则变更](./arkts-v1.1-v1.2-interop-rules.md)。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis-arkts/js-apis-util.md b/zh-cn/application-dev/reference/apis-arkts/js-apis-util.md index 0700d1a53c638b3580059a5d82f2a870c6f57dbe..9bac59dc2d8cb493b65c8f0ac1fa4261b5716848 100644 --- a/zh-cn/application-dev/reference/apis-arkts/js-apis-util.md +++ b/zh-cn/application-dev/reference/apis-arkts/js-apis-util.md @@ -399,6 +399,8 @@ printf(format: string, ...args: Object[]): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -433,6 +435,8 @@ getErrorString(errno: number): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -466,6 +470,8 @@ promiseWrapper(original: (err: Object, value: Object) => void): Object **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -558,6 +564,8 @@ console.info('result2 is ' + result2); **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + | 名称 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | stream | boolean | 否 | 在随后的decodeWithStream()调用中是否跟随附加数据块。如果以块的形式处理数据，则设置为true；如果处理最后的数据块或数据未分块，则设置为false。默认为false。 | @@ -856,7 +864,7 @@ static create(encoding?: string, options?: TextDecoderOptions): TextDecoder | encoding | string | 否 | 编码格式，默认值是'utf-8'。 | | options | [TextDecoderOptions](#textdecoderoptions11) | 否 | 解码相关选项参数，存在两个属性fatal和ignoreBOM。| -**错误码：** +**ArkTS1.1版本错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 @@ -864,6 +872,10 @@ static create(encoding?: string, options?: TextDecoderOptions): TextDecoder | -------- | -------- | | 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | +**ArkTS1.2版本错误码：** + +此接口在ArkTS1.2无错误码。 + **示例：** ```ts @@ -939,6 +951,8 @@ decodeWithStream(input: Uint8Array, options?: DecodeWithStreamOptions): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -996,6 +1010,8 @@ TextDecoder的构造函数。 **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -1028,6 +1044,8 @@ decode(input: Uint8Array, options?: { stream?: false }): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -1074,8 +1092,8 @@ console.info("retStr = " + retStr); | 名称 | 类型 | 可读 |可写 | 说明 | | --------- | -------- | -------- |-------- |------------------ | -| read | number | 是 | 否 |表示已读取的字符数。 | -| written | number | 是 |否 |表示已写入的字节数。 | +| read | ArkTS1.1: number
ArkTS1.2: int | 是 | 否 |表示已读取的字符数。 | +| written | ArkTS1.1: number
ArkTS1.2: int | 是 |否 |表示已写入的字节数。 | ## TextEncoder @@ -1192,7 +1210,7 @@ encodeInto(input?: string): Uint8Array | ---------- | ------------------ | | Uint8Array | 返回编码后的Uint8Array对象。 | -**错误码：** +**ArkTS1.1版本错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 @@ -1200,6 +1218,10 @@ encodeInto(input?: string): Uint8Array | -------- | -------- | | 401 | Parameter error. Possible causes: 1. Incorrect parameter types. | +**ArkTS1.2版本错误码：** + +此接口在ArkTS1.2无错误码。 + **示例：** ```ts @@ -1232,7 +1254,7 @@ encodeIntoUint8Array(input: string, dest: Uint8Array): EncodeIntoUint8ArrayInfo | ---------- | ------------------ | | [EncodeIntoUint8ArrayInfo](#encodeintouint8arrayinfo11) | 返回一个对象，read表示已编码的字符数，write表示编码字符所占用的字节数。 | -**错误码：** +**ArkTS1.1版本错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 @@ -1240,6 +1262,10 @@ encodeIntoUint8Array(input: string, dest: Uint8Array): EncodeIntoUint8ArrayInfo | -------- | -------- | | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | +**ArkTS1.2版本错误码：** + +此接口在ArkTS1.2无错误码。 + **示例：** ```ts @@ -1267,6 +1293,8 @@ encodeInto(input: string, dest: Uint8Array): { read: number; written: number } **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -1303,6 +1331,8 @@ encode(input?: string): Uint8Array **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -1778,6 +1808,8 @@ RationalNumber的构造函数。 **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -1803,6 +1835,8 @@ compareTo(another: RationalNumber): number​ **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -1837,6 +1871,8 @@ static getCommonDivisor(number1: number,number2: number): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -3897,6 +3933,8 @@ isBooleanObject(value: Object): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -3933,6 +3971,8 @@ isBoxedPrimitive(value: Object): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -4445,6 +4485,8 @@ isNumberObject(value: Object): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -4647,6 +4689,8 @@ isStringObject(value: Object): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -4683,6 +4727,8 @@ isSymbolObject(value: Object): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5087,6 +5133,8 @@ isSharedArrayBuffer(value: Object): boolean **系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + | 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | | length | number | 是 | 否 | 当前缓冲区中值的总数。 | @@ -5114,6 +5162,8 @@ constructor(capacity?: number) **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5138,6 +5188,8 @@ updateCapacity(newCapacity: number): void **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5163,6 +5215,8 @@ toString(): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5193,6 +5247,8 @@ getCapacity(): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5220,6 +5276,8 @@ clear(): void **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **示例：** ```ts @@ -5241,6 +5299,8 @@ getCreateCount(): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5269,6 +5329,8 @@ getMissCount(): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5298,6 +5360,8 @@ getRemovalCount(): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5328,6 +5392,8 @@ getMatchCount(): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5357,6 +5423,8 @@ getPutCount(): number **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5385,6 +5453,8 @@ isEmpty(): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5413,6 +5483,8 @@ get(key: K): V | undefined **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5447,6 +5519,8 @@ put(key: K,value: V): V **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5481,6 +5555,8 @@ values(): V[] **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5511,6 +5587,8 @@ keys(): K[] **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5539,6 +5617,8 @@ remove(key: K): V | undefined **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5573,6 +5653,8 @@ afterRemoval(isEvict: boolean,key: K,value: V,newValue: V): void **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5620,6 +5702,8 @@ contains(key: K): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5654,6 +5738,8 @@ createDefault(key: K): V **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5685,6 +5771,8 @@ entries(): IterableIterator<[K,V]> **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5711,6 +5799,8 @@ entries(): IterableIterator<[K,V]> **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5744,6 +5834,8 @@ constructor(lowerObj: ScopeType, upperObj: ScopeType) **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5787,6 +5879,8 @@ toString(): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5832,6 +5926,8 @@ intersect(range: Scope): Scope **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5886,6 +5982,8 @@ intersect(lowerObj:ScopeType,upperObj:ScopeType):Scope **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -5940,6 +6038,8 @@ getUpper(): ScopeType **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -5985,6 +6085,8 @@ getLower(): ScopeType **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **返回值：** | 类型 | 说明 | @@ -6030,6 +6132,8 @@ expand(lowerObj: ScopeType,upperObj: ScopeType): Scope **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6084,6 +6188,8 @@ expand(range: Scope): Scope **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6138,6 +6244,8 @@ expand(value: ScopeType): Scope **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6190,6 +6298,8 @@ contains(value: ScopeType): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6242,6 +6352,8 @@ contains(range: Scope): boolean **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6297,6 +6409,8 @@ clamp(value: ScopeType): ScopeType **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6356,6 +6470,8 @@ Base64的构造函数。 **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **示例：** ```ts @@ -6374,6 +6490,8 @@ encodeSync(src: Uint8Array): Uint8Array **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6408,6 +6526,8 @@ encodeToStringSync(src: Uint8Array): string **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6442,6 +6562,8 @@ decodeSync(src: Uint8Array | string): Uint8Array **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6476,6 +6598,8 @@ encode(src: Uint8Array): Promise<Uint8Array> **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6511,6 +6635,8 @@ encodeToString(src: Uint8Array): Promise<string> **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | @@ -6547,6 +6673,8 @@ decode(src: Uint8Array | string): Promise<Uint8Array> **系统能力：** SystemCapability.Utils.Lang +**ArkTS版本：** 该接口仅适用于ArkTS1.1。 + **参数：** | 参数名 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis-distributedservice-kit/js-apis-distributedExtensionAbility.md b/zh-cn/application-dev/reference/apis-distributedservice-kit/js-apis-distributedExtensionAbility.md index b42cc63939f7ba02607015b9d8bed294f8525109..6a534d512699dfa394c60cf78e32d1540560b539 100644 --- a/zh-cn/application-dev/reference/apis-distributedservice-kit/js-apis-distributedExtensionAbility.md +++ b/zh-cn/application-dev/reference/apis-distributedservice-kit/js-apis-distributedExtensionAbility.md @@ -4,7 +4,7 @@ DistributedExtensionAbility模块提供分布式相关扩展能力，提供分 > **说明：** > -> 本模块首批接口从API version 18开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > > 本模块接口仅可在Stage模型下使用。 @@ -42,11 +42,11 @@ Extension生命周期回调，在创建时回调，执行初始化业务逻辑 import { Want } from '@kit.AbilityKit'; import { DistributedExtensionAbility} from '@kit.DistributedServiceKit'; -class DistributedExtensionAbility { - onCreate(want: Want) { - console.log(TAG, `DistributedExterntion Create ok`); - console.log(TAG, `DistributedExterntionon onCollabRequest ${JSON.stringify(want)}`); - console.log(TAG, `DistributedExterntionon Create end`); +export default class DistributedExtension extends DistributedExtensionAbility { + onCreate(want: Want) { + console.info(`DistributedExtension Create ok`); + console.info(`DistributedExtension on Create want: ${JSON.stringify(want)}`); + console.info(`DistributedExtension Create end`); } } ``` @@ -74,19 +74,19 @@ onCollaborate(wantParam: Record ) : AbilityConstant.CollaborateR **示例** ```ts -import { DistributedExtensionAbility} from '@kit.DistributedServiceKit'; +import { abilityConnectionManager, DistributedExtensionAbility } from '@kit.DistributedServiceKit'; import { AbilityConstant } from '@kit.AbilityKit'; -class DistributedExtensionAbility { - onCollaborate(wantParam: Record) { - console.info(TAG, `DistributedExterntionon onCollabRequest Accept to the result of Ability collaborate`); - let sessionId = -1; - const collabrationType = wantParam["CollabrationType"] as abilityConnectionManager.CollabrationType; - if (collabrationType == undefined) { - return sessionId; - } - console.info(TAG, `onCollab, peerInfo: ${JSON.stringify(collabrationType)}`); - return AbilityConstant.CollaborateResult.ACCEPT; +export default class DistributedExtension extends DistributedExtensionAbility { + onCollaborate(wantParam: Record) { + console.info(`DistributedExtension onCollabRequest Accept to the result of Ability collaborate`); + let sessionId = -1; + const collaborationValues = wantParam["CollaborationValues"] as abilityConnectionManager.CollaborationValues; + if (collaborationValues == undefined) { + return sessionId; + } + console.info(`onCollab, collaborationValues: ${JSON.stringify(collaborationValues)}`); + return AbilityConstant.CollaborateResult.ACCEPT; } } ``` @@ -104,9 +104,9 @@ Extension生命周期回调，在销毁时回调，执行资源清理等操作 ```ts import { DistributedExtensionAbility} from '@kit.DistributedServiceKit'; -class DistributedExtensionAbility{ +export default class DistributedExtension extends DistributedExtensionAbility { onDestroy() { - console.log('DistributedExterntion onDestroy ok'); + console.info('DistributedExtension onDestroy ok'); } } ``` diff --git a/zh-cn/application-dev/reference/apis-test-kit/js-apis-uitest.md b/zh-cn/application-dev/reference/apis-test-kit/js-apis-uitest.md index 4b7d00c88e3ec35f11ab79aac6c9d01ff69f54b8..a3112105c247ece0c673779697be8ec89f5ffab2 100644 --- a/zh-cn/application-dev/reference/apis-test-kit/js-apis-uitest.md +++ b/zh-cn/application-dev/reference/apis-test-kit/js-apis-uitest.md @@ -17,14 +17,59 @@ UiTest提供模拟UI操作的能力，供开发者在测试场景使用，主要 > - 本模块接口在[自动化测试脚本](../../application-test/arkxtest-guidelines.md)中使用。 > - 本模块接口不支持并发调用。 > - 本模块接口适用于手机、平板、2in1、智能穿戴设备。 - +> - ArkTS1.2中，本模块接口调用前需调用loadAndSetupUiTest接口初始化测试环境。 ## 导入模块 +ArkTS1.1: ```ts import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver } from '@kit.TestKit'; ``` +ArkTS1.2: +```ts +import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPattern, DisplayRotation, ResizeDirection, WindowMode, PointerMatrix, UiDirection, MouseButton, UIElementInfo, UIEventObserver, loadAndSetupUiTest } from '@kit.TestKit'; +``` + +## loadAndSetupUiTest20+ + +loadAndSetupUiTest(): void + +初始化测试环境，ArkTS1.2测试启动前必须调用一次。 + +**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 + +**系统能力**：SystemCapability.Test.UiTest + +**ArkTS版本**：该接口仅适用于ArkTS1.2。 + +**错误码：** + +以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 + +| 错误码ID | 错误信息 | +| -------- | ---------------------------------------- | +| 17000001 | Initialization failed. | + +**示例：** + +```ts +import { loadAndSetupUiTest } from '@kit.TestKit'; + +export default function demo() { + describe('uitestDemo', (): void => { + beforeAll(async () : Promise => { + try { + loadAndSetupUiTest(); + console.info("uitestDemo loadup over!!!!!") + } catch(error: Error) { + console.error(`uitestDemo, start abilityFailed: ${JSON.stringify(error)}`); + } + }) + } +} +``` + ## MatchPattern 控件属性支持的匹配模式。 @@ -67,9 +112,9 @@ import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPatter **系统能力**：SystemCapability.Test.UiTest | 名称 | 类型 | 可读 | 可写 | 说明 | -| ---- | ------ | ---- | ---- | ---------------- | -| x | number | 是 | 否 | 坐标点的横坐标。 | -| y | number | 是 | 否 | 坐标点的纵坐标。 | +| ---- | ------ | ---- | ---- |-----------| +| x | number | 是 | 否 | 坐标点的横坐标，取值大于0。 | +| y | number | 是 | 否 | 坐标点的纵坐标，取值大于0。 | ## Rect9+ @@ -81,10 +126,10 @@ import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPatter | 名称 | 类型 | 可读 | 可写 | 说明 | | ------ | ------ | ---- | ---- | ------------------------- | -| left | number | 是 | 否 | 控件边框的左上角的X坐标。 | -| top | number | 是 | 否 | 控件边框的左上角的Y坐标。 | -| right | number | 是 | 否 | 控件边框的右下角的X坐标。 | -| bottom | number | 是 | 否 | 控件边框的右下角的Y坐标。 | +| left | number | 是 | 否 | 控件边框的左上角的X坐标，取值大于0。 | +| top | number | 是 | 否 | 控件边框的左上角的Y坐标，取值大于0。 | +| right | number | 是 | 否 | 控件边框的右下角的X坐标，取值大于0。 | +| bottom | number | 是 | 否 | 控件边框的右下角的Y坐标，取值大于0。 | ## WindowMode9+ @@ -126,9 +171,9 @@ import { UiComponent, UiDriver, Component, Driver, UiWindow, ON, BY, MatchPatter | -------------------- | ------- | ---- | ---- | ------------------------------------------------------------ | | bundleName | string | 是 | 否 | 窗口归属应用的包名。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | | title | string | 是 | 否 | 窗口的标题信息。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | -| focused | boolean | 是 | 否 | 窗口是否处于获焦状态。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | -| actived(deprecated) | boolean | 是 | 否 | 窗口是否正与用户进行交互。
从API11开始，名称变更为active。 | -| active11+ | boolean | 是 | 否 | 窗口是否正与用户进行交互。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | +| focused | boolean | 是 | 否 | 窗口是否处于获焦状态，true：获焦状态，false：未获焦状态。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | +| actived(deprecated) | boolean | 是 | 否 | 窗口是否正与用户进行交互，true：交互状态，false：未交互状态。
从API version 11开始废弃，建议使用active替代。 +| active11+ | boolean | 是 | 否 | 窗口是否正与用户进行交互，true：交互状态，false：未交互状态。
**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | ## UiDirection10+ @@ -183,8 +228,8 @@ UI事件的相关信息。 **系统能力**：SystemCapability.Test.UiTest | 名称 | 类型 | 可读 | 可写 | 说明 | -| ---------- | ------ |----|----|----------------------------------------------------------| -| stay | boolean | 否 | 是 | 触摸板多指滑动结束是否停留1s后再抬起，默认为false（不停留1s）。 | +| ---------- | ------ |----|----|--------------------------------------------------------| +| stay | boolean | 否 | 是 | 触摸板多指滑动结束是否停留1s后再抬起，默认为false（不停留1s），true：停留，false：不停留。 | | speed | number | 否 | 是 | 滑动速率，取值范围为200-40000，默认值为2000，不在范围内设为默认值为2000，单位：px/s。 | ## On9+ @@ -309,7 +354,7 @@ id(id: string, pattern?: MatchPattern): On ```ts import { MatchPattern, On, ON } from '@kit.TestKit'; -let on:On = ON.id('id', MatchPattern.REG_EXP_ICASE) // 忽略大小写匹配控件的id属性值 +let on:On = ON.id('id', MatchPattern.REG_EXP_ICASE); // 忽略大小写匹配控件的id属性值 ``` ### type9+ @@ -409,7 +454,7 @@ clickable(b?: boolean): On | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | +| b | boolean | 否 | 指定控件可点击状态。true：可点击。false：不可点击。默认为true。 | **返回值：** @@ -446,7 +491,7 @@ longClickable(b?: boolean): On | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件可长按点击状态，true：可长按点击，false：不可长按点击。默认为true。 | +| b | boolean | 否 | 指定控件可长按点击状态。true：可长按点击。false：不可长按点击。默认为true。 | **返回值：** @@ -484,7 +529,7 @@ scrollable(b?: boolean): On | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ----------------------------------------------------------- | -| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | +| b | boolean | 否 | 控件可滑动状态。true：可滑动。false：不可滑动。默认为true。 | **返回值：** @@ -521,7 +566,7 @@ enabled(b?: boolean): On | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | --------------------------------------------------------- | -| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | +| b | boolean | 否 | 指定控件使能状态。true：使能。false：未使能。默认为true。 | **返回值：** @@ -558,7 +603,7 @@ focused(b?: boolean): On | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ----------------------------------------------------- | -| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | +| b | boolean | 否 | 控件获焦状态。true：获焦。false：未获焦。默认为true。 | **返回值：** @@ -595,7 +640,7 @@ selected(b?: boolean): On | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | +| b | boolean | 否 | 指定控件被选中状态。true：被选中。false：未被选中。默认为true。 | **返回值：** @@ -631,8 +676,8 @@ checked(b?: boolean): On **参数：** | 参数名 | 类型 | 必填 | 说明 | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件被勾选状态，true：被勾选，false：未被勾选。默认为false。 | +| ------ | ------- | ---- |----------------------------------------| +| b | boolean | 否 | 指定控件被勾选状态。true：被勾选。false：未被勾选。默认为true。 | **返回值：** @@ -668,8 +713,8 @@ checkable(b?: boolean): On **参数：** | 参数名 | 类型 | 必填 | 说明 | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件能否被勾选状态，true：能被勾选，false：不能被勾选。默认为false。 | +| ------ | ------- | ---- |-----------------------------------------| +| b | boolean | 否 | 指定控件能否被勾选状态。true：能被勾选。false：不能被勾选。默认为true。 | **返回值：** @@ -767,7 +812,7 @@ isAfter(on: On): On import { On, ON } from '@kit.TestKit'; // 使用静态构造器ON创建On对象，指定目标控件位于给出的特征属性控件之后。 -let on:On = ON.type('Text').isAfter(ON.text('123')) // 查找 text为123之后的第一个Text组件 +let on:On = ON.type('Text').isAfter(ON.text('123')); // 查找 text为123之后的第一个Text组件 ``` ### within10+ @@ -810,7 +855,7 @@ let on:On = ON.text('java').within(ON.type('Scroll')); // 查找Scroller里面 ### inWindow10+ -inWindow(bundleName: string): On; +inWindow(bundleName: string): On 指定目标控件位于给出的应用窗口内，返回On对象自身。 @@ -952,8 +997,10 @@ click(): Promise\ import { Driver, ON, Component } from '@kit.TestKit'; async function demo() { let driver:Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - await button.click(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + await button.click(); + } } ``` @@ -982,8 +1029,10 @@ doubleClick(): Promise\ import {Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - await button.doubleClick(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + await button.doubleClick(); + } } ``` @@ -1012,8 +1061,10 @@ longClick(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - await button.longClick(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + await button.longClick(); + } } ``` @@ -1048,8 +1099,10 @@ getId(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let id = await button.getId(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + let id = await button.getId(); + } } ``` @@ -1084,8 +1137,10 @@ getText(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let text = await button.getText(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + let text = await button.getText(); + } } ``` @@ -1120,8 +1175,10 @@ getType(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let type = await button.getType(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + let type = await button.getType(); + } } ``` @@ -1156,8 +1213,10 @@ getBounds(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let rect = await button.getBounds(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + let rect = await button.getBounds(); + } } ``` @@ -1192,8 +1251,10 @@ getBoundsCenter(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let point = await button.getBoundsCenter(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + let point = await button.getBoundsCenter(); + } } ``` @@ -1228,8 +1289,8 @@ isClickable(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - if(await button.isClickable()) { + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button && await button.isClickable()) { console.info('This button can be Clicked'); } else { console.info('This button can not be Clicked'); @@ -1268,8 +1329,8 @@ isLongClickable(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - if(await button.isLongClickable()) { + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button && await button.isLongClickable()) { console.info('This button can longClick'); } else { console.info('This button can not longClick'); @@ -1308,8 +1369,8 @@ isChecked(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); - if(await checkBox.isChecked()) { + let checkBox: Component|null = await driver.findComponent(ON.type('Checkbox')); + if (checkBox && await checkBox.isChecked()) { console.info('This checkBox is checked'); } else { console.info('This checkBox is not checked'); @@ -1348,8 +1409,8 @@ isCheckable(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let checkBox: Component = await driver.findComponent(ON.type('Checkbox')); - if(await checkBox.isCheckable()) { + let checkBox: Component|null = await driver.findComponent(ON.type('Checkbox')); + if (checkBox && await checkBox.isCheckable()) { console.info('This checkBox is checkable'); } else { console.info('This checkBox is not checkable'); @@ -1388,8 +1449,8 @@ isScrollable(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let scrollBar: Component = await driver.findComponent(ON.scrollable(true)); - if(await scrollBar.isScrollable()) { + let scrollBar: Component|null = await driver.findComponent(ON.scrollable(true)); + if (scrollBar && await scrollBar.isScrollable()) { console.info('This scrollBar can be operated'); } else { console.info('This scrollBar can not be operated'); @@ -1429,8 +1490,8 @@ isEnabled(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - if(await button.isEnabled()) { + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button && await button.isEnabled()) { console.info('This button can be operated'); } else { console.info('This button can not be operated'); @@ -1469,8 +1530,8 @@ isFocused(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - if(await button.isFocused()) { + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button && await button.isFocused()) { console.info('This button is focused'); } else { console.info('This button is not focused'); @@ -1509,8 +1570,8 @@ isSelected(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - if(await button.isSelected()) { + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button && await button.isSelected()) { console.info('This button is selected'); } else { console.info('This button is not selected'); @@ -1536,7 +1597,7 @@ inputText(text: string): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1550,8 +1611,10 @@ inputText(text: string): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let text: Component = await driver.findComponent(ON.text('hello world')); - await text.inputText('123'); + let text: Component|null = await driver.findComponent(ON.text('hello world')); + if (text) { + await text.inputText('123'); + } } ``` @@ -1559,7 +1622,7 @@ async function demo() { clearText(): Promise\ -清除控件的文本信息(适用于文本框控件)。 +清除控件的文本信息（适用于文本框控件）。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 @@ -1579,14 +1642,18 @@ clearText(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let text: Component = await driver.findComponent(ON.text('hello world')); - await text.clearText(); + let text: Component|null = await driver.findComponent(ON.text('hello world')); + if (text) { + await text.clearText(); + } } ``` ### scrollSearch9+ -scrollSearch(on: On): Promise\ +ArkTS1.1: scrollSearch(on: On): Promise\ + +ArkTS1.2: scrollSearch(on: On): Promise\ 在控件上滑动查找目标控件（适用支持滑动的控件），使用Promise异步回调。 @@ -1602,13 +1669,19 @@ scrollSearch(on: On): Promise\ **返回值：** +ArkTS1.1: | 类型 | 说明 | | ---------------------------------- | ------------------------------------- | | Promise\<[Component](#component9)> | 以Promise形式返回找到的目标控件对象。 | +ArkTS1.2: +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\<[Component](#component9)\|null> | Promise对象，返回找到的目标控件对象。在未找到目标对象时以Promise形式返回null。 | + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1623,14 +1696,21 @@ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); - let button = await scrollBar.scrollSearch(ON.text('next page')); + let scrollBar: Component|null = await driver.findComponent(ON.type('Scroll')); + if (scrollBar) { + let button = await scrollBar.scrollSearch(ON.text('next page')); + if (button) { + await button.click(); + } + } } ``` ### scrollSearch18+ -scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\ +ArkTS1.1: scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\ + +ArkTS1.2: scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\ 在控件上滑动查找目标控件（适用支持滑动的控件），使用Promise异步回调。 @@ -1644,14 +1724,20 @@ scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\ |------------------------| ---------- | ---- |-----------------------------------| | on | [On](#on9) | 是 | 目标控件的属性要求。 | | vertical | boolean | 否 | 默认为true，表示查找方向是纵向。false表示查找方向为横向。 | -| offset | number| 否 | 滑动起点/终点到组件边框的偏移, 默认80，单位：px。 | +| offset | number| 否 | 滑动起点/终点到组件边框的偏移，默认80，单位：px，取值大于等于0的整数。 | **返回值：** +ArkTS1.1: | 类型 | 说明 | | ---------------------------------- | ------------------------------------- | | Promise\<[Component](#component9)> | 以Promise形式返回找到的目标控件对象。 | +ArkTS1.2: +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\<[Component](#component9)\|null> | Promise对象，返回找到的目标控件对象。在未找到目标对象时以Promise形式返回null。 | + **错误码：** 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 @@ -1668,8 +1754,13 @@ scrollSearch(on: On, vertical?: boolean, offset?: number): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); - let button = await scrollBar.scrollSearch(ON.text('next page')); + let scrollBar: Component|null = await driver.findComponent(ON.type('Scroll')); + if (scrollBar) { + let button = await scrollBar.scrollSearch(ON.text('next page')); + if (button) { + await button.click(); + } + } } ``` @@ -1677,7 +1768,7 @@ async function demo() { scrollToTop(speed?: number): Promise\ -在控件上滑动到顶部(适用支持滑动的控件)。 +在控件上滑动到顶部（适用支持滑动的控件）。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 @@ -1691,7 +1782,7 @@ scrollToTop(speed?: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1705,8 +1796,10 @@ scrollToTop(speed?: number): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); - await scrollBar.scrollToTop(); + let scrollBar: Component|null = await driver.findComponent(ON.type('Scroll')); + if (scrollBar) { + await scrollBar.scrollToTop(); + } } ``` @@ -1714,7 +1807,7 @@ async function demo() { scrollToBottom(speed?: number): Promise\ -在控件上滑动到底部(适用支持滑动的控件)。 +在控件上滑动到底部（适用支持滑动的控件）。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 @@ -1728,7 +1821,7 @@ scrollToBottom(speed?: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1742,7 +1835,7 @@ scrollToBottom(speed?: number): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let scrollBar: Component = await driver.findComponent(ON.type('Scroll')); + let scrollBar: Component|null = await driver.findComponent(ON.type('Scroll')); await scrollBar.scrollToBottom(); } ``` @@ -1769,7 +1862,7 @@ dragTo(target: Component): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1783,9 +1876,11 @@ dragTo(target: Component): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let text: Component = await driver.findComponent(ON.text('hello world')); - await button.dragTo(text); + let button: Component|null = await driver.findComponent(ON.type('Button')); + let text: Component|null = await driver.findComponent(ON.text('hello world')); + if (button && text) { + await button.dragTo(text); + } } ``` @@ -1807,7 +1902,7 @@ pinchOut(scale: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1821,8 +1916,10 @@ pinchOut(scale: number): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let image: Component = await driver.findComponent(ON.type('Image')); - await image.pinchOut(1.5); + let image: Component|null = await driver.findComponent(ON.type('Image')); + if (image) { + await image.pinchOut(1.5); + } } ``` @@ -1844,7 +1941,7 @@ pinchIn(scale: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -1858,8 +1955,10 @@ pinchIn(scale: number): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let image: Component = await driver.findComponent(ON.type('Image')); - await image.pinchIn(0.5); + let image: Component|null = await driver.findComponent(ON.type('Image')); + if (image) { + await image.pinchIn(0.5); + } } ``` @@ -1881,7 +1980,7 @@ getDescription(): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -1894,8 +1993,10 @@ getDescription(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('Button')); - let description = await button.getDescription(); + let button: Component|null = await driver.findComponent(ON.type('Button')); + if (button) { + let description = await button.getDescription(); + } } ``` ### getHint18+ @@ -1912,7 +2013,7 @@ getHint(): Promise\ | 类型 | 说明 | | ---------------- |----------------------| -| Promise\ | 以Promise形式返回控件的提示文本。 | +| Promise\ | Promise对象，返回控件的提示文本。 | **错误码：** @@ -1929,8 +2030,10 @@ getHint(): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.type('TextInput')); - let hints = await button.getHint(); + let button: Component|null = await driver.findComponent(ON.type('TextInput')); + if (button) { + let hints = await button.getHint(); + } } ``` @@ -1990,7 +2093,7 @@ Driver对象在给定的时间内延时。 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2009,7 +2112,9 @@ async function demo() { ### findComponent9+ -findComponent(on: On): Promise\ +ArkTS1.1: findComponent(on: On): Promise\ + +ArkTS1.2: findComponent(on: On): Promise\ 在Driver对象中，根据给出的目标控件属性要求查找目标控件。 @@ -2025,13 +2130,19 @@ findComponent(on: On): Promise\ **返回值：** -| 类型 | 说明 | +ArkTS1.1: +| 类型 | 说明 | | ---------------------------------- | --------------------------------- | | Promise\<[Component](#component9)> | 以Promise形式返回找到的控件对象。 | +ArkTS1.2: +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\<[Component](#component9)\|null> | Promise对象，返回找到的目标控件对象。在未找到目标对象时以Promise形式返回null。 | + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2044,13 +2155,18 @@ findComponent(on: On): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.findComponent(ON.text('next page')); + let button: Component|null = await driver.findComponent(ON.text('next page')); + if (button) { + await button.click(); + } } ``` ### findComponents9+ -findComponents(on: On): Promise\> +ArkTS1.1: findComponents(on: On): Promise\> + +ArkTS1.2: findComponents(on: On): Promise\\|null> 在Driver对象中，根据给出的目标控件属性要求查找出所有匹配控件，以列表保存。 @@ -2066,13 +2182,19 @@ findComponents(on: On): Promise\> **返回值：** -| 类型 | 说明 | +ArkTS1.1: +| 类型 | 说明 | | ------------------------------------------ | --------------------------------------- | | Promise\> | 以Promise形式返回找到的控件对象的列表。 | +ArkTS1.2: +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\\|null\> | Promise对象，返回找到的控件对象的列表。在未找到目标对象时以Promise形式返回null。 | + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2085,13 +2207,18 @@ findComponents(on: On): Promise\> import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let buttonList: Array = await driver.findComponents(ON.text('next page')); + let buttonList: Array|null = await driver.findComponents(ON.text('next page')); + if (buttonList) { + await buttonList[0].click(); + } } ``` ### findWindow9+ -findWindow(filter: WindowFilter): Promise\ +ArkTS1.1: findWindow(filter: WindowFilter): Promise\ + +ArkTS1.2: findWindow(filter: WindowFilter): Promise\ 通过指定窗口的属性来查找目标窗口。 @@ -2107,13 +2234,20 @@ findWindow(filter: WindowFilter): Promise\ **返回值：** -| 类型 | 说明 | +ArkTS1.1: +| 类型 | 说明 | | -------------------------------- | ------------------------------------- | | Promise\<[UiWindow](#uiwindow9)> | 以Promise形式返回找到的目标窗口对象。 | +ArkTS1.2: +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\<[UiWindow](#uiwindow9)\|null> | Promise对象，返回找到的目标窗口对象，在未找到目标窗口对象时以Promise形式返回null。 | + + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2126,13 +2260,18 @@ findWindow(filter: WindowFilter): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let name: string = window.getBundleName(); + } } ``` ### waitForComponent9+ -waitForComponent(on: On, time: number): Promise\ +ArkTS1.1: waitForComponent(on: On, time: number): Promise\ + +ArkTS1.2: waitForComponent(on: On, time: number): Promise\ 在Driver对象中，在用户给定的时间内，持续查找满足控件属性要求的目标控件。 @@ -2149,13 +2288,19 @@ waitForComponent(on: On, time: number): Promise\ **返回值：** -| 类型 | 说明 | +ArkTS1.1: +| 类型 | 说明 | | --------------------------------- | --------------------------------- | | Promise\<[Component](#component9)> | 以Promise形式返回找到的控件对象。 | +ArkTS1.2: +| 类型 | 说明 | +| ---------------------------------- | ------------------------------------- | +| Promise\<[Component](#component9)\|null> | Promise对象，返回找到的控件对象，在未找到目标对象时以Promise形式返回null。 | + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2168,7 +2313,10 @@ waitForComponent(on: On, time: number): Promise\ import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let button: Component = await driver.waitForComponent(ON.text('next page'),500); + let button: Component|null = await driver.waitForComponent(ON.text('next page'),500); + if (button) { + let buttonId: string = button.id(); + } } ``` @@ -2190,7 +2338,7 @@ assertComponentExist(on: On): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2250,11 +2398,11 @@ Driver对象采取如下操作：传入key值实现模拟点击对应按键的 | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ------------- | -| keyCode | number | 是 | 指定的key值。 | +| keyCode | number | 是 | 指定的key值，取值大于等于0的整数。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2285,13 +2433,13 @@ Driver对象通过给定的key值，找到对应组合键并点击。例如，Ke | 参数名 | 类型 | 必填 | 说明 | | ------ | ------ | ---- | ------------------------------ | -| key0 | number | 是 | 指定的第一个key值。 | -| key1 | number | 是 | 指定的第二个key值。 | -| key2 | number | 否 | 指定的第三个key值。默认值为0。 | +| key0 | number | 是 | 指定的第一个key值，取值大于等于0。 | +| key1 | number | 是 | 指定的第二个key值，取值大于等于0。 | +| key2 | number | 否 | 指定的第三个key值。默认值为0，取值大于等于0。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2328,7 +2476,7 @@ Driver对象采取如下操作：在目标坐标点单击。 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2364,7 +2512,7 @@ Driver对象采取如下操作：在目标坐标点双击。 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2400,7 +2548,7 @@ Driver对象采取如下操作：在目标坐标点长按。 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2439,7 +2587,7 @@ Driver对象采取如下操作：从起始坐标点滑向目的坐标点。 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2452,7 +2600,7 @@ Driver对象采取如下操作：从起始坐标点滑向目的坐标点。 import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.swipe(100,100,200,200,600); + await driver.swipe(100, 100, 200, 200, 600); } ``` @@ -2482,7 +2630,7 @@ Driver对象采取如下操作：从起始坐标点拖拽至目的坐标点。 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2495,7 +2643,7 @@ Driver对象采取如下操作：从起始坐标点拖拽至目的坐标点。 import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.drag(100,100,200,200,600); + await driver.drag(100, 100, 200, 200, 600); } ``` @@ -2523,7 +2671,7 @@ Driver对象采取如下操作：捕获当前屏幕，并保存为PNG格式的 **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2562,7 +2710,7 @@ setDisplayRotation(rotation: DisplayRotation): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2631,11 +2779,11 @@ setDisplayRotationEnabled(enabled: boolean): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ------- | ------- | ---- | ------------------------------------------------------- | -| enabled | boolean | 是 | 能否旋转屏幕的标识，true：可以旋转，false：不可以旋转。 | +| enabled | boolean | 是 | 能否旋转屏幕的标识。true：可以旋转。false：不可以旋转。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2802,11 +2950,11 @@ waitForIdle(idleTime: number, timeout: number): Promise\ | 类型 | 说明 | | ----------------- | --------------------------------------------------- | -| Promise\ | 以Promise的形式返回当前界面的所有控件是否已经空闲。 | +| Promise\ | 以Promise的形式返回当前界面的所有控件是否已经空闲，true：已经空闲，false：不空闲。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2844,7 +2992,7 @@ fling(from: Point, to: Point, stepLen: number, speed: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2857,7 +3005,7 @@ fling(from: Point, to: Point, stepLen: number, speed: number): Promise\ import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.fling({x: 500, y: 480},{x: 450, y: 480},5,600); + await driver.fling({x: 500, y: 480},{x: 450, y: 480}, 5, 600); } ``` @@ -2882,11 +3030,11 @@ injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\ | 以Promise的形式返回操作是否成功完成。 | +| Promise\ | 以Promise的形式返回操作是否成功完成，true：完成，false：未完成。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -2899,17 +3047,17 @@ injectMultiPointerAction(pointers: PointerMatrix, speed?: number): Promise\; **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -2975,7 +3123,7 @@ screenCapture(savePath: string, rect?: Rect): Promise\; **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3008,12 +3156,12 @@ mouseClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Promise\ | ------ | ----------------------------- | ---- | ------------------------------ | | p | [Point](#point9) | 是 | 鼠标点击的坐标。 | | btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | -| key1 | number | 否 | 指定的第一个key值。默认值为0。 | -| key2 | number | 否 | 指定的第二个key值。默认值为0。 | +| key1 | number | 否 | 指定的第一个key值。默认值为0，取值大于等于0。 | +| key2 | number | 否 | 指定的第二个key值。默认值为0，取值大于等于0。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3045,14 +3193,14 @@ mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): P | 参数名 | 类型 | 必填 | 说明 | | ------ | ---------------- | ---- | ----------------------------------------------------------- | | p | [Point](#point9) | 是 | 鼠标点击的坐标。 | -| down | boolean | 是 | 滚轮滑动方向是否向下，true表示向下滑动，false表示向上滚动。 | -| d | number | 是 | 鼠标滚轮滚动的格数，每格对应目标点位移120px。 | -| key1 | number | 否 | 指定的第一个key值。默认值为0。 | -| key2 | number | 否 | 指定的第二个key值。默认值为0。 | +| down | boolean | 是 | 滚轮滑动方向是否向下。true表示向下滑动。false表示向上滚动。 | +| d | number | 是 | 鼠标滚轮滚动的格数，每格对应目标点位移120px，取值大于等于0。 | +| key1 | number | 否 | 指定的第一个key值。默认值为0，取值大于等于0。 | +| key2 | number | 否 | 指定的第二个key值。默认值为0，取值大于等于0。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3065,7 +3213,7 @@ mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number): P import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.mouseScroll({x:360, y:640}, true, 30, 2072) + await driver.mouseScroll({x:360, y:640}, true, 30, 2072); } ``` @@ -3087,7 +3235,7 @@ mouseMoveTo(p: Point): Promise\; **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3100,7 +3248,7 @@ mouseMoveTo(p: Point): Promise\; import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.mouseMoveTo({x:100, y:100}) + await driver.mouseMoveTo({x:100, y:100}); } ``` @@ -3134,7 +3282,7 @@ createUIEventObserver(): UIEventObserver; import { Driver, UIEventObserver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let observer: UIEventObserver = await driver.createUIEventObserver() + let observer: UIEventObserver = await driver.createUIEventObserver(); } ``` @@ -3153,15 +3301,15 @@ mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, sp | 参数名 | 类型 | 必填 | 说明 | | ------ | ---------------- | ---- | ------------------------------------------------------------ | | p | [Point](#point9) | 是 | 鼠标点击的坐标。 | -| down | boolean | 是 | 滚轮滑动方向是否向下，true表示向下滑动，false表示向上滚动。 | -| d | number | 是 | 鼠标滚轮滚动的格数，每格对应目标点位移120px。 | -| key1 | number | 否 | 指定的第一个key值。默认值为0。 | -| key2 | number | 否 | 指定的第二个key值。默认值为0。 | +| down | boolean | 是 | 滚轮滑动方向是否向下。true表示向下滑动。false表示向上滚动。 | +| d | number | 是 | 鼠标滚轮滚动的格数，每格对应目标点位移120px，取值大于等于0的整数。 | +| key1 | number | 否 | 指定的第一个key值。默认值为0，取值大于等于0的整数。 | +| key2 | number | 否 | 指定的第二个key值。默认值为0，取值大于等于0的整数。 | | speed | number | 否 | 鼠标滚轮滚动的速度，范围：1-500，不在范围内设为默认值为20，单位：格/秒。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3174,7 +3322,7 @@ mouseScroll(p: Point, down: boolean, d: number, key1?: number, key2?: number, sp import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.mouseScroll({x:360, y:640}, true, 30, 2072,20) + await driver.mouseScroll({x:360, y:640}, true, 30, 2072, 20); } ``` @@ -3194,12 +3342,12 @@ mouseDoubleClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Pr | ------ | ----------------------------- | ---- | ------------------------------ | | p | [Point](#point9) | 是 | 鼠标双击的坐标。 | | btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | -| key1 | number | 否 | 指定的第一个key值。默认值为0。 | -| key2 | number | 否 | 指定的第二个key值。默认值为0。 | +| key1 | number | 否 | 指定的第一个key值。默认值为0，取值大于等于0。 | +| key2 | number | 否 | 指定的第二个key值。默认值为0，取值大于等于0。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3232,12 +3380,12 @@ mouseLongClick(p: Point, btnId: MouseButton, key1?: number, key2?: number): Prom | ------ | ----------------------------- | ---- | ------------------------------ | | p | [Point](#point9) | 是 | 鼠标长按的坐标。 | | btnId | [MouseButton](#mousebutton10) | 是 | 按下的鼠标按钮。 | -| key1 | number | 否 | 指定的第一个key值。默认值为0。 | -| key2 | number | 否 | 指定的第二个key值。默认值为0。 | +| key1 | number | 否 | 指定的第一个key值。默认值为0，取值大于等于0。 | +| key2 | number | 否 | 指定的第二个key值。默认值为0，取值大于等于0。 | **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3274,7 +3422,7 @@ mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3287,7 +3435,7 @@ mouseMoveWithTrack(from: Point, to: Point, speed?: number): Promise\ import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.mouseMoveWithTrack({x:100, y:100},{x:200, y:200},600); + await driver.mouseMoveWithTrack({x:100, y:100}, {x:200, y:200}, 600); } ``` @@ -3315,7 +3463,7 @@ mouseDrag(from: Point, to: Point, speed?: number): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3328,7 +3476,7 @@ mouseDrag(from: Point, to: Point, speed?: number): Promise\ import { Driver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - await driver.mouseDrag({x:100, y:100},{x:200, y:200},600); + await driver.mouseDrag({x:100, y:100},{x:200, y:200}, 600); } ``` @@ -3351,7 +3499,7 @@ inputText(p: Point, text: string): Promise\ **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | @@ -3363,10 +3511,12 @@ inputText(p: Point, text: string): Promise\ ```ts import { Component, Driver, ON } from '@kit.TestKit'; async function demo() { - let driver:Driver = Driver.create(); - let text: Component = await driver.findComponent(ON.type('TextInput')); - let point = await text.getBoundsCenter(); - await driver.inputText(point, '123'); + let driver: Driver = Driver.create(); + let text: Component|null = await driver.findComponent(ON.type('TextInput')); + if (text) { + let point = await text.getBoundsCenter(); + await driver.inputText(point, '123'); + } } ``` @@ -3627,7 +3777,7 @@ injectPenPointerAction(pointers: PointerMatrix, speed?: number, pressure?: numbe import { Driver, PointerMatrix } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let pointer = PointerMatrix.create(1,8); + let pointer = PointerMatrix.create(1, 8); for (let step = 0; step < 8; step++) { pointer.setPoint(0, step, {x: 500, y: 1100 - 100 *step}); } @@ -3653,8 +3803,8 @@ static create(fingers: number, steps: number): PointerMatrix | 参数名 | 类型 | 必填 | 说明 | | ------- | ------ | ---- | ------------------------------------------ | -| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1,10]。 | -| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1,1000]。 | +| fingers | number | 是 | 多指操作中注入的手指数，取值范围：[1, 10]。 | +| steps | number | 是 | 每根手指操作的步骤数，取值范围：[1, 1000]。 | **返回值：** @@ -3675,7 +3825,7 @@ static create(fingers: number, steps: number): PointerMatrix ```ts import { PointerMatrix } from '@kit.TestKit'; async function demo() { - let pointerMatrix: PointerMatrix = PointerMatrix.create(2,3); + let pointerMatrix: PointerMatrix = PointerMatrix.create(2, 3); } ``` @@ -3710,17 +3860,17 @@ setPoint(finger: number, step: number, point: Point): void ```ts import { PointerMatrix } from '@kit.TestKit'; async function demo() { - let pointers: PointerMatrix = PointerMatrix.create(2,5); - pointers.setPoint(0,0,{x:250,y:480}); - pointers.setPoint(0,1,{x:250,y:440}); - pointers.setPoint(0,2,{x:250,y:400}); - pointers.setPoint(0,3,{x:250,y:360}); - pointers.setPoint(0,4,{x:250,y:320}); - pointers.setPoint(1,0,{x:250,y:480}); - pointers.setPoint(1,1,{x:250,y:440}); - pointers.setPoint(1,2,{x:250,y:400}); - pointers.setPoint(1,3,{x:250,y:360}); - pointers.setPoint(1,4,{x:250,y:320}); + let pointers: PointerMatrix = PointerMatrix.create(2, 5); + pointers.setPoint(0, 0, {x:250, y:480}); + pointers.setPoint(0, 1, {x:250, y:440}); + pointers.setPoint(0, 2, {x:250, y:400}); + pointers.setPoint(0, 3, {x:250, y:360}); + pointers.setPoint(0, 4, {x:250, y:320}); + pointers.setPoint(1, 0, {x:250, y:480}); + pointers.setPoint(1, 1, {x:250, y:440}); + pointers.setPoint(1, 2, {x:250, y:400}); + pointers.setPoint(1, 3, {x:250, y:360}); + pointers.setPoint(1, 4, {x:250, y:320}); } ``` @@ -3761,8 +3911,10 @@ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - let name: string = await window.getBundleName(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let name: string = await window.getBundleName(); + } } ``` @@ -3797,8 +3949,10 @@ getBounds(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - let rect = await window.getBounds(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let rect = await window.getBounds(); + } } ``` @@ -3833,8 +3987,10 @@ getTitle(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - let rect = await window.getTitle(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let rect = await window.getTitle(); + } } ``` @@ -3869,8 +4025,10 @@ getWindowMode(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - let mode = await window.getWindowMode(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let mode = await window.getWindowMode(); + } } ``` @@ -3905,8 +4063,10 @@ isFocused(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - let focused = await window.isFocused(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let focused = await window.isFocused(); + } } ``` @@ -3941,8 +4101,10 @@ isActived(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - let focused = await window.isActived(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + let focused = await window.isActived(); + } } ``` @@ -3956,6 +4118,12 @@ focus(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**返回值：** + +| 类型 | 说明 | +|----------------|-----------------| +| Promise\ | Promise对象，返回无结果的Promise对象。 | + **错误码：** 以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 @@ -3971,8 +4139,10 @@ focus(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.focus(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.focus(); + } } ``` @@ -3993,9 +4163,15 @@ moveTo(x: number, y: number): Promise\ | x | number | 是 | 以number的形式传入目标点的横坐标信息，取值大于等于0。 | | y | number | 是 | 以number的形式传入目标点的纵坐标信息，取值大于等于0。 | +**返回值：** + +| 类型 | 说明 | +|----------------|-----------------| +| Promise\ | Promise对象，返回无结果的Promise对象。 | + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -4010,8 +4186,10 @@ moveTo(x: number, y: number): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.moveTo(100, 100); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.moveTo(100, 100); + } } ``` @@ -4029,13 +4207,19 @@ resize(wide: number, height: number, direction: ResizeDirection): Promise\ | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------------ | ---- | ------------------------------------------------------------ | -| wide | number | 是 | 以number的形式传入调整后窗口的宽度。 | -| height | number | 是 | 以number的形式传入调整后窗口的高度。 | +| wide | number | 是 | 以number的形式传入调整后窗口的宽度，取值大于等于0。 | +| height | number | 是 | 以number的形式传入调整后窗口的高度，取值大于等于0。 | | direction | [ResizeDirection](#resizedirection9) | 是 | 以[ResizeDirection](#resizedirection9)的形式传入窗口调整的方向。 | +**返回值：** + +| 类型 | 说明 | +|----------------|-----------------| +| Promise\ | Promise对象，返回无结果的Promise对象。 | + **错误码：** -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[uitest测试框架错误码](errorcode-uitest.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | @@ -4050,8 +4234,10 @@ resize(wide: number, height: number, direction: ResizeDirection): Promise\ import { Driver, ResizeDirection, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.resize(100, 100, ResizeDirection.LEFT); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.resize(100, 100, ResizeDirection.LEFT); + } } ``` @@ -4065,6 +4251,12 @@ split(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**返回值：** + +| 类型 | 说明 | +|----------------|-----------------| +| Promise\ | Promise对象，返回无结果的Promise对象。 | + **错误码：** 以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 @@ -4081,8 +4273,10 @@ split(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.split(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.split(); + } } ``` @@ -4096,6 +4290,12 @@ maximize(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**返回值：** + +| 类型 | 说明 | +|----------------|-----------------| +| Promise\ | Promise对象，返回无结果的Promise对象。 | + **错误码：** 以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 @@ -4112,8 +4312,10 @@ maximize(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.maximize(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.maximize(); + } } ``` @@ -4127,6 +4329,12 @@ minimize(): Promise\ **系统能力**：SystemCapability.Test.UiTest +**返回值：** + +| 类型 | 说明 | +|----------------|-----------------| +| Promise\ | Promise对象，返回无结果的Promise对象。 | + **错误码：** 以下错误码的详细介绍请参见[uitest测试框架错误码](errorcode-uitest.md)。 @@ -4143,8 +4351,10 @@ minimize(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.minimize(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.minimize(); + } } ``` @@ -4174,8 +4384,10 @@ resume(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.resume(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.resume(); + } } ``` @@ -4205,8 +4417,10 @@ close(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver:Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({actived: true}); - await window.close(); + let window: UiWindow|null = await driver.findWindow({actived: true}); + if (window) { + await window.close(); + } } ``` @@ -4241,8 +4455,10 @@ isActive(): Promise\ import { Driver, UiWindow } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let window: UiWindow = await driver.findWindow({active: true}); - let focused = await window.isActive(); + let window: UiWindow|null = await driver.findWindow({active: true}); + if (window) { + let focused = await window.isActive(); + } } ``` @@ -4281,13 +4497,13 @@ once(type: 'toastShow', callback: Callback\): void; import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let observer: UIEventObserver = await driver.createUIEventObserver() + let observer: UIEventObserver = await driver.createUIEventObserver(); let callback = (UIElementInfo: UIElementInfo)=>{ - console.info(UIElementInfo.bundleName) - console.info(UIElementInfo.text) - console.info(UIElementInfo.type) + console.info(UIElementInfo.bundleName); + console.info(UIElementInfo.text); + console.info(UIElementInfo.type); } - observer.once('toastShow', callback) + observer.once('toastShow', callback); } ``` @@ -4305,8 +4521,8 @@ once(type: 'dialogShow', callback: Callback\): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------------- | ---- | ---------------------------------- | -| type | string | 是 | 订阅的事件类型，取值为'dialogShow' | -| callback | Callback\<[UIElementInfo](#uielementinfo10)> | 是 | 事件发生时执行的回调函数 | +| type | string | 是 | 订阅的事件类型，取值为'dialogShow'。 | +| callback | Callback\<[UIElementInfo](#uielementinfo10)> | 是 | 事件发生时执行的回调函数。 | **错误码：** @@ -4322,13 +4538,13 @@ once(type: 'dialogShow', callback: Callback\): void; import { Driver, UIElementInfo, UIEventObserver } from '@kit.TestKit'; async function demo() { let driver: Driver = Driver.create(); - let observer: UIEventObserver = await driver.createUIEventObserver() + let observer: UIEventObserver = await driver.createUIEventObserver(); let callback = (UIElementInfo: UIElementInfo)=>{ - console.info(UIElementInfo.bundleName) - console.info(UIElementInfo.text) - console.info(UIElementInfo.type) + console.info(UIElementInfo.bundleName); + console.info(UIElementInfo.text); + console.info(UIElementInfo.type); } - observer.once('dialogShow', callback) + observer.once('dialogShow', callback); } ``` @@ -4479,7 +4695,7 @@ clickable(b?: boolean): By | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件可点击状态，true：可点击，false：不可点击。默认为true。 | +| b | boolean | 否 | 指定控件可点击状态。true：可点击。false：不可点击。默认为true。 | **返回值：** @@ -4509,7 +4725,7 @@ scrollable(b?: boolean): By | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ----------------------------------------------------------- | -| b | boolean | 否 | 控件可滑动状态，true：可滑动，false：不可滑动。默认为true。 | +| b | boolean | 否 | 控件可滑动状态。true：可滑动。false：不可滑动。默认为true。 | **返回值：** @@ -4538,7 +4754,7 @@ enabled(b?: boolean): By | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | --------------------------------------------------------- | -| b | boolean | 否 | 指定控件使能状态，true：使能，false：未使能。默认为true。 | +| b | boolean | 否 | 指定控件使能状态。true：使能。false：未使能。默认为true。 | **返回值：** @@ -4567,7 +4783,7 @@ focused(b?: boolean): By | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ----------------------------------------------------- | -| b | boolean | 否 | 控件获焦状态，true：获焦，false：未获焦。默认为true。 | +| b | boolean | 否 | 控件获焦状态。true：获焦。false：未获焦。默认为true。 | **返回值：** @@ -4596,7 +4812,7 @@ selected(b?: boolean): By | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | -| b | boolean | 否 | 指定控件被选中状态，true：被选中，false：未被选中。默认为true。 | +| b | boolean | 否 | 指定控件被选中状态。true：被选中。false：未被选中。默认为true。 | **返回值：** @@ -4874,7 +5090,7 @@ import { UiDriver, BY, UiComponent } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); let button: UiComponent = await driver.findComponent(BY.type('Button')); - if(await button.isClickable()) { + if (await button.isClickable()) { console.info('This button can be Clicked'); } else { console.info('This button can not be Clicked'); @@ -4905,7 +5121,7 @@ import { UiDriver, BY, UiComponent } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); let scrollBar: UiComponent = await driver.findComponent(BY.scrollable(true)); - if(await scrollBar.isScrollable()) { + if (await scrollBar.isScrollable()) { console.info('This scrollBar can be operated'); } else { console.info('This scrollBar can not be operated'); @@ -4937,7 +5153,7 @@ import { UiDriver, BY, UiComponent } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); let button: UiComponent = await driver.findComponent(BY.type('Button')); - if(await button.isEnabled()) { + if (await button.isEnabled()) { console.info('This button can be operated'); } else { console.info('This button can not be operated'); @@ -4969,7 +5185,7 @@ import { UiDriver, BY, UiComponent } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); let button: UiComponent = await driver.findComponent(BY.type('Button')); - if(await button.isFocused()) { + if (await button.isFocused()) { console.info('This button is focused'); } else { console.info('This button is not focused'); @@ -5000,7 +5216,7 @@ import { UiDriver, BY, UiComponent } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); let button: UiComponent = await driver.findComponent(BY.type('Button')); - if(await button.isSelected()) { + if (await button.isSelected()) { console.info('This button is selected'); } else { console.info('This button is not selected'); @@ -5012,7 +5228,7 @@ async function demo() { inputText(text: string): Promise\ -向控件中输入文本(适用于文本框控件)。 +向控件中输入文本（适用于文本框控件）。 从API version 9开始不再维护，建议使用[inputText9+](#inputtext9)。 @@ -5039,7 +5255,7 @@ async function demo() { scrollSearch(by: By): Promise\ -在控件上滑动查找目标控件(适用于List等支持滑动的控件)。 +在控件上滑动查找目标控件（适用于List等支持滑动的控件）。 从API version 9开始不再维护，建议使用[scrollSearch9+](#scrollsearch9)。 @@ -5296,7 +5512,7 @@ UiDriver对象采取如下操作：在目标坐标点单击。 import { UiDriver } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); - await driver.click(100,100); + await driver.click(100, 100); } ``` @@ -5323,7 +5539,7 @@ UiDriver对象采取如下操作：在目标坐标点双击。 import { UiDriver } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); - await driver.doubleClick(100,100); + await driver.doubleClick(100, 100); } ``` @@ -5350,7 +5566,7 @@ UiDriver对象采取如下操作：在目标坐标点长按下鼠标左键。 import { UiDriver } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); - await driver.longClick(100,100); + await driver.longClick(100, 100); } ``` @@ -5379,7 +5595,7 @@ UiDriver对象采取如下操作：从给出的起始坐标点滑向给出的目 import { UiDriver } from '@kit.TestKit'; async function demo() { let driver: UiDriver = UiDriver.create(); - await driver.swipe(100,100,200,200); + await driver.swipe(100, 100, 200, 200); } ``` @@ -5413,4 +5629,4 @@ async function demo() { let driver: UiDriver = UiDriver.create(); await driver.screenCap('/data/storage/el2/base/cache/1.png'); } -``` \ No newline at end of file +``` diff --git a/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth-sys.md b/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth-sys.md index 5af420ca59acf71c2982a84b4ad0689a4f9e011c..89fede7f0df48c9a7cd3e7dcf6bd5a2ac3f49ebb 100644 --- a/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth-sys.md +++ b/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth-sys.md @@ -274,7 +274,9 @@ try { ### sendCommand10+ -sendCommand(cmdData: string): void +ArkTS1.1: sendCommand(cmdData: string): void + +ArkTS1.2: sendCommand: (cmdData: string) => void 回调函数，用于用户认证框架向组件发送命令。 @@ -290,6 +292,8 @@ sendCommand(cmdData: string): void **示例：** +ArkTS1.1示例： + ```ts import { userAuth } from '@kit.UserAuthenticationKit'; @@ -308,6 +312,26 @@ try { } ``` +ArkTS1.2示例： + +```ts +import { userAuth } from '@kit.UserAuthenticationKit'; + +const userAuthWidgetMgrVersion = 1; +try { + let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion); + console.info('get userAuthWidgetMgr instance success'); + userAuthWidgetMgr.on('command', { + sendCommand: (cmdData) => { + console.info(`The cmdData is ${cmdData}`); + } + }) + console.info('subscribe authentication event success'); +} catch (error) { + console.error(`userAuth widgetMgr catch error: ${JSON.stringify(error)}`); +} +``` + ## UserAuthType8+ 表示身份认证的凭据类型枚举。 diff --git a/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth.md b/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth.md index ebaab5958ab0fc8255abde1e2d2a58ddfddb87be..2ade93b324ff660fe49c168be04dcd8d2ab78e9f 100644 --- a/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth.md +++ b/zh-cn/application-dev/reference/apis-user-authentication-kit/js-apis-useriam-userauth.md @@ -164,7 +164,9 @@ try { ### onResult10+ -onResult(result: UserAuthResult): void +ArkTS1.1: onResult(result: UserAuthResult): void + +ArkTS1.2: onResult: (result: UserAuthResult) => void 回调函数，返回认证结果。如果认证成功，可以通过UserAuthResult获取到认证通过的令牌信息。 @@ -182,6 +184,8 @@ onResult(result: UserAuthResult): void 发起用户认证，采用认证可信等级≥ATL3的人脸+锁屏密码认证，获取认证结果： +ArkTS1.1示例： + ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { cryptoFramework } from '@kit.CryptoArchitectureKit'; @@ -215,10 +219,47 @@ try { } ``` +ArkTS1.2示例： + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; + +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.PIN], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + }; + const widgetParam: userAuth.WidgetParam = { + title: '请输入密码', + }; + + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 + userAuthInstance.on('result', { + onResult:: (result) => { + console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); + } + }); + console.info('auth on success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} +``` + **示例2：** 发起用户认证，采用认证可信等级≥ATL3的人脸 + 认证类型相关 + 复用设备解锁最大有效时长认证，获取认证结果： +ArkTS1.1示例： + ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { cryptoFramework } from '@kit.CryptoArchitectureKit'; @@ -256,10 +297,51 @@ try { } ``` +ArkTS1.2示例： + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; + +let reuseUnlockResult: userAuth.ReuseUnlockResult = { + reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, + reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, +} +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.PIN], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + reuseUnlockResult: reuseUnlockResult, + }; + const widgetParam: userAuth.WidgetParam = { + title: '请输入密码', + }; + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 + userAuthInstance.on('result', { + onResult: (result) => { + console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); + } + }); + console.info('auth on success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} +``` + **示例3：** 发起用户认证，采用认证可信等级≥ATL3的人脸 + 任意应用认证类型相关 + 复用任意应用最大有效时长认证，获取认证结果： +ArkTS1.1示例： + ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { cryptoFramework } from '@kit.CryptoArchitectureKit'; @@ -297,6 +379,45 @@ try { } ``` +ArkTS1.2示例： + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; + +let reuseUnlockResult: userAuth.ReuseUnlockResult = { + reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, + reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, +} +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.PIN], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + reuseUnlockResult: reuseUnlockResult, + }; + const widgetParam: userAuth.WidgetParam = { + title: '请输入密码', + }; + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 + userAuthInstance.on('result', { + onResult: (result) => { + console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); + } + }); + console.info('auth on success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} +``` + ## UserAuthInstance10+ 用于执行用户身份认证，并支持使用统一用户身份认证控件。 diff --git a/zh-cn/application-dev/reference/native-lib/ArkTS1.2-taskpool.md b/zh-cn/application-dev/reference/native-lib/ArkTS1.2-taskpool.md new file mode 100644 index 0000000000000000000000000000000000000000..16e7137eb4edbd70e25b68e29dc7d5ee68335a03 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/ArkTS1.2-taskpool.md @@ -0,0 +1,1503 @@ +# taskpool (启动任务池) + +任务池（taskpool）作用是为应用程序提供一个多线程的运行环境，降低整体资源的消耗、提高系统的整体性能，且您无需关心线程实例的生命周期。您可以使用任务池API创建后台任务（Task），并对所创建的任务进行如任务执行、任务取消的操作。此外，不建议您在任务中执行阻塞操作，特别是无限期阻塞操作，长时间的阻塞操作占据工作线程，可能会阻塞其他任务调度，影响您的应用性能。 + +您所创建的同一优先级任务的执行顺序可以由您决定，任务真实执行的顺序与您调用任务池API提供的任务执行接口顺序一致。任务默认优先级是MEDIUM。 + +文档中涉及到的各种任务概念： +- 任务组任务：对应为[TaskGroup](#taskgroup)任务。 +- 串行队列任务：对应为[SequenceRunner](#sequencerunner)任务。 +- 周期任务：被[executePeriodically](#taskpoolexecuteperiodically)执行过的任务。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## taskpool.execute + +execute(func: Function, ...args: NullishType[]): Promise\ + +将待执行的函数放入taskpool内部任务队列，函数不会立即执行，而是等待分发到工作线程执行。当前执行模式不可取消任务。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ----------------------------- | +| func | Function | 是 | 执行的逻辑需要传入参数。 | +| args | NullishType[] | 否 | 执行逻辑的函数所需要的入参。默认值为undefined。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------------- | ----------------------------------- | +| Promise\ | Promise对象，返回任务函数的执行结果。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +taskpool.execute(printArgs, 100.0).then((value: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool result: " + value); +}); +``` + +## taskpool.execute + +execute(task: Task, priority?: Priority): Promise\ + +将创建好的任务放入taskpool内部任务队列，任务不会立即执行，而是等待分发到工作线程执行。当前执行模式可以设置任务优先级和尝试调用cancel进行任务取消。该任务不可以是任务组任务、串行队列任务和已执行的任务。该任务仅支持执行一次。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------------------------------------- | +| task | [Task](#task) | 是 | 需要在任务池中执行的任务。 | +| priority | [Priority](#priority) | 否 | 等待执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ---------------- | +| Promise\ | Promise对象，返回任务函数的执行结果。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ------------------------------------------- | ---------------------------------------- | +| groupTask cannot execute outside. | 不能执行任务组任务。
可能原因：执行的任务是任务组任务。
处理步骤：调用时，确保任务不是任务组任务。无法保证时，需捕获异常。 | +| seqRunnerTask cannot execute outside. | 不能执行串行队列任务。
可能原因：执行的任务是串行队列任务。
处理步骤：调用时，确保任务不是串行队列任务。无法保证时，需捕获异常。 | +| executedTask with dependency cannot execute again. | 有依赖关系的已执行任务不能被再次执行。
可能原因：执行的任务是有依赖关系的已执行任务。
处理步骤：调用时，确保任务不是已执行的任务。无法保证时，需捕获异常。 | +| task has been executed. | 任务已被执行。
可能原因：该任务已被执行过。
处理步骤：执行任务前确保任务未被执行过。无法保证时，需捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let task1: taskpool.Task = new taskpool.Task(printArgs, 100.0); +let task2: taskpool.Task = new taskpool.Task(printArgs, 200.0); +let task3: taskpool.Task = new taskpool.Task(printArgs, 300.0); +taskpool.execute(task1, taskpool.Priority.LOW).then((value: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool result1: " + value); +}); +taskpool.execute(task2, taskpool.Priority.MEDIUM).then((value: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool result2: " + value); +}); +taskpool.execute(task3, taskpool.Priority.HIGH).then((value: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool result3: " + value); +}); +``` + +## taskpool.execute + +execute(group: TaskGroup, priority?: Priority): Promise\> + +将创建好的任务组放入taskpool内部任务队列，任务组中的任务不会立即执行，而是等待分发到工作线程执行。任务组中任务全部执行完成后，结果数组统一返回。当前执行模式适用于执行一组有关联的任务。该任务组仅支持执行一次。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | --------------------------- | ---- | -------------------------------------------------------------- | +| group | [TaskGroup](#taskgroup) | 是 | 需要在任务池中执行的任务组。 | +| priority | [Priority](#priority) | 否 | 等待执行的任务组的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------- | ---------------------------------- | +| Promise\> | Promise对象数组，返回任务函数的执行结果。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); +taskGroup1.addTask(printArgs, 10.0); +taskGroup1.addTask(printArgs, 20.0); +taskGroup1.addTask(printArgs, 30.0); + +let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); +let task1: taskpool.Task = new taskpool.Task(printArgs, 100.0); +let task2: taskpool.Task = new taskpool.Task(printArgs, 200.0); +let task3: taskpool.Task = new taskpool.Task(printArgs, 300.0); +taskGroup2.addTask(task1); +taskGroup2.addTask(task2); +taskGroup2.addTask(task3); +taskpool.execute(taskGroup1).then((res: Array) => { + hilog.info(0x0000, "testTag", "taskpool execute res is:" + res); +}); +taskpool.execute(taskGroup2).then((res: Array) => { + hilog.info(0x0000, "testTag", "taskpool execute res is:" + res); +}); +``` + +## taskpool.executeDelayed + +executeDelayed(delayTime: number, task: Task, priority?: Priority): Promise\ + +延时执行任务。当前执行模式可以设置任务优先级和尝试调用cancel进行任务取消。该任务不可以是任务组任务、串行队列任务、周期任务和已执行的任务。该任务仅支持执行一次。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------------- | ---- | -------------------- | +| delayTime | number | 是 | 延时时间。单位为ms。不可以为负值。 | +| task | [Task](#task) | 是 | 需要延时执行的任务。 | +| priority | [Priority](#priority) | 否 | 延时执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。| + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ---------------------------------- | +| Promise\ | Promise对象，返回任务函数的执行结果。 | + +**错误信息：** + +| 错误信息 | 说明 | +| -------------------------------- | ---------------------------------------- | +| The delayTime is less than zero. | 延时时间小于零。
可能原因：给定参数delayTime的值小于零。
处理步骤：调用时，确保给定参数delayTime的值大于等于零。无法保证时，需要捕获异常。 | +| groupTask cannot executeDelayed outside. | 不能延时执行任务组任务。
可能原因：执行的任务是任务组任务。
处理步骤：调用时，确保任务不是任务组任务。无法保证时，需捕获异常。 | +| seqRunnerTask cannot executeDelayed outside. | 不能延时执行串行队列任务。
可能原因：执行的任务是串行队列任务。
处理步骤：调用时，确保任务不是串行队列任务。无法保证时，需捕获异常。 | +| executedTask with dependency cannot execute again. | 有依赖关系的已执行任务不能再次执行。
可能原因：执行的任务是有依赖关系且已执行的。
处理步骤：执行任务前确保任务未被执行过。无法保证时，需捕获异常。 | +| the periodicTask cannot executeDelayed. | 周期任务不能延时执行。
可能原因：该任务是周期任务。
处理步骤：执行任务前确保不是周期任务。无法保证时，需捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): void { + hilog.info(0x0000, "testTag", "printArgs: " + args); +} + +let task: taskpool.Task = new taskpool.Task(printArgs, 100.0); +taskpool.executeDelayed(1000.0, task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool execute success"); +}).catch((e) => { + hilog.info(0x0000, "testTag", "taskpool execute occur error: " + e); +}) +``` + +## taskpool.executePeriodically + +executePeriodically(period: number, task: Task, priority?: Priority): void + +周期执行任务，每隔period时长执行一次任务。当前执行模式支持设置任务优先级和调用cancel取消任务周期执行。周期任务不可以是任务组任务、串行队列任务和已执行的任务，不可以再次调用执行接口，不可以拥有依赖关系。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------------- | ----- | -------------------- | +| period | number | 是 | 周期时长。单位为ms。不可以为负值。 | +| task | [Task](#task) | 是 | 需要周期执行的任务。 | +| priority | [Priority](#priority) | 否 | 周期执行的任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ----------------------------- | --------------------------------------- | +| The period value is less than zero. | 周期执行间隔时间小于零。
可能原因：给定参数period的值小于零。
处理步骤：调用时，确保给定参数period的值大于等于零。无法保证时，需要捕获异常。 | +| The concurrent task has been executed and cannot be executed periodically. | 已执行的任务不能再周期执行。
可能原因：调用该接口时，传入已执行的任务。
处理步骤：执行任务前确保任务未被执行过。无法保证时，需捕获异常。 | +| the task with dependency cannot executePeriodically. | 有依赖关系的任务不能周期执行。
可能原因：调用该接口时，传入有依赖关系的任务。
处理步骤：执行任务前确保任务无依赖关系。无法保证时，需捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): void { + hilog.info(0x0000, "testTag", "printArgs: " + args); +} + +function testExecutePeriodically(args: number): void { + let t = Date.now(); + while ((Date.now() - t) < args) {} + taskpool.Task.sendData(args); // 向宿主线程发送消息 +} + +function printResult(data: number): void { + hilog.info(0x0000, "testTag", "taskpool: data is: " + data); +} + +function taskpoolTest() { + try { + let task: taskpool.Task = new taskpool.Task(printArgs, 100.0); + taskpool.executePeriodically(1000.0, task); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool execute-1: error: " + e); + } + + try { + let periodicTask: taskpool.Task = new taskpool.Task(testExecutePeriodically, 200.0); + periodicTask.onReceiveData(printResult); + taskpool.executePeriodically(1000.0, periodicTask); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool execute-2: error: " + e); + } +} + +taskpoolTest(); +``` + +## taskpool.cancel + +cancel(task: Task): void + +取消任务池中的任务。当任务在taskpool等待队列中，取消该任务后该任务将不再执行，并返回任务被取消的异常；当任务已经在taskpool工作线程执行，取消该任务并不影响任务继续执行，执行结果在catch分支返回，搭配isCanceled使用可以对任务取消行为作出响应。taskpool.cancel对其之前的taskpool.execute/taskpool.executeDelayed生效。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------- | ---- | -------------------- | +| task | [Task](#task) | 是 | 需要取消执行的任务。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ---------------------------------- | ---------------------------------- | +| sequenceRunner task has been executed. | 串行队列任务已执行完成。
可能原因：取消已执行完成的串行队列任务。
处理步骤：取消任务前，确保任务不是已执行完成的串行队列任务。无法保证时，需要捕获异常。 | +| task is not executed or has been executed. | 任务未通过调用taskpool.execute等接口开始执行或已执行完。
可能原因：取消的任务未通过调用taskpool.execute等接口开始执行或者已执行完成。
：取消任务前，确保任务已执行且未执行结束。无法保证时，需要捕获异常。 | + +**正在执行的任务取消示例：** + +```ts +import hilog from '@ohos.hilog'; + +function inspectStatus(arg: number): number { + // 第一次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + hilog.info(0x0000, "testTag", "task has been canceled before 2s sleep."); + return arg + 2; + } + // 2s sleep + let t = Date.now(); + while (Date.now() - t < 2000) {} + // 第二次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + hilog.info(0x0000, "testTag", "task has been canceled after 2s sleep."); + return arg + 3; + } + return arg + 1; +} + +function concurrentFunc() { + let task1: taskpool.Task = new taskpool.Task(inspectStatus, 100.0); + let task2: taskpool.Task = new taskpool.Task(inspectStatus, 200.0); + let task3: taskpool.Task = new taskpool.Task(inspectStatus, 300.0); + let task4: taskpool.Task = new taskpool.Task(inspectStatus, 400.0); + let task5: taskpool.Task = new taskpool.Task(inspectStatus, 500.0); + let task6: taskpool.Task = new taskpool.Task(inspectStatus, 600.0); + taskpool.execute(task1).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool test result: " + res); + }); + taskpool.execute(task2); + taskpool.execute(task3); + taskpool.execute(task4); + taskpool.execute(task5); + taskpool.execute(task6); + // 1s后取消task + setTimeout(() => { + try { + taskpool.cancel(task1); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool: cancel error: " + e); + } + }, 1000); +} + +concurrentFunc(); +``` + +## taskpool.cancel + +cancel(group: TaskGroup): void + +取消任务池中的任务组。当一个任务组的任务未全部执行结束时取消任务组，返回undefined作为任务组结果。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------- | ---- | -------------------- | +| group | [TaskGroup](#taskgroup) | 是 | 需要取消执行的任务组。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ------------------------------------------------- | ------------------------------------ | +| taskGroup is not executed or has been executed. | 取消一个未通过调用taskpool.execute开始执行或已执行完的任务组。
可能原因：取消任务组时，该任务组并不存在于任务池中。
处理步骤：取消任务组前，确保任务组已被taskpool.execute调用进入任务池且任务组内存在任务未执行完成。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + let t = Date.now(); + while ((Date.now() - t) < 2000) {} + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +function concurrentFunc() { + let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); + taskGroup1.addTask(printArgs, 10.0); + let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); + taskGroup2.addTask(printArgs, 100.0); + taskpool.execute(taskGroup1).then((res: Array) => { + hilog.info(0x0000, "testTag", "taskGroup1 res is:" + res); + }); + taskpool.execute(taskGroup2).then((res: Array) => { + hilog.info(0x0000, "testTag", "taskGroup2 res is:" + res); + }); + setTimeout(() => { + try { + taskpool.cancel(taskGroup2); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool: cancel error: " + e); + } + }, 1000); +} + +concurrentFunc(); +``` + +## taskpool.getTaskPoolInfo + +getTaskPoolInfo(): TaskPoolInfo + +获取任务池内部信息，包含线程信息和任务信息。 + +**返回值：** + +| 类型 | 说明 | +| ------------------------------- | ------------------ | +| [TaskPoolInfo](#taskpoolinfo) | 任务池的内部信息。 | + +**示例：** + +```ts +let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo(); +``` + +## Priority + +表示所创建任务(Task)执行时的优先级。 + +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| HIGH | 0 | 任务为高优先级。 | +| MEDIUM | 1 | 任务为中优先级。 | +| LOW | 2 | 任务为低优先级。 | +| IDLE | 3 | 任务为后台任务。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + let t = Date.now(); + // 延时1s + while (Date.now() - t < 1000) {} + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let allCount = 100; // 100: test number +let taskArray: Array = []; +// 创建400个任务并添加至taskArray +for (let i = 0; i < allCount; i++) { + let task1: taskpool.Task = new taskpool.Task(printArgs, i * 1.0); + taskArray.push(task1); + let task2: taskpool.Task = new taskpool.Task(printArgs, i * 10.0); + taskArray.push(task2); + let task3: taskpool.Task = new taskpool.Task(printArgs, i * 100.0); + taskArray.push(task3); + let task4: taskpool.Task = new taskpool.Task(printArgs, i * 1000.0); + taskArray.push(task4); +} + +// 从taskArray中获取不同的任务并给定不同优先级执行 +for (let i = 0; i < taskArray.length; i+=4) { // 4: 每次执行4个任务，循环取任务时需后移4项，确保执行的是不同的任务 + taskpool.execute(taskArray[i], taskpool.Priority.HIGH); + taskpool.execute(taskArray[i + 1], taskpool.Priority.LOW); + taskpool.execute(taskArray[i + 2], taskpool.Priority.MEDIUM); + taskpool.execute(taskArray[i + 3], taskpool.Priority.IDLE); +} +``` + +## Task + +表示任务。使用[constructor](#constructor)方法构造Task。任务可以单次执行或放入任务组执行或放入串行队列执行或添加依赖关系执行。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ---------------- | -------------- | ---- | ---- | ------------------------------------------------------------ | +| f | () => NullishType | 否 | 否 | 创建任务时需要传入的函数。 | +| arguments | NullishType[] | 否 | 是 | 创建任务传入函数所需的参数。默认值为undefined。 | +| name | string | 否 | 否 | 创建任务时指定的任务名称。无长度限制和其他格式要求。 | +| totalDuration | number | 否 | 否 | 执行任务总耗时。单位为ms。当任务未执行时值为0，当任务执行后为任务执行的实际总耗时。 | +| ioDuration | number | 否 | 否 | 执行任务异步IO耗时。单位为ms。当任务未执行时值为0，当任务执行后为任务执行的实际异步IO耗时。 | +| cpuDuration | number | 否 | 否 | 执行任务CPU耗时。单位为ms。当任务未执行时值为0，当任务执行后为任务执行的实际异步CPU耗时。 | + +### constructor + +constructor(func: Function, ...args: NullishType[]) + +Task的构造函数。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | -------------------------------------------------------------------- | +| func | Function | 是 | 执行的逻辑需要传入函数。 | +| args | NullishType[] | 否 | 任务执行传入函数的入参。默认值为undefined。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let task: taskpool.Task = new taskpool.Task(printArgs, 100.0); +``` + +### constructor + +constructor(name: string, func: Function, ...args: NullishType[]) + +Task的构造函数，可以指定任务名称。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------- | ---- | --------------------------------------------- | +| name | string | 是 | 任务名称。无长度限制和其他格式要求。 | +| func | Function | 是 | 执行的逻辑需要传入函数。 | +| args | NullishType[] | 否 | 任务执行传入函数的入参。默认值为undefined。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let taskName: string = "taskName"; +let task: taskpool.Task = new taskpool.Task(taskName, printArgs, 100.0); +let name: string = task.name; +``` + +### isCanceled + +static isCanceled(): boolean + +检查当前正在运行的任务是否已取消。使用该方法前需要先构造Task。 + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------------ | +| boolean | 如果当前正在运行的任务被取消返回true，未被取消返回false。| + +**示例：** + +```ts +function inspectStatus(arg: number): number { + if (taskpool.Task.isCanceled()) { + return arg + 1; + } + return arg; +} +``` + +> **说明：** +> +> isCanceled方法需要和taskpool.cancel方法搭配使用，如果不调用cancel方法，isCanceled方法默认返回false。 + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function inspectStatus(arg: number): number { + // 第一次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + hilog.info(0x0000, "testTag", "task has been canceled before 2s sleep."); + return arg + 2; + } + // 延时2s + let t = Date.now(); + while (Date.now() - t < 2000) {} + // 第二次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + hilog.info(0x0000, "testTag", "task has been canceled after 2s sleep."); + return arg + 3; + } + return arg + 1; +} + +let task: taskpool.Task = new taskpool.Task(inspectStatus, 100.0); +taskpool.execute(task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool test result: " + res); +}).catch((err) => { + hilog.info(0x0000, "testTag", "taskpool test occur error: " + err); +}); +// 不调用cancel，isCanceled()默认返回false，task执行的结果为101 +``` + +### sendData + +static sendData(...args: Object[]): void + +在任务执行过程中向宿主线程发送消息并触发回调。使用该方法前需要先构造Task。 + +> **说明：** +> +> - 该接口在taskpool的线程中调用。 +> - 避免在回调函数中使用该方法。 +> - 调用该接口时确保处理数据的回调函数在宿主线程已注册。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------- | ---- | --------------------------------- | +| args | Object[] | 否 | 回调函数的参数。默认值为undefined。 | + +**错误信息：** + +| 错误信息 | 说明 | +| --------------------------------------- | --------------------------------------- | +| The function is not called in the TaskPool thread. | 该函数未在任务池的线程中调用。
可能原因：在UI主线程中或在非taskpool的其他线程中调用该函数。
处理步骤：调用时，确保并发函数执行在taskpool线程中。无法保证时，需要捕获异常。 | +| The callback is not registered on the host side. | 该函数使用时未在宿主线程注册回调函数。
可能原因：该函数使用时未在宿主线程注册回调函数。
处理步骤：调用时，确保函数在宿主线程已注册。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function sendDataTest(num: number): number { + let res = num * 10; + taskpool.Task.sendData(res); + return num; +} + +function printLog(data: number): void { + hilog.info(0x0000, "testTag", "taskpool: data is: " + data); +} + +async function taskpoolTest(): Promise { + try { + let task: taskpool.Task = new taskpool.Task(sendDataTest, 1.0); + task.onReceiveData(printLog); + await taskpool.execute(task); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool error: " + e); + } +} + +taskpoolTest(); +``` + +### onReceiveData + +onReceiveData(callback?: Function): void + +为任务注册回调函数，以接收和处理来自任务池工作线程的数据。使用该方法前需要先构造Task。 + +> **说明：** +> +> 不支持给同一个任务定义多种回调函数，如果重复赋值只有最后一个会生效。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| callback | Function | 否 | 处理数据的回调函数，发送到宿主线程的数据将会作为入参传入该回调函数。不传参可以取消注册的回调函数。默认值为undefined。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function ConcurrentFunc(num: number): number { + let res = num * 10; + taskpool.Task.sendData(res); + return num; +} + +function printLog(data: number): void { + hilog.info(0x0000, "testTag", "taskpool: data is: " + data); +} + +async function testFunc(): Promise { + try { + let task: taskpool.Task = new taskpool.Task(ConcurrentFunc, 1.0); + task.onReceiveData(printLog); + await taskpool.execute(task); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool error: " + e); + } +} + +testFunc(); +``` + +### addDependency + +addDependency(...tasks: Task[]): void + +为当前任务添加对其他任务的依赖。使用该方法前需要先构造Task。该任务和被依赖的任务不可以是任务组任务、串行队列任务、已执行的任务和周期任务。存在依赖关系的任务(依赖其他任务的任务或被依赖的任务)执行后不可以再次执行。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------------- | ---- | ------------------ | +| tasks | [Task](#task)[] | 否 | 被依赖的任务数组。默认值为undefined。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ------------------------------- | ---------------------------------------- | +| There is a circular dependency. | 当前任务存在循环依赖关系。
可能原因：当前任务存在循环依赖关系。
处理步骤：排查找到循环依赖关系的相关任务，根据实际情况使用removeDependency()删除不需要的依赖关系，确保所有任务中不存在循环依赖关系。无法保证时，需要捕获异常。 | +| addDependency has no params. | 调用该函数未传参。
可能原因：调用该函数未传需要被依赖的任务。
处理步骤：调用时，确保传入任务。无法保证时，需要捕获异常。 | +| seqRunnerTask or executedTask cannot addDependency. | 串行队列任务或者已执行的任务不能增加依赖关系。
可能原因：串行队列任务或者已执行的任务调用该函数。
处理步骤：调用时，确保任务不是串行队列任务或者已执行的任务。无法保证时，需要捕获异常。 | +| groupTask cannot addDependency. | 任务组任务增加依赖关系。
可能原因：任务组任务调用该函数。
处理步骤：调用时，确保任务不是任务组任务。无法保证时，需要捕获异常。 | +| seqRunnerTask or executedTask cannot be relied on. | 串行队列任务或者已执行的任务不能被依赖。
可能原因：调用该函数，传参是串行队列任务或者已执行的任务。
处理步骤：调用时，确保传参不是串行队列任务或者已执行的任务。无法保证时，需要捕获异常。 | +| groupTask cannot be relied on. | 任务组任务不能被依赖。
可能原因：调用该函数，传参是任务组任务。
处理步骤：调用时，确保传参不是任务组任务。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function delay(args: number): number { + let t = Date.now(); + while ((Date.now() - t) < 1000) {} + return args; +} + +let task1:taskpool.Task = new taskpool.Task(delay, 100.0); +let task2:taskpool.Task = new taskpool.Task(delay, 200.0); +let task3:taskpool.Task = new taskpool.Task(delay, 200.0); +task1.addDependency(task2); +task2.addDependency(task3); + +taskpool.execute(task1).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "dependency: second task1 success"); +}) +taskpool.execute(task2).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "dependency: second task2 success"); +}) +taskpool.execute(task3).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "dependency: second task3 success"); +}) +``` + +### removeDependency + +removeDependency(...tasks: Task[]): void + +删除当前任务对其他任务的依赖。使用该方法前需要先构造Task。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| tasks | [Task](#task)[] | 否 | 被依赖的任务数组。默认值为undefined。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ------------------------------ | ------------------------------ | +| The dependency does not exist. | 依赖关系不存在。
可能原因：使用removeDependency()删除任务依赖时，依赖关系不存在。
处理步骤：调用时，确保在删除依赖之前，已经使用addDependency()成功添加依赖。无法保证时，需要捕获异常。 | +| task has no dependency. | 依赖关系不存在。
可能原因：使用removeDependency()删除任务依赖时，依赖关系不存在。
处理步骤：调用时，确保在删除依赖之前，已经使用addDependency()成功添加依赖。无法保证时，需要捕获异常。 | +| removeDependency has no params. | 调用该函数未传参。
可能原因：调用该函数未传需要被依赖的任务。
处理步骤：调用时，确保传入任务。无法保证时，需要捕获异常。 | +| executedTask cannot addDependency. | 已执行的任务不能移除依赖关系。
可能原因：已执行的任务调用该函数。
处理步骤：调用时，确保任务不是已执行的任务。无法保证时，需要捕获异常。 | +| cannot removeDependency on a dependent and executed task. | 已执行的任务不能移除依赖。
可能原因：调用该函数。传参是已执行的任务。
处理步骤：调用时，确保传参不是已执行的任务。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function delay(args: number): number { + let t = Date.now(); + while ((Date.now() - t) < 1000) {} + return args; +} + +let task1:taskpool.Task = new taskpool.Task(delay, 100.0); +let task2:taskpool.Task = new taskpool.Task(delay, 200.0); +let task3:taskpool.Task = new taskpool.Task(delay, 200.0); +task1.addDependency(task2); +task2.addDependency(task3); +task1.removeDependency(task2); +task2.removeDependency(task3); +taskpool.execute(task1).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "dependency: task1 success"); +}) +taskpool.execute(task2).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "dependency: task2 success"); +}) +taskpool.execute(task3).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "dependency: task3 success"); +}) +``` + +### onEnqueued + +onEnqueued(callback: CallbackFunction): void + +注册一个回调函数，并在任务入队时调用它。需在任务执行前注册，否则会抛异常。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| callback | [CallbackFunction](#callbackfunction) | 是 | 需注册的回调函数。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ----------------------------- | --------------------------------- | +| The executed task does not support the registration of listeners. | 执行的任务不支持注册监听器。
可能原因：未注册回调函数或在执行任务之后注册回调函数。
处理步骤：确保在任务执行之前注册回调函数。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function delay(args: number): number { + let t = Date.now(); + while ((Date.now() - t) < 1000) {} + return args; +} + +let task: taskpool.Task = new taskpool.Task(delay, 1.0); +task.onEnqueued(() => { + hilog.info(0x0000, "testTag", "taskpool: onEnqueued") +}); +taskpool.execute(task).then((res: NullishType)=> { + hilog.info(0x0000, "testTag", "taskpool: execute task success") +}); +``` + +### onStartExecution + +onStartExecution(callback: CallbackFunction): void + +注册一个回调函数，并在执行任务前调用它。需在任务执行前注册，否则会抛异常。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| callback | [CallbackFunction](#callbackfunction) | 是 | 需注册的回调函数。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ----------------------------- | ---------------------------------- | +| The executed task does not support the registration of listeners. | 执行的任务不支持注册监听器。
可能原因：未注册回调函数或在执行任务之后注册回调函数。
处理步骤：确保在任务执行之前注册回调函数。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function delay(args: number): number { + let t = Date.now(); + while ((Date.now() - t) < 1000) {} + return args; +} + +let task: taskpool.Task = new taskpool.Task(delay, 1.0); +task.onStartExecution(() => { + hilog.info(0x0000, "testTag", "taskpool: onStartExecution") +}); +taskpool.execute(task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool: execute task success") +}); +``` + +### onExecutionFailed + +onExecutionFailed(callback: CallbackFunctionWithError): void + +注册一个回调函数，并在任务执行失败时调用它。需在任务执行前注册，否则会抛异常。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| callback | [CallbackFunctionWithError](#callbackfunctionwitherror) | 是 | 需注册的回调函数。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ----------------------------- | ---------------------------------- | +| The executed task does not support the registration of listeners. | 执行的任务不支持注册监听器。
可能原因：未注册回调函数或在执行任务之后注册回调函数。
处理步骤：确保在任务执行之前注册回调函数。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function test(args: number) { + let t = Date.now() + while ((Date.now() - t) < 100) {} +} + +let task2 = new taskpool.Task(test, 1.0); +task2.onExecutionFailed((e:Error) => { + hilog.info(0x0000, "testTag", "taskpool: onExecutionFailed error is " + e); +}) +taskpool.execute(task2).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool: execute task success"); +}).catch((e) => { + hilog.info(0x0000, "testTag", "taskpool error: " + e); +}) +``` + +### onExecutionSucceeded + +onExecutionSucceeded(callback: CallbackFunction): void + +注册一个回调函数，并在任务执行成功时调用它。需在任务执行前注册，否则会抛异常。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| callback | [CallbackFunction](#callbackfunction) | 是 | 需注册的回调函数。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ----------------------------- | ---------------------------------- | +| The executed task does not support the registration of listeners. | 执行的任务不支持注册监听器。
可能原因：未注册回调函数或在执行任务之后注册回调函数。
处理步骤：确保在任务执行之前注册回调函数。无法保证时，需要捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function delay(args: number): number { + let t = Date.now(); + while ((Date.now() - t) < 1000) {} + return args; +} + +let task: taskpool.Task = new taskpool.Task(delay, 1.0); +task.onExecutionSucceeded(() => { + hilog.info(0x0000, "testTag", "taskpool: onExecutionSucceeded") +}); +taskpool.execute(task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool: execute task success") +}); +``` + +### isDone + +isDone(): boolean + +检查任务是否已完成。 + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------------ | +| boolean | 任务执行完成返回true，任务未执行完成返回false。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function inspectStatus(arg: number): number { + let t = Date.now(); + while (Date.now() - t < 1000) {} + return arg + 1; +} + +async function taskpoolCancel(): Promise { + let task: taskpool.Task = new taskpool.Task(inspectStatus, 100.0); + taskpool.execute(task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool test result: " + res); + }).catch((err) => { + hilog.info(0x0000, "testTag", "taskpool test occur error: " + err); + }); + + setTimeout(() => { + if (!task.isDone()) { + taskpool.cancel(task); + } + }, 3000); // 延时3s，确保任务已执行 +} + +taskpoolCancel(); +``` + +## CallbackFunction + +type CallbackFunction = () => void + +注册的回调函数类型。 + +## CallbackFunctionWithError + +type CallbackFunctionWithError = (e: Error) => void + +注册带有错误信息的回调函数类型。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| e | Error | 是 | 错误信息。 | + +## TaskGroup + +表示任务组，一次执行一组任务，适用于执行一组有关联的任务。如果所有任务正常执行，异步执行完毕后返回所有任务结果的数组，数组中元素的顺序与[addTask](#addtask)的顺序相同；如果任意任务失败，则会抛出对应异常。如果任务组中存在多个任务失败的情况，则会抛出第一个失败任务的异常。使用[constructor](#constructor)方法构造TaskGroup。该任务组仅支持单次执行。 + +### constructor + +constructor() + +TaskGroup的构造函数。 + +**示例：** + +```ts +let taskGroup = new taskpool.TaskGroup(); +``` + +### constructor + +constructor(name: string) + +TaskGroup的构造函数，可以指定任务组名称。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| name | string | 是 | 任务组名称。无长度限制和其他格式要求。 | + +**示例：** + +```ts +let taskGroupName: string = "groupName"; +let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(taskGroupName); +let name: string = taskGroup.name; +``` + +### addTask + +addTask(func: Function, ...args: NullishType[]): void + +将待执行的函数添加到任务组中。使用该方法前需要先构造TaskGroup。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------- | ---- | ---------------------------------------------------------------------- | +| func | Function | 是 | 执行的逻辑需要传入函数。 | +| args | NullishType[] | 否 | 任务执行函数所需要的入参。默认值为undefined。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(); +taskGroup.addTask(printArgs, 100.0); +``` + +### addTask + +addTask(task: Task): void + +将创建好的任务添加到任务组中。使用该方法前需要先构造TaskGroup。任务组不可以添加其他任务组任务、串行队列任务、有依赖关系的任务、周期任务和已执行的任务。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------------------------------------- | +| task | [Task](#task) | 是 | 需要添加到任务组中的任务。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ------------------------------------------- | ------------------------------------------- | +| taskGroup cannot add groupTask. | 任务组不能添加任务组任务。
可能原因：添加的任务是任务组任务。
处理步骤：添加任务需确保任务不是任务组任务。无法保证时，需捕获异常。 | +| The interface does not support the periodicTask. | 周期任务不能再次执行。
可能原因：周期任务已被执行过。
处理步骤：执行任务前确保任务未被执行过。无法保证时，需捕获异常。 | +| taskGroup cannot add seqRunnerTask or executedTask. | 任务组不能添加串行队列任务或已执行任务。
可能原因：添加的任务是串行队列任务或已执行任务。
处理步骤：确保添加的任务不是串行队列任务或已执行任务。无法保证时，需捕获异常。 | +| dependent task not allowed. | 不允许有依赖关系的任务。
可能原因：添加的任务有依赖关系。
处理步骤：确保添加的任务没有依赖关系。无法保证时，需捕获异常。 | +| task has been executed. | 添加已执行的任务。
可能原因：添加已执行的任务。
处理步骤：添加任务前确保任务未执行。无法保证时，需捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: number): number { + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +let taskGroup: taskpool.TaskGroup = new taskpool.TaskGroup(); +let task: taskpool.Task = new taskpool.Task(printArgs, 200.0); +taskGroup.addTask(task); +``` + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ---- | ------ | ---- | ---- | ---------------------------- | +| name | string | 否 | 否 | 创建任务组时指定的任务组名称。无长度限制和其他格式要求。 | + +## SequenceRunner + +表示串行队列的任务，用于执行一组需要串行执行的任务。使用[constructor](#constructor)方法构造SequenceRunner。 + +### constructor + +constructor(priority?: Priority) + +SequenceRunner的构造函数。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------------------------------------------------------- | +| priority | [Priority](#priority) | 否 | 指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + +**示例：** + +```ts +let runner: taskpool.SequenceRunner = new taskpool.SequenceRunner(); +``` + +### constructor + +constructor(name: string, priority?: Priority) + +SequenceRunner的构造函数。构造一个全局串行队列，如果名字相同，将返回同一个串行队列。 + +> **说明：** +> +> - 底层通过单例模式保证了：创建同名串行队列时，获取到同一个实例。 +> - 不支持修改串行队列的优先级。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ------------------------------------------------------- | +| name | string | 是 | 串行队列的名字。无长度限制和其他格式要求。 | +| priority | [Priority](#priority) | 否 | 指定任务的优先级，该参数默认值为taskpool.Priority.MEDIUM。 | + +**示例：** + +```ts +let runner:taskpool.SequenceRunner = new taskpool.SequenceRunner("runner1", taskpool.Priority.LOW); +``` + +### execute + +execute(task: Task): Promise\ + +执行串行任务。使用该方法前需要先构造SequenceRunner。串行队列不可以执行任务组任务、其他串行队列任务、有依赖关系的任务和已执行的任务。使用Promise异步回调。 + +> **说明：** +> +> - 不支持加入存在依赖的任务。 +> - 前面的任务执行失败或取消不影响后续任务执行。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------- | ---- | -------------------------------- | +| task | [Task](#task) | 是 | 需要添加到串行任务队列中的任务。 | + +**返回值：** + +| 类型 | 说明 | +| ---------------- | --------------------------------- | +| Promise\ | Promise对象，返回任务执行的结果。 | + +**错误信息：** + +| 错误信息 | 说明 | +| ------------------------------------------- | ------------------------------------------- | +| SequenceRunner cannot execute groupTask. | 串行队列不能执行任务组任务。
可能原因：串行队列执行了任务组任务。
处理步骤：调用时，确保串行队列不执行任务组任务。无法保证时，需捕获异常。 | +| SequenceRunner cannot execute seqRunnerTask or executedTask. | 串行队列不能执行串行队列任务或已经执行过的任务。
可能原因：串行队列执行已经执行过的任务。
处理步骤：调用时，确保串行队列不执行已经执行过的任务。无法保证时，需捕获异常。 | +| dependent task not allowed. | 串行队列执行有依赖关系的任务。
可能原因：串行队列执行有依赖关系的任务。
处理步骤：排查找到串行队列里使用addDependency()添加依赖的任务，使用removeDependency()删除此任务的依赖。无法保证时，需捕获异常。 | +| SequenceRunner cannot execute the periodicTask. | 周期任务不能再次执行。
可能原因：串行队列执行周期任务。
处理步骤：执行任务前确保任务未被执行过。无法保证时，需捕获异常。 | +| task has been executed. | 任务已经被执行过。
可能原因：串行队列执行已经执行过的任务。
处理步骤：执行任务前确保任务未被执行过。无法保证时，需捕获异常。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog'; + +function additionDelay(delay: number): void { + let start = new Date().getTime(); + while ((new Date().getTime() - start) < delay) {} +} + +function waitForRunner(finalString: string): string { + return finalString; +} + +async function seqRunner() { + let finalString:string = ""; + let task1:taskpool.Task = new taskpool.Task(additionDelay, 3000.0); + let task2:taskpool.Task = new taskpool.Task(additionDelay, 2000.0); + let task3:taskpool.Task = new taskpool.Task(additionDelay, 1000.0); + let task4:taskpool.Task = new taskpool.Task(waitForRunner, finalString); + + let runner:taskpool.SequenceRunner = new taskpool.SequenceRunner(); + runner.execute(task1).then((res: NullishType) => { + finalString += 'a'; + hilog.info(0x0000, "testTag", "seqrunner: task1 done."); + }); + runner.execute(task2).then((res: NullishType) => { + finalString += 'b'; + hilog.info(0x0000, "testTag", "seqrunner: task2 done"); + }); + runner.execute(task3).then((res: NullishType) => { + finalString += 'c'; + hilog.info(0x0000, "testTag", "seqrunner: task3 done"); + }); + await runner.execute(task4); + hilog.info(0x0000, "testTag", "seqrunner: task4 done, finalString is " + finalString); +} +``` + +## State + +表示任务（Task）状态的枚举。当任务创建成功后，调用execute，任务进入taskpool等待队列，状态设置为WAITING；任务从等待队列出来进入taskpool工作线程中，任务状态更新为RUNNING；当任务执行完成，返回结果后任务状态重置为WAITING；当主动cancel任务时，将任务状态更新为CANCELED。 + +| 名称 | 值 | 说明 | +| --------- | -------- | ------------- | +| WAITING | 1 | 任务正在等待。 | +| RUNNING | 2 | 任务正在执行。 | +| CANCELED | 3 | 任务已被取消。 | + +## TaskInfo + +任务的内部信息。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| -------- | ------------------ | ---- | ---- | ------------------------------------------------------------- | +| taskId | number | 否 | 否 | 任务的标识符。无单位。值为标识任务的一个正值。 | +| state | [State](#state) | 否 | 否 | 任务的状态。 | +| duration | number | 否 | 是 | 任务执行至当前所用的时间，单位为ms。当返回为0时，表示任务未执行；返回为空时，表示没有任务执行。默认值为0。 | +| name | string | 否 | 否 | 任务的名字。无长度限制和其他格式要求。 | + +## ThreadInfo + +工作线程的内部信息。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| -------- | ---------------------- | ---- | ---- | -------------------------------------------------------- | +| tid | number | 否 | 否 | 工作线程的标识符。无单位。值为标识工作线程的一个正值。返回为空时，代表没有任务执行。 | +| taskIds | number[] | 否 | 是 | 在当前线程上运行的任务ID列表。无单位。值为运行任务ID的一个正值数组。返回为空时，代表没有任务执行。默认值为undefined。 | +| priority | [Priority](#priority) | 否 | 是 | 当前线程的优先级。返回为空时，代表没有任务执行。默认值为taskpool.Priority.MEDIUM。 | + +## TaskPoolInfo + +任务池的内部信息。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ------------- | ------------------------------ | ---- | ---- | -------------------- | +| threadInfos | [ThreadInfo[]](#threadinfo) | 否 | 否 | 工作线程的内部信息。 | +| taskInfos | [TaskInfo[]](#taskinfo) | 否 | 否 | 任务的内部信息。 | + +## 其他说明 + +### 简单使用 + +**示例一** +```ts +import hilog from '@ohos.hilog'; + +function printArgs(args: string): string { + hilog.info(0x0000, "testTag", "func: " + args); + return args; +} + +async function taskpoolExecute(): Promise { + let task: taskpool.Task = new taskpool.Task(printArgs, "create task, then execute"); + hilog.info(0x0000, "testTag", "taskpool.execute(task) result: " + await taskpool.execute(task)); + hilog.info(0x0000, "testTag", "taskpool.execute(function) result: " + await taskpool.execute(printArgs, "execute task by func")); +} + +taskpoolExecute(); +``` + +**示例二** +```ts +import hilog from '@ohos.hilog'; + +// c.ets +function strSort(inPutArr: Array): Array { + let newArr = inPutArr.sort(); + return newArr; +} + +export async function func1(): Promise { + let strArray: Array = ['c test string', 'b test string', 'a test string']; + let task: taskpool.Task = new taskpool.Task(strSort, strArray); + hilog.info(0x0000, "testTag", "func1 result:" + await taskpool.execute(task)); +} + +export async function func2(): Promise { + let strArray: Array = ['c test string', 'b test string', 'a test string']; + taskpool.execute(strSort, strArray).then((result: NullishType) => { + hilog.info(0x0000, "testTag", "func2 result: " + result); + }).catch((err) => { + hilog.info(0x0000, "testTag", "taskpool test occur error: " + err); + }); +} +``` + +```ts +// index.ets +import { func1, func2 } from "./c"; + +func1(); +func2(); +``` + +**示例三** +```ts +import hilog from '@ohos.hilog'; + +// 任务取消成功 +function inspectStatus(arg: number): number { + // 第一次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + hilog.info(0x0000, "testTag", "task has been canceled before 2s sleep."); + return arg + 2; + } + // 2s sleep + let t = Date.now(); + while (Date.now() - t < 2000) {} + // 第二次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + hilog.info(0x0000, "testTag", "task has been canceled after 2s sleep."); + return arg + 3; + } + return arg + 1; +} + +async function taskpoolCancel(): Promise { + let task: taskpool.Task = new taskpool.Task(inspectStatus, 100.0); + taskpool.execute(task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool test result: " + res); + }).catch((err) => { + hilog.info(0x0000, "testTag", "taskpool test occur error: " + err); + }); + // 1s后取消task + setTimeout(() => { + try { + taskpool.cancel(task); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool: cancel error: " + e); + } + }, 1000); +} + +taskpoolCancel(); +``` + +**示例四** +```ts +import hilog from '@ohos.hilog'; + +// 已执行的任务取消失败 +function inspectStatus(arg: number): number { + // 第一次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + return arg + 2; + } + // 延时500ms + let t = Date.now(); + while (Date.now() - t < 500) {} + // 第二次检查任务是否已经取消并作出响应 + if (taskpool.Task.isCanceled()) { + return arg + 3; + } + return arg + 1; +} + +async function taskpoolCancel(): Promise { + let task: taskpool.Task = new taskpool.Task(inspectStatus, 100.0); + taskpool.execute(task).then((res: NullishType) => { + hilog.info(0x0000, "testTag", "taskpool test result: " + res); + }).catch((err) => { + hilog.info(0x0000, "testTag", "taskpool test occur error: " + err); + }); + + setTimeout(() => { + try { + taskpool.cancel(task); // 任务已执行,取消失败 + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool: cancel error: " + e); + } + }, 3000); // 延时3s，确保任务已执行 +} + +taskpoolCancel(); +``` + +**示例五** +```ts +import hilog from '@ohos.hilog'; + +// 待执行的任务组取消成功 +function printArgs(args: number): number { + let t = Date.now(); + while (Date.now() - t < 1000) {} + hilog.info(0x0000, "testTag", "printArgs: " + args); + return args; +} + +async function taskpoolGroupCancelTest(): Promise { + let taskGroup1: taskpool.TaskGroup = new taskpool.TaskGroup(); + taskGroup1.addTask(printArgs, 10.0); + taskGroup1.addTask(printArgs, 20.0); + taskGroup1.addTask(printArgs, 30.0); + let taskGroup2: taskpool.TaskGroup = new taskpool.TaskGroup(); + let task1: taskpool.Task = new taskpool.Task(printArgs, 100.0); + let task2: taskpool.Task = new taskpool.Task(printArgs, 200.0); + let task3: taskpool.Task = new taskpool.Task(printArgs, 300.0); + taskGroup2.addTask(task1); + taskGroup2.addTask(task2); + taskGroup2.addTask(task3); + taskpool.execute(taskGroup1).then((res: Array) => { + hilog.info(0x0000, "testTag", "taskpool execute res is:" + res); + }).catch((e) => { + hilog.info(0x0000, "testTag", "taskpool execute error is:" + e); + }); + taskpool.execute(taskGroup2).then((res: Array) => { + hilog.info(0x0000, "testTag", "taskpool execute res is:" + res); + }).catch((e) => { + hilog.info(0x0000, "testTag", "taskpool execute error is:" + e); + }); + + try { + taskpool.cancel(taskGroup2); + } catch (e) { + hilog.info(0x0000, "testTag", "taskpool: cancel error: " + e); + } +} + +taskpoolGroupCancelTest() +``` + +**示例六** +```ts +import hilog from '@ohos.hilog'; + +// 分别创建执行100个高、中、低优先级的任务，查看其各项信息 +function delay(): void { + let start = new Date().getTime(); + while (new Date().getTime() - start < 500) {} +} + +let highCount: int = 0; +let mediumCount: int = 0; +let lowCount: int = 0; +let allCount: int = 100; +for (let i = 0; i < allCount; i++) { + let task1: taskpool.Task = new taskpool.Task(delay); + let task2: taskpool.Task = new taskpool.Task(delay); + let task3: taskpool.Task = new taskpool.Task(delay); + taskpool.execute(task1, taskpool.Priority.LOW).then((res: NullishType) => { + lowCount++; + }).catch((e) => { + hilog.info(0x0000, "testTag", "low task error: " + e); + }) + taskpool.execute(task2, taskpool.Priority.MEDIUM).then((res: NullishType) => { + mediumCount++; + }).catch((e) => { + hilog.info(0x0000, "testTag", "medium task error: " + e); + }) + taskpool.execute(task3, taskpool.Priority.HIGH).then((res: NullishType) => { + highCount++; + }).catch((e) => { + hilog.info(0x0000, "testTag", "high task error: " + e); + }) +} +let start = new Date().getTime(); +while (new Date().getTime() - start < 1000) { + continue; +} +let taskpoolInfo: taskpool.TaskPoolInfo = taskpool.getTaskPoolInfo(); +let tid: number = 0; +let taskIds: Array = []; +let priority: number = 0; +let taskId: number = 0; +let state: number = 0; +let duration: number = 0; +let name: string = ""; +let threadIS = Array.from(taskpoolInfo.threadInfos) +for (let threadInfo of threadIS) { + tid = threadInfo.tid; + if (threadInfo.taskIds != undefined && threadInfo.priority != undefined) { + taskIds.length = threadInfo.taskIds.length; + priority = threadInfo.priority; + } + hilog.info(0x0000, "testTag", "taskpool---tid is:" + tid + ", taskIds is:" + taskIds + ", priority is:" + priority); +} +let taskIS = Array.from(taskpoolInfo.taskInfos) +for (let taskInfo of taskIS) { + taskId = taskInfo.taskId; + state = taskInfo.state; + if (taskInfo.duration != undefined) { + duration = taskInfo.duration; + name = taskInfo.name; + } + hilog.info(0x0000, "testTag", "taskpool---taskId is:" + taskId + ", state is:" + state + ", duration is:" + duration + ", name is:" + name); +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/native-lib/Readme-CN.md b/zh-cn/application-dev/reference/native-lib/Readme-CN.md index e3b283f66681f33f1d8cbe1fe176cd791325245c..f32060ac4b95dccdfef8ae52724c4846d1e7cda7 100644 --- a/zh-cn/application-dev/reference/native-lib/Readme-CN.md +++ b/zh-cn/application-dev/reference/native-lib/Readme-CN.md @@ -22,6 +22,10 @@ - [VkNativeBufferPropertiesOHOS](_vk_native_buffer_properties_o_h_o_s.md) - [VkNativeBufferUsageOHOS](_vk_native_buffer_usage_o_h_o_s.md) - [VkSurfaceCreateInfoOHOS](_vk_surface_create_info_o_h_o_s.md) +- EAWorker + - [EAWorker 独占线程任务执行器（ArkTS）](eaworker_managed.md) + - [EAWorker 独占线程任务执行器（C/C++）](eaworker_native.md) +- [Job](job.md) - 附录 - [libc中没有导出的符号列表](musl-peculiar-symbol.md) - [NDK musl-libc接口受权限影响的说明](guidance-on-ndk-libc-interfaces-affected-by-permissions.md) diff --git a/zh-cn/application-dev/reference/native-lib/arkts1.2-asynclock.md b/zh-cn/application-dev/reference/native-lib/arkts1.2-asynclock.md new file mode 100644 index 0000000000000000000000000000000000000000..5ba580041d3f2c9d1093edd699642a486716d353 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/arkts1.2-asynclock.md @@ -0,0 +1,334 @@ +# AsyncLock (异步锁) + +ArkTS1.2支持并发与内存共享，为了解决多并发实例间的数据竞争问题，引入异步锁能力。由于ArkTS1.2支持异步操作，阻塞锁容易产生死锁问题，因此我们在ArkTS1.2中仅支持异步锁（非阻塞式锁）。 + +使用异步锁的方法需要标记为async，调用方需要await修饰调用，才能保证时序正确。因此会导致外层调用函数全部标记成async。 + +> **说明：** +> +> ArkTS版本：该标准库接口仅适用于ArkTS1.2。 + +## AsyncLockCallback\ + +type AsyncLockCallback\ = () => T | Promise\ + +这是一个补充类型别名，表示[lockAsync](#lockasync)函数所有重载中的回调。 + +**返回值：** + +| 类型 | 说明 | +| ---------------- | ------------------------------ | +| T \| Promise\ | T类型的值或泛型为T的Promise对象。 | + +## AsyncLock + +实现异步锁功能的类，允许在锁下执行异步操作。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ---- | ------ | ---- | ---- | --------------------------- | +| name | string | 是 | 否 | 锁的名称，开发者可自定义填写。 | + +### constructor + +constructor() + +默认构造函数，创建一个异步锁。 + +**示例：** + +```ts +let lock = new AsyncLock(); +``` + +### request + +static request(name: string): AsyncLock + +使用指定的名称查找或创建（如果未找到）异步锁实例。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ----------------------------------------------- | +| name | string | 是 | 按指定名称查找或创建异步锁实例。开发者可自定义填写。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------- | ----------------------------- | +| [AsyncLock](#asynclock) | 返回查找到或创建后的异步锁实例。 | + +**示例：** + +```ts +let lockName = "isAvailableLock"; +let lock = AsyncLock.request(lockName); +``` + +### query + +static query(name: string): AsyncLockState + +查询指定异步锁的信息。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ----------------------------------------------------- | +| name | string | 是 | 锁的名称。使用[request](#request)方法创建锁时设置的名称。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | ------------------------------- | +| [AsyncLockState](#asynclockstate) | 一个包含状态描述的异步锁状态实例。 | + +**示例：** + +```ts +// 你已经在别的地方创建了一个锁。 +// let lock = AsyncLock.request("queryTestLock"); +let state = AsyncLock.query("queryTestLock"); +if (!state) { + throw new Error("测试失败：期望有效的状态，但得到的是 " + state); +} +let pending: AsyncLockInfo[] = state.pending; +let held: AsyncLockInfo[] = state.held; +``` + +### queryAll + +static queryAll(): AsyncLockState[] + +查询所有现有锁的信息。 + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | ---------------------------- | +| [AsyncLockState](#asynclockstate)[] | 包含锁状态信息的异步锁状态数组。 | + +**示例：** + +```ts +let states: AsyncLockState[] = AsyncLock.queryAll(); +if (states.length === 0) { + throw new Error("测试失败：期望至少有1个状态，但得到的是 " + states.length); +} +``` + +### lockAsync + +lockAsync\(callback: AsyncLockCallback\): Promise\ + +在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用[lockAsync](#lockasync)的同一线程中以异步方式执行。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------ | +| callback | [AsyncLockCallback\](#asynclockcallbackt) | 是 | 获取锁后要调用的函数。| + +**返回值：** + +| 类型 | 说明 | +| ----------- | ----------------------------- | +| Promise\ | Promise对象，返回回调函数结果。 | + +**示例：** + +```ts +let lock = new AsyncLock(); +let p1 = lock.lockAsync(() => { + // 执行某些操作 +}); +``` + +### lockAsync + +lockAsync\(callback: AsyncLockCallback\, mode: AsyncLockMode): Promise\ + +在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用[lockAsync](#lockasync)的同一线程中以异步方式执行。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | -------------------- | +| callback | [AsyncLockCallback\](#asynclockcallbackt) | 是 | 获取锁后要调用的函数。 | +| mode | [AsyncLockMode](#asynclockmode) | 是 | 锁的操作模式。 | + +**返回值：** + +| 类型 | 说明 | +| ----------- | ---------------------------- | +| Promise\ | Promise对象，返回回调函数结果。| + +**示例：** + +```ts +let lock = new AsyncLock(); +let p1 = lock.lockAsync(() => { + // 执行某些操作 +}, AsyncLockMode.EXCLUSIVE); +``` + +### lockAsync + +lockAsync\(callback: AsyncLockCallback\, mode: AsyncLockMode, options: AsyncLockOptions\): Promise\ + +在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用[lockAsync](#lockasync)的同一线程中以异步方式执行。在[AsyncLockOptions](#asynclockoptionst)中可以提供一个可选的超时值。在这种情况下，如果超时前未能获取锁，lockAsync将拒绝返回的Promise并带上一个Error实例，携带超时异常信息。使用Promise异步回调。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | --------------------- | +| callback | [AsyncLockCallback\](#asynclockcallbackt) | 是 | 获取锁后要调用的函数。 | +| mode | [AsyncLockMode](#asynclockmode) | 是 | 锁的操作模式。 | +| options | [AsyncLockOptions\](#asynclockoptionst) | 是 | 锁的操作选项。 | + +**返回值：** + +| 类型 | 说明 | +| ----------- | -------------------------------------------------- | +| Promise\ | Promise对象，返回回调函数结果，或者在超时情况下被拒绝。 | + +**示例：** + +```ts +let lock = new AsyncLock(); +let options = new AsyncLockOptions(); +options.timeout = 1000; +let p: Promise = lock.lockAsync( + () => { + // 执行某些操作 + }, + AsyncLockMode.EXCLUSIVE, + options +); +``` + +## AsyncLockMode + +锁操作对应的模式枚举。 + +| 名称 | 值 | 说明 | +| --------- | --- | --------------------------------------------------- | +| SHARED | 1 | 共享锁模式。如果指定了此模式，可以在任意线程同时执行。 | +| EXCLUSIVE | 2 | 独占锁模式。如果指定了此模式，仅在独占获取锁时才能执行。 | + +**示例：** + +```ts +import hilog from '@ohos.hilog' + +let lock = new AsyncLock(); +// shared0可获取锁并开始执行 +lock.lockAsync(async () => { + hilog.info(0x0000, 'testTag', "shared0"); + await new Promise((resolve) => { setTimeout(resolve, 1000, 1.0) }); +}, AsyncLockMode.SHARED); +// shared1可获取锁并开始执行，无需等待shared0 +lock.lockAsync(async () => { + hilog.info(0x0000, 'testTag', "shared1"); + await new Promise((resolve) => { setTimeout(resolve, 1000, 1.0) }); +}, AsyncLockMode.SHARED); +// exclusive0需等待shared0、1执行完后才可获取锁并执行 +lock.lockAsync(async () => { + hilog.info(0x0000, 'testTag', "exclusive0"); + await new Promise((resolve) => { setTimeout(resolve, 1000, 1.0) }); +}, AsyncLockMode.EXCLUSIVE); +// shared2需等待exclusive0执行完后才可获取锁并执行 +lock.lockAsync(async () => { + hilog.info(0x0000, 'testTag', "shared2"); + await new Promise((resolve) => { setTimeout(resolve, 1000, 1.0) }); +}, AsyncLockMode.SHARED); +// shared3需等待exclusive0执行完后才可获取锁并执行，无需等待shared2 +lock.lockAsync(async () => { + hilog.info(0x0000, 'testTag', "shared3"); + await new Promise((resolve) => { setTimeout(resolve, 1000, 1.0) }); +}, AsyncLockMode.SHARED); +``` + +## AsyncLockOptions\ + +表示锁操作选项的类。 + +### 属性 + +| 参数名 | 类型 | 只读 | 可选 | 说明 | +| ----------- | ------------------------------------- | ---- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| isAvailable | boolean | 否 | 否 | 当前锁是否可用。取值为true，则只有在尚未持有锁定请求时才会授予该锁定请求；为false则表示将等待当前锁被释放。默认为 false。 | +| signal | [AbortSignal\](#abortsignalt) \| null | 否 | 否 | 用于中止异步操作的对象。当signal.aborted 为true时，锁请求将被丢弃；当signal.aborted为false时，请求会继续等待获取锁；当signal为null时，请求正常排队运行。默认为null。 | +| timeout | number | 否 | 否 | 锁操作的超时时间（毫秒）。如果该值大于零，且运行超过该时间，[lockAsync](#lockasync)将返回被拒绝的 Promise。默认为0。 | + +### constructor + +constructor() + +默认构造函数。创建一个所有属性均具有默认值的异步锁配置项实例。 + +**示例：** + +```ts +let s: AbortSignal = { aborted: false, reason: "Aborted" }; +let options = new AsyncLockOptions(); +options.isAvailable = false; +options.signal = s; +``` + +### constructor + +constructor(isAvailable: boolean, signal: AbortSignal\ | null, timeout: number) + +有参构造函数。根据输入参数创建异步锁配置项实例。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | --------------------------------------- | ---- | ------------------------ | +| isAvailable | boolean | 是 | 当前锁是否可用。取值为true，则只有在尚未持有锁定请求时才会授予该锁定请求；为false则表示将等待当前锁被释放。 | +| signal | [AbortSignal\](#abortsignalt) \| null | 是 | 用于中止异步操作的对象。当signal.aborted 为true时，锁请求将被丢弃；当signal.aborted为false时，请求会继续等待获取锁；当signal为null时，请求正常排队运行。 | +| timeout | number | 是 | 锁操作的超时时间（毫秒）。如果该值大于零，且运行超过该时间，[lockAsync](#lockasync)将返回被拒绝的 Promise。 | + +**示例：** + +```ts +let s: AbortSignal = { aborted: false, reason: "Aborted" }; +let options = new AsyncLockOptions(false, s, 0); +``` + +## AsyncLockState + +用于存储特定异步锁实例上当前执行的所有锁操作的信息的类。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ------- | --------------------------------- | ---- | ---- | -------------------- | +| held | [AsyncLockInfo](#asynclockinfo)[] | 否 | 否 | 持有的锁信息列表。 | +| pending | [AsyncLockInfo](#asynclockinfo)[] | 否 | 否 | 等待中的锁信息列表。 | + +## AsyncLockInfo + +封装锁信息的类。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| --------- | ------------------------------- | ---- | ---- | ---------------------------------------------------------------------- | +| name | string | 是 | 否 | 锁的名称。 | +| mode | [AsyncLockMode](#asynclockmode) | 是 | 否 | 锁的模式。 | +| contextId | number | 是 | 否 | [AsyncLockMode](#asynclockmode)调用者的执行上下文标识符。大于0的整数。 | + +## AbortSignal\ + +用于中止异步操作的对象。该类的实例必须在其创建的同一线程中访问。从其他线程访问此类的字段会导致未定义的行为。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ------- | ------- | ---- | ---- | --------------------------------------------------------------------------- | +| aborted | boolean | 否 | 否 | 锁请求终止标志。设置为true时，锁请求将被丢弃；设置为false时，请求会继续等待获取锁。| +| reason | T | 否 | 否 | 中止的原因。此值将用于拒绝[lockAsync](#lockasync)返回的Promise。 | diff --git a/zh-cn/application-dev/reference/native-lib/arkts1.2-blockingqueue.md b/zh-cn/application-dev/reference/native-lib/arkts1.2-blockingqueue.md new file mode 100644 index 0000000000000000000000000000000000000000..07d1ef626566f006d3e44fc7ca409142cfd586b0 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/arkts1.2-blockingqueue.md @@ -0,0 +1,381 @@ +# BlockingQueue (阻塞队列) + +阻塞队列（BlockingQueue）是一种线程安全的队列容器，其核心特点是在队列为空时阻塞消费者线程弹出元素，队列满时阻塞生产者线程插入元素。它通过内部的锁和条件变量保证多线程并发安全，常用于解决多线程环境下的数据共享与协同问题。 + +**推荐使用场景：** 可用于实现多线程阻塞式channel（管道，一种用于多线程之间数据传递和同步的通信机制）、​​线程池任务队列taskpool、流量控制等场景，允许生产者线程与消费者线程间安全传递数据。 + +> **说明：** +> +> ArkTS版本：该标准库接口仅适用于ArkTS1.2。 + +## BlockingQueue + +BlockingQueue\ 是定义了阻塞队列及其方法的interface，有两个实现类：[LinkedBlockingQueue](#linkedblockingqueue)和[ArrayBlockingQueue](#arrayblockingqueue)。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| :------- | :--- | :--- | :--- | :--------------------- | +| size | int | 是 | 否 | 阻塞队列中元素的个数。 | +| capacity | int | 是 | 否 | 阻塞队列的容量。 | + +### push + +push(element: T): void + +将元素插入队列尾部。如果队列已满，则阻塞，直到队列有空余容量后再插入元素。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------ | :--- | :--- | :----------------- | +| element | T | 是 | 要插入队列的数据。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(10); //阻塞队列容量设置为10 +for (let i = 0; i < 10; i++) { + queueInt.push(i); +} +queueInt.push(10); //阻塞 +``` + +### pop + +pop(): T + +弹出并返回队列的头部元素。如果队列为空，则阻塞，直到队列中有元素后再弹出元素。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :--- | :------------------- | +| T | 返回队列的头部元素。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(); +for (let i = 0; i < 10; i++) { + queueInt.push(i); +} +for (let i = 0; i < 9; i++) { + queueInt.pop(); +} +let res_0 = queueInt.pop(); // 9 +let res_1 = queueInt.pop(); // 阻塞 +``` + +### add + +add(element: T): boolean + +尝试将元素插入队列。如果队列已满，则插入失败返回false，否则插入成功返回true。该方法不会阻塞。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------ | :--- | :--- | :----------------- | +| element | T | 是 | 待插入队列的数据。 | + +**返回值：** + +| 类型 | 说明 | +| :------ | :------------------------------------------------------ | +| boolean | 如果队列已满，插入失败返回false，否则插入成功返回true。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(10); +for (let i = 0; i < 10; i++) { + let res = queueInt.add(i); // true +} +assertEQ(queueInt.size, 10); // 插入了10个元素，队列元素数量为10 +let res = queueInt.add(11); // false +``` + +### poll + +poll(): T \| undefined + +尝试移除队列的头部元素。如果队列为空，则返回undefined，否则返回被移除的元素。该方法不会阻塞。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :------------- | :---------------------------------------------------- | +| T \| undefined | 返回被移除的头部元素，如果队列为空，则返回undefined。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(); +for (let i = 0; i < 10; i++) { + queueInt.push(i); +} +let res = queueInt.poll(); // 0 +res = queueInt.poll(); // 1 +``` + +### getFirst + +getFirst(): T | undefined + +获取队列的头部元素，如果队列为空，则返回undefined。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :------------- | :------------------------------------------------ | +| T \| undefined | 返回队列头部元素，如果队列为空，则返回undefined。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(); +for (let i: int = 0; i < 10; ++i) { + queueInt.push(i); +} +let res = queueInt.getFirst(); // 0 +res = queueInt.getFirst(); // 0 +``` + +### isEmpty + +isEmpty(): boolean + +检查队列是否为空。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :------ | :-------------------------------------- | +| boolean | 队列为空返回true，队列不为空返回false。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(); +let res = queueInt.isEmpty(); // true +queueInt.push(1); +res = queueInt.isEmpty(); // false +``` + +### remainingCapacity + +remainingCapacity(): int + +当前队列在不阻塞的情况下还可以容纳的元素数量，即剩余容量，等于队列的容量减去当前的元素数量。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :--- | :----------------------- | +| int | 返回当前队列的剩余容量。 | + +**示例：** + +```typescript +let queueInt: BlockingQueue = new ArrayBlockingQueue(10); +for (let i = 0; i < 5; i++) { + queueInt.push(i); +} +let remainingcapacity = queueInt.remainingCapacity(); // 5 +queueInt.pop(); +remainingcapacity = queueInt.remainingCapacity(); // 6 +assertEQ(queueInt.remainingCapacity(), queueInt.capacity - queueInt.size); +``` + +## LinkedBlockingQueue + +LinkedBlockingQueue\，实现了[BlockingQueue](#blockingqueue)接口，是一个基于链表实现的阻塞队列，提供了阻塞队列的基本操作，如插入、删除、获取元素等，并在队列为空或满时支持线程阻塞等待，支持多线程环境下的并发操作。 + +### constructor + +constructor() + +LinkedBlockingQueue的构造函数，创建一个容量为Int.MAX_VALUE(2147483647)的LinkedBlockingQueue\实例。 + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(); +let capacity = queueInt.capacity; // 2147483647 +``` + +### constructor + +constructor(capacity: int) + +LinkedBlockingQueue的构造函数，创建一个容量为capacity的LinkedBlockingQueue\实例。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------- | :--- | :--- | :--------------------------------------------------- | +| capacity | int | 是 | 初始化队列的容量。
取值范围：大于等于0。
| + +**示例：** + +```typescript +let queueInt: BlockingQueue = new LinkedBlockingQueue(10); +let capacity = queueInt.capacity; // 10 +``` + +### constructor + +constructor(iterable: Iterable\) + +LinkedBlockingQueue的构造函数，传入一个实现了Iterable\接口的可迭代对象。该构造函数创建一个容量为Int.MAX_VALUE(2147483647)的LinkedBlockingQueue\实例，并将iterable中（非undefined）的元素添加到新创建的链表阻塞队列中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------- | :----------- | :--- | :--------------------------- | +| iterable | Iterable\ | 是 | 一个迭代器，用于初始化队列。 | + +**示例：** + +```typescript +let arr = new Array(10); +arr[0] = 0; +let queueInt: BlockingQueue = new LinkedBlockingQueue(arr); +let res = queueInt.capacity; // 2147483647 +let size = queueInt.size; // 1 +let first = queueInt.getFirst(); // 0 +``` + +### constructor + +constructor(capacity: int, iterable: Iterable\) + +LinkedBlockingQueue的构造函数，传入一个实现了Iterable\接口的可迭代对象。该构造函数创建一个容量为capacity的LinkedBlockingQueue\实例，并将iterable中（非undefined）的元素添加到新创建的链表阻塞队列中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------- | :----------- | :--- | :------------------------------------------------- | +| capacity | int | 是 | 初始化队列容量。
取值范围：大于等于0。
| +| iterable | Iterable\ | 是 | 一个迭代器，用于初始化队列。 | + +**示例：** + +```typescript +let arr = new Array(10); +arr[0] = 0; +let iter = arr.values(); +let queueInt: BlockingQueue = new LinkedBlockingQueue(10, iter); +let res = queueInt.capacity; // 10 +let size = queueInt.size; // 1 +let first = queueInt.getFirst(); // 0 +``` + +### getEnd + +getEnd(): T | undefined + +获取队列的尾部元素，如果队列为空，则返回undefined。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :------------- | :-------------------------------------------------- | +| T \| undefined | 返回队列尾部元素，若队列没有元素，则返回undefined。 | + +**示例：** + +```typescript +let queueInt: LinkedBlockingQueue = new LinkedBlockingQueue(10); +for (let i: int = 0; i < 10; ++i) { + queueInt.push(i); +} +let res = queueInt.getEnd(); // 9 +``` + +## ArrayBlockingQueue + +ArrayBlockingQueue\，实现了[BlockingQueue](#blockingqueue)接口，是一个基于数组实现的阻塞队列，提供了阻塞队列的基本操作，如插入、删除、获取元素等，并在队列为空或满时支持线程阻塞等待，支持多线程环境下的并发操作。 + +### constructor + +constructor(capacity: int) + +ArrayBlockingQueue的构造函数，创建一个容量为capacity的ArrayBlockingQueue\实例。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---- | ---- | ------------------------------------------------ | +| capacity | int | 是 | 初始化队列的容量。
取值范围：大于0。
| + +**示例：** + +```typescript +let queueInt: BlockingQueue = new ArrayBlockingQueue(10); +let res = queueInt.isEmpty(); // true +``` + +### constructor + +constructor(capacity: int , iterable: Iterable\) + +ArrayBlockingQueue的构造函数。该构造函数创建一个容量为capacity的ArrayBlockingQueue\实例，并将iterable中（非undefined）的元素添加到新创建的数组阻塞队列中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------ | ---- | ------------------------------------------------ | +| capacity | int | 是 | 初始化队列的容量。
取值范围：大于0。
| +| iterable | Iterable\ | 是 | 一个迭代器，用于初始化队列。 | + +**示例：** + +```typescript +const arr: Number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; +let set: Set = new Set(arr); +let queueInt: BlockingQueue = new ArrayBlockingQueue(200, set); +let capacity = queueInt.capacity; // 200 +let size = queueInt.size; // 10 +``` + +### getEnd + +getEnd(): T \| undefined + +获取队列的尾部元素，如果队列为空，则返回undefined。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| -------------- | --------------------------------------------------- | +| T \| undefined | 返回队列尾部元素，若队列没有元素，则返回undefined。 | + +**示例：** + +```typescript +let queueInt: ArrayBlockingQueue = new ArrayBlockingQueue(10); +for (let i: int = 0; i < 10; ++i) { + queueInt.push(i); +} +let res = queueInt.getEnd(); // 9 +``` diff --git a/zh-cn/application-dev/reference/native-lib/arkts1.2-concurrenthashmap.md b/zh-cn/application-dev/reference/native-lib/arkts1.2-concurrenthashmap.md new file mode 100644 index 0000000000000000000000000000000000000000..fb9dbfda6a5e497addb503f0dec81147e79caf3c --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/arkts1.2-concurrenthashmap.md @@ -0,0 +1,531 @@ +# ConcurrentHashMap (并发哈希表) + +ConcurrentHashMap<[K, V]> 是一个多线程安全的哈希表，支持并发读取和写入，减少锁的竞争，实现高并发性能。提供了对容器元素的高效操作，包括添加、删除、查找等，并且可以迭代操作内部存储的元素。 + +> **说明：** +> +> ArkTS版本：该标准库接口仅适用于ArkTS1.2。 + +## 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| :--- | :----- | :--- | :--- | :--------------------- | +| size | number | 是 | 否 | 哈希表中键值对的个数。 | + +## constructor + +constructor() + +ConcurrentHashMap的构造函数，创建一个空的ConcurrentHashMap实例。 + +**示例：** + +```typescript +let concurrentHashMap: ConcurrentHashMap = new ConcurrentHashMap(); +``` + +## constructor + +constructor(entries: ArrayLike<[K, V]>) + +ConcurrentHashMap的构造函数，传入一个实现了ArrayLike<[K, V]>接口的数组对象entries，该构造函数创建一个新的ConcurrentHashMap实例，并将entries中的所有元素添加到新创建的哈希表中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------ | :---------------- | :--- | :------------------------------------------------------------ | +| entries | ArrayLike<[K, V]> | 是 | 一个实现了ArrayLike<[K, V]>接口的数组对象，用于初始化哈希表。 | + +**示例：** + +```typescript +let arrKeys: number[] = [0, 1, 2, 3, 4]; +let arrValues: string[] = ["zero", "one", "two", "three", "four"]; +let array = Array<[Double, String]>(5); +for (let i = 0; i < 5; i++) { + let arrKV: [Double, String] = [arrKeys[i], arrValues[i]]; + array[i] = arrKV; +} +let concurrentHashMap: ConcurrentHashMap = new ConcurrentHashMap(array); +``` + +## constructor + +constructor(iterable: Iterable<[K, V]>) + +ConcurrentHashMap的构造函数，传入一个实现了Iterable<[K, V]>接口的可迭代对象iterable，该构造函数创建一个新的ConcurrentHashMap实例，并将iterable中的所有元素添加到新创建的哈希表中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------- | :--------------- | :--- | :------------------------------------------------------------- | +| iterable | Iterable<[K, V]> | 是 | 一个实现了Iterable<[K, V]>接口的可迭代对象，用于初始化哈希表。 | + +**示例：** + +```typescript +let arr: Array<[Double, string]> = [ + [1.0, "1.0"], + [2.0, "2.0"], + [3.0, "3.0"], +]; +let map = new Map(arr); +let iterable = map.entries(); +let concurrentHashMap: ConcurrentHashMap = new ConcurrentHashMap(iterable); +``` + +## constructor + +constructor(map: ReadonlyMap) + +ConcurrentHashMap的构造函数，传入一个实现了ReadonlyMap接口的映射对象map，该构造函数创建一个新的ConcurrentHashMap实例，并将map中的所有元素添加到新创建的哈希表中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :---------------- | :--- | :------------------------------------------------------------ | +| map | ReadonlyMap | 是 | 一个实现了ReadonlyMap接口的映射对象，用于初始化哈希表。 | + +**示例：** + +```typescript +let map: Map = new Map(); +map.set(1, "1"); +let concurrentHashMap: ConcurrentHashMap = new ConcurrentHashMap(map); +``` + +## set + +set(key: K, val: V): this + +向哈希表中添加或更新一个键值对，返回this即调用该方法的[ConcurrentHashMap](#concurrenthashmap-并发哈希表)对象，支持链式调用。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :-------------------- | +| key | K | 是 | 待增添/更新元素的键。 | +| val | V | 是 | 待增添/更新元素的值。 | + +**返回值：** + +| 类型 | 说明 | +| :--- | :----------------------------------------------------------------------- | +| this | 返回调用该方法的[ConcurrentHashMap](#concurrenthashmap-并发哈希表)对象。 | + +**示例：** + +```typescript +let concurrentHashMap: ConcurrentHashMap = new ConcurrentHashMap(); +let val = concurrentHashMap.set(1, "one").get(1); //"one" +``` + +## get + +get(key: K): V \| undefined + +获取指定key所映射的value，哈希表中不存在该键值对时则返回undefined。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :------------------ | +| key | K | 是 | 待查找的指定key值。 | + +**返回值：** + +| 类型 | 说明 | +| :------------- | :---------------------------------------------------- | +| V \| undefined | 返回指定key所映射的value值；当不存在时返回undefined。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +let val_0 = concurrentHashMap.get(1); // "one" +let val_1 = concurrentHashMap.get(2); // undefined +``` + +## replace + +replace(key: K, newValue: V): boolean + +对哈希表中一组键值对进行更新替换，若哈希表中没有key对应的键值对，替换失败，且不会增添键值对。替换成功时返回true，失败返回false。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------- | :--- | :--- | :-------------------- | +| key | K | 是 | 待替换元素指定key值。 | +| newValue | V | 是 | 待替换的新值。 | + +**返回值：** + +| 类型 | 说明 | +| :------ | :---------------------------------- | +| boolean | 替换成功时返回true，否则返回false。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +let val = concurrentHashMap.set(1, "one").get(1); //"one" +let flag_0 = concurrentHashMap.replace(1, "first"); // true +let flag_1 = concurrentHashMap.replace(2, "second"); // false +val = concurrentHashMap.get(1); // "first" +``` + +## has + +has(key: K): boolean + +判断此哈希表中是否含有键为key的元素。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :---------------------- | +| key | K | 是 | 待查找元素的指定key值。 | + +**返回值：** + +| 类型 | 说明 | +| :------ | :----------------------------------------------- | +| boolean | 表中包含指定key的元素时返回true，否则返回false。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +let flag_1 = concurrentHashMap.has(1); // true +let flag_2 = concurrentHashMap.has(2); // false +``` + +## remove + +remove(key: K): V | undefined + +删除指定key所对应的键值对，并返回其value值，如不存在匹配的键值对则直接返回undefined。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :---------------------- | +| key | K | 是 | 待删除元素的指定key值。 | + +**返回值：** + +| 类型 | 说明 | +| :------------- | :---------------------------------------------------------------- | +| V \| undefined | 返回被删除元素的value值，当key对应的键值对不存在则返回undefined。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +let val_0 = concurrentHashMap.remove(1); // "one" +let val_1 = concurrentHashMap.remove(1); // undefined +``` + +## delete + +delete(key:K): boolean + +删除指定key所对应的键值对。如果哈希表中存在该键值对且被成功删除，则返回true；如果该键值对不存在或删除失败，则返回false。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :---------------------- | +| key | K | 是 | 待删除元素的指定key值。 | + +**返回值：** + +| 类型 | 说明 | +| :------ | :---------------------------------- | +| boolean | 删除成功时返回true，否则返回false。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +let flag = concurrentHashMap.delete(1); // true +flag = concurrentHashMap.delete(1); // false +``` + +## isEmpty + +isEmpty(): boolean + +判断该哈希表是否为空（即元素数量为0）。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :------ | :-------------------------------------------- | +| boolean | 该哈希表为空时，返回true，不为空则返回false。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +let flag: boolean = concurrentHashMap.isEmpty(); // true +``` + +## clear + +clear():void + +清空该哈希表中所有元素。 + +该方法多线程并发执行安全。 + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); +concurrentHashMap.clear(); +let size = concurrentHashMap.size; // 0 +let isEmpty = concurrentHashMap.isEmpty(); +``` + +## keys + +keys(): IterableIterator\ + +获取一个包含此哈希表中所有键值对的键的迭代器。 + +弱一致性，会返回当前哈希表所有元素的键的快照，不保证会反映之后该哈希表中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :------------------- | :----------------------------------------- | +| IterableIterator\ | 返回包含此哈希表中所有键值对的键的迭代器。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(0, "zero"); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); +concurrentHashMap.set(3, "three"); +concurrentHashMap.set(4, "four"); + +let iter = concurrentHashMap.keys(); +let v = iter.next(); +while (!v.done) { + let val = v.value; + console.log("key: " + val); + v = iter.next(); +} +/* +key: 0 +key: 1 +key: 2 +key: 3 +key: 4 +*/ +``` + +## values + +values(): IterableIterator\ + +获取一个包含此哈希表中所有键值对的值的迭代器。 + +弱一致性，会返回当前哈希表所有元素的值的快照，不保证会反映之后该哈希表中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :------------------- | :----------------------------------------- | +| IterableIterator\ | 返回包含此哈希表中所有键值对的值的迭代器。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(0, "zero"); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); +concurrentHashMap.set(3, "three"); +concurrentHashMap.set(4, "four"); + +let iter = concurrentHashMap.values(); +let v = iter.next(); +while (!v.done) { + let value = v.value; + console.log("value: " + value); + v = iter.next(); +} +/* +value: zero +value: one +value: two +value: three +value: four +*/ +``` + +## entries + +entries(): IterableIterator<[K, V]> + +获取一个包含此哈希表中所有元素（键值对）的迭代器。 + +弱一致性，会返回当前所有元素的快照，不保证会反映之后该哈希表中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :----------------------- | :----------------------------------- | +| IterableIterator<[K, V]> | 返回包含此哈希表中所有元素的迭代器。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(0, "zero"); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); +concurrentHashMap.set(3, "three"); +concurrentHashMap.set(4, "four"); + +let iter = concurrentHashMap.entries(); +let v = iter.next(); +while (!v.done) { + let value = v.value; + console.log("key: " + value![0] + " value: " + value![1]); + v = iter.next(); +} +/* +key: 0 value: zero +key: 1 value: one +key: 2 value: two +key: 3 value: three +key: 4 value: four +*/ +``` + +## \$\_iterator() + +\$\_iterator(): IterableIterator<[K, V]> + +获取一个包含此哈希表中所有元素（键值对）的迭代器，与[entries](#entries)结果一致。 + +弱一致性，会返回当前所有元素的快照，不保证会反映之后该哈希表中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :----------------------- | :----------------------------------- | +| IterableIterator<[K, V]> | 返回包含此哈希表中所有元素的迭代器。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(0, "zero"); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); +concurrentHashMap.set(3, "three"); +concurrentHashMap.set(4, "four"); + +let iter = concurrentHashMap.$_iterator(); +let v = iter.next(); +while (!v.done) { + let value = v.value; + console.log("key: " + value![0] + " value: " + value![1]); + v = iter.next(); +} +/* +key: 0 value: zero +key: 1 value: one +key: 2 value: two +key: 3 value: three +key: 4 value: four +*/ +``` + +## forEach + +forEach(callbackfn: (value: V, key: K, map: ConcurrentHashMap) => void): void + +对哈希表中的每个键值对执行指定的回调函数。回调函数可以接收当前迭代到的键值对的值、键，以及此哈希表实例。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :--------- | :------- | :--- | :--------- | +| callbackFn | function | 是 | 回调函数。 | + +callbackfn的参数说明： + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :---------------------- | :--- | :------------------------------------------------------------------- | +| value | V | 否 | 当前遍历到的键值对的值。 | +| key | K | 否 | 当前遍历到的键值对的键。 | +| map | ConcurrentHashMap | 否 | 调用该方法的[ConcurrentHashMap](#concurrenthashmap-并发哈希表)对象。 | + +**示例：** + +```typescript +let concurrentHashMap: ConcurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); + +concurrentHashMap.forEach((value: string, key: number, map: ConcurrentHashMap) => { + console.log("value: " + value, " key: " + key); +}); +/* +value: one key: 1 +value: two key: 2 +*/ +``` + +## toString + +toString(): String + +以字符串的形式输出哈希表中的元素。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :----- | :--------------------------------- | +| String | 返回包含哈希表内所有元素的字符串。 | + +**示例：** + +```typescript +let concurrentHashMap = new ConcurrentHashMap(); +concurrentHashMap.set(1, "one"); +concurrentHashMap.set(2, "two"); +let str = concurrentHashMap.toString(); +``` diff --git a/zh-cn/application-dev/reference/native-lib/arkts1.2-concurrentset.md b/zh-cn/application-dev/reference/native-lib/arkts1.2-concurrentset.md new file mode 100644 index 0000000000000000000000000000000000000000..f444cc9a39e6b9e0340f258a732389083a5982c3 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/arkts1.2-concurrentset.md @@ -0,0 +1,402 @@ +# ConcurrentSet (并发集合) + +ConcurrentSet\是一个多线程并发安全的集合类，支持并发读取和写入，减少锁的竞争，实现高并发性能。它提供了对集合元素的高效操作，包括添加、删除、查找等，并且可以迭代操作内部存储的元素。该类基于[ConcurrentHashMap\](./arkts1.2-concurrenthashmap.md)实现，确保了在多线程环境下的安全性。 + +> **说明：** +> +> ArkTS版本：该标准库接口仅适用于ArkTS1.2。 + +## 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| :--- | :----- | :--- | :--- | :----------------- | +| size | number | 是 | 否 | 集合中元素的个数。 | + +## constructor + +constructor() + +ConcurrentSet的构造函数，创建一个空的ConcurrentSet\实例。 + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +``` + +## constructor + +constructor(entries: ArrayLike\) + +ConcurrentSet的构造函数，传入一个实现了ArrayLike\接口的数组对象entries，该构造函数创建一个新的ConcurrentSet\实例，并将entries中的所有元素添加到新创建的集合中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------ | :------------ | :--- | :-------------------------------------------------- | +| entries | ArrayLike\ | 是 | 一个实现了ArrayLike\的数组对象，用于初始化集合。 | + +**示例：** + +```typescript +let array = new Array(0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0); +let concurrentSet: ConcurrentSet = new ConcurrentSet(array); +``` + +## constructor + +constructor(iterable: Iterable\) + +ConcurrentSet的构造函数，传入一个实现了Iterable\ 接口的可迭代对象iterable，该构造函数创建一个新的ConcurrentSet\实例，并将iterable中的所有元素添加到新创建的集合中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :------- | :----------- | :--- | :-------------------------------------------------------- | +| iterable | Iterable\ | 是 | 一个实现了Iterable\ 接口的可迭代对象，用于初始化集合。 | + +**示例：** + +```typescript +let set = new Set(); +for (let i = 0; i < 10; i++) { + set.add(i); +} +let iter: Iterable = set.keys(); +let concurrentSet: ConcurrentSet = new ConcurrentSet(iter); +``` + +## constructor + +constructor(set: ReadonlySet\) + +ConcurrentSet的构造函数，传入一个了实现ReadonlySet\接口的集合对象set，该构造函数创建一个新的ConcurrentSet\实例，并将set中的所有元素添加到新创建的集合中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :-------------- | :--- | :-------------------------------------------------------- | +| set | ReadonlySet\ | 是 | 一个实现了ReadonlySet\接口的集合对象，用于初始化集合。 | + +**示例：** + +```typescript +let set = new Set(); +for (let i = 0; i < 10; i++) { + set.add(i); +} +let concurrentSet: ConcurrentSet = new ConcurrentSet(set); +``` + +## add + +add(val: T): this + +向集合中添加一个元素，如果元素已经存在，则不会重复添加。返回this即调用该方法的[ConcurrentSet](#concurrentset-并发集合)对象，支持链式调用。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :----------------------- | +| val | T | 是 | 需要添加到集合中的元素。 | + +**返回值：** + +| 类型 | 说明 | +| :--- | :------------------------------------------------------------- | +| this | 返回调用该方法的[ConcurrentSet](#concurrentset-并发集合)对象。 | + +**示例：** + +```typescript +let arrValues = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]; +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +for (let i = 0; i < 10; i++) { + concurrentSet.add(arrValues[i]); +} +``` + +## has + +has(val: T): boolean + +检查集合中是否包含指定的元素。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :------------- | +| val | T | 是 | 要查找的元素。 | + +**返回值：** + +| 类型 | 说明 | +| :------ | :---------------------------------------------- | +| boolean | 当集合中包含该元素时，返回true，否则返回false。 | + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +for (let i = 0; i < 10; i++) { + concurrentSet.add(i); +} +let val = concurrentSet.has(1); // true +val = concurrentSet.has(-1); // false +``` + +## delete + +delete(val: T): boolean + +从集合中删除指定的元素。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :--- | :--- | :------------- | +| val | T | 是 | 要删除的元素。 | + +**返回值：** + +| 类型 | 说明 | +| :------ | :---------------------------------------------- | +| boolean | 元素存在并被成功删除，返回true，否则返回false。 | + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +concurrentSet.add(0); +let res = concurrentSet.delete(0); // true +res = concurrentSet.delete(0); // false +``` + +## clear + +clear(): void + +清空集合中的所有元素。 + +该方法多线程并发执行安全。 + +**示例：** + +```typescript +let arrValues = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]; +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +let beforeClearSize = concurrentSet.size; //10 +concurrentSet.clear(); +let afterClearSize = concurrentSet.size; //0 +``` + +## keys + +keys(): IterableIterator\ + +获取一个包含集合中所有元素的迭代器。 + +弱一致性，会返回当前所有元素的快照，不保证反映之后该集合中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :------------------- | :------------------------------- | +| IterableIterator\ | 返回包含集合中所有元素的迭代器。 | + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +for (let i = 0; i < 5; i++) { + concurrentSet.add(i); +} +let iter = concurrentSet.keys(); +let v = iter.next(); +while (!v.done) { + const value = v.value; + console.log("value: " + value); + v = iter.next(); +} +/* +value: 0 +value: 1 +value: 2 +value: 3 +value: 4 +*/ +``` + +## values + +values(): IterableIterator\ + +获取一个包含集合中所有元素的迭代器。与[keys](#keys)相同。 + +弱一致性，会返回当前所有元素的快照，不保证会反映之后该集合中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :------------------- | :------------------------------- | +| IterableIterator\ | 返回包含集合中所有元素的迭代器。 | + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +for (let i = 0; i < 5; i++) { + concurrentSet.add(i); +} +let iter = concurrentSet.values(); +let v = iter.next(); +while (!v.done) { + const value = v.value; + console.log("value: " + value); + v = iter.next(); +} +/* +value: 0 +value: 1 +value: 2 +value: 3 +value: 4 +*/ +``` + +## \$\_iterator + +\$\_iterator(): IterableIterator\ + +获取一个包含集合中所有元素的迭代器，与[keys](#keys)相同。 + +弱一致性，会返回当前所有元素的快照，不保证会反映之后该集合中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :------------------- | :------------------------------- | +| IterableIterator\ | 返回包含集合中所有元素的迭代器。 | + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +for (let i = 0; i < 5; i++) { + concurrentSet.add(i); +} +let iter = concurrentSet.$_iterator(); +let v = iter.next(); +while (!v.done) { + const value = v.value; + console.log("value: " + value); + v = iter.next(); +} +/* +value: 0 +value: 1 +value: 2 +value: 3 +value: 4 +*/ +``` + +## entries + +entries(): IterableIterator\<[T, T]> + +获取一个包含集合中所有元素的键值对迭代器。由于集合中的键和值相同，因此每个键值对都是[T, T]的形式。 + +弱一致性，会返回当前所有元素的键值对的快照，不保证会反映之后该集合中元素的变化。 + +**返回值：** + +| 类型 | 说明 | +| :------------------------ | :------------------------------------- | +| IterableIterator\<[T, T]> | 返回包含集合中所有元素键值对的迭代器。 | + +**示例：** + +```typescript +let concurrentSet: ConcurrentSet = new ConcurrentSet(); +for (let i: int = 0; i < 5; i++) { + concurrentSet.add(i); +} + +let iter = concurrentSet.entries(); +let v = iter.next(); +while (!v.done) { + const value = v.value; + console.log("key: " + value![0] + " value:" + value![1]); + v = iter.next(); +} +/* +key: 0 value:0 +key: 1 value:1 +key: 2 value:2 +key: 3 value:3 +key: 4 value:4 +*/ +``` + +## forEach + +forEach(callbackfn: (value: T, value2: T, set: ConcurrentSet\) => void): void + +对集合中的每个元素执行指定的回调函数。回调函数可以接收当前迭代到的元素作为value1和value2，以及此集合实例。 + +该方法多线程并发执行安全。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| :--------- | :------- | :--- | :--------- | +| callbackfn | function | 是 | 回调函数。 | + +callbackfn的参数说明： + +| 参数名 | 类型 | 必填 | 说明 | +| :----- | :---------------- | :--- | :------------------------------------------------------- | +| value | T | 否 | 集合当前遍历到的元素的值。 | +| value2 | T | 否 | 集合当前遍历到的元素的值。 | +| set | ConcurrentSet\ | 否 | 调用该方法的[ConcurrentSet](#concurrentset-并发集合)对象 | + +**示例：** + +```typescript +let arrKeys = new Array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); +let ConcurrentSet: ConcurrentSet = new ConcurrentSet(arrKeys); +let count = 0; +ConcurrentSet.forEach((k: number, v: number, set: ConcurrentSet) => { + if (k % 2 == 0) { + count++; + } +}); +console.log(count); // 5 +``` + +## toString + +toString(): String + +以字符串的形式输出该集合中的元素。 + +该方法多线程并发执行安全。 + +**返回值：** + +| 类型 | 说明 | +| :----- | :------------------------------- | +| String | 返回包含集合内所有元素的字符串。 | + +```typescript +let array = new Array(0.0, 1.0, 2.0, 3.0, 4.0); +let concurrentSet: ConcurrentSet = new ConcurrentSet(array); +let val = concurrentSet.toString(); // 'ConcurrentSet[0,1,2,3,4]' +``` diff --git a/zh-cn/application-dev/reference/native-lib/arkts1.2-std_process.md b/zh-cn/application-dev/reference/native-lib/arkts1.2-std_process.md new file mode 100644 index 0000000000000000000000000000000000000000..ce5b126ab5926f85a19c5cfe4b6c13e1496d61e5 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/arkts1.2-std_process.md @@ -0,0 +1,251 @@ +# StdProcess (进程管理标准库) + +提供系统进程信息查询及跨进程交互能力，支持环境变量管理、系统资源配置等高级操作。 + +> **说明：** +> +> ArkTS版本：该标准库接口仅适用于ArkTS1.2。 + +## process + +进程控制核心类，提供进程信息查询接口。 + +### 属性 + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ---------------- | ------ | ---- | ---- | ------------------ | +| uid | number | 是 | 否 | 进程的用户标识。 | +| pid | number | 是 | 否 | 当前进程的pid。 | +| tid | number | 是 | 否 | 当前线程的tid。 | + +### is64Bit + +static is64Bit(): boolean + +检查运行环境是否为64位。 + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------------------------------- | +| boolean | 返回判断结果。如果运行环境是64位则返回true，否则返回false。 | + +**示例：** + +```js +let result = StdProcess.process.is64Bit(); +``` + +### getStartRealtime + +static getStartRealtime(): number + +获取系统启动到进程启动的实时时间（以毫秒为单位）。 + +**返回值：** + +| 类型 | 说明 | +| ------ | ----------------------------- | +| number | 返回经过的实时时间。单位：毫秒。 | + +**示例：** + +```js +let realtime = StdProcess.process.getStartRealtime(); +``` + +### getPastCpuTime + +static getPastCpuTime(): number + +获取进程启动到当前时间的CPU时间（以毫秒为单位）。 + +**返回值：** + +| 类型 | 说明 | +| ------ | ----------------------------- | +| number | 返回经过的CPU时间。单位：毫秒。 | + +**示例：** + +```js +let result = StdProcess.process.getPastCpuTime(); +``` + +### abort + +static abort(): void + +该方法会导致进程立即退出并生成一个核心文件，谨慎使用。 + +**示例：** + +```js +StdProcess.process.abort(); +``` + +### uptime + +static uptime(): number + +获取当前系统已运行的时间（以秒为单位）。 + +**返回值：** + +| 类型 | 说明 | +| ------ | ---------------------------- | +| number | 当前系统已运行的时间。单位：秒。| + +**示例：** + +```js +let time = StdProcess.process.uptime(); +``` + +## ProcessManager + +提供与系统进程进行交互的接口，用于获取进程特有和系统特有的信息。 + +### getUidForName + +static getUidForName(v: string): number + +根据指定的用户名，从系统的用户数据库中获取该用户uid。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------- | +| v | string | 是 | 用户名。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | --------------------------------- | +| number | 获取用户uid，如果用户不存在则返回-1。| + +**示例：** + +```js +let pres = StdProcess.ProcessManager.getUidForName("tool"); +``` + +### getThreadPriority + +static getThreadPriority(v: number): number + +根据指定的tid获取线程优先级。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ----------------------------- | +| v | number | 是 | 指定的线程tid。大于等于0的整数。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | -------------------------------------------- | +| number | 返回线程的优先级。优先级顺序取决于当前操作系统。 | + +**示例：** + +```js +let tid = StdProcess.process.tid; +let pres = StdProcess.ProcessManager.getThreadPriority(tid); +``` + +### getSystemConfig + +static getSystemConfig(name: number): number + +获取系统配置信息。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------ | +| name | number | 是 | 指定系统配置参数名。大于0的整数。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------------------- | +| number | 返回系统配置信息。如果配置不存在，返回-1。 | + +**示例：** + +```js +let _SC_ARG_MAX = 0; +let pres = StdProcess.ProcessManager.getSystemConfig(_SC_ARG_MAX); +``` + +### getEnvironmentVar + +static getEnvironmentVar(name: string): string + +获取环境变量对应的值，如果值不存在，返回空字符串。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ----------- | +| name | string | 是 | 环境变量名。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ----------------------- | +| string | 返回环境变量名对应的值。 | + +**示例：** + +```js +let pres = StdProcess.ProcessManager.getEnvironmentVar("PATH"); +``` + +### exit + +static exit(code: number): void + +终止程序。 + +请谨慎使用此接口，此接口调用后应用会退出，如果入参非0会产生数据丢失或者异常情况。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------- | +| code | number | 是 | 进程的退出码。0~255的整数。 | + +**示例：** + +```js +StdProcess.ProcessManager.exit(0); +``` + +### kill + +static kill(signal: number, pid: number): boolean + +发送signal到指定的进程，结束指定进程。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------------------- | +| signal | number | 是 | 发送特定的信号给目标进程。1~64的整数。| +| pid | number | 是 | 进程的id。大于0的整数。 | + +**返回值：** + +| 类型 | 说明 | +| ------- | -------------------------------------------------------- | +| boolean | 信号是否发送成功。如果信号发送成功则返回true，否则返回false。 | + +**示例：** + +```js +let pres = StdProcess.process.pid; +let result = StdProcess.ProcessManager.kill(28, pres); +``` diff --git a/zh-cn/application-dev/reference/native-lib/eaworker_managed.md b/zh-cn/application-dev/reference/native-lib/eaworker_managed.md new file mode 100644 index 0000000000000000000000000000000000000000..32cbcef45094bafc6436d7380f861d5272ea3f9d --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/eaworker_managed.md @@ -0,0 +1,113 @@ +# EAWorker（独占线程任务执行器）(ArkTS) + +EAWorker类为开发者提供了以独占线程模式执行异步任务的接口。通过创建EAWorker实例，系统会自动分配专属工作线程，开发者可复用该实例执行不同任务，有效提升线程资源利用率。 +> **说明：** +> +> 使用完毕后必须显式调用[join](#join)方法释放线程资源，避免内存泄漏。 + +文档中涉及到概念以及解释： +- 互操作（interop）：ArkTS1.2和ArkTS1.1代码相互操作。 + +## constructor +constructor(needInterop: boolean = false) + +EAWorker的构造器，用于创建支持或者不支持interop能力的EAWorker。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**参数:** +| 参数名 | 类型 | 必填| 说明 | +|----------------|-----------|-------|----------------------------------------------------------------------------| +| needInterop | boolean | 否 | 参数用于控制创建的EAWorker实例是否支持interop。true表示支持互操作，false表示不支持互操作。默认值为false。 | + +**示例：** +```ts +// 创建基础实例（不开启互操作） +let worker = new EAWorker(); + +// 创建支持ArkTS1.1互操作的实例 +let interopWorker = new EAWorker(true); +``` +## run +run\(task: Function, ...args: NullishType[]): Job\ + +向当前Worker线程提交异步任务。需通过已创建的EAWorker实例调用，任务将在该实例绑定的独占线程中执行。 + +**ArkTS 版本：** 该接口仅适用于ArkTS1.2。 + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------- | --- | ------------ | +| task | Function | 是 | 开发者期望执行的任务函数。 | +| args | NullishType[] | 否 | 任务函数的参数列表。默认值undefined。 | + +**返回值：** +| 类型 | 说明 | +| -------- | ------------------ | +| Job\ | 任务执行句柄，可通过[Await](./job.md#await)获取异步结果。 | + +**示例：** + +基础任务执行。 +```ts +import hilog from '@ohos.hilog' +// 定义任务函数 +function logNumber(arg: int): int { + hilog.info(0x0000, "testTag", "Received number: " + arg); + return arg * 2; +} + +// 创建 Worker 并提交任务 +const worker = new EAWorker(); +const job = worker.run(logNumber, 42); + +// 获取异步结果 +hilog.info(0x0000, "testTag", "Result: " + job.Await()); // 输出：Result: 84 +``` +创建支持与ArkTS1.1互操作的EAWorker并执行任务。 +```ts +// ArkTS1.1 文件 taskFile.ets +import hilog from '@ohos.hilog' + +export function task(a: number): string { + hilog.info(0x0000, "testTag", "ArkTS 1.1 task called: " + a); // 输出：ArkTS 1.1 task called: 1 + return "success"; +} +``` + +```ts +// ArkTS1.2 文件 +import hilog from '@ohos.hilog' + +let eaw = new EAWorker(true); + +let job = eaw.run((a:number): string => { + let arg = ESObject.wrapInt(a); + let mod = ESObject.load("taskFile"); + return mod.getProperty("task").invoke(arg).toString() +}, 1) +hilog.info(0x0000, "testTag", "res: " + job.Await()); // 输出：res: success +``` + +## join +join(): void + +主动销毁Worker线程资源。调用此接口会向EAWorker提交任务请求释放当前EAWorker实例绑定的工作线程，停止接收新任务并回收系统资源。 + +> **说明：** +> +> 开发者调用join之后，EAWorker实例仍旧存活不会立即被回收，但是对应的系统线程资源已经销毁，因此开发者在调用[join](#join)之后，不应该继续使用EAWorker实例提交任务。 + +**ArkTS 版本：** 该接口仅适用于ArkTS1.2。 + +**示例：** +```ts +import hilog from '@ohos.hilog' + +let eaw = new EAWorker(); +eaw.run(() => { + hilog.info(0x0000, "testTag", "hello"); +}); + +eaw.join(); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/native-lib/eaworker_native.md b/zh-cn/application-dev/reference/native-lib/eaworker_native.md new file mode 100644 index 0000000000000000000000000000000000000000..eae083c9cfef7511a2643ad73b6cbd07b15e7f38 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/eaworker_native.md @@ -0,0 +1,98 @@ +# EAWorker（独占线程任务执行器）(C/C++) +开发者可以通过[AttachCurrentThread](#attachcurrentthread)接口将当前线程提供给ArkTS1.2虚拟机，并获取静态虚拟机的env。开发者可以使用该env在当前执行特定重载/长时任务，避免对于ArkTS1.2虚拟机系统调用造成影响。任务完成后，开发者需要手动调用[DetachCurrentThread](#detachcurrentthread)释放对应的系统资源。 + +文档中涉及到概念以及解释： +- 互操作（interop）：ArkTS1.2和ArkTS1.1代码相互操作。 +- ANI：ArkTS1.2 Native Interface，ArkTS1.2的原生操作接口。 + +## AttachCurrentThread +ani_status AttachCurrentThread(ani_vm *vm, const ani_options *options, uint32_t version, ani_env **result) + +将当前Native线程附加到ArkTS1.2虚拟机，并获取对应的ani_env指针，以便在该线程中执行特定任务。此操作允许Native线程使用虚拟机提供的功能调用ArkTS1.2函数。 + +**ArkTS版本：** 该接口仅适用于ArkTS1.2。 + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +|---------------|------------------|------------|----------------------------------------------------------------------| +| vm | ani_vm* | 是 | ArkTS1.2虚拟机实例句柄。 | +| options | ani_options* | 是 | 用于控制创建的EAWorker是否支持interop。使用方式见示例。| +| version | uint32_t | 是 | ANI接口版本标识。 | +| result | ani_env** | 是 | 输出参数，返回绑定成功的线程执行环境指针。 | + + +**返回值：** +| 类型 | 说明 | +| ---------- | -------------------------- | +| ani_status | AttachCurrentThread接口调用的结果。
- ANI_OK表示接口调用成功。
- ANI_ERROR表示接口调用失败。
- ANI_INVALID_ARGS表示参数校验失败。
- ANI_INVALID_VERSION表示ANI版本校验失败。
- ANI_ALREADY_ATTACHED表示当前线程已经attach，开发者尝试重复attach同一个线程。 | + +**示例：** + +在Native侧将当前线程提供给虚拟机创建不支持interop的EAWorker。 +```cpp +std::thread worker((){ + ani_env *workerEnv = nullptr; + ani_options aniArgs {0, nullptr}; + + auto status = vm_->AttachCurrentThread(&aniArgs, ANI_VERSION_1, &workerEnv); +}) +``` + +在Native侧将当前线程提供给虚拟机创建支持interop的EAWorker。 +```cpp +std::thread worker((){ + ani_env *workerEnv = nullptr; + ani_option interopEnabled {"--interop=enable", nullptr}; + ani_options aniArgs {1, &interopEnabled}; + + auto status = vm_->AttachCurrentThread(&aniArgs, ANI_VERSION_1, &workerEnv); +}) +``` + +## DetachCurrentThread +ani_status DetachCurrentThread(ani_vm *vm) + +解除当前Native线程与ArkTS1.2虚拟机的绑定关系，释放线程关联的虚拟机资源。必须与[AttachCurrentThread](#attachcurrentthread)严格配对使用。 + +> **说明：** +> +> DetachCurrentThread会销毁虚拟机侧对应的资源，Detach之后开发者不应该在当前线程继续调用ArkTS1.2函数。 + +**ArkTS版本：** 该接口仅适用于ArkTS1.2。 + +**参数：** +| 参数名 | 类型 | 必填 | 说明 | +|-----------|--------------|-------|----------------------------------------------------------------------| +| vm | ani_vm* | 是 | 有效的ArkTS1.2虚拟机实例句柄。 | + +**返回值：** +| 类型 | 说明 | +| ---------- | -------------------------- | +| ani_status | DetachCurrentThread接口调用的结果。
- ANI_OK表示接口调用成功。
- ANI_ERROR表示接口调用失败。
- ANI_INVALID_ARGS表示用户传入参数校验失败。
- ANI_ALREADY_DETACHED表示当前线程已经detach，开发者尝试重复detach同一个线程。 | + +**示例：** + +在Native侧销毁不支持interop的EAWorker。 +```cpp +std::thread worker((){ + ani_env *workerEnv = nullptr; + ani_options aniArgs {0, nullptr}; + + auto status = vm_->AttachCurrentThread(&aniArgs, ANI_VERSION_1, &workerEnv); + +    status = vm_->DetachCurrentThread(); +}) +``` + +在Native侧销毁支持interop的EAWorker。 +```cpp +std::thread worker((){ + ani_env *workerEnv = nullptr; + ani_option interopEnabled {"--interop=enable", nullptr}; + ani_options aniArgs {1, &interopEnabled}; + + auto status = vm_->AttachCurrentThread(&aniArgs, ANI_VERSION_1, &workerEnv); + +    status = vm_->DetachCurrentThread(); +}) +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/native-lib/job.md b/zh-cn/application-dev/reference/native-lib/job.md new file mode 100644 index 0000000000000000000000000000000000000000..11fd6737d69d02051cdb8f192dc31b3ed1a8e653 --- /dev/null +++ b/zh-cn/application-dev/reference/native-lib/job.md @@ -0,0 +1,152 @@ +# Job（获取EAWorker任务执行结果） +[EAWorker](./eaworker_managed.md#eaworker)执行任务返回值的句柄，用于表征一个任务，可以通过[Await](#await)等待获取任务的返回值。 + +## Await +Await(): T + +用于获得[Job](#job)的值。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**返回值：** +| 类型 | 说明 | +| -------- | ------------------ | +| T | 开发者提交任务的返回值，其类型和开发者提交任务时候指定的泛型类型一致。 | + +**示例：** +```ts +import hilog from '@ohos.hilog' + +// 定义任务函数 +function logNumber(arg: int): int { + hilog.info(0x0000, "testTag", "Received number: " + arg); + return arg * 2; +} + +// 创建Worker并提交任务 +const worker = new EAWorker(); +const job = worker.run(logNumber, 42); + +// 获取异步结果 +hilog.info(0x0000, "testTag", "Result: " + job.Await()); // 输出：Result: 84 +``` + +# CompletableJob +继承自[Job](#job)，开发者可以手动创建CompletableJob实例，并通过[finish](#finish)以及[fail](#fail)方法给实例赋值。其中finish可用于表征任务执行成功并将结果设置到实例中，fail表示任务执行失败并将失败的原因赋值到实例中。开发者可以通过[Await](#await-1)方法获取任务的执行结果。 + +## constructor +constructor() + +[CompletableJob](#completablejob)的构造器，用于构造一个开发者能够设置任务成功与失败的CompletableJob实例。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**示例：** +```ts +// 创建一个能接受String类型作为任务完成值类型的CompletableJob +let job = new CompletableJob() +``` + +## finish +finish() + +用于将一个[CompletableJob](#completablejob)状态置为完成态，并将值设置为undefined。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**示例：** +```ts +let job = new CompletableJob(); +job.finish(); +``` + +## finish +finish\(value: T) + +用于将一个[CompletableJob](#completablejob)状态设置为完成态，并将其值设置为开发者传入的value。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**参数：** +|参数名|类型|必填|说明| +|-----|----|--|----| +|value|T|是|设置CompletableJob的值。| + +**示例：** +```ts +let job = new CompletableJob(); +job.finish("finished"); +``` + +## fail +fail() + +用于将一个[CompletableJob](#completablejob)状态设置为失败，并将值设置为一个空的Error。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**示例：** +```ts +let job = new CompletableJob(); +job.fail(); +``` + +## fail +fail(error: Error) + +用于将一个[CompletableJob](#completablejob)状态设置为失败，并将其值设置为开发者传入的error。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**参数：** +|参数名|类型|必填|说明| +|------|----|---|---| +|error| Error|是|设置CompletableJob失败的值。| + +**示例：** +```ts +let job = new CompletableJob(); +job.fail(new Error("job failed")); +``` + +## Await +Await(): T + +用于获取[CompletableJob](#completablejob)的值。 + +**ArkTS 版本：** 本接口仅支持ArkTS1.2。 + +**返回值：** +| 类型 | 说明 | +| -------- | ------------------ | +| T | CompletableJob的值，其类型和开发者创建CompletableJob时候指定的泛型类型一致。 | + +**示例：** + +通过Await获取完成状态的CompletableJob的值。 +```ts +import hilog from '@ohos.hilog' + +let job = new CompletableJob(); +job.finish("job finished"); + +hilog.info(0x0000, "testTag", job.Await()); // 输出job finished + +let job2 = new CompletableJob(); +job2.finish(2); + +hilog.info(0x0000, "testTag", job2.Await());// 输出 2 +``` +通过Await获取失败状态的CompletableJob +的值。 +```ts +import hilog from '@ohos.hilog' + +let job = new CompletableJob(); +try { + job.fail(new Error("job executed error")); + job.Await(); +} catch(e: Error) { + hilog.error(0x0000, "testTag", e.toString()); // 输出Error: job executed error +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/security/UserAuthenticationKit/start-authentication.md b/zh-cn/application-dev/security/UserAuthenticationKit/start-authentication.md index c7fa75a1c545a9285c1c8188d2a39ad6fdcf4610..d8f681d76151267daa8d8144133d67ba799b5c36 100644 --- a/zh-cn/application-dev/security/UserAuthenticationKit/start-authentication.md +++ b/zh-cn/application-dev/security/UserAuthenticationKit/start-authentication.md @@ -75,6 +75,8 @@ 发起用户认证，采用认证可信等级≥ATL3的人脸+锁屏密码认证，获取认证结果： + ArkTS1.1示例： + ```ts // API version 10 import { BusinessError } from '@kit.BasicServicesKit'; @@ -114,10 +116,55 @@ try { console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); } ``` + +ArkTS1.2示例： + +```ts +// API version 20 +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; + +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; // Generate a 16-byte random number. + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + // 设置认证参数。 + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.PIN, userAuth.UserAuthType.FACE], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + }; + // 配置认证界面。 + const widgetParam: userAuth.WidgetParam = { + title: '请进行身份认证', + }; + // 获取认证对象。 + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 订阅认证结果。 + userAuthInstance.on('result', { + onResult: (result) => { + console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); + // 可在认证结束或其他业务需要场景，取消订阅认证结果。 + userAuthInstance.off('result'); + } + }); + console.info('auth on success'); + userAuthInstance.start(); + console.info('auth start success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} +``` + **示例2：** 发起用户认证，采用认证可信等级≥ATL3的人脸 + 认证类型相关 + 复用设备解锁最大有效时长认证，获取认证结果： +ArkTS1.1示例： + ```ts // API version 10 import { BusinessError } from '@kit.BasicServicesKit'; @@ -162,10 +209,60 @@ try { console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); } ``` + +ArkTS1.2示例： + +```ts +// API version 20 +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; + +// 设置认证参数。 +let reuseUnlockResult: userAuth.ReuseUnlockResult = { + reuseMode: userAuth.ReuseMode.AUTH_TYPE_RELEVANT, + reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, +} +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.FACE], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + reuseUnlockResult: reuseUnlockResult, + }; + // 配置认证界面。 + const widgetParam: userAuth.WidgetParam = { + title: '请进行身份认证', + }; + // 获取认证对象。 + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 订阅认证结果。 + userAuthInstance.on('result', { + onResult: (result) => { + console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); + // 可在认证结束或其他业务需要场景，取消订阅认证结果。 + userAuthInstance.off('result'); + } + }); + console.info('auth on success'); + userAuthInstance.start(); + console.info('auth start success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} +``` + **示例3：** 发起用户认证，采用认证可信等级≥ATL3的人脸 + 任意应用认证类型相关 + 复用任意应用最大有效时长认证，获取认证结果： +ArkTS1.1示例： + ```ts // API version 14 import { BusinessError } from '@kit.BasicServicesKit'; @@ -211,10 +308,59 @@ try { } ``` +ArkTS1.2示例： + +```ts +// API version 20 +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; + +// 设置认证参数。 +let reuseUnlockResult: userAuth.ReuseUnlockResult = { + reuseMode: userAuth.ReuseMode.CALLER_IRRELEVANT_AUTH_TYPE_RELEVANT, + reuseDuration: userAuth.MAX_ALLOWABLE_REUSE_DURATION, +} +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.FACE], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + reuseUnlockResult: reuseUnlockResult, + }; + // 配置认证界面。 + const widgetParam: userAuth.WidgetParam = { + title: '请进行身份认证', + }; + // 获取认证对象。 + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 订阅认证结果。 + userAuthInstance.on('result', { + onResult: (result) => { + console.info(`userAuthInstance callback result: ${JSON.stringify(result)}`); + // 可在认证结束或其他业务需要场景，取消订阅认证结果。 + userAuthInstance.off('result'); + } + }); + console.info('auth on success'); + userAuthInstance.start(); + console.info('auth start success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} +``` + **示例4：** 以模应用方式进行用户身份认证： +ArkTS1.1示例： + ```ts // API version 16 import { BusinessError } from '@kit.BasicServicesKit'; @@ -247,4 +393,41 @@ try { const err: BusinessError = error as BusinessError; console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); } +``` + +ArkTS1.2示例： + +```ts +// API version 20 +import { BusinessError } from '@kit.BasicServicesKit'; +import { cryptoFramework } from '@kit.CryptoArchitectureKit'; +import { userAuth } from '@kit.UserAuthenticationKit'; +import Context from ''./application/Context; + +try { + const rand = cryptoFramework.createRandom(); + const len: number = 16; + const randData: Uint8Array = rand?.generateRandomSync(len)?.data; + const authParam: userAuth.AuthParam = { + challenge: randData, + authType: [userAuth.UserAuthType.PIN], + authTrustLevel: userAuth.AuthTrustLevel.ATL3, + }; + const widgetParam: userAuth.WidgetParam = { + title: '请输入密码', + uiContext: this.getUIContext().getHostContext(), + }; + const userAuthInstance = userAuth.getUserAuthInstance(authParam, widgetParam); + console.info('get userAuth instance success'); + // 需要调用UserAuthInstance的start()接口，启动认证后，才能通过onResult获取到认证结果。 + userAuthInstance.on('result', { + onResult: (result) => { + console.info(`userAuthInstance callback result = ${JSON.stringify(result)}`); + } + }); + console.info('auth on success'); +} catch (error) { + const err: BusinessError = error as BusinessError; + console.error(`auth catch error. Code is ${err?.code}, message is ${err?.message}`); +} ``` \ No newline at end of file