harmony 鸿蒙Preferences Development
Preferences Development
NOTE
This feature is supported since API version 9. For the versions earlier than API version 9, use Lightweight Storage APIs.
When to Use
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.
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.
Available APIs
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.
For details about Preferences APIs, see Preferences.
Obtaining a Preferences Instance
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.
Table 1 API for obtaining a Preferences instance
Bundle Name | API | Description |
---|---|---|
ohos.data.preferences | getPreferences(context: Context, name: string): Promise<Preferences> | Obtains a Preferences instance. |
Processing Data
Call put() to add or modify data in a Preferences instance.
Call get() to read data from a Preferences instance.
Call getAll() to obtain an Object instance that contains all KV pairs in a Preferences instance.
Call delete() to delete the KV pair of the specified key from the Preferences instance.
Table 2 APIs for processing Preferences data
Class | API | Description |
---|---|---|
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 | delete(key: string): Promise<void> | Deletes the KV pair of the specified key from the Preferences instance. |
Storing Data Persistently
Call flush() to write the cached data back to its text file for persistent storage.
Table 4 API for data persistence
Class | API | Description |
---|---|---|
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 and saved by flush(), a callback will be invoked to return the new data.
Table 5 APIs for observing Preferences changes
Class | API | Description |
---|---|---|
Preferences | on(type: ‘change’, callback: Callback<{ key : string }>): void | Subscribes to data changes. |
Preferences | off(type: ‘change’, callback: Callback<{ key : string }>): void | Unsubscribes from data changes. |
Deleting Data
You can use the following APIs to delete a Preferences instance or data file.
Table 6 APIs for deleting Preferences
Bundle Name | API | Description |
---|---|---|
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
- Import @ohos.data.preferences and related modules to the development environment.
import data_preferences from '@ohos.data.preferences';
- Obtain a Preferences instance.
Read the specified file and load its data to the Preferences instance for data operations.
FA model:
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility'
let context = featureAbility.getContext();
let preferences = null;
let promise = data_preferences.getPreferences(context, 'mystore');
promise.then((pref) => {
preferences = pref;
}).catch((err) => {
console.info("Failed to get the preferences.");
})
Stage model:
// Obtain the context.
import UIAbility from '@ohos.app.ability.UIAbility';
let context = null;
let preferences = null;
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage){
context = this.context;
}
}
let promise = data_preferences.getPreferences(context, 'mystore');
promise.then((pref) => {
preferences = pref;
}).catch((err) => {
console.info("Failed to get the preferences.");
})
- Write data.
Use preferences.put() to write data to the Preferences instance.
let putPromise = preferences.put('startup', 'auto');
putPromise.then(() => {
console.info("Put the value of 'startup' successfully.");
}).catch((err) => {
console.info("Failed to put the value of 'startup'. Cause: " + err);
})
- Read data.
Use preferences.get() to read data.
let getPromise = preferences.get('startup', 'default');
getPromise.then((value) => {
console.info("The value of 'startup' is " + value);
}).catch((err) => {
console.info("Failed to get the value of 'startup'. Cause: " + err);
})
- Store data persistently.
Use preferences.flush() to flush data from the Preferences instance to its file.
preferences.flush();
- 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 saved by flush(), the observer callback will be invoked to return the new data.
let observer = function (key) {
console.info("The key" + key + " changed.");
}
preferences.on('change', observer);
// The data is changed from 'auto' to 'manual'.
preferences.put('startup', 'manual', function (err) {
if (err) {
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Put the value of 'startup' successfully.");
preferences.flush(function (err) {
if (err) {
console.info("Failed to flush data. Cause: " + err);
return;
}
console.info("Flushed data successfully."); // The observer will be called.
})
})
- Delete the specified file.
Use deletePreferences() 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.
let proDelete = data_preferences.deletePreferences(context, 'mystore');
proDelete.then(() => {
console.info("Deleted data successfully.");
}).catch((err) => {
console.info("Failed to delete data. Cause: " + err);
})
你可能感兴趣的鸿蒙文章
harmony 鸿蒙DataShare Development
harmony 鸿蒙Distributed Data Object Development
harmony 鸿蒙Distributed Data Object Overview
harmony 鸿蒙Distributed Data Service Development
harmony 鸿蒙Distributed Data Service Overview
- 所属分类: 后端技术
- 本文标签:
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦