diff --git a/en/application-dev/reference/apis/js-apis-data-preferences.md b/en/application-dev/reference/apis/js-apis-data-preferences.md index 95e2ed9fcdb3459ae9c818e149f2ce46b530b722..bb4bad334615e6c004c0ca6eab1081cfa75d4593 100644 --- a/en/application-dev/reference/apis/js-apis-data-preferences.md +++ b/en/application-dev/reference/apis/js-apis-data-preferences.md @@ -1,33 +1,33 @@ -# Lightweight Storage +# Preferences -Lightweight storage provides applications with data processing capability and allows applications to perform lightweight data storage and query. Data is stored in key-value (KV) pairs. Keys are of the string type, and values can be of the number, string, or Boolean type. +Preferences provide capabilities for processing key-value (KV) data for applications and supports lightweight data persistence, modification, and query. Data is stored in KV pairs. Keys are of the string type, and values can be of the number, string, or Boolean type. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **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. ## Modules to Import -``` -import data_preferences from '@ohos.data.preferences' +```ts +import data_preferences from '@ohos.data.preferences'; ``` -## Attributes +## Constants **System capability**: SystemCapability.DistributedDataManager.Preferences.Core | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | | MAX_KEY_LENGTH | string | Yes| No| Maximum length of a key. It is 80 bytes.| -| MAX_VALUE_LENGTH | string | Yes| No| Maximum length of a value of the string type. It is 8192 bytes.| +| MAX_VALUE_LENGTH | string | Yes| No| Maximum length of a value. It is 8192 bytes.| ## data_preferences.getPreferences getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void -Reads a file and loads the data to the **Preferences** instance. This method uses an asynchronous callback to return the execution result. +Reads a preference persistence file and loads data to the **Preferences** instance for data operations. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core @@ -35,35 +35,37 @@ Reads a file and loads the data to the **Preferences** instance. This method use - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | context | Context | Yes| Context of the app or functionality.| - | name | string | Yes| Name of the app's internal data storage.| + | context | [Context](js-apis-Context.md) | Yes| Context of the app or functionality.| + | name | string | Yes| Name of the **Preferences** instance persistence file.| | callback | AsyncCallback<[Preferences](#preferences)> | Yes| Callback used to return the execution result.| - Example - ``` + ```ts import Ability from '@ohos.application.Ability' import data_preferences from '@ohos.data.preferences' - var path = this.context.getDataBaseDir() - data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { - if (err) { - console.info("Get the preferences failed, path: " + path + '/mystore') - return; - } - preferences.put('startup', 'auto', function (err) { + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { if (err) { - console.info("Put the value of startup failed with err: " + err) - return + console.info("Failed to get the preferences") + return; } - console.info("Put the value of startup successfully.") - preferences.flush(function (err) { + preferences.put('startup', 'auto', function (err) { if (err) { - console.info("Flush to file failed with err: " + err) + console.info("Failed to put the value of startup, err: " + err) return } - console.info("Flushed to file successfully.") + console.info("Put the value of startup successfully.") + preferences.flush(function (err) { + if (err) { + console.info("Failed to flush data to file, err: " + err) + return + } + console.info("Flushed data to file successfully.") + }) }) }) - }) + } ``` @@ -71,45 +73,47 @@ Reads a file and loads the data to the **Preferences** instance. This method use getPreferences(context: Context, name: string): Promise<Preferences> -Reads a file and loads the data to the **Preferences** instance. This method uses a promise to return the execution result. +Reads a preference persistence file and loads data to the **Preferences** instance for data operations. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | context | Context | Yes| Context of the app or functionality.| - | name | string | Yes| Name of the app's internal data storage.| + | context | [Context](js-apis-Context.md) | Yes| Context of the app or functionality.| + | name | string | Yes| Name of the **Preferences** instance persistence file.| - Return value | Type| Description| | -------- | -------- | - | Promise<[Preferences](#preferences)> | Promise used to return the result.| + | Promise<[Preferences](#preferences)> | Promise used to return the execution result.| - Example - ``` + ```ts import Ability from '@ohos.application.Ability' import data_preferences from '@ohos.data.preferences' - var path = this.context.getDataBaseDir() - let promisePre = data_preferences.getPreferences(this.context, 'mystore') - promisePre.then((preferences) => { - preferences.put('startup', 'auto', function (err) { - if (err) { - console.info("Put the value of startup failed with err: " + err) - return - } - console.info("Put the value of startup successfully.") - preferences.flush(function (err) { + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + preferences.put('startup', 'auto', function (err) { if (err) { - console.info("Flush to file failed with err: " + err) + console.info("Failed to put the value of startup, err: " + err) return } - console.info("Flushed to file successfully.") + console.info("Put the value of startup successfully.") + preferences.flush(function (err) { + if (err) { + console.info("Failed to flush data to file, err: " + err) + return + } + console.info("Flushed data to file successfully.") + }) }) + }).catch((err) => { + console.info("Failed to get the preferences") }) - }).catch((err) => { - console.info("Get the preferences failed, path: " + path + '/mystore') - }) + } ``` @@ -117,28 +121,32 @@ Reads a file and loads the data to the **Preferences** instance. This method use deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void -Removes the singleton **Preferences** instance of the specified file from the memory, and deletes the specified file, its backup file, and corrupted files. After the specified files are deleted, the **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This method uses an asynchronous callback to return the execution result. +Deletes a **Preferences** singleton instance, the persistence file and backup file, and corrupted files from the memory. +Once a preference persistence file is deleted, the **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses an asynchronous callback to return the execution result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | context | Context | Yes| Context of the app or functionality.| - | name | string | Yes| Name of the app's internal data storage.| + | context | [Context](js-apis-Context.md) | Yes| Context of the app or functionality.| + | name | string | Yes| Name of the **Preferences** instance persistence file.| | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - Example - ``` + ```ts import Ability from '@ohos.application.Ability' import data_preferences from '@ohos.data.preferences' - data_preferences.deletePreferences(this.context, 'mystore', function (err) { - if (err) { - console.info("Deleted failed with err: " + err) - return - } - console.info("Deleted successfully.") - }) + export default class MainAbility extends Ability { + + data_preferences.deletePreferences(this.context, 'mystore', function (err) { + if (err) { + console.info("Failed to delete data, err: " + err) + return + } + console.info("Deleted data successfully.") + }) + } ``` @@ -146,31 +154,35 @@ Removes the singleton **Preferences** instance of the specified file from the me deletePreferences(context: Context, name: string): Promise<void> -Removes the singleton **Preferences** instance of the specified file from the memory, and deletes the specified file, its backup file, and corrupted files. After the specified files are deleted, the **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This method uses a promise to return the execution result. +Deletes a **Preferences** singleton instance, the persistence file and backup file, and corrupted files from the memory. +Once a preference persistence file is deleted, the **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses a promise to return the execution result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | context | Context | Yes| Context of the app or functionality.| - | name | string | Yes| Name of the app's internal data storage.| + | context | [Context](js-apis-Context.md) | Yes| Context of the app or functionality.| + | name | string | Yes| Name of the **Preferences** instance persistence file.| - Return value | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result.| + | Promise<void> | Promise used to return the execution result.| - Example - ``` + ```ts import Ability from '@ohos.application.Ability' import data_preferences from '@ohos.data.preferences' - let promisedelPre = data_preferences.deletePreferences(this.context, 'mystore') - promisedelPre.then(() => { - console.info("Deleted successfully.") - }).catch((err) => { - console.info("Deleted failed with err: " + err) - }) + export default class MainAbility extends Ability { + + let promise = data_preferences.deletePreferences(this.context, 'mystore') + promise.then(() => { + console.info("Deleted data successfully.") + }).catch((err) => { + console.info("Failed to delete data, err: " + err) + }) + } ``` @@ -178,30 +190,33 @@ Removes the singleton **Preferences** instance of the specified file from the me removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void -Removes the singleton **Preferences** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. +Removes a **Preferences** singleton instance from the memory. -This method uses an asynchronous callback to return the result. +When a **Preferences** singleton instance is removed, this instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses an asynchronous callback to return the execution result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | context | Context | Yes| Context of the app or functionality.| - | name | string | Yes| Name of the app's internal data storage.| + | context | [Context](js-apis-Context.md) | Yes| Context of the app or functionality.| + | name | string | Yes| Name of the **Preferences** instance persistence file.| | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - Example - ``` + ```ts import Ability from '@ohos.application.Ability' import data_preferences from '@ohos.data.preferences' - data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) { - if (err) { - console.info("Removed preferences from cache failed with err: " + err) - return - } - console.info("Removed preferences from cache successfully.") - }) + export default class MainAbility extends Ability { + + data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) { + if (err) { + console.info("Failed to remove preferences from cache, err: " + err) + return + } + console.info("Removed preferences from cache successfully.") + }) + } ``` @@ -209,33 +224,36 @@ This method uses an asynchronous callback to return the result. removePreferencesFromCache(context: Context, name: string): Promise<void> -Removes the singleton **Preferences** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. +Removes a **Preferences** singleton instance from the memory. -This method uses a promise to return the result. +When a **Preferences** singleton instance is removed, this instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses a promise to return the execution result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | context | Context | Yes| Context of the app or functionality.| - | name | string | Yes| Name of the app's internal data storage.| + | context | [Context](js-apis-Context.md) | Yes| Context of the app or functionality.| + | name | string | Yes| Name of the **Preferences** instance persistence file.| - Return value | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result.| + | Promise<void> | Promise used to return the execution result.| - Example - ``` + ```ts import Ability from '@ohos.application.Ability' import data_preferences from '@ohos.data.preferences' - let promiserevPre = data_preferences.removePreferencesFromCache(this.context, 'mystore') - promiserevPre.then(() => { - console.info("Removed preferences from cache successfully.") - }).catch((err) => { - console.info("Removed preferences from cache failed with err: " + err) - }) + export default class MainAbility extends Ability { + + let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore') + promise.then(() => { + console.info("Removed preferences from cache successfully.") + }).catch((err) => { + console.info("Failed to remove preferences from cache, err: " + err) + }) + } ``` @@ -248,28 +266,37 @@ Provides APIs for obtaining and modifying storage data. get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void -Obtains the value corresponding to a key. If the value is null or not in the default value format, the default value is returned. - -This method uses an asynchronous callback to return the result. +Obtains the value of a key. If the value is null or a non-default value, the default data is returned. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | defValue | ValueType | Yes| Default value to be returned. It can be a number, string, or Boolean value.| + | key | string | Yes| Key of the data to obtain. It cannot be empty.| + | defValue | [ValueType](#valuetype) | Yes| Default value to be returned. It can be a number, string, or Boolean value.| | callback | AsyncCallback<ValueType> | Yes| Callback used to return the execution result.| - Example - ``` - preferences.get('startup', 'default', function(err, value) { - if (err) { - console.info("Get the value of startup failed with err: " + err) - return - } - console.info("The value of startup is " + value) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Get the preferences failed, err: " + err) + return + } + preferences.get('startup', 'default', function(err, value) { + if (err) { + console.info("Get the value of startup failed, err: " + err) + return + } + console.info("The value of startup is " + value) + }) + }) + } ``` @@ -277,31 +304,39 @@ This method uses an asynchronous callback to return the result. get(key: string, defValue: ValueType): Promise<ValueType> -Obtains the value corresponding to a key. If the value is null or not in the default value format, the default value is returned. - -This method uses a promise to return the result. +Obtains the value of a key. If the value is null or a non-default value, the default data is returned. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| - | defValue | ValueType | Yes| Default value to be returned. It can be a number, string, or Boolean value.| + | key | string | Yes| Key of the data to obtain. It cannot be empty.| + | defValue | [ValueType](#valuetype) | Yes| Default value to be returned. It can be a number, string, or Boolean value.| - Return value | Type| Description| | -------- | -------- | - | Promise<ValueType> | Promise used to return the result.| + | Promise<ValueType> | Promise used to return the execution result.| - Example - ``` - let promiseget = preferences.get('startup', 'default') - promiseget.then((value) => { - console.info("The value of startup is " + value) - }).catch((err) => { - console.info("Get the value of startup failed with err: " + err) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + let promiseGet = preferences.get('startup', 'default') + promiseGet.then((value) => { + console.info("The value of startup is " + value) + }).catch((err) => { + console.info("Failed to get the value of startup, err: " + err) + }) + }).catch((err) => { + console.info("Get the preferences failed, err: " + err) + }) + } ``` @@ -309,28 +344,37 @@ This method uses a promise to return the result. put(key: string, value: ValueType, callback: AsyncCallback<void>): void -Obtains the **Preferences** instance corresponding to the specified file, writes data to the **Preferences** instance using a **Preferences** API, and saves data to the file using **flush()** or **flushSync()**. - -This method uses an asynchronous callback to return the result. +Obtain a **Preferences** instance, writes data to the **Preferences** instance, and saves the data to the file using **flush()** or **flushSync()**. This API uses an asynchronous callback to return the execution result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data to modify. It cannot be empty.| - | value | ValueType | Yes| New value to store. It can be a number, string, or Boolean value.| + | key | string | Yes| Key of the data. It cannot be empty.| + | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.| | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - Example - ``` - preferences.put('startup', 'auto', function (err) { - if (err) { - console.info("Put the value of startup failed with err: " + err) - return - } - console.info("Put the value of startup successfully.") - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Failed to get the preferences, err: " + err) + return + } + preferences.put('startup', 'auto', function (err) { + if (err) { + console.info("Failed to put the value of startup, err: " + err) + return + } + console.info("Put the value of startup successfully.") + }) + }) + } ``` @@ -338,31 +382,39 @@ This method uses an asynchronous callback to return the result. put(key: string, value: ValueType): Promise<void> -Obtains the **Preferences** instance corresponding to the specified file, writes data to the **Preferences** instance using a **Preferences** API, and saves data to the file using **flush()** or **flushSync()**. - -This method uses a promise to return the result. +Obtain a **Preferences** instance, writes data to the **Preferences** instance, and saves the data to the file using **flush()** or **flushSync()**. This API uses a promise to return the execution result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data to modify. It cannot be empty.| - | value | ValueType | Yes| New value to store. It can be a number, string, or Boolean value.| + | key | string | Yes| Key of the data. It cannot be empty.| + | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.| - Return value | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result.| + | Promise<void> | Promise used to return the execution result.| - Example - ``` - let promiseput = preferences.put('startup', 'auto') - promiseput.then(() => { - console.info("Put the value of startup successfully.") - }).catch((err) => { - console.info("Put the value of startup failed with err: " + err) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + let promisePut = preferences.put('startup', 'auto') + promisePut.then(() => { + console.info("Put the value of startup successfully.") + }).catch((err) => { + console.info("Failed to put the value of startup, err: " + err) + }) + }).catch((err) => { + console.info("Get the preferences failed, err: " + err) + }) + } ``` @@ -370,34 +422,45 @@ This method uses a promise to return the result. has(key: string, callback: AsyncCallback<boolean>): boolean -Checks whether the **Preference** object contains data with a given key. - -This method uses an asynchronous callback to return the result. +Checks whether the **Preferences** instance contains data with a given key. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| + | key | string | Yes| Key of the data to check. It cannot be empty.| | callback | AsyncCallback<boolean> | Yes| Callback used to return the execution result.| - Return value | Type| Description| | -------- | -------- | - | boolean | Returns **true** if the **Preference** object contains data with the specified key; returns **false** otherwise.| + | boolean | Returns **true** if the **Preferences** instance contains data with the specified key; returns **false** otherwise.| - Example - ``` - preferences.has('startup', function (err, isExist) { - if (err) { - console.info("Check the key of startup failed with err: " + err) - return - } - if (isExist) { - console.info("The key of startup is contained.") - } - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Failed to get the preferences, err: " + err) + return + } + preferences.has('startup', function (err, isExist) { + if (err) { + console.info("Failed to check the key of startup, err: " + err) + return + } + if (isExist) { + console.info("The key of startup is contained.") + } else { + console.info("The key of startup is not contained.") + } + }) + }) + } ``` @@ -405,32 +468,42 @@ This method uses an asynchronous callback to return the result. has(key: string): Promise<boolean> -Checks whether the **Preference** object contains data with a given key. - -This method uses a promise to return the result. +Checks whether the **Preferences** instance contains data with a given key. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| + | 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.| + | Promise<boolean> | Promise used to return the execution result.| - Example - ``` - let promisehas = preferences.has('startup') - promisehas.then((isExist) => { - if (isExist) { - console.info("The key of startup is contained.") - } - }).catch((err) => { - console.info("Check the key of startup failed with err: " + err) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + let promiseHas = preferences.has('startup') + promiseHas.then((isExist) => { + if (isExist) { + console.info("The key of startup is contained.") + } else { + console.info("The key of startup is not contained.") + } + }).catch((err) => { + console.info("Check the key of startup failed, err: " + err) + }) + }).catch((err) => { + console.info("Get the preferences failed, err: " + err) + }) + } ``` @@ -438,27 +511,36 @@ This method uses a promise to return the result. delete(key: string, callback: AsyncCallback<void>): void -Deletes data with the specified key from this **Preference** object. - -This method uses an asynchronous callback to return the result. +Deletes the KV pair of the specified key from this **Preferences** instance. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data. It cannot be empty.| + | key | string | Yes| Key of the KV pair to delete. It cannot be empty.| | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - Example - ``` - preferences.delete('startup', function (err) { - if (err) { - console.info("Delete startup key failed with err: " + err) - return - } - console.info("Deleted startup key successfully.") - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Failed to get the preferences, err: " + err) + return + } + preferences.delete('startup', function (err) { + if (err) { + console.info("Failed to delete startup key, err: " + err) + return + } + console.info("Deleted startup key successfully.") + }) + }) + } ``` @@ -466,30 +548,38 @@ This method uses an asynchronous callback to return the result. delete(key: string): Promise<void> -Deletes data with the specified key from this **Preference** object. - -This method uses a promise to return the result. +Deletes the KV pair of the specified key from this **Preferences** instance. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Parameters | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | key | string | Yes| Key of the data.| + | key | string | Yes| Key of the KV pair to delete. It cannot be empty.| - Return value | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result.| + | Promise<void> | Promise used to return the execution result.| - Example - ``` - let promisedel = preferences.delete('startup') - promisedel.then(() => { - console.info("Deleted startup key successfully.") - }).catch((err) => { - console.info("Delete startup key failed with err: " + err) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + let promiseDelete = preferences.delete('startup') + promiseDelete.then(() => { + console.info("Deleted startup key successfully.") + }).catch((err) => { + console.info("Failed to delete startup key, err: " + err) + }) + }).catch((err) => { + console.info("Failed to get the preferences, err: " + err) + }) + } ``` @@ -497,9 +587,7 @@ This method uses a promise to return the result. flush(callback: AsyncCallback<void>): void -Saves the modification of this object to the **Preferences** instance and synchronizes the modification to the file. - -This method uses an asynchronous callback to return the result. +Saves the modification to this **Preferences** instance and synchronizes the modification to the preference persistence file. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core @@ -509,14 +597,25 @@ This method uses an asynchronous callback to return the result. | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - Example - ``` - preferences.flush(function (err) { - if (err) { - console.info("Flush to file failed with err: " + err) - return - } - console.info("Flushed to file successfully.") - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Failed to get the preferences, err: " + err) + return + } + preferences.flush(function (err) { + if (err) { + console.info("Failed to flush data to file, err: " + err) + return + } + console.info("Flushed data to file successfully.") + }) + }) + } ``` @@ -524,25 +623,33 @@ This method uses an asynchronous callback to return the result. flush(): Promise<void> -Saves the modification of this object to the **Preferences** instance and synchronizes the modification to the file. - -This method uses a promise to return the result. +Saves the modification to this **Preferences** instance and synchronizes the modification to the preference persistence file. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Return value | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result.| + | Promise<void> | Promise used to return the execution result.| - Example - ``` - let promiseflush = preferences.flush() - promiseflush.then(() => { - console.info("Flushed to file successfully.") - }).catch((err) => { - console.info("Flush to file failed with err: " + err) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + let promiseFlush = preferences.flush() + promiseFlush.then(() => { + console.info("Flushed data to file successfully.") + }).catch((err) => { + console.info("Failed to flush data to file, err: " + err) + }) + }).catch((err) => { + console.info("Failed to get the preferences, err: " + err) + }) + } ``` @@ -550,9 +657,7 @@ This method uses a promise to return the result. clear(callback: AsyncCallback<void>): void -Clears this **Preferences** object. - -This method uses an asynchronous callback to return the result. +Clears data of this **Preferences** instance. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core @@ -562,14 +667,25 @@ This method uses an asynchronous callback to return the result. | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - Example - ``` - preferences.clear(function (err) { - if (err) { - console.info("Clear to file failed with err: " + err) - return - } - console.info("Cleared to file successfully.") - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Failed to get the preferences, err: " + err) + return + } + preferences.clear(function (err) { + if (err) { + console.info("Failed to clear data, err: " + err) + return + } + console.info("Cleared to file successfully.") + }) + }) + } ``` @@ -577,25 +693,33 @@ This method uses an asynchronous callback to return the result. clear(): Promise<void> -Clears this **Preferences** object. - -This method uses a promise to return the result. +Clears data of this **Preferences** instance. This API uses a promise to return the result. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core - Return value | Type| Description| | -------- | -------- | - | Promise<void> | Promise used to return the result.| + | Promise<void> | Promise used to return the execution result.| - Example - ``` - let promiseclear = preferences.clear() - promiseclear.then(() => { - console.info("Cleared to file successfully.") - }).catch((err) => { - console.info("Clear to file failed with err: " + err) - }) + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + let promise = data_preferences.getPreferences(this.context, 'mystore') + promise.then((preferences) => { + let promiseClear = preferences.clear() + promiseClear.then(() => { + console.info("Cleared to file successfully.") + }).catch((err) => { + console.info("Failed to clear data, err: " + err) + }) + }).catch((err) => { + console.info("Failed to get the preferences, err: " + err) + }) + } ``` @@ -603,7 +727,7 @@ This method uses a promise to return the result. on(type: 'change', callback: Callback<{ key : string }>): void -Subscribes to data changes. When the value of the subscribed key changes, a callback will be invoked after the **flush()** method is executed. +Subscribes to data changes. When the value of the subscribed key changes, a callback will be invoked after **flush()** is executed. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core @@ -614,25 +738,36 @@ Subscribes to data changes. When the value of the subscribed key changes, a call | callback | Callback<{ key : string }> | Callback used to return data changes.| - Example - ``` - var observer = function (key) { - console.info("The key of " + key + " changed.") - } - preferences.on('change', observer) - preferences.put('startup', 'auto', function (err) { - if (err) { - console.info("Put the value of startup failed with err: " + err) - return + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + + var observer = function (key) { + console.info("The key of " + key + " changed.") } - console.info("Put the value of startup successfully.") - preferences.flush(function (err) { + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { if (err) { - console.info("Flush to file failed with err: " + err) + console.info("Failed to get the preferences, err: " + err) return } - console.info("Flushed to file successfully.") // observer will be called. + preferences.on('change', observer) + preferences.put('startup', 'auto', function (err) { + if (err) { + console.info("Failed to put the value of startup, err: " + err) + return + } + console.info("Put the value of startup successfully.") + preferences.flush(function (err) { + if (err) { + console.info("Failed to flush data to file, err: " + err) + return + } + console.info("Flushed data to file successfully.") // The observer will be called. + }) + }) }) - }) + } ``` @@ -651,9 +786,46 @@ Unsubscribes from data changes. | callback | Callback<{ key : string }> | Callback used to return data changes.| - Example - ``` - var observer = function (key) { - console.info("The key of " + key + " changed.") + ```ts + import Ability from '@ohos.application.Ability' + import data_preferences from '@ohos.data.preferences' + export default class MainAbility extends Ability { + var observer = function (key) { + console.info("The key of " + key + " changed.") + } + data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { + if (err) { + console.info("Failed to get the preferences, err: " + err) + return + } + preferences.on('change', observer) + preferences.put('startup', 'auto', function (err) { + if (err) { + console.info("Failed to put the value of startup, err: " + err) + return + } + console.info("Put the value of startup successfully.") + preferences.flush(function (err) { + if (err) { + console.info("Failed to flush data to file, err: " + err) + return + } + console.info("Flushed to file successfully.") // observer will be called. + preferences.off('change', observer) + }) + }) + }) } - preferences.off('change', observer) ``` + +## ValueType + +Enumerates the value types. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +| Name | Description | +| ------- | -------------------- | +| number | The value is a number. | +| string | The value is a string. | +| boolean | The value is of Boolean type.|