harmony 鸿蒙@ohos.data.preferences (User Preferences)

2025-06-12
浏览 (3)

@ohos.data.preferences (User Preferences)

The Preferences module provides APIs for processing data in the form of key-value (KV) pairs, including querying, modifying, and persisting KV pairs.

The key is of the string type, and the value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.

The user preference persistent files are stored in the preferencesDir directory. Before creating a preferences object, ensure that the preferencesDir directory is readable and writeable. The encryption level of the persistent file directory determines the access to the files. For details, see Application File Directory and Application File Path.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Preferences are not thread-safe and may cause file damage and data loss when used in multi-process scenarios. Do not use preferences in multi-process scenarios.

Modules to Import

import { preferences } from '@kit.ArkData';

Constants

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Name	Type	Readable	Writable	Description
MAX_KEY_LENGTH	number	Yes	No	Maximum key length, which is 1024 bytes.
MAX_VALUE_LENGTH	number	Yes	No	Maximum value length, which is 16 MB.

preferences.getPreferences

getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void

Obtains a Preferences instance. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.
callback	AsyncCallback<Preferences>	Yes	Callback used to return the result. If the operation is successful, err is undefined and the Preferences instance obtained is returned. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

FA model:

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 model:

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<Preferences>

Obtains a Preferences instance. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.

Return value

Type	Description
Promise<Preferences>	Promise used to return the Preferences instance obtained.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

FA model:

// Obtain the 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 model:

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.getPreferences¹⁰⁺

getPreferences(context: Context, options: Options, callback: AsyncCallback<Preferences>): void

Obtains a Preferences instance. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.
callback	AsyncCallback<Preferences>	Yes	Callback used to return the result. If the operation is successful, err is undefined and the Preferences instance obtained is returned. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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.getPreferences¹⁰⁺

getPreferences(context: Context, options: Options): Promise<Preferences>

Obtains a Preferences instance. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.

Return value

Type	Description
Promise<Preferences>	Promise used to return the Preferences instance obtained.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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.getPreferencesSync¹⁰⁺

getPreferencesSync(context: Context, options: Options): Preferences

Obtains a Preferences instance. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.

Return value

Type	Description
Preferences	Preferences instance obtained.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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

Deletes a Preferences instance from the cache. If the Preferences instance has a persistent file, the persistent file will also be deleted. This API uses an asynchronous callback to return the result.

Avoid using a deleted Preferences instance to perform data operations, which may cause data inconsistency. Instead, set the deleted Preferences instance to null. The system will reclaim them in a unified manner.

This API cannot be called concurrently with other preferences APIs.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.
15500010	Failed to delete the user preferences persistence file.

Example

FA model:

// Obtain the 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 model:

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>

Deletes a Preferences instance from the cache. If the Preferences instance has a persistent file, the persistent file will also be deleted. This API uses a promise to return the result.

This API cannot be called concurrently with other preferences APIs.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.
15500010	Failed to delete the user preferences persistence file.

Example

FA model:

// Obtain the 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 model:

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.deletePreferences¹⁰⁺

deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void

This API cannot be called concurrently with other preferences APIs.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15500010	Failed to delete the user preferences persistence file.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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.deletePreferences¹⁰⁺

deletePreferences(context: Context, options: Options): Promise<void>

Deletes a Preferences instance from the cache. If the Preferences instance has a persistent file, the persistent file will also be deleted. This API uses a promise to return the result.

This API cannot be called concurrently with other preferences APIs.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15500010	Failed to delete the user preferences persistence file.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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

Removes a Preferences instance from the cache. This API uses an asynchronous callback to return the result.

After an application calls getPreferences for the first time to obtain a Preferences instance, the obtained Preferences instance is cached. When the application calls getPreferences again, the Preferences instance will be read from the cache instead of from the persistent file. After this API is called to remove the instance from the cache, calling getPreferences again will read data from the persistent file and create a Preferences instance.

Avoid using a removed Preferences instance to perform data operations, which may cause data inconsistency. Instead, set the removed Preferences instance to null. The system will reclaim them in a unified manner.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

FA model:

// Obtain the 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 model:

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>

Removes a Preferences instance from the cache. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

FA model:

// Obtain the 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 model:

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.removePreferencesFromCacheSync¹⁰⁺

removePreferencesFromCacheSync(context: Context, name: string): void

Removes a Preferences instance from the cache. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
name	string	Yes	Name of the Preferences instance.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

FA model:

// Obtain the context.
import { featureAbility } from '@kit.AbilityKit';
let context = featureAbility.getContext();
preferences.removePreferencesFromCacheSync(context, 'myStore');

Stage model:

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    preferences.removePreferencesFromCacheSync(this.context, 'myStore');
  }
}

preferences.removePreferencesFromCache¹⁰⁺

removePreferencesFromCache(context: Context, options: Options, callback: AsyncCallback<void>): void

Removes a Preferences instance from the cache. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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.removePreferencesFromCache¹⁰⁺

removePreferencesFromCache(context: Context, options: Options): Promise<void>

Removes a Preferences instance from the cache. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the 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 model:

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.removePreferencesFromCacheSync¹⁰⁺

removePreferencesFromCacheSync(context: Context, options: Options):void

Removes a Preferences instance from the cache. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
context	Context	Yes	Application context. For details about the application context of the FA model, see Context. For details about the application context of the stage model, see Context.
options	Options	Yes	Configuration options of the Preferences instance.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
15500000	Inner error.
15501001	The operations is supported in stage mode only.
15501002	Invalid dataGroupId.

Example

FA model:

// Obtain the context.
import { featureAbility } from '@kit.AbilityKit';
let context = featureAbility.getContext();
let options: preferences.Options = { name: 'myStore' };
preferences.removePreferencesFromCacheSync(context, options);

Stage model:

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);
  }
}

StorageType¹⁸⁺

Enumerates the storage types of preferences.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Name	Value	Description
XML	0	XML, which is the default storage mode of preferences. In this mode, data is stored in XML format. Data operations are performed in the memory. To persist data, call flush().
GSKV	1	GSKV. Data is stored in GSKV mode. Data operations are flushed on a real-time basis without calling flush().

NOTE - Before using this mode, you are advised to call isStorageTypeSupported to check whether this storage type is supported. - Once the storage type is selected and data instances are obtained via getPreferences(), the storage type cannot be changed. - Data cannot be directly migrated between the Preferences instances that use different storage types. To migrate data between them, you need to read the data to be migrated and then write the data. - If you need to change the storage directory of preferences, you cannot move or overwrite files. Instead, you need to read the data and then write the data.

preferences.isStorageTypeSupported¹⁸⁺

isStorageTypeSupported(type: StorageType): boolean

Checks whether the specified storage type is supported. This API returns the result synchronously. If the storage type is supported, true is returned. Otherwise, false is returned.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	StorageType	Yes	Storage type to check.

Return value

Type	Description
boolean	Returns true if the storage type is supported; returns false otherwise.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: Incorrect parameter types.

Example

let xmlType = preferences.StorageType.XML;
let gskvType = preferences.StorageType.GSKV;
let isXmlSupported = preferences.isStorageTypeSupported(xmlType);
let isGskvSupported = preferences.isStorageTypeSupported(gskvType);
console.info("Is xml supported in current platform: " + isXmlSupported);
console.info("Is gskv supported in current platform: " + isGskvSupported);

Options¹⁰⁺

Represents the configuration of a Preferences instance.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Name	Type	Mandatory	Description
name	string	Yes	Name of the Preferences instance. It must be longer than 0 bytes and less than or equal to 255 bytes, and cannot contain or end with slashes (/). Atomic service API: This API can be used in atomic services since API version 11.
dataGroupId	string\|null\|undefined	No	Application group ID. Currently, this parameter is not supported. This parameter is optional. A Preferences instance will be created in the sandbox path corresponding to the specified dataGroupId. If this parameter is not specified, the Preferences instance is created in the sandbox directory of the application. Model restriction: This attribute can be used only in the stage model. Atomic service API: This API can be used in atomic services since API version 11.
storageType¹⁸⁺	StorageType\|null\|undefined	No	Storage mode to be used by the Preferences instance. This parameter is optional. If this parameter is left blank, the XML storage type is used by default. After the storage type is set for a Preferences instance, it cannot be changed. Atomic service API: This API can be used in atomic services since API version 18.

Preferences

Provides APIs for obtaining and modifying the stored data.

Before calling any API of Preferences, you must obtain a Preferences instance by using preferences.getPreferences.

get

get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void

Obtains the value of a key from this Preferences instance. This API uses an asynchronous callback to return the result. If the value is null or is not of the default value type, defValue is returned.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data to obtain. It cannot be empty.
defValue	ValueType	Yes	Default value to be returned.
callback	AsyncCallback<ValueType>	Yes	Callback used to return the result. If the operation is successful, err is undefined and data is the value obtained. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Obtained the value of 'startup' successfully. val: " + val);
})

get

get(key: string, defValue: ValueType): Promise<ValueType>

Obtains the value of a key from this Preferences instance. This API uses a promise to return the result. If the value is null or is not of the default value type, defValue is returned.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data to obtain. It cannot be empty.
defValue	ValueType	Yes	Default value to be returned.

Return value

Type	Description
Promise<ValueType>	Promise used to return the value obtained.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = dataPreferences.get('startup', 'default');
promise.then((data: preferences.ValueType) => {
  console.info("Got the value of 'startup'. Data: " + data);
}).catch((err: BusinessError) => {
  console.error("Failed to get value of 'startup'. code =" + err.code + ", message =" + err.message);
})

getSync¹⁰⁺

getSync(key: string, defValue: ValueType): ValueType

Obtains the value of a key from this Preferences instance. This API returns the result synchronously. If the value is null or is not of the default value type, defValue is returned.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data to obtain. It cannot be empty.
defValue	ValueType	Yes	Default value to be returned.

Return value

Type	Description
ValueType	Returns the value obtained.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

let value: preferences.ValueType = dataPreferences.getSync('startup', 'default');

getAll

getAll(callback: AsyncCallback<Object>): void

Obtains all KV pairs from this Preferences instance. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<Object>	Yes	Callback used to return the result. If the operation is successful, err is undefined and value provides all KV pairs obtained. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Mandatory parameters are left unspecified.
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// There is no Object.keys in ArkTS, and the for..in... syntax cannot be used.
// If an error is reported, extract this API to a .ts file and expose it. Then import the API to the .ets file when required.
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>

Obtains all KV pairs from this Preferences instance. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Return value

Type	Description
Promise<Object>	Promise used to return the KV pairs obtained.

Error codes

For details about the error codes, see User Preference Error Codes.

ID	Error Message
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

// There is no Object.keys in ArkTS, and the for..in... syntax cannot be used.
// If an error is reported, extract this API to a .ts file and expose it. Then import the API to the .ets file when required.
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);
})

getAllSync¹⁰⁺

getAllSync(): Object

Obtains all KV pairs from this Preferences instance. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Return value

Type	Description
Object	Returns all KV pairs obtained.

Error codes

For details about the error codes, see User Preference Error Codes.

ID	Error Message
15500000	Inner error.

Example

// There is no Object.keys in ArkTS, and the for..in... syntax cannot be used.
// If an error is reported, extract this API to a .ts file and expose it. Then import the API to the .ets file when required.
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

Writes data to this Preferences instance. This API uses an asynchronous callback to return the result. You can use flush to persist the Preferences instance.

NOTE

If the value contains a string that is not in UTF-8 format, store it in an Uint8Array. Otherwise, the persistent file may be damaged due to format errors.

If the key already exists, put() overwrites the value. You can use hasSync() to check whether the KV pair exists.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data. It cannot be empty.
value	ValueType	Yes	Value to write.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Successfully put the value of 'startup'.");
})

put

put(key: string, value: ValueType): Promise<void>

Writes data to this Preferences instance. This API uses a promise to return the result. You can use flush to persist the Preferences instance.

NOTE

If the value contains a string that is not in UTF-8 format, store it in an Uint8Array. Otherwise, the persistent file may be damaged due to format errors.

If the key already exists, put() overwrites the value. You can use hasSync() to check whether the KV pair exists.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data. It cannot be empty.
value	ValueType	Yes	Value to write.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = dataPreferences.put('startup', 'auto');
promise.then(() => {
  console.info("Successfully put the value of 'startup'.");
}).catch((err: BusinessError) => {
  console.error("Failed to put value of 'startup'. code =" + err.code + ", message =" + err.message);
})

putSync¹⁰⁺

putSync(key: string, value: ValueType): void

Writes data to this Preferences instance. This API returns the result synchronously. You can use flush to persist the Preferences instance.

NOTE

If the value contains a string that is not in UTF-8 format, store it in an Uint8Array. Otherwise, the persistent file may be damaged due to format errors.

If the key already exists, putSync() overwrites the value. You can use hasSync() to check whether the KV pair exists.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data. It cannot be empty.
value	ValueType	Yes	Value to write.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

dataPreferences.putSync('startup', 'auto');

has

has(key: string, callback: AsyncCallback<boolean>): void

Checks whether this Preferences instance contains the KV pair of the given key. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data to check. It cannot be empty.
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. If the Preferences instance contains the KV pair, true will be returned. Otherwise, false will be returned.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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' is not contained.");
  }
})

has

has(key: string): Promise<boolean>

Checks whether this Preferences instance contains the KV pair of the given key. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data to check. It cannot be empty.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. If the Preferences instance contains the KV pair, true will be returned. Otherwise, false will be returned.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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' is not contained.");
  }
}).catch((err: BusinessError) => {
  console.error("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message);
})

hasSync¹⁰⁺

hasSync(key: string): boolean

Checks whether this Preferences instance contains the KV pair of the given key. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the data to check. It cannot be empty.

Return value

Type	Description
boolean	If the Preferences instance contains the KV pair, true will be returned. Otherwise, false will be returned.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

let isExist: boolean = dataPreferences.hasSync('startup');
if (isExist) {
  console.info("The key 'startup' is contained.");
} else {
  console.info("The key 'startup' is not contained.");
}

delete

delete(key: string, callback: AsyncCallback<void>): void

Deletes a KV pair from this Preferences instance. This API uses an asynchronous callback to return the result. You can use flush to persist the Preferences instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to delete. It cannot be empty.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Deleted the key 'startup'.");
})

delete

delete(key: string): Promise<void>

Deletes a KV pair from this Preferences instance. This API uses a promise to return the result. You can use flush to persist the Preferences instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to delete. It cannot be empty.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = dataPreferences.delete('startup');
promise.then(() => {
  console.info("Deleted the key 'startup'.");
}).catch((err: BusinessError) => {
  console.error("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message);
})

deleteSync¹⁰⁺

deleteSync(key: string): void

Deletes a KV pair from this Preferences instance. This API returns the result synchronously. You can use flush to persist the Preferences instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to delete. It cannot be empty.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

dataPreferences.deleteSync('startup');

flush

flush(callback: AsyncCallback<void>): void

Flushes the data in this Preferences instance to the persistent file. This API uses an asynchronous callback to return the result.

NOTE

If no data is modified or the modified data is the same as the cached data, the persistent file will not be updated.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Mandatory parameters are left unspecified.
15500000	Inner error.

Example

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("Successfully flushed data.");
})

flush

flush(): Promise<void>

Flushes the data in this Preferences instance to the persistent file. This API uses a promise to return the result.

NOTE

If no data is modified or the modified data is the same as the cached data, the persistent file will not be updated.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see User Preference Error Codes.

ID	Error Message
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = dataPreferences.flush();
promise.then(() => {
  console.info("Successfully flushed data.");
}).catch((err: BusinessError) => {
  console.error("Failed to flush. code =" + err.code + ", message =" + err.message);
})

flushSync¹⁴⁺

flushSync(): void

Flushes the data in the cached Preferences instance to the persistent file.

NOTE

If no data is modified or the modified data is the same as the cached data, the persistent file will not be updated.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Error codes

For details about the error codes, see User Preference Error Codes.

ID	Error Message
15500000	Inner error.

Example

dataPreferences.flushSync();

clear

clear(callback: AsyncCallback<void>): void

Clears this Preferences instance. This API uses an asynchronous callback to return the result. You can use flush to persist the Preferences instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Mandatory parameters are left unspecified.
15500000	Inner error.

Example

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("Successfully cleared data.");
})

clear

clear(): Promise<void>

Clears this Preferences instance. This API uses a promise to return the result. You can use flush to persist the Preferences instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see User Preference Error Codes.

ID	Error Message
15500000	Inner error.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let promise = dataPreferences.clear();
promise.then(() => {
  console.info("Successfully cleared data.");
}).catch((err: BusinessError) => {
  console.error("Failed to clear. code =" + err.code + ", message =" + err.message);
})

clearSync¹⁰⁺

clearSync(): void

Clears this Preferences instance. This API returns the result synchronously. You can use flush to persist the Preferences instance.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Example

dataPreferences.clearSync();

on(‘change’)

on(type: ‘change’, callback: Callback<string>): void

Subscribes to data changes. The registered callback will be invoked to return the new value if the data change is flushed.

NOTE

After removePreferencesFromCache or deletePreferences is called, the data change subscription will be automatically canceled. After getPreferences is called again, you need to subscribe to data changes again.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is ‘change’, which indicates data changes.
callback	Callback<string>	Yes	Callback used to return the data change.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Successfully flushed data.");
})

on(‘multiProcessChange’)¹⁰⁺

on(type: ‘multiProcessChange’, callback: Callback<string>): void

Subscribes to inter-process data changes. When multiple processes hold the same preference file, calling flush in any process (including the current process) will trigger the callback in this API.

This API is provided for applications that have applied for dataGroupId. Avoid using this API for the applications that have not applied for dataGroupId because calling it in multiple process may damage the persistent files and cause data loss.

NOTE

The maximum number of subscriptions for inter-process data change of the same persistent file for the current process is 50. Once the limit is reached, the subscription will fail. You are advised to cancel the subscription in a timely manner after the callback is triggered.

After removePreferencesFromCache or deletePreferences is called, the data change subscription will be automatically canceled. After getPreferences is called again, you need to subscribe to data changes again.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is ‘multiProcessChange’, which indicates inter-process data changes.
callback	Callback<string>	Yes	Callback used to return the data change.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.
15500019	Failed to obtain the subscription service.

Example

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("Successfully flushed data.");
})

on(‘dataChange’)¹²⁺

on(type: ‘dataChange’, keys: Array<string>, callback: Callback<Record<string, ValueType>>): void

Subscribes to changes of specific data. The registered callback will be invoked only after the values of the specified keys are changed and flushed.

NOTE

After removePreferencesFromCache or deletePreferences is called, the data change subscription will be automatically canceled. After getPreferences is called again, you need to subscribe to data changes again.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is ‘dataChange’, which indicates data changes.
keys	Array<string>	Yes	Array of the keys to be observed.
callback	Callback<Record<string, ValueType>>	Yes	Callback used to return the changed data, in an array of KV pairs. The keys identify the data changed, and the values are the new values. The values support the following data types: number, string, boolean, Array<number>, Array<string>, Array< boolean>, Uint8Array, and object.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Successfully flushed data.");
})

off(‘change’)

off(type: ‘change’, callback?: Callback<string>): void

Unsubscribes from data changes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is ‘change’, which indicates data changes.
callback	Callback<string>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for data changes.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Successfully flushed data.");
})
dataPreferences.off('change', observer);

off(‘multiProcessChange’)¹⁰⁺

off(type: ‘multiProcessChange’, callback?: Callback<string>): void

Unsubscribes from inter-process data changes.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is ‘multiProcessChange’, which indicates inter-process data changes.
callback	Callback<string>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for data changes.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Successfully flushed data.");
})
dataPreferences.off('multiProcessChange', observer);

off(‘dataChange’)¹²⁺

off(type: ‘dataChange’, keys: Array<string>, callback?: Callback<Record<string, ValueType>>): void

Unsubscribes from changes of specific data.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is ‘dataChange’, which indicates data changes.
keys	Array<string>	Yes	Array of keys to be unsubscribed from. If this parameter is left empty, all keys are unsubscribed from.
callback	Callback<Record<string, ValueType>>	No	Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the changes of the specified data.

Error codes

For details about the error codes, see Universal Error Codes and User Preference Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
15500000	Inner error.

Example

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("Successfully flushed data.");
})
dataPreferences.off('dataChange', keys, observer);

ValueType

Enumerates the value types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Type	Description
number	The value is a number.
string	The value is a string.
boolean	The value is true or false.
Array<number>	The value is an array of numbers.
Array<boolean>	The value is a Boolean array.
Array<string>	The value is an array of strings.
Uint8Array¹¹⁺	The value is an array of 8-bit unsigned integers.
object¹²⁺	The value is an object.
bigint¹²⁺	The value is an integer in any format.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (ArkData Management)

harmony 鸿蒙Data

harmony 鸿蒙OH_Cursor

harmony 鸿蒙OH_Predicates

harmony 鸿蒙OH_Rdb_Config

harmony 鸿蒙OH_Rdb_Store

harmony 鸿蒙OH_VBucket

harmony 鸿蒙OH_VObject

harmony 鸿蒙Preferences

harmony 鸿蒙_r_d_b

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/5o0ZuP

harmony 鸿蒙@ohos.data.preferences (User Preferences)

@ohos.data.preferences (User Preferences)

Modules to Import

Constants

preferences.getPreferences

preferences.getPreferences

preferences.getPreferences10+

preferences.getPreferences10+

preferences.getPreferencesSync10+

preferences.deletePreferences

preferences.deletePreferences

preferences.deletePreferences10+

preferences.deletePreferences10+

preferences.removePreferencesFromCache

preferences.removePreferencesFromCache

preferences.removePreferencesFromCacheSync10+

preferences.removePreferencesFromCache10+

preferences.removePreferencesFromCache10+

preferences.removePreferencesFromCacheSync10+

StorageType18+

preferences.isStorageTypeSupported18+

Options10+

Preferences

get

get

getSync10+

getAll

getAll

getAllSync10+

put

put

putSync10+

has

has

hasSync10+

delete

delete

deleteSync10+

flush

flush

flushSync14+

clear

clear

clearSync10+

on(‘change’)

on(‘multiProcessChange’)10+

on(‘dataChange’)12+

off(‘change’)

off(‘multiProcessChange’)10+

off(‘dataChange’)12+

ValueType

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

preferences.getPreferences¹⁰⁺

preferences.getPreferences¹⁰⁺

preferences.getPreferencesSync¹⁰⁺

preferences.deletePreferences¹⁰⁺

preferences.deletePreferences¹⁰⁺

preferences.removePreferencesFromCacheSync¹⁰⁺

preferences.removePreferencesFromCache¹⁰⁺

preferences.removePreferencesFromCache¹⁰⁺

preferences.removePreferencesFromCacheSync¹⁰⁺

StorageType¹⁸⁺

preferences.isStorageTypeSupported¹⁸⁺

Options¹⁰⁺

getSync¹⁰⁺

getAllSync¹⁰⁺

putSync¹⁰⁺

hasSync¹⁰⁺

deleteSync¹⁰⁺

flushSync¹⁴⁺

clearSync¹⁰⁺

on(‘multiProcessChange’)¹⁰⁺

on(‘dataChange’)¹²⁺

off(‘multiProcessChange’)¹⁰⁺

off(‘dataChange’)¹²⁺