1# @arkts.utils (ArkTS工具库) 2 3本模块提供了各种ArkTS实用工具函数。 4 5> **说明：** 6> 7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 此模块仅支持在ArkTS文件（文件后缀为.ets）中导入使用。 10 11## 导入模块 12 13```ts 14import { ArkTSUtils } from '@kit.ArkTS' 15``` 16 17## ArkTSUtils.locks 18 19为了解决多并发实例间的数据竞争问题，ArkTS语言基础库引入了异步锁能力。为了开发者的开发效率，AsyncLock对象支持跨并发实例引用传递。 20 21由于ArkTS语言支持异步操作，阻塞锁容易产生死锁问题，因此我们在ArkTS中仅支持异步锁（非阻塞式锁）。 22 23使用异步锁的方法需要标记为async，调用方需要await修饰调用，才能保证时序正确。因此会导致外层调用函数全部标记成async。 24 25### AsyncLockCallback 26 27type AsyncLockCallback\<T> = () => T | Promise\<T> 28 29这是一个补充类型别名，表示[lockAsync](#lockasync)函数所有重载中的回调。 30 31**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 32 33**系统能力：** SystemCapability.Utils.Lang 34 35### AsyncLock 36 37实现异步锁功能的类，允许在锁下执行异步操作。该类使用[@Sendable装饰器](../../arkts-utils/arkts-sendable.md)装饰。 38 39#### 属性 40 41**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.Utils.Lang 44 45| 名称 | 类型 | 可读 | 可写 | 说明 | 46| ---- | ------ | ---- | ---- | ---------- | 47| name | string | 是 | 否 | 锁的名称。 | 48 49**示例：** 50 51```ts 52// 示例一： 53@Sendable 54class A { 55 count_: number = 0; 56 async getCount(): Promise<number> { 57 let lock: ArkTSUtils.locks.AsyncLock = ArkTSUtils.locks.AsyncLock.request("lock_1"); 58 return lock.lockAsync(() => { 59 return this.count_; 60 }) 61 } 62 async setCount(count: number) { 63 let lock: ArkTSUtils.locks.AsyncLock = ArkTSUtils.locks.AsyncLock.request("lock_1"); 64 await lock.lockAsync(() => { 65 this.count_ = count; 66 }) 67 } 68} 69 70// 示例二： 71@Sendable 72class A { 73 count_: number = 0; 74 lock_: ArkTSUtils.locks.AsyncLock = new ArkTSUtils.locks.AsyncLock(); 75 async getCount(): Promise<number> { 76 return this.lock_.lockAsync(() => { 77 return this.count_; 78 }) 79 } 80 async setCount(count: number) { 81 await this.lock_.lockAsync(() => { 82 this.count_ = count; 83 }) 84 } 85} 86 87@Concurrent 88async function foo(a: A) { 89 await a.setCount(10) 90} 91``` 92 93#### constructor 94 95constructor() 96 97默认构造函数。创建一个异步锁。 98 99**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 100 101**系统能力：** SystemCapability.Utils.Lang 102 103**返回值：** 104 105| 类型 | 说明 | 106| ----------------------- | ------------------ | 107| [AsyncLock](#asynclock) | 创建的异步锁实例。 | 108 109**示例：** 110 111```ts 112let lock = new ArkTSUtils.locks.AsyncLock(); 113``` 114 115#### request 116 117static request(name: string): AsyncLock 118 119使用指定的名称查找或创建（如果未找到）异步锁实例。 120 121**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.Utils.Lang 124 125**参数：** 126 127| 名称 | 类型 | 必填 | 说明 | 128| ---- | ------ | ---- | -------------------------------- | 129| name | string | 是 | 按指定名称查找或创建异步锁实例。 | 130 131**返回值：** 132 133| 类型 | 说明 | 134| ----------------------- | -------------------------------- | 135| [AsyncLock](#asynclock) | 返回查找到或创建后的异步锁实例。 | 136 137**示例：** 138 139```ts 140let lockName = 'isAvailableLock'; 141let lock = ArkTSUtils.locks.AsyncLock.request(lockName); 142``` 143 144#### query 145 146static query(name: string): AsyncLockState 147 148查询指定异步锁的信息。 149 150**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 151 152**系统能力：** SystemCapability.Utils.Lang 153 154**参数：** 155 156| 名称 | 类型 | 必填 | 说明 | 157| ---- | ------ | ---- | ---------- | 158| name | string | 是 | 锁的名称。 | 159 160**返回值：** 161 162| 类型 | 说明 | 163| --------------------------------- | ---------------------------------- | 164| [AsyncLockState](#asynclockstate) | 一个包含状态描述的异步锁状态实例。 | 165 166**错误码：** 167 168以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 169 170| 错误码ID | 错误信息 | 171| -------- | ------------- | 172| 401 | The input parameters are invalid. | 173| 10200030 | The lock does not exist. | 174 175**示例：** 176 177```ts 178// 你已经在别的地方创建了一个锁。 179// let lock = ArkTSUtils.locks.AsyncLock.request("queryTestLock"); 180let state = ArkTSUtils.locks.AsyncLock.query('queryTestLock'); 181if (!state) { 182 throw new Error('测试失败：期望有效的状态，但得到的是 ' + state); 183} 184let pending: ArkTSUtils.locks.AsyncLockInfo[] = state.pending; 185let held: ArkTSUtils.locks.AsyncLockInfo[] = state.held; 186``` 187 188#### queryAll 189 190static queryAll(): AsyncLockState[] 191 192查询所有现有锁的信息。 193 194**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 195 196**系统能力：** SystemCapability.Utils.Lang 197 198**返回值：** 199 200| 类型 | 说明 | 201| ----------------------------------- | -------------------------------- | 202| [AsyncLockState](#asynclockstate)[] | 包含锁状态信息的异步锁状态数组。 | 203 204**示例：** 205 206```ts 207let states: ArkTSUtils.locks.AsyncLockState[] = ArkTSUtils.locks.AsyncLock.queryAll(); 208if (states.length === 0) { 209 throw new Error('测试失败：期望至少有1个状态，但得到的是 ' + states.length); 210} 211``` 212 213#### lockAsync 214 215lockAsync\<T>(callback: AsyncLockCallback\<T>): Promise\<T> 216 217在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用[lockAsync](#lockasync)的同一线程中以异步方式执行。 218 219**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 220 221**系统能力：** SystemCapability.Utils.Lang 222 223**参数：** 224 225| 名称 | 类型 | 必填 | 说明 | 226| -------- | --------------------------------------- | ---- | ---------------------- | 227| callback | [AsyncLockCallback](#asynclockcallback) | 是 | 获取锁后要调用的函数。 | 228 229**返回值：** 230 231| 类型 | 说明 | 232| ----------- | --------------------------- | 233| Promise\<T> | 回调执行后将解决的Promise。 | 234 235**错误码：** 236 237以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 238 239| 错误码ID | 错误信息 | 240| -------- | ------------- | 241| 401 | The input parameters are invalid. | 242| 10200030 | The lock does not exist. | 243 244**示例：** 245 246```ts 247let lock = new ArkTSUtils.locks.AsyncLock(); 248let p1 = lock.lockAsync<void>(() => { 249 // 执行某些操作 250}); 251``` 252 253#### lockAsync 254 255lockAsync\<T>(callback: AsyncLockCallback\<T>, mode: AsyncLockMode): Promise\<T> 256 257在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用[lockAsync](#lockasync)的同一线程中以异步方式执行。 258 259**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 260 261**系统能力：** SystemCapability.Utils.Lang 262 263**参数：** 264 265| 名称 | 类型 | 必填 | 说明 | 266| -------- | --------------------------------------- | ---- | ---------------------- | 267| callback | [AsyncLockCallback](#asynclockcallback) | 是 | 获取锁后要调用的函数。 | 268| mode | [AsyncLockMode](#asynclockmode) | 是 | 锁的操作模式。 | 269 270**返回值：** 271 272| 类型 | 说明 | 273| ----------- | --------------------------- | 274| Promise\<T> | 回调执行后将解决的Promise。 | 275 276**错误码：** 277 278以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 279 280| 错误码ID | 错误信息 | 281| -------- | ------------- | 282| 401 | The input parameters are invalid. | 283| 10200030 | The lock does not exist. | 284 285**示例：** 286 287```ts 288let lock = new ArkTSUtils.locks.AsyncLock(); 289let p1 = lock.lockAsync<void>(() => { 290 // 执行某些操作 291}, ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE); 292``` 293 294#### lockAsync 295 296lockAsync\<T, U>(callback: AsyncLockCallback\<T>, mode: AsyncLockMode, options: AsyncLockOptions\<U>): Promise\<T | U> 297 298在获取的锁下执行操作。该方法首先获取锁，然后调用回调，最后释放锁。回调在调用[lockAsync](#lockasync)的同一线程中以异步方式执行。在[AsyncLockOptions](#asynclockoptions)中可以提供一个可选的超时值。在这种情况下，如果超时前未能获取锁，lockAsync将拒绝返回的Promise并带上一个BusinessError实例。这种情况下，错误信息将包含持有的锁和等待的锁的信息以及可能的死锁警告。 299 300**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 301 302**系统能力：** SystemCapability.Utils.Lang 303 304**参数：** 305 306| 名称 | 类型 | 必填 | 说明 | 307| -------- | ----------------------------------------- | ---- | ---------------------- | 308| callback | [AsyncLockCallback](#asynclockcallback) | 是 | 获取锁后要调用的函数。 | 309| mode | [AsyncLockMode](#asynclockmode) | 是 | 锁的操作模式。 | 310| options | [AsyncLockOptions\<U>](#asynclockoptions) | 是 | 锁的操作选项。 | 311 312**返回值：** 313 314| 类型 | 说明 | 315| ---------------- | -------------------------------------------------- | 316| Promise\<T \| U> | 回调执行后解决的Promise，或者在超时情况下被拒绝。 | 317 318**错误码：** 319 320以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 321 322| 错误码ID | 错误信息 | 323| -------- | ----------------- | 324| 401 | The input parameters are invalid. | 325| 10200030 | The lock does not exist. | 326| 10200031 | Timeout exceeded. | 327 328**示例：** 329 330```ts 331let lock = new ArkTSUtils.locks.AsyncLock(); 332let options = new ArkTSUtils.locks.AsyncLockOptions<void>(); 333options.timeout = 1000; 334let p: Promise<void> = lock.lockAsync<void, void>( 335 () => { 336 // 执行某些操作 337 }, 338 ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE, 339 options 340); 341``` 342 343### AsyncLockMode 344 345锁操作对应的模式枚举。 346 347**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 348 349**系统能力：** SystemCapability.Utils.Lang 350 351| 名称 | 值 | 说明 | 352| --------- | --- | -------------------------------------------------------- | 353| SHARED | 1 | 共享锁模式。如果指定了此模式，可以在任意线程同时执行。 | 354| EXCLUSIVE | 2 | 独占锁模式。如果指定了此模式，仅在独占获取锁时才能执行。 | 355 356**示例：** 357 358```ts 359let lock = new ArkTSUtils.locks.AsyncLock(); 360// shared0可获取锁并开始执行 361lock.lockAsync(async () => { 362 console.info('shared0'); 363 await new Promise<void>((resolve) => setTimeout(resolve, 1000)); 364}, ArkTSUtils.locks.AsyncLockMode.SHARED); 365// shared1可获取锁并开始执行，无需等待shared0 366lock.lockAsync(async () => { 367 console.info('shared1'); 368 await new Promise<void>((resolve) => setTimeout(resolve, 1000)); 369}, ArkTSUtils.locks.AsyncLockMode.SHARED); 370// exclusive0需等待shared0、1执行完后才可获取锁并执行 371lock.lockAsync(async () => { 372 console.info('exclusive0'); 373 await new Promise<void>((resolve) => setTimeout(resolve, 1000)); 374}, ArkTSUtils.locks.AsyncLockMode.EXCLUSIVE); 375// shared2需等待exclusive0执行完后才可获取锁并执行 376lock.lockAsync(async () => { 377 console.info('shared2'); 378 await new Promise<void>((resolve) => setTimeout(resolve, 1000)); 379}, ArkTSUtils.locks.AsyncLockMode.SHARED); 380// shared3需等待exclusive0执行完后才可获取锁并执行，无需等待shared2 381lock.lockAsync(async () => { 382 console.info('shared3'); 383 await new Promise<void>((resolve) => setTimeout(resolve, 1000)); 384}, ArkTSUtils.locks.AsyncLockMode.SHARED); 385``` 386 387### AsyncLockOptions 388 389class AsyncLockOptions\<T> 390 391表示锁操作选项的类。 392 393**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 394 395**系统能力：** SystemCapability.Utils.Lang 396 397#### constructor 398 399constructor() 400 401默认构造函数。创建一个所有属性均具有默认值的异步锁配置项实例。 402 403**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 404 405**系统能力：** SystemCapability.Utils.Lang 406 407**返回值：** 408 409| 类型 | 说明 | 410| ------------------------------------- | ---------------------- | 411| [AsyncLockOptions](#asynclockoptions) | 新的异步锁配置项实例。 | 412 413**示例：** 414 415```ts 416let s: ArkTSUtils.locks.AbortSignal<string> = { aborted: false, reason: 'Aborted' }; 417let options = new ArkTSUtils.locks.AsyncLockOptions<string>(); 418options.isAvailable = false; 419options.signal = s; 420``` 421 422#### 属性 423 424| 名称 | 类型 | 可读 | 可写 | 说明 | 425| ----------- | ------------------------------------- | ---- | ---- | ------------------------------------------------------------------------------------------------------------------------- | 426| isAvailable | boolean | 是 | 是 | 当前锁是否可用。取值为true，则只有在尚未持有锁定请求时才会授予该锁定请求；为false则表示将等待当前锁被释放。默认为 false。 | 427| signal | [AbortSignal\<T>](#abortsignal)\|null | 是 | 是 | 用于中止异步操作的对象。当signal.aborted为true时，锁请求将被丢弃；当signal.aborted为false时，请求会继续等待获取锁；当signal为null时，请求正常排队运行。默认为 null。 | 428| timeout | number | 是 | 是 | 锁操作的超时时间（毫秒）。如果该值大于零，且运行超过该时间，[lockAsync](#lockasync)将返回被拒绝的Promise。默认为 0。 | 429 430### AsyncLockState 431 432用于存储特定异步锁实例上当前执行的所有锁操作的信息的类。 433 434**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 435 436**系统能力：** SystemCapability.Utils.Lang 437 438#### 属性 439 440| 名称 | 类型 | 可读 | 可写 | 说明 | 441| ------- | --------------------------------- | ---- | ---- | ---------------- | 442| held | [AsyncLockInfo[]](#asynclockinfo) | 是 | 是 | 持有的锁信息。 | 443| pending | [AsyncLockInfo[]](#asynclockinfo) | 是 | 是 | 等待中的锁信息。 | 444 445### AsyncLockInfo 446 447关于锁的信息。 448 449**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 450 451**系统能力：** SystemCapability.Utils.Lang 452 453#### 属性 454 455| 名称 | 类型 | 可读 | 可写 | 说明 | 456| --------- | ------------------------------- | ---- | ---- | --------------------------------------------------------- | 457| name | string | 是 | 是 | 锁的名称。 | 458| mode | [AsyncLockMode](#asynclockmode) | 是 | 是 | 锁的模式。 | 459| contextId | number | 是 | 是 | [AsyncLockMode](#asynclockmode)调用者的执行上下文标识符。 | 460 461### AbortSignal 462 463用于中止异步操作的对象。该类的实例必须在其创建的同一线程中访问。从其他线程访问此类的字段会导致未定义的行为。 464 465**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 466 467**系统能力：** SystemCapability.Utils.Lang 468 469#### 属性 470 471| 名称 | 类型 | 可读 | 可写 | 说明 | 472| ------- | ------- | ---- | ---- | ---------------------------------------------------------------- | 473| aborted | boolean | 是 | 是 | 是否终止异步操作。为true时表示中止异步操作，为false时表示异步操作未被中止。 | 474| reason | \<T> | 是 | 是 | 中止的原因。此值将用于拒绝[lockAsync](#lockasync)返回的Promise。 | 475 476### ConditionVariable<sup>18+</sup> 477 478实现异步等待功能的类，允许执行异步等待通知操作。 479 480**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 481 482**系统能力：** SystemCapability.Utils.Lang 483 484#### constructor<sup>18+</sup> 485 486constructor() 487 488默认构造函数。创建一个异步等待通知操作的对象。 489 490**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 491 492**系统能力：** SystemCapability.Utils.Lang 493 494**示例：** 495 496```ts 497let conditionVariable = new ArkTSUtils.locks.ConditionVariable(); 498``` 499 500#### request<sup>18+</sup> 501 502static request(name: string): ConditionVariable 503 504使用指定的名称查找或创建（如果未找到）异步等待通知操作的对象。 505 506**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 507 508**系统能力：** SystemCapability.Utils.Lang 509 510**参数：** 511 512| 名称 | 类型 | 必填 | 说明 | 513| ---- | ------ | ---- | -------------------------------- | 514| name | string | 是 | 按指定名称查找或创建等待通知操作的对象名称，字符串无特别限制。 | 515 516**返回值：** 517 518| 类型 | 说明 | 519| ----------------------- | -------------------------------- | 520| [ConditionVariable](#conditionvariable18) | 返回查找到或创建后的异步等待通知操作的实例。 | 521 522**示例：** 523 524```ts 525let conditionVariable = ArkTSUtils.locks.ConditionVariable.request("conditionName"); 526``` 527 528#### wait<sup>18+</sup> 529 530wait(): Promise\<void> 531 532异步调用进入等待中，将在被唤醒后继续执行。使用Promise异步回调。 533 534**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 535 536**系统能力：** SystemCapability.Utils.Lang 537 538**返回值：** 539 540| 类型 | 说明 | 541| ----------- | --------------------------- | 542| Promise\<void> | 无返回结果的Promise对象。 | 543 544**示例：** 545 546```ts 547let conditionVariable = ArkTSUtils.locks.AsyncLock.ConditionVariable(); 548conditionVariable.wait().then(() => { 549 console.info(`Thread being awakened, then continue...`); //被唤醒后输出日志 550}); 551``` 552 553#### waitFor<sup>18+</sup> 554 555waitFor(timeout : number) : Promise\<void> 556 557异步调用进入等待中, 将在被唤醒或者等待时间结束后继续执行。使用Promise异步回调。 558 559**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 560 561**系统能力：** SystemCapability.Utils.Lang 562 563**参数：** 564 565| 名称 | 类型 | 必填 | 说明 | 566| -------- | -------- | ---- | ---------- | 567| timeout | number | 是 | 等待时间，单位为ms，正整数。 | 568 569**返回值：** 570 571| 类型 | 说明 | 572| ----------- | --------------------------- | 573| Promise\<void> | 无返回结果的Promise对象。 | 574 575**示例：** 576 577```ts 578let conditionVariable = ArkTSUtils.locks.AsyncLock.ConditionVariable(); 579conditionVariable.waitFor(3000).then(() => { 580 console.info(`Thread being awakened, then continue...`); //被唤醒后输出日志 581}); 582``` 583 584#### notifyAll<sup>18+</sup> 585 586notifyAll() : void 587 588通知所有等待的线程。 589 590**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 591 592**系统能力：** SystemCapability.Utils.Lang 593 594**示例：** 595 596```ts 597let conditionVariable = ArkTSUtils.locks.AsyncLock.ConditionVariable(); 598conditionVariable.waitFor(3000).then(() => { 599 console.info(`Thread being awakened, then continue...`); //被唤醒后输出日志 600}); 601conditionVariable.notifyAll(); 602``` 603 604#### notifyOne<sup>18+</sup> 605 606notifyOne() : void 607 608通知第一个等待的线程。 609 610**原子化服务API**：从API version 18 开始，该接口支持在原子化服务中使用。 611 612**系统能力：** SystemCapability.Utils.Lang 613 614**示例：** 615 616```ts 617let conditionVariable = ArkTSUtils.locks.AsyncLock.ConditionVariable(); 618conditionVariable.waitFor(3000).then(() => { 619 console.info(`Thread a being awakened, then continue...`); //被唤醒后输出日志 620}); 621conditionVariable.waitFor().then(() => { 622 console.info(`Thread twob being awakened, then continue...`); //被唤醒后输出日志 623}); 624conditionVariable.notifyOne(); 625``` 626 627## ArkTSUtils.ASON 628 629为支持将JSON字符串解析成共享数据，即[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)，ArkTS语言基础库新增了ASON工具。ASON支持开发者解析JSON字符串，并生成共享数据进行跨并发域传输，同时ASON也支持将共享数据转换成JSON字符串。 630 631### ISendable 632 633type ISendable = lang.ISendable 634 635ISendable是所有Sendable类型（除`null`和`undefined`）的父类型。自身没有任何必须的方法和属性。 636 637**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 638 639**系统能力：** SystemCapability.Utils.Lang 640 641| 类型 | 说明 | 642| ------ | ------ | 643| [lang.ISendable](js-apis-arkts-lang.md#langisendable) | 所有Sendable类型的父类型。 | 644 645### Transformer 646 647type Transformer = (this: ISendable, key: string, value: ISendable | undefined | null) => ISendable | undefined | null 648 649用于转换结果函数的类型。 650 651**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 652 653**系统能力：** SystemCapability.Utils.Lang 654 655**参数：** 656 657| 参数名 | 类型 | 必填 | 说明 | 658| ------ | ------ | ---- | --------------- | 659| this | [ISendable](#isendable) | 是 | 在解析的键值对所属的对象。| 660| key | string | 是 | 属性名。| 661| value | [ISendable](#isendable) | 是 | 在解析的键值对的值。| 662 663**返回值：** 664 665| 类型 | 说明 | 666| -------- | -------- | 667| [ISendable](#isendable) \| undefined \| null | 返回转换结果后的ISendable对象或undefined或null。| 668 669### BigIntMode 670 671定义处理BigInt的模式。 672 673**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 674 675**系统能力：** SystemCapability.Utils.Lang 676 677| 名称 | 值| 说明 | 678| ------ | ------ | --------------- | 679| DEFAULT | 0 |不支持BigInt。| 680| PARSE_AS_BIGINT | 1 |当整数小于-(2^53-1)或大于(2^53-1)时，解析为BigInt。| 681| ALWAYS_PARSE_AS_BIGINT | 2 |所有整数都解析为BigInt。| 682 683### ParseReturnType 684 685定义解析结果的返回类型。 686 687**系统能力：** SystemCapability.Utils.Lang 688 689| 名称 | 值| 说明 | 690| ------ | ------ | --------------- | 691| OBJECT | 0 |返回 SendableObject 对象。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 692| MAP<sup>13+</sup> | 1 |返回 SendableMap 对象。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。| 693 694### ParseOptions 695 696解析的选项，可定义处理BigInt的模式与解析结果的返回类型。 697 698**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 699 700**系统能力：** SystemCapability.Utils.Lang 701 702| 名称 | 类型| 必填 | 说明 | 703| ------ | ------ | ---- | --------------- | 704| bigIntMode | [BigIntMode](#bigintmode) | 是 |定义处理BigInt的模式。| 705| parseReturnType | [ParseReturnType](#parsereturntype) | 是 |定义解析结果的返回类型。| 706 707### parse 708 709parse(text: string, reviver?: Transformer, options?: ParseOptions): ISendable | null 710 711用于解析JSON字符串生成ISendable数据或null。 712 713**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 714 715**系统能力：** SystemCapability.Utils.Lang 716 717**参数：** 718 719| 参数名 | 类型 | 必填 | 说明 | 720| ------ | ------ | ---- | --------------- | 721| text | string | 是 | 有效的JSON字符串。| 722| reviver | [Transformer](#transformer) | 否 | 转换函数，传入该参数，可以用来修改解析生成的原始值。默认值是undefined。目前只支持传入undefined。| 723| options | [ParseOptions](#parseoptions) | 否 | 解析的配置，传入该参数，可以用来控制解析生成的结果类型。默认值是undefined。| 724 725**返回值：** 726 727| 类型 | 说明 | 728| -------- | -------- | 729| [ISendable](#isendable) \| null | 返回ISendable数据或null。当入参是null时，返回null。| 730 731**示例：** 732 733```ts 734import { lang } from '@kit.ArkTS'; 735import { collections } from '@kit.ArkTS'; 736 737type ISendable = lang.ISendable; 738let jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}'; 739let obj = ArkTSUtils.ASON.parse(jsonText) as ISendable; 740console.info((obj as object)?.["name"]); 741// 期望输出: 'John' 742console.info((obj as object)?.["age"]); 743// 期望输出: 30 744console.info((obj as object)?.["city"]); 745// 期望输出: 'ChongQing' 746 747let options: ArkTSUtils.ASON.ParseOptions = { 748 bigIntMode: ArkTSUtils.ASON.BigIntMode.PARSE_AS_BIGINT, 749 parseReturnType: ArkTSUtils.ASON.ParseReturnType.OBJECT, 750} 751let numberText = '{"largeNumber":112233445566778899}'; 752let numberObj = ArkTSUtils.ASON.parse(numberText,undefined,options) as ISendable; 753 754console.info((numberObj as object)?.["largeNumber"]); 755// 期望输出: 112233445566778899 756 757let options2: ArkTSUtils.ASON.ParseOptions = { 758 bigIntMode: ArkTSUtils.ASON.BigIntMode.PARSE_AS_BIGINT, 759 parseReturnType: ArkTSUtils.ASON.ParseReturnType.MAP, 760 } 761let mapText = '{"largeNumber":112233445566778899}'; 762let map = ArkTSUtils.ASON.parse(mapText,undefined,options2); 763console.info("map is " + map); 764// 期望输出: map is [object SendableMap] 765console.info("largeNumber is " + (map as collections.Map<string,bigint>).get("largeNumber")); 766// 期望输出: largeNumber is 112233445566778899 767``` 768 769### stringify 770 771stringify(value: ISendable | null | undefined): string 772 773该方法将ISendable数据转换为JSON字符串。 774 775**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 776 777**系统能力：** SystemCapability.Utils.Lang 778 779**参数：** 780 781| 参数名 | 类型 | 必填 | 说明 | 782| -------- | -------- | -------- | -------- | 783| value | [ISendable](#isendable) \| null \| undefined | 是 | ISendable数据。| 784 785**返回值：** 786 787| 类型 | 说明 | 788| -------- | -------- | 789| string | 转换后的JSON字符串。| 790 791**示例：** 792 793```ts 794import { collections } from '@kit.ArkTS'; 795 796let arr = new collections.Array(1, 2, 3); 797let str = ArkTSUtils.ASON.stringify(arr); 798console.info(str); 799// 期望输出: '[1,2,3]' 800``` 801 802### stringify<sup>18+</sup> 803 804stringify(value: Object | null | undefined): string 805 806该方法将ArkTS对象数据转换为JSON字符串，额外支持Map和Set相关类型。 807 808**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 809 810**系统能力：** SystemCapability.Utils.Lang 811 812**参数：** 813 814| 参数名 | 类型 | 必填 | 说明 | 815| -------- | -------- | -------- | -------- | 816| value | Object \| null \| undefined | 是 | ArkTS对象数据。| 817 818**返回值：** 819 820| 类型 | 说明 | 821| -------- | -------- | 822| string | 转换后的JSON字符串。| 823 824**示例：** 825 826```ts 827import { ArkTSUtils, collections, HashMap, HashSet } from '@kit.ArkTS'; 828 829let hashMap = new HashMap<string,string>(); 830hashMap.set("ha","a"); 831hashMap.set("sh","b"); 832hashMap.set("map","c"); 833let str1 = ArkTSUtils.ASON.stringify(hashMap); 834console.info(str1); 835//期望输出：'{"sh":"b","ha":"a","map":"c"}' 836let hashSet = new HashSet<string>(); 837hashSet.add("ha"); 838hashSet.add("sh"); 839hashSet.add("set"); 840let str2 = ArkTSUtils.ASON.stringify(hashSet); 841console.info(str2); 842//期望输出：'["set","sh","ha"]' 843let map = new Map<string,string>(); 844map.set("m","a"); 845map.set("a","b"); 846map.set("p","c"); 847let str3 = ArkTSUtils.ASON.stringify(map); 848console.info(str3); 849//期望输出：'{"m":"a","a":"b","p":"c"}' 850let set = new Set<string>(); 851set.add("s"); 852set.add("e"); 853set.add("t"); 854let str4 = ArkTSUtils.ASON.stringify(set); 855console.info(str4); 856//期望输出：'["s","e","t"]' 857let sendableMap = new collections.Map<string,string>(); 858sendableMap.set("send","a"); 859sendableMap.set("able","b"); 860sendableMap.set("map","c"); 861let str5 = ArkTSUtils.ASON.stringify(sendableMap); 862console.info(str5); 863//期望输出：'{"send":"a","able":"b","map":"c"}' 864let sendableSet = new collections.Set<string>(); 865sendableSet.add("send"); 866sendableSet.add("able"); 867sendableSet.add("set"); 868let str6 = ArkTSUtils.ASON.stringify(sendableSet); 869console.info(str6); 870//期望输出：'["send","able","set"]' 871``` 872 873### isSendable 874 875isSendable(value: Object | null | undefined): boolean 876 877该方法用于判断value是否为Sendable数据类型。 878 879**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 880 881**系统能力：** SystemCapability.Utils.Lang 882 883**参数：** 884 885| 参数名 | 类型 | 必填 | 说明 | 886| -------- | -------- | -------- | -------- | 887| value | Object \| null \| undefined | 是 | 待校验的对象。| 888 889**返回值：** 890 891| 类型 | 说明 | 892| -------- | -------- | 893| boolean | value是否为Sendable数据类型，true表示value是Sendable数据类型，否则为false。| 894 895**示例：** 896 897```ts 898import { ArkTSUtils } from '@kit.ArkTS' 899 900@Sendable 901function sendableFunc() { 902 console.info("sendableFunc") 903} 904 905if (ArkTSUtils.isSendable(sendableFunc)) { 906 console.info("sendableFunc is Sendable"); 907} else { 908 console.info("sendableFunc is not Sendable"); 909} 910// 期望输出: 'SendableFunc is Sendable' 911``` 912 913## SendableLruCache<K, V><sup>18+</sup> 914 915SendableLruCache用于在缓存空间不够的时候，将近期最少使用的数据替换为新数据。此设计基于资源访问的考虑：近期访问的数据，可能在不久的将来会再次访问。于是最少访问的数据就是价值最小的数据，是最应该踢出缓存空间的数据。 SendableLruCache支持Sendable特性，保存Sendable对象，可以跨线程安全访问。 916 917### 属性 918 919**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 920 921**系统能力：** SystemCapability.Utils.Lang 922 923| 名称 | 类型 | 可读 | 可写 | 说明 | 924| ------ | ------ | ---- | ---- | ---------------------- | 925| length | number | 是 | 否 | 当前缓冲区中值的总数。 | 926 927**示例：** 928 929```ts 930let pro = new ArkTSUtils.SendableLruCache<number, number>(); 931pro.put(2, 10); 932pro.put(1, 8); 933let result = pro.length; 934console.info('result = ' + result); 935// 期望输出：result = 2 936``` 937 938### constructor<sup>18+</sup> 939 940constructor(capacity?: number) 941 942默认构造函数用于创建一个新的SendableLruCache实例，默认容量为64。 943 944**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 945 946**系统能力：** SystemCapability.Utils.Lang 947 948**参数：** 949 950| 参数名 | 类型 | 必填 | 说明 | 951| -------- | ------ | ---- | ---------------------------- | 952| capacity | number | 否 | 指示要为缓冲区自定义的容量，不传默认值为64，最大值不能超过2147483647。 | 953 954**示例：** 955 956```ts 957let pro = new ArkTSUtils.SendableLruCache<number, number>(); 958``` 959 960### updateCapacity<sup>18+</sup> 961 962updateCapacity(newCapacity: number): void 963 964将缓冲区容量更新为指定容量。当缓冲区中值的总数大于指定容量时，会执行删除操作，删除最少使用的键值对。 965 966**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 967 968**系统能力：** SystemCapability.Utils.Lang 969 970**参数：** 971 972| 参数名 | 类型 | 必填 | 说明 | 973| ----------- | ------ | ---- | ---------------------------- | 974| newCapacity | number | 是 | 指示要为缓冲区自定义的容量，最大值不能超过2147483647；小于等于0时会抛出异常。| 975 976**错误码：** 977 978以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 979 980| 错误码ID | 错误信息 | 981| -------- | ------------------------------------------| 982| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 983 984**示例：** 985 986```ts 987let pro = new ArkTSUtils.SendableLruCache<number, number>(); 988pro.updateCapacity(100); 989``` 990 991### toString<sup>18+</sup> 992 993toString(): string 994 995返回对象的字符串表示形式。 996 997**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 998 999**系统能力：** SystemCapability.Utils.Lang 1000 1001**返回值：** 1002 1003| 类型 | 说明 | 1004| ------ | -------------------------- | 1005| string | 返回对象的字符串表示形式。 返回字符串格式是：SendableLruCache[ maxSize = (maxSize), hits = (hitCount), misses = (missCount), hitRate = (hitRate) ]。 (maxSize)表示缓存区最大值，(hitCount)表示查询值匹配成功的次数，(missCount)表示查询值匹配失败的次数，(hitRate)表示查询值匹配率。| 1006 1007**示例：** 1008 1009```ts 1010let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1011pro.put(2, 10); 1012pro.get(2); 1013pro.get(3); 1014console.info(pro.toString()); 1015// 预期输出：SendableLruCache[ maxSize = 64, hits = 1, misses = 1, hitRate = 50% ] 1016// maxSize: 缓存区最大值 hits: 查询值匹配成功的次数 misses: 查询值匹配失败的次数 hitRate: 查询值匹配率 1017``` 1018 1019### getCapacity<sup>18+</sup> 1020 1021getCapacity(): number 1022 1023获取当前缓冲区的容量。 1024 1025**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1026 1027**系统能力：** SystemCapability.Utils.Lang 1028 1029**返回值：** 1030 1031| 类型 | 说明 | 1032| ------ | ---------------------- | 1033| number | 返回当前缓冲区的容量。 | 1034 1035**示例：** 1036 1037```ts 1038let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1039let result = pro.getCapacity(); 1040console.info('result = ' + result); 1041// 预期输出：result = 64 1042``` 1043 1044### clear<sup>18+</sup> 1045 1046clear(): void 1047 1048从当前缓冲区清除所有键值对。 1049 1050**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1051 1052**系统能力：** SystemCapability.Utils.Lang 1053 1054**示例：** 1055 1056```ts 1057let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1058pro.put(2, 10); 1059let result = pro.length; 1060pro.clear(); 1061let res = pro.length; 1062console.info('result = ' + result); 1063console.info('res = ' + res); 1064// 预期输出：result = 1 1065// 预期输出：res = 0 1066``` 1067 1068### getCreateCount<sup>18+</sup> 1069 1070getCreateCount(): number 1071 1072获取调用createDefault接口创建对象的次数。 1073 1074**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1075 1076**系统能力：** SystemCapability.Utils.Lang 1077 1078**返回值：** 1079 1080| 类型 | 说明 | 1081| ------ | -------------------| 1082| number | 返回使用createDefault接口创建对象的次数。 | 1083 1084**示例：** 1085 1086```ts 1087@Sendable 1088class ChildLRUCache extends ArkTSUtils.SendableLruCache<number, number> { 1089 constructor() { 1090 super(); 1091 } 1092 createDefault(key: number): number { 1093 return key; 1094 } 1095} 1096 1097let lru = new ChildLRUCache(); 1098lru.put(2, 10); 1099lru.get(3); 1100lru.get(5); 1101let res = lru.getCreateCount(); 1102console.info('res = ' + res); 1103// 预期输出：res = 2 1104// 执行get操作时，如果键值不存在，调用createDefault接口判断返回值是否等于undefined 1105// 如果不等于，则需要把key和返回值作为键值对添加到cache中，并且创建次数加1 1106``` 1107 1108### getMissCount<sup>18+</sup> 1109 1110getMissCount(): number 1111 1112获取查询值不匹配的次数。 1113 1114**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1115 1116**系统能力：** SystemCapability.Utils.Lang 1117 1118**返回值：** 1119 1120| 类型 | 说明 | 1121| ------ | ------------------------ | 1122| number | 返回查询值不匹配的次数。 | 1123 1124**示例：** 1125 1126```ts 1127let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1128pro.put(2, 10); 1129pro.get(2); 1130let result = pro.getMissCount(); 1131console.info('result = ' + result); 1132// 预期输出：result = 0 1133``` 1134 1135### getRemoveCount<sup>18+</sup> 1136 1137getRemoveCount(): number 1138 1139获取缓冲区键值对回收的次数，当缓冲区数超过容量限制后，最少使用的键值对会被回收。 1140 1141**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1142 1143**系统能力：** SystemCapability.Utils.Lang 1144 1145**返回值：** 1146 1147| 类型 | 说明 | 1148| ------ | -------------------------- | 1149| number | 返回缓冲区键值对回收的次数。 | 1150 1151**示例：** 1152 1153```ts 1154let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1155pro.put(2, 10); 1156pro.updateCapacity(2); 1157pro.put(50, 22); 1158let result = pro.getRemoveCount(); 1159console.info('result = ' + result); 1160// 预期输出：result = 0 1161``` 1162 1163### getMatchCount<sup>18+</sup> 1164 1165getMatchCount(): number 1166 1167获取查询值匹配成功的次数。 1168 1169**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1170 1171**系统能力：** SystemCapability.Utils.Lang 1172 1173**返回值：** 1174 1175| 类型 | 说明 | 1176| ------ | -------------------------- | 1177| number | 返回查询值匹配成功的次数。 | 1178 1179**示例：** 1180 1181```ts 1182let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1183pro.put(2, 10); 1184pro.get(2); 1185let result = pro.getMatchCount(); 1186console.info('result = ' + result); 1187// 预期输出：result = 1 1188``` 1189 1190### getPutCount<sup>18+</sup> 1191 1192getPutCount(): number 1193 1194获取将值添加到缓冲区的次数。 1195 1196**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1197 1198**系统能力：** SystemCapability.Utils.Lang 1199 1200**返回值：** 1201 1202| 类型 | 说明 | 1203| ------ | ---------------------------- | 1204| number | 返回将值添加到缓冲区的次数。 | 1205 1206**示例：** 1207 1208```ts 1209let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1210pro.put(2, 10); 1211let result = pro.getPutCount(); 1212console.info('result = ' + result); 1213// 预期输出：result = 1 1214``` 1215 1216### isEmpty<sup>18+</sup> 1217 1218isEmpty(): boolean 1219 1220检查当前缓冲区是否为空。 1221 1222**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1223 1224**系统能力：** SystemCapability.Utils.Lang 1225 1226**返回值：** 1227 1228| 类型 | 说明 | 1229| ------- | ---------------------------------------- | 1230| boolean | 返回true表示当前缓冲区为空不包含任何键值对；返回false表示当前缓冲区不为空。 | 1231 1232**示例：** 1233 1234```ts 1235let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1236pro.put(2, 10); 1237let result = pro.isEmpty(); 1238console.info('result = ' + result); 1239// 预期输出：result = false 1240``` 1241 1242### get<sup>18+</sup> 1243 1244get(key: K): V | undefined 1245 1246返回键对应的值。 1247 1248**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1249 1250**系统能力：** SystemCapability.Utils.Lang 1251 1252**参数：** 1253 1254| 参数名 | 类型 | 必填 | 说明 | 1255| ------ | ---- | ---- | ------------ | 1256| key | K | 是 | 要查询的键。 | 1257 1258**返回值：** 1259 1260| 类型 | 说明 | 1261| ------------------------ | ------------------------------------------------------------ | 1262| V \| undefined | 如果指定的键存在于缓冲区中，则返回与键关联的值；否则调用createDefault接口，如果返回值为undefined，则返回undefined，否则返回createDefault接口结果。 | 1263 1264**示例：** 1265 1266```ts 1267let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1268pro.put(2, 10); 1269let result = pro.get(2); 1270console.info('result = ' + result); 1271// 预期输出：result = 10 1272``` 1273 1274### put<sup>18+</sup> 1275 1276put(key: K,value: V): V 1277 1278将键值对添加到缓冲区中，返回与添加的键关联的值。当缓冲区中值的总数大于容量时，会执行删除操作。 1279 1280**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1281 1282**系统能力：** SystemCapability.Utils.Lang 1283 1284**参数：** 1285 1286| 参数名 | 类型 | 必填 | 说明 | 1287| ------ | ---- | ---- | -------------------------- | 1288| key | K | 是 | 要添加的键。 | 1289| value | V | 是 | 指示与要添加的键关联的值。 | 1290 1291**返回值：** 1292 1293| 类型 | 说明 | 1294| ---- | ------------------------------------------------------------ | 1295| V | 返回与添加的键关联的值。如果键或值为空，则抛出错误ID为401的参数错误异常。 | 1296 1297**示例：** 1298 1299```ts 1300let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1301let result = pro.put(2, 10); 1302console.info('result = ' + result); 1303// 预期输出：result = 10 1304``` 1305 1306### values<sup>18+</sup> 1307 1308values(): V[] 1309 1310获取当前缓冲区中所有值从最近访问到最少访问的顺序列表，最近访问表示有最新操作的键值对。 1311 1312**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1313 1314**系统能力：** SystemCapability.Utils.Lang 1315 1316**返回值：** 1317 1318| 类型 | 说明 | 1319| --------- | ------------------------------------------------------------ | 1320| V [] | 按从最近访问到最少访问的顺序返回当前缓冲区中所有值的列表。 | 1321 1322**示例：** 1323 1324```ts 1325let pro = new ArkTSUtils.SendableLruCache<number|string,number|string>(); 1326pro.put(2, 10); 1327pro.put(2, "anhu"); 1328pro.put("afaf", "grfb"); 1329let result = pro.values(); 1330console.info('result = ' + result); 1331// 预期输出：result = anhu,grfb 1332``` 1333 1334### keys<sup>18+</sup> 1335 1336keys(): K[] 1337 1338获取当前缓冲区中所有键从最近访问到最近最少访问的升序列表。 1339 1340**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1341 1342**系统能力：** SystemCapability.Utils.Lang 1343 1344**返回值：** 1345 1346| 类型 | 说明 | 1347| --------- | ------------------------------------------------------------ | 1348| K [] | 按升序返回当前缓冲区中所有键的列表，从最近访问到最近最少访问。 | 1349 1350**示例：** 1351 1352```ts 1353let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1354pro.put(2, 10); 1355pro.put(3, 1); 1356let result = pro.keys(); 1357console.info('result = ' + result); 1358// 预期输出：result = 2,3 1359``` 1360 1361### remove<sup>18+</sup> 1362 1363remove(key: K): V | undefined 1364 1365从当前缓冲区中删除指定的键及其关联的值，返回键关联的值。如果键不存在时，则返回undefined。 1366 1367**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1368 1369**系统能力：** SystemCapability.Utils.Lang 1370 1371**参数：** 1372 1373| 参数名 | 类型 | 必填 | 说明 | 1374| ------ | ---- | ---- | -------------- | 1375| key | K | 是 | 要删除的键值。 | 1376 1377**返回值：** 1378 1379| 类型 | 说明 | 1380| ------------------------ | ------------------------------------------------------------ | 1381| V \| undefined | 返回一个包含已删除键值对的Optional对象；如果key不存在，则返回undefined，如果key为null，则抛出异常。 | 1382 1383**示例：** 1384 1385```ts 1386let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1387pro.put(2, 10); 1388let result = pro.remove(20); 1389console.info('result = ' + result); 1390// 预期输出：result = undefined 1391``` 1392 1393### contains<sup>18+</sup> 1394 1395contains(key: K): boolean 1396 1397检查当前缓冲区是否包含指定的键，假如存在，返回true，否则返回false。 1398 1399**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1400 1401**系统能力：** SystemCapability.Utils.Lang 1402 1403**参数：** 1404 1405| 参数名 | 类型 | 必填 | 说明 | 1406| ------ | ------ | ---- | ---------------- | 1407| key | K | 是 | 表示要检查的键。 | 1408 1409**返回值：** 1410 1411| 类型 | 说明 | 1412| ------- | ------------------------------------------ | 1413| boolean | 如果缓冲区包含指定的键，则返回true，否则返回false。 | 1414 1415**示例：** 1416 1417```ts 1418let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1419pro.put(2, 10); 1420let result = pro.contains(2); 1421console.info('result = ' + result); 1422// 预期输出：result = true 1423``` 1424 1425### entries<sup>18+</sup> 1426 1427entries(): IterableIterator<[K,V]> 1428 1429允许迭代包含在这个对象中的所有键值对。 1430 1431**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1432 1433**系统能力：** SystemCapability.Utils.Lang 1434 1435**返回值：** 1436 1437| 类型 | 说明 | 1438| ----------- | -------------------- | 1439| IterableIterator<[K, V]> | 返回一个可迭代数组。 | 1440 1441**示例：** 1442 1443```ts 1444let pro = new ArkTSUtils.SendableLruCache<number, number>(); 1445pro.put(2, 10); 1446pro.put(3, 15); 1447let pair:Iterable<Object[]> = pro.entries(); 1448let arrayValue = Array.from(pair); 1449for (let value of arrayValue) { 1450 console.info(value[0]+ ', '+ value[1]); 1451 // 预期输出： 1452 // 2, 10 1453 // 3, 15 1454} 1455```