【HarmonyOS Next】数据本地存储：@ohos.data.preferences

【HarmonyOS Next】数据本地存储：@ohos.data.preferences

在开发现代应用程序时，数据存储是一个至关重要的过程。应用程序为了保持某些用户设置、应用状态以及其他小量数据信息通常需要一个可靠的本地存储解决方案。在 HarmonyOS Next 环境下，@ohos.data.preferences 模块为我们提供了一个轻量级且高效的键值对存储方式。本文将深入探讨如何利用该模块进行数据的本地存储，并通过一个实际封装的类举例说明其实现方式。

什么是 @ohos.data.preferences？

@ohos.data.preferences 是 HarmonyOS 提供的轻量级本地存储解决方案，适用于存储简单的键值对。例如保存用户的设置或者应用的配置信息。这一模块提供了一套简便的接口，便于开发者读写数据，持久化存储。

核心功能

• 轻量级存储：非常适用于存储小量和简单的数据。
• 易于使用：通过简单的接口即可实现对数据的增删改查。
• 持久化特性：数据保存在本地存储，应用重启后仍然可以访问。

@ohos.data.preferences 的基本用法

要使用 Preferences 模块进行数据存储，以下是基本步骤：

1. 获取 Preferences 实例：
   使用 dataPreferences.getPreferences(context, 'preferenceName') 方法来获取或创建一个 Preferences 实例。

2. 存储数据：
   使用 putString, putInt, putBoolean 等方法来存储数据。最后必须调用 flush() 方法，让数据持久化到存储系统中。

3. 读取数据：
   使用 getString, getInt, getBoolean 等方法来读取存储在 Preferences 中的数据。

4. 删除数据：
   用 delete(key) 删除具体键的值，用 clear() 删除所有数据。

示例代码实现

import preferences from '@ohos.data.preferences';// 获取 Preferences
const context = ...; // 假设 context 可用
const prefName = 'userPreferences';
const preferencesHelper = preferences.getPreferences(context, prefName);// 写入数据
preferencesHelper.putString('theme', 'dark');
preferencesHelper.flush();// 读取数据
const theme = preferencesHelper.getString('theme', 'light');// 删除数据
preferencesHelper.delete('theme');
preferencesHelper.flush();// 清空数据
preferencesHelper.clear();
preferencesHelper.flush();

封装 Preferences 进行简化操作

在更复杂的项目中，直接调用这些方法可能并不够优雅和简洁。为此，我们创建了 PreferencesUtils 类，对 @ohos.data.preferences 进行了一层封装，统一了对数据的操作方法。

PreferencesUtils 类的实现详解

1. 类的基本结构

export class PreferencesUtils {private preferencesName: string;private keyPreferences: string;constructor(name: string = PREFERENCES_NAME,keyP: string = KEY_PREFERENCES) {this.preferencesName = name;this.keyPreferences = keyP;}
}

• 成员变量：preferencesName 和 keyPreferences 分别用于存储的文件名和全局引用。
• 构造函数：允许通过参数自定义这两个参数，提高了工具类的灵活性。

2. 创建和获取 Preferences 实例

async createPreferences(context: Context): Promise<dataPreferences.Preferences | null> {try {const preferences = await dataPreferences.getPreferences(context, this.preferencesName);GlobalContext.getContext().setObject(this.keyPreferences, preferences);return preferences;} catch (error) {console.error('Error creating preferences:', error);return null;}
}async getPreferences(): Promise<dataPreferences.Preferences | null> {try {return GlobalContext.getContext().getObject(KEY_PREFERENCES);} catch (error) {console.error('Error getting preferences:', error);return null;}
}

• 功能实现：通过 createPreferences 方法创建 Preferences，并保存在全局上下文中；getPreferences 方法用于获取实例，确保在需要时能够顺利地进行数据操作。
• 异常处理：使用 try/catch 结构确保错误被捕获并记录。

3. 数据的基本操作

   • 获取数据

   async get(key: string, def?: ValueType): Promise<ValueType | undefined> {try {const preferences = await this.getPreferences();return preferences ? await preferences.get(key, def) : def;} catch (error) {console.error(`Error getting key ${key}:`, error);return def;}
   }
   

   • 存储数据

   async put(key: string, value: ValueType): Promise<void> {try {const preferences = await this.getPreferences();if (preferences) {await preferences.put(key, value);await preferences.flush();}} catch (error) {console.error(`Error putting key ${key}:`, error);}
   }
   

   • 删除数据和清空数据

   async delete(key: string): Promise<void> {try {const preferences = await this.getPreferences();if (preferences) {await preferences.delete(key);await preferences.flush();}} catch (error) {console.error(`Error deleting key ${key}:`, error);}
   }async clear(): Promise<void> {try {const preferences = await this.getPreferences();if (preferences) {await preferences.clear();await preferences.flush();}} catch (error) {console.error('Error clearing preferences:', error);}
   }
   

• 一致的接口：通过 get, put, delete, 和 clear 方法，它简化了对具体存储操作的调用。
• 数据持久化：每次数据操作后调用 flush 确保数据立即写入存储，避免数据丢失。
• 全面的错误管理：在每个方法的实现中均加入了错误捕获和日志记录，以确保运行时出现问题时能够及时反应和处理。

应用示例

下面展示如何在应用中使用 PreferencesUtils 类来管理本地存储的数据：

import PreferencesUtils from './PreferencesUtils';async function initAppPreferences(context: Context) {await PreferencesUtils.createPreferences(context);
}async function updateUserPreferences() {await PreferencesUtils.put('language', 'English');const language = await PreferencesUtils.get('language', 'en');console.log(`Current language preference: ${language}`);
}// 初始化并使用
initAppPreferences(appContext).then(updateUserPreferences);

完整的封装

以下是一个可以直接使用的封装

import GlobalContext from './GlobalContext'
import dataPreferences from '@ohos.data.preferences'const PREFERENCES_NAME = 'yiPreferences'
const KEY_PREFERENCES = "preferences"
type ValueType = number | string | boolean | Array<number> | Array<string> | Array<boolean> | Uint8Array | object | bigintexport class PreferencesUtils{// preferences的文件名private preferencesName: string = PREFERENCES_NAME// 用于获取preferences实例的key值，保存到单例中private keyPreferences: string = KEY_PREFERENCESconstructor(name: string = PREFERENCES_NAME, keyP: string = KEY_PREFERENCES) {this.preferencesName = namethis.keyPreferences = keyP}createPreferences(context: Context): Promise<dataPreferences.Preferences> {let preferences = dataPreferences.getPreferences(context, this.preferencesName)GlobalContext.getContext().setObject(this.keyPreferences, preferences)return preferences}getPreferences(): Promise<dataPreferences.Preferences> {return GlobalContext.getContext().getObject(KEY_PREFERENCES) as Promise<dataPreferences.Preferences>}async get(key: string, def?: ValueType): Promise<ValueType> {return (await this.getPreferences()).get(key, def)}async getAll(): Promise<Object> {let  preferences = await this.getPreferences()return preferences.getAll()}async put(key: string, value: ValueType): Promise<void> {let promise = await this.getPreferences().then(async (p) => {await p.put(key, value)await p.flush();}).catch((err: Error)=>{console.log(String(err))})return promise}async delete(key: string): Promise<void> {return (await this.getPreferences()).delete(key).finally(async () => {(await this.getPreferences()).flush()})}async clear(): Promise<void> {return (await this.getPreferences()).clear().finally(async () => {(await this.getPreferences()).flush()})}}export default new PreferencesUtils()