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

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

Storing Data Persistently

Call flush() to write the cached data back to its text file for persistent storage.

Table 4 API for data persistence

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

Deleting Data

You can use the following APIs to delete a Preferences instance or data file.

Table 6 APIs for deleting Preferences

How to Develop

1. Import @ohos.data.preferences and related modules to the development environment.

   import data_preferences from '@ohos.data.preferences';

1. 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.");
   })

1. 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);
   })

1. 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);
   })

1. Store data persistently.

Use preferences.flush() to flush data from the Preferences instance to its file.

   preferences.flush();

1. 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.
       })
   })

1. 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 鸿蒙Data Management

harmony 鸿蒙DataShare Development

harmony 鸿蒙DataShare Overview

harmony 鸿蒙Distributed Data Object Development

harmony 鸿蒙Distributed Data Object Overview

harmony 鸿蒙Distributed Data Service Development

harmony 鸿蒙Distributed Data Service Overview

harmony 鸿蒙Preferences Overview

harmony 鸿蒙RDB Development

harmony 鸿蒙RDB Overview