241 lines
13 KiB
JavaScript
241 lines
13 KiB
JavaScript
|
// 契约：自定义导航页必须为右上角「胶囊按钮」留出安全区
|
|||
|
|
//
|
|||
|
|
// 由来（2026-09-23，用户在微信开发者工具实测反馈）：
|
|||
|
|
// 首页顶部、以及找对象/消息/活动/我的四个 Tab 页顶部的内容与微信胶囊按钮（「••• ⊙」）重合：
|
|||
|
|
// - 竖直方向：消息页四个快捷入口、活动页分类胶囊整体落在胶囊所在横带里被压住；
|
|||
|
|
// - 水平方向：首页「消息」、找对象「搜索」、活动「日历」、我的「设置 / 编辑资料」、
|
|||
|
|
// 聊天页「⋯」（ui-nav-bar 的右侧 slot）被压在胶囊下面，点不到。
|
|||
|
|
// 根因不是「padding 写小了」，而是**取值来源错了**：五个页面都写
|
|||
|
|
// `padding-top: env(safe-area-inset-top)`。该值只反映设备物理安全区（刘海/挖孔），
|
|||
|
|
// 安卓上常为 0，且**完全不反映胶囊按钮的位置**；右对齐元素更是从未让出胶囊宽度。
|
|||
|
|
// ⇒ 唯一可靠来源是 `wx.getMenuButtonBoundingClientRect()` 实测。
|
|||
|
|
//
|
|||
|
|
// 本守卫锁三层（都是「改回旧写法就会复发」的部分）：
|
|||
|
|
// A. 几何算法：胶囊必须落在导航行内垂直居中，右对齐元素必须整体落在胶囊左侧；
|
|||
|
|
// B. 页面覆盖：每个自定义导航页要么用 ui-nav-bar（组件统一处理），要么注入 navVars
|
|||
|
|
// 并在 wxss 里用 var(--nav-status/--nav-h/--nav-right)，且不得只依赖 env()；
|
|||
|
|
// C. 首页两张卡片的尺寸契约：宽度 1/3 + **显式 height**。
|
|||
|
|
// （同一批反馈的第二个问题：封面图只写 width 不写 height，小程序 <image> 会取默认
|
|||
|
|
// 240px = 480rpx，卡片被撑到约 480rpx 高。脚本 scripts/audit-image-height.mjs
|
|||
|
|
// 对修复前版本实测命中 .service-cover / .safety-cover 两条规则。）
|
|||
|
|
//
|
|||
|
|
// 自检：A/B/C 各带正反样例，防止守卫自己变哑（本项目已有三次「守卫全绿但缺陷在」的教训）。
|
|||
|
|
|
|||
|
|
import assert from 'node:assert/strict'
|
|||
|
|
import { existsSync, readFileSync, readdirSync } from 'node:fs'
|
|||
|
|
import { join, resolve } from 'node:path'
|
|||
|
|
import navMetrics from '../miniapp/utils/nav-metrics.js'
|
|||
|
|
|
|||
|
|
const root = resolve(import.meta.dirname, '..')
|
|||
|
|
const read = (path) => readFileSync(resolve(root, path), 'utf8')
|
|||
|
|
/**
|
|||
|
|
* 分析前剥离注释 —— 本项目已有一次教训：守卫被**自己的说明注释**误伤
|
|||
|
|
* （注释里写了示例代码，被当成真实代码断言）。本文件里就写了 `env(safe-area-inset-top)`
|
|||
|
|
* 作为反例说明，不剥离会立刻假红。
|
|||
|
|
* 注意保留换行，避免后续若按行定位时行号漂移（wxss-selectors.mjs 曾因此偏 68 行）。
|
|||
|
|
*/
|
|||
|
|
const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, ' '))
|
|||
|
|
const readWxss = (path) => stripComments(read(path))
|
|||
|
|
const { computeNavMetrics } = navMetrics
|
|||
|
|
|
|||
|
|
// ────────────────────────────── A. 几何算法 ──────────────────────────────
|
|||
|
|
|
|||
|
|
// 本守卫不得自己维护一份机型表当成事实源：真值必须来自胶囊实测。
|
|||
|
|
const metricSource = read('miniapp/utils/nav-metrics.js')
|
|||
|
|
assert.match(
|
|||
|
|
metricSource,
|
|||
|
|
/getMenuButtonBoundingClientRect/,
|
|||
|
|
'顶部安全区必须由 wx.getMenuButtonBoundingClientRect() 实测胶囊位置，不得写死机型常量',
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
const DEVICE_SAMPLES = [
|
|||
|
|
{ name: 'iPhone SE/8（无刘海）', windowWidth: 375, statusBarHeight: 20, capsule: { top: 24, left: 281, width: 87, height: 32 } },
|
|||
|
|
{ name: 'iPhone 13（刘海）', windowWidth: 390, statusBarHeight: 47, capsule: { top: 51, left: 292, width: 87, height: 32 } },
|
|||
|
|
{ name: 'Android 常见', windowWidth: 360, statusBarHeight: 24, capsule: { top: 32, left: 267, width: 87, height: 32 } },
|
|||
|
|
{ name: '小屏 Android', windowWidth: 320, statusBarHeight: 20, capsule: { top: 28, left: 228, width: 87, height: 32 } },
|
|||
|
|
]
|
|||
|
|
|
|||
|
|
for (const device of DEVICE_SAMPLES) {
|
|||
|
|
const m = computeNavMetrics(device)
|
|||
|
|
assert.equal(m.source, 'capsule', `${device.name}: 有胶囊信息时必须走实测分支`)
|
|||
|
|
|
|||
|
|
// 1) 胶囊在导航行内垂直居中 —— 导航行的上边缘 = 状态栏高度
|
|||
|
|
const capsuleCenter = device.capsule.top + device.capsule.height / 2
|
|||
|
|
const navBarCenter = m.statusBarHeight + m.navBarHeight / 2
|
|||
|
|
assert.ok(
|
|||
|
|
Math.abs(capsuleCenter - navBarCenter) <= 1,
|
|||
|
|
`${device.name}: 导航行与胶囊未垂直对齐（胶囊中心 ${capsuleCenter} vs 导航行中心 ${navBarCenter}）`,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 2) 内容起点 = 状态栏 + 导航行
|
|||
|
|
assert.equal(m.navTop, m.statusBarHeight + m.navBarHeight, `${device.name}: navTop 必须等于状态栏 + 导航行`)
|
|||
|
|
|
|||
|
|
// 3) 右对齐元素让出的宽度必须真正覆盖胶囊：右边缘 ≤ 胶囊左边缘 - 余量
|
|||
|
|
const contentRightEdge = device.windowWidth - m.reserve
|
|||
|
|
assert.ok(
|
|||
|
|
contentRightEdge <= device.capsule.left,
|
|||
|
|
`${device.name}: 右对齐元素右边缘 ${contentRightEdge} 仍在胶囊（左边缘 ${device.capsule.left}）右侧，会被压住`,
|
|||
|
|
)
|
|||
|
|
assert.ok(m.reserve <= device.windowWidth / 2, `${device.name}: 安全区不得超过半屏，否则内容区被挤没`)
|
|||
|
|
|
|||
|
|
// 4) 导航行高度落在合理区间，不能退化成 0/NaN
|
|||
|
|
assert.ok(m.navBarHeight >= 40 && m.navBarHeight <= 56, `${device.name}: 导航行高度异常 ${m.navBarHeight}`)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 拿不到胶囊信息（低版本基础库 / 接口异常）时必须退回兜底值，且宁可多留不可少留
|
|||
|
|
const fallback = computeNavMetrics({ windowWidth: 375, statusBarHeight: 44 })
|
|||
|
|
assert.equal(fallback.source, 'fallback', '无胶囊信息时应标记为兜底取值')
|
|||
|
|
assert.ok(fallback.navTop >= 64, `无胶囊信息时也必须留足顶部空间，实得 ${fallback.navTop}`)
|
|||
|
|
|
|||
|
|
// 极端输入：胶囊 tops 落在状态栏内（gap 为负）时不得产出 NaN / 负值
|
|||
|
|
const degenerate = computeNavMetrics({ windowWidth: 375, statusBarHeight: 44, capsule: { top: 40, left: 281, width: 87, height: 32 } })
|
|||
|
|
assert.ok(Number.isFinite(degenerate.navBarHeight) && degenerate.navBarHeight >= 40, '胶囊与状态栏重叠时仍须给出合法导航行高度')
|
|||
|
|
|
|||
|
|
// ─────────────────────── B. 页面覆盖：自定义导航页 ───────────────────────
|
|||
|
|
|
|||
|
|
/** 纯函数：审计一个「自带导航行」的自定义导航页，返回问题清单
|
|||
|
|
* （并入参已剥离注释：见 stripComments 注释）*/
|
|||
|
|
function auditTabHeader({ wxml = '', ts = '', wxss = '' } = {}) {
|
|||
|
|
const issues = []
|
|||
|
|
const rootTag = (wxml.match(/<view[^>]*reference-page[^>]*>/) || [''])[0]
|
|||
|
|
if (!/style="\{\{navVars\}\}"/.test(rootTag)) {
|
|||
|
|
issues.push('根节点未注入 style="{{navVars}}"（拿不到实测安全区）')
|
|||
|
|
}
|
|||
|
|
if (!/navVars\s*:\s*''/.test(ts)) issues.push('data 里缺少 navVars 初始值')
|
|||
|
|
if (!/require\(['"]\.\.\/\.\.\/utils\/nav-metrics['"]\)/.test(ts)) issues.push('未引入 utils/nav-metrics')
|
|||
|
|
if (!/setData\(\s*navSafeData\(\)\s*\)/.test(ts)) issues.push('未在 onLoad 里 setData(navSafeData())')
|
|||
|
|
// env(safe-area-inset-top) 本身不是非法 API，但它只反映设备物理安全区、不反映胶囊位置，
|
|||
|
|
// 单独使用即本次缺陷的原始写法 —— 出现即判红，改用 var(--nav-status)。
|
|||
|
|
if (/env\(safe-area-inset-top\)/.test(wxss)) issues.push('仍在用 env(safe-area-inset-top)（不反映胶囊位置）')
|
|||
|
|
if (!/var\(--nav-status/.test(wxss)) issues.push('顶部未用 var(--nav-status) 顶开状态栏')
|
|||
|
|
if (!/var\(--nav-h/.test(wxss)) issues.push('导航行高度未用 var(--nav-h)，无法与胶囊垂直对齐')
|
|||
|
|
if (!/var\(--nav-right/.test(wxss)) issues.push('右对齐元素未让出 var(--nav-right) 胶囊安全区')
|
|||
|
|
return issues
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 自检：正向样例（修好之后的样子）必须 0 问题；反向样例（本次缺陷的原始写法）必须全部命中
|
|||
|
|
const SELF_CHECK = [
|
|||
|
|
{
|
|||
|
|
name: '正向：注入 navVars + 用 var(--nav-status/--nav-h/--nav-right)',
|
|||
|
|
sample: {
|
|||
|
|
wxml: '<view class="page app-page reference-page" style="{{navVars}}">',
|
|||
|
|
ts: "const { navSafeData } = require('../../utils/nav-metrics')\nnavVars: ''\nthis.setData(navSafeData())",
|
|||
|
|
wxss: '.hero{padding:var(--nav-status, 44px) 24rpx 24rpx}.nav{height:var(--nav-h, 80rpx)}.act{right:var(--nav-right, 102px)}',
|
|||
|
|
},
|
|||
|
|
expect: 0,
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
name: '反向：本次缺陷的原始写法（只用 env(safe-area-inset-top)，无 navVars）',
|
|||
|
|
sample: {
|
|||
|
|
wxml: '<view class="page app-page reference-page">',
|
|||
|
|
ts: 'Page({ data: {}, onLoad() {} })',
|
|||
|
|
wxss: '.hero{padding:env(safe-area-inset-top) 24rpx 24rpx}.nav{height:88rpx}.act{right:0}',
|
|||
|
|
},
|
|||
|
|
expect: 8,
|
|||
|
|
},
|
|||
|
|
]
|
|||
|
|
for (const c of SELF_CHECK) {
|
|||
|
|
const issues = auditTabHeader(c.sample)
|
|||
|
|
assert.equal(
|
|||
|
|
issues.length,
|
|||
|
|
c.expect,
|
|||
|
|
`守卫自检失败 —— ${c.name}\n期望 ${c.expect} 条问题，实得 ${issues.length} 条：\n ${issues.join('\n ')}`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 从文件系统推导清单（不写死），新增自定义导航页会被自动纳入
|
|||
|
|
const pagesRoot = resolve(root, 'miniapp/pages')
|
|||
|
|
const pageNames = readdirSync(pagesRoot, { withFileTypes: true })
|
|||
|
|
.filter((entry) => entry.isDirectory())
|
|||
|
|
.map((entry) => entry.name)
|
|||
|
|
|
|||
|
|
const customNavPages = pageNames.filter((name) => {
|
|||
|
|
const jsonPath = join(pagesRoot, name, `${name}.json`)
|
|||
|
|
if (!existsSync(jsonPath)) return false
|
|||
|
|
try {
|
|||
|
|
return JSON.parse(readFileSync(jsonPath, 'utf8')).navigationStyle === 'custom'
|
|||
|
|
} catch {
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
assert.ok(customNavPages.length >= 20, `自定义导航页只找到 ${customNavPages.length} 个 —— 扫描清单可能失配，拒绝报绿`)
|
|||
|
|
|
|||
|
|
const selfNavPages = customNavPages.filter((name) => {
|
|||
|
|
const wxmlPath = join(pagesRoot, name, `${name}.wxml`)
|
|||
|
|
return existsSync(wxmlPath) && !readFileSync(wxmlPath, 'utf8').includes('ui-nav-bar')
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const EXPECTED_SELF_NAV = ['index', 'discover', 'messages', 'activity', 'mine']
|
|||
|
|
for (const name of EXPECTED_SELF_NAV) {
|
|||
|
|
assert.ok(selfNavPages.includes(name), `${name} 应自带导航行（未用 ui-nav-bar）但未被识别 —— 清单失配`)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
const failures = []
|
|||
|
|
for (const name of selfNavPages) {
|
|||
|
|
const issues = auditTabHeader({
|
|||
|
|
wxml: read(`miniapp/pages/${name}/${name}.wxml`),
|
|||
|
|
ts: read(`miniapp/pages/${name}/${name}.ts`),
|
|||
|
|
wxss: readWxss(`miniapp/pages/${name}/${name}.wxss`),
|
|||
|
|
})
|
|||
|
|
if (issues.length) failures.push(`${name}: ${issues.join('；')}`)
|
|||
|
|
}
|
|||
|
|
assert.deepEqual(failures, [], `以下自定义导航页仍会让内容与胶囊按钮重合：\n ${failures.join('\n ')}`)
|
|||
|
|
|
|||
|
|
// 右侧 slot 的使用者（聊天页「⋯」）依赖 ui-nav-bar 的胶囊安全区，必须仍走组件
|
|||
|
|
for (const name of pageNames) {
|
|||
|
|
const wxmlPath = join(pagesRoot, name, `${name}.wxml`)
|
|||
|
|
if (!existsSync(wxmlPath)) continue
|
|||
|
|
if (readFileSync(wxmlPath, 'utf8').includes('slot="right"')) {
|
|||
|
|
assert.ok(
|
|||
|
|
read(`miniapp/pages/${name}/${name}.wxml`).includes('ui-nav-bar'),
|
|||
|
|
`${name} 用了导航栏右侧 slot 但未使用 ui-nav-bar，右侧操作会落在胶囊下面`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// ui-nav-bar 组件自身必须处理胶囊（20 个非 Tab 页共用它）
|
|||
|
|
const navBarJs = read('miniapp/components/nav-bar/index.js')
|
|||
|
|
const navBarWxss = read('miniapp/components/nav-bar/index.wxss')
|
|||
|
|
assert.match(navBarJs, /getNavMetrics/, 'ui-nav-bar 必须实测胶囊位置（见 utils/nav-metrics.js）')
|
|||
|
|
assert.match(navBarJs, /--nav-right/, 'ui-nav-bar 必须把胶囊安全区注入 wxss')
|
|||
|
|
assert.match(
|
|||
|
|
navBarWxss,
|
|||
|
|
/\.ui-nav__title\s*\{[^}]*max-width:\s*calc\(100% - 2 \* var\(--nav-right/,
|
|||
|
|
'ui-nav-bar 标题必须让开胶囊（左右对称留白，才能既居中又不被压住）',
|
|||
|
|
)
|
|||
|
|
assert.match(
|
|||
|
|
navBarWxss,
|
|||
|
|
/\.ui-nav__right\s*\{[^}]*padding-right:\s*var\(--nav-right/,
|
|||
|
|
'ui-nav-bar 右侧 slot 必须整体左移到胶囊左侧',
|
|||
|
|
)
|
|||
|
|
assert.match(navBarWxss, /\.ui-nav__bar\s*\{[^}]*height:\s*var\(--nav-h/, 'ui-nav-bar 导航行高度必须与胶囊对齐')
|
|||
|
|
|
|||
|
|
// ─────────────────── C. 首页两张卡片：1/3 尺寸 + 显式高度 ───────────────────
|
|||
|
|
|
|||
|
|
const indexWxss = readWxss('miniapp/pages/index/index.wxss')
|
|||
|
|
|
|||
|
|
const cardRule = (indexWxss.match(/\.mini-card\s*\{([^}]*)\}/) || [])[1] || ''
|
|||
|
|
assert.ok(cardRule, '首页必须保留 .mini-card 规则（公益服务 / 安全提醒的 1/3 小卡）')
|
|||
|
|
assert.match(cardRule, /width:\s*calc\(\(100% - var\(--spacing-2\) \* 2\) \/ 3\)/, '小卡宽度必须是三分一行（原尺寸的 1/3）')
|
|||
|
|
assert.match(cardRule, /(?:^|;)\s*height:\s*\d+rpx/, '小卡必须写死高度（约 1/3），否则会被内容或默认高度撑开')
|
|||
|
|
|
|||
|
|
const coverRule = (indexWxss.match(/\.mini-card-cover\s*\{([^}]*)\}/) || [])[1] || ''
|
|||
|
|
assert.ok(coverRule, '首页必须保留 .mini-card-cover 规则')
|
|||
|
|
assert.match(coverRule, /(?:^|;)\s*width\s*:/, '封面必须有显式宽度')
|
|||
|
|
assert.match(
|
|||
|
|
coverRule,
|
|||
|
|
/(?:^|;)\s*height\s*:/,
|
|||
|
|
'封面必须写显式 height —— 小程序 <image> 未指定高度时取默认 240px(=480rpx)，卡片会被撑到约 480rpx',
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// 回归钉：本次缺陷的两条「只写 width / min-height」的封面规则不得复活
|
|||
|
|
for (const legacy of ['.service-cover', '.safety-cover']) {
|
|||
|
|
assert.ok(
|
|||
|
|
!new RegExp(`\\${legacy}\\s*\\{`).test(indexWxss),
|
|||
|
|
`首页不得恢复「只写 width 不写 height」的 ${legacy} 规则（该写法会把卡片撑到约 480rpx）`,
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
console.log(`胶囊安全区契约通过（实测机型 ${DEVICE_SAMPLES.length} 组 + 自带导航行页面 ${selfNavPages.length} 个）`)
|