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的最大长度限制为16MB。 | 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/arkts-sendable.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 | The operations is supported in stage mode only. | 68| 15501002 | Invalid dataGroupId. | 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/arkts-sendable.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 | The operations is supported in stage mode only. | 126| 15501002 | Invalid dataGroupId. | 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 the user preferences persistence file. | 179| 15501001 | The operations is supported in stage mode only. | 180| 15501002 | Invalid dataGroupId. | 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 | The operations is supported in stage mode only. | 237| 15501002 | Invalid dataGroupId. | 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 | The operations is supported in stage mode only. | 288| 15501002 | Invalid dataGroupId. | 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，<!--RP1-->暂不支持指定dataGroupId在对应共享沙箱路径下创建Preferences实例。<!--RP1End--><br/>为可选参数。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时，默认在本应用沙箱目录下创建Preferences实例。<br/> **模型约束：** 此属性仅在Stage模型下可用。| 316 317 318## Preferences 319 320Preferences继承自[ISendable](../../arkts-utils/arkts-sendable.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/arkts-sendable.md#isendable) | 是 | 默认返回值。 | 340 341**返回值：** 342 343| 类型 | 说明 | 344| ----------------------------------- | ----------------------------- | 345| Promise<[lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable)> | Promise对象，返回键对应的值。 <br>该实例继承[ISendable](../../arkts-utils/arkts-sendable.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/arkts-sendable.md#isendable) | 是 | 默认返回值。 | 387 388**返回值：** 389 390| 类型 | 说明 | 391| ----------------------------------- | ----------------------------- | 392| [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable) | 返回键对应的值。 <br>该实例继承[ISendable](../../arkts-utils/arkts-sendable.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/arkts-sendable.md#isendable)> | Promise对象，返回含有所有键值数据。 <br>该对象继承[ISendable](../../arkts-utils/arkts-sendable.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/arkts-sendable.md#isendable) | 返回含有所有键值数据。<br>该对象继承[ISendable](../../arkts-utils/arkts-sendable.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 > 当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造成持久化文件出现格式错误造成文件损坏。 494 > 495 > 当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 496 497**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 498 499**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 500 501**参数：** 502 503| 参数名 | 类型 | 必填 | 说明 | 504| ------ | ----------------------- | ---- |--------------------------| 505| key | string | 是 | 要修改的存储的Key，不能为空。 | 506| value | [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable) | 是 | 存储的新值。 | 507 508**返回值：** 509 510| 类型 | 说明 | 511| ------------------- | ------------------------- | 512| Promise<void> | 无返回结果的Promise对象。 | 513 514**错误码：** 515 516以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 517 518| 错误码ID | 错误信息 | 519| -------- | ------------------------------ | 520| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 521| 15500000 | Inner error. | 522 523**示例：** 524 525```ts 526import { BusinessError } from '@kit.BasicServicesKit'; 527 528let promise = preferences.put('startup', 'auto'); 529promise.then(() => { 530 console.info("Succeeded in putting value of 'startup'."); 531}).catch((err: BusinessError) => { 532 console.error(`Failed to put value of 'startup'. code: ${err.code}, message: ${err.message}`); 533}) 534``` 535 536### putSync 537 538putSync(key: string, value: lang.ISendable): void 539 540将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 541 542 > **说明：** 543 > 544 > 当value中包含非UTF-8格式的字符串时，请使用Uint8Array类型存储，否则会造成持久化文件出现格式错误造成文件损坏。 545 > 546 > 当对应的键已经存在时，putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 547 548**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 549 550**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 551 552**参数：** 553 554| 参数名 | 类型 | 必填 | 说明 | 555| ------ | ----------------------- | ---- | ------------------------ | 556| key | string | 是 | 要修改的存储的Key，不能为空。 | 557| value | [lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable) | 是 | 存储的新值。 | 558 559**错误码：** 560 561以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 562 563| 错误码ID | 错误信息 | 564| -------- | ------------------------------ | 565| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 566| 15500000 | Inner error. | 567 568**示例：** 569 570```ts 571preferences.putSync('startup', 'auto'); 572``` 573 574### has 575 576has(key: string): Promise<boolean> 577 578检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用Promise异步回调。 579 580**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 581 582**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| ------ | ------ | ---- | ------------------------------- | 588| key | string | 是 | 要检查的存储key名称，不能为空。 | 589 590**返回值：** 591 592| 类型 | 说明 | 593| ---------------------- | ------------------------------------------------------------ | 594| Promise<boolean> | Promise对象。返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 595 596**错误码：** 597 598以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 599 600| 错误码ID | 错误信息 | 601| -------- | ------------------------------ | 602| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 603| 15500000 | Inner error. | 604 605**示例：** 606 607```ts 608import { BusinessError } from '@kit.BasicServicesKit'; 609 610let promise = preferences.has('startup'); 611promise.then((val: boolean) => { 612 if (val) { 613 console.info("The key 'startup' is contained."); 614 } else { 615 console.error("The key 'startup' dose not contain."); 616 } 617}).catch((err: BusinessError) => { 618 console.error(`Failed to check the key 'startup'. code: ${err.code}, message: ${err.message}`); 619}) 620``` 621 622### hasSync 623 624hasSync(key: string): boolean 625 626检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，此为同步接口。 627 628**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 629 630**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 631 632**参数：** 633 634| 参数名 | 类型 | 必填 | 说明 | 635| ------ | ------ | ---- | ------------------------------- | 636| key | string | 是 | 要检查的存储key名称，不能为空。 | 637 638**返回值：** 639 640| 类型 | 说明 | 641| ---------------------- | ------------------------------------------------------------ | 642| boolean | 返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 643 644**错误码：** 645 646以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 647 648| 错误码ID | 错误信息 | 649| -------- | ------------------------------ | 650| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 651| 15500000 | Inner error. | 652 653**示例：** 654 655```ts 656let isExist: boolean = preferences.hasSync('startup'); 657if (isExist) { 658 console.info("The key 'startup' is contained."); 659} else { 660 console.error("The key 'startup' dose not contain."); 661} 662``` 663 664### delete 665 666delete(key: string): Promise<void> 667 668从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 669 670**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 671 672**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 673 674**参数：** 675 676| 参数名 | 类型 | 必填 | 说明 | 677| ------ | ------ | ---- | ------------------------------- | 678| key | string | 是 | 要删除的存储key名称，不能为空。 | 679 680**返回值：** 681 682| 类型 | 说明 | 683| ------------------- | ------------------------- | 684| Promise<void> | 无返回结果的Promise对象。 | 685 686**错误码：** 687 688以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 689 690| 错误码ID | 错误信息 | 691| -------- | ------------------------------ | 692| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 693| 15500000 | Inner error. | 694 695**示例：** 696 697```ts 698import { BusinessError } from '@kit.BasicServicesKit'; 699 700let promise = preferences.delete('startup'); 701promise.then(() => { 702 console.info("Succeeded in deleting the key 'startup'."); 703}).catch((err: BusinessError) => { 704 console.error(`Failed to delete the key 'startup'. code: ${err.code}, message: ${err.message}`); 705}) 706``` 707 708### deleteSync 709 710deleteSync(key: string): void 711 712从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 713 714**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 715 716**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 717 718**参数：** 719 720| 参数名 | 类型 | 必填 | 说明 | 721| ------ | ------ | ---- | ------------------------------- | 722| key | string | 是 | 要删除的存储key名称，不能为空。 | 723 724**错误码：** 725 726以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 727 728| 错误码ID | 错误信息 | 729| -------- | ------------------------------ | 730| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 731| 15500000 | Inner error. | 732 733**示例：** 734 735```ts 736preferences.deleteSync('startup'); 737``` 738 739### flush 740 741flush(): Promise<void> 742 743将缓存的Preferences实例中的数据异步存储到共享用户首选项的持久化文件中，使用Promise异步回调。 744 745 > **说明：** 746 > 747 > 当数据未修改或修改后的数据与缓存数据一致时，不会刷新持久化文件。 748 749**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 750 751**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 752 753**返回值：** 754 755| 类型 | 说明 | 756| ------------------- | ------------------------- | 757| Promise<void> | 无返回结果的Promise对象。 | 758 759**错误码：** 760 761以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 762 763| 错误码ID | 错误信息 | 764| -------- | ------------------------------ | 765| 15500000 | Inner error. | 766 767**示例：** 768 769```ts 770import { BusinessError } from '@kit.BasicServicesKit'; 771 772let promise = preferences.flush(); 773promise.then(() => { 774 console.info("Succeeded in flushing."); 775}).catch((err: BusinessError) => { 776 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 777}) 778``` 779 780### flushSync<sup>14+</sup> 781 782flushSync(): void 783 784将缓存的Preferences实例中的数据存储到共享用户首选项的持久化文件中。 785 786 > **说明：** 787 > 788 > 当数据未修改或修改后的数据与缓存数据一致时，不会刷新持久化文件。 789 790**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 791 792**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 793 794**错误码：** 795 796以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 797 798| 错误码ID | 错误信息 | 799| -------- | ------------------------------ | 800| 15500000 | Inner error. | 801 802**示例：** 803 804```ts 805preferences.flushSync(); 806``` 807 808### clear 809 810clear(): Promise<void> 811 812清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 813 814**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 815 816**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 817 818**返回值：** 819 820| 类型 | 说明 | 821| ------------------- | ------------------------- | 822| Promise<void> | 无返回结果的Promise对象。 | 823 824**错误码：** 825 826以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 827 828| 错误码ID | 错误信息 | 829| -------- | ------------------------------ | 830| 15500000 | Inner error. | 831 832**示例：** 833 834```ts 835import { BusinessError } from '@kit.BasicServicesKit'; 836 837let promise = preferences.clear(); 838promise.then(() => { 839 console.info("Succeeded in clearing."); 840}).catch((err: BusinessError) => { 841 console.error(`Failed to clear. code: ${err.code}, message: ${err.message}`); 842}) 843``` 844 845### clearSync 846 847clearSync(): void 848 849清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 850 851**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 852 853**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 854 855**错误码：** 856 857以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 858 859| 错误码ID | 错误信息 | 860| -------- | ------------------------------ | 861| 15500000 | Inner error. | 862 863**示例：** 864 865```ts 866preferences.clearSync(); 867``` 868 869### on('change') 870 871on(type: 'change', callback: Callback<string>): void 872 873订阅数据变更，订阅的Key的值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 874 875 > **说明：** 876 > 877 > 当调用[removePreferencesFromCache](#sendablepreferencesremovepreferencesfromcache)或者[deletePreferences](#sendablepreferencesdeletepreferences)后，订阅的数据变更会主动取消订阅，在重新[getPreferences](#sendablepreferencesgetpreferences)后需要重新订阅数据变更。 878 879**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 880 881**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 882 883**参数：** 884 885| 参数名 | 类型 | 必填 | 说明 | 886| -------- | -------- | ---- | ---------------------------------------- | 887| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 888| callback | Callback<string> | 是 | 回调函数。返回发生变更的Key。 | 889 890**错误码：** 891 892以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 893 894| 错误码ID | 错误信息 | 895| -------- | ------------------------------ | 896| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 897| 15500000 | Inner error. | 898 899**示例：** 900 901```ts 902import { BusinessError } from '@kit.BasicServicesKit'; 903 904let observer = (key: string) => { 905 console.info("The key " + key + " changed."); 906} 907preferences.on('change', observer); 908preferences.putSync('startup', 'manual'); 909preferences.flush().then(() => { 910 console.info("Succeeded in flushing."); 911}).catch((err: BusinessError) => { 912 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 913}) 914``` 915 916### on('multiProcessChange') 917 918on(type: 'multiProcessChange', callback: Callback<string>): void 919 920订阅进程间数据变更，多个进程持有同一个首选项文件时，在任意一个进程（包括本进程）执行[flush](#flush)方法，持久化文件发生变更后，触发callback回调。 921 922本接口提供给申请了[dataGroupId](#options)的应用进行使用，未申请的应用不推荐使用，多进程操作可能会损坏持久化文件，导致数据丢失。 923 924 > **说明：** 925 > 926 > 同一持久化文件在当前进程订阅进程间数据变更的最大数量为50次，超过最大限制后会订阅失败。建议在触发callback回调后及时取消订阅。 927 > 928 > 当调用[removePreferencesFromCache](#sendablepreferencesremovepreferencesfromcache)或者[deletePreferences](#sendablepreferencesdeletepreferences)后，订阅的数据变更会主动取消订阅，在重新[getPreferences](#sendablepreferencesgetpreferences)后需要重新订阅数据变更。 929 930**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 931 932**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 933 934**参数：** 935 936| 参数名 | 类型 | 必填 | 说明 | 937| -------- | -------- | ---- | ------------------------------------------------------------ | 938| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 939| callback | Callback<string> | 是 | 回调函数。返回发生变更的Key。 | 940 941**错误码：** 942 943以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 944 945| 错误码ID | 错误信息 | 946| -------- | -------------------------------------- | 947| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 948| 15500000 | Inner error. | 949| 15500019 | Failed to obtain the subscription service. | 950 951**示例：** 952 953```ts 954import { BusinessError } from '@kit.BasicServicesKit'; 955 956let observer = (key: string) => { 957 console.info("The key " + key + " changed."); 958} 959preferences.on('multiProcessChange', observer); 960preferences.putSync('startup', 'manual'); 961preferences.flush().then(() => { 962 console.info("Succeeded in flushing."); 963}).catch((err: BusinessError) => { 964 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 965}) 966``` 967 968### on('dataChange') 969 970on(type: 'dataChange', keys: Array<string>, callback: Callback<lang.ISendable>): void 971 972精确订阅数据变更，只有被订阅的key值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 973 974 > **说明：** 975 > 976 > 当调用[removePreferencesFromCache](#sendablepreferencesremovepreferencesfromcache)或者[deletePreferences](#sendablepreferencesdeletepreferences)后，订阅的数据变更会主动取消订阅，在重新[getPreferences](#sendablepreferencesgetpreferences)后需要重新订阅数据变更。 977 978**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 979 980**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 981 982**参数：** 983 984| 参数名 | 类型 | 必填 | 说明 | 985| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 986| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 987| keys | Array<string> | 是 | 需要订阅的key集合。 | 988| callback | callback: Callback<[lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable)> | 是 | 回调函数。回调支持返回多个键值对，其中键为发生变更的订阅key，值为变更后的数据：支持number、string、boolean、bigint以及可序列化的object。 | 989 990**错误码：** 991 992以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 993 994| 错误码ID | 错误信息 | 995| -------- | ------------------------------ | 996| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 997| 15500000 | Inner error. | 998 999**示例：** 1000 1001```ts 1002import { BusinessError } from '@kit.BasicServicesKit'; 1003import { lang } from '@kit.ArkTS'; 1004 1005let observer = (data: lang.ISendable) => { 1006 console.info(`observer : ${data}`) 1007} 1008let keys = ['name', 'age']; 1009preferences.on('dataChange', keys, observer); 1010preferences.putSync('name', 'xiaohong'); 1011preferences.putSync('weight', 125); 1012preferences.flush().then(() => { 1013 console.info("Succeeded in flushing."); 1014}).catch((err: BusinessError) => { 1015 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1016}); 1017``` 1018 1019### off('change') 1020 1021off(type: 'change', callback?: Callback<string>): void 1022 1023取消订阅数据变更。 1024 1025**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1026 1027**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1028 1029**参数：** 1030 1031| 参数名 | 类型 | 必填 | 说明 | 1032| -------- | -------- | ---- | ------------------------------------------------------------ | 1033| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 1034| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 1035 1036**错误码：** 1037 1038以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1039 1040| 错误码ID | 错误信息 | 1041| -------- | ------------------------------ | 1042| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1043| 15500000 | Inner error. | 1044 1045**示例：** 1046 1047```ts 1048import { BusinessError } from '@kit.BasicServicesKit'; 1049 1050let observer = (key: string) => { 1051 console.info("The key " + key + " changed."); 1052} 1053preferences.on('change', observer); 1054preferences.putSync('startup', 'auto'); 1055preferences.flush().then(() => { 1056 console.info("Succeeded in flushing."); 1057 preferences.off('change', observer); 1058}).catch((err: BusinessError) => { 1059 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1060}); 1061``` 1062 1063### off('multiProcessChange') 1064 1065off(type: 'multiProcessChange', callback?: Callback<string>): void 1066 1067取消订阅进程间数据变更。 1068 1069本接口提供给申请了[dataGroupId](#options)的应用进行使用，未申请的应用不推荐使用，多进程操作可能会损坏持久化文件，导致数据丢失。 1070 1071**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1072 1073**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1074 1075**参数：** 1076 1077| 参数名 | 类型 | 必填 | 说明 | 1078| -------- | -------- | ---- | ------------------------------------------------------------ | 1079| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 1080| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 1081 1082**错误码：** 1083 1084以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1085 1086| 错误码ID | 错误信息 | 1087| -------- | ------------------------------ | 1088| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1089| 15500000 | Inner error. | 1090 1091**示例：** 1092 1093```ts 1094import { BusinessError } from '@kit.BasicServicesKit'; 1095 1096let observer = (key: string) => { 1097 console.info("The key " + key + " changed."); 1098} 1099preferences.on('multiProcessChange', observer); 1100preferences.putSync('startup', 'auto'); 1101preferences.flush().then(() => { 1102 console.info("Succeeded in flushing."); 1103 preferences.off('multiProcessChange', observer); 1104}).catch((err: BusinessError) => { 1105 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1106}); 1107``` 1108### off('dataChange') 1109 1110off(type: 'dataChange', keys: Array<string>, callback?: Callback<lang.ISendable>): void 1111 1112取消精确订阅数据变更。 1113 1114**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1115 1116**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1117 1118**参数：** 1119 1120| 参数名 | 类型 | 必填 | 说明 | 1121| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1122| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 1123| keys | Array<string> | 是 | 需要取消订阅的key集合，当keys为空数组时，表示取消订阅全部key；当keys为非空数组时，表示只取消订阅key集合中的key。 | 1124| callback | Callback<[lang.ISendable](../../arkts-utils/arkts-sendable.md#isendable)> | 否 | 需要取消的回调函数，若callback不填写，表示所有的callback都需要处理；若callback填写，表示只处理该callback。 | 1125 1126**错误码：** 1127 1128以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1129 1130| 错误码ID | 错误信息 | 1131| -------- | ------------------------------ | 1132| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1133| 15500000 | Inner error. | 1134 1135**示例：** 1136 1137```ts 1138import { BusinessError } from '@kit.BasicServicesKit'; 1139import { lang } from '@kit.ArkTS'; 1140 1141let observer = (data: lang.ISendable) => { 1142 console.info(`observer : ${data}`) 1143} 1144let keys = ['name', 'age']; 1145preferences.on('dataChange', keys, observer); 1146preferences.putSync('name', 'xiaohong'); 1147preferences.putSync('weight', 125); 1148preferences.flush().then(() => { 1149 console.info("Succeeded in flushing."); 1150 preferences.off('dataChange', keys, observer); 1151}).catch((err: BusinessError) => { 1152 console.error(`Failed to flush. code: ${err.code}, message: ${err.message}`); 1153}); 1154``` 1155