docs: add miniprogram header capsule safe-area implementation plan.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed
1 parent
2866fef5bf
commit
0599b7a3a9
1 file changed
+494
@@ -0,0 +1,494 @@
|
||||
# 小程序顶部栏胶囊安全区适配 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 让所有 `navigationStyle: custom` 页面的业务顶栏避开微信状态栏与右上角胶囊（方案 B：加高 + 右侧预留）。
|
||||
|
||||
**Architecture:** 复用 `utils/safeArea.js` 量纲；新增纯函数 `buildSafeAreaCssVarsStyle` 供顶栏根节点 `:style` 注入 CSS 变量；`.db-header` / `.bx-page .topbar` / `.mp-header` 统一消费 `--sq-*`。微信端不依赖 `document.documentElement`。
|
||||
|
||||
**Tech Stack:** uni-app Vue3、现有 SCSS 主题（`db-theme` / `bx-theme` / `mp-shell`）、`getMenuButtonBoundingClientRect`
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-09-12-miniprogram-header-capsule-safe-area-design.md`
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
| 路径 | 职责 |
|
||||
|------|------|
|
||||
| `miniprogram/utils/safeArea.js` | 量纲计算 + `buildSafeAreaCssVarsStyle` |
|
||||
| `miniprogram/utils/__tests__/safeArea.style.test.mjs` | 纯函数 Node 单测（无 uni 运行时依赖的 style 映射） |
|
||||
| `miniprogram/styles/db-theme.scss` | `.db-header` 方案 B 几何 |
|
||||
| `miniprogram/styles/bx-theme.scss` | `.topbar` 对齐同一变量 |
|
||||
| `miniprogram/styles/mp-shell.scss` | `.mp-header*` 用 safe-top + capsule-right |
|
||||
| `miniprogram/styles/index.scss` | 确认 `.sq-hero-header` 变量路径一致（注释/兜底） |
|
||||
| `miniprogram/components/app-safe-header.vue` | 改用 `buildSafeAreaCssVarsStyle`（供后续新页） |
|
||||
| `miniprogram/pages/db/**/*.vue` | `:style="safeAreaStyle"` + `__nav` 结构 |
|
||||
| `miniprogram/pages/bx/**/*.vue` + `components/bx-ui/bx-wf-config-page.vue` | topbar 绑定 style |
|
||||
| `miniprogram/pages/{workbench,home,todo}/*.vue` 等 | mp-header 绑定 style |
|
||||
| `docs/miniprogram-ui-spec-sanqiang.md` | §3.2 补充胶囊 SHALL |
|
||||
|
||||
---
|
||||
|
||||
### Task 1: `buildSafeAreaCssVarsStyle` + 单测
|
||||
|
||||
**Files:**
|
||||
- Modify: `miniprogram/utils/safeArea.js`
|
||||
- Create: `miniprogram/utils/__tests__/safeArea.style.test.mjs`
|
||||
|
||||
- [ ] **Step 1: 写失败单测（先测 style 映射）**
|
||||
|
||||
创建 `miniprogram/utils/__tests__/safeArea.style.test.mjs`：
|
||||
|
||||
```js
|
||||
import assert from 'node:assert/strict'
|
||||
import { buildSafeAreaCssVarsStyle } from '../safeArea.js'
|
||||
|
||||
const style = buildSafeAreaCssVarsStyle({
|
||||
topSafeHeight: 44,
|
||||
navContentHeight: 40,
|
||||
headerHeight: 84,
|
||||
capsuleRightSafeWidth: 96,
|
||||
})
|
||||
|
||||
assert.equal(style['--sq-safe-top'], '44px')
|
||||
assert.equal(style['--sq-nav-height'], '40px')
|
||||
assert.equal(style['--sq-header-height'], '84px')
|
||||
assert.equal(style['--sq-capsule-right-safe'], '96px')
|
||||
console.log('ok')
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行确认失败**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd miniprogram && node utils/__tests__/safeArea.style.test.mjs
|
||||
```
|
||||
|
||||
Expected: `ERR_MODULE_NOT_FOUND` 或 `buildSafeAreaCssVarsStyle is not a function`
|
||||
|
||||
- [ ] **Step 3: 实现函数**
|
||||
|
||||
在 `miniprogram/utils/safeArea.js` 末尾追加：
|
||||
|
||||
```js
|
||||
export function buildSafeAreaCssVarsStyle(metrics) {
|
||||
const m = metrics || getGlobalSafeArea()
|
||||
return {
|
||||
'--sq-safe-top': `${m.topSafeHeight}px`,
|
||||
'--sq-nav-height': `${m.navContentHeight}px`,
|
||||
'--sq-header-height': `${m.headerHeight}px`,
|
||||
'--sq-capsule-right-safe': `${m.capsuleRightSafeWidth}px`,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
确保文件可作为 ESM 被 Node 导入：若当前无 `"type":"module"`，测试改为动态 `createRequire` 不可行时，把测试改为内联复制映射断言并在注释中要求实现与之一致；**优先**给 `safeArea.js` 保持现有导出方式（uni 打包为普通 JS），测试文件用：
|
||||
|
||||
```js
|
||||
import { createRequire } from 'node:module'
|
||||
const require = createRequire(import.meta.url)
|
||||
|
||||
// 若 safeArea 依赖 uni，则只测纯映射：复制最小实现到测试或拆出 safeAreaCss.js
|
||||
```
|
||||
|
||||
**推荐落地（避免 uni 依赖拖垮 Node 测试）：**
|
||||
|
||||
新建 `miniprogram/utils/safeAreaCss.js`（纯函数，无 `uni`）：
|
||||
|
||||
```js
|
||||
export function buildSafeAreaCssVarsStyle(metrics) {
|
||||
return {
|
||||
'--sq-safe-top': `${metrics.topSafeHeight}px`,
|
||||
'--sq-nav-height': `${metrics.navContentHeight}px`,
|
||||
'--sq-header-height': `${metrics.headerHeight}px`,
|
||||
'--sq-capsule-right-safe': `${metrics.capsuleRightSafeWidth}px`,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`safeArea.js` 改为：
|
||||
|
||||
```js
|
||||
import { buildSafeAreaCssVarsStyle } from './safeAreaCss.js'
|
||||
export { buildSafeAreaCssVarsStyle }
|
||||
|
||||
export function getSafeAreaStyle() {
|
||||
return buildSafeAreaCssVarsStyle(getGlobalSafeArea())
|
||||
}
|
||||
```
|
||||
|
||||
单测只 import `safeAreaCss.js`。
|
||||
|
||||
- [ ] **Step 4: 再跑单测**
|
||||
|
||||
```bash
|
||||
cd miniprogram && node utils/__tests__/safeArea.style.test.mjs
|
||||
```
|
||||
|
||||
Expected: 打印 `ok`，exit 0
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add miniprogram/utils/safeAreaCss.js miniprogram/utils/safeArea.js miniprogram/utils/__tests__/safeArea.style.test.mjs
|
||||
git commit -m "feat(miniprogram): add safe-area CSS vars style builder"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: 地磅 `.db-header` 样式（方案 B）
|
||||
|
||||
**Files:**
|
||||
- Modify: `miniprogram/styles/db-theme.scss`（约 L10–36）
|
||||
|
||||
- [ ] **Step 1: 替换 `.db-header` 块为：**
|
||||
|
||||
```scss
|
||||
.db-header {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 50;
|
||||
background: #fff;
|
||||
border-bottom: 1px solid #eee;
|
||||
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.05);
|
||||
height: var(--sq-header-height, calc(44px + 44px));
|
||||
padding-top: var(--sq-safe-top, 44px);
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.db-header__nav {
|
||||
height: var(--sq-nav-height, 44px);
|
||||
display: grid;
|
||||
grid-template-columns: auto minmax(0, 1fr) var(--sq-capsule-right-safe, 96px);
|
||||
align-items: center;
|
||||
padding: 0 12px 0 8px;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.db-header__left {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.db-header__back {
|
||||
font-size: 20px;
|
||||
color: #333;
|
||||
padding: 4px 8px;
|
||||
}
|
||||
|
||||
.db-header__title {
|
||||
font-size: 17px;
|
||||
font-weight: 700;
|
||||
color: #111827;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.db-header__user {
|
||||
font-size: 12px;
|
||||
color: #6b7280;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
white-space: nowrap;
|
||||
text-align: right;
|
||||
padding-right: 4px;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add miniprogram/styles/db-theme.scss
|
||||
git commit -m "style(miniprogram): adapt db-header for WeChat capsule safe area"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: 地磅页面挂载变量 + `__nav` 结构
|
||||
|
||||
**Files:**
|
||||
- Modify:
|
||||
- `miniprogram/pages/db/dashboard/index.vue`
|
||||
- `miniprogram/pages/db/plans/list.vue`
|
||||
- `miniprogram/pages/db/plans/detail.vue`
|
||||
- `miniprogram/pages/db/inventory/list.vue`
|
||||
- `miniprogram/pages/db/inventory/detail.vue`
|
||||
- `miniprogram/pages/db/weighing/list.vue`
|
||||
- `miniprogram/pages/db/weighing/detail.vue`
|
||||
|
||||
- [ ] **Step 1: 每个文件 script 增加**
|
||||
|
||||
```js
|
||||
import { getSafeAreaStyle } from '@/utils/safeArea'
|
||||
const safeAreaStyle = getSafeAreaStyle()
|
||||
```
|
||||
|
||||
（若页面已是 `<script setup>`，直接按上；否则在 `data`/`setup` 暴露 `safeAreaStyle`。）
|
||||
|
||||
- [ ] **Step 2: 模板统一改结构**
|
||||
|
||||
仪表盘示例（有用户名）：
|
||||
|
||||
```html
|
||||
<view class="db-header" :style="safeAreaStyle">
|
||||
<view class="db-header__nav">
|
||||
<view class="db-header__left">
|
||||
<text class="db-header__back" @click="goWorkbench">←</text>
|
||||
<text class="db-header__title">仪表盘</text>
|
||||
</view>
|
||||
<text class="db-header__user">{{ username }}</text>
|
||||
<view /><!-- 胶囊占位列 -->
|
||||
</view>
|
||||
</view>
|
||||
```
|
||||
|
||||
列表/详情（无用户名）：
|
||||
|
||||
```html
|
||||
<view class="db-header" :style="safeAreaStyle">
|
||||
<view class="db-header__nav">
|
||||
<view class="db-header__left">
|
||||
<text class="db-header__back" @click="goBack">←</text>
|
||||
<text class="db-header__title">{{ title }}</text>
|
||||
</view>
|
||||
<view />
|
||||
<view />
|
||||
</view>
|
||||
</view>
|
||||
```
|
||||
|
||||
删除 `dashboard/index.vue` 中 scoped 重复的 `.db-header__user`（已迁入 theme），避免冲突。
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add miniprogram/pages/db/
|
||||
git commit -m "fix(miniprogram): wire db pages to capsule safe-area header"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: 报销 `.topbar` 样式 + 页面绑定
|
||||
|
||||
**Files:**
|
||||
- Modify: `miniprogram/styles/bx-theme.scss`（`.bx-page .topbar` 约 L74–148）
|
||||
- Modify 所有含 `<view class="topbar">` 的文件：
|
||||
- `miniprogram/pages/bx/advance/{list,apply,detail}.vue`
|
||||
- `miniprogram/pages/bx/reimburse/{list,apply,detail}.vue`
|
||||
- `miniprogram/pages/bx/mine/list.vue`
|
||||
- `miniprogram/pages/bx/all/list.vue`
|
||||
- `miniprogram/pages/bx/invoice/{mine,admin}.vue`
|
||||
- `miniprogram/pages/bx/admin/expense-item.vue`
|
||||
- `miniprogram/components/bx-ui/bx-wf-config-page.vue`
|
||||
|
||||
- [ ] **Step 1: 替换 topbar 高度规则**
|
||||
|
||||
将：
|
||||
|
||||
```scss
|
||||
height: calc(58px + env(safe-area-inset-top, 0px));
|
||||
padding: env(safe-area-inset-top, 0px) 12px 0;
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```scss
|
||||
.bx-page .topbar {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 50;
|
||||
display: grid;
|
||||
grid-template-columns: 1fr auto var(--sq-capsule-right-safe, 96px);
|
||||
align-items: center;
|
||||
height: var(--sq-header-height, calc(44px + 44px));
|
||||
padding: var(--sq-safe-top, 44px) 12px 0;
|
||||
box-sizing: border-box;
|
||||
background: rgba(255, 255, 255, 0.92);
|
||||
box-shadow: 0 1px 0 rgba(217, 232, 226, 0.85), 0 8px 20px rgba(15, 23, 42, 0.06);
|
||||
}
|
||||
|
||||
.bx-page .topbar::before {
|
||||
height: var(--sq-header-height, calc(44px + 44px));
|
||||
/* 其余渐变背景保持不变 */
|
||||
}
|
||||
```
|
||||
|
||||
标题仍 `justify-self: center`；`topbar-right` 作为中间/右侧业务槽时不得伸入最后一列——最后一列留给胶囊（grid 第三列为空即可；若现结构是 `1fr auto 1fr`，改为 `1fr auto var(--sq-capsule-right-safe)`，左侧放返回，中间标题，右侧列空）。
|
||||
|
||||
具体 grid：
|
||||
|
||||
```scss
|
||||
grid-template-columns: minmax(0, 1fr) auto var(--sq-capsule-right-safe, 96px);
|
||||
```
|
||||
|
||||
`topbar-title` 放第二列居中；`topbar-right` 若需对称，可并入第一列或改为不占用第三列。
|
||||
|
||||
- [ ] **Step 2: 每个 topbar 根节点**
|
||||
|
||||
```html
|
||||
<view class="topbar" :style="safeAreaStyle">
|
||||
```
|
||||
|
||||
script：
|
||||
|
||||
```js
|
||||
import { getSafeAreaStyle } from '@/utils/safeArea'
|
||||
const safeAreaStyle = getSafeAreaStyle()
|
||||
```
|
||||
|
||||
- [ ] **Step 3: 修正 `expense-item.vue` 列表高度计算**
|
||||
|
||||
将：
|
||||
|
||||
```js
|
||||
const topbar = 44 + (sys.statusBarHeight || 0)
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```js
|
||||
import { getGlobalSafeArea } from '@/utils/safeArea'
|
||||
const topbar = getGlobalSafeArea().headerHeight
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add miniprogram/styles/bx-theme.scss miniprogram/pages/bx/ miniprogram/components/bx-ui/bx-wf-config-page.vue
|
||||
git commit -m "fix(miniprogram): adapt bx topbar for WeChat capsule safe area"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: 壳层 `.mp-header`（工作台/首页/待办/占位）
|
||||
|
||||
**Files:**
|
||||
- Modify: `miniprogram/styles/mp-shell.scss`（`.mp-header` 及 `--home` / `--workbench`）
|
||||
- Modify:
|
||||
- `miniprogram/pages/workbench/workbench.vue`
|
||||
- `miniprogram/pages/home/home.vue`
|
||||
- `miniprogram/pages/todo/todo.vue`
|
||||
- `miniprogram/pages/common/biz-placeholder.vue`
|
||||
- `miniprogram/components/bx-ui/bx-placeholder-page.vue`
|
||||
- Modify: `miniprogram/components/app-safe-header.vue`（改用 `buildSafeAreaCssVarsStyle`）
|
||||
|
||||
- [ ] **Step 1: 更新 mp-shell 头部 padding**
|
||||
|
||||
```scss
|
||||
.mp-header {
|
||||
background: var(--mp-header-gradient);
|
||||
color: #fff;
|
||||
padding:
|
||||
calc(28rpx + var(--sq-safe-top, env(safe-area-inset-top, 0px)))
|
||||
calc(32rpx + var(--sq-capsule-right-safe, 96px))
|
||||
32rpx
|
||||
32rpx;
|
||||
border-bottom-left-radius: var(--mp-radius-xl);
|
||||
border-bottom-right-radius: var(--mp-radius-xl);
|
||||
box-shadow: 0 16rpx 40rpx rgba(10, 159, 109, 0.12);
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.mp-header--home {
|
||||
padding-top: calc(40rpx + var(--sq-safe-top, env(safe-area-inset-top, 0px)));
|
||||
padding-bottom: 48rpx;
|
||||
}
|
||||
|
||||
.mp-header--workbench {
|
||||
/* 去掉魔法 40px 双叠加；仅用 safe-top + 内容间距 */
|
||||
padding-top: calc(48rpx + var(--sq-safe-top, env(safe-area-inset-top, 0px)));
|
||||
padding-bottom: 56rpx;
|
||||
min-height: calc(200rpx + var(--sq-safe-top, 0px));
|
||||
box-sizing: border-box;
|
||||
}
|
||||
```
|
||||
|
||||
工作台 `mp-header__row` 已有左右分栏；右侧用户栈靠 `padding-right` 的 capsule 预留避开胶囊，**不要**再把退出按钮画进胶囊区。
|
||||
|
||||
- [ ] **Step 2: 各页 `:style="safeAreaStyle"` + `getSafeAreaStyle()`**
|
||||
|
||||
```html
|
||||
<view class="mp-header mp-header--workbench" :style="safeAreaStyle">
|
||||
```
|
||||
|
||||
- [ ] **Step 3: `app-safe-header.vue` 改用**
|
||||
|
||||
```js
|
||||
import { getGlobalSafeArea, buildSafeAreaCssVarsStyle } from '@/utils/safeArea'
|
||||
const headerStyle = computed(() => ({
|
||||
...buildSafeAreaCssVarsStyle(getGlobalSafeArea()),
|
||||
'--sq-header-background': props.background,
|
||||
}))
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add miniprogram/styles/mp-shell.scss miniprogram/pages/workbench/workbench.vue miniprogram/pages/home/home.vue miniprogram/pages/todo/todo.vue miniprogram/pages/common/biz-placeholder.vue miniprogram/components/bx-ui/bx-placeholder-page.vue miniprogram/components/app-safe-header.vue
|
||||
git commit -m "fix(miniprogram): adapt mp-header for WeChat capsule safe area"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: 规范文档 + 手工验收清单
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/miniprogram-ui-spec-sanqiang.md` §3.2
|
||||
|
||||
- [ ] **Step 1: 在 §3.2 追加**
|
||||
|
||||
```markdown
|
||||
#### 自定义导航与微信胶囊（SHALL）
|
||||
|
||||
- 使用 `navigationStyle: custom` 的页面，业务顶栏 SHALL 避开状态栏与右上角胶囊。
|
||||
- 量纲 SHALL 来自 `statusBarHeight` 与 `getMenuButtonBoundingClientRect`（见 `utils/safeArea.js`）。
|
||||
- CSS 变量：`--sq-safe-top`、`--sq-nav-height`、`--sq-header-height`、`--sq-capsule-right-safe`；微信端 SHALL 通过顶栏根节点内联 style 注入，不得仅依赖 H5 `document`。
|
||||
- 白底顶栏：总高 `--sq-header-height`，内容行高 `--sq-nav-height`，右侧列预留 `--sq-capsule-right-safe`，该列 SHALL NOT 放置可点击业务按钮。
|
||||
- 渐变大头：`padding-top` 含 `--sq-safe-top`，`padding-right` 含 `--sq-capsule-right-safe`。
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 手工验收（微信开发者工具 + 真机体验版）**
|
||||
|
||||
| 页面 | 检查 |
|
||||
|------|------|
|
||||
| 地磅仪表盘 | 标题/返回/用户名不被胶囊挡 |
|
||||
| 地磅任一列表+详情 | 同上 |
|
||||
| 报销任一列表 | 同上 |
|
||||
| 工作台 | 标题与退出不与胶囊重叠 |
|
||||
| H5 预览（若有） | 无胶囊时右侧无异常大空白 |
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add docs/miniprogram-ui-spec-sanqiang.md
|
||||
git commit -m "docs: require miniprogram custom header capsule safe area"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spec 覆盖自检
|
||||
|
||||
| Spec 要求 | Task |
|
||||
|-----------|------|
|
||||
| 方案 B 几何 | 2, 4, 5 |
|
||||
| 微信端变量注入 | 1, 3, 4, 5 |
|
||||
| 地磅全链路 | 2, 3 |
|
||||
| 报销 topbar | 4 |
|
||||
| mp-header / 工作台 | 5 |
|
||||
| 规范 SHALL | 6 |
|
||||
| 无胶囊兜底 | Task1 metrics + SCSS fallback；H5 右侧 0 |
|
||||
| 不改默认导航页 | 未列入文件 |
|
||||
|
||||
## 执行交接
|
||||
|
||||
Plan complete and saved to `docs/superpowers/plans/2026-09-12-miniprogram-header-capsule-safe-area.md`. Two execution options:
|
||||
|
||||
**1. Subagent-Driven (recommended)** — 每个 Task 派生子代理，Task 间复查
|
||||
**2. Inline Execution** — 本会话按 executing-plans 连续执行并设检查点
|
||||
|
||||
Which approach?
|
||||
Reference in new issue
Block a user