# 状态栏/导航栏/底部安全区适配技术实现文档

## 1. 文档目标

本文档为专项技术文档，仅描述以下适配能力的实现方案：

- 状态栏适配
- 自定义导航栏高度适配
- 底部安全区适配

文档用于开发实现、联调验收、问题排查与后续复用。

---

## 2. 适用范围

适用页面：

- 笔记编辑页 [User-uniapp/src/pages/tools/NotesBookToolView_children/NoteEditView.vue](../src/pages/tools/NotesBookToolView_children/NoteEditView.vue)

核心工具：

- 统一适配工具 [User-uniapp/src/util/navBarHeight.js](../src/util/navBarHeight.js)

支持平台：

- H5
- 微信小程序等小程序端
- App-Plus（iOS / Android）

---

## 3. 设计目标

1. 顶部不遮挡状态栏内容
2. 自定义导航在多端保持一致视觉高度
3. 底部内容不被手势条或刘海区域遮挡
4. 适配逻辑可复用、可扩展、可排障

---

## 4. 技术方案总览

采用 分层适配 方案：

1. 计算层（工具函数）
- 在 navBarHeight.js 内统一计算 statusBarHeight、navBarHeight、safeAreaInsets

2. 应用层（页面绑定）
- 页面通过内联 style 绑定高度数据，不写死平台值

3. 刷新层（生命周期）
- onLoad 与 onShow 均刷新，避免页面恢复后尺寸失真

---

## 5. 计算层实现

### 5.1 导航信息计算 getNavBarInfo

入口：

- [User-uniapp/src/util/navBarHeight.js](../src/util/navBarHeight.js)

计算字段：

- statusBarHeight：系统状态栏高度
- navBarHeight：自定义导航栏内容区高度（不含状态栏）
- totalHeight：状态栏 + 导航栏总高度
- menuButtonRect：胶囊按钮信息（小程序）

关键策略：

1. 基础兜底
- 默认 navBarHeight = 44
- totalHeight = statusBarHeight + 44

2. 小程序精确计算
- 可用胶囊 API 时，按公式计算：

$$
navBarHeight = (menuTop - statusBarHeight) \times 2 + menuHeight
$$

- 再与默认值比较，保证不小于 44

3. App 端补偿
- iOS 端最小高度校正：statusBarHeight + 44
- Android 端最小高度校正：statusBarHeight + 50

4. H5 固定策略
- H5 使用默认值 44，减少浏览器差异波动

### 5.2 安全区计算 getSafeAreaInfo

入口：

- [User-uniapp/src/util/navBarHeight.js](../src/util/navBarHeight.js)

返回字段：

- top
- bottom
- left
- right

当前页面重点使用 bottom 处理底部留白。

---

## 6. 页面应用层实现

页面：

- [User-uniapp/src/pages/tools/NotesBookToolView_children/NoteEditView.vue](../src/pages/tools/NotesBookToolView_children/NoteEditView.vue)

### 6.1 底部安全区适配

根容器绑定：

- paddingBottom = safeAreaInfo.bottom

目的：

- 防止底部按钮、输入区被手势条遮挡

### 6.2 状态栏适配

自定义导航外层绑定：

- paddingTop = navBarInfo.statusBarHeight

目的：

- 顶部导航内容整体下移，避开系统状态栏

### 6.3 导航栏高度适配

导航内容行绑定：

- height = navBarInfo.navBarHeight

目的：

- 保证导航操作区在不同端保持可点击高度与视觉一致性

---

## 7. 生命周期刷新策略

刷新函数：

- refreshLayoutInfo

执行时机：

1. onLoad
- 首次进入页面时初始化高度

2. onShow
- 页面从后台返回或再次显示时重新计算

原因：

- 部分设备在切后台/前台后状态栏参数可能变化
- 二次进入时可避免顶部或底部错位

---

## 8. 关键代码映射

1. 适配计算工具
- [User-uniapp/src/util/navBarHeight.js](../src/util/navBarHeight.js)

2. 根容器底部安全区绑定
- [User-uniapp/src/pages/tools/NotesBookToolView_children/NoteEditView.vue](../src/pages/tools/NotesBookToolView_children/NoteEditView.vue)

3. 顶部状态栏绑定
- [User-uniapp/src/pages/tools/NotesBookToolView_children/NoteEditView.vue](../src/pages/tools/NotesBookToolView_children/NoteEditView.vue)

4. 导航栏高度绑定
- [User-uniapp/src/pages/tools/NotesBookToolView_children/NoteEditView.vue](../src/pages/tools/NotesBookToolView_children/NoteEditView.vue)

5. 生命周期刷新
- [User-uniapp/src/pages/tools/NotesBookToolView_children/NoteEditView.vue](../src/pages/tools/NotesBookToolView_children/NoteEditView.vue)

---

## 9. 验收标准

### 9.1 功能验收

1. 顶部导航不与系统状态栏重叠
2. 导航按钮点击区域完整可点
3. 底部内容可完整滚动展示，不被手势条覆盖

### 9.2 多端验收

1. H5：不同浏览器窗口高度下无顶部遮挡
2. 小程序：不同机型胶囊位置下导航高度正常
3. App：iOS / Android 均无顶部与底部遮挡

---

## 10. 常见问题与排障

1. 现象：顶部被压住
- 排查：是否调用 refreshLayoutInfo
- 排查：paddingTop 是否绑定 statusBarHeight

2. 现象：底部按钮被遮挡
- 排查：根容器是否绑定 safeAreaInfo.bottom
- 排查：页面是否被固定高度容器裁切

3. 现象：不同端导航高度不一致
- 排查：是否直接写死高度
- 排查：小程序端胶囊 API 是否可用且未报错

---

## 11. 复用建议

后续新页面若使用自定义导航，建议统一复用本方案：

1. 页面内定义 navBarInfo 与 safeAreaInfo
2. onLoad + onShow 调用 refreshLayoutInfo
3. 顶部绑定 statusBarHeight 与 navBarHeight
4. 根容器绑定 safeAreaInfo.bottom

该模式可显著降低多端布局问题与适配维护成本。

---

## 12. 结论

当前方案通过 统一计算 + 页面绑定 + 生命周期刷新 三步完成状态栏/导航栏/底部安全区适配，已满足多端稳定显示要求，并具备良好的可复用性和可维护性。