《Web 到 HarmonyOS》-- 本地存储:localStorage → Preferences

3 阅读6分钟

系列:《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 ContextAppStorageV2、ArkUI LocalStorage
B. 应用持久化杀进程还在,沙箱文件localStorage / IndexedDBPreferences、RDB(SQLite)、DDM
C. Web 沙箱只发生在 Web 组件里Cookie / Cache / DOM StorageWebCookieManager、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 / ContextAppStorageV2.connect进程内,可跨 Ability是否(落盘走 PersistenceV2)
当前路由 provide/injectArkUI LocalStorage + @LocalStorageProp / @LocalStorageLink页面树;loadContent 可同 Ability 多页共享是否
Pinia persist / localStoragePreferences 或 PersistenceV2杀进程仍在Preferences 不自动刷 UI是
sessionStorageWeb DOM Session Storage(需 domStorageAccess)随 Web 会话仅 Web 页否
CookieWebCookieManager约 30s 刷盘;saveCookieAsync 可强制否视类型
HTTP CachecacheMode + removeCache单应用静态资源约 100MB否ROM/RAM
IndexedDBrelationalStore(SQLite)沙箱 db否是
SharedPreferences 式 KVPreferences内存实例 + flush 才写文件否必须 flush
没有对等物:跨设备 KVDDM视同步策略否是 + 可同步

前端常把「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 / @Eventprops / emit
AppStorageV2全局 store
PersistenceV2persist 插件

复杂对象要 @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{&#34;只要当前页 UI 跟着变?&#34;} -->|是| a1[&#34;@Local 或 ArkUI LocalStorage&#34;]
  q1 -->|否| q2{&#34;多页甚至另一个 Ability 也要同一份 UI 状态?&#34;}
  q2 -->|是| a2[&#34;AppStorageV2&#34;]
  q2 -->|否| q3{&#34;杀进程还要在?&#34;}
  q3 -->|否| a1
  q3 -->|是| q4{&#34;数据长什么样?&#34;}
  q4 -->|&#34;少量配置 主题/开关&#34;| a3[&#34;Preferences 或 MMKV 必须 flush&#34;]
  q4 -->|&#34;可观察对象图 如 Todo 列表&#34;| a4[&#34;PersistenceV2&#34;]
  q4 -->|&#34;列表 关系 查询 分页&#34;| a5[&#34;RDB SQLite&#34;]
  q4 -->|&#34;跨设备同步&#34;| a6[&#34;DDM&#34;]
  q4 -->|&#34;只发生在 Web 组件里&#34;| a7[&#34;Cookie / domStorageAccess / cacheMode&#34;]
  q4 -->|&#34;Token 密码 设备口令&#34;| a8[&#34;加密加安全等级 禁止明文塞 Preferences&#34;]

需要界面跟着 Preferences / RDB 变:先读盘,再灌回状态仓。


八、本篇结论

  1. 三层模型:状态仓 ≠ 持久化 ≠ Web 沙箱。
  2. 要 Pinia persist,不要去找 ArkUI LocalStorage;去 Preferences / PersistenceV2 / RDB。
  3. put 之后记得 flush。
  4. H5 存储默认出不来,除非 Bridge。
  5. 结构化大数据用 SQLite;跨设备才用 DDM。

下一篇预告

《Web 到 HarmonyOS》-- 工程结构:Vite → DevEco/HAP

对照 Vite 工程怎么对应 DevEco 模块、HAP 产物和资源目录。