HarmonyOS NEXT Practical: Storage data - Preferences Tools

Goal: Encapsulate the Preferences utility class to achieve persistent storage of data. User preferences provide Key Value data processing capabilities for applications, supporting the persistence of lightweight data and its modification and querying. When users want a globally unique storage location, they can use their preferences for storage. Preferences will cache the data in memory, and when the user reads it, they can quickly retrieve the data from memory. When persistence is required, the flush interface can be used to write the data in memory to a persistent file. Preferences will consume more memory as the amount of data stored increases. Therefore, Preferences is not suitable for storing too much data and does not support encryption through configuration. It is generally suitable for applications that save users' personalized settings (font size, whether night mode is enabled or not). Operating mechanism The user program calls the user preferences to read and write corresponding data files through the ArkTS interface. Developers can load the content of user preference persistence files into a Preferences instance, with each file uniquely corresponding to a Preferences instance. The system will store the instance in memory through a static container until the instance is actively removed from memory or the file is deleted. The persistent file of application preferences is saved inside the application sandbox and its path can be obtained through context. Please refer to the path to obtain the application file for details. Constraints and limitations: Preferences cannot guarantee process concurrency security, and there is a risk of file corruption and data loss. They are not supported for use in multi process scenarios. The Key key is of type string, and it is required to be non empty and not exceed 1024 bytes in length. If the Value value is of type string, please use UTF-8 encoding format, which can be empty, and if not empty, the length should not exceed 16MB. When the stored data contains non UTF-8 formatted strings, please use Uint8Array type storage, otherwise it will cause format errors in the persistent file and result in file damage. When removePreferencesFromCache or deletePreferences is called, the subscribed data will be automatically unsubscribed. After getting Preferences again, the subscribed data will need to be re subscribed to. DeletePreferences is not allowed to be called concurrently with other interfaces in multiple threads or processes, otherwise unexpected behavior may occur. Memory will increase with the increase of stored data, so the amount of stored data should be lightweight. It is recommended to store no more than 50MB of data. When the stored data is large, creating Preferences objects and persisting data using the synchronization interface will become time-consuming operations. It is not recommended to use it in the main thread, otherwise appfreeze problems may occur. Actual combat:PreferencesService import { preferences } from '@kit.ArkData' export default class PreferencesService { /** * 保存key和value（新增和更新） * @param key * @param value / static save(key: string, value: preferences.ValueType) { const pfr = getPreferences() pfr.putSync(key, value) pfr.flush() // // 当字符串有特殊字符时，需要将字符串转为Uint8Array类型再存储 // let uInt8Array1 = new util.TextEncoder().encodeInto("~！@#￥%……&（）——+？"); // dataPreferences.putSync('uInt8', uInt8Array1); } /** * 根据key删除 * @param key */ static delete(key: string) { const pfr = getPreferences() pfr.deleteSync(key) pfr.flush() } // static get(key: string, defaultValue: preferences.ValueType) : preferences.ValueType{ /** * 根据preferencesItem的key获取value，有该项则获取对应的value，没有则返回preferencesItem.defaultValue * @param preferencesItem * @returns */ static get(preferencesItem: PreferencesItem): preferences.ValueType { const pfr = getPreferences() return pfr.getSync(preferencesItem.key, preferencesItem.defaultValue) } /** * 清除全部信息 */ static clear(){ const pfr = getPreferences() pfr.clearSync() pfr.flush() } } /** * 获取preferences实例 * @returns */ function getPreferences(): preferences.Preferences { const context = AppStorage.get('ablity_context') const pfr = preferences.getPreferencesSync(context, { name: 'my_preferences' }) return pfr } export interface PreferencesItem { key: string; defaultValue: preferences.ValueType; }

Mar 26, 2025 - 10:20

HarmonyOS NEXT Practical: Storage data - Preferences Tools

Goal: Encapsulate the Preferences utility class to achieve persistent storage of data.

User preferences provide Key Value data processing capabilities for applications, supporting the persistence of lightweight data and its modification and querying. When users want a globally unique storage location, they can use their preferences for storage. Preferences will cache the data in memory, and when the user reads it, they can quickly retrieve the data from memory. When persistence is required, the flush interface can be used to write the data in memory to a persistent file. Preferences will consume more memory as the amount of data stored increases. Therefore, Preferences is not suitable for storing too much data and does not support encryption through configuration. It is generally suitable for applications that save users' personalized settings (font size, whether night mode is enabled or not).

Operating mechanism
The user program calls the user preferences to read and write corresponding data files through the ArkTS interface. Developers can load the content of user preference persistence files into a Preferences instance, with each file uniquely corresponding to a Preferences instance. The system will store the instance in memory through a static container until the instance is actively removed from memory or the file is deleted.

The persistent file of application preferences is saved inside the application sandbox and its path can be obtained through context. Please refer to the path to obtain the application file for details.

Constraints and limitations:

Preferences cannot guarantee process concurrency security, and there is a risk of file corruption and data loss. They are not supported for use in multi process scenarios.
The Key key is of type string, and it is required to be non empty and not exceed 1024 bytes in length.
If the Value value is of type string, please use UTF-8 encoding format, which can be empty, and if not empty, the length should not exceed 16MB.
When the stored data contains non UTF-8 formatted strings, please use Uint8Array type storage, otherwise it will cause format errors in the persistent file and result in file damage.
When removePreferencesFromCache or deletePreferences is called, the subscribed data will be automatically unsubscribed. After getting Preferences again, the subscribed data will need to be re subscribed to.
DeletePreferences is not allowed to be called concurrently with other interfaces in multiple threads or processes, otherwise unexpected behavior may occur.
Memory will increase with the increase of stored data, so the amount of stored data should be lightweight. It is recommended to store no more than 50MB of data. When the stored data is large, creating Preferences objects and persisting data using the synchronization interface will become time-consuming operations. It is not recommended to use it in the main thread, otherwise appfreeze problems may occur.

Actual combat:PreferencesService

import { preferences } from '@kit.ArkData'

export default class PreferencesService {
  /**
   * 保存key和value（新增和更新）
   * @param key
   * @param value
   */
  static save(key: string, value: preferences.ValueType) {
    const pfr = getPreferences()
    pfr.putSync(key, value)
    pfr.flush()
    // // 当字符串有特殊字符时，需要将字符串转为Uint8Array类型再存储
    // let uInt8Array1 = new util.TextEncoder().encodeInto("~！@#￥%……&*（）——+？");
    // dataPreferences.putSync('uInt8', uInt8Array1);
  }

  /**
   * 根据key删除
   * @param key
   */
  static delete(key: string) {
    const pfr = getPreferences()
    pfr.deleteSync(key)
    pfr.flush()
  }

  // static get(key: string, defaultValue: preferences.ValueType) : preferences.ValueType{
  /**
   * 根据preferencesItem的key获取value，有该项则获取对应的value，没有则返回preferencesItem.defaultValue
   * @param preferencesItem
   * @returns
   */
  static get(preferencesItem: PreferencesItem): preferences.ValueType {
    const pfr = getPreferences()
    return pfr.getSync(preferencesItem.key, preferencesItem.defaultValue)
  }

  /**
   * 清除全部信息
   */
  static clear(){
    const pfr = getPreferences()
    pfr.clearSync()
    pfr.flush()
  }
}

/**
 * 获取preferences实例
 * @returns
 */
function getPreferences(): preferences.Preferences {
  const context = AppStorage.get('ablity_context')
  const pfr = preferences.getPreferencesSync(context, { name: 'my_preferences' })
  return pfr
}

export interface PreferencesItem {
  key: string;
  defaultValue: preferences.ValueType;
}