往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)
- 鸿蒙开发核心知识点,看这篇文章就够了
- 最新版!鸿蒙HarmonyOS Next应用开发实战学习路线
- 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南
- 鸿蒙应用开发实战项目,看这一篇文章就够了(部分项目附源码)
@ohos.data.preferences (用户首选项)
用户首选项为应用提供Key-Value键值型的数据处理能力,支持应用长期化轻量级数据,并对其修改和查询。
数据存储形式为键值对,键的类型为字符串型,值的存储数据类型包罗数字型、字符型、布尔型以及这3种类型的数组类型。
用户首选项的长期化文件存储在preferencesDir路径下,创建preferences对象前,需要保证preferencesDir路径可读写。
阐明
本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
首选项无法保证进程并发安全,会有文件损坏和数据丢失的风险,不支持在多进程场景下使用。
导入模块
- 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模子示例:
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let dataPreferences: preferences.Preferences | null = null;
- preferences.getPreferences(context, 'myStore', (err: BusinessError, val: preferences.Preferences) => {
- if (err) {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- dataPreferences = val;
- console.info("Succeeded in getting preferences.");
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- let dataPreferences: preferences.Preferences | null = null;
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- preferences.getPreferences(this.context, 'myStore', (err: BusinessError, val: preferences.Preferences) => {
- if (err) {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- dataPreferences = val;
- console.info("Succeeded in getting preferences.");
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let dataPreferences: preferences.Preferences | null = null;
- let promise = preferences.getPreferences(context, 'myStore');
- promise.then((object: preferences.Preferences) => {
- dataPreferences = object;
- console.info("Succeeded in getting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- let dataPreferences: preferences.Preferences | null = null;
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let promise = preferences.getPreferences(this.context, 'myStore');
- promise.then((object: preferences.Preferences) => {
- dataPreferences = object;
- console.info("Succeeded in getting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let dataPreferences: preferences.Preferences | null = null;
- let options: preferences.Options = { name: 'myStore' };
- preferences.getPreferences(context, options, (err: BusinessError, val: preferences.Preferences) => {
- if (err) {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- dataPreferences = val;
- console.info("Succeeded in getting preferences.");
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- let dataPreferences: preferences.Preferences | null = null;
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- preferences.getPreferences(this.context, options, (err: BusinessError, val: preferences.Preferences) => {
- if (err) {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- dataPreferences = val;
- console.info("Succeeded in getting preferences.");
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let dataPreferences: preferences.Preferences | null = null;
- let options: preferences.Options = { name: 'myStore' };
- let promise = preferences.getPreferences(context, options);
- promise.then((object: preferences.Preferences) => {
- dataPreferences = object;
- console.info("Succeeded in getting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- let dataPreferences: preferences.Preferences | null = null;
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- let promise = preferences.getPreferences(this.context, options);
- promise.then((object: preferences.Preferences) => {
- dataPreferences = object;
- console.info("Succeeded in getting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to get preferences. code =" + err.code + ", message =" + err.message);
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- let context = featureAbility.getContext();
- let dataPreferences: preferences.Preferences | null = null;
- let options: preferences.Options = { name: 'myStore' };
- dataPreferences = preferences.getPreferencesSync(context, options);
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { window } from '@kit.ArkUI';
- let dataPreferences: preferences.Preferences | null = null;
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- dataPreferences = preferences.getPreferencesSync(this.context, options);
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- preferences.deletePreferences(context, 'myStore', (err: BusinessError) => {
- if (err) {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in deleting preferences.");
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- preferences.deletePreferences(this.context, 'myStore', (err: BusinessError) => {
- if (err) {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in deleting preferences.");
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let promise = preferences.deletePreferences(context, 'myStore');
- promise.then(() => {
- console.info("Succeeded in deleting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let promise = preferences.deletePreferences(this.context, 'myStore');
- promise.then(() => {
- console.info("Succeeded in deleting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let options: preferences.Options = { name: 'myStore' };
- preferences.deletePreferences(context, options, (err: BusinessError) => {
- if (err) {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in deleting preferences.");
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- preferences.deletePreferences(this.context, options, (err: BusinessError) => {
- if (err) {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in deleting preferences.");
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let options: preferences.Options = { name: 'myStore' };
- let promise = preferences.deletePreferences(context, options);
- promise.then(() => {
- console.info("Succeeded in deleting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- let promise = preferences.deletePreferences(this.context, options);
- promise.then(() => {
- console.info("Succeeded in deleting preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to delete preferences. code =" + err.code + ", message =" + err.message);
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- preferences.removePreferencesFromCache(context, 'myStore', (err: BusinessError) => {
- if (err) {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in removing preferences.");
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- preferences.removePreferencesFromCache(this.context, 'myStore', (err: BusinessError) => {
- if (err) {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in removing preferences.");
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let promise = preferences.removePreferencesFromCache(context, 'myStore');
- promise.then(() => {
- console.info("Succeeded in removing preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let promise = preferences.removePreferencesFromCache(this.context, 'myStore');
- promise.then(() => {
- console.info("Succeeded in removing preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- let context = featureAbility.getContext();
- preferences.removePreferencesFromCacheSync(context, 'myStore');
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- preferences.removePreferencesFromCacheSync(this.context, 'myStore');
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let options: preferences.Options = { name: 'myStore' };
- preferences.removePreferencesFromCache(context, options, (err: BusinessError) => {
- if (err) {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in removing preferences.");
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- preferences.removePreferencesFromCache(this.context, options, (err: BusinessError) => {
- if (err) {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in removing preferences.");
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- let context = featureAbility.getContext();
- let options: preferences.Options = { name: 'myStore' };
- let promise = preferences.removePreferencesFromCache(context, options);
- promise.then(() => {
- console.info("Succeeded in removing preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- })
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { BusinessError } from '@kit.BasicServicesKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- let promise = preferences.removePreferencesFromCache(this.context, options);
- promise.then(() => {
- console.info("Succeeded in removing preferences.");
- }).catch((err: BusinessError) => {
- console.error("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
- })
- }
- }
复制代码 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模子示例:
- // 获取context
- import { featureAbility } from '@kit.AbilityKit';
- let context = featureAbility.getContext();
- let options: preferences.Options = { name: 'myStore' };
- preferences.removePreferencesFromCacheSync(context, options);
复制代码 Stage模子示例:
- import { UIAbility } from '@kit.AbilityKit';
- import { window } from '@kit.ArkUI';
- class EntryAbility extends UIAbility {
- onWindowStageCreate(windowStage: window.WindowStage) {
- let options: preferences.Options = { name: 'myStore' };
- preferences.removePreferencesFromCacheSync(this.context, options);
- }
- }
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- dataPreferences.get('startup', 'default', (err: BusinessError, val: preferences.ValueType) => {
- if (err) {
- console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in getting value of 'startup'. val: " + val);
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let promise = dataPreferences.get('startup', 'default');
- promise.then((data: preferences.ValueType) => {
- console.info("Succeeded in getting value of 'startup'. Data: " + data);
- }).catch((err: BusinessError) => {
- console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
- })
复制代码 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. 示例:
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- // 由于ArkTS中无Object.keys,且无法使用for..in...
- // 若报ArkTS问题,请将此方法单独抽离至一个ts文件中并暴露,在需要用到的ets文件中引入使用
- function getObjKeys(obj: Object): string[] {
- let keys = Object.keys(obj);
- return keys;
- }
- dataPreferences.getAll((err: BusinessError, value: Object) => {
- if (err) {
- console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
- return;
- }
- let allKeys = getObjKeys(value);
- console.info("getAll keys = " + allKeys);
- console.info("getAll object = " + JSON.stringify(value));
- })
复制代码 getAll
getAll(): Promise<Object>
从缓存的Preferences实例中获取所有键值数据。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Promise<Object>Promise对象,返回含有所有键值数据。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- // 由于ArkTS中无Object.keys,且无法使用for..in...
- // 若报ArkTS问题,请将此方法单独抽离至一个ts文件中并暴露,在需要用到的ets文件中引入使用
- function getObjKeys(obj: Object): string[] {
- let keys = Object.keys(obj);
- return keys;
- }
- let promise = dataPreferences.getAll();
- promise.then((value: Object) => {
- let allKeys = getObjKeys(value);
- console.info('getAll keys = ' + allKeys);
- console.info("getAll object = " + JSON.stringify(value));
- }).catch((err: BusinessError) => {
- console.error("Failed to get all key-values. code =" + err.code + ", message =" + err.message);
- })
复制代码 getAllSync10+
getAllSync(): Object
从缓存的Preferences实例中获取所有键值数据,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Object返回含有所有键值数据。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
- // 由于ArkTS中无Object.keys,且无法使用for..in...
- // 若报ArkTS问题,请将此方法单独抽离至一个ts文件中并暴露,在需要用到的ets文件中引入使用
- function getObjKeys(obj: Object): string[] {
- let keys = Object.keys(obj);
- return keys;
- }
- let value = dataPreferences.getAllSync();
- let allKeys = getObjKeys(value);
- console.info('getAll keys = ' + allKeys);
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- dataPreferences.put('startup', 'auto', (err: BusinessError) => {
- if (err) {
- console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in putting value of 'startup'.");
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let promise = dataPreferences.put('startup', 'auto');
- promise.then(() => {
- console.info("Succeeded in putting value of 'startup'.");
- }).catch((err: BusinessError) => {
- console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
- })
复制代码 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. 示例:
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- dataPreferences.has('startup', (err: BusinessError, val: boolean) => {
- if (err) {
- console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
- return;
- }
- if (val) {
- console.info("The key 'startup' is contained.");
- } else {
- console.info("The key 'startup' dose not contain.");
- }
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let promise = dataPreferences.has('startup');
- promise.then((val: boolean) => {
- if (val) {
- console.info("The key 'startup' is contained.");
- } else {
- console.info("The key 'startup' dose not contain.");
- }
- }).catch((err: BusinessError) => {
- console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
- })
复制代码 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. 示例:
- let isExist: boolean = dataPreferences.hasSync('startup');
- if (isExist) {
- console.info("The key 'startup' is contained.");
- } else {
- console.info("The key 'startup' dose not contain.");
- }
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- dataPreferences.delete('startup', (err: BusinessError) => {
- if (err) {
- console.error("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in deleting the key 'startup'.");
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let promise = dataPreferences.delete('startup');
- promise.then(() => {
- console.info("Succeeded in deleting the key 'startup'.");
- }).catch((err: BusinessError) => {
- console.error("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message);
- })
复制代码 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. 示例:
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in flushing.");
- })
复制代码 flush
flush(): Promise<void>
将缓存的Preferences实例中的数据异步存储到用户首选项的长期化文件中,使用Promise异步回调。
阐明
当数据未修改或修改后的数据与缓存数据同等时,不会刷新长期化文件。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let promise = dataPreferences.flush();
- promise.then(() => {
- console.info("Succeeded in flushing.");
- }).catch((err: BusinessError) => {
- console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
- })
复制代码 flushSync14+
flushSync(): void
将缓存的Preferences实例中的数据存储到用户首选项的长期化文件中。
阐明
当数据未修改或修改后的数据与缓存数据同等时,不会刷新长期化文件。
元服务API: 从API version 14开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- dataPreferences.clear((err: BusinessError) =>{
- if (err) {
- console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
- return;
- }
- console.info("Succeeded in clearing.");
- })
复制代码 clear
clear(): Promise<void>
扫除缓存的Preferences实例中的所有数据,可通过flush将Preferences实例长期化,使用Promise异步回调。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
返回值:
类型阐明Promise<void>无返回结果的Promise对象。 错误码:
以下错误码的具体先容。
错误码ID错误信息15500000Inner error. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let promise = dataPreferences.clear();
- promise.then(() => {
- console.info("Succeeded in clearing.");
- }).catch((err: BusinessError) => {
- console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
- })
复制代码 clearSync10+
clearSync(): void
扫除缓存的Preferences实例中的所有数据,可通过flush将Preferences实例长期化,此为同步接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
体系能力: SystemCapability.DistributedDataManager.Preferences.Core
示例:
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let observer = (key: string) => {
- console.info("The key " + key + " changed.");
- }
- dataPreferences.on('change', observer);
- dataPreferences.putSync('startup', 'manual');
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. Cause: " + err);
- return;
- }
- console.info("Succeeded in flushing.");
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let observer = (key: string) => {
- console.info("The key " + key + " changed.");
- }
- dataPreferences.on('multiProcessChange', observer);
- dataPreferences.putSync('startup', 'manual');
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. Cause: " + err);
- return;
- }
- console.info("Succeeded in flushing.");
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let observer = (data: Record<string, preferences.ValueType>) => {
- for (const keyValue of Object.entries(data)) {
- console.info(`observer : ${keyValue}`)
- }
- console.info("The observer called.")
- }
- let keys = ['name', 'age']
- dataPreferences.on('dataChange', keys, observer);
- dataPreferences.putSync('name', 'xiaohong');
- dataPreferences.putSync('weight', 125);
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. Cause: " + err);
- return;
- }
- console.info("Succeeded in flushing.");
- })
复制代码 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let observer = (key: string) => {
- console.info("The key " + key + " changed.");
- }
- dataPreferences.on('change', observer);
- dataPreferences.putSync('startup', 'auto');
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. Cause: " + err);
- return;
- }
- console.info("Succeeded in flushing.");
- })
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let observer = (key: string) => {
- console.info("The key " + key + " changed.");
- }
- dataPreferences.on('multiProcessChange', observer);
- dataPreferences.putSync('startup', 'auto');
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. Cause: " + err);
- return;
- }
- console.info("Succeeded in flushing.");
- })
- 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. 示例:
- import { BusinessError } from '@kit.BasicServicesKit';
- let observer = (data: Record<string, preferences.ValueType>) => {
- for (const keyValue of Object.entries(data)) {
- console.info(`observer : ${keyValue}`)
- }
- console.info("The observer called.")
- }
- let keys = ['name', 'age']
- dataPreferences.on('dataChange', keys, observer);
- dataPreferences.putSync('name', 'xiaohong');
- dataPreferences.putSync('weight', 125);
- dataPreferences.flush((err: BusinessError) => {
- if (err) {
- console.error("Failed to flush. Cause: " + err);
- return;
- }
- console.info("Succeeded in flushing.");
- })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企服之家,中国第一个企服评测及商务社交产业平台。 |