分清页面内状态和应用全局状态

写业务的时候很容易图省事,把所有跨页面要用到的数据全部丢进 AppStorage。登录信息、用户设置、筛选条件、购物车数据一股脑往里放,最后改一个字段,一堆无关页面、子组件跟着触发刷新。我之前做商城项目,把购物车总数放在 AppStorage,修改商品数量之后,首页、分类页、结算页全部收到变更通知,哪怕页面根本不在路由栈顶端,也会执行状态更新,整机 CPU 莫名抬升。

这里有一个核心边界:@State、@Computed 是组件局部观测,生命周期跟着组件走;AppStorage 是应用级全局单例存储,生命周期和整个 HAP 绑定,只要进程存活,数据就保留。它的通知机制是广播式的,一旦 key 对应的值变更,所有订阅这个 key 的地方全部收到回调,不会自动过滤页面是否可见、组件是否存活。

很多人误以为 AppStorage 只是一个全局变量容器,忽略它自带的响应式订阅。它的定位是少量全局共享配置,而不是放业务列表、表单草稿、临时分页数据的仓库。高频变更、大数据量的数据,绝对不适合放在 AppStorage 里面。

还有一个容易混淆的:LocalStorage 是页面级共享存储,作用域绑定一个 UIContext,适合同一个页面内多个组件共享,不要拿它替代 AppStorage 做跨页面全局数据。

AppStorage 基础订阅与读写示例

下面是可直接运行的示例,包含写入、订阅、取消订阅,规范使用用户基础信息这类低频变更的全局数据。

// 全局初始化,建议在entry的AbilityStage里统一注册默认值
import { AppStorage } from '@kit.ArkUI';

// 只注册一次,重复注册会覆盖订阅
AppStorage.setOrCreate('userInfo', {
  userId: '',
  nickname: '',
  avatar: '',
  isLogin: false
})
// UserCenter.ets 写入全局状态
import { AppStorage } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

@Component
struct UserCenter {
  login() {
    // 写入全局
    AppStorage.set('userInfo', {
      userId: 'U10001',
      nickname: '阿明',
      avatar: 'https://xxx/avatar.png',
      isLogin: true
    })
  }

  logout() {
    AppStorage.set('userInfo', {
      userId: '',
      nickname: '',
      avatar: '',
      isLogin: false
    })
  }

  build() {
    Column() {
      Button('登录')
        .onClick(() => this.login())
      Button('退出登录')
        .margin({top:12})
        .onClick(() => this.logout())
    }
    .padding(20)
  }
}
// HomePage.ets 订阅全局状态
import { AppStorage, StorageLink } from '@kit.ArkUI';

@Component
struct HomePage {
  // StorageLink:双向绑定,读和写都会触发全局广播
  @StorageLink('userInfo') userInfo: {
    userId: string,
    nickname: string,
    avatar: string,
    isLogin: boolean
  }

  build() {
    Column() {
      if (this.userInfo.isLogin) {
        Text(`欢迎 ${this.userInfo.nickname}`)
      } else {
        Text('请先登录')
      }
    }
    .padding(16)
  }
}

这里有两个高频踩坑点。第一,@StorageLink是双向绑定,你在组件内部直接修改它的属性,同样会触发全局广播。很多人在子组件里直接修改 userInfo.nickname,一改动,所有订阅页面全部刷新,这就是连锁风暴的来源。如果组件只需要读,不需要修改,优先用@StorageProp单向只读订阅,杜绝意外写操作。

// 只读订阅,组件内不能修改,修改会编译报错
@StorageProp('userInfo') userInfo: {
  userId: string,
  nickname: string,
  avatar: string,
  isLogin: boolean
}

第二,AppStorage 的对象是引用传递的响应式代理。如果你拿到对象之后,原地修改对象内部属性,同样触发变更。不要写这种代码:

// 错误:原地修改,触发广播
const info = AppStorage.get('userInfo')
info.nickname = '新名字'
AppStorage.set('userInfo', info)

// 正确:生成新对象替换
const oldInfo = AppStorage.get('userInfo')
AppStorage.set('userInfo', {...oldInfo, nickname: '新名字'})

手动订阅与主动取消监听

除了装饰器,还可以用 watch 手动订阅,适合在工具类、非组件代码里监听全局变更。手动订阅最大的责任是必须取消监听,否则就算页面销毁,回调依旧存活,持续接收广播,造成内存泄漏。

import { AppStorage } from '@kit.ArkUI';

@Component
struct DemoPage {
  private watchId: number = -1

  aboutToAppear() {
    this.watchId = AppStorage.watch('userInfo', (newVal, oldVal) => {
      console.info('全局用户信息变更', newVal)
    })
  }

  aboutToDisappear() {
    // 页面销毁取消监听
    if (this.watchId >= 0) {
      AppStorage.unwatch(this.watchId)
      this.watchId = -1
    }
  }

  build() {
    Text('监听全局用户状态')
  }
}

很多人只记得用 @StorageLink,忘记它底层也是自动 watch。只要组件没有销毁,它就一直订阅。页面压在路由栈深处、后台驻留的时候,全局 key 一变,它就会执行更新,不管用户看不看得见这个页面。

避免广播风暴的分层策略

广播风暴,就是一个全局 key 频繁 set,大量订阅节点同步执行刷新。商城购物车、实时搜索关键词这类高频数据,是重灾区。

第一种方案:分层隔离。高频变动的数据,不要放进 AppStorage。放在页面内 @State,或者封装一个普通单例 Map,自己写简单的事件总线,手动控制订阅者,不需要的页面不订阅。AppStorage 只放登录态、深色模式、字体大小这类改动频率极低的配置。

第二种方案:合并多次写入。短时间多次 set 同一个 key,会多次触发广播。连续多次修改的时候,做防抖,等待所有字段修改完成之后一次性 set。

// 防抖封装示例
let updateTimer: number | null = null
function updateUserInfo(data: Record<string, string | boolean>) {
  if (updateTimer) clearTimeout(updateTimer)
  updateTimer = setTimeout(() => {
    const old = AppStorage.get('userInfo')
    AppStorage.set('userInfo', {...old, ...data})
    updateTimer = null
  }, 50)
}

第三种方案:区分 “需要跨页面同步” 和 “只是临时缓存”。很多数据只是页面跳转临时传一下,用完就丢,完全不需要全局响应式,用 router 传 id 或者普通内存缓存即可,不需要进 AppStorage。

持久化联动与初始化时序陷阱

AppStorage 是内存存储,进程杀掉之后数据清空。很多业务会搭配 Preferences 持久化,启动时从 Preferences 加载到 AppStorage,变更时同步写入 Preferences。这里有一个时序坑:AbilityStage 加载 Preferences 是异步的,页面先渲染,AppStorage 还是默认空值,异步加载完成之后才变更,页面会闪一次。

稳妥写法:在 AbilityStage 的 onCreate 里面,await 读取持久化数据,再 setOrCreate 到 AppStorage,再启动页面,避免页面先渲染旧默认值。

另外不要在 AppStorage 里面放超大数组、图片二进制。它的响应式代理会递归劫持对象内部所有属性,数据量大的时候,劫持、对比、广播的开销会急剧上升,拖慢整个应用。

多实例与模块边界

HAP 内只有一份 AppStorage 实例,跨 HAP 之间,AppStorage 互相隔离。A HAP 的 AppStorage,B HAP 读取不到,跨 HAP 共享数据不能靠它,要用其他跨 HAP 通信方案。

还有一个坑:HSP 公共模块里面使用 AppStorage。不同业务模块共用同一个 key,一个模块改了,其他模块全部收到通知。公共 HSP 里尽量只读,不要随便写入 AppStorage,写入收敛到业务主模块。

全局状态的开发规范

AppStorage 本质是一个带自动订阅的全局事件中心,它的强大之处就是广播,麻烦也来自广播。

第一,严格控制入库范围:只存低频、全应用需要同步的配置,登录态、主题设置、全局开关。高频业务数据、列表、分页、表单草稿禁止放入。 第二,优先单向 @StorageProp,少用双向 @StorageLink,从源头减少意外写操作。 第三,手动 watch 必须配对 unwatch;装饰器订阅跟随组件生命周期,但是栈内隐藏页面依然会接收广播,要评估是否接受这个开销。 第四,写入时使用新对象替换引用,禁止原地修改对象属性,减少隐式变更。 第五,不要依赖 AppStorage 做大量状态联动,联动逻辑越多,越容易出现意料之外的连锁刷新,排查成本极高。

用好全局状态的核心,不是把状态集中,而是把变更的影响范围锁死。每一次 set,都要清楚哪些地方会收到通知,而不是写完之后,任由变更在整个应用里扩散。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐