前言

做过设置页面的都知道，用户改了配置项之后，退出页面再进来，状态应该还保留着。在 Web 开发里我们用 localStorage，在 Android 里用 SharedPreferences。鸿蒙 ArkUI 提供了一个更优雅的方案——@StorageLink，直接把变量和全局的 AppStorage 绑定在一起，而且是双向的。

这篇文章用一个"用户信息 + 积分 + 主题"的案例，把 @StorageLink 的实际用法讲清楚。

应用场景

哪些场景特别适合 @StorageLink：

• 用户偏好设置：字体大小、主题色、语言选项
• 登录状态缓存：用户名、头像 URL、权限标识
• 积分/计数器：游戏分数、访问次数、操作计数
• 功能开关：通知开关、声音开关、自动保存

这些数据的共同特点是：需要在多个页面间共享，且关闭页面后仍然要保留。

方案设计

整体思路很简单：

组件变量 ←→ @StorageLink ←→ AppStorage（全局存储）

组件通过 @StorageLink 声明变量时，指定一个字符串 key。框架自动完成以下工作：

1. 初始化时从 AppStorage 读取对应 key 的值
2. 组件修改变量时，自动写回 AppStorage
3. AppStorage 中该 key 的值被其他地方修改时，组件变量也同步更新

这就是所谓的双向绑定。

编码实现

完整的 StorageLink 页面

@Entry
@Component
struct StorageLinkPage {
  @StorageLink('app_username') username: string = '未设置'
  @StorageLink('app_score') score: number = 0
  @StorageLink('app_theme') themeIdx: number = 0
  private themes: string[] = ['蓝色', '橙色', '绿色', '紫色']
  private themeColors: string[] = ['#4D96FF', '#FFA500', '#6BCB77', '#9B59B6']

  build() {
    Column() {
      Scroll() {
        Column() {
          Text('@StorageLink')
            .fontSize(18).fontWeight(FontWeight.Bold).margin({ bottom: 8 })

          Column() {
            Text('AppStorage 双向绑定')
              .fontSize(14).fontWeight(FontWeight.Medium).margin({ bottom: 12 })

            Row() {
              Text('用户名: ').fontSize(13)
              Text(this.username).fontSize(13)
                .fontWeight(FontWeight.Medium).fontColor('#4D96FF')
            }.margin({ bottom: 8 })

            Row() {
              Text('积分: ').fontSize(13)
              Text(this.score.toString()).fontSize(13)
                .fontWeight(FontWeight.Medium).fontColor('#4D96FF')
            }.margin({ bottom: 8 })

            Row() {
              Text('主题: ').fontSize(13)
              Column()
                .width(20).height(20)
                .backgroundColor(this.themeColors[this.themeIdx])
                .borderRadius(4).margin({ left: 4 })
            }

            Row({ space: 8 }) {
              Button('设置用户名').onClick(() => {
                this.username = `用户${Math.floor(Math.random() * 1000)}`
              })
              Button('加积分').onClick(() => {
                this.score += 10
              })
              Button('换主题').onClick(() => {
                this.themeIdx = (this.themeIdx + 1) % this.themes.length
              })
            }
            .width('100%').justifyContent(FlexAlign.SpaceEvenly).margin({ top: 16 })

            Button('清除所有').width('100%').margin({ top: 8 })
              .onClick(() => {
                this.username = ''
                this.score = 0
                this.themeIdx = 0
              })
          }
          .width('100%').backgroundColor('#FFFFFF').borderRadius(12).padding(16)

          Column() {
            Text('提示').fontSize(14).fontWeight(FontWeight.Medium)
            Text('@StorageLink 与 AppStorage 建立双向绑定，数据存储在应用全局存储中，关闭页面后数据依然保留。')
              .fontSize(12).fontColor('#666666').margin({ top: 4 })
          }
          .width('100%').backgroundColor('#FFFFFF').borderRadius(12)
          .padding(16).margin({ top: 10 })
        }
        .width('100%')
      }
      .layoutWeight(1)
    }
    .width('100%').height('100%').backgroundColor('#F5F6FA').padding(16)
  }
}

关键代码解读

@StorageLink 的声明方式是：

@StorageLink('key_name') variableName: Type = defaultValue

• 'key_name'：在 AppStorage 中的存储键名
• defaultValue：当 AppStorage 中没有该 key 时的默认值

双向绑定的体现：当你点击"加积分"按钮执行 this.score += 10 时，不仅当前页面的 Text 组件更新了，AppStorage 里的值也同步变成了新值。如果另一个页面也通过 @StorageLink('app_score') 绑定了同一个 key，那边也会自动刷新。

踩坑总结

坑1：默认值不生效

@StorageLink 的默认值只在 AppStorage 中没有对应 key 的时候才生效。如果之前已经写入过值，再次打开页面会读到旧值，默认值被忽略。

坑2：key 名冲突

AppStorage 是全局共享的，所有页面用同一个 key 空间。建议加上前缀（比如 module_username、settings_fontsize）避免冲突。

坑3：和 @State 混用

不要对同一个变量同时使用 @State 和 @StorageLink。它们各自有独立的观察机制，混用会导致不可预期的行为。

坑4：复杂对象支持有限

AppStorage 适合存储简单类型（string、number、boolean）。如果要存复杂对象，建议序列化后再存入。

优化建议

• 统一 key 管理：把所有 AppStorage 的 key 定义为常量，避免散落各处
• 初始化策略：在 UIAbility 的 onCreate 中做 AppStorage 的初始值设置，保证数据一致性
• 清理机制：用户登出时记得清理对应的存储数据

@StorageLink 本质上就是把 AppStorage 的操作从手动 get/set 变成了声明式绑定，写起来舒服很多。

写在最后

@StorageLink 是 ArkUI 状态管理装饰器里实用性很高的一个。它把全局存储和组件状态之间的同步逻辑自动化了，省去了手动读写 AppStorage 的样板代码。做设置页面、偏好管理、状态缓存这类需求时，优先考虑它就对了。