# @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](../../application-models/application-context-stage.md#obtaining-application-file-path) directory. Before creating a preferences object, ensure that the **preferencesDir** directory is readable and writeable. The [encryption level](../apis-ability-kit/js-apis-app-ability-contextConstant.md#areamode) of the persistent file directory determines the access to the files. For details, see [Application File Directory and Application File Path](../../file-management/app-sandbox-directory.md#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
```ts
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 length of a key, 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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback<[Preferences](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
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:
```ts
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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance.|
**Return value**
| Type | Description |
| ------------------------------------------ | ---------------------------------- |
| Promise<[Preferences](#preferences)> | Promise used to return the **Preferences** instance obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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<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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
| callback | AsyncCallback<[Preferences](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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<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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
**Return value**
| Type | Description |
| --------------------------------------- | ---------------------------------- |
| Promise<[Preferences](#preferences)> | Promise used to return the **Preferences** instance obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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
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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
**Return value**
| Type | Description |
| --------------------------- | --------------------- |
| [Preferences](#preferences) | **Preferences** instance obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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.
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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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
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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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>
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.
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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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](#preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#preferencesgetpreferences) 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 new **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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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.
After an application calls [getPreferences](#preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#preferencesgetpreferences) 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 new **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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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
Removes a **Preferences** instance from the cache. This API returns the result synchronously.
After an application calls [getPreferences](#preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#preferencesgetpreferences) 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 new **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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// Obtain the context.
import { featureAbility } from '@kit.AbilityKit';
let context = featureAbility.getContext();
preferences.removePreferencesFromCacheSync(context, 'myStore');
```
Stage model:
```ts
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
Removes a **Preferences** instance from the cache. This API uses an asynchronous callback to return the result.
After an application calls [getPreferences](#preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#preferencesgetpreferences) 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 new **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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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>
Removes a **Preferences** instance from the cache. This API uses a promise to return the result.
After an application calls [getPreferences](#preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#preferencesgetpreferences) 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 new **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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// 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:
```ts
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
Removes a **Preferences** instance from the cache. This API returns the result synchronously.
After an application calls [getPreferences](#preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#preferencesgetpreferences) 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 new **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](../apis-ability-kit/js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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:
```ts
// Obtain the context.
import { featureAbility } from '@kit.AbilityKit';
let context = featureAbility.getContext();
let options: preferences.Options = { name: 'myStore' };
preferences.removePreferencesFromCacheSync(context, options);
```
Stage model:
```ts
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);
}
}
```
## StorageType16+
Enumerates the storage types of preferences.
**Atomic service API**: This API can be used in atomic services since API version 16.
**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()**. |
| CLKV | 1 |CLKV.
Data is stored in CLKV database 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.isStorageTypeSupported16+
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 16.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------- | ---- | ------------------------------------------------------------ |
| type | [StorageType](#storagetype16) | 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error: Incorrect parameter types. |
**Example**
```ts
let xmlType = preferences.StorageType.XML;
let clkvType = preferences.StorageType.CLKV;
let isXmlSupported = preferences.isStorageTypeSupported(xmlType);
let isClkvSupported = preferences.isStorageTypeSupported(clkvType);
console.info("Is xml supported in current platform: " + isXmlSupported);
console.info("Is clkv supported in current platform: " + isClkvSupported);
```
## Options10+
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.
|
| storageType16+ | [StorageType](#storagetype16)\|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 16.
|
## 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](#preferencesgetpreferences).
### 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](#valuetype) | Yes | Default value to be returned.|
| callback | AsyncCallback<[ValueType](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](#valuetype) | Yes | Default value to be returned.|
**Return value**
| Type | Description |
| ----------------------------------- | ----------------------------- |
| Promise<[ValueType](#valuetype)> | Promise used to return the value obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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);
})
```
### getSync10+
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](#valuetype) | Yes | Default value to be returned.|
**Return value**
| Type | Description |
| ----------------------------------- | ----------------------------- |
| [ValueType](#valuetype) | Returns the value obtained.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Mandatory parameters are left unspecified.|
| 15500000 | Inner error. |
**Example**
```ts
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](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15500000 | Inner error. |
**Example**
```ts
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);
})
```
### getAllSync10+
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](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15500000 | Inner error. |
**Example**
```ts
// 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](#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](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](#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](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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);
})
```
### putSync10+
putSync(key: string, value: ValueType): void
Writes data to this **Preferences** instance. This API returns the result synchronously. You can use [flush](#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](#valuetype) | Yes | Value to write.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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);
})
```
### hasSync10+
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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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);
})
```
### deleteSync10+
deleteSync(key: string): void
Deletes a KV pair from this **Preferences** instance. This API returns the result synchronously. You can use [flush](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Mandatory parameters are left unspecified. |
| 15500000 | Inner error. |
**Example**
```ts
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](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15500000 | Inner error. |
**Example**
```ts
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);
})
```
### flushSync14+
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](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15500000 | Inner error. |
**Example**
```ts
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](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 401 | Parameter error. Mandatory parameters are left unspecified. |
| 15500000 | Inner error. |
**Example**
```ts
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](#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](errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15500000 | Inner error. |
**Example**
```ts
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);
})
```
### clearSync10+
clearSync(): void
Clears this **Preferences** instance. This API returns the result synchronously. You can use [flush](#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**
```ts
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](#flush).
> **NOTE**
>
> After [removePreferencesFromCache](#preferencesremovepreferencesfromcache) or [deletePreferences](#preferencesdeletepreferences) is called, the data change subscription will be automatically canceled. After [getPreferences](#preferencesgetpreferences) 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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')10+
on(type: 'multiProcessChange', callback: Callback<string>): void
Subscribes to inter-process data changes. When multiple processes hold the same preference file, calling [flush](#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](#options10). 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](#preferencesremovepreferencesfromcache) or [deletePreferences](#preferencesdeletepreferences) is called, the data change subscription will be automatically canceled. After [getPreferences](#preferencesgetpreferences) 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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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')12+
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](#flush).
> **NOTE**
>
> After [removePreferencesFromCache](#preferencesremovepreferencesfromcache) or [deletePreferences](#preferencesdeletepreferences) is called, the data change subscription will be automatically canceled. After [getPreferences](#preferencesgetpreferences) 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](#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\, Array\, Array\< boolean>, Uint8Array, and object.|
**Error codes**
For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let observer = (data: Record) => {
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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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')10+
off(type: 'multiProcessChange', callback?: Callback<string>): void
Unsubscribes from inter-process data changes.
This API is provided for applications that have applied for [dataGroupId](#options10). 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.
**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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
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')12+
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](#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](../errorcode-universal.md) and [User Preference Error Codes](errorcode-preferences.md).
| 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**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
let observer = (data: Record) => {
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
type ValueType = number | string | boolean | Array\ | Array\ | Array\ | Uint8Array | object | bigint
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\ | The value is an array of numbers. |
| Array\ | The value is a Boolean array. |
| Array\ | The value is an array of strings. |
| Uint8Array11+ | The value is an array of 8-bit unsigned integers.|
| object12+ | The value is an object.|
| bigint12+ | The value is an integer in any format. |