系列:《Web 到 HarmonyOS》· 本地存储专题
适合人群:会 Pinia /localStorage/ IndexedDB / Cookie,准备在鸿蒙里选对「存哪儿」
上一篇里相关的点:03 进程、线程与通信(组件状态共享)、插播:嵌入 Web 与桥接(H5 沙箱)
写在前面
Web 里「存一下」常常是一件事:Pinia persist 写进 localStorage,页面刷新还能回来。鸿蒙里这是两步:状态仓负责刷界面,持久化负责落盘。名字还容易撞车——ArkUI 的 LocalStorage 不是 window.localStorage。
先拆三层,再对照 API。第 03 篇用的是 V1(AppStorage + PersistentStorage);本篇按 V2 写(AppStorageV2 + PersistenceV2)。不要混用。
一、先拆三层,避免同名陷阱
| 层 | 干什么 | Web 直觉 | 鸿蒙 |
|---|---|---|---|
| A. UI 状态仓 | 驱动刷新,进程内内存 | Vuex / Pinia / React Context | AppStorageV2、ArkUI LocalStorage |
| B. 应用持久化 | 杀进程还在,沙箱文件 | localStorage / IndexedDB | Preferences、RDB(SQLite)、DDM |
| C. Web 沙箱 | 只发生在 Web 组件里 | Cookie / Cache / DOM Storage | WebCookieManager、cacheMode、domStorageAccess |
同名红线:
- ArkUI
LocalStorage= 页面级内存状态库,不是window.localStorage。 - 设备能力里的 LocalStorage(SD 卡 / 硬盘录像)是另一套业务词,不要混进前端存储。
- V1:
AppStorage+PersistentStorage;V2:AppStorageV2+PersistenceV2。 - H5 的
localStorage进不了 ArkUI 状态仓 / Preferences,除非自己做 JSBridge。
flowchart TB
subgraph A["A. UI 状态仓 进程内内存"]
direction TB
n1["@Local / @Param"] --> n2["页面级 LocalStorage"]
n2 --> n3["全局 AppStorageV2"]
end
subgraph B["B. 应用持久化 杀进程仍在"]
direction TB
n4["PersistenceV2"]
n5["Preferences 必须 flush"]
n6["RDB SQLite / DDM"]
end
subgraph C["C. Web 沙箱 仅 Web 组件"]
n7["Cookie / DOM Storage / cacheMode"]
end
n3 -.-> n4
n3 -.-> n5
实线:组件状态往上交,页面级仓再交到全局仓,改了会刷 UI。
虚线:全局仓要活过重启,再接到 PersistenceV2;少量配置走 Preferences,必须 flush。
C 层没有连到 B:ArkWeb 和应用持久化默认隔离。
一句话:想让界面动,用状态仓;想让数据活过重启,用持久化;想管 H5 站点,用 ArkWeb。
二、Web 对照总表
| Web 心智 | 鸿蒙对应 | 生命周期 | 驱动 UI | 落盘 |
|---|---|---|---|---|
| Pinia / Vuex / Context | AppStorageV2.connect | 进程内,可跨 Ability | 是 | 否(落盘走 PersistenceV2) |
| 当前路由 provide/inject | ArkUI LocalStorage + @LocalStorageProp / @LocalStorageLink | 页面树;loadContent 可同 Ability 多页共享 | 是 | 否 |
Pinia persist / localStorage | Preferences 或 PersistenceV2 | 杀进程仍在 | Preferences 不自动刷 UI | 是 |
sessionStorage | Web DOM Session Storage(需 domStorageAccess) | 随 Web 会话 | 仅 Web 页 | 否 |
| Cookie | WebCookieManager | 约 30s 刷盘;saveCookieAsync 可强制 | 否 | 视类型 |
| HTTP Cache | cacheMode + removeCache | 单应用静态资源约 100MB | 否 | ROM/RAM |
| IndexedDB | relationalStore(SQLite) | 沙箱 db | 否 | 是 |
| SharedPreferences 式 KV | Preferences | 内存实例 + flush 才写文件 | 否 | 必须 flush |
| 没有对等物:跨设备 KV | DDM | 视同步策略 | 否 | 是 + 可同步 |
前端常把「Pinia persist」当成一件事。鸿蒙里状态仓负责刷新,持久化负责磁盘。
三、AppStorageV2:全局 UI 状态,不是磁盘 API
定位:跨页面、跨 Ability 的全局 UI 状态,等价 Pinia 全局 store,默认不 persist。
官方 Todo 示例:主页和独立 SettingAbility 用同一个 key "Setting" 共享「是否显示已完成任务」:
@Local setting: Setting = AppStorageV2.connect(Setting, 'Setting', () => new Setting())!;
任务列表要杀进程仍在,走另一条线:
this.taskList = PersistenceV2.connect(TaskList, 'TaskList', () => new TaskList([]))!;
和组件装饰器的边界:
| 装饰器 | Web 类比 |
|---|---|
@Local | 组件 ref / useState |
@Param / @Event | props / emit |
AppStorageV2 | 全局 store |
PersistenceV2 | persist 插件 |
复杂对象要 @ObservedV2 + @Trace;要序列化落盘时用 @Type。connect 拿到的是可观察对象,改字段会刷 UI;它本身不是 localStorage.setItem。
@ObservedV2
export class Setting {
@Trace showCompletedTask: boolean = true;
}
@Local setting: Setting = AppStorageV2.connect(Setting, 'Setting', () => new Setting())!;
四、ArkUI LocalStorage:页面级 store,不是 window.localStorage
官方定义:页面级、内存内状态库。通过 @Entry 注入后,子树自动可见;同一 UIAbility 可用 windowStage.loadContent(..., storage) 多页共享。跨 UIAbility 不要用它,改 AppStorageV2。
最后一个引用释放后会被 GC,杀进程即丢。
| 装饰器 | Web 类比 | 行为 |
|---|---|---|
@LocalStorageProp(key) | 单向 props | 本地改不回写;Storage 变了会覆盖本地 |
@LocalStorageLink(key) | v-model 到 store | 本地改会写回,所有绑定方一起变 |
组件外可以当普通 Map 用:
let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let propA = storage.get('PropA'); // 47
let link1 = storage.link('PropA'); // 双向
let prop = storage.prop('PropA'); // 单向
link1.set(48); // link 与 prop 都会到 48
prop.set(1); // 只有单向副本变成 1,link 仍是 48
@LocalStorageProp / @LocalStorageLink 只能绑 key,不能从父组件 props 初始化;key 不存在时用本地默认值写入 Storage。
let storage = new LocalStorage({ 'filter': 'all' });
@Entry(storage)
@Component
struct ListPage {
@LocalStorageLink('filter') filter: string = 'all';
build() {
Button(this.filter).onClick(() => { this.filter = 'unread'; })
}
}
五、ArkWeb:这里才真正接近浏览器
只发生在 Web 组件里,和 ArkUI 状态仓、Preferences 默认隔离。开关和桥接见插播:嵌入 Web 与桥接,这里只记存储。
Cookie
WebCookieManager.configCookieSync(url, cookie)- 未指定
SameSite时默认 Lax - 约 30s 周期落盘;
saveCookieAsync强制刷盘 - PC / 2in1 / 平板:session cookie 即使 save 也不写盘
- API 22+:
setLazyInitializeWebEngine(true)可在设 Cookie 时推迟内核初始化
Cache(cacheMode)
| 模式 | 直觉 |
|---|---|
Default | 优先未过期缓存 |
None | 优先用缓存(含过期) |
Online | 强制走网络 |
Only | 只从缓存读 |
removeCache(true) 清 ROM+RAM,false 只清 RAM。单应用静态资源缓存上限约 100MB。
DOM Storage
- 必须
.domStorageAccess(true)才启用 - Session Storage ≈
sessionStorage - Local Storage ≈ 浏览器
localStorage(在应用目录,仍只属于 Web 内核)
Web({ src: 'https://example.com', controller: this.controller })
.domStorageAccess(true)
.cacheMode(CacheMode.Default)
webview.WebCookieManager.configCookieSync('https://example.com', 'value=test');
六、真正的持久化:Preferences / SQLite / DDM
状态仓解决「界面动」;下面三个才是「数据活过重启」。
1. Preferences ≈ localStorage,但必须 flush
轻量 KV,适合用户设置、开关、少量配置。put 只改内存实例,不 flush 杀进程会丢。 这是和浏览器 localStorage 最大的心智差:Web 的 setItem 基本同步落盘;鸿蒙要把「写内存」和「刷盘」拆开。
import { preferences } from '@kit.ArkData';
const pref = await preferences.getPreferences(this.context, 'user_settings');
await pref.put('theme', 'dark');
await pref.flush(); // 不 flush ≈ 没存盘
const theme = await pref.get('theme', 'light');
await pref.delete('theme');
await pref.flush();
建议少量数据(不宜当 DB、条目不宜过大,约万级以内)、非多进程安全。敏感值不要明文(工程里常见做法是独立文件名 + 加密后再 put)。Preferences 不会自动刷 UI:需要界面跟着变,读出来再灌回状态仓。
2. SQLite / relationalStore ≈ IndexedDB + SQL
大量结构化、要查询 / 分页 / 事务时用它,不要把整表 JSON 塞进 Preferences。安全级别、是否加密在 StoreConfig 里配,不是事后加个 https 能代替的。
import { relationalStore } from '@kit.ArkData';
const config: relationalStore.StoreConfig = {
name: 'message.db',
securityLevel: relationalStore.SecurityLevel.S1
};
const store = await relationalStore.getRdbStore(this.context, config);
await store.executeSql(
'CREATE TABLE IF NOT EXISTS msg (id INTEGER PRIMARY KEY, title TEXT, read INTEGER)'
);
await store.insert('msg', { title: '告警', read: 0 });
const predicates = new relationalStore.RdbPredicates('msg');
predicates.equalTo('read', 0);
const result = await store.query(predicates);
3. DDM:Web 没有对等物
分布式数据管理面向跨设备访问 / 共享 / 同步,接近「可同步的 KV / 跨端状态」,不是 localStorage,也不是 Pinia。
单机 App 的主题、Token、消息列表,默认不该上 DDM。需要「手机改完平板立刻看到」再考虑。
七、选型决策树
flowchart TD
q1{"只要当前页 UI 跟着变?"} -->|是| a1["@Local 或 ArkUI LocalStorage"]
q1 -->|否| q2{"多页甚至另一个 Ability 也要同一份 UI 状态?"}
q2 -->|是| a2["AppStorageV2"]
q2 -->|否| q3{"杀进程还要在?"}
q3 -->|否| a1
q3 -->|是| q4{"数据长什么样?"}
q4 -->|"少量配置 主题/开关"| a3["Preferences 或 MMKV 必须 flush"]
q4 -->|"可观察对象图 如 Todo 列表"| a4["PersistenceV2"]
q4 -->|"列表 关系 查询 分页"| a5["RDB SQLite"]
q4 -->|"跨设备同步"| a6["DDM"]
q4 -->|"只发生在 Web 组件里"| a7["Cookie / domStorageAccess / cacheMode"]
q4 -->|"Token 密码 设备口令"| a8["加密加安全等级 禁止明文塞 Preferences"]
需要界面跟着 Preferences / RDB 变:先读盘,再灌回状态仓。
八、本篇结论
- 三层模型:状态仓 ≠ 持久化 ≠ Web 沙箱。
- 要 Pinia persist,不要去找 ArkUI
LocalStorage;去 Preferences /PersistenceV2/ RDB。 put之后记得flush。- H5 存储默认出不来,除非 Bridge。
- 结构化大数据用 SQLite;跨设备才用 DDM。
下一篇预告
《Web 到 HarmonyOS》-- 工程结构:Vite → DevEco/HAP
对照 Vite 工程怎么对应 DevEco 模块、HAP 产物和资源目录。