> This feature is supported since API Version 9. For the versions earlier than API Version 9, use [Lightweight Storage](../reference/apis/js-apis-data-storage.md) APIs.
> This feature is supported since API Version 9. For the versions earlier than API version 9, use [Lightweight Storage](../reference/apis/js-apis-data-storage.md) APIs.
## When to Use
Preferences are ideal for storing data frequently used by applications, but not for storing a large amount of data or data with frequent changes. The application data is persistently stored on a device in the form of files. Note that the instance accessed by an application contains all data of the file. The data is always loaded to the memory of the device until the application removes it from the memory. The application can perform data operations using the **Preferences** APIs.
Preferences are used for storing the data that is frequently used by applications, but not for storing a large amount of data or data frequently changed. The application data is persistently stored on a device in the form of files.
## Available APIs
Note that the instance accessed by an application contains all data of the file. The data is always loaded to the memory of the device until the application removes it from the memory. The application can call the **Preferences** APIs to manage data.
Preferences provide capabilities for processing data in the form of key-value (KV) pairs and support data persistence, modification, and query. In KV pairs, keys are of the string type, and values can be of the number, string, or Boolean type. For more APIs related to preferences, see [Preferences](../reference/apis/js-apis-data-preferences.md).
## Available APIs
### Creating a Preferences Instance
The **Preferences** module provides APIs for processing data in the form of key-value (KV) pairs and supports persistence of the KV pairs when required.
Create a **Preferences** instance for data operations. A **Preferences** instance is created after data is read from a specified file and loaded to the instance.
The key is of the string type, and the value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.
**Table 1** API for creating a **Preferences** instance
For details about **Preferences** APIs, see [Preferences](../reference/apis/js-apis-data-preferences.md).
| ohos.data.preferences | getPreferences(context: Context, name: string): Promise\<Preferences> | Obtains a **Preferences** instance for data operations.|
### Obtaining a **Preferences** Instance
### Writing Data
Obtain a **Preferences** instance for data operations. A **Preferences** instance is obtained after data is read from a specified file and loaded to the instance.
Call the **put()** method to add or modify data in a **Preferences** instance.
**Table 1** API for obtaining a **Preferences** instance
| Preferences | put(key: string, value: ValueType): Promise\<void> | Writes data with the value type of number, string, boolean, Array\<number>, Array\<string>, or Array\<boolean>.|
### Accessing Data
### Reading Data
Call the **put()** method to add or modify data in a **Preferences** instance.
Call the **get()** method to read data from a **Preferences** instance.
**Table 3** API for reading data
Call **getAll()** to obtain an **Object** instance that contains all KV pairs in a **Preferences** instance.
**Table 2** APIs for accessing **Preferences** data
| Preferences | put(key: string, value: ValueType): Promise\<void> | Writes data to the **Preferences** instance. The value to write can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| Preferences | get(key: string, defValue: ValueType): Promise\<ValueType> | Obtains data from the **Preferences** instance. The value to read can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| Preferences | getAll(): Promise<Object> | Obtains an **Object** instance that contains all KV pairs in the **Preferences** instance. |
| Preferences | get(key: string, defValue: ValueType): Promise\<ValueType> | Obtains data with the value type of number, string, boolean, Array\<number>, Array\<string>, or Array\<boolean>.|
### Storing Data Persistently
...
...
@@ -48,18 +51,18 @@ Call the **flush()** method to write the cached data back to its text file for p
| Preferences | flush(): Promise\<void> | Flushes data from the **Preferences** instance to its file through an asynchronous thread.|
### Observing Data Changes
You can subscribe to data changes. When the value of the subscribed key is changed by **flush()**, a callback will be invoked to return the new data.
You can subscribe to data changes. When the value of the subscribed key is changed and saved by **flush()**, a callback will be invoked to return the new data.
**Table 5** APIs for observing **Preferences** changes
| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void>; | Deletes a **Preferences** instance from the cache and deletes its file from the device.|
| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void>; | Removes a **Preferences** instance from the memory to release memory.
| ohos.data.preferences | deletePreferences(context: Context, name: string): Promise\<void> | Deletes a **Preferences** instance from the memory and its files from the device.|
| ohos.data.preferences | removePreferencesFromCache(context: Context, name: string): Promise\<void> | Removes a **Preferences** instance from the memory to release memory. |
## How to Develop
1. Import @ohos.data.preferences and related modules to the development environment.
console.info("Failed to get the value of startup with err: "+err)
console.info("Failed to get the value of 'startup'. Cause: "+err);
})
}).catch((err)=>{
console.info("Failed to get the preferences")})
console.info("Failed to get the preferences.")
});
```
5. Store data persistently.
...
...
@@ -132,38 +136,38 @@ Use the following APIs to delete a **Preferences** instance or data file.
6. Observe data changes.
Specify an observer as the callback to subscribe to data changes for an application. When the value of the subscribed key is changed and the **flush()** method is executed, the observe callback will be invoked to return the change.
Specify an observer as the callback to subscribe to data changes for an application. When the value of the subscribed key is changed and saved by **flush()**, the observer callback will be invoked to return the new data.
```js
varobserver=function(key){
console.info("The key of "+key+" changed.")
console.info("The key"+key+" changed.");
}
preferences.on('change',observer)
preferences.on('change',observer);
preferences.put('startup','auto',function(err){
if(err){
console.info("Failed to put the value of startup with err: "+err)
return
console.info("Failed to put the value of 'startup'. Cause: "+err);
return;
}
console.info("Put the value of startup successfully.")
console.info("Put the value of 'startup' successfully.");
preferences.flush(function(err){
if(err){
console.info("Failed to flush data to file with err: "+err)
return
console.info("Failed to flush data. Cause: "+err);
return;
}
console.info("Flushed to file successfully.")// Observer will be called.
console.info("Flushed data successfully.");// The observer will be called.
})
})
```
7. Delete the specified file.
Use the **deletePreferences** method to delete the **Preferences**singleton of the specified file from the memory, and delete the specified file, its backup file, and corrupted files. After the specified files are deleted, the application cannot use that instance to perform any data operation. Otherwise, data inconsistency will occur. The deleted data and files cannot be restored.
Use the **deletePreferences** method to delete the **Preferences**instance and its persistent file and backup and corrupted files. After the specified files are deleted, the application cannot use that instance to perform any data operation. Otherwise, data inconsistency will be caused. The deleted data and files cannot be restored.
Preferences are used for access and persistence operations on the data in the key-value structure. When an application accesses a **Preferences** instance, the data in the instance will be cached in the memory for faster access. The cached data can also be written back to the text file for persistent storage. Since file read and write consume system resources, you are advised to minimize the frequency of reading and writing persistent files.
Preferences are used to implement quick access and persistence of the data in the `key-value` structure.
After an application obtains a **Preferences** instance, the data in the instance will be cached in the memory for faster access.
The cached data can also be written to a text file for persistent storage. Since file read and write consume system resources, you are advised to minimize the frequency of reading and writing files.
You do not need to worry about the implementation of the database lock mechanism.
## Basic Concepts
-**Key-value data structure**
-**Key-value structure**
A type of data structure. The key is the unique identifier for a piece of data, and the value is the specific data being identified.
A type of data structure. The `Key` is the unique identifier for a piece of data, and the `Value` is the specific data being identified.
-**Non-relational database**
A database not in compliance with the atomicity, consistency, isolation, and durability (ACID) database management properties of relational data transactions. The data in a non-relational database is independent.
A database not in compliance with the atomicity, consistency, isolation, and durability (ACID) properties of relational data transactions. The data in a non-relational database is independent. The database that organizes data in the `key-value` structure is a non-relational database.
## Working Principles
When an application loads data from a **Preferences** file to a **Preferences** instance, the system stores the instance in the memory through a static container. Each file of an application or process has only one **Preferences** instance in the memory, till the application removes the instance from the memory or deletes the **Preferences** file.
When obtaining a **Preferences** instance, the application can read data from or write data to the instance. The data in the instance can be flushed to its **Preferences** file by calling the **flush()** method.
1. An application can load data from a **Preferences** persistent file to a **Preferences** instance. The system stores the **Preferences** instance in the memory through a static container. Each file of an application or process has only one **Preferences** instance in the memory, till the application removes the instance from the memory or deletes the **Preferences** persistent file.
2. When obtaining a **Preferences** instance, the application can read data from or write data to the instance. The data in the `Preferences` instance can be flushed to its **Preferences** persistent file by calling the **flush()** method.
**Figure 1**How **Preferences** work
**Figure 1**Working mechanism
## Constraints
-**Preferences** instances are loaded to the memory. To minimize non-memory overhead, the number of data records stored in a **Preferences** instance cannot exceed 10,000. Delete the instances that are no longer used in a timely manner.
- The key in key-value pairs is of the string type. It cannot be empty or exceed 80 bytes.
- The value of the string type in key-value pairs can be empty, but cannot exceed 8192 bytes if not empty.
- The `Key` in key-value pairs is of the string type. It cannot be empty or exceed 80 bytes.
- The `Value` of the string type in key-value pairs can be empty, but cannot exceed 8192 bytes if not empty.
Preferences provide capabilities for processing data in the form of key-value (KV) pairs and support lightweight data persistence, modification, and query. In KV pairs, the keys are of the string type, and the values can be of the number, string, Boolean, Array\<number>, Array\<string>, or Array\<boolean> type.
The **Preferences** module provides APIs for processing data in the form of key-value (KV) pairs and supports persistence of the KV pairs when required.
The key is of the string type, and the value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.
> **NOTE**<br/>
>
> 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.
Reads a **Preferences** persistence file and loads data to the **Preferences** instance for data operations. This API uses an asynchronous callback to return the result.
Obtains a **Preferences** instance. This API uses an asynchronous callback to return the result.
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback<[Preferences](#preferences)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **object** is the **Preferences** instance obtained. Otherwise, **err** is an error code.|
Reads a **Preferences** persistence file and loads data to the **Preferences** instance for data operations. This API uses a promise to return the result.
Obtains a **Preferences** instance. This API uses a promise to return the result.
Deletes a **Preferences** singleton instance, the persistence file and backup file, and corrupted files from the memory.
Once a **Preferences** 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 result.
Deletes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result.
If the **Preferences** instance has a persistent file, this API also deletes the persistent file.
The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
| name | string | Yes | Name of the **Preferences** instance to delete. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
Deletes a **Preferences** singleton instance, the persistence file and backup file, and corrupted files from the memory.
Once a **Preferences** 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 result.
Deletes a **Preferences** instance from the memory. This API uses a promise to return the result.
If the **Preferences** instance has a persistent file, this API also deletes the persistent file.
The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
Removes a **Preferences**singleton instance from the memory.
Removes a **Preferences**instance from the memory. This API 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 result.
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
| name | string | Yes | Name of the **Preferences** instance to remove. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
Removes a **Preferences**singleton instance from the memory.
Removes a **Preferences**instance from the memory. This API 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.
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
console.info("Removed preferences from cache successfully.")
console.info("Removed the preferences successfully.");
}).catch((err)=>{
console.info("Failed to remove preferences from cache, err: "+err)
console.info("Failed to remove the preferences. Cause: "+err);
})
```
## Preferences
Provides APIs for obtaining and modifying storage data.
Provides methods for obtaining and modifying data.
Before calling any method of **Preferences**, you must obtain a **Preferences** instance by using [data_preferences.getPreferences](#data_preferencesgetpreferences).
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.
Obtains the value of a key. This API uses an asynchronous callback to return the result. If the value is **null** or is not the type of the default value, the default value is returned.
| 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, a string, a Boolean value, an array of numbers, an array of strings, or a Boolean array.
| callback | AsyncCallback<ValueType> | Yes| Callback used to return the result.|
| key | string | Yes | Key of the data to obtain. It cannot be empty. |
| defValue | [ValueType](#valuetype) | Yes | Default value to be returned. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback<[ValueType](#valuetype)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is** undefined** and **data** is the value obtained. Otherwise, **err** is an error code.|
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.
Obtains the value of a key. This API uses a promise to return the result. If the value is **null** or is not the type of the default value, the default value is returned.
| 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, a string, a Boolean value, an array of numbers, an array of strings, or a Boolean array.
| key | string | Yes | Key of the data to obtain. It cannot be empty. |
| defValue | [ValueType](#valuetype) | Yes | Default value to be returned. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<ValueType> | Promise used to return the result.|
| callback | AsyncCallback<Object> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **value** is the **Object** instance obtained. Otherwise, **err** is an error code.|
**Example**
```ts
```js
preferences.getAll(function(err,value){
if(err){
console.info("getAll failed, err: "+err)
return
console.info("Failed to get all KV pairs. Cause: "+err);
Puts a new value to this **Preferences** instance and its persistence file. This API uses an asynchronous callback to return the result.
Writes data to this **Preferences** instance. This API uses an asynchronous callback to return the result. You can use [flush](#flush) to make the **Preferences** instance persistent.
| key | string | Yes| Key of the data. It cannot be empty.|
| value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, a string, a Boolean value, an array of numbers, an array of strings, or a Boolean array.|
| callback | AsyncCallback<void> | Yes| Callback that returns no value.|
| key | string | Yes | Key of the data. It cannot be empty. |
| value | [ValueType](#valuetype) | Yes | Value to write. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is undefined. Otherwise, **err** is an error code. |
**Example**
```ts
```js
preferences.put('startup','auto',function(err){
if(err){
console.info("Failed to put the value of startup, err: "+err)
return
console.info("Failed to put the value of 'startup'. Cause: "+err);
return;
}
console.info("Put the value of startup successfully.")
console.info("Put the value of 'startup' successfully.");
})
```
...
...
@@ -345,28 +365,28 @@ preferences.put('startup', 'auto', function (err) {
Puts a new value to this **Preferences** instance and its persistence file. This API uses a promise to return the result.
Writes data to this **Preferences** instance. This API uses a promise to return the result. You can use [flush](#flush) to make the **Preferences** instance persistent.
| key | string | Yes| Key of the data. It cannot be empty.|
| value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, a string, a Boolean value, an array of numbers, an array of strings, or a Boolean array.|
| key | string | Yes | Key of the data. It cannot be empty. |
| value | [ValueType](#valuetype) | Yes | Value to write. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<void> | Promise that returns no value.|
| key | string | Yes| Key of the data to check. It cannot be empty.|
| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. It returns **true** if the **Preferences** instance contains data with the given key and returns **false** otherwise.|
| key | string | Yes | Key of the data to check. It cannot be empty. |
| callback | AsyncCallback<boolean> | Yes | Callback invoked to return the result. If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.|
**Example**
```ts
```js
preferences.has('startup',function(err,isExist){
if(err){
console.info("Failed to check the key of startup, err: "+err)
return
console.info("Failed to check the key 'startup'. Cause: "+err);
return;
}
if(isExist){
console.info("The key of startup is contained.")
console.info("The key 'startup' is contained.");
}else{
console.info("The key of startup is not contained.")
console.info("The key 'startup' is not contained.");
}
})
```
...
...
@@ -405,31 +425,32 @@ preferences.has('startup', function (err, isExist) {
has(key: string): Promise<boolean>
Checks whether this **Preferences** instance contains data with a given key. This API uses a promise to return the result.
Checks whether this **Preferences** instance contains data with the given key. This API uses a promise to return the result.
| 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. It returns **true** if the **Preferences** instance contains data with the given key and returns **false** otherwise.|
| Promise<boolean> | Promise used to return the result. If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.|
**Example**
```ts
letpromise=preferences.has('startup')
```js
letpromise=preferences.has('startup');
promise.then((isExist)=>{
if(isExist){
console.info("The key of startup is contained.")
console.info("The key 'startup' is contained.");
}else{
console.info("The key of startup is not contained.")
console.info("The key 'startup' is not contained.");
}
}).catch((err)=>{
console.info("Failed to check the key of startup, err: "+err)
console.info("Failed to check the key 'startup'. Cause: "+err);
| key | string | Yes | Key of the KV pair to delete. It cannot be empty. |
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
**Example**
```ts
```js
preferences.delete('startup',function(err){
if(err){
console.info("Failed to delete startup key, err: "+err)
return
console.info("Failed to delete the key 'startup'. Cause: "+err);
return;
}
console.info("Deleted startup key successfully.")
console.info("Deleted the key 'startup'.");
})
```
...
...
@@ -464,27 +485,27 @@ preferences.delete('startup', function (err) {
delete(key: string): Promise<void>
Deletes a KV pair of the specified key from this **Preferences** instance. This API uses a promise to return the result.
Deletes a KV pair from this **Preferences** instance. This API uses a promise to return the result.
| Promise<void> | Promise that returns no value.|
**Example**
```ts
letpromise=preferences.delete('startup')
```js
letpromise=preferences.delete('startup');
promise.then(()=>{
console.info("Deleted startup key successfully.")
console.info("Deleted the key 'startup'.");
}).catch((err)=>{
console.info("Failed to delete startup key, err: "+err)
console.info("Failed to delete the key 'startup'. Cause: "+err);
})
```
...
...
@@ -493,23 +514,23 @@ promise.then(() => {
flush(callback: AsyncCallback<void>): void
Saves the modification to this **Preferences** instance and synchronizes the modification to the **Preferences** persistence file. This API uses an asynchronous callback to return the result.
Saves the data of the **Preferences** instance to a file asynchronously. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
**Example**
```ts
```js
preferences.flush(function(err){
if(err){
console.info("Failed to flush data to file, err: "+err)
return
console.info("Failed to flush data. Cause: "+err);
return;
}
console.info("Flushed data to file successfully.")
Saves the modification to this **Preferences** instance and synchronizes the modification to the **Preferences** persistence file. This API uses a promise to return the result.
Saves the data of the **Preferences** instance to a file asynchronously. This API uses a promise to return the result.
| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
**Example**
```ts
```js
preferences.clear(function(err){
if(err){
console.info("Failed to clear data, err: "+err)
return
console.info("Failed to clear data. Cause: "+err);
| type | string | Yes| Event type. The value **change** indicates data change events.|
| callback | Callback<{ key : string }> | No| Callback used to return data changes. If this parameter is left empty, all callbacks for data changes will be canceled.|
| type | string | Yes | Event type to unsubscribe from. The value **change** indicates data change events. |
| callback | Callback<{ key : string }> | No | Callback to unregister. If this parameter is left blank, the callbacks used to subscribing to all data changes will be unregistered.|
