diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 4e072772748b27c506c29b5ecf6d6fc8c3c2f1b3..b1e826787f33151f1dd4eba2ff2078c35cbaab9d 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -22,12 +22,13 @@ - [User Authentication](js-apis-useriam-userauth.md) - [Access Control](js-apis-abilityAccessCtrl.md) - Data Management - - [Lightweight Storage (deprecated since 8)](js-apis-data-storage.md) + - [Lightweight Storage9+](js-apis-data-preferences.md) + - [Lightweight Storage](js-apis-data-storage.md) - [Distributed Data Management](js-apis-distributed-data.md) - [Relational Database](js-apis-data-rdb.md) - [Result Set](js-apis-data-resultset.md) - [DataAbilityPredicates](js-apis-data-ability.md) - - [Settings](js-apis-settings.md) + - [Settings](js-apis-settings.md) - File Management - [File Management](js-apis-fileio.md) - [Statfs](js-apis-statfs.md) diff --git a/en/application-dev/reference/apis/js-apis-data-preferences.md b/en/application-dev/reference/apis/js-apis-data-preferences.md new file mode 100644 index 0000000000000000000000000000000000000000..964159792a1c87f4d0e1bec1493405c164a9500f --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-data-preferences.md @@ -0,0 +1,623 @@ +# Lightweight Storage + +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. + + +> ![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' +``` + +## Attributes + +**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.| + + +## 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. + + +**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.| + | callback | AsyncCallback<[Preferences](#preferences)> | Yes| Callback used to return the execution result.| + +- Example + ``` + 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.putSync('startup', 'auto') + preferences.flushSync() + }) + ``` + + +## data_Preferences.getPreferences + +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. + +**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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<[Preferences](#preferences)> | Promise used to return the result.| + +- Example + ``` + 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.putSync('startup', 'auto') + preferences.flushSync() + }).catch((err) => { + console.info("Get the preferences failed, path: " + path + '/mystore') + }) + ``` + + +## data_Preferences.deletePreferences + +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. + +**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.| + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +- Example + ``` + 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.") + }) + ``` + + +## data_Preferences.deletePreferences + +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. + +**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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + ``` + 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) + }) + ``` + + +## data_Preferences.removePreferencesFromCache + +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. + +This method uses an asynchronous callback 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.| + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +- Example + ``` + 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.") + }) + ``` + + +## data_Preferences.removePreferencesFromCache + +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. + +This method uses an asynchronous callback 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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + ``` + 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) + }) + ``` + + +## Preferences + +Provides APIs for obtaining and modifying storage data. + + +### get + +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. + +**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.| + | 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) + }) + ``` + + +### get + +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. + +**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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<ValueType> | Promise used to return the 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) + }) + ``` + + +### put + +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. + +**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.| + | 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.") + }) + ``` + + +### put + +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 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 to modify. It cannot be empty.| + | value | 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.| + +- 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) + }) + ``` + + +### has + +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. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | key | string | Yes| Key of the data. 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.| + +- 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.") + } + }) + ``` + + +### has + +has(key: string): Promise<boolean> + +Checks whether the **Preference** object contains data with a given key. + +This method 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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the 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) + }) + ``` + + +### delete + +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. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | key | string | Yes| Key of the data. 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.") + }) + ``` + + +### delete + +delete(key: string): Promise<void> + +Deletes data with the specified key from this **Preference** object. + +This method 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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the 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) + }) + ``` + + +### flush + +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. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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.") + }) + ``` + + +### flush + +flush(): Promise<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. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the 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) + }) + ``` + + +### clear + +clear(callback: AsyncCallback<void>): void + +Clears this **Preferences** object. + +This method uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | 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.") + }) + ``` + + +### clear + +clear(): Promise<void> + +Clears this **Preferences** object. + +This method uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the 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) + }) + ``` + + +### on('change') + +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. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Description| + | -------- | -------- | -------- | + | type | string | Event type. The value **change** indicates data change events.| + | 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') + preferences.flush() // observer will be called. + ``` + + +### off('change') + +off(type: 'change', callback: Callback<{ key : string }>): void + +Unsubscribes from data changes. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Description| + | -------- | -------- | -------- | + | type | string | Event type. The value **change** indicates data change events.| + | callback | Callback<{ key : string }> | Callback used to return data changes.| + +- Example + ``` + var observer = function (key) { + console.info("The key of " + key + " changed.") + } + preferences.off('change', observer) + ``` diff --git a/en/application-dev/reference/apis/js-apis-data-storage.md b/en/application-dev/reference/apis/js-apis-data-storage.md index b8dd0be285a7e325ee0f5a2e7483bdb5d04400f7..33ee7b2bc74f028e0a5f5f61e91d84ec3b103b51 100644 --- a/en/application-dev/reference/apis/js-apis-data-storage.md +++ b/en/application-dev/reference/apis/js-apis-data-storage.md @@ -1,1614 +1,824 @@ -# Lightweight Storage +# Lightweight Storage -Lightweight storage provides applications with data processing capability and allows applications to perform lightweight data storage and query. Data is stored in key-value pairs. Keys are of the string type, and values can be of the numeric, string, or Boolean type. +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. ->![](../../public_sys-resources/icon-note.gif) **NOTE** -> ->The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. -## Modules to Import +> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
The APIs of this module are no longer maintained since API Version 9. You are advised to use [@ohos.data.preferences](js-apis-data-preferences.md). + + +## Modules to Import ``` import dataStorage from '@ohos.data.storage' ``` -## System Capabilities -SystemCapability.DistributedDataManager.Preferences.Core - - -## Attributes - - - - - - - - - - - - - - - - - - - - - - -

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.

-
- -## dataStorage.getStorageSync - -getStorageSync\(path: string\): Storage - -Reads a specified file and loads the data to the **Storage** instance for data operations in synchronous mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Storage

-

Storage instance used for data storage operations

-
- -- Example: - - ``` - import dataStorage from '@ohos.data.storage' - import featureAbility from '@ohos.ability.featureAbility' - - (async () => { - var context = featureAbility.getContext() - var path = await context.getFilesDir() - let storage = dataStorage.getStorageSync(path + '/mystore') +## Attributes + +**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.| + + +## dataStorage.getStorageSync + +getStorageSync(path: string): Storage + +Reads a file and loads the data to the **Storage** instance in synchronous mode. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + +- Return value + | Type| Description| + | -------- | -------- | + | [Storage](#storage) | **Storage** instance used for data storage operations.| + +- Example + ``` + import dataStorage from '@ohos.data.storage' + import featureAbility from '@ohos.ability.featureAbility' + + var context = featureAbility.getContext() + var path = await context.getFilesDir() + let storage = dataStorage.getStorageSync(path + '/mystore') + storage.putSync('startup', 'auto') + storage.flushSync() + ``` + + +## dataStorage.getStorage + +getStorage(path: string, callback: AsyncCallback<Storage>): void + +Reads a file and loads the data to the **Storage** instance. This method uses an asynchronous callback to return the execution result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + | callback | AsyncCallback<[Storage](#storage)> | Yes| Callback used to return the execution result.| + +- Example + ``` + import dataStorage from '@ohos.data.storage' + import featureAbility from '@ohos.ability.featureAbility' + + var context = featureAbility.getContext() + var path = await context.getFilesDir() + dataStorage.getStorage(path + '/mystore', function (err, storage) { + if (err) { + console.info("Get the storage failed, path: " + path + '/mystore') + return; + } storage.putSync('startup', 'auto') storage.flushSync() - })() + }) ``` -## dataStorage.getStorage - -getStorage\(path: string, callback: AsyncCallback\): void - -Reads a specified file and loads the data to the **Storage** instance for data operations. This method uses a callback to return the execution result. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-

callback

-

AsyncCallback<Storage>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - import dataStorage from '@ohos.data.storage' - import featureAbility from '@ohos.ability.featureAbility' - - (async () => { - var context = featureAbility.getContext() - var path = await context.getFilesDir() - dataStorage.getStorage(path + '/mystore', function (err, storage) { - if (err) { - console.info("Get the storage failed, path: " + path + '/mystore') - return; - } - storage.putSync('startup', 'auto') - storage.flushSync() - }) - })() +## dataStorage.getStorage + +getStorage(path: string): Promise<Storage> + +Reads a file and loads the data to the **Storage** instance. This method uses a promise to return the execution result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<[Storage](#storage)> | Promise used to return the result.| + +- Example + ``` + import dataStorage from '@ohos.data.storage' + import featureAbility from '@ohos.ability.featureAbility' + + var context = featureAbility.getContext() + var path = await context.getFilesDir() + let promisegetSt = dataStorage.getStorage(path + '/mystore') + promisegetSt.then((storage) => { + storage.putSync('startup', 'auto') + storage.flushSync() + }).catch((err) => { + console.info("Get the storage failed, path: " + path + '/mystore') + }) ``` -## dataStorage.getStorage - -getStorage\(path: string\): Promise - -Reads a specified file and loads the data to the **Storage** instance for data operations. This method uses a promise to return the execution result. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<Storage>

-

Promise used to return the result.

-
- -- Example: - - ``` - import dataStorage from '@ohos.data.storage' - import featureAbility from '@ohos.ability.featureAbility' - - (async () => { - var context = featureAbility.getContext() - var path = await context.getFilesDir() - let promise = dataStorage.getStorage(path + '/mystore') - promise.then((storage) => { - storage.putSync('startup', 'auto') - storage.flushSync() - }).catch((err) => { - console.info("Get the storage failed, path: " + path + '/mystore') - }) - }() +## dataStorage.deleteStorageSync + +deleteStorageSync(path: string): void + +Deletes the singleton **Storage** instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the **Storage** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This method uses a synchronous mode. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + +- Example + ``` + dataStorage.deleteStorageSync(path + '/mystore') + ``` + + +## dataStorage.deleteStorage + +deleteStorage(path: string, callback: AsyncCallback<void>): void + +Deletes the singleton **Storage** instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the **Storage** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This method uses an asynchronous callback to return the execution result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +- Example ``` + dataStorage.deleteStorage(path + '/mystore', function (err) { + if (err) { + console.info("Deleted failed with err: " + err) + return + } + console.info("Deleted successfully.") + }) + ``` + +## dataStorage.deleteStorage -## dataStorage.deleteStorageSync - -deleteStorageSync\(path: string\): void - -Removes the singleton **Storage** instance of the specified file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified file is deleted, the **Storage** instance cannot be used to perform any data operation. Otherwise, data inconsistency will occur. This method uses a synchronous mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-
- -- Example: - - ``` - dataStorage.deleteStorageSync(path + '/mystore') - ``` - - -## dataStorage.deleteStorage - -deleteStorage\(path: string, callback: AsyncCallback\) - -Removes the singleton **Storage** instance of the specified file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified file is deleted, the **Storage** instance cannot be used to perform any data operation. Otherwise, data inconsistency will occur. This method uses an asynchronous callback to return the execution result. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - dataStorage.deleteStorage(path + '/mystore', function (err) { - if (err) { - console.info("Deleted failed with err: " + err) - return - } - console.info("Deleted successfully.") - }) - ``` - - -## dataStorage.deleteStorage - -deleteStorage\(path: string\): Promise - -Removes the singleton **Storage** instance of the specified file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified file is deleted, the **Storage** instance cannot be used to perform any data operation. Otherwise, data inconsistency will occur. This method uses a promise to return the execution result. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = dataStorage.deleteStorage(path + '/mystore') - promise.then(() => { - console.info("Deleted successfully.") - }).catch((err) => { - console.info("Deleted failed with err: " + err) - }) - ``` - - -## dataStorage.removeStorageFromCacheSync - -removeStorageFromCacheSync\(path: string\): void - -Removes the singleton **Storage** instance of the specified file from the memory. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. +deleteStorage(path: string): Promise<void> + +Deletes the singleton **Storage** instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the **Storage** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This method uses a promise to return the execution result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + ``` + let promisedelSt = dataStorage.deleteStorage(path + '/mystore') + promisedelSt.then(() => { + console.info("Deleted successfully.") + }).catch((err) => { + console.info("Deleted failed with err: " + err) + }) + ``` + + +## dataStorage.removeStorageFromCacheSync + +removeStorageFromCacheSync(path: string): void + +Removes the singleton **Storage** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. This method uses a synchronous mode. -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-
- -- Example: - - ``` - dataStorage.removeStorageFromCacheSync(path + '/mystore') - ``` - - -## dataStorage.removeStorageFromCache - -removeStorageFromCache\(path: string, callback: AsyncCallback\): void - -Removes the singleton **Storage** instance of the specified file from the memory. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-

callback

-

AsyncCallback<Storage>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - dataStorage.removeStorageFromCache(path + '/mystore', function (err) { - if (err) { - console.info("Removed storage from cache failed with err: " + err) - return - } - console.info("Removed storage from cache successfully.") - }) - ``` - - -## dataStorage.removeStorageFromCache - -removeStorageFromCache\(path: string\): Promise - -Removes the singleton **Storage** instance of the specified file from the memory. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

path

-

string

-

Yes

-

Storage path of the application internal data

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = dataStorage.removeStorageFromCache(path + '/mystore') - promise.then(() => { - console.info("Removed storage from cache successfully.") - }).catch((err) => { - console.info("Removed storage from cache failed with err: " + err) - }) - ``` - - -## Storage +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + +- Example + ``` + dataStorage.removeStorageFromCacheSync(path + '/mystore') + ``` + + +## dataStorage.removeStorageFromCache + +removeStorageFromCache(path: string, callback: AsyncCallback<void>): void + +Removes the singleton **Storage** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. + +This method uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +- Example + ``` + dataStorage.removeStorageFromCache(path + '/mystore', function (err) { + if (err) { + console.info("Removed storage from cache failed with err: " + err) + return + } + console.info("Removed storage from cache successfully.") + }) + ``` + + +## dataStorage.removeStorageFromCache + +removeStorageFromCache(path: string): Promise<void> + +Removes the singleton **Storage** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. + +This method uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | path | string | Yes| Path of the target file.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + ``` + let promiserevSt = dataStorage.removeStorageFromCache(path + '/mystore') + promiserevSt.then(() => { + console.info("Removed storage from cache successfully.") + }).catch((err) => { + console.info("Removed storage from cache failed with err: " + err) + }) + ``` + + +## Storage Provides APIs for obtaining and modifying storage data. -### getSync -getSync\(key: string, defValue: ValueType\): ValueType +### getSync + +getSync(key: string, defValue: ValueType): 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 synchronous mode. -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-

defValue

-

ValueType

-

Yes

-

Default value to be returned if the value of the specified key does not exist. The value can be a number, string, or Boolean value.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

ValueType

-

Value corresponding to the specified key. If the value is null or not in the default value format, the default value is returned.

-
- -- Example: - - ``` - let value = storage.getSync('startup', 'default') - console.info("The value of startup is " + value) - ``` - - -### get - -get\(key: string, defValue: ValueType, callback: AsyncCallback\): void +**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 if the value of the specified key does not exist. It can be a number, string, or Boolean value.| + +- Return value + | Type| Description| + | -------- | -------- | + | ValueType | Value corresponding to the specified key. If the value is null or not in the default value format, the default value is returned.| + +- Example + ``` + let value = storage.getSync('startup', 'default') + console.info("The value of startup is " + value) + ``` + + +### get + +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 mode. - -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-

defValue

-

ValueType

-

Yes

-

Default value to be returned. The value can be a number, string, or Boolean value.

-

callback

-

AsyncCallback<ValueType>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - storage.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) - }) - ``` - - -### get - -get\(key: string, defValue: ValueType\): Promise +This method 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.| + | callback | AsyncCallback<ValueType> | Yes| Callback used to return the execution result.| + +- Example + ``` + storage.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) + }) + ``` + + +### get + +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 an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-

defValue

-

ValueType

-

Yes

-

Default value to be returned. The value can be a number, string, or Boolean value.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<ValueType>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = storage.get('startup', 'default') - promise.then((value) => { - console.info("The value of startup is " + value) - }).catch((err) => { - console.info("Get the value of startup failed with err: " + err) - }) - ``` - - -### putSync - -putSync\(key: string, value: ValueType\): void - -Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush\(\)** or **flushSync\(\)**. +This method 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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<ValueType> | Promise used to return the result.| + +- Example + ``` + let promiseget = storage.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) + }) + ``` -This method uses a synchronous mode. -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data to be modified. It cannot be empty.

-

value

-

ValueType

-

Yes

-

New value. The value can be a number, string, or Boolean value.

-
- -- Example: - - ``` - storage.putSync('startup', 'auto') - ``` - - -### put - -put\(key: string, value: ValueType, callback: AsyncCallback\): void - -Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush\(\)** or **flushSync\(\)**. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data to be modified. It cannot be empty.

-

value

-

ValueType

-

Yes

-

New value. The value can be a number, string, or Boolean value.

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - storage.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.") - }) - ``` - - -### put - -put\(key: string, value: ValueType\): Promise - -Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush\(\)** or **flushSync\(\)**. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data to be modified. It cannot be empty.

-

value

-

ValueType

-

Yes

-

New value. The value can be a number, string, or Boolean value.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = storage.put('startup', 'auto') - promise.then(() => { - console.info("Put the value of startup successfully.") - }).catch((err) => { - console.info("Put the value of startup failed with err: " + err) - }) - ``` - - -### hasSync - -hasSync\(key: string\): boolean - -Checks whether the storage object contains data with the specified key. +### putSync + +putSync(key: string, value: ValueType): void + +Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush()** or **flushSync()**. This method uses a synchronous mode. -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

boolean

-

Returns true if the storage object contains data with the specified key; returns false otherwise.

-
- -- Example: - - ``` - let isExist = storage.hasSync('startup') - if (isExist) { - console.info("The key of startup is contained.") - } - ``` - - -### has - -has\(key: string, callback: AsyncCallback\): boolean - -Checks whether the storage object contains data with the specified key. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-

callback

-

AsyncCallback<boolean>

-

Yes

-

Callback used to return the result.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

boolean

-

Returns true if the storage object contains data with the specified key; returns false otherwise.

-
- -- Example: - - ``` - storage.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.") - } - }) - ``` - - -### has - -has\(key: string\): Promise - -Checks whether the storage object contains data with the specified key. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<boolean>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = storage.has('startup') - promise.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) - }) - ``` - - -### deleteSync - -deleteSync\(key: string\): void - -Deletes the data with the specified key from this storage object. +**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.| + +- Example + ``` + storage.putSync('startup', 'auto') + ``` + + +### put + +put(key: string, value: ValueType, callback: AsyncCallback<void>): void + +Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush()** or **flushSync()**. + +This method 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 to modify. It cannot be empty.| + | value | 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 + ``` + storage.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.") + }) + ``` + + +### put + +put(key: string, value: ValueType): Promise<void> + +Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush()** or **flushSync()**. + +This method 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 to modify. It cannot be empty.| + | value | 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.| + +- Example + ``` + let promiseput = storage.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) + }) + ``` + + +### hasSync + +hasSync(key: string): boolean + +Checks whether the storage object contains data with a given key. This method uses a synchronous mode. -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-
- -- Example: - - ``` - storage.deleteSync('startup') - ``` - - -### delete - -delete\(key: string, callback: AsyncCallback\): void - -Deletes the data with the specified key from this storage object. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data. It cannot be empty.

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - storage.delete('startup', function (err) { - if (err) { - console.info("Delete startup key failed with err: " + err) - return - } - console.info("Deleted startup key successfully.") - }) - ``` - - -### delete - -delete\(key: string\): Promise - -Deletes the data with the specified key from this storage object. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

Yes

-

Key of the data.

-
- -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = storage.delete('startup') - promise.then(() => { - console.info("Deleted startup key successfully.") - }).catch((err) => { - console.info("Delete startup key failed with err: " + err) - }) - ``` - - -### flushSync - -flushSync\(\): void - -Saves the modification of the current object to the current **Storage** instance and synchronizes the modification to the file. +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | key | string | Yes| Key of the data. It cannot be empty.| + +- Return value + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.| + +- Example + ``` + let isExist = storage.hasSync('startup') + if (isExist) { + console.info("The key of startup is contained.") + } + ``` + + +### has + +has(key: string, callback: AsyncCallback<boolean>): boolean + +Checks whether the storage object contains data with a given key. + +This method 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.| + | callback | AsyncCallback<boolean> | Yes| Callback used to return the execution result.| + +- Return value + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.| + +- Example + ``` + storage.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.") + } + }) + ``` + + +### has + +has(key: string): Promise<boolean> + +Checks whether the storage object contains data with a given key. + +This method 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.| + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result.| + +- Example + ``` + let promisehas = storage.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) + }) + ``` + + +### deleteSync + +deleteSync(key: string): void + +Deletes data with the specified key from this storage object. This method uses a synchronous mode. -- Example: +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | key | string | Yes| Key of the data. It cannot be empty.| + +- Example + ``` + storage.deleteSync('startup') + ``` + + +### delete + +delete(key: string, callback: AsyncCallback<void>): void + +Deletes data with the specified key from this storage object. + +This method 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.| + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| + +- Example + ``` + storage.delete('startup', function (err) { + if (err) { + console.info("Delete startup key failed with err: " + err) + return + } + console.info("Deleted startup key successfully.") + }) + ``` + - ``` - storage.flushSync() - ``` +### delete +delete(key: string): Promise<void> -### flush +Deletes data with the specified key from this storage object. -flush\(callback: AsyncCallback\): void +This method uses an asynchronous callback to return the result. -Saves the modification of the current object to the current **Storage** instance and stores the modification to the file in an asynchronous mode. +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core -This method uses an asynchronous mode. +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | key | string | Yes| Key of the data.| -- Parameters +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to return the result.

-
+- Example + ``` + let promisedel = storage.delete('startup') + promisedel.then(() => { + console.info("Deleted startup key successfully.") + }).catch((err) => { + console.info("Delete startup key failed with err: " + err) + }) + ``` + + +### flushSync + +flushSync(): void + +Saves the modification of this object to the **Storage** instance and synchronizes the modification to the file. + +This method uses a synchronous mode. -- Example: +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core - ``` - storage.flush(function (err) { - if (err) { - console.info("Flush to file failed with err: " + err) - return - } - console.info("Flushed to file successfully.") - }) - ``` +- Example + ``` + storage.flushSync() + ``` + + +### flush +flush(callback: AsyncCallback<void>): void -### flush +Saves the modification of this object to the **Storage** instance and synchronizes the modification to the file. -flush\(\): Promise +This method uses an asynchronous callback to return the result. -Saves the modification of the current object to the current **Storage** instance and stores the modification to the file in an asynchronous mode. +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core -This method uses an asynchronous mode. +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| -- Return values +- Example + ``` + storage.flush(function (err) { + if (err) { + console.info("Flush to file failed with err: " + err) + return + } + console.info("Flushed to file successfully.") + }) + ``` - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to return the result.

-
-- Example: +### flush - ``` - let promise = storage.flush() - promise.then(() => { - console.info("Flushed to file successfully.") - }).catch((err) => { - console.info("Flush to file failed with err: " + err) - }) - ``` +flush(): Promise<void> +Saves the modification of this object to the **Storage** instance and synchronizes the modification to the file. -### clearSync +This method uses an asynchronous callback to return the result. -clearSync\(\): void +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core -Clears all data in a storage object. +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + ``` + let promiseflush = storage.flush() + promiseflush.then(() => { + console.info("Flushed to file successfully.") + }).catch((err) => { + console.info("Flush to file failed with err: " + err) + }) + ``` + + +### clearSync + +clearSync(): void + +Clears this **Storage** object. This method uses a synchronous mode. -- Example: +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Example + ``` + storage.clearSync() + ``` + + +### clear + +clear(callback: AsyncCallback<void>): void + +Clears this **Storage** object. + +This method uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the execution result.| - ``` - storage.clearSync() - ``` +- Example + ``` + storage.clear(function (err) { + if (err) { + console.info("Clear to file failed with err: " + err) + return + } + console.info("Cleared to file successfully.") + }) + ``` + + +### clear + +clear(): Promise<void> + +Clears this **Storage** object. + +This method uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Return value + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +- Example + ``` + let promiseclear = storage.clear() + promiseclear.then(() => { + console.info("Cleared to file successfully.") + }).catch((err) => { + console.info("Clear to file failed with err: " + err) + }) + ``` + + +### on('change') + +on(type: 'change', callback: Callback<StorageObserver>): void + +Subscribes to data changes. The **StorageObserver** needs to be implemented. When the value of the key subscribed to is changed, a callback will be invoked after **flush()** or **flushSync()** is executed. +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Description| + | -------- | -------- | -------- | + | type | string | Event type. The value **change** indicates data change events.| + | callback | Callback<[StorageObserver](#storageobserver)> | Callback used to return data changes.| + +- Example + ``` + var observer = function (key) { + console.info("The key of " + key + " changed.") + } + storage.on('change', observer) + storage.putSync('startup', 'auto') + storage.flushSync() // observer will be called. + ``` + + +### off('change') + +off(type: 'change', callback: Callback<StorageObserver>): void -### clear - -clear\(callback: AsyncCallback\): void - -Clears all data in a storage object. - -This method uses an asynchronous mode. - -- Parameters - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

callback

-

AsyncCallback<void>

-

Yes

-

Callback used to return the result.

-
- -- Example: - - ``` - storage.clear(function (err) { - if (err) { - console.info("Clear to file failed with err: " + err) - return - } - console.info("Cleared to file successfully.") - }) - ``` - - -### clear - -clear\(\): Promise - -Clears all data in a storage object. - -This method uses an asynchronous mode. - -- Return values - - - - - - - - - - -

Type

-

Description

-

Promise<void>

-

Promise used to return the result.

-
- -- Example: - - ``` - let promise = storage.clear() - promise.then(() => { - console.info("Cleared to file successfully.") - }).catch((err) => { - console.info("Clear to file failed with err: " + err) - }) - ``` - - -### on \('change'\) - -on\(type: 'change', callback: Callback\): void - -Subscribes to data changes. The **StorageObserver** needs to be implemented. When the value of the key subscribed to is changed, a callback will be invoked after **flush\(\)** or **flushSync\(\)** is executed. - -- Parameters - - - - - - - - - - - - - - - - -

Name

-

Type

-

Description

-

type

-

string

-

Event type. The value change indicates a data change event.

-

callback

-

Callback<StorageObserver>

-

Callback object.

-
- -- Example: - - ``` - var observer = function (key) { - console.info("The key of " + key + " changed.") - } - storage.on('change', observer) - storage.putSync('startup', 'auto') - storage.flushSync() // observer will be called. - ``` - - -### off \('change'\) - -off\(type: 'change', callback: Callback\): void - Unsubscribes from data changes. -- Parameters - - - - - - - - - - - - - - - - -

Name

-

Type

-

Description

-

type

-

string

-

Event type. The value change indicates a data change event.

-

callback

-

Callback<StorageObserver>

-

Callback object to be canceled.

-
- -- Example: - - ``` - var observer = function (key) { - console.info("The key of " + key + " changed.") - } - storage.off('change', observer) - ``` - - -## StorageObserver - - - - - - - - - - - - - - -

Name

-

Type

-

Mandatory

-

Description

-

key

-

string

-

No

-

Data changed

-
+**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +- Parameters + | Name| Type| Description| + | -------- | -------- | -------- | + | type | string | Event type. The value **change** indicates data change events.| + | callback | Callback<[StorageObserver](#storageobserver)> | Callback used to return data changes.| + +- Example + ``` + var observer = function (key) { + console.info("The key of " + key + " changed.") + } + storage.off('change', observer) + ``` + + +## StorageObserver + +**System capability**: SystemCapability.DistributedDataManager.Preferences.Core + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| key | string | No| Data changed.| diff --git a/en/website-directory.md b/en/website-directory.md index e7324e098e2bb798e1d0f17e15fff4ed7b1ea071..a8be57bf1225286780a9111c88c35cc05fa1e789 100644 --- a/en/website-directory.md +++ b/en/website-directory.md @@ -1268,6 +1268,8 @@ ——>——>——>——> Data Management +——>——>——>——>——> [Lightweight Storage](application-dev/reference/apis/js-apis-data-preferences.md) + ——>——>——>——>——> [Lightweight Storage (deprecated since 8)](application-dev/reference/apis/js-apis-data-storage.md) ——>——>——>——>——> [Distributed Data Management](application-dev/reference/apis/js-apis-distributed-data.md)