探秘鴻蒙 HarmonyOS NEXT：鴻蒙存儲核心技術全解析

引言

本文章基于HarmonyOS?NEXT操作系統，API12以上的版本。

在 ArkTS (ArkUI 框架) 中，用戶首選項 (Preferences) 和 持久化存儲 (PersistentStorage) 都用于數據存儲，但它們有不同的應用場景和特點。

1. 用戶首選項 (Preferences)

概念：

輕量級鍵值對存儲，主要用于存儲用戶設置或小型數據，如應用配置、主題模式、語言等。
適用于 頻繁讀取 和 少量更新 的數據存儲。

特點：

主要用于存儲簡單的鍵值對，如 boolean、string、number 等。
數據存儲在 本地沙盒 中，并會在 應用重新啟動后保持不變。
適合存儲 小量數據，如 UI 設置、開關狀態等。

使用場景：

主題模式（淺色/深色模式）。
語言偏好設置（中文/英文）。
記住用戶是否已登錄（布爾值）。
開關設置，如通知開關。

示例代碼：

import preferences from '@ohos.data.preferences';// 獲取 Preferences 實例
async function saveThemePreference(isDarkMode: boolean) {const preferencesInstance = await preferences.getPreferences(globalThis, 'user_settings');await preferencesInstance.put('dark_mode', isDarkMode);await preferencesInstance.flush(); // 確保數據寫入
}// 讀取 Preferences
async function getThemePreference(): Promise<boolean> {const preferencesInstance = await preferences.getPreferences(globalThis, 'user_settings');return await preferencesInstance.get('dark_mode', false); // 默認值 false
}

2. 核心API介紹

Preferences 組件主要提供 讀取、寫入、刪除 用戶首選項的方法。常用的 API 主要包括：

（1）獲取 Preferences 實例

在 OpenHarmony 設備上，用戶首選項存儲在文件中，因此需要指定存儲路徑。

import preferences from '@ohos.data.preferences';async function getPreferences() {try {const pref = await preferences.getPreferences(globalThis.getContext(), 'settings.preferences');return pref;} catch (err) {console.error('獲取 Preferences 失敗:', err);}
}

getPreferences(context, fileName): 通過 文件名 獲取 Preferences 實例，該文件存儲在應用的數據目錄下。
context: 需要傳入全局應用上下文 globalThis.getContext()。

（2）存儲數據

使用 put() 方法存儲鍵值對數據，并使用 flush() 進行同步保存。

async function savePreferences() {const pref = await getPreferences();if (!pref) return;pref.put('theme', 'dark');  // 存儲字符串pref.put('volume', 50);      // 存儲數值pref.put('notifications', true);  // 存儲布爾值await pref.flush();  // 立即保存到本地console.log('數據已保存');
}

put(key, value): 存儲 key-value 鍵值對。
flush(): 同步寫入存儲，否則數據可能不會立即寫入。

（3）讀取數據

使用 get() 方法獲取存儲的數據：

async function loadPreferences() {const pref = await getPreferences();if (!pref) return;const theme = pref.get('theme', 'light');  // 默認值 "light"const volume = pref.get('volume', 10);     // 默認值 10const notifications = pref.get('notifications', false);  // 默認值 falseconsole.log(`當前主題: ${theme}, 音量: ${volume}, 通知開關: ${notifications}`);
}

get(key, defaultValue): 讀取存儲的值，如果鍵不存在，則返回默認值。

（4）刪除數據

使用 delete() 方法移除指定鍵：

async function removePreferenceKey() {const pref = await getPreferences();if (!pref) return;pref.delete('theme');  // 刪除 "theme" 配置項await pref.flush();  // 確保數據同步更新console.log('主題設置已刪除');
}

delete(key): 刪除指定 key 對應的值。

（5）清除所有數據

可以使用 clear() 方法清空整個 Preferences。

async function clearPreferences() {const pref = await getPreferences();if (!pref) return;pref.clear();  // 清空所有數據await pref.flush();console.log('所有用戶設置已清除');
}

clear(): 清空所有存儲的鍵值對數據。

3. 持久化存儲 (PersistentStorage)

概念：

更通用的數據存儲方式，可以用于存儲更大規模的結構化數據，如對象、列表或復雜數據。
通常與本地數據庫（如 SQLite 或 文件存儲）結合使用。

特點：

適用于 存儲較大數據量，如緩存數據、用戶數據、應用狀態等。
提供更豐富的 API，支持復雜的數據管理。
數據存儲在應用的私有目錄，可以長期存儲，即使應用重啟也不會丟失。

使用場景：

用戶賬戶信息（如用戶名、頭像）。
應用的緩存數據（如搜索歷史、下載列表）。
復雜的設置數據（如 JSON 結構的配置）。
離線數據存儲（如離線文檔、任務列表）。

示例代碼（基于數據存儲組件）：

import { PersistentStorage } from '@ohos.data.storage';// 保存數據
async function saveUserData(userData: any) {const storage = new PersistentStorage('user_data'); // 創建存儲實例await storage.set('profile', JSON.stringify(userData));await storage.flush(); // 確保數據寫入
}// 讀取數據
async function getUserData(): Promise<any> {const storage = new PersistentStorage('user_data');const userDataStr = await storage.get('profile', '{}'); // 默認值為空對象return JSON.parse(userDataStr);
}

4. 核心API介紹

（1）存儲數據

使用 set() 方法存儲數據：

storage.set('username', 'Alice');
storage.set('age', 25);
storage.set('isPremiumUser', true);

該方法支持存儲 字符串、數值、布爾值等基本數據類型。
數據存儲在應用本地，不會在應用重啟時丟失。

（2）獲取數據

使用 get<T>() 方法獲取存儲的數據：

let username: string = storage.get<string>('username', 'defaultUser');
let age: number = storage.get<number>('age', 0);
let isPremium: boolean = storage.get<boolean>('isPremiumUser', false);

參數：
- 第一個參數是鍵（key）。
- 第二個參數是 默認值（當 key 不存在時返回此值）。
返回值類型 需要顯式指定（泛型 <T>）。

（3）刪除數據

使用 delete() 方法刪除某個鍵值：

storage.delete('username');

刪除后，使用 get() 方法查詢時將返回默認值。

（4）清空所有數據

使用 clear() 方法刪除所有存儲的鍵值對：

storage.clear();

該方法會清除 PersistentStorage 中存儲的所有數據，謹慎使用！

（5）數據是否存在

使用 has() 方法檢查某個鍵是否存在：

if (storage.has('username')) {console.log('用戶名已存儲');
} else {console.log('用戶名不存在');
}

（6）簡單封裝

以下是一個簡單封裝的 PersistentStorage 工具類:

import { PersistentStorage } from '@ohos.data.preferences';class StorageUtil {private static instance: PersistentStorage;private constructor() {}/*** 獲取 PersistentStorage 實例（單例模式）*/private static getInstance(): PersistentStorage {if (!this.instance) {this.instance = PersistentStorage.getSharedInstance();}return this.instance;}/*** 存儲數據* @param key 鍵名* @param value 要存儲的值（支持 string、number、boolean）*/static set<T>(key: string, value: T): void {this.getInstance().set(key, value);}/*** 獲取存儲數據* @param key 鍵名* @param defaultValue 默認值（如果 key 不存在，則返回此值）* @returns 存儲的數據*/static get<T>(key: string, defaultValue: T): T {return this.getInstance().get<T>(key, defaultValue);}/*** 刪除指定 key 的存儲數據* @param key 鍵名*/static delete(key: string): void {this.getInstance().delete(key);}/*** 清除所有存儲數據*/static clear(): void {this.getInstance().clear();}/*** 判斷某個 key 是否存在* @param key 鍵名* @returns 存在返回 true，否則返回 false*/static has(key: string): boolean {return this.getInstance().has(key);}
}export default StorageUtil;// 示例使用
StorageUtil.set('username', 'Alice');
const username = StorageUtil.get('username', 'defaultUser');
console.log(`Username: ${username}`);
StorageUtil.delete('username');
console.log(StorageUtil.has('username')); // false
StorageUtil.clear();

5. 對比總結

特性	用戶首選項 (Preferences)	持久化存儲 (PersistentStorage)
存儲方式	輕量級鍵值對存儲	適用于存儲復雜數據
數據類型	`string`, `boolean`, `number`	復雜數據結構（JSON、列表等）
數據量	小量數據	大量數據
適用場景	主題、語言、用戶偏好	用戶信息、緩存、離線數據
讀寫性能	讀取速度快	適用于批量存儲
數據持久性	持久化存儲	持久化存儲