1# @ohos.data.sendablePreferences (共享用户首选项) 2 3 4共享用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。 5 6数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括number、string、boolean、bigint以及可序列化的object。 7 8共享用户首选项默认加密等级为EL2，持久化文件存储在对应的EL2路径下。设备开机后，若无锁屏密码，可直接访问；若有锁屏密码，此路径下的文件需要至少一次解锁对应用户的锁屏界面后（密码、指纹、人脸等方式解锁皆可）才能够访问。需避免在开机未解锁的情况下访问首选项。修改加密等级的方法请参见[获取和修改加密分区](../../../application-dev/application-models/application-context-stage.md#获取和修改加密分区)。 9 10共享用户首选项可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，性能优于普通的[用户首选项](js-apis-data-preferences.md)，可参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。 11 12> **说明：** 13> 14> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> 共享用户首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。 17 18## 导入模块 19 20```ts 21import { sendablePreferences } from '@kit.ArkData'; 22``` 23 24## 常量 25 26**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 27 28**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 29 30| 名称 | 参数类型 | 可读 | 可写 | 说明 | 31| ---------------- | -------- | ---- | ---- | --------------------------------------- | 32| MAX_KEY_LENGTH | number | 是 | 否 | Key的最大长度限制为1024个字节。 | 33| MAX_VALUE_LENGTH | number | 是 | 否 | Value的最大长度限制为16 * 1024 * 1024个字节。 | 34 35## sendablePreferences.getPreferences 36 37getPreferences(context: Context, options: Options): Promise<Preferences> 38 39获取Preferences实例，使用Promise异步回调。 40 41**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 42 43**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 44 45**参数：** 46 47| 参数名 | 类型 | 必填 | 说明 | 48| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 49| context | [Context](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 应用上下文。 | 50| options | [Options](#options) | 是 | 与Preferences实例相关的配置选项。 | 51 52**返回值：** 53 54| 类型 | 说明 | 55| --------------------------------------- | ---------------------------------- | 56| Promise<[Preferences](#preferences)> | Promise对象，返回Preferences实例。<br>该实例继承[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。 | 57 58**错误码：** 59 60以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 61 62| 错误码ID | 错误信息 | 63| -------- | ------------------------------ | 64| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 65| 801 | Capability not supported. | 66| 15500000 | Inner error. | 67| 15501001 | Only supported in stage mode. | 68| 15501002 | The data group id is not valid. | 69 70**示例：** 71 72```ts 73import { UIAbility } from '@kit.AbilityKit'; 74import { BusinessError } from '@kit.BasicServicesKit'; 75import { window } from '@kit.ArkUI'; 76 77let preferences: sendablePreferences.Preferences; 78 79class EntryAbility extends UIAbility { 80 onWindowStageCreate(windowStage: window.WindowStage) { 81 let options: sendablePreferences.Options = { name: 'myStore' }; 82 let promise = sendablePreferences.getPreferences(this.context, options); 83 promise.then((object: sendablePreferences.Preferences) => { 84 preferences = object; 85 console.info("Succeeded in getting preferences."); 86 }).catch((err: BusinessError) => { 87 console.error(`Failed to get preferences. code: ${err.code}, message: ${err.message}`); 88 }) 89 } 90} 91``` 92 93## sendablePreferences.getPreferencesSync 94 95getPreferencesSync(context: Context, options: Options): Preferences 96 97获取Preferences实例，此为同步接口。 98 99**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 100 101**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| ------- | --------------------- | ---- | ------------------------------------------------------------ | 107| context | [Context](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 应用上下文。 | 108| options | [Options](#options) | 是 | 与Preferences实例相关的配置选项。 | 109 110**返回值：** 111 112| 类型 | 说明 | 113| --------------------------- | --------------------- | 114| [Preferences](#preferences) | 返回Preferences实例。<br>该实例继承[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。 | 115 116**错误码：** 117 118以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 119 120| 错误码ID | 错误信息 | 121| -------- | ------------------------------ | 122| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 123| 801 | Capability not supported. | 124| 15500000 | Inner error. | 125| 15501001 | Only supported in stage mode. | 126| 15501002 | The data group id is not valid. | 127 128**示例：** 129 130```ts 131import { UIAbility } from '@kit.AbilityKit'; 132import { window } from '@kit.ArkUI'; 133 134let preferences: sendablePreferences.Preferences; 135 136class EntryAbility extends UIAbility { 137 onWindowStageCreate(windowStage: window.WindowStage) { 138 let options: sendablePreferences.Options = { name: 'myStore' }; 139 preferences = sendablePreferences.getPreferencesSync(this.context, options); 140 } 141} 142``` 143 144## sendablePreferences.deletePreferences 145 146deletePreferences(context: Context, options: Options): Promise<void> 147 148从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用Promise异步回调。 149 150调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题。 151 152**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 153 154**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| ------- | ---------------- | ---- | ----------------------------------------------------------------------------| 160| context | [Context](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 应用上下文。 | 161| options | [Options](#options) | 是 | 与Preferences实例相关的配置选项。 | 162 163**返回值：** 164 165| 类型 | 说明 | 166| ------------------- | ------------------------- | 167| Promise<void> | 无返回结果的Promise对象。 | 168 169**错误码：** 170 171以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 172 173| 错误码ID | 错误信息 | 174| -------- | ------------------------------ | 175| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 176| 801 | Capability not supported. | 177| 15500000 | Inner error. | 178| 15500010 | Failed to delete preferences file. | 179| 15501001 | Only supported in stage mode. | 180| 15501002 | The data group id is not valid. | 181 182**示例：** 183 184```ts 185import { UIAbility } from '@kit.AbilityKit'; 186import { BusinessError } from '@kit.BasicServicesKit'; 187import { window } from '@kit.ArkUI'; 188 189class EntryAbility extends UIAbility { 190 onWindowStageCreate(windowStage: window.WindowStage) { 191 let options: sendablePreferences.Options = { name: 'myStore' }; 192 let promise = sendablePreferences.deletePreferences(this.context, options); 193 promise.then(() => { 194 console.info("Succeeded in deleting preferences."); 195 }).catch((err: BusinessError) => { 196 console.error(`Failed to delete preferences. code: ${err.code}, message: ${err.message}`); 197 }) 198 } 199} 200``` 201 202## sendablePreferences.removePreferencesFromCache 203 204removePreferencesFromCache(context: Context, options: Options): Promise<void> 205 206从缓存中移出指定的Preferences实例，使用Promise异步回调。 207 208应用首次调用[getPreferences](#sendablepreferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#sendablepreferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 209 210**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 211 212**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 213 214**参数：** 215 216| 参数名 | 类型 | 必填 | 说明 | 217| ------- | ---------------- | ---- | ----------------------------------------------------------------------------------------------------------------------- | 218| context | [Context](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 应用上下文。 | 219| options | [Options](#options) | 是 | 与Preferences实例相关的配置选项。 | 220 221**返回值：** 222 223| 类型 | 说明 | 224| ------------------- | ------------------------- | 225| Promise<void> | 无返回结果的Promise对象。 | 226 227**错误码：** 228 229以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 230 231| 错误码ID | 错误信息 | 232| -------- | ------------------------------ | 233| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 234| 801 | Capability not supported. | 235| 15500000 | Inner error. | 236| 15501001 | Only supported in stage mode. | 237| 15501002 | The data group id is not valid. | 238 239**示例：** 240 241```ts 242import { UIAbility } from '@kit.AbilityKit'; 243import { BusinessError } from '@kit.BasicServicesKit'; 244import { window } from '@kit.ArkUI'; 245 246class EntryAbility extends UIAbility { 247 onWindowStageCreate(windowStage: window.WindowStage) { 248 let options: sendablePreferences.Options = { name: 'myStore' }; 249 let promise = sendablePreferences.removePreferencesFromCache(this.context, options); 250 promise.then(() => { 251 console.info("Succeeded in removing preferences."); 252 }).catch((err: BusinessError) => { 253 console.error(`Failed to remove preferences. code: ${err.code}, message: ${err.message}`); 254 }) 255 } 256} 257``` 258 259## sendablePreferences.removePreferencesFromCacheSync 260 261removePreferencesFromCacheSync(context: Context, options: Options):void 262 263从缓存中移出指定的Preferences实例，此为同步接口。 264 265应用首次调用[getPreferences](#sendablepreferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#sendablepreferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 266 267**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 268 269**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 270 271**参数：** 272 273| 参数名 | 类型 | 必填 | 说明 | 274| ------- | --------------------- | ---- | ------------------------------------------------------------ | 275| context | [Context](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 应用上下文。 | 276| options | [Options](#options) | 是 | 与Preferences实例相关的配置选项。 | 277 278**错误码：** 279 280以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 281 282| 错误码ID | 错误信息 | 283| -------- | ------------------------------ | 284| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 285| 801 | Capability not supported. | 286| 15500000 | Inner error. | 287| 15501001 | Only supported in stage mode. | 288| 15501002 | The data group id is not valid. | 289 290**示例：** 291 292```ts 293import { UIAbility } from '@kit.AbilityKit'; 294import { window } from '@kit.ArkUI'; 295 296class EntryAbility extends UIAbility { 297 onWindowStageCreate(windowStage: window.WindowStage) { 298 let options: sendablePreferences.Options = { name: 'myStore' }; 299 sendablePreferences.removePreferencesFromCacheSync(this.context, options); 300 } 301} 302``` 303 304## Options 305 306Preferences实例配置选项。 307 308**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 309 310**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 311 312| 名称 | 类型 | 必填 | 说明 | 313| ----------- | ------ | ---- | ------------------------------------------------------------ | 314| name | string | 是 | Preferences实例的名称。 | 315| dataGroupId | string\|null | 否 | 应用组ID，需要向应用市场获取，暂不支持。<br/>为可选参数。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时，默认在本应用沙箱目录下创建Preferences实例。<br/> **模型约束：** 此属性仅在Stage模型下可用。| 316 317 318## Preferences 319 320Preferences继承自[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，提供获取和修改存储数据的接口。 321 322下列接口都需先使用[sendablePreferences.getPreferences](#sendablepreferencesgetpreferences)获取到Preferences实例，再通过此实例调用对应接口。 323 324### get 325 326get(key: string, defValue: lang.ISendable): Promise<lang.ISendable> 327 328从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用Promise异步回调。 329 330**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 331 332**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 333 334 **参数：** 335 336| 参数名 | 类型 | 必填 | 说明 | 337| -------- | ----------------------- | ---- |--------| 338| key | string | 是 | 要获取的存储Key名称，不能为空。 | 339| defValue | [lang.ISendable](../../arkts-utils/sendable-overview.md#isendable) | 是 | 默认返回值。 | 340 341**返回值：** 342 343| 类型 | 说明 | 344| ----------------------------------- | ----------------------------- | 345| Promise<[lang.ISendable](../../arkts-utils/sendable-overview.md#isendable)> | Promise对象，返回键对应的值。 <br>该实例继承[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。| 346 347**错误码：** 348 349以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 350 351| 错误码ID | 错误信息 | 352| -------- | ------------------------------ | 353| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 354| 15500000 | Inner error. | 355 356**示例：** 357 358```ts 359import { BusinessError } from '@kit.BasicServicesKit'; 360import { lang } from '@kit.ArkTS'; 361 362let promise = preferences.get('startup', 'default'); 363promise.then((data: lang.ISendable) => { 364 let dataStr = data as string; 365 console.info(`Succeeded in getting value of 'startup'. Data: ${dataStr}`); 366}).catch((err: BusinessError) => { 367 console.error(`Failed to get value of 'startup'. code: ${err.code}, message: ${err.message}`); 368}) 369``` 370 371### getSync 372 373getSync(key: string, defValue: lang.ISendable): lang.ISendable 374 375从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，此为同步接口。 376 377**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 378 379**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 380 381**参数：** 382 383| 参数名 | 类型 | 必填 | 说明 | 384| -------- | ----------------------- | ---- |---------------------| 385| key | string | 是 | 要获取的存储Key名称，不能为空。 | 386| defValue | [lang.ISendable](../../arkts-utils/sendable-overview.md#isendable) | 是 | 默认返回值。 | 387 388**返回值：** 389 390| 类型 | 说明 | 391| ----------------------------------- | ----------------------------- | 392| [lang.ISendable](../../arkts-utils/sendable-overview.md#isendable) | 返回键对应的值。 <br>该实例继承[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。| 393 394**错误码：** 395 396以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 397 398| 错误码ID | 错误信息 | 399| -------- | ------------------------------ | 400| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 401| 15500000 | Inner error. | 402 403**示例：** 404 405```ts 406import { lang } from '@kit.ArkTS'; 407let value: lang.ISendable = preferences.getSync('startup', 'default'); 408``` 409 410### getAll 411 412getAll(): Promise<lang.ISendable> 413 414从缓存的Preferences实例中获取所有键值数据。 415 416**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 417 418**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 419 420**返回值：** 421 422| 类型 | 说明 | 423| --------------------- | ------------------------------------------- | 424| Promise<[lang.ISendable](../../arkts-utils/sendable-overview.md#isendable)> | Promise对象，返回含有所有键值数据。 <br>该对象继承[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。 | 425 426**错误码：** 427 428以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 429 430| 错误码ID | 错误信息 | 431| -------- | ------------------------------ | 432| 15500000 | Inner error. | 433 434**示例：** 435 436```ts 437import { BusinessError } from '@kit.BasicServicesKit'; 438import { lang } from '@kit.ArkTS'; 439 440let promise = preferences.getAll(); 441promise.then((keyValues: lang.ISendable) => { 442 for (let value of Object.keys(keyValues)) { 443 console.info("getAll " + JSON.stringify(value)); 444 } 445}).catch((err: BusinessError) => { 446 console.error(`Failed to get all key-values. code: ${err.code}, message: ${err.message}`); 447}) 448``` 449 450### getAllSync 451 452getAllSync(): lang.ISendable 453 454从缓存的Preferences实例中获取所有键值数据，此为同步接口。 455 456**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 457 458**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 459 460**返回值：** 461 462| 类型 | 说明 | 463| --------------------- | ------------------------------------------- | 464| [lang.ISendable](../../arkts-utils/sendable-overview.md#isendable) | 返回含有所有键值数据。<br>该对象继承[ISendable](../../arkts-utils/sendable-overview.md#isendable)，可以在ArkTS并发实例间（包括主线程、TaskPool&Worker工作线程）传递，传递的行为是引用传递，参考[Sendable使用场景](../../arkts-utils/sendable-guide.md)。 | 465 466**错误码：** 467 468以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 469 470| 错误码ID | 错误信息 | 471| -------- | ------------------------------ | 472| 15500000 | Inner error. | 473 474**示例：** 475 476```ts 477import { lang } from '@kit.ArkTS'; 478 479let keyValues: lang.ISendable = preferences.getAllSync(); 480for (let value of Object.keys(keyValues)) { 481 console.info("getAll " + JSON.stringify(value)); 482} 483``` 484 485### put 486 487put(key: string, value: lang.ISendable): Promise<void> 488 489将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 490 491 > **说明：** 492 > 493 > 当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 494 495**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 496 497**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 498 499**参数：** 500 501| 参数名 | 类型 | 必填 | 说明 | 502| ------ | ----------------------- | ---- |--------------------------| 503| key | string | 是 | 要修改的存储的Key，不能为空。 | 504| value | [lang.ISendable](../../arkts-utils/sendable-overview.md#isendable) | 是 | 存储的新值。 | 505 506**返回值：** 507 508| 类型 | 说明 | 509| ------------------- | ------------------------- | 510| Promise<void> | 无返回结果的Promise对象。 | 511 512**错误码：** 513 514以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 515 516| 错误码ID | 错误信息 | 517| -------- | ------------------------------ | 518| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 519| 15500000 | Inner error. | 520 521**示例：** 522 523```ts 524import { BusinessError } from '@kit.BasicServicesKit'; 525 526let promise = preferences.put('startup', 'auto'); 527promise.then(() => { 528 console.info("Succeeded in putting value of 'startup'."); 529}).catch((err: BusinessError) => { 530 console.error(`Failed to put value of 'startup'. code: ${err.code}, message: ${err.message}`); 531}) 532``` 533 534### putSync 535 536putSync(key: string, value: lang.ISendable): void 537 538将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 539 540 > **说明：** 541 > 542 > 当对应的键已经存在时，putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 543 544**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 545 546**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 547 548**参数：** 549 550| 参数名 | 类型 | 必填 | 说明 | 551| ------ | ----------------------- | ---- | ------------------------ | 552| key | string | 是 | 要修改的存储的Key，不能为空。 | 553| value | [lang.ISendable](../../arkts-utils/sendable-overview.md#isendable) | 是 | 存储的新值。 | 554 555**错误码：** 556 557以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 558 559| 错误码ID | 错误信息 | 560| -------- | ------------------------------ | 561| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 562| 15500000 | Inner error. | 563 564**示例：** 565 566```ts 567preferences.putSync('startup', 'auto'); 568``` 569 570### has 571 572has(key: string): Promise<boolean> 573 574检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用Promise异步回调。 575 576**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 577 578**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 579 580**参数：** 581 582| 参数名 | 类型 | 必填 | 说明 | 583| ------ | ------ | ---- | ------------------------------- | 584| key | string | 是 | 要检查的存储key名称，不能为空。 | 585 586**返回值：** 587 588| 类型 | 说明 | 589| ---------------------- | ------------------------------------------------------------ | 590| Promise<boolean> | Promise对象。返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 591 592**错误码：** 593 594以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 595 596| 错误码ID | 错误信息 | 597| -------- | ------------------------------ | 598| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 599| 15500000 | Inner error. | 600 601**示例：** 602 603```ts 604import { BusinessError } from '@kit.BasicServicesKit'; 605 606let promise = preferences.has('startup'); 607promise.then((val: boolean) => { 608 if (val) { 609 console.info("The key 'startup' is contained."); 610 } else { 611 console.error("The key 'startup' dose not contain."); 612 } 613}).catch((err: BusinessError) => { 614 console.error(`Failed to check the key 'startup'. code: ${err.code}, message: ${err.message}`); 615}) 616``` 617 618### hasSync 619 620hasSync(key: string): boolean 621 622检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，此为同步接口。 623 624**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 625 626**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 627 628**参数：** 629 630| 参数名 | 类型 | 必填 | 说明 | 631| ------ | ------ | ---- | ------------------------------- | 632| key | string | 是 | 要检查的存储key名称，不能为空。 | 633 634**返回值：** 635 636| 类型 | 说明 | 637| ---------------------- | ------------------------------------------------------------ | 638| boolean | 返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 639 640**错误码：** 641 642以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 643 644| 错误码ID | 错误信息 | 645| -------- | ------------------------------ | 646| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 647| 15500000 | Inner error. | 648 649**示例：** 650 651```ts 652let isExist: boolean = preferences.hasSync('startup'); 653if (isExist) { 654 console.info("The key 'startup' is contained."); 655} else { 656 console.error("The key 'startup' dose not contain."); 657} 658``` 659 660### delete 661 662delete(key: string): Promise<void> 663 664从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 665 666**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 667 668**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 669 670**参数：** 671 672| 参数名 | 类型 | 必填 | 说明 | 673| ------ | ------ | ---- | ------------------------------- | 674| key | string | 是 | 要删除的存储key名称，不能为空。 | 675 676**返回值：** 677 678| 类型 | 说明 | 679| ------------------- | ------------------------- | 680| Promise<void> | 无返回结果的Promise对象。 | 681 682**错误码：** 683 684以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 685 686| 错误码ID | 错误信息 | 687| -------- | ------------------------------ | 688| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 689| 15500000 | Inner error. | 690 691**示例：** 692 693```ts 694import { BusinessError } from '@kit.BasicServicesKit'; 695 696let promise = preferences.delete('startup'); 697promise.then(() => { 698 console.info("Succeeded in deleting the key 'startup'."); 699}).catch((err: BusinessError) => { 700 console.error(`Failed to delete the key 'startup'. code: ${err.code}, message: ${err.message}`); 701}) 702``` 703 704### deleteSync 705 706deleteSync(key: string): void 707 708从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 709 710**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 711 712**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 713 714**参数：** 715 716| 参数名 | 类型 | 必填 | 说明 | 717| ------ | ------ | ---- | ------------------------------- | 718| key | string | 是 | 要删除的存储key名称，不能为空。 | 719 720**错误码：** 721 722以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 723 724| 错误码ID | 错误信息 | 725| -------- | ------------------------------ | 726| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 727| 15500000 | Inner error. | 728 729**示例：** 730 731```ts 732preferences.deleteSync('startup'); 733``` 734 735### flush 736 737flush(): Promise<void> 738 739将缓存的Preferences实例中的数据异步存储到共享用户首选项的持久化文件中，使用Promise异步回调。 740 741**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 742 743**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 744 745**返回值：** 746 747| 类型 | 说明 | 748| ------------------- | ------------------------- | 749| Promise<void> | 无返回结果的Promise对象。 | 750 751**错误码：** 752 753以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 754 755| 错误码ID | 错误信息 | 756| -------- | ------------------------------ | 757| 15500000 | Inner error. | 758 759**示例：** 760 761```ts 762import { BusinessError } from '@kit.BasicServicesKit'; 763 764let promise = preferences.flush(); 765promise.then(() => { 766 console.info("Succeeded in flushing."); 767}).catch((err: BusinessError) => { 768 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 769}) 770``` 771 772### clear 773 774clear(): Promise<void> 775 776清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 777 778**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 779 780**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 781 782**返回值：** 783 784| 类型 | 说明 | 785| ------------------- | ------------------------- | 786| Promise<void> | 无返回结果的Promise对象。 | 787 788**错误码：** 789 790以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 791 792| 错误码ID | 错误信息 | 793| -------- | ------------------------------ | 794| 15500000 | Inner error. | 795 796**示例：** 797 798```ts 799import { BusinessError } from '@kit.BasicServicesKit'; 800 801let promise = preferences.clear(); 802promise.then(() => { 803 console.info("Succeeded in clearing."); 804}).catch((err: BusinessError) => { 805 console.error(`Failed to clear. code: ${err.code}, message: ${err.message}`); 806}) 807``` 808 809### clearSync 810 811clearSync(): void 812 813清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 814 815**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 816 817**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 818 819**错误码：** 820 821以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 822 823| 错误码ID | 错误信息 | 824| -------- | ------------------------------ | 825| 15500000 | Inner error. | 826 827**示例：** 828 829```ts 830preferences.clearSync(); 831``` 832 833### on('change') 834 835on(type: 'change', callback: Callback<string>): void 836 837订阅数据变更，订阅的Key的值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 838 839**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 840 841**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 842 843**参数：** 844 845| 参数名 | 类型 | 必填 | 说明 | 846| -------- | -------- | ---- | ---------------------------------------- | 847| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 848| callback | Callback<string> | 是 | 回调函数。返回发生变更的Key。 | 849 850**错误码：** 851 852以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 853 854| 错误码ID | 错误信息 | 855| -------- | ------------------------------ | 856| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 857| 15500000 | Inner error. | 858 859**示例：** 860 861```ts 862import { BusinessError } from '@kit.BasicServicesKit'; 863 864let observer = (key: string) => { 865 console.info("The key " + key + " changed."); 866} 867preferences.on('change', observer); 868preferences.putSync('startup', 'manual'); 869preferences.flush().then(() => { 870 console.info("Succeeded in flushing."); 871}).catch((err: BusinessError) => { 872 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 873}) 874``` 875 876### on('multiProcessChange') 877 878on(type: 'multiProcessChange', callback: Callback<string>): void 879 880订阅进程间数据变更，多个进程持有同一个首选项文件时，订阅的Key的值在任意一个进程发生变更后，执行[flush](#flush)方法后，触发callback回调。 881 882**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 883 884**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 885 886**参数：** 887 888| 参数名 | 类型 | 必填 | 说明 | 889| -------- | -------- | ---- | ------------------------------------------------------------ | 890| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 891| callback | Callback<string> | 是 | 回调函数。返回发生变更的Key。 | 892 893**错误码：** 894 895以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 896 897| 错误码ID | 错误信息 | 898| -------- | -------------------------------------- | 899| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 900| 15500000 | Inner error. | 901| 15500019 | Failed to obtain subscription service. | 902 903**示例：** 904 905```ts 906import { BusinessError } from '@kit.BasicServicesKit'; 907 908let observer = (key: string) => { 909 console.info("The key " + key + " changed."); 910} 911preferences.on('multiProcessChange', observer); 912preferences.putSync('startup', 'manual'); 913preferences.flush().then(() => { 914 console.info("Succeeded in flushing."); 915}).catch((err: BusinessError) => { 916 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 917}) 918``` 919 920### on('dataChange') 921 922on(type: 'dataChange', keys: Array<string>, callback: Callback<lang.ISendable>): void 923 924精确订阅数据变更，只有被订阅的key值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 925 926**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 927 928**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 929 930**参数：** 931 932| 参数名 | 类型 | 必填 | 说明 | 933| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 934| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 935| keys | Array<string> | 是 | 需要订阅的key集合。 | 936| callback | callback: Callback<[lang.ISendable](../../arkts-utils/sendable-overview.md#isendable)> | 是 | 回调函数。回调支持返回多个键值对，其中键为发生变更的订阅key，值为变更后的数据：支持number、string、boolean、bigint以及可序列化的object。 | 937 938**错误码：** 939 940以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 941 942| 错误码ID | 错误信息 | 943| -------- | ------------------------------ | 944| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 945| 15500000 | Inner error. | 946 947**示例：** 948 949```ts 950import { BusinessError } from '@kit.BasicServicesKit'; 951import { lang } from '@kit.ArkTS'; 952 953let observer = (data: lang.ISendable) => { 954 console.info(`observer : ${data}`) 955} 956let keys = ['name', 'age']; 957preferences.on('dataChange', keys, observer); 958preferences.putSync('name', 'xiaohong'); 959preferences.putSync('weight', 125); 960preferences.flush().then(() => { 961 console.info("Succeeded in flushing."); 962}).catch((err: BusinessError) => { 963 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 964}); 965``` 966 967### off('change') 968 969off(type: 'change', callback?: Callback<string>): void 970 971取消订阅数据变更。 972 973**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 974 975**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 976 977**参数：** 978 979| 参数名 | 类型 | 必填 | 说明 | 980| -------- | -------- | ---- | ------------------------------------------------------------ | 981| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 982| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 983 984**错误码：** 985 986以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 987 988| 错误码ID | 错误信息 | 989| -------- | ------------------------------ | 990| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 991| 15500000 | Inner error. | 992 993**示例：** 994 995```ts 996import { BusinessError } from '@kit.BasicServicesKit'; 997 998let observer = (key: string) => { 999 console.info("The key " + key + " changed."); 1000} 1001preferences.on('change', observer); 1002preferences.putSync('startup', 'auto'); 1003preferences.flush().then(() => { 1004 console.info("Succeeded in flushing."); 1005 preferences.off('change', observer); 1006}).catch((err: BusinessError) => { 1007 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1008}); 1009``` 1010 1011### off('multiProcessChange') 1012 1013off(type: 'multiProcessChange', callback?: Callback<string>): void 1014 1015取消订阅进程间数据变更。 1016 1017**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1018 1019**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1020 1021**参数：** 1022 1023| 参数名 | 类型 | 必填 | 说明 | 1024| -------- | -------- | ---- | ------------------------------------------------------------ | 1025| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 1026| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 1027 1028**错误码：** 1029 1030以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1031 1032| 错误码ID | 错误信息 | 1033| -------- | ------------------------------ | 1034| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1035| 15500000 | Inner error. | 1036 1037**示例：** 1038 1039```ts 1040import { BusinessError } from '@kit.BasicServicesKit'; 1041 1042let observer = (key: string) => { 1043 console.info("The key " + key + " changed."); 1044} 1045preferences.on('multiProcessChange', observer); 1046preferences.putSync('startup', 'auto'); 1047preferences.flush().then(() => { 1048 console.info("Succeeded in flushing."); 1049 preferences.off('multiProcessChange', observer); 1050}).catch((err: BusinessError) => { 1051 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1052}); 1053``` 1054### off('dataChange') 1055 1056off(type: 'dataChange', keys: Array<string>, callback?: Callback<lang.ISendable>): void 1057 1058取消精确订阅数据变更。 1059 1060**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1061 1062**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1063 1064**参数：** 1065 1066| 参数名 | 类型 | 必填 | 说明 | 1067| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1068| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 1069| keys | Array<string> | 是 | 需要取消订阅的key集合，当keys为空数组时，表示取消订阅全部key；当keys为非空数组时，表示只取消订阅key集合中的key。 | 1070| callback | Callback<[lang.ISendable](../../arkts-utils/sendable-overview.md#isendable)> | 否 | 需要取消的回调函数，若callback不填写，表示所有的callback都需要处理；若callback填写，表示只处理该callback。 | 1071 1072**错误码：** 1073 1074以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1075 1076| 错误码ID | 错误信息 | 1077| -------- | ------------------------------ | 1078| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1079| 15500000 | Inner error. | 1080 1081**示例：** 1082 1083```ts 1084import { BusinessError } from '@kit.BasicServicesKit'; 1085import { lang } from '@kit.ArkTS'; 1086 1087let observer = (data: lang.ISendable) => { 1088 console.info(`observer : ${data}`) 1089} 1090let keys = ['name', 'age']; 1091preferences.on('dataChange', keys, observer); 1092preferences.putSync('name', 'xiaohong'); 1093preferences.putSync('weight', 125); 1094preferences.flush().then(() => { 1095 console.info("Succeeded in flushing."); 1096 preferences.off('dataChange', keys, observer); 1097}).catch((err: BusinessError) => { 1098 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1099}); 1100``` 1101