本模块提供了各种ArkTS实用工具函数。

本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { ArkTSUtils } from '@kit.ArkTS'

ArkTSUtils.locks

为了解决多并发实例间的数据竞争问题，ArkTS语言基础库引入了异步锁能力。为了开发者的开发效率，AsyncLock对象支持跨并发实例引用传递。

由于ArkTS语言支持异步操作，阻塞锁容易产生死锁问题，因此我们在ArkTS中仅支持异步锁（非阻塞式锁）。

使用异步锁的方法需要标记为async，调用方需要await修饰调用，才能保证时序正确。因此会导致外层调用函数全部标记成async。

AsyncLockCallback

type AsyncLockCallback<T> = () => T | Promise<T>

这是一个补充类型别名，表示lockAsync函数所有重载中的回调。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

AsyncLock

实现异步锁功能的类，允许在锁下执行异步操作。

属性

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

名称类型可读可写说明
namestring是否锁的名称。

示例：

// 示例一：
@Sendable
class A {
  count_: number = 0;
  async getCount(): Promise<number> {
    let lock: ArkTSUtils.locks.AsyncLock = ArkTSUtils.locks.AsyncLock.request("lock_1");
    return lock.lockAsync(() => {
      return this.count_;
    })
  }
  async setCount(count: number) {
    let lock: ArkTSUtils.locks.AsyncLock = ArkTSUtils.locks.AsyncLock.request("lock_1");
    await lock.lockAsync(() => {
      this.count_ = count;
    })
  }
}

// 示例二：
@Sendable
class A {
  count_: number = 0;
  lock_: ArkTSUtils.locks.AsyncLock = new ArkTSUtils.locks.AsyncLock();
  async getCount(): Promise<number> {
    return this.lock_.lockAsync(() => {
      return this.count_;
    })
  }
  async setCount(count: number) {
    await this.lock_.lockAsync(() => {
      this.count_ = count;
    })
  }
}

@Concurrent
async function foo(a: A) {
  await a.setCount(10)
}

constructor

constructor()

默认构造函数。创建一个异步锁。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型说明
AsyncLock创建的异步锁实例。

示例：

let lock = new ArkTSUtils.locks.AsyncLock();

request

static request(name: string): AsyncLock

使用指定的名称查找或创建（如果未找到）异步锁实例。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

名称类型必填说明
namestring是按指定名称查找或创建异步锁实例。

返回值：

类型说明
AsyncLock返回查找到或创建后的异步锁实例。

示例：

let lockName = 'isAvailableLock';
let lock = ArkTSUtils.locks.AsyncLock.request(lockName);

query

static query(name: string): AsyncLockState

查询指定异步锁的信息。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

名称类型必填说明
namestring是锁的名称。

返回值：

类型说明
AsyncLockState一个包含状态描述的异步锁状态实例。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID错误信息
10200030The lock does not exist.

示例：

// 你已经在别的地方创建了一个锁。
// let lock = ArkTSUtils.locks.AsyncLock.request("queryTestLock");
let state = ArkTSUtils.locks.AsyncLock.query('queryTestLock');
if (!state) {
    throw new Error('测试失败：期望有效的状态，但得到的是 ' + state);
}
let pending: ArkTSUtils.locks.AsyncLockInfo[] = state.pending;
let held: ArkTSUtils.locks.AsyncLockInfo[] = state.held;

queryAll

static queryAll(): AsyncLockState[]

查询所有现有锁的信息。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型说明
AsyncLockState[]包含锁状态信息的异步锁状态数组。

示例：

let states: ArkTSUtils.locks.AsyncLockState[] = ArkTSUtils.locks.AsyncLock.queryAll();
if (states.length == 0) {
    throw new Error('测试失败：期望至少有1个状态，但得到的是 ' + states.length);
}

lockAsync

lockAsync<T>(callback: AsyncLockCallback<T>): Promise<T>

在获取的锁下独占执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用lockAsync的同一线程中以异步方式执行。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

名称类型必填说明
callbackAsyncLockCallback是获取锁后要调用的函数。

返回值：

类型说明
Promise<T>回调执行后将解决的Promise。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID错误信息
10200030The lock does not exist.

示例：

let lock = new ArkTSUtils.locks.AsyncLock();
let p1 = lock.lockAsync<void>(() => {
    // 执行某些操作
});

lockAsync

lockAsync<T>(callback: AsyncLockCallback<T>, mode: AsyncLockMode): Promise<T>

在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用lockAsync的同一线程中以异步方式执行。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

名称类型必填说明
callbackAsyncLockCallback是获取锁后要调用的函数。
modeAsyncLockMode是锁的操作模式。

返回值：

类型说明
Promise<T>回调执行后将解决的Promise。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID错误信息
10200030The lock does not exist.

示例：

let lock = new ArkTSUtils.locks.AsyncLock();
let p1 = lock.lockAsync<void>(() => {
    // 执行某些操作
}, ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE);

lockAsync

lockAsync<T, U>(callback: AsyncLockCallback<T>, mode: AsyncLockMode, options: AsyncLockOptions<U>): Promise<T | U>

在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用lockAsync的同一线程中以异步方式执行。在AsyncLockOptions中可以提供一个可选的超时值。在这种情况下，如果超时前未能获取锁，lockAsync将拒绝返回的Promise并带上一个BusinessError实例。这种情况下，错误信息将包含持有的锁和等待的锁的信息以及可能的死锁警告。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

名称类型必填说明
callbackAsyncLockCallback是获取锁后要调用的函数。
modeAsyncLockMode是锁的操作模式。
optionsAsyncLockOptions<U>是锁的操作选项。

返回值：

类型说明
Promise<T | U>回调执行后解决的 Promise，或者在超时情况下被拒绝。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID错误信息
10200030The lock does not exist.
10200031Timeout exceeded.

示例：

let lock = new ArkTSUtils.locks.AsyncLock();
let options = new ArkTSUtils.locks.AsyncLockOptions<void>();
options.timeout = 1000;
let p: Promise<void> = lock.lockAsync<void, void>(
    () => {
        // 执行某些操作
    },
    ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE,
    options
);

AsyncLockMode

锁操作对应的模式枚举。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

名称值说明
SHARED1共享锁操作。如果指定了此模式，操作可以在同一线程中重入。
EXCLUSIVE2独占锁操作。如果指定了此模式，仅在独占获取锁时执行操作。

AsyncLockOptions

class AsyncLockOptions<T>

表示锁操作选项的类。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

constructor

constructor()

默认构造函数。创建一个所有属性均具有默认值的异步锁配置项实例。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型说明
AsyncLockOptions新的异步锁配置项实例。

示例：

let s: ArkTSUtils.locks.AbortSignal<string> = { aborted: false, reason: 'Aborted' };
let options = new ArkTSUtils.locks.AsyncLockOptions<string>();
options.isAvailable = false;
options.signal = s;

属性

名称类型可读可写说明
isAvailableboolean是是当前锁是否可用。取值为true，则只有在尚未持有锁定请求时才会授予该锁定请求；为false则表示将等待当前锁被释放。默认为 false。
signalAbortSignal<T>|null是是用于中止异步操作的对象。如果signal.aborted为true，则锁请求将被丢弃；为null则请求正常排队运行。默认为 null。
timeoutnumber是是锁操作的超时时间（毫秒）。如果该值大于零，且运行超过该时间，lockAsync将返回被拒绝的Promise。默认为 0。

AsyncLockState

用于存储特定异步锁实例上当前执行的所有锁操作的信息的类。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

属性

名称类型可读可写说明
heldAsyncLockInfo[]是是持有的锁信息。
pendingAsyncLockInfo[]是是等待中的锁信息。

AsyncLockInfo

关于锁的信息。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

属性

名称类型可读可写说明
namestring是是锁的名称。
modeAsyncLockMode是是锁的模式。
contextIdnumber是是AsyncLockMode调用者的执行上下文标识符。

AbortSignal

用于中止异步操作的对象。该类的实例必须在其创建的同一线程中访问。从其他线程访问此类的字段会导致未定义的行为。

元服务API：从API version 12 开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

属性

名称类型可读可写说明
abortedboolean是是设置为true以中止操作。
reason<T>是是中止的原因。此值将用于拒绝lockAsync返回的Promise。

ArkTSUtils.ASON

为支持将JSON字符串解析成共享数据，ArkTS语言基础库新增了ASON工具。ASON支持开发者解析JSON字符串，并生成共享数据进行跨并发域传输，同时ASON也支持将共享数据转换成JSON字符串。

ISendable

type ISendable = lang.ISendable

ISendable是所有Sendable类型（除null和undefined）的父类型。自身没有任何必须的方法和属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

类型说明
lang.ISendable所有Sendable类型的父类型。

parse

parse(text: string): ISendable | null

用于解析JSON字符串生成ISendable数据或null。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名类型必填说明
textstring是有效的JSON字符串。

返回值：

类型说明
ISendable | null返回ISendable数据或null。当入参是null时，返回null。

示例：

import { lang } from '@kit.ArkTS';

type ISendable = lang.ISendable;
let jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
let obj = ArkTSUtils.ASON.parse(jsonText) as ISendable;
console.info((obj as object)?.["name"]);
// 期望输出: 'John'
console.info((obj as object)?.["age"]);
// 期望输出: 30
console.info((obj as object)?.["city"]);
// 期望输出: 'ChongQing'

stringify

stringify(value: ISendable | null | undefined): string

该方法将ISendable数据转换为JSON字符串。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名类型必填说明
valueISendable | null | undefined是ISendable数据。

返回值：

类型说明
string转换后的JSON字符串。

示例：

import { collections } from '@kit.ArkTS';

let arr = new collections.Array(1, 2, 3);
let str = ArkTSUtils.ASON.stringify(arr);
console.info(str);
// 期望输出: '[1,2,3]'

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）资料用来跟着学习是非常有必要的。 

点击领取→【纯血版鸿蒙全套最新学习资料】（安全链接，放心点击）希望这一份鸿蒙学习资料能够给大家带来帮助，有需要的小伙伴自行领取~限时开源！！

 鸿蒙（HarmonyOS NEXT）最新学习路线

​

有了路线图，怎么能没有学习资料呢，小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙（OpenHarmony ）学习手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门教学视频，内容包含：ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习资料

这份鸿蒙（HarmonyOS NEXT）资料包含了鸿蒙开发必掌握的核心知识要点，内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、（南向驱动、嵌入式等）鸿蒙项目实战等等）鸿蒙（HarmonyOS NEXT）技术知识点。


HarmonyOS Next 最新全套视频教程

​

 《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

​

《鸿蒙开发基础》

  • ArkTS语言
  • 安装DevEco Studio
  • 运用你的第一个ArkTS应用
  • ArkUI声明式UI开发
  • .……​

《鸿蒙开发进阶》

  • Stage模型入门
  • 网络管理
  • 数据管理
  • 电话服务
  • 分布式应用开发
  • 通知与窗口管理
  • 多媒体技术
  • 安全技能
  • 任务管理
  • WebGL
  • 国际化开发
  • 应用测试
  • DFX面向未来设计
  • 鸿蒙系统移植和裁剪定制
  • ……

​

《鸿蒙进阶实战》

  • ArkTS实践
  • UIAbility应用
  • 网络案例
  • ……

​

大厂面试必问面试题

​

鸿蒙南向开发技术

​

鸿蒙APP开发必备

​
请点击→纯血版全套鸿蒙HarmonyOS学习资料

总的来说，华为鸿蒙不再兼容安卓，对中年程序员来说是一个挑战，也是一个机会。只有积极应对变化，不断学习和提升自己，才能在这个变革的时代中立于不败之地。 

                   

# 前端 # 服务器 # harmonyos # 鸿蒙系统 # linux # 数据库
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙UI系统组件06——进度条(Progress)

avatar HarmonyOS开发者社区
cover

鸿蒙Native项目生产动态库(.so) 和静态库(.a)

avatar HarmonyOS开发者社区
cover

鸿蒙（API 12 Beta3版）【自定义界面扫码】

avatar HarmonyOS开发者社区