前言

底部 Tab 切换是移动应用最常见的导航模式之一。几乎每个开发者都遇到过这样的 bug：

用户在「表单」Tab 填了一半，切到「设置」再切回来，输入内容没了、滚动位置回到顶部、计数器归零。

第一反应往往是「是不是没保存到数据库？」——其实问题出在 Tabs 子页的生命周期与默认销毁策略：TabContent 内的 @State 跟着组件实例走，实例被销毁，状态自然丢失。

HarmonyOS 没有 Vue 里独立的 keep-alive 组件名，但提供了等价的 cachedMaxCount 缓存机制（API 19+）。此外，状态提升到 Tabs 父组件是更通用、更低版本兼容的方案。

本文结合项目 Demo，从默认销毁原理、barPosition 布局、cachedMaxCount 两种模式、状态提升到排查流程，做一次完整解析。

---

一、Tabs 架构与生命周期

1.1 基本结构

Tabs({ barPosition: BarPosition.End, index: this.currentIndex }) {
  TabContent() {
    HomePage()
  }
  .tabBar('首页')

  TabContent() {
    FormPage()
  }
  .tabBar('表单')
}
.onChange((index: number) => {
  this.currentIndex = index
})

组件	职责
Tabs	容器，管理 Tab 切换、缓存策略、bar 位置
TabContent	每个 Tab 的内容区
.tabBar()	Tab 栏上显示的标签
TabsController	编程式切换 changeIndex()

1.2 默认销毁策略

未开启缓存时，离开当前 Tab 后，对应 TabContent 子树可能触发：

aboutToDisappear() → 组件销毁 → @State 清空
         ↓
切回该 Tab → aboutToAppear() → 重新初始化

Demo 用 aboutToAppear 次数观测这一行为：

aboutToAppear(): void {
  this.lifecycleAppear++  // 每重建一次 +1
}

默认模式下，切走再切回，aboutToAppear 从 1 变成 2——说明子页被销毁并重建了。

1.3 状态存在哪里

状态位置	子页销毁后	适用场景
TabContent 内 @State	❌ 丢失	简单展示页
Tabs 父组件 @State	✅ 保留	表单草稿、计数
cachedMaxCount 缓存实例	✅ 保留	需保留子页完整状态
AppStorage / 持久化	✅ 保留	跨会话数据

---

二、barPosition：Tab 栏位置

2.1 枚举值

BarPosition.Start  // 垂直 Tabs 时在左侧；水平 Tabs 时在顶部
BarPosition.End    // 垂直 Tabs 时在右侧；水平 Tabs 时在底部

Demo 中的切换：

Tabs({
  barPosition: this.barAtBottom ? BarPosition.End : BarPosition.Start,
  index: this.currentIndex
})

barPosition	水平 Tabs（默认）	典型场景
Start	Tab 栏在顶部	分类页、二级导航
End	Tab 栏在底部	主 App 底部 TabBar（微信、淘宝）

2.2 barPosition 与状态丢失的关系

barPosition 不影响缓存策略。无论顶栏还是底栏，默认销毁行为相同。但它影响：

• 内容区与 Tab 栏的布局分配；
• 与 layoutWeight、安全区的配合；
• 用户手势习惯（底部 Tab 更常见）。

排查状态丢失时，不要混淆 barPosition 与 cachedMaxCount——前者管布局，后者管生命周期。

2.3 相关属性

Tabs()
  .barMode(BarMode.Fixed)      // 固定 Tab 栏，不随内容滚动
  .barWidth(200)                // 垂直 Tabs 时栏宽
  .barHeight(56)                // 水平 Tabs 时栏高

---

三、坑：默认模式下的状态丢失

3.1 Demo 错误场景

TabsCacheCase.WRONG_DESTROY —— 不加任何缓存：

Tabs({ barPosition: BarPosition.End }) {
  TabContent() {
    TabFormContent({ cacheCase: WRONG_DESTROY, ... })
  }
  .tabBar('表单')
}
// ❌ 无 .cachedMaxCount(...)

TabFormContent 内部用局部 @State：

@State localCounter: number = 0
@State localInput: string = ''

3.2 复现步骤

1. 进入「表单」Tab，输入「测试文字」，点 +1 使计数为 1；
2. 切到「设置」Tab；
3. 切回「表单」Tab；
4. 观察：输入框为空、计数为 0、aboutToAppear 次数变为 2。

3.3 用户感知

• 表单草稿丢失；
• 列表滚动位置回到顶部；
• 筛选条件重置；
• 临时编辑内容消失。

---

四、解法一：cachedMaxCount（官方 keepAlive）

4.1 API 说明

自 API 19 起，Tabs 提供：

Tabs()
  .cachedMaxCount(count: number, mode: TabsCacheMode)

参数	含义
count	最多缓存的子 Tab 数量
mode	缓存淘汰策略

4.2 TabsCacheMode 两种模式

模式	行为	适用
CACHE_BOTH_SIDE	缓存当前页两侧的子组件	3~5 个 Tab，常左右切换
CACHE_LATEST_SWITCHED	缓存最近切换过的子组件	Tab 较多、内存敏感

Demo 使用：

Tabs({ barPosition: BarPosition.End, index: this.currentIndex }) {
  // ... TabContent ...
}
.cachedMaxCount(3, TabsCacheMode.CACHE_BOTH_SIDE)

3 个 Tab 全部缓存，切换时实例不销毁，@State 自然保留。

4.3 效果验证

缓存模式下切走再切回：

• localCounter / localInput 保持不变；
• aboutToAppear 不重复触发（次数仍为 1）；
• 滚动位置、临时 UI 状态均保留。

4.4 与 keepAlive 的对应关系

不少文章用 Vue 的 <keep-alive> 类比。HarmonyOS 中：

cachedMaxCount ≈ 官方 keepAlive 机制

注意：SDK 中 没有名为 keepAlive 的 TabContent 属性，搜索文档应使用 cachedMaxCount。

4.5 使用注意

要点	说明
内存	count 越大，缓存越多，内存越高
数量	count 应 ≥ 实际需要保留的 Tab 数
版本	API 19+，低版本需用状态提升
销毁	超出 count 的 Tab 仍会被淘汰

---

五、解法二：状态提升（State Lifting）

5.1 原理

将数据从 TabContent 子组件提升到 Tabs 父组件的 @State，子组件通过 @Link 读写。子页即使销毁重建，父级 @State 不受影响。

5.2 Demo 实现

父组件（TabsCachePitfallDemo.ets）：

@Observed
export class TabPageState {
  counter: number = 0
  inputText: string = ''
  appearCount: number = 0
}

@State formState: TabPageState = createTabPageState()

TabContent() {
  TabFormContent({
    cacheCase: CORRECT_STATE_LIFT,
    sharedState: $formState   // @Link 双向绑定
  })
}
.tabBar('表单')

子组件（TabFormContent.ets）：

@Link sharedState: TabPageState

private bumpCounter(): void {
  this.sharedState.counter++   // 写入父级状态
}

5.3 与 cachedMaxCount 对比

维度	cachedMaxCount	状态提升
API 版本	19+	全版本
保留范围	子页全部 @State	仅提升的字段
滚动位置	✅ 自动保留	❌ 需额外处理
内存	缓存整棵子树	仅存数据对象
复杂度	低（一行配置）	中（需设计状态结构）

推荐组合：简单 App 用 cachedMaxCount；复杂表单 / 低版本兼容用状态提升；核心数据还可同步 AppStorage。

5.4 @Observed 的作用

TabPageState 标记 @Observed，使嵌套属性变化能触发 UI 刷新：

@Observed
export class TabPageState {
  counter: number = 0
  // ...
}

---

六、三种策略对照总表

策略	代码	切回 Tab 后	appear 次数
❌ 默认销毁	无缓存	数据归零	+1
✅ cachedMaxCount	.cachedMaxCount(3, CACHE_BOTH_SIDE)	@State 保留	不变
✅ 状态提升	父 @State + 子 @Link	数据保留	可能 +1，但数据不丢

---

七、其他相关 API

7.1 TabsController 编程式切换

private controller: TabsController = new TabsController()

Tabs({ controller: this.controller }) { ... }

// 切换到 index 1
this.controller.changeIndex(1)

changeIndex 触发的切换与点击 Tab 栏行为一致，缓存策略同样生效。

7.2 onChange / onSelected

Tabs()
  .onChange((index: number) => {
    this.currentIndex = index
  })

onChange 在选中 Tab 变化时触发。若需与 index 双向绑定，用 @State currentIndex 传入 Tabs 构造函数。

7.3 onContentWillChange（API 12+）

切换前拦截：

Tabs()
  .onContentWillChange((current, coming) => {
    // return false 可阻止切换（如未保存提示）
    return true
  })

适合「表单未保存是否离开」场景，与状态保留互补。

---

八、选型决策树

Tab 切换后数据丢了？
  │
  ├─ API 19+ 且 Tab 数 ≤ 5？
  │     └─ 是 → cachedMaxCount(N, CACHE_BOTH_SIDE)
  │
  ├─ 需兼容低版本 / 只保留部分字段？
  │     └─ 状态提升到 Tabs 父组件 @State + @Link
  │
  ├─ 需跨 App 重启保留？
  │     └─ Preferences / AppStorage / 服务端
  │
  └─ 需阻止未保存离开？
        └─ onContentWillChange 拦截

---

九、系统性排查流程

1. 确认数据存在哪：子 @State、父 @State、还是全局存储？
2. 观测生命周期：在 aboutToAppear 打日志，切 Tab 看是否重复触发；
3. 检查 cachedMaxCount：是否配置？count 是否覆盖所有 Tab？
4. 检查状态提升：@Link 是否指向父级 @State？对象是否 @Observed？
5. 区分 barPosition：布局问题勿当缓存问题；
6. 内存与数量：Tab 很多时评估 CACHE_LATEST_SWITCHED 节省内存。

---

十、Demo 体验指南

路径：entry/src/main/ets/tabscache/

1. 默认 ❌ 默认销毁，在「表单」输入并 +1；
2. 切到「设置」再切回 → 数据丢失，appear = 2；
3. 切换 ✅ cachedMaxCount 重复 → 数据保留，appear = 1；
4. 切换 ✅ 状态提升 → 数据保留（即使 appear 增加）；
5. 拨动开关对比 barPosition.End（底栏）与 Start（顶栏）。

---

十一、生产环境 Checklist

• 明确哪些 Tab 需保留状态（表单、列表滚动、筛选）
• API 19+ 项目优先 cachedMaxCount
• count 值覆盖需缓存的 Tab 数量
• 多 Tab 场景评估 CACHE_LATEST_SWITCHED 内存
• 低版本或轻量需求用状态提升
• 嵌套状态对象使用 @Observed
• 核心数据持久化到 Preferences / 服务端
• 未保存表单用 onContentWillChange 拦截
• barPosition 按设计选 End（底栏）或 Start（顶栏）

---

十二、总结

Tabs 切换丢状态，不是框架 bug，而是默认会销毁不可见子页的设计选择。

核心结论	说明
默认行为	切走 Tab → 子页可能销毁 → @State 丢失
keepAlive	HarmonyOS 用 cachedMaxCount，无独立 keepAlive 属性
缓存模式	CACHE_BOTH_SIDE / CACHE_LATEST_SWITCHED
状态提升	父 @State + 子 @Link，全版本可用
barPosition	End 底栏 / Start 顶栏，与缓存无关
观测手段	aboutToAppear 次数判断子页是否重建

记住一句话：

子页 @State 跟着实例走，要么缓存实例，要么把状态托到父级。

---

附录：快速参考卡

// ✅ 官方缓存（API 19+，≈ keepAlive）
Tabs({ barPosition: BarPosition.End, index: this.currentIndex }) {
  TabContent() { FormPage() }.tabBar('表单')
  TabContent() { SettingsPage() }.tabBar('设置')
}
.cachedMaxCount(3, TabsCacheMode.CACHE_BOTH_SIDE)
.onChange((i) => { this.currentIndex = i })

// ✅ 状态提升
@State formState: TabPageState = new TabPageState()
TabContent() {
  FormPage({ state: $formState })
}

// ✅ 底栏 / 顶栏
barPosition: BarPosition.End    // 底部 TabBar
barPosition: BarPosition.Start  // 顶部 Tab