1# @ohos.data.preferences (用户首选项) 2 3用户首选项为应用提供Key-Value键值型的数据处理能力，支持应用持久化轻量级数据，并对其修改和查询。 4 5数据存储形式为键值对，键的类型为字符串型，值的存储数据类型包括数字型、字符型、布尔型以及这3种类型的数组类型。 6 7用户首选项默认加密等级为EL2，持久化文件存储在对应的EL2路径下。设备开机后，若无锁屏密码，可直接访问；若有锁屏密码，此路径下的文件需要至少一次解锁对应用户的锁屏界面后（密码、指纹、人脸等方式解锁皆可）才能够访问。需避免在开机未解锁的情况下访问首选项。修改加密等级的方法请参见[获取和修改加密分区](../../../application-dev/application-models/application-context-stage.md#获取和修改加密分区)。 8 9> **说明：** 10> 11> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> 13> 首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。 14 15## 导入模块 16 17```ts 18import { preferences } from '@kit.ArkData'; 19``` 20 21## 常量 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 26 27| 名称 | 参数类型 | 可读 | 可写 | 说明 | 28| ---------------- | -------- | ---- | ---- | --------------------------------------- | 29| MAX_KEY_LENGTH | number | 是 | 否 | Key的最大长度限制为1024个字节。 | 30| MAX_VALUE_LENGTH | number | 是 | 否 | Value的最大长度限制为16 * 1024 * 1024个字节。 | 31 32 33## preferences.getPreferences 34 35getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void 36 37获取Preferences实例，使用callback异步回调。 38 39**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 47| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 48| name | string | 是 | Preferences实例的名称。 | 49| callback | AsyncCallback<[Preferences](#preferences)> | 是 | 回调函数。当获取Preferences实例成功，err为undefined，返回Preferences实例；否则err为错误对象。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 54 55| 错误码ID | 错误信息 | 56| -------- | ------------------------------ | 57| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 58| 15500000 | Inner error. | 59 60**示例：** 61 62FA模型示例： 63 64<!--code_no_check_fa--> 65```ts 66import { featureAbility } from '@kit.AbilityKit'; 67import { BusinessError } from '@kit.BasicServicesKit'; 68 69let context = featureAbility.getContext(); 70let dataPreferences: preferences.Preferences | null = null; 71 72preferences.getPreferences(context, 'myStore', (err: BusinessError, val: preferences.Preferences) => { 73 if (err) { 74 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 75 return; 76 } 77 dataPreferences = val; 78 console.info("Succeeded in getting preferences."); 79}) 80``` 81 82Stage模型示例： 83 84```ts 85import { UIAbility } from '@kit.AbilityKit'; 86import { BusinessError } from '@kit.BasicServicesKit'; 87import { window } from '@kit.ArkUI'; 88 89let dataPreferences: preferences.Preferences | null = null; 90 91class EntryAbility extends UIAbility { 92 onWindowStageCreate(windowStage: window.WindowStage) { 93 preferences.getPreferences(this.context, 'myStore', (err: BusinessError, val: preferences.Preferences) => { 94 if (err) { 95 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 96 return; 97 } 98 dataPreferences = val; 99 console.info("Succeeded in getting preferences."); 100 }) 101 } 102} 103``` 104 105## preferences.getPreferences 106 107getPreferences(context: Context, name: string): Promise<Preferences> 108 109获取Preferences实例，使用Promise异步回调。 110 111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 114 115**参数：** 116 117| 参数名 | 类型 | 必填 | 说明 | 118| ------- | ------------------------------------- | ---- | ----------------------- | 119| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 120| name | string | 是 | Preferences实例的名称。 | 121 122**返回值：** 123 124| 类型 | 说明 | 125| ------------------------------------------ | ---------------------------------- | 126| Promise<[Preferences](#preferences)> | Promise对象，返回Preferences实例。 | 127 128**错误码：** 129 130以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 131 132| 错误码ID | 错误信息 | 133| -------- | ------------------------------ | 134| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 135| 15500000 | Inner error. | 136 137**示例：** 138 139FA模型示例： 140 141<!--code_no_check_fa--> 142```ts 143// 获取context 144import { featureAbility } from '@kit.AbilityKit'; 145import { BusinessError } from '@kit.BasicServicesKit'; 146 147let context = featureAbility.getContext(); 148 149let dataPreferences: preferences.Preferences | null = null; 150let promise = preferences.getPreferences(context, 'myStore'); 151promise.then((object: preferences.Preferences) => { 152 dataPreferences = object; 153 console.info("Succeeded in getting preferences."); 154}).catch((err: BusinessError) => { 155 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 156}) 157``` 158 159Stage模型示例： 160 161```ts 162import { UIAbility } from '@kit.AbilityKit'; 163import { BusinessError } from '@kit.BasicServicesKit'; 164import { window } from '@kit.ArkUI'; 165 166let dataPreferences: preferences.Preferences | null = null; 167 168class EntryAbility extends UIAbility { 169 onWindowStageCreate(windowStage: window.WindowStage) { 170 let promise = preferences.getPreferences(this.context, 'myStore'); 171 promise.then((object: preferences.Preferences) => { 172 dataPreferences = object; 173 console.info("Succeeded in getting preferences."); 174 }).catch((err: BusinessError) => { 175 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 176 }) 177 } 178} 179``` 180 181## preferences.getPreferences<sup>10+</sup> 182 183getPreferences(context: Context, options: Options, callback: AsyncCallback<Preferences>): void 184 185获取Preferences实例，使用callback异步回调。 186 187**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 188 189**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 195| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 196| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 197| callback | AsyncCallback<[Preferences](#preferences)> | 是 | 回调函数。当获取Preferences实例成功，err为undefined，返回Preferences实例；否则err为错误对象。 | 198 199**错误码：** 200 201以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 202 203| 错误码ID | 错误信息 | 204| -------- | ------------------------------ | 205| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 206| 801 | Capability not supported. | 207| 15500000 | Inner error. | 208| 15501001 | Only supported in stage mode. | 209| 15501002 | The data group id is not valid. | 210 211**示例：** 212 213FA模型示例： 214 215<!--code_no_check_fa--> 216```ts 217// 获取context 218import { featureAbility } from '@kit.AbilityKit'; 219import { BusinessError } from '@kit.BasicServicesKit'; 220 221let context = featureAbility.getContext(); 222let dataPreferences: preferences.Preferences | null = null; 223 224let options: preferences.Options = { name: 'myStore' }; 225preferences.getPreferences(context, options, (err: BusinessError, val: preferences.Preferences) => { 226 if (err) { 227 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 228 return; 229 } 230 dataPreferences = val; 231 console.info("Succeeded in getting preferences."); 232}) 233``` 234 235 236Stage模型示例： 237 238```ts 239import { UIAbility } from '@kit.AbilityKit'; 240import { BusinessError } from '@kit.BasicServicesKit'; 241import { window } from '@kit.ArkUI'; 242 243let dataPreferences: preferences.Preferences | null = null; 244 245class EntryAbility extends UIAbility { 246 onWindowStageCreate(windowStage: window.WindowStage) { 247 let options: preferences.Options = { name: 'myStore' }; 248 preferences.getPreferences(this.context, options, (err: BusinessError, val: preferences.Preferences) => { 249 if (err) { 250 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 251 return; 252 } 253 dataPreferences = val; 254 console.info("Succeeded in getting preferences."); 255 }) 256 } 257} 258``` 259 260## preferences.getPreferences<sup>10+</sup> 261 262getPreferences(context: Context, options: Options): Promise<Preferences> 263 264获取Preferences实例，使用Promise异步回调。 265 266**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 267 268**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 269 270**参数：** 271 272| 参数名 | 类型 | 必填 | 说明 | 273| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 274| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 275| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 276 277**返回值：** 278 279| 类型 | 说明 | 280| --------------------------------------- | ---------------------------------- | 281| Promise<[Preferences](#preferences)> | Promise对象，返回Preferences实例。 | 282 283**错误码：** 284 285以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 286 287| 错误码ID | 错误信息 | 288| -------- | ------------------------------ | 289| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 290| 801 | Capability not supported. | 291| 15500000 | Inner error. | 292| 15501001 | Only supported in stage mode. | 293| 15501002 | The data group id is not valid. | 294 295**示例：** 296 297FA模型示例： 298 299<!--code_no_check_fa--> 300```ts 301// 获取context 302import { featureAbility } from '@kit.AbilityKit'; 303import { BusinessError } from '@kit.BasicServicesKit'; 304 305let context = featureAbility.getContext(); 306 307let dataPreferences: preferences.Preferences | null = null; 308let options: preferences.Options = { name: 'myStore' }; 309let promise = preferences.getPreferences(context, options); 310promise.then((object: preferences.Preferences) => { 311 dataPreferences = object; 312 console.info("Succeeded in getting preferences."); 313}).catch((err: BusinessError) => { 314 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 315}) 316``` 317 318Stage模型示例： 319 320```ts 321import { UIAbility } from '@kit.AbilityKit'; 322import { BusinessError } from '@kit.BasicServicesKit'; 323import { window } from '@kit.ArkUI'; 324 325let dataPreferences: preferences.Preferences | null = null; 326 327class EntryAbility extends UIAbility { 328 onWindowStageCreate(windowStage: window.WindowStage) { 329 let options: preferences.Options = { name: 'myStore' }; 330 let promise = preferences.getPreferences(this.context, options); 331 promise.then((object: preferences.Preferences) => { 332 dataPreferences = object; 333 console.info("Succeeded in getting preferences."); 334 }).catch((err: BusinessError) => { 335 console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message); 336 }) 337 } 338} 339``` 340 341## preferences.getPreferencesSync<sup>10+</sup> 342 343getPreferencesSync(context: Context, options: Options): Preferences 344 345获取Preferences实例，此为同步接口。 346 347**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 348 349**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 350 351**参数：** 352 353| 参数名 | 类型 | 必填 | 说明 | 354| ------- | --------------------- | ---- | ------------------------------------------------------------ | 355| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 356| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 357 358**返回值：** 359 360| 类型 | 说明 | 361| --------------------------- | --------------------- | 362| [Preferences](#preferences) | 返回Preferences实例。 | 363 364**错误码：** 365 366以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 367 368| 错误码ID | 错误信息 | 369| -------- | ------------------------------ | 370| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 371| 801 | Capability not supported. | 372| 15500000 | Inner error. | 373| 15501001 | Only supported in stage mode. | 374| 15501002 | The data group id is not valid. | 375 376**示例：** 377 378FA模型示例： 379 380<!--code_no_check_fa--> 381```ts 382// 获取context 383import { featureAbility } from '@kit.AbilityKit'; 384 385let context = featureAbility.getContext(); 386let dataPreferences: preferences.Preferences | null = null; 387 388let options: preferences.Options = { name: 'myStore' }; 389dataPreferences = preferences.getPreferencesSync(context, options); 390``` 391 392Stage模型示例： 393 394```ts 395import { UIAbility } from '@kit.AbilityKit'; 396import { window } from '@kit.ArkUI'; 397 398let dataPreferences: preferences.Preferences | null = null; 399 400class EntryAbility extends UIAbility { 401 onWindowStageCreate(windowStage: window.WindowStage) { 402 let options: preferences.Options = { name: 'myStore' }; 403 dataPreferences = preferences.getPreferencesSync(this.context, options); 404 } 405} 406``` 407 408## preferences.deletePreferences 409 410deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void 411 412从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用callback异步回调。 413 414调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 415 416不支持该接口与preference其他接口并发调用。 417 418**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 419 420**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| -------- | ------------------------------------- | ---- | ---------------------------------------------------- | 426| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 427| name | string | 是 | Preferences实例的名称。 | 428| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 429 430**错误码：** 431 432以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 433 434| 错误码ID | 错误信息 | 435| -------- | ------------------------------ | 436| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 437| 15500000 | Inner error. | 438| 15500010 | Failed to delete preferences file. | 439 440**示例：** 441 442FA模型示例： 443 444<!--code_no_check_fa--> 445```ts 446// 获取context 447import { featureAbility } from '@kit.AbilityKit'; 448import { BusinessError } from '@kit.BasicServicesKit'; 449 450let context = featureAbility.getContext(); 451 452preferences.deletePreferences(context, 'myStore', (err: BusinessError) => { 453 if (err) { 454 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 455 return; 456 } 457 console.info("Succeeded in deleting preferences."); 458}) 459``` 460 461Stage模型示例： 462 463```ts 464import { UIAbility } from '@kit.AbilityKit'; 465import { BusinessError } from '@kit.BasicServicesKit'; 466import { window } from '@kit.ArkUI'; 467 468class EntryAbility extends UIAbility { 469 onWindowStageCreate(windowStage: window.WindowStage) { 470 preferences.deletePreferences(this.context, 'myStore', (err: BusinessError) => { 471 if (err) { 472 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 473 return; 474 } 475 console.info("Succeeded in deleting preferences."); 476 }) 477 } 478} 479``` 480 481## preferences.deletePreferences 482 483deletePreferences(context: Context, name: string): Promise<void> 484 485从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用Promise异步回调。 486 487调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 488 489不支持该接口与preference其他接口并发调用。 490 491**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 492 493**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| ------- | ------------------------------------- | ---- | ----------------------- | 499| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 500| name | string | 是 | Preferences实例的名称。 | 501 502**返回值：** 503 504| 类型 | 说明 | 505| ------------------- | ------------------------- | 506| Promise<void> | 无返回结果的Promise对象。 | 507 508**错误码：** 509 510以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 511 512| 错误码ID | 错误信息 | 513| -------- | ------------------------------ | 514| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 515| 15500000 | Inner error. | 516| 15500010 | Failed to delete preferences file. | 517 518**示例：** 519 520FA模型示例： 521 522<!--code_no_check_fa--> 523```ts 524// 获取context 525import { featureAbility } from '@kit.AbilityKit'; 526import { BusinessError } from '@kit.BasicServicesKit'; 527 528let context = featureAbility.getContext(); 529 530let promise = preferences.deletePreferences(context, 'myStore'); 531promise.then(() => { 532 console.info("Succeeded in deleting preferences."); 533}).catch((err: BusinessError) => { 534 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 535}) 536``` 537 538Stage模型示例： 539 540```ts 541import { UIAbility } from '@kit.AbilityKit'; 542import { BusinessError } from '@kit.BasicServicesKit'; 543import { window } from '@kit.ArkUI'; 544 545class EntryAbility extends UIAbility { 546 onWindowStageCreate(windowStage: window.WindowStage) { 547 let promise = preferences.deletePreferences(this.context, 'myStore'); 548 promise.then(() => { 549 console.info("Succeeded in deleting preferences."); 550 }).catch((err: BusinessError) => { 551 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 552 }) 553 } 554} 555``` 556 557## preferences.deletePreferences<sup>10+</sup> 558 559deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void 560 561从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用callback异步回调。 562 563调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 564 565不支持该接口与preference其他接口并发调用。 566 567**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 568 569**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 570 571**参数：** 572 573| 参数名 | 类型 | 必填 | 说明 | 574| -------- | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 575| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 576| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 577| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 578 579**错误码：** 580 581以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 582 583| 错误码ID | 错误信息 | 584| -------- | ------------------------------ | 585| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 586| 801 | Capability not supported. | 587| 15500000 | Inner error. | 588| 15500010 | Failed to delete preferences file. | 589| 15501001 | Only supported in stage mode. | 590| 15501002 | The data group id is not valid. | 591 592**示例：** 593 594FA模型示例： 595 596<!--code_no_check_fa--> 597```ts 598// 获取context 599import { featureAbility } from '@kit.AbilityKit'; 600import { BusinessError } from '@kit.BasicServicesKit'; 601 602let context = featureAbility.getContext(); 603 604let options: preferences.Options = { name: 'myStore' }; 605preferences.deletePreferences(context, options, (err: BusinessError) => { 606 if (err) { 607 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 608 return; 609 } 610 console.info("Succeeded in deleting preferences."); 611}) 612``` 613 614Stage模型示例： 615 616```ts 617import { UIAbility } from '@kit.AbilityKit'; 618import { BusinessError } from '@kit.BasicServicesKit'; 619import { window } from '@kit.ArkUI'; 620 621class EntryAbility extends UIAbility { 622 onWindowStageCreate(windowStage: window.WindowStage) { 623 let options: preferences.Options = { name: 'myStore' }; 624 preferences.deletePreferences(this.context, options, (err: BusinessError) => { 625 if (err) { 626 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 627 return; 628 } 629 console.info("Succeeded in deleting preferences."); 630 }) 631 } 632} 633``` 634 635 636## preferences.deletePreferences<sup>10+</sup> 637 638deletePreferences(context: Context, options: Options): Promise<void> 639 640从缓存中移出指定的Preferences实例，若Preferences实例有对应的持久化文件，则同时删除其持久化文件。使用Promise异步回调。 641 642调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 643 644不支持该接口与preference其他接口并发调用。 645 646**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 647 648**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 649 650**参数：** 651 652| 参数名 | 类型 | 必填 | 说明 | 653| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 654| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 655| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 656 657**返回值：** 658 659| 类型 | 说明 | 660| ------------------- | ------------------------- | 661| Promise<void> | 无返回结果的Promise对象。 | 662 663**错误码：** 664 665以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 666 667| 错误码ID | 错误信息 | 668| -------- | ------------------------------ | 669| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 670| 801 | Capability not supported. | 671| 15500000 | Inner error. | 672| 15500010 | Failed to delete preferences file. | 673| 15501001 | Only supported in stage mode. | 674| 15501002 | The data group id is not valid. | 675 676**示例：** 677 678FA模型示例： 679 680<!--code_no_check_fa--> 681```ts 682// 获取context 683import { featureAbility } from '@kit.AbilityKit'; 684import { BusinessError } from '@kit.BasicServicesKit'; 685 686let context = featureAbility.getContext(); 687 688let options: preferences.Options = { name: 'myStore' }; 689let promise = preferences.deletePreferences(context, options); 690promise.then(() => { 691 console.info("Succeeded in deleting preferences."); 692}).catch((err: BusinessError) => { 693 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 694}) 695``` 696 697Stage模型示例： 698 699```ts 700import { UIAbility } from '@kit.AbilityKit'; 701import { BusinessError } from '@kit.BasicServicesKit'; 702import { window } from '@kit.ArkUI'; 703 704class EntryAbility extends UIAbility { 705 onWindowStageCreate(windowStage: window.WindowStage) { 706 let options: preferences.Options = { name: 'myStore' }; 707 let promise = preferences.deletePreferences(this.context, options); 708 promise.then(() => { 709 console.info("Succeeded in deleting preferences."); 710 }).catch((err: BusinessError) => { 711 console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message); 712 }) 713 } 714} 715``` 716 717 718## preferences.removePreferencesFromCache 719 720removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void 721 722从缓存中移出指定的Preferences实例，使用callback异步回调。 723 724应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 725 726调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 727 728**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 729 730**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 731 732**参数：** 733 734| 参数名 | 类型 | 必填 | 说明 | 735| -------- | ------------------------------------- | ---- | ---------------------------------------------------- | 736| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 737| name | string | 是 | Preferences实例的名称。 | 738| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 739 740**错误码：** 741 742以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 743 744| 错误码ID | 错误信息 | 745| -------- | ------------------------------ | 746| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 747| 15500000 | Inner error. | 748 749**示例：** 750 751FA模型示例： 752 753<!--code_no_check_fa--> 754```ts 755// 获取context 756import { featureAbility } from '@kit.AbilityKit'; 757import { BusinessError } from '@kit.BasicServicesKit'; 758 759let context = featureAbility.getContext(); 760preferences.removePreferencesFromCache(context, 'myStore', (err: BusinessError) => { 761 if (err) { 762 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 763 return; 764 } 765 console.info("Succeeded in removing preferences."); 766}) 767``` 768 769Stage模型示例： 770 771```ts 772import { UIAbility } from '@kit.AbilityKit'; 773import { BusinessError } from '@kit.BasicServicesKit'; 774import { window } from '@kit.ArkUI'; 775 776class EntryAbility extends UIAbility { 777 onWindowStageCreate(windowStage: window.WindowStage) { 778 preferences.removePreferencesFromCache(this.context, 'myStore', (err: BusinessError) => { 779 if (err) { 780 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 781 return; 782 } 783 console.info("Succeeded in removing preferences."); 784 }) 785 } 786} 787``` 788 789## preferences.removePreferencesFromCache 790 791removePreferencesFromCache(context: Context, name: string): Promise<void> 792 793从缓存中移出指定的Preferences实例，使用Promise异步回调。 794 795应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 796 797调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 798 799**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 800 801**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 802 803**参数：** 804 805| 参数名 | 类型 | 必填 | 说明 | 806| ------- | ------------------------------------- | ---- | ----------------------- | 807| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 808| name | string | 是 | Preferences实例的名称。 | 809 810**返回值：** 811 812| 类型 | 说明 | 813| ------------------- | ------------------------- | 814| Promise<void> | 无返回结果的Promise对象。 | 815 816**错误码：** 817 818以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 819 820| 错误码ID | 错误信息 | 821| -------- | ------------------------------ | 822| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 823| 15500000 | Inner error. | 824 825**示例：** 826 827FA模型示例： 828 829<!--code_no_check_fa--> 830```ts 831// 获取context 832import { featureAbility } from '@kit.AbilityKit'; 833import { BusinessError } from '@kit.BasicServicesKit'; 834 835let context = featureAbility.getContext(); 836let promise = preferences.removePreferencesFromCache(context, 'myStore'); 837promise.then(() => { 838 console.info("Succeeded in removing preferences."); 839}).catch((err: BusinessError) => { 840 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 841}) 842``` 843 844Stage模型示例： 845 846```ts 847import { UIAbility } from '@kit.AbilityKit'; 848import { BusinessError } from '@kit.BasicServicesKit'; 849import { window } from '@kit.ArkUI'; 850 851class EntryAbility extends UIAbility { 852 onWindowStageCreate(windowStage: window.WindowStage) { 853 let promise = preferences.removePreferencesFromCache(this.context, 'myStore'); 854 promise.then(() => { 855 console.info("Succeeded in removing preferences."); 856 }).catch((err: BusinessError) => { 857 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 858 }) 859 } 860} 861``` 862 863## preferences.removePreferencesFromCacheSync<sup>10+</sup> 864 865removePreferencesFromCacheSync(context: Context, name: string): void 866 867从缓存中移出指定的Preferences实例，此为同步接口。 868 869应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 870 871调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 872 873**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 874 875**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 876 877**参数：** 878 879| 参数名 | 类型 | 必填 | 说明 | 880| ------- | ------------------------------------- | ---- | ----------------------- | 881| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 882| name | string | 是 | Preferences实例的名称。 | 883 884**错误码：** 885 886以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 887 888| 错误码ID | 错误信息 | 889| -------- | ------------------------------ | 890| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 891| 15500000 | Inner error. | 892 893**示例：** 894 895FA模型示例： 896 897<!--code_no_check_fa--> 898```ts 899// 获取context 900import { featureAbility } from '@kit.AbilityKit'; 901let context = featureAbility.getContext(); 902preferences.removePreferencesFromCacheSync(context, 'myStore'); 903``` 904 905Stage模型示例： 906 907```ts 908import { UIAbility } from '@kit.AbilityKit'; 909import { window } from '@kit.ArkUI'; 910 911class EntryAbility extends UIAbility { 912 onWindowStageCreate(windowStage: window.WindowStage) { 913 preferences.removePreferencesFromCacheSync(this.context, 'myStore'); 914 } 915} 916``` 917 918## preferences.removePreferencesFromCache<sup>10+</sup> 919 920removePreferencesFromCache(context: Context, options: Options, callback: AsyncCallback<void>): void 921 922从缓存中移出指定的Preferences实例，使用callback异步回调。 923 924应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 925 926调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 927 928**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 929 930**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 931 932**参数：** 933 934| 参数名 | 类型 | 必填 | 说明 | 935| -------- | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 936| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 937| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 938| callback | AsyncCallback<void> | 是 | 回调函数。当移除成功，err为undefined，否则为错误对象。 | 939 940**错误码：** 941 942以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 943 944| 错误码ID | 错误信息 | 945| -------- | ------------------------------ | 946| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 947| 801 | Capability not supported. | 948| 15500000 | Inner error. | 949| 15501001 | Only supported in stage mode. | 950| 15501002 | The data group id is not valid. | 951 952**示例：** 953 954FA模型示例： 955 956<!--code_no_check_fa--> 957```ts 958// 获取context 959import { featureAbility } from '@kit.AbilityKit'; 960import { BusinessError } from '@kit.BasicServicesKit'; 961 962let context = featureAbility.getContext(); 963let options: preferences.Options = { name: 'myStore' }; 964preferences.removePreferencesFromCache(context, options, (err: BusinessError) => { 965 if (err) { 966 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 967 return; 968 } 969 console.info("Succeeded in removing preferences."); 970}) 971``` 972 973Stage模型示例： 974 975```ts 976import { UIAbility } from '@kit.AbilityKit'; 977import { BusinessError } from '@kit.BasicServicesKit'; 978import { window } from '@kit.ArkUI'; 979 980class EntryAbility extends UIAbility { 981 onWindowStageCreate(windowStage: window.WindowStage) { 982 let options: preferences.Options = { name: 'myStore' }; 983 preferences.removePreferencesFromCache(this.context, options, (err: BusinessError) => { 984 if (err) { 985 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 986 return; 987 } 988 console.info("Succeeded in removing preferences."); 989 }) 990 } 991} 992``` 993 994## preferences.removePreferencesFromCache<sup>10+</sup> 995 996removePreferencesFromCache(context: Context, options: Options): Promise<void> 997 998从缓存中移出指定的Preferences实例，使用Promise异步回调。 999 1000应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 1001 1002调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 1003 1004**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1005 1006**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1007 1008**参数：** 1009 1010| 参数名 | 类型 | 必填 | 说明 | 1011| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 1012| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 1013| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 1014 1015**返回值：** 1016 1017| 类型 | 说明 | 1018| ------------------- | ------------------------- | 1019| Promise<void> | 无返回结果的Promise对象。 | 1020 1021**错误码：** 1022 1023以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1024 1025| 错误码ID | 错误信息 | 1026| -------- | ------------------------------ | 1027| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1028| 801 | Capability not supported. | 1029| 15500000 | Inner error. | 1030| 15501001 | Only supported in stage mode. | 1031| 15501002 | The data group id is not valid. | 1032 1033**示例：** 1034 1035FA模型示例： 1036 1037<!--code_no_check_fa--> 1038```ts 1039// 获取context 1040import { featureAbility } from '@kit.AbilityKit'; 1041import { BusinessError } from '@kit.BasicServicesKit'; 1042 1043let context = featureAbility.getContext(); 1044let options: preferences.Options = { name: 'myStore' }; 1045let promise = preferences.removePreferencesFromCache(context, options); 1046promise.then(() => { 1047 console.info("Succeeded in removing preferences."); 1048}).catch((err: BusinessError) => { 1049 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 1050}) 1051``` 1052 1053Stage模型示例： 1054 1055```ts 1056import { UIAbility } from '@kit.AbilityKit'; 1057import { BusinessError } from '@kit.BasicServicesKit'; 1058import { window } from '@kit.ArkUI'; 1059 1060class EntryAbility extends UIAbility { 1061 onWindowStageCreate(windowStage: window.WindowStage) { 1062 let options: preferences.Options = { name: 'myStore' }; 1063 let promise = preferences.removePreferencesFromCache(this.context, options); 1064 promise.then(() => { 1065 console.info("Succeeded in removing preferences."); 1066 }).catch((err: BusinessError) => { 1067 console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message); 1068 }) 1069 } 1070} 1071``` 1072 1073## preferences.removePreferencesFromCacheSync<sup>10+</sup> 1074 1075removePreferencesFromCacheSync(context: Context, options: Options):void 1076 1077从缓存中移出指定的Preferences实例，此为同步接口。 1078 1079应用首次调用[getPreferences](#preferencesgetpreferences)接口获取某个Preferences实例后，该实例会被会被缓存起来，后续再次[getPreferences](#preferencesgetpreferences)时不会再次从持久化文件中读取，直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后，再次getPreferences将会重新读取持久化文件，生成新的Preferences实例。 1080 1081调用该接口后，不建议再使用旧的Preferences实例进行数据操作，否则会出现数据一致性问题，应将Preferences实例置为null，系统将会统一回收。 1082 1083**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1084 1085**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1086 1087**参数：** 1088 1089| 参数名 | 类型 | 必填 | 说明 | 1090| ------- | --------------------- | ---- | ------------------------------------------------------------ | 1091| context | Context | 是 | 应用上下文。<br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 1092| options | [Options](#options10) | 是 | 与Preferences实例相关的配置选项。 | 1093 1094**错误码：** 1095 1096以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1097 1098| 错误码ID | 错误信息 | 1099| -------- | ------------------------------ | 1100| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1101| 801 | Capability not supported. | 1102| 15500000 | Inner error. | 1103| 15501001 | Only supported in stage mode. | 1104| 15501002 | The data group id is not valid. | 1105 1106**示例：** 1107 1108FA模型示例： 1109 1110<!--code_no_check_fa--> 1111```ts 1112// 获取context 1113import { featureAbility } from '@kit.AbilityKit'; 1114let context = featureAbility.getContext(); 1115let options: preferences.Options = { name: 'myStore' }; 1116preferences.removePreferencesFromCacheSync(context, options); 1117``` 1118 1119Stage模型示例： 1120 1121```ts 1122import { UIAbility } from '@kit.AbilityKit'; 1123import { window } from '@kit.ArkUI'; 1124 1125class EntryAbility extends UIAbility { 1126 onWindowStageCreate(windowStage: window.WindowStage) { 1127 let options: preferences.Options = { name: 'myStore' }; 1128 preferences.removePreferencesFromCacheSync(this.context, options); 1129 } 1130} 1131``` 1132 1133## Options<sup>10+</sup> 1134 1135Preferences实例配置选项。 1136 1137**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1138 1139**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1140 1141| 名称 | 类型 | 必填 | 说明 | 1142| ----------- | ------ | ---- | ------------------------------------------------------------ | 1143| name | string | 是 | Preferences实例的名称。 | 1144| dataGroupId | string\|null\|undefined | 否 | 应用组ID，需要向应用市场获取，暂不支持。<br/>为可选参数。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时，默认在本应用沙箱目录下创建Preferences实例。<br/> **模型约束：** 此属性仅在Stage模型下可用。| 1145 1146 1147## Preferences 1148 1149首选项实例，提供获取和修改存储数据的接口。 1150 1151下列接口都需先使用[preferences.getPreferences](#preferencesgetpreferences)获取到Preferences实例，再通过此实例调用对应接口。 1152 1153 1154### get 1155 1156get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void 1157 1158从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用callback异步回调。 1159 1160**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1161 1162**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1163 1164**参数：** 1165 1166| 参数名 | 类型 | 必填 | 说明 | 1167| -------- | -------------------------------------------- | ---- |---------------------------| 1168| key | string | 是 | 要获取的存储Key名称，不能为空。 | 1169| defValue | [ValueType](#valuetype) | 是 | 默认返回值。 | 1170| callback | AsyncCallback<[ValueType](#valuetype)> | 是 | 回调函数。当获取成功时，err为undefined，data为键对应的值；否则err为错误对象。 | 1171 1172**错误码：** 1173 1174以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1175 1176| 错误码ID | 错误信息 | 1177| -------- | ------------------------------ | 1178| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1179| 15500000 | Inner error. | 1180 1181**示例：** 1182 1183```ts 1184import { BusinessError } from '@kit.BasicServicesKit'; 1185 1186dataPreferences.get('startup', 'default', (err: BusinessError, val: preferences.ValueType) => { 1187 if (err) { 1188 console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message); 1189 return; 1190 } 1191 console.info("Succeeded in getting value of 'startup'. val： " + val); 1192}) 1193``` 1194 1195### get 1196 1197get(key: string, defValue: ValueType): Promise<ValueType> 1198 1199从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，使用Promise异步回调。 1200 1201**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1202 1203**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1204 1205 **参数：** 1206 1207| 参数名 | 类型 | 必填 | 说明 | 1208| -------- | ----------------------- | ---- |--------| 1209| key | string | 是 | 要获取的存储Key名称，不能为空。 | 1210| defValue | [ValueType](#valuetype) | 是 | 默认返回值。 | 1211 1212**返回值：** 1213 1214| 类型 | 说明 | 1215| ----------------------------------- | ----------------------------- | 1216| Promise<[ValueType](#valuetype)> | Promise对象，返回键对应的值。 | 1217 1218**错误码：** 1219 1220以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1221 1222| 错误码ID | 错误信息 | 1223| -------- | ------------------------------ | 1224| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1225| 15500000 | Inner error. | 1226 1227**示例：** 1228 1229```ts 1230import { BusinessError } from '@kit.BasicServicesKit'; 1231 1232let promise = dataPreferences.get('startup', 'default'); 1233promise.then((data: preferences.ValueType) => { 1234 console.info("Succeeded in getting value of 'startup'. Data: " + data); 1235}).catch((err: BusinessError) => { 1236 console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message); 1237}) 1238``` 1239 1240### getSync<sup>10+</sup> 1241 1242getSync(key: string, defValue: ValueType): ValueType 1243 1244从缓存的Preferences实例中获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue，此为同步接口。 1245 1246**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1247 1248**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1249 1250**参数：** 1251 1252| 参数名 | 类型 | 必填 | 说明 | 1253| -------- | ----------------------- | ---- |---------------------| 1254| key | string | 是 | 要获取的存储Key名称，不能为空。 | 1255| defValue | [ValueType](#valuetype) | 是 | 默认返回值。 | 1256 1257**返回值：** 1258 1259| 类型 | 说明 | 1260| ----------------------------------- | ----------------------------- | 1261| [ValueType](#valuetype) | 返回键对应的值。 | 1262 1263**错误码：** 1264 1265以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1266 1267| 错误码ID | 错误信息 | 1268| -------- | ------------------------------ | 1269| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1270| 15500000 | Inner error. | 1271 1272**示例：** 1273 1274```ts 1275let value: preferences.ValueType = dataPreferences.getSync('startup', 'default'); 1276``` 1277 1278### getAll 1279 1280getAll(callback: AsyncCallback<Object>): void; 1281 1282从缓存的Preferences实例中获取所有键值数据。 1283 1284**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1285 1286**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1287 1288**参数：** 1289 1290| 参数名 | 类型 | 必填 | 说明 | 1291| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 1292| callback | AsyncCallback<Object> | 是 | 回调函数。当获取成功，err为undefined，value为所有键值数据；否则err为错误对象。 | 1293 1294**错误码：** 1295 1296以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1297 1298| 错误码ID | 错误信息 | 1299| -------- | ------------------------------ | 1300| 401 | Parameter error. Mandatory parameters are left unspecified.| 1301| 15500000 | Inner error. | 1302 1303**示例：** 1304 1305```ts 1306import { BusinessError } from '@kit.BasicServicesKit'; 1307 1308// 由于ArkTS中无Object.keys，且无法使用for..in... 1309// 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用 1310function getObjKeys(obj: Object): string[] { 1311 let keys = Object.keys(obj); 1312 return keys; 1313} 1314 1315dataPreferences.getAll((err: BusinessError, value: Object) => { 1316 if (err) { 1317 console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message); 1318 return; 1319 } 1320 let allKeys = getObjKeys(value); 1321 console.info("getAll keys = " + allKeys); 1322 console.info("getAll object = " + JSON.stringify(value)); 1323}) 1324``` 1325 1326 1327### getAll 1328 1329getAll(): Promise<Object> 1330 1331从缓存的Preferences实例中获取所有键值数据。 1332 1333**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1334 1335**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1336 1337**返回值：** 1338 1339| 类型 | 说明 | 1340| --------------------- | ------------------------------------------- | 1341| Promise<Object> | Promise对象，返回含有所有键值数据。 | 1342 1343**错误码：** 1344 1345以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1346 1347| 错误码ID | 错误信息 | 1348| -------- | ------------------------------ | 1349| 15500000 | Inner error. | 1350 1351**示例：** 1352 1353```ts 1354import { BusinessError } from '@kit.BasicServicesKit'; 1355 1356// 由于ArkTS中无Object.keys，且无法使用for..in... 1357// 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用 1358function getObjKeys(obj: Object): string[] { 1359 let keys = Object.keys(obj); 1360 return keys; 1361} 1362 1363let promise = dataPreferences.getAll(); 1364promise.then((value: Object) => { 1365 let allKeys = getObjKeys(value); 1366 console.info('getAll keys = ' + allKeys); 1367 console.info("getAll object = " + JSON.stringify(value)); 1368}).catch((err: BusinessError) => { 1369 console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message); 1370}) 1371``` 1372 1373### getAllSync<sup>10+</sup> 1374 1375getAllSync(): Object 1376 1377从缓存的Preferences实例中获取所有键值数据，此为同步接口。 1378 1379**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1380 1381**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1382 1383**返回值：** 1384 1385| 类型 | 说明 | 1386| --------------------- | ------------------------------------------- | 1387| Object | 返回含有所有键值数据。 | 1388 1389**错误码：** 1390 1391以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1392 1393| 错误码ID | 错误信息 | 1394| -------- | ------------------------------ | 1395| 15500000 | Inner error. | 1396 1397**示例：** 1398 1399```ts 1400// 由于ArkTS中无Object.keys，且无法使用for..in... 1401// 若报ArkTS问题，请将此方法单独抽离至一个ts文件中并暴露，在需要用到的ets文件中引入使用 1402function getObjKeys(obj: Object): string[] { 1403 let keys = Object.keys(obj); 1404 return keys; 1405} 1406 1407let value = dataPreferences.getAllSync(); 1408let allKeys = getObjKeys(value); 1409console.info('getAll keys = ' + allKeys); 1410console.info("getAll object = " + JSON.stringify(value)); 1411``` 1412 1413### put 1414 1415put(key: string, value: ValueType, callback: AsyncCallback<void>): void 1416 1417将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。 1418 1419 > **说明：** 1420 > 1421 > 当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 1422 1423**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1424 1425**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1426 1427**参数：** 1428 1429| 参数名 | 类型 | 必填 | 说明 | 1430| -------- | ------------------------- | ---- |-------------------------| 1431| key | string | 是 | 要修改的存储的Key，不能为空。 | 1432| value | [ValueType](#valuetype) | 是 | 存储的新值。 | 1433| callback | AsyncCallback<void> | 是 | 回调函数。当数据写入成功，err为undefined；否则为错误对象。 | 1434 1435**错误码：** 1436 1437以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1438 1439| 错误码ID | 错误信息 | 1440| -------- | ------------------------------ | 1441| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1442| 15500000 | Inner error. | 1443 1444**示例：** 1445 1446```ts 1447import { BusinessError } from '@kit.BasicServicesKit'; 1448 1449dataPreferences.put('startup', 'auto', (err: BusinessError) => { 1450 if (err) { 1451 console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message); 1452 return; 1453 } 1454 console.info("Succeeded in putting value of 'startup'."); 1455}) 1456``` 1457 1458 1459### put 1460 1461put(key: string, value: ValueType): Promise<void> 1462 1463将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 1464 1465 > **说明：** 1466 > 1467 > 当对应的键已经存在时，put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 1468 1469**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1470 1471**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1472 1473**参数：** 1474 1475| 参数名 | 类型 | 必填 | 说明 | 1476| ------ | ----------------------- | ---- |--------------------------| 1477| key | string | 是 | 要修改的存储的Key，不能为空。 | 1478| value | [ValueType](#valuetype) | 是 | 存储的新值。 | 1479 1480**返回值：** 1481 1482| 类型 | 说明 | 1483| ------------------- | ------------------------- | 1484| Promise<void> | 无返回结果的Promise对象。 | 1485 1486**错误码：** 1487 1488以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1489 1490| 错误码ID | 错误信息 | 1491| -------- | ------------------------------ | 1492| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1493| 15500000 | Inner error. | 1494 1495**示例：** 1496 1497```ts 1498import { BusinessError } from '@kit.BasicServicesKit'; 1499 1500let promise = dataPreferences.put('startup', 'auto'); 1501promise.then(() => { 1502 console.info("Succeeded in putting value of 'startup'."); 1503}).catch((err: BusinessError) => { 1504 console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message); 1505}) 1506``` 1507 1508 1509### putSync<sup>10+</sup> 1510 1511putSync(key: string, value: ValueType): void 1512 1513将数据写入缓存的Preferences实例中，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 1514 1515 > **说明：** 1516 > 1517 > 当对应的键已经存在时，putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。 1518 1519**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1520 1521**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1522 1523**参数：** 1524 1525| 参数名 | 类型 | 必填 | 说明 | 1526| ------ | ----------------------- | ---- | ------------------------ | 1527| key | string | 是 | 要修改的存储的Key，不能为空。 | 1528| value | [ValueType](#valuetype) | 是 | 存储的新值。 | 1529 1530**错误码：** 1531 1532以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1533 1534| 错误码ID | 错误信息 | 1535| -------- | ------------------------------ | 1536| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1537| 15500000 | Inner error. | 1538 1539**示例：** 1540 1541```ts 1542dataPreferences.putSync('startup', 'auto'); 1543``` 1544 1545 1546### has 1547 1548has(key: string, callback: AsyncCallback<boolean>): void 1549 1550检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用callback异步回调。 1551 1552**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1553 1554**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1555 1556**参数：** 1557 1558| 参数名 | 类型 | 必填 | 说明 | 1559| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 1560| key | string | 是 | 要检查的存储key名称，不能为空。 | 1561| callback | AsyncCallback<boolean> | 是 | 回调函数。返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 1562 1563**错误码：** 1564 1565以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1566 1567| 错误码ID | 错误信息 | 1568| -------- | ------------------------------ | 1569| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1570| 15500000 | Inner error. | 1571 1572**示例：** 1573 1574```ts 1575import { BusinessError } from '@kit.BasicServicesKit'; 1576 1577dataPreferences.has('startup', (err: BusinessError, val: boolean) => { 1578 if (err) { 1579 console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 1580 return; 1581 } 1582 if (val) { 1583 console.info("The key 'startup' is contained."); 1584 } else { 1585 console.info("The key 'startup' dose not contain."); 1586 } 1587}) 1588``` 1589 1590 1591### has 1592 1593has(key: string): Promise<boolean> 1594 1595检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，使用Promise异步回调。 1596 1597**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1598 1599**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1600 1601**参数：** 1602 1603| 参数名 | 类型 | 必填 | 说明 | 1604| ------ | ------ | ---- | ------------------------------- | 1605| key | string | 是 | 要检查的存储key名称，不能为空。 | 1606 1607**返回值：** 1608 1609| 类型 | 说明 | 1610| ---------------------- | ------------------------------------------------------------ | 1611| Promise<boolean> | Promise对象。返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 1612 1613**错误码：** 1614 1615以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1616 1617| 错误码ID | 错误信息 | 1618| -------- | ------------------------------ | 1619| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1620| 15500000 | Inner error. | 1621 1622**示例：** 1623 1624```ts 1625import { BusinessError } from '@kit.BasicServicesKit'; 1626 1627let promise = dataPreferences.has('startup'); 1628promise.then((val: boolean) => { 1629 if (val) { 1630 console.info("The key 'startup' is contained."); 1631 } else { 1632 console.info("The key 'startup' dose not contain."); 1633 } 1634}).catch((err: BusinessError) => { 1635 console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 1636}) 1637``` 1638 1639 1640### hasSync<sup>10+</sup> 1641 1642hasSync(key: string): boolean 1643 1644检查缓存的Preferences实例中是否包含名为给定Key的存储键值对，此为同步接口。 1645 1646**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1647 1648**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1649 1650**参数：** 1651 1652| 参数名 | 类型 | 必填 | 说明 | 1653| ------ | ------ | ---- | ------------------------------- | 1654| key | string | 是 | 要检查的存储key名称，不能为空。 | 1655 1656**返回值：** 1657 1658| 类型 | 说明 | 1659| ---------------------- | ------------------------------------------------------------ | 1660| boolean | 返回Preferences实例是否包含给定key的存储键值对，true表示存在，false表示不存在。 | 1661 1662**错误码：** 1663 1664以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1665 1666| 错误码ID | 错误信息 | 1667| -------- | ------------------------------ | 1668| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1669| 15500000 | Inner error. | 1670 1671**示例：** 1672 1673```ts 1674let isExist: boolean = dataPreferences.hasSync('startup'); 1675if (isExist) { 1676 console.info("The key 'startup' is contained."); 1677} else { 1678 console.info("The key 'startup' dose not contain."); 1679} 1680``` 1681 1682 1683### delete 1684 1685delete(key: string, callback: AsyncCallback<void>): void 1686 1687从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。 1688 1689**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1690 1691**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1692 1693**参数：** 1694 1695| 参数名 | 类型 | 必填 | 说明 | 1696| -------- | ------------------------- | ---- | ---------------------------------------------------- | 1697| key | string | 是 | 要删除的存储Key名称，不能为空。 | 1698| callback | AsyncCallback<void> | 是 | 回调函数。当删除成功，err为undefined；否则为错误对象。 | 1699 1700**错误码：** 1701 1702以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1703 1704| 错误码ID | 错误信息 | 1705| -------- | ------------------------------ | 1706| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1707| 15500000 | Inner error. | 1708 1709**示例：** 1710 1711```ts 1712import { BusinessError } from '@kit.BasicServicesKit'; 1713 1714dataPreferences.delete('startup', (err: BusinessError) => { 1715 if (err) { 1716 console.error("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message); 1717 return; 1718 } 1719 console.info("Succeeded in deleting the key 'startup'."); 1720}) 1721``` 1722 1723 1724### delete 1725 1726delete(key: string): Promise<void> 1727 1728从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 1729 1730**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1731 1732**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1733 1734**参数：** 1735 1736| 参数名 | 类型 | 必填 | 说明 | 1737| ------ | ------ | ---- | ------------------------------- | 1738| key | string | 是 | 要删除的存储key名称，不能为空。 | 1739 1740**返回值：** 1741 1742| 类型 | 说明 | 1743| ------------------- | ------------------------- | 1744| Promise<void> | 无返回结果的Promise对象。 | 1745 1746**错误码：** 1747 1748以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1749 1750| 错误码ID | 错误信息 | 1751| -------- | ------------------------------ | 1752| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1753| 15500000 | Inner error. | 1754 1755**示例：** 1756 1757```ts 1758import { BusinessError } from '@kit.BasicServicesKit'; 1759 1760let promise = dataPreferences.delete('startup'); 1761promise.then(() => { 1762 console.info("Succeeded in deleting the key 'startup'."); 1763}).catch((err: BusinessError) => { 1764 console.error("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message); 1765}) 1766``` 1767 1768 1769### deleteSync<sup>10+</sup> 1770 1771deleteSync(key: string): void 1772 1773从缓存的Preferences实例中删除名为给定Key的存储键值对，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 1774 1775**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1776 1777**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1778 1779**参数：** 1780 1781| 参数名 | 类型 | 必填 | 说明 | 1782| ------ | ------ | ---- | ------------------------------- | 1783| key | string | 是 | 要删除的存储key名称，不能为空。 | 1784 1785**错误码：** 1786 1787以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1788 1789| 错误码ID | 错误信息 | 1790| -------- | ------------------------------ | 1791| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1792| 15500000 | Inner error. | 1793 1794**示例：** 1795 1796```ts 1797dataPreferences.deleteSync('startup'); 1798``` 1799 1800 1801### flush 1802 1803flush(callback: AsyncCallback<void>): void 1804 1805将缓存的Preferences实例中的数据异步存储到用户首选项的持久化文件中，使用callback异步回调。 1806 1807**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1808 1809**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1810 1811**参数：** 1812 1813| 参数名 | 类型 | 必填 | 说明 | 1814| -------- | ------------------------- | ---- | ---------------------------------------------------- | 1815| callback | AsyncCallback<void> | 是 | 回调函数。当保存成功，err为undefined；否则为错误对象。 | 1816 1817**错误码：** 1818 1819以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1820 1821| 错误码ID | 错误信息 | 1822| -------- | ------------------------------ | 1823| 401 | Parameter error. Mandatory parameters are left unspecified. | 1824| 15500000 | Inner error. | 1825 1826**示例：** 1827 1828```ts 1829import { BusinessError } from '@kit.BasicServicesKit'; 1830 1831dataPreferences.flush((err: BusinessError) => { 1832 if (err) { 1833 console.error("Failed to flush. code =" + err.code + ", message =" + err.message); 1834 return; 1835 } 1836 console.info("Succeeded in flushing."); 1837}) 1838``` 1839 1840 1841### flush 1842 1843flush(): Promise<void> 1844 1845将缓存的Preferences实例中的数据异步存储到用户首选项的持久化文件中，使用Promise异步回调。 1846 1847**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1848 1849**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1850 1851**返回值：** 1852 1853| 类型 | 说明 | 1854| ------------------- | ------------------------- | 1855| Promise<void> | 无返回结果的Promise对象。 | 1856 1857**错误码：** 1858 1859以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1860 1861| 错误码ID | 错误信息 | 1862| -------- | ------------------------------ | 1863| 15500000 | Inner error. | 1864 1865**示例：** 1866 1867```ts 1868import { BusinessError } from '@kit.BasicServicesKit'; 1869 1870let promise = dataPreferences.flush(); 1871promise.then(() => { 1872 console.info("Succeeded in flushing."); 1873}).catch((err: BusinessError) => { 1874 console.error("Failed to flush. code =" + err.code + ", message =" + err.message); 1875}) 1876``` 1877 1878 1879### clear 1880 1881clear(callback: AsyncCallback<void>): void 1882 1883清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用callback异步回调。 1884 1885**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1886 1887**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1888 1889**参数：** 1890 1891| 参数名 | 类型 | 必填 | 说明 | 1892| -------- | ------------------------- | ---- | ---------------------------------------------------- | 1893| callback | AsyncCallback<void> | 是 | 回调函数。当清除成功，err为undefined；否则为错误对象。 | 1894 1895**错误码：** 1896 1897以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1898 1899| 错误码ID | 错误信息 | 1900| -------- | ------------------------------ | 1901| 401 | Parameter error. Mandatory parameters are left unspecified. | 1902| 15500000 | Inner error. | 1903 1904**示例：** 1905 1906```ts 1907import { BusinessError } from '@kit.BasicServicesKit'; 1908 1909dataPreferences.clear((err: BusinessError) =>{ 1910 if (err) { 1911 console.error("Failed to clear. code =" + err.code + ", message =" + err.message); 1912 return; 1913 } 1914 console.info("Succeeded in clearing."); 1915}) 1916``` 1917 1918 1919### clear 1920 1921clear(): Promise<void> 1922 1923清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，使用Promise异步回调。 1924 1925**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1926 1927**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1928 1929**返回值：** 1930 1931| 类型 | 说明 | 1932| ------------------- | ------------------------- | 1933| Promise<void> | 无返回结果的Promise对象。 | 1934 1935**错误码：** 1936 1937以下错误码的详细介绍请参见[用户首选项错误码](errorcode-preferences.md)。 1938 1939| 错误码ID | 错误信息 | 1940| -------- | ------------------------------ | 1941| 15500000 | Inner error. | 1942 1943**示例：** 1944 1945```ts 1946import { BusinessError } from '@kit.BasicServicesKit'; 1947 1948let promise = dataPreferences.clear(); 1949promise.then(() => { 1950 console.info("Succeeded in clearing."); 1951}).catch((err: BusinessError) => { 1952 console.error("Failed to clear. code =" + err.code + ", message =" + err.message); 1953}) 1954``` 1955 1956 1957### clearSync<sup>10+</sup> 1958 1959clearSync(): void 1960 1961清除缓存的Preferences实例中的所有数据，可通过[flush](#flush)将Preferences实例持久化，此为同步接口。 1962 1963**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1964 1965**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1966 1967**示例：** 1968 1969```ts 1970dataPreferences.clearSync(); 1971``` 1972 1973 1974### on('change') 1975 1976on(type: 'change', callback: Callback<string>): void 1977 1978订阅数据变更，订阅的Key的值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 1979 1980**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1981 1982**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 1983 1984**参数：** 1985 1986| 参数名 | 类型 | 必填 | 说明 | 1987| -------- | -------- | ---- | ---------------------------------------- | 1988| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 1989| callback | Callback<string> | 是 | 回调函数。 | 1990 1991**错误码：** 1992 1993以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 1994 1995| 错误码ID | 错误信息 | 1996| -------- | ------------------------------ | 1997| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 1998| 15500000 | Inner error. | 1999 2000**示例：** 2001 2002```ts 2003import { BusinessError } from '@kit.BasicServicesKit'; 2004 2005let observer = (key: string) => { 2006 console.info("The key " + key + " changed."); 2007} 2008dataPreferences.on('change', observer); 2009dataPreferences.putSync('startup', 'manual'); 2010dataPreferences.flush((err: BusinessError) => { 2011 if (err) { 2012 console.error("Failed to flush. Cause: " + err); 2013 return; 2014 } 2015 console.info("Succeeded in flushing."); 2016}) 2017``` 2018 2019### on('multiProcessChange')<sup>10+</sup> 2020 2021on(type: 'multiProcessChange', callback: Callback<string>): void 2022 2023订阅进程间数据变更，多个进程持有同一个首选项文件时，订阅的Key的值在任意一个进程发生变更后，执行[flush](#flush)方法后，触发callback回调。 2024 2025**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2026 2027**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2028 2029**参数：** 2030 2031| 参数名 | 类型 | 必填 | 说明 | 2032| -------- | -------- | ---- | ------------------------------------------------------------ | 2033| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 2034| callback | Callback<string> | 是 | 回调函数。 | 2035 2036**错误码：** 2037 2038以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2039 2040| 错误码ID | 错误信息 | 2041| -------- | -------------------------------------- | 2042| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2043| 15500000 | Inner error. | 2044| 15500019 | Failed to obtain subscription service. | 2045 2046**示例：** 2047 2048```ts 2049import { BusinessError } from '@kit.BasicServicesKit'; 2050 2051let observer = (key: string) => { 2052 console.info("The key " + key + " changed."); 2053} 2054dataPreferences.on('multiProcessChange', observer); 2055dataPreferences.putSync('startup', 'manual'); 2056dataPreferences.flush((err: BusinessError) => { 2057 if (err) { 2058 console.error("Failed to flush. Cause: " + err); 2059 return; 2060 } 2061 console.info("Succeeded in flushing."); 2062}) 2063``` 2064 2065### on('dataChange')<sup>12+</sup> 2066 2067on(type: 'dataChange', keys: Array<string>, callback: Callback<Record<string, ValueType>>): void 2068 2069精确订阅数据变更，只有被订阅的key值发生变更后，在执行[flush](#flush)方法后，触发callback回调。 2070 2071**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2072 2073**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2074 2075**参数：** 2076 2077| 参数名 | 类型 | 必填 | 说明 | 2078| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2079| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 2080| keys | Array<string> | 是 | 需要订阅的key集合。 | 2081| callback | Callback<Record<string, [ValueType](#valuetype)>> | 是 | 回调函数。回调支持返回多个键值对，其中键为发生变更的订阅key，值为变更后的数据：支持number、string、boolean、Array\<number>、Array\<string>、Array\<boolean>、Uint8Array、object类型。 | 2082 2083**错误码：** 2084 2085以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2086 2087| 错误码ID | 错误信息 | 2088| -------- | ------------------------------ | 2089| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2090| 15500000 | Inner error. | 2091 2092**示例：** 2093 2094```ts 2095import { BusinessError } from '@kit.BasicServicesKit'; 2096 2097let observer = (data: Record<string, preferences.ValueType>) => { 2098 for (const keyValue of Object.entries(data)) { 2099 console.info(`observer : ${keyValue}`) 2100 } 2101 console.info("The observer called.") 2102} 2103let keys = ['name', 'age'] 2104dataPreferences.on('dataChange', keys, observer); 2105dataPreferences.putSync('name', 'xiaohong'); 2106dataPreferences.putSync('weight', 125); 2107dataPreferences.flush((err: BusinessError) => { 2108 if (err) { 2109 console.error("Failed to flush. Cause: " + err); 2110 return; 2111 } 2112 console.info("Succeeded in flushing."); 2113}) 2114``` 2115 2116### off('change') 2117 2118off(type: 'change', callback?: Callback<string>): void 2119 2120取消订阅数据变更。 2121 2122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2123 2124**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2125 2126**参数：** 2127 2128| 参数名 | 类型 | 必填 | 说明 | 2129| -------- | -------- | ---- | ------------------------------------------------------------ | 2130| type | string | 是 | 事件类型，固定值'change'，表示数据变更。 | 2131| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 2132 2133**错误码：** 2134 2135以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2136 2137| 错误码ID | 错误信息 | 2138| -------- | ------------------------------ | 2139| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2140| 15500000 | Inner error. | 2141 2142**示例：** 2143 2144```ts 2145import { BusinessError } from '@kit.BasicServicesKit'; 2146 2147let observer = (key: string) => { 2148 console.info("The key " + key + " changed."); 2149} 2150dataPreferences.on('change', observer); 2151dataPreferences.putSync('startup', 'auto'); 2152dataPreferences.flush((err: BusinessError) => { 2153 if (err) { 2154 console.error("Failed to flush. Cause: " + err); 2155 return; 2156 } 2157 console.info("Succeeded in flushing."); 2158}) 2159dataPreferences.off('change', observer); 2160``` 2161 2162### off('multiProcessChange')<sup>10+</sup> 2163 2164off(type: 'multiProcessChange', callback?: Callback<string>): void 2165 2166取消订阅进程间数据变更。 2167 2168**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2169 2170**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2171 2172**参数：** 2173 2174| 参数名 | 类型 | 必填 | 说明 | 2175| -------- | -------- | ---- | ------------------------------------------------------------ | 2176| type | string | 是 | 事件类型，固定值'multiProcessChange'，表示多进程间的数据变更。 | 2177| callback | Callback<string> | 否 | 需要取消的回调函数，不填写则全部取消。 | 2178 2179**错误码：** 2180 2181以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2182 2183| 错误码ID | 错误信息 | 2184| -------- | ------------------------------ | 2185| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2186| 15500000 | Inner error. | 2187 2188**示例：** 2189 2190```ts 2191import { BusinessError } from '@kit.BasicServicesKit'; 2192 2193let observer = (key: string) => { 2194 console.info("The key " + key + " changed."); 2195} 2196dataPreferences.on('multiProcessChange', observer); 2197dataPreferences.putSync('startup', 'auto'); 2198dataPreferences.flush((err: BusinessError) => { 2199 if (err) { 2200 console.error("Failed to flush. Cause: " + err); 2201 return; 2202 } 2203 console.info("Succeeded in flushing."); 2204}) 2205dataPreferences.off('multiProcessChange', observer); 2206``` 2207### off('dataChange')<sup>12+</sup> 2208 2209off(type: 'dataChange', keys: Array<string>, callback?: Callback<Record<string, ValueType>>): void 2210 2211取消精确订阅数据变更。 2212 2213**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2214 2215**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2216 2217**参数：** 2218 2219| 参数名 | 类型 | 必填 | 说明 | 2220| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2221| type | string | 是 | 事件类型，固定值'dataChange'，表示精确的数据变更。 | 2222| keys | Array<string> | 是 | 需要取消订阅的key集合，当keys为空数组时，表示取消订阅全部key；当keys为非空数组时，表示只取消订阅key集合中的key。 | 2223| callback | Callback<Record<string, [ValueType](#valuetype)>> | 否 | 需要取消的回调函数，若callback不填写，表示所有的callback都需要处理；若callback填写，表示只处理该callback。 | 2224 2225**错误码：** 2226 2227以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[用户首选项错误码](errorcode-preferences.md)。 2228 2229| 错误码ID | 错误信息 | 2230| -------- | ------------------------------ | 2231| 401 | Parameter error. Possible causes:<br>1. Mandatory parameters are left unspecified;<br>2. Incorrect parameter types;<br>3. Parameter verification failed. | 2232| 15500000 | Inner error. | 2233 2234**示例：** 2235 2236```ts 2237import { BusinessError } from '@kit.BasicServicesKit'; 2238 2239let observer = (data: Record<string, preferences.ValueType>) => { 2240 for (const keyValue of Object.entries(data)) { 2241 console.info(`observer : ${keyValue}`) 2242 } 2243 console.info("The observer called.") 2244} 2245let keys = ['name', 'age'] 2246dataPreferences.on('dataChange', keys, observer); 2247dataPreferences.putSync('name', 'xiaohong'); 2248dataPreferences.putSync('weight', 125); 2249dataPreferences.flush((err: BusinessError) => { 2250 if (err) { 2251 console.error("Failed to flush. Cause: " + err); 2252 return; 2253 } 2254 console.info("Succeeded in flushing."); 2255}) 2256dataPreferences.off('dataChange', keys, observer); 2257``` 2258 2259## ValueType 2260 2261type ValueType = number | string | boolean | Array\<number> | Array\<string> | Array\<boolean> | Uint8Array | object | bigint 2262 2263用于表示允许的数据字段类型。 2264 2265**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2266 2267**系统能力：** SystemCapability.DistributedDataManager.Preferences.Core 2268 2269| 类型 | 说明 | 2270|--------------------------|-------------------| 2271| number | 表示值类型为数字。 | 2272| string | 表示值类型为字符串。 | 2273| boolean | 表示值类型为布尔值。 | 2274| Array\<number> | 表示值类型为数字类型的数组。 | 2275| Array\<boolean> | 表示值类型为布尔类型的数组。 | 2276| Array\<string> | 表示值类型为字符串类型的数组。 | 2277| Uint8Array<sup>11+</sup> | 表示值类型为8位无符号整型的数组。 | 2278| object<sup>12+</sup> | 表示值类型为对象。 | 2279| bigint<sup>12+</sup> | 表示值类型为任意精度格式的整数。 | 2280