鸿蒙NEXT开发:ArkData数据管理-@ohos.data.preferences (用户首选项) ...

打印 上一主题 下一主题

主题 959|帖子 959|积分 2877

 往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)



  • 鸿蒙开发核心知识点,看这篇文章就够了
  • 最新版!鸿蒙HarmonyOS Next应用开发实战学习路线
  • 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南
  • 鸿蒙应用开发实战项目,看这一篇文章就够了(部分项目附源码)

@ohos.data.preferences (用户首选项)

用户首选项为应用提供Key-Value键值型的数据处理能力,支持应用长期化轻量级数据,并对其修改和查询。
数据存储形式为键值对,键的类型为字符串型,值的存储数据类型包罗数字型、字符型、布尔型以及这3种类型的数组类型。
用户首选项的长期化文件存储在preferencesDir路径下,创建preferences对象前,需要保证preferencesDir路径可读写。
   阐明
  本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
  首选项无法保证进程并发安全,会有文件损坏和数据丢失的风险,不支持在多进程场景下使用。
  导入模块

  1. import { preferences } from '@kit.ArkData';
复制代码
常量

元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
名称参数类型可读可写阐明MAX_KEY_LENGTHnumber是否Key的最大长度限制为1024个字节。MAX_VALUE_LENGTHnumber是否Value的最大长度限制为16MB。 preferences.getPreferences

getPreferences(context: Context, name: string, callback: AsyncCallback<references>): void
获取Preferences实例,使用callback异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。callbackAsyncCallback<references>是回调函数。当获取Preferences实例乐成,err为undefined,返回Preferences实例;否则err为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
FA模子示例:
  1. import { featureAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. let context = featureAbility.getContext();
  4. let dataPreferences: preferences.Preferences | null = null;
  5. preferences.getPreferences(context, 'myStore', (err: BusinessError, val: preferences.Preferences) => {
  6.   if (err) {
  7.     console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  8.     return;
  9.   }
  10.   dataPreferences = val;
  11.   console.info("Succeeded in getting preferences.");
  12. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. let dataPreferences: preferences.Preferences | null = null;
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     preferences.getPreferences(this.context, 'myStore', (err: BusinessError, val: preferences.Preferences) => {
  8.       if (err) {
  9.         console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  10.         return;
  11.       }
  12.       dataPreferences = val;
  13.       console.info("Succeeded in getting preferences.");
  14.     })
  15.   }
  16. }
复制代码
preferences.getPreferences

getPreferences(context: Context, name: string): Promise<references>
获取Preferences实例,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 返回值:
类型阐明Promise<references>Promise对象,返回Preferences实例。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let dataPreferences: preferences.Preferences | null = null;
  6. let promise = preferences.getPreferences(context, 'myStore');
  7. promise.then((object: preferences.Preferences) => {
  8.   dataPreferences = object;
  9.   console.info("Succeeded in getting preferences.");
  10. }).catch((err: BusinessError) => {
  11.   console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  12. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. let dataPreferences: preferences.Preferences | null = null;
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let promise = preferences.getPreferences(this.context, 'myStore');
  8.     promise.then((object: preferences.Preferences) => {
  9.       dataPreferences = object;
  10.       console.info("Succeeded in getting preferences.");
  11.     }).catch((err: BusinessError) => {
  12.       console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  13.     })
  14.   }
  15. }
复制代码
preferences.getPreferences10+

getPreferences(context: Context, options: Options, callback: AsyncCallback<references>): void
获取Preferences实例,使用callback异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。callbackAsyncCallback<references>是回调函数。当获取Preferences实例乐成,err为undefined,返回Preferences实例;否则err为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let dataPreferences: preferences.Preferences | null = null;
  6. let options: preferences.Options = { name: 'myStore' };
  7. preferences.getPreferences(context, options, (err: BusinessError, val: preferences.Preferences) => {
  8.   if (err) {
  9.     console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  10.     return;
  11.   }
  12.   dataPreferences = val;
  13.   console.info("Succeeded in getting preferences.");
  14. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. let dataPreferences: preferences.Preferences | null = null;
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let options: preferences.Options = { name: 'myStore' };
  8.     preferences.getPreferences(this.context, options, (err: BusinessError, val: preferences.Preferences) => {
  9.       if (err) {
  10.         console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  11.         return;
  12.       }
  13.       dataPreferences = val;
  14.       console.info("Succeeded in getting preferences.");
  15.     })
  16.   }
  17. }
复制代码
preferences.getPreferences10+

getPreferences(context: Context, options: Options): Promise<references>
获取Preferences实例,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值:
类型阐明Promise<references>Promise对象,返回Preferences实例。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let dataPreferences: preferences.Preferences | null = null;
  6. let options: preferences.Options = { name: 'myStore' };
  7. let promise = preferences.getPreferences(context, options);
  8. promise.then((object: preferences.Preferences) => {
  9.   dataPreferences = object;
  10.   console.info("Succeeded in getting preferences.");
  11. }).catch((err: BusinessError) => {
  12.   console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  13. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. let dataPreferences: preferences.Preferences | null = null;
  5. class EntryAbility extends UIAbility {
  6.   onWindowStageCreate(windowStage: window.WindowStage) {
  7.     let options: preferences.Options = { name: 'myStore' };
  8.     let promise = preferences.getPreferences(this.context, options);
  9.     promise.then((object: preferences.Preferences) => {
  10.       dataPreferences = object;
  11.       console.info("Succeeded in getting preferences.");
  12.     }).catch((err: BusinessError) => {
  13.       console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
  14.     })
  15.   }
  16. }
复制代码
preferences.getPreferencesSync10+

getPreferencesSync(context: Context, options: Options): Preferences
获取Preferences实例,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值:
类型阐明Preferences返回Preferences实例。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. let context = featureAbility.getContext();
  4. let dataPreferences: preferences.Preferences | null = null;
  5. let options: preferences.Options = { name: 'myStore' };
  6. dataPreferences = preferences.getPreferencesSync(context, options);
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { window } from '@kit.ArkUI';
  3. let dataPreferences: preferences.Preferences | null = null;
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let options: preferences.Options = { name: 'myStore' };
  7.     dataPreferences = preferences.getPreferencesSync(this.context, options);
  8.   }
  9. }
复制代码
preferences.deletePreferences

deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例,若Preferences实例有对应的长期化文件,则同时删除其长期化文件。使用callback异步回调。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。callbackAsyncCallback<void>是回调函数。当移除乐成,err为undefined,否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error.15500010Failed to delete the user preferences persistence file. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. preferences.deletePreferences(context, 'myStore', (err: BusinessError) => {
  6.   if (err) {
  7.     console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  8.     return;
  9.   }
  10.   console.info("Succeeded in deleting preferences.");
  11. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     preferences.deletePreferences(this.context, 'myStore', (err: BusinessError) => {
  7.       if (err) {
  8.         console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  9.         return;
  10.       }
  11.       console.info("Succeeded in deleting preferences.");
  12.     })
  13.   }
  14. }
复制代码
preferences.deletePreferences

deletePreferences(context: Context, name: string): Promise<void>
从缓存中移出指定的Preferences实例,若Preferences实例有对应的长期化文件,则同时删除其长期化文件。使用Promise异步回调。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error.15500010Failed to delete the user preferences persistence file. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let promise = preferences.deletePreferences(context, 'myStore');
  6. promise.then(() => {
  7.   console.info("Succeeded in deleting preferences.");
  8. }).catch((err: BusinessError) => {
  9.   console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  10. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let promise = preferences.deletePreferences(this.context, 'myStore');
  7.     promise.then(() => {
  8.       console.info("Succeeded in deleting preferences.");
  9.     }).catch((err: BusinessError) => {
  10.       console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  11.     })
  12.   }
  13. }
复制代码
preferences.deletePreferences10+

deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例,若Preferences实例有对应的长期化文件,则同时删除其长期化文件。使用callback异步回调。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。callbackAsyncCallback<void>是回调函数。当移除乐成,err为undefined,否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15500010Failed to delete the user preferences persistence file.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let options: preferences.Options = { name: 'myStore' };
  6. preferences.deletePreferences(context, options, (err: BusinessError) => {
  7.   if (err) {
  8.     console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  9.     return;
  10.   }
  11.   console.info("Succeeded in deleting preferences.");
  12. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let options: preferences.Options = { name: 'myStore' };
  7.     preferences.deletePreferences(this.context, options, (err: BusinessError) => {
  8.       if (err) {
  9.         console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  10.         return;
  11.       }
  12.       console.info("Succeeded in deleting preferences.");
  13.     })
  14.   }
  15. }
复制代码
preferences.deletePreferences10+

deletePreferences(context: Context, options: Options): Promise<void>
从缓存中移出指定的Preferences实例,若Preferences实例有对应的长期化文件,则同时删除其长期化文件。使用Promise异步回调。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
不支持该接口与preference其他接口并发调用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15500010Failed to delete the user preferences persistence file.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let options: preferences.Options = { name: 'myStore' };
  6. let promise = preferences.deletePreferences(context, options);
  7. promise.then(() => {
  8.   console.info("Succeeded in deleting preferences.");
  9. }).catch((err: BusinessError) => {
  10.   console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  11. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let options: preferences.Options = { name: 'myStore' };
  7.     let promise = preferences.deletePreferences(this.context, options);
  8.     promise.then(() => {
  9.       console.info("Succeeded in deleting preferences.");
  10.     }).catch((err: BusinessError) => {
  11.       console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
  12.     })
  13.   }
  14. }
复制代码
preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例,使用callback异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后,该实例会被会被缓存起来,后续再次getPreferences时不会再次从长期化文件中读取,直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后,再次getPreferences将会重新读取长期化文件,天生新的Preferences实例。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。callbackAsyncCallback<void>是回调函数。当移除乐成,err为undefined,否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. preferences.removePreferencesFromCache(context, 'myStore', (err: BusinessError) => {
  6.   if (err) {
  7.     console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  8.     return;
  9.   }
  10.   console.info("Succeeded in removing preferences.");
  11. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     preferences.removePreferencesFromCache(this.context, 'myStore', (err: BusinessError) => {
  7.       if (err) {
  8.         console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  9.         return;
  10.       }
  11.       console.info("Succeeded in removing preferences.");
  12.     })
  13.   }
  14. }
复制代码
preferences.removePreferencesFromCache

removePreferencesFromCache(context: Context, name: string): Promise<void>
从缓存中移出指定的Preferences实例,使用Promise异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后,该实例会被会被缓存起来,后续再次getPreferences时不会再次从长期化文件中读取,直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后,再次getPreferences将会重新读取长期化文件,天生新的Preferences实例。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let promise = preferences.removePreferencesFromCache(context, 'myStore');
  6. promise.then(() => {
  7.   console.info("Succeeded in removing preferences.");
  8. }).catch((err: BusinessError) => {
  9.   console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  10. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let promise = preferences.removePreferencesFromCache(this.context, 'myStore');
  7.     promise.then(() => {
  8.       console.info("Succeeded in removing preferences.");
  9.     }).catch((err: BusinessError) => {
  10.       console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  11.     })
  12.   }
  13. }
复制代码
preferences.removePreferencesFromCacheSync10+

removePreferencesFromCacheSync(context: Context, name: string): void
从缓存中移出指定的Preferences实例,此为同步接口。
应用初次调用getPreferences接口获取某个Preferences实例后,该实例会被会被缓存起来,后续再次getPreferences时不会再次从长期化文件中读取,直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后,再次getPreferences将会重新读取长期化文件,天生新的Preferences实例。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
namestring是Preferences实例的名称。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. let context = featureAbility.getContext();
  4. preferences.removePreferencesFromCacheSync(context, 'myStore');
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { window } from '@kit.ArkUI';
  3. class EntryAbility extends UIAbility {
  4.   onWindowStageCreate(windowStage: window.WindowStage) {
  5.     preferences.removePreferencesFromCacheSync(this.context, 'myStore');
  6.   }
  7. }
复制代码
preferences.removePreferencesFromCache10+

removePreferencesFromCache(context: Context, options: Options, callback: AsyncCallback<void>): void
从缓存中移出指定的Preferences实例,使用callback异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后,该实例会被会被缓存起来,后续再次getPreferences时不会再次从长期化文件中读取,直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后,再次getPreferences将会重新读取长期化文件,天生新的Preferences实例。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。callbackAsyncCallback<void>是回调函数。当移除乐成,err为undefined,否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let options: preferences.Options = { name: 'myStore' };
  6. preferences.removePreferencesFromCache(context, options, (err: BusinessError) => {
  7.   if (err) {
  8.     console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  9.     return;
  10.   }
  11.   console.info("Succeeded in removing preferences.");
  12. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let options: preferences.Options = { name: 'myStore' };
  7.     preferences.removePreferencesFromCache(this.context, options, (err: BusinessError) => {
  8.       if (err) {
  9.         console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  10.         return;
  11.       }
  12.       console.info("Succeeded in removing preferences.");
  13.     })
  14.   }
  15. }
复制代码
preferences.removePreferencesFromCache10+

removePreferencesFromCache(context: Context, options: Options): Promise<void>
从缓存中移出指定的Preferences实例,使用Promise异步回调。
应用初次调用getPreferences接口获取某个Preferences实例后,该实例会被会被缓存起来,后续再次getPreferences时不会再次从长期化文件中读取,直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后,再次getPreferences将会重新读取长期化文件,天生新的Preferences实例。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. import { BusinessError } from '@kit.BasicServicesKit';
  4. let context = featureAbility.getContext();
  5. let options: preferences.Options = { name: 'myStore' };
  6. let promise = preferences.removePreferencesFromCache(context, options);
  7. promise.then(() => {
  8. console.info("Succeeded in removing preferences.");
  9. }).catch((err: BusinessError) => {
  10. console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  11. })
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { BusinessError } from '@kit.BasicServicesKit';
  3. import { window } from '@kit.ArkUI';
  4. class EntryAbility extends UIAbility {
  5.   onWindowStageCreate(windowStage: window.WindowStage) {
  6.     let options: preferences.Options = { name: 'myStore' };
  7.     let promise = preferences.removePreferencesFromCache(this.context, options);
  8.     promise.then(() => {
  9.       console.info("Succeeded in removing preferences.");
  10.     }).catch((err: BusinessError) => {
  11.       console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
  12.     })
  13.   }
  14. }
复制代码
preferences.removePreferencesFromCacheSync10+

removePreferencesFromCacheSync(context: Context, options: Options):void
从缓存中移出指定的Preferences实例,此为同步接口。
应用初次调用getPreferences接口获取某个Preferences实例后,该实例会被会被缓存起来,后续再次getPreferences时不会再次从长期化文件中读取,直接从缓存中获取Preferences实例。调用此接口移出缓存中的实例之后,再次getPreferences将会重新读取长期化文件,天生新的Preferences实例。
调用该接口后,不发起再使用旧的Preferences实例举行数据利用,否则会出现数据同等性题目,应将Preferences实例置为null,体系将会同一回收。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明contextContext是 应用上下文。
FA模子的应用Context界说见Context。
Stage模子的应用Context界说见Context。
optionsOptions是与Preferences实例相关的配置选项。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
801Capability not supported.15500000Inner error.15501001The operations is supported in stage mode only.15501002Invalid dataGroupId. 示例:
FA模子示例:
  1. // 获取context
  2. import { featureAbility } from '@kit.AbilityKit';
  3. let context = featureAbility.getContext();
  4. let options: preferences.Options = { name: 'myStore' };
  5. preferences.removePreferencesFromCacheSync(context, options);
复制代码
Stage模子示例:
  1. import { UIAbility } from '@kit.AbilityKit';
  2. import { window } from '@kit.ArkUI';
  3. class EntryAbility extends UIAbility {
  4.   onWindowStageCreate(windowStage: window.WindowStage) {
  5.     let options: preferences.Options = { name: 'myStore' };
  6.     preferences.removePreferencesFromCacheSync(this.context, options);
  7.   }
  8. }
复制代码
Options10+

Preferences实例配置选项。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
名称类型必填阐明namestring是 Preferences实例的名称。名称长度需大于零且小于等于255字节,名称中不能包含'/'且不能以'/'结尾。
元服务API: 从API version 11开始,该参数支持在元服务中使用。
dataGroupIdstring|null|undefined否 应用组ID,需要向应用市场获取。基于dataGroupId的数据共享支持两种场景:1.同一应用的不同进程间共享,只支持三方应用中输入法和输入法的扩展场景使用;2.不同应用间的数据共享,只支持体系应用使用。
为可选参数。指定在此dataGroupId对应的沙箱路径下创建Preferences实例。当此参数不填时,默认在本应用沙箱目录下创建Preferences实例。
模子束缚: 此属性仅在Stage模子下可用。
元服务API: 从API version 11开始,该参数支持在元服务中使用。
  Preferences

首选项实例,提供获取和修改存储数据的接口。
下列接口都需先使用preferences.getPreferences获取到Preferences实例,再通过此实例调用对应接口。
get

get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void
从缓存的Preferences实例中获取键对应的值,假如值为null或者非默认值类型,返回默认数据defValue,使用callback异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要获取的存储Key名称,不能为空。defValueValueType是默认返回值。callbackAsyncCallback<ValueType>是回调函数。当获取乐成时,err为undefined,data为键对应的值;否则err为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. dataPreferences.get('startup', 'default', (err: BusinessError, val: preferences.ValueType) => {
  3.   if (err) {
  4.     console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
  5.     return;
  6.   }
  7.   console.info("Succeeded in getting value of 'startup'. val: " + val);
  8. })
复制代码
get

get(key: string, defValue: ValueType): Promise<ValueType>
从缓存的Preferences实例中获取键对应的值,假如值为null或者非默认值类型,返回默认数据defValue,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要获取的存储Key名称,不能为空。defValueValueType是默认返回值。 返回值:
类型阐明Promise<ValueType>Promise对象,返回键对应的值。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let promise = dataPreferences.get('startup', 'default');
  3. promise.then((data: preferences.ValueType) => {
  4.   console.info("Succeeded in getting value of 'startup'. Data: " + data);
  5. }).catch((err: BusinessError) => {
  6.   console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
  7. })
复制代码
getSync10+

getSync(key: string, defValue: ValueType): ValueType
从缓存的Preferences实例中获取键对应的值,假如值为null或者非默认值类型,返回默认数据defValue,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要获取的存储Key名称,不能为空。defValueValueType是默认返回值。 返回值:
类型阐明ValueType返回键对应的值。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. let value: preferences.ValueType = dataPreferences.getSync('startup', 'default');
复制代码
getAll

getAll(callback: AsyncCallback<Object>): void;
从缓存的Preferences实例中获取所有键值数据。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明callbackAsyncCallback<Object>是回调函数。当获取乐成,err为undefined,value为所有键值数据;否则err为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401Parameter error. Mandatory parameters are left unspecified.15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // 由于ArkTS中无Object.keys,且无法使用for..in...
  3. // 若报ArkTS问题,请将此方法单独抽离至一个ts文件中并暴露,在需要用到的ets文件中引入使用
  4. function getObjKeys(obj: Object): string[] {
  5.   let keys = Object.keys(obj);
  6.   return keys;
  7. }
  8. dataPreferences.getAll((err: BusinessError, value: Object) => {
  9.   if (err) {
  10.     console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
  11.     return;
  12.   }
  13.   let allKeys = getObjKeys(value);
  14.   console.info("getAll keys = " + allKeys);
  15.   console.info("getAll object = " + JSON.stringify(value));
  16. })
复制代码
getAll

getAll(): Promise<Object>
从缓存的Preferences实例中获取所有键值数据。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Promise<Object>Promise对象,返回含有所有键值数据。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. // 由于ArkTS中无Object.keys,且无法使用for..in...
  3. // 若报ArkTS问题,请将此方法单独抽离至一个ts文件中并暴露,在需要用到的ets文件中引入使用
  4. function getObjKeys(obj: Object): string[] {
  5.   let keys = Object.keys(obj);
  6.   return keys;
  7. }
  8. let promise = dataPreferences.getAll();
  9. promise.then((value: Object) => {
  10.   let allKeys = getObjKeys(value);
  11.   console.info('getAll keys = ' + allKeys);
  12.   console.info("getAll object = " + JSON.stringify(value));
  13. }).catch((err: BusinessError) => {
  14.   console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
  15. })
复制代码
getAllSync10+

getAllSync(): Object
从缓存的Preferences实例中获取所有键值数据,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Object返回含有所有键值数据。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
  1. // 由于ArkTS中无Object.keys,且无法使用for..in...
  2. // 若报ArkTS问题,请将此方法单独抽离至一个ts文件中并暴露,在需要用到的ets文件中引入使用
  3. function getObjKeys(obj: Object): string[] {
  4.   let keys = Object.keys(obj);
  5.   return keys;
  6. }
  7. let value = dataPreferences.getAllSync();
  8. let allKeys = getObjKeys(value);
  9. console.info('getAll keys = ' + allKeys);
  10. console.info("getAll object = " + JSON.stringify(value));
复制代码
put

put(key: string, value: ValueType, callback: AsyncCallback<void>): void
将数据写入缓存的Preferences实例中,可通过flush将Preferences实例长期化,使用callback异步回调。
   阐明
  当value中包含非UTF-8格式的字符串时,请使用Uint8Array类型存储,否则会造发展期化文件出现格式错误造成文件损坏。
  当对应的键已经存在时,put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要修改的存储的Key,不能为空。valueValueType是存储的新值。callbackAsyncCallback<void>是回调函数。当数据写入乐成,err为undefined;否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. dataPreferences.put('startup', 'auto', (err: BusinessError) => {
  3.   if (err) {
  4.     console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
  5.     return;
  6.   }
  7.   console.info("Succeeded in putting value of 'startup'.");
  8. })
复制代码
put

put(key: string, value: ValueType): Promise<void>
将数据写入缓存的Preferences实例中,可通过flush将Preferences实例长期化,使用Promise异步回调。
   阐明
  当value中包含非UTF-8格式的字符串时,请使用Uint8Array类型存储,否则会造发展期化文件出现格式错误造成文件损坏。
  当对应的键已经存在时,put()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要修改的存储的Key,不能为空。valueValueType是存储的新值。 返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let promise = dataPreferences.put('startup', 'auto');
  3. promise.then(() => {
  4.   console.info("Succeeded in putting value of 'startup'.");
  5. }).catch((err: BusinessError) => {
  6.   console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
  7. })
复制代码
putSync10+

putSync(key: string, value: ValueType): void
将数据写入缓存的Preferences实例中,可通过flush将Preferences实例长期化,此为同步接口。
   阐明
  当value中包含非UTF-8格式的字符串时,请使用Uint8Array类型存储,否则会造发展期化文件出现格式错误造成文件损坏。
  当对应的键已经存在时,putSync()方法会覆盖其值。可以使用hasSync()方法检查是否存在对应键值对。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要修改的存储的Key,不能为空。valueValueType是存储的新值。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. dataPreferences.putSync('startup', 'auto');
复制代码
has

has(key: string, callback: AsyncCallback<boolean>): void
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对,使用callback异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要检查的存储key名称,不能为空。callbackAsyncCallback<boolean>是回调函数。返回Preferences实例是否包含给定key的存储键值对,true表现存在,false表现不存在。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. dataPreferences.has('startup', (err: BusinessError, val: boolean) => {
  3.   if (err) {
  4.     console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
  5.     return;
  6.   }
  7.   if (val) {
  8.     console.info("The key 'startup' is contained.");
  9.   } else {
  10.     console.info("The key 'startup' dose not contain.");
  11.   }
  12. })
复制代码
has

has(key: string): Promise<boolean>
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要检查的存储key名称,不能为空。 返回值:
类型阐明Promise<boolean>Promise对象。返回Preferences实例是否包含给定key的存储键值对,true表现存在,false表现不存在。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let promise = dataPreferences.has('startup');
  3. promise.then((val: boolean) => {
  4.   if (val) {
  5.     console.info("The key 'startup' is contained.");
  6.   } else {
  7.     console.info("The key 'startup' dose not contain.");
  8.   }
  9. }).catch((err: BusinessError) => {
  10.   console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
  11. })
复制代码
hasSync10+

hasSync(key: string): boolean
检查缓存的Preferences实例中是否包含名为给定Key的存储键值对,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要检查的存储key名称,不能为空。 返回值:
类型阐明boolean返回Preferences实例是否包含给定key的存储键值对,true表现存在,false表现不存在。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. let isExist: boolean = dataPreferences.hasSync('startup');
  2. if (isExist) {
  3.   console.info("The key 'startup' is contained.");
  4. } else {
  5.   console.info("The key 'startup' dose not contain.");
  6. }
复制代码
delete

delete(key: string, callback: AsyncCallback<void>): void
从缓存的Preferences实例中删除名为给定Key的存储键值对,可通过flush将Preferences实例长期化,使用callback异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要删除的存储Key名称,不能为空。callbackAsyncCallback<void>是回调函数。当删除乐成,err为undefined;否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. dataPreferences.delete('startup', (err: BusinessError) => {
  3.   if (err) {
  4.     console.error("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message);
  5.     return;
  6.   }
  7.   console.info("Succeeded in deleting the key 'startup'.");
  8. })
复制代码
delete

delete(key: string): Promise<void>
从缓存的Preferences实例中删除名为给定Key的存储键值对,可通过flush将Preferences实例长期化,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要删除的存储key名称,不能为空。 返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let promise = dataPreferences.delete('startup');
  3. promise.then(() => {
  4.   console.info("Succeeded in deleting the key 'startup'.");
  5. }).catch((err: BusinessError) => {
  6.   console.error("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message);
  7. })
复制代码
deleteSync10+

deleteSync(key: string): void
从缓存的Preferences实例中删除名为给定Key的存储键值对,可通过flush将Preferences实例长期化,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明keystring是要删除的存储key名称,不能为空。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. dataPreferences.deleteSync('startup');
复制代码
flush

flush(callback: AsyncCallback<void>): void
   阐明
  当数据未修改或修改后的数据与缓存数据同等时,不会刷新长期化文件。
  将缓存的Preferences实例中的数据异步存储到用户首选项的长期化文件中,使用callback异步回调。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明callbackAsyncCallback<void>是回调函数。当保存乐成,err为undefined;否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401Parameter error. Mandatory parameters are left unspecified.15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. dataPreferences.flush((err: BusinessError) => {
  3.   if (err) {
  4.     console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
  5.     return;
  6.   }
  7.   console.info("Succeeded in flushing.");
  8. })
复制代码
flush

flush(): Promise<void>
将缓存的Preferences实例中的数据异步存储到用户首选项的长期化文件中,使用Promise异步回调。
   阐明
  当数据未修改或修改后的数据与缓存数据同等时,不会刷新长期化文件。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let promise = dataPreferences.flush();
  3. promise.then(() => {
  4.   console.info("Succeeded in flushing.");
  5. }).catch((err: BusinessError) => {
  6.   console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
  7. })
复制代码
flushSync14+

flushSync(): void
将缓存的Preferences实例中的数据存储到用户首选项的长期化文件中。
   阐明
  当数据未修改或修改后的数据与缓存数据同等时,不会刷新长期化文件。
  元服务API: 从API version 14开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
  1. dataPreferences.flushSync();
复制代码
clear

clear(callback: AsyncCallback<void>): void
扫除缓存的Preferences实例中的所有数据,可通过flush将Preferences实例长期化,使用callback异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明callbackAsyncCallback<void>是回调函数。当扫除乐成,err为undefined;否则为错误对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息401Parameter error. Mandatory parameters are left unspecified.15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. dataPreferences.clear((err: BusinessError) =>{
  3.   if (err) {
  4.     console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
  5.     return;
  6.   }
  7.   console.info("Succeeded in clearing.");
  8. })
复制代码
clear

clear(): Promise<void>
扫除缓存的Preferences实例中的所有数据,可通过flush将Preferences实例长期化,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let promise = dataPreferences.clear();
  3. promise.then(() => {
  4.   console.info("Succeeded in clearing.");
  5. }).catch((err: BusinessError) => {
  6.   console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
  7. })
复制代码
clearSync10+

clearSync(): void
扫除缓存的Preferences实例中的所有数据,可通过flush将Preferences实例长期化,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
示例:
  1. dataPreferences.clearSync();
复制代码
on('change')

on(type: 'change', callback: Callback<string>): void
订阅数据变更,订阅的Key的值发生变更后,在实行flush方法后,触发callback回调。
   阐明
  当调用removePreferencesFromCache或者deletePreferences后,订阅的数据变更会自动取消订阅,在重新getPreferences后需要重新订阅数据变更。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明typestring是事件类型,固定值'change',表现数据变更。callbackCallback<string>是回调函数。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let observer = (key: string) => {
  3.   console.info("The key " + key + " changed.");
  4. }
  5. dataPreferences.on('change', observer);
  6. dataPreferences.putSync('startup', 'manual');
  7. dataPreferences.flush((err: BusinessError) => {
  8.   if (err) {
  9.     console.error("Failed to flush. Cause: " + err);
  10.     return;
  11.   }
  12.   console.info("Succeeded in flushing.");
  13. })
复制代码
on('multiProcessChange')10+

on(type: 'multiProcessChange', callback: Callback<string>): void
订阅进程间数据变更,多个进程持有同一个首选项文件时,在恣意一个进程(包罗本进程)实行flush方法,长期化文件发生变更后,触发callback回调。
本接口提供给申请了dataGroupId的应用举利用用,未申请的应用不推荐使用,多进程利用可能会损坏长期化文件,导致数据丢失。
   阐明
  同一长期化文件在当前进程订阅进程间数据变更的最大数目为50次,凌驾最大限制后会订阅失败。发起在触发callback回调后及时取消订阅。
  当调用removePreferencesFromCache或者deletePreferences后,订阅的数据变更会自动取消订阅,在重新getPreferences后需要重新订阅数据变更。
  元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明typestring是事件类型,固定值'multiProcessChange',表现多进程间的数据变更。callbackCallback<string>是回调函数。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error.15500019Failed to obtain the subscription service. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let observer = (key: string) => {
  3.   console.info("The key " + key + " changed.");
  4. }
  5. dataPreferences.on('multiProcessChange', observer);
  6. dataPreferences.putSync('startup', 'manual');
  7. dataPreferences.flush((err: BusinessError) => {
  8.   if (err) {
  9.     console.error("Failed to flush. Cause: " + err);
  10.     return;
  11.   }
  12.   console.info("Succeeded in flushing.");
  13. })
复制代码
on('dataChange')12+

on(type: 'dataChange', keys: Array<string>, callback: Callback<Record<string, ValueType>>): void
精确订阅数据变更,只有被订阅的key值发生变更后,在实行flush方法后,触发callback回调。
   阐明
  当调用removePreferencesFromCache或者deletePreferences后,订阅的数据变更会自动取消订阅,在重新getPreferences后需要重新订阅数据变更。
  元服务API: 从API version 12开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明typestring是事件类型,固定值'dataChange',表现精确的数据变更。keysArray<string>是需要订阅的key集合。callbackCallback<Record<string, ValueType>>是回调函数。回调支持返回多个键值对,其中键为发生变更的订阅key,值为变更后的数据:支持number、string、boolean、Array<number>、Array<string>、Array<boolean>、Uint8Array、object类型。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let observer = (data: Record<string, preferences.ValueType>) => {
  3.   for (const keyValue of Object.entries(data)) {
  4.     console.info(`observer : ${keyValue}`)
  5.   }
  6.   console.info("The observer called.")
  7. }
  8. let keys = ['name', 'age']
  9. dataPreferences.on('dataChange', keys, observer);
  10. dataPreferences.putSync('name', 'xiaohong');
  11. dataPreferences.putSync('weight', 125);
  12. dataPreferences.flush((err: BusinessError) => {
  13.   if (err) {
  14.     console.error("Failed to flush. Cause: " + err);
  15.     return;
  16.   }
  17.   console.info("Succeeded in flushing.");
  18. })
复制代码
off('change')

off(type: 'change', callback?: Callback<string>): void
取消订阅数据变更。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明typestring是事件类型,固定值'change',表现数据变更。callbackCallback<string>否需要取消的回调函数,不填写则全部取消。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let observer = (key: string) => {
  3.   console.info("The key " + key + " changed.");
  4. }
  5. dataPreferences.on('change', observer);
  6. dataPreferences.putSync('startup', 'auto');
  7. dataPreferences.flush((err: BusinessError) => {
  8.   if (err) {
  9.     console.error("Failed to flush. Cause: " + err);
  10.     return;
  11.   }
  12.   console.info("Succeeded in flushing.");
  13. })
  14. dataPreferences.off('change', observer);
复制代码
off('multiProcessChange')10+

off(type: 'multiProcessChange', callback?: Callback<string>): void
取消订阅进程间数据变更。
本接口提供给申请了dataGroupId的应用举利用用,未申请的应用不推荐使用,多进程利用可能会损坏长期化文件,导致数据丢失。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明typestring是事件类型,固定值'multiProcessChange',表现多进程间的数据变更。callbackCallback<string>否需要取消的回调函数,不填写则全部取消。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let observer = (key: string) => {
  3.   console.info("The key " + key + " changed.");
  4. }
  5. dataPreferences.on('multiProcessChange', observer);
  6. dataPreferences.putSync('startup', 'auto');
  7. dataPreferences.flush((err: BusinessError) => {
  8.   if (err) {
  9.     console.error("Failed to flush. Cause: " + err);
  10.     return;
  11.   }
  12.   console.info("Succeeded in flushing.");
  13. })
  14. dataPreferences.off('multiProcessChange', observer);
复制代码
off('dataChange')12+

off(type: 'dataChange', keys: Array<string>, callback?: Callback<Record<string, ValueType>>): void
取消精确订阅数据变更。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
参数:
参数名类型必填阐明typestring是事件类型,固定值'dataChange',表现精确的数据变更。keysArray<string>是需要取消订阅的key集合,当keys为空数组时,表现取消订阅全部key;当keys为非空数组时,表现只取消订阅key集合中的key。callbackCallback<Record<string, ValueType>>否需要取消的回调函数,若callback不填写,表现所有的callback都需要处理;若callback填写,表现只处理该callback。 错误码:
以下错误码的具体先容。
错误码ID错误信息401 Parameter error. Possible causes:
1. Mandatory parameters are left unspecified;
2. Incorrect parameter types;
3. Parameter verification failed.
15500000Inner error. 示例:
  1. import { BusinessError } from '@kit.BasicServicesKit';
  2. let observer = (data: Record<string, preferences.ValueType>) => {
  3.   for (const keyValue of Object.entries(data)) {
  4.     console.info(`observer : ${keyValue}`)
  5.   }
  6.   console.info("The observer called.")
  7. }
  8. let keys = ['name', 'age']
  9. dataPreferences.on('dataChange', keys, observer);
  10. dataPreferences.putSync('name', 'xiaohong');
  11. dataPreferences.putSync('weight', 125);
  12. dataPreferences.flush((err: BusinessError) => {
  13.   if (err) {
  14.     console.error("Failed to flush. Cause: " + err);
  15.     return;
  16.   }
  17.   console.info("Succeeded in flushing.");
  18. })dataPreferences.off('dataChange', keys, observer);
复制代码
ValueType

type ValueType = number | string | boolean | Array<number> | Array<string> | Array<boolean> | Uint8Array | object | bigint
用于表现答应的数据字段类型。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
类型阐明number表现值类型为数字。string表现值类型为字符串。boolean表现值类型为布尔值。Array<number>表现值类型为数字类型的数组。Array<boolean>表现值类型为布尔类型的数组。Array<string>表现值类型为字符串类型的数组。Uint8Array11+表现值类型为8位无符号整型的数组。object12+表现值类型为对象。bigint12+表现值类型为恣意精度格式的整数。


免责声明:如果侵犯了您的权益,请联系站长,我们会及时删除侵权内容,谢谢合作!更多信息从访问主页:qidao123.com:ToB企服之家,中国第一个企服评测及商务社交产业平台。

本帖子中包含更多资源

您需要 登录 才可以下载或查看,没有账号?立即注册

x
回复

使用道具 举报

0 个回复

倒序浏览

快速回复

您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

万有斥力

金牌会员
这个人很懒什么都没写!
快速回复 返回顶部 返回列表