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