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