What is HarmonyOS NEXT - Preferences?

User preferences provide Key-Value data processing capabilities for applications, and support applications to persist lightweight data, and modify and query it. Preferences will cache the data in memory, and when users read it, they can quickly get the data from memory. Preferences will lead to more memory occupied by applications with the more data stored, so Preferences are not suitable for storing too much data. Applicable scenario: save the user's personalized settings (font size, whether to turn on night mode) and personalized information (user name, login validity period) for the application. Constraint restriction ·Preference can't guarantee the security of process concurrency, and it will risk file damage and data loss, so it is not supported in multi-process scenarios. ·The key key is a string, which is required to be non-empty and not longer than 1024 bytes. If the Value is string, please use UTF-8 encoding format, which can be empty, and the length is not more than 16 * 1024 * 1024 bytes when it is not empty. ·Memory will increase with the increase of the amount of data stored, so the amount of data stored should be lightweight, and it is recommended to store no more than 10,000 pieces of data, otherwise it will cause great overhead in memory. ·When the stored data contains strings in non-UTF-8 format, please use the type of Uint8Array for storage, otherwise it will cause format errors in persisted files and cause file damage. ·When you call removePreferencesFromCache or deletePreferences, the subscribed data changes will be unsubscribed actively, and you need to re-subscribe to the data changes after getting Preferences again. ·DeletePreferences is not allowed to be called concurrently with other interfaces in multi-thread and multi-process, otherwise unpredictable behavior will occur. Operating mechanism: ·User program calls user preferences to read and write corresponding data files through ArkTS interface. Developers can load the contents of user preference persistent files into Preferences instances, and each file uniquely corresponds 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 in the application sandbox, and its path can be obtained through context. See the path to get the application file. Interface description: getPreferencesSync(context: Context, options: Options): Preferences//Gets the Preferences instance. The interface has an asynchronous interface. putSync(key: string, value: ValueType): void//Write the data to the Preferences instance, which can be persisted through flush. The interface has an asynchronous interface. hasSync(key: string): boolean//Checks whether the Preferences instance contains a storage Key-value pair with the given key. The given Key value cannot be empty. The interface has an asynchronous interface. getSync(key: string, defValue: ValueType): ValueType//Gets the value corresponding to the key, and returns the default data defValue if the value is null or non-default type. The interface has an asynchronous interface. deleteSync(key: string): void//Deletes a storage Key-value pair named given key from the Preferences instance. The interface has an asynchronous interface. flush(callback: AsyncCallback): void//Store the data of the current Preferences instance asynchronously in the user preference persistence file. Code example PreferencesUtil export class PreferencesUtil { static getPreferences(context?: Context, preferencesFileName = "MyPreferences") { context = context || getContext() let options: preferences.Options = { name: preferencesFileName } return preferences.getPreferencesSync(context, options); } static async setData(key: string, value: string, context?: Context) { const store = PreferencesUtil.getPreferences(context); store.putSync(key, value) await store.flush() } static getData(key: string, context?: Context) { const store = PreferencesUtil.getPreferences(context); return store.getSync(key, "") as string } } usage mode const list = PreferencesUtil.getData("beautyList"); PreferencesUtil.setData("beautyList", JSON.stringify(this.data.getAllData()));

Mar 25, 2025 - 14:13

User preferences provide Key-Value data processing capabilities for applications, and support applications to persist lightweight data, and modify and query it.
Preferences will cache the data in memory, and when users read it, they can quickly get the data from memory. Preferences will lead to more memory occupied by applications with the more data stored, so Preferences are not suitable for storing too much data.

Applicable scenario: save the user's personalized settings (font size, whether to turn on night mode) and personalized information (user name, login validity period) for the application.

Constraint restriction
·Preference can't guarantee the security of process concurrency, and it will risk file damage and data loss, so it is not supported in multi-process scenarios.
·The key key is a string, which is required to be non-empty and not longer than 1024 bytes.
If the Value is string, please use UTF-8 encoding format, which can be empty, and the length is not more than 16 * 1024 * 1024 bytes when it is not empty.
·Memory will increase with the increase of the amount of data stored, so the amount of data stored should be lightweight, and it is recommended to store no more than 10,000 pieces of data, otherwise it will cause great overhead in memory.
·When the stored data contains strings in non-UTF-8 format, please use the type of Uint8Array for storage, otherwise it will cause format errors in persisted files and cause file damage.
·When you call removePreferencesFromCache or deletePreferences, the subscribed data changes will be unsubscribed actively, and you need to re-subscribe to the data changes after getting Preferences again.
·DeletePreferences is not allowed to be called concurrently with other interfaces in multi-thread and multi-process, otherwise unpredictable behavior will occur.

Operating mechanism:
·User program calls user preferences to read and write corresponding data files through ArkTS interface. Developers can load the contents of user preference persistent files into Preferences instances, and each file uniquely corresponds 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 in the application sandbox, and its path can be obtained through context. See the path to get the application file.

Interface description:

getPreferencesSync(context: Context, options: Options): Preferences//Gets the Preferences instance. The interface has an asynchronous interface.
putSync(key: string, value: ValueType): void//Write the data to the Preferences instance, which can be persisted through flush. The interface has an asynchronous interface.
hasSync(key: string): boolean//Checks whether the Preferences instance contains a storage Key-value pair with the given key. The given Key value cannot be empty. The interface has an asynchronous interface.
getSync(key: string, defValue: ValueType): ValueType//Gets the value corresponding to the key, and returns the default data defValue if the value is null or non-default type. The interface has an asynchronous interface.
deleteSync(key: string): void//Deletes a storage Key-value pair named given key from the Preferences instance. The interface has an asynchronous interface.
flush(callback: AsyncCallback): void//Store the data of the current Preferences instance asynchronously in the user preference persistence file.

Code example
PreferencesUtil

export class PreferencesUtil {
  static getPreferences(context?: Context, preferencesFileName = "MyPreferences") {
    context = context || getContext()
    let options: preferences.Options = { name: preferencesFileName }
    return preferences.getPreferencesSync(context, options);
  }

  static async setData(key: string, value: string, context?: Context) {
    const store = PreferencesUtil.getPreferences(context);
    store.putSync(key, value)
    await store.flush()
  }

  static getData(key: string, context?: Context) {
    const store = PreferencesUtil.getPreferences(context);
    return store.getSync(key, "") as string
  }
}

usage mode

const list = PreferencesUtil.getData("beautyList");
PreferencesUtil.setData("beautyList", JSON.stringify(this.data.getAllData()));