docs(readme): 新增「UI 排版规范」14 节全站强约束 + 设备平台注意事项

- 字号 10 档 / 圆角 3 档 / 5px 间距网格 / 颜色 token 与 npm run lint:layout 自检一一对应
- 本地绘制(二维码/条形码)、控件内嵌图标(可见标记为控件高 55~60%,热区独立)、页面骨架与公共类约定
- 设备平台说明:真机 WebView 由 Chrome 应用提供,能力以实测为准(勿照搬 Android 版本推断);媒体查询 rem 按 16px 解析、0x0 视口会归零 vw/vh、vw 数值不可取整
- 交互约定:行操作为「单击弹确认窗 + 右键直执行」,长按已废弃(真机难摁)
This commit is contained in:
liufumingren 2026-09-27 03:15:12 +08:00
parent 20f0454c79
commit 2240dbba7a

240
README.md
View File

@ -1,5 +1,243 @@
# WMS 工作台(wms_worker_station)
## UI 排版规范(全站强约束)
> 一句话:**布局用 rem(1rem = 100px),间距用 5px 网格;控件高度 36px,行高两档,字号 10 档,圆角 3 档,控件内嵌图标取控件高度的 55~60%。**
> 新增页面/组件照此写;改动旧页面时按本节重新排一遍。
> 页面级结构与自查见 **第 14 节**;真机平台注意见 **第 13 节**。
### 1. 尺寸基数:1rem = 100px
- 唯一实现 `src/render-common/rem-base.js`:`html.fontSize = 100 × min(1, 视口宽 / 1280)`
- **宽度 ≥1280 一律 1rem = 100px**(1280 / 1920 / 2560 / 4K 都一样,也不看窗口高度);
- 窄于 1280 等比缩小,下限 50px(640 宽)。
- 口径:**CSS 里的 rem 值 = 设计稿像素 ÷ 100**(写 `0.5rem` 就是 50px)。
- 真机 APP-PLUS 由 `App.vue` 的 `html { font-size: 7.8125vw !important }` 承担;`7.8125vw = 100/1280`,**必须精确,不要取整**。
- **小数位最多 2 位**(2 位 = 1px 精度,误差 ≤0.5px),`0.20` 写成 `0.2`。
- **媒体查询里不要用 rem 写断点**:媒体查询中的 `rem` 按**初始 16px** 解析,与本项目 1rem = 100px 不是一套(例如写 `20.48rem` 实际是 327px,永远不会触发)。
本项目**不需要窄屏断点**:宽度 <1280 时整站按比例缩放(下限 0.5 倍 = 640px 宽);桌面窗口由 `electron/main.js` 的 `minWidth: 1024` / `minHeight: 640` 兜底。
如需新增断点,写**真实 px** 并注明理由。
### 2. 控件高度 / 行高
| 类型 | rem | ≥1280 时 | 用途 |
|---|---|---|---|
| 控件 | `0.36rem` | 36px | **按钮、输入框、下拉、tab、步进按钮全部统一这一档** |
| 表格/列表行 | `0.5rem` 左右 | 50px | 表格行、列表行(订单表格实为 `0.52`/`0.56rem`,以内容为准) |
| 顶栏 | `0.7rem` | 70px | 顶栏高度,内行由 `0.5rem` 的 logo 决定 |
- **控件不要再写 `0.5rem` 高度**(2026-09-25 已全站从 0.5rem 降到 0.36rem);`80px`/`120px` 是移动端口径,PC 上更不要用。
- 图标、图片、头像、缩略图等**非控件**不套这几档,按内容尺寸走。
- **控件内部的图标/徽标/字形**另有比例要求(可见标记 ≈ 控件高度的 55~60%),见第 12 节。
- 按钮**不要写死宽度**:给高度 + 左右 `padding`,宽度跟内容走。
- 给 `button` 设高度时**必须同时设 `line-height`**(uni-app 默认 `line-height: 2.55555556`,不设会文字偏移/被裁)。
- 多行粘贴框(订单页 `.batch-review-input`)例外,按内容给高度。
### 3. 字号:只有 10 档
| token | rem | ≥1280 | 用途 |
|---|---|---|---|
| `--wms-font-xs` | 0.15 | 15px | 标签、角标、辅助提示 |
| `--wms-font-sm` | 0.17 | 17px | 说明文字 |
| `--wms-font-base` | 0.18 | 18px | 正文、表格 |
| `--wms-font-md` | 0.2 | 20px | 正文强调 |
| `--wms-font-lg` | 0.21 | 21px | 卡片标题 |
| `--wms-font-xl` | 0.22 | 22px | 导航菜单、大标题 |
| `--wms-font-title` | 0.25 | 25px | 页面/弹窗标题 |
| `--wms-font-2xl` | 0.3 | 30px | 大号数值(称重输入、数量) |
| `--wms-font-3xl` | 0.35 | 35px | 合计、重点数字 |
| `--wms-font-4xl` | 0.45 | 45px | 强调大字(打包拦截提示等) |
- 全站字号已统一 ×0.85(只降文字、不降布局尺寸);**要调字号只改字号值,别动 rem 基数**。
- 浮层里的 `px` 字号(退件页摄像头浮窗 11/12/13px、`scan-diag-panel.vue`)是有意为之,不参与本刻度。
### 4. 间距:5px 网格
- `padding` / `margin` / `gap` 取 **`0.05rem` 的倍数**(5 / 10 / 15 / 20 / 25 / 30 …px)。
- 紧凑标签、角标的**内部微内边距**可取 **`0.02rem` 的倍数**(2 / 4px),不要再出现第三种写法。
- 行高与控件高度不受本网格限制(走第 2 节的 36 / 50 / 70)。
### 5. 圆角:3 档 + 圆
| 档位 | rem | 用途 |
|---|---|---|
| 角标 | `0.03rem` | 小标签、角标 |
| 控件/小卡片 | `0.07rem` | 按钮、输入框、标签、小色块;列表/信息类小卡片(退件 `.rp-card`、订单左栏卡片) |
| 大容器 | `0.13rem` | 页面级面板/弹窗(`.pack-card`、`.popup-card`、`.update-dialog`、`.container`) |
| 圆形 | `50%` | 头像、圆形图标按钮 |
### 6. 边框:1px
- 常规边框统一 `0.01rem`(≥1280 正好 1px)。
- 例外只有两种:图标描边/装饰虚线 `0.02rem`(2px)、左侧强调条/对齐条 `0.05rem`(5px)。
### 7. 颜色:用 token,不写死高频色值
- 颜色/圆角/字号都集中在 `src/styles/base.css` 的 `:root`,页面里写 `var(--wms-*)`:
`--wms-primary`、`--wms-primary-alt`、`--wms-success`、`--wms-warning`、`--wms-danger`、
`--wms-text` / `-strong` / `-secondary` / `-tertiary` / `-muted` / `-placeholder` / `-disabled`、
`--wms-page-bg`、`--wms-card-bg`、`--wms-bg-subtle`、`--wms-bg-tint`、`--wms-border` / `-alt` / `-light` / `-strong`、`--wms-white`。
- **页面底色全站统一 `--wms-page-bg = #e8eaed`,各页不要自己写底色**(登录页、打包页原先各写 `#f2f2f2` / `#e8eaed`,已统一)。
它比 `#f8f8f8` 深一档:与白卡片对比 **1.21 : 1**(`#f8f8f8` 只有 1.06 : 1),这样白色卡片才「立」得起来。
页面级框架背景在 `pages.json` 的 `globalStyle.backgroundColor`,与 token 保持同值。
- 纯白分两种写法:**底色**用 `var(--wms-card-bg)`,**文字/描边**用 `var(--wms-white)`。
- 一次性特殊色(渐变、遮罩、阴影里的 `rgba()`、品牌图标色)可以直接写。
### 8. 布局:% / flex 负责伸展,rem 负责封顶
- **大屏表现**:宽度 ≥1280 后所有 rem 尺寸封顶,只做布局变化——多余空间给主区(`flex: 1; min-width: 0`),**不要给窄侧栏**。
- 窄侧栏统一 `flex: 0 0 3.8rem`(380px),三页(订单左栏 / 打包右栏 / 退件左栏)保持一致。
- **主体到页边的留白全站统一**:`--wms-page-pad` = `0.25rem`(25px),由基准 `.page-main` 的
`padding: 0.05rem var(--wms-page-pad) var(--wms-page-pad)` 提供;顶栏 `margin-bottom: 0.2rem` + 上 0.05 = 25px,**四边视觉留白一致**。
- 页面内层容器**不要再加内间距**,否则和基准叠加(订单 `.container` 已置 0;打包页没有 `.page-main`,`.mode-main` 直接取同一个 token)。
- 顶栏(`top-nav`)与打包页顶栏(`.mode-topbar`)的水平内边距也用 `var(--wms-page-pad)`,保证 logo/内容左右对齐。
- **主体内左右分栏间距统一 `--wms-panel-gap` = `0.15rem`(15px)**:
订单 `.panel-left { margin-right }`、退件 `.rp-left { margin-right }`、打包 `.pack-right { margin-left }`(三页统一用 `margin`,保持一致)。
> 更正(2026-09-26):此前记的“真机 WebView 不支持 flex `gap`,写了会贴在一起”**不成立** —— 用户实测 `gap` 在真机生效(原因见第 13 节)。
> 所以页面里现存的 `gap` **保留即可**,不必再逐处换成 `margin`;新代码用 `gap` 或 `margin` 都行,只是同一处不要两种混用。
- 页面骨架统一用 `.page` / `.page-main`,每页只写差异项。
- **侧栏内容用「灰底 + 白卡片」**:侧栏自己不要铺底色(订单左栏、退件左栏都是透明灰底,与右栏一致);里面的每一块(搜索、列表、底部信息栏)做成独立白卡片,卡片间距 `0.15rem`、卡片内边距 `0.15rem`。
- 滚动方式各页自定:整块滚用 `overflow-y: auto`(订单、称重);面板各自滚用 `overflow: hidden` + 子面板 `auto`(退件)。
### 9. 样式放哪:全局在 base.css,个性化在页面
- 6 个页面都要用的 → `src/styles/base.css`(`App.vue` 的 `<style>` 顶部 `@import` 引入;编译后顺序在所有页面 CSS 之前,页面同权重规则天然覆盖基准)。
- 单页面用、或与基准不同的 → 写在页面 `<style>` 里,只写差异项。
- **不要**把页面骨架类改造成公共类去复用:`.page` / `.page-main` 是跨页共用类名(首页用 `keep-alive` 内嵌其它页),加公共类会把别页的 `padding` / `overflow` 套到自己身上。
- 页面 `<style>` 没有 `lang="scss"`,`uni.scss` 的 scss 变量在页面里不可用 → 基准统一用 **CSS 变量**。
### 10. 提交前自检
```bash
npm run lint:layout # 代码级自检:字号/圆角/间距网格/rem 小数位/颜色 token
```
- [ ] 控件高度是 `0.36rem`(表格/列表行 ≈ `0.5rem`),顶栏 `0.7rem`;按钮没写死宽度,设了高度就设 `line-height`
- [ ] 间距是 `0.05rem` 的倍数(微内边距是 `0.02rem` 的倍数)
- [ ] 字号在 10 档内、圆角在 3 档内、边框 `0.01rem`(例外:图标描边 0.02、强调条 0.05)
- [ ] 颜色用 `var(--wms-*)`,没有写死 `#333` / `#2f7dff` / `#909399` 这类高频色
- [ ] 控件内嵌图标/字形 ≤ `0.22rem`,且点击热区与可见标记分开写(第 12 节)
- [ ] 没新增 flex `gap`;`position: sticky` 带了 `-webkit-` 前缀;没在媒体查询里写 rem(第 13 节)
- [ ] rem 值最多 2 位小数;没有动 `7.8125vw`
- [ ] `npm run build:h5` 通过
> 代码级自检只能盖住可量化的部分(字号/间距/小数位);**尺寸比例、图标大小、真机表现这类“看得见”的问题必须先在 dev 里量尺寸或截图确认**(见第 14 节自查)。
### 11. 本地画图:二维码/条形码一律视图层现画,不走远程出图
- **原因**:远程出图(`.../grcode/build?text=`、`api.qrserver.com` 兜底)在断网、内网隔离、服务不可用时二维码直接出不来,
且真机每次都要联网取图。扫码登录二维码、工作台绑定码已全部改为本地绘制。
- **二维码**:`src/render-common/qr-render.js`(依赖 `qrcode-generator`,devDependency:纯 ES5、零运行时依赖、约 15KB)。
用法固定为「属性传内容 + 视图层画」:
```vue
<view class="scan-image" :data-qr-text="scanQrText"></view>
```
```js
// 页面 renderjs 模块
import { paintQrIn, watchQrIn } from '../../render-common/qr-render.js'
mounted () {
// 视图层副作用(画二维码/条形码、console 转发、视口自愈)直接写在最外层:
// 它们 H5 与真机都要跑,不要包进任何 #ifdef 里
this.paintQrCodes() // 内部:paintQrIn + 80/600/1500ms 兜底 + watchQrIn
// #ifndef APP-PLUS
// 只有 H5/Electron 需要的东西(如 rem 初始化)包在 #ifndef 里,
// ⚠️ 不要用 `#ifdef APP-PLUS + return`(会让 esbuild 报 semicolon-after-return,
// 而且以后补的视图层代码会变成真机永不执行)
// #endif
}
```
- **约定**:`data-qr-text` 存**二维码内容**(不是图片地址);画完打 `data-qr-drawn` 记录已画内容,内容不变不重画
(绑定码轮询每 1.5s 一次,不做这层判断会一直重绘);容器用 `childList` + `attributeFilter` 监听,`v-if` 首次插入也会画。
- **绘制细节**:静区 4 模块(少了真机扫不出)、白底、`shape-rendering: crispEdges`(缩放不抗锯齿)、同色连续模块横向合并成一个 `rect`(节点数约减半)。
- **容器要求**:固定正方形(登录页 `0.36rem` 级控件之外的 `1.47rem` 图),**不要加 `border-radius` / `overflow: hidden` 剪裁**,否则会把码切掉导致扫不出。
- **条形码**同理:退件页 `JsBarcode` → SVG(`data-bc-code`,见该页 renderjs)。
- **验证方式**(改完照着做一遍):① 反推 SVG 矩阵与库矩阵逐格比对(0 差异);② 用独立解码器(如 `jsqr`)回环解码等于原文;③ 真机实扫。
### 12. 控件内嵌元素:图标 / 徽标 / 字形
- **可见标记取控件高度的 55~60%**:36px 控件里放 `0.2rem`~`0.22rem`(20~22px),上下各留 7~8px 白边。
- 输入框清除圆标:`0.22rem` 圆 + `0.01rem` 描边 + `0.15rem` 字形 + `line-height: 0.2rem`(配 `box-sizing: border-box`)
- 密码可见图标 `0.2rem`;下拉箭头 `0.2rem`;搜索框清除字形 `0.18rem`(36px 灰圆本身保留)
- **点击热区与可见标记必须分开写**:热区保持控件尺寸 `0.36rem`(透明、**不加边框**),可见圆标/图标放子元素上。
- 坑:`content-box` 下给 `0.36rem` 的盒子再加 `0.01rem` 边框,实际占位 38px,会比 36px 输入框高出 2px 溢出上下边(登录页清除圆标原来就是这样)。
- 圆形一律 `border-radius: 50%`;描边用 `0.01rem`(`0.02rem` 是装饰虚线档)。
- 图标统一用内联 `<svg>`(`viewBox` + `width/height: 100%`),尺寸由外层盒子控制,不要在 `svg` 上写死 px。
- 反例(2026-09-25 已全改):圆标和输入框同高、眼睛图标 `0.3rem` 顶满输入框、下拉箭头 `0.3rem`、搜索清除字形 `0.25rem`。
- 非控件图形(商品图 59px、头像 42.6px、缩略图 36px、表格行 50px+)按内容尺寸走,不套本节的 55~60%。
### 13. 真机平台注意(WebView 由 Chrome 应用提供)
> **更正(2026-09-26)**:此前记录的“真机 WebView = Chromium 52、不支持 flex `gap`”**已被实测推翻** —— 用户确认 `gap` 在真机生效。
> 原因:真机的 WebView 提供者是 **Chrome 应用**(`adb shell settings get global webview_provider` = `com.android.chrome`),
> 不是随固件的系统 `com.android.webview`;版本跟设备上装的 Chrome 走,**不能用“Android 7.1.2 ⇒ Chromium 52”推断能力边界**。
> 复核版本:`adb shell dumpsys webviewupdate`(顺手 `adb shell dumpsys package com.android.chrome | findstr versionName`)。
> ⚠️ 该固件 WebView 实现就是 Chrome,**不能卸载 Chrome/系统 webview**(卸了页面直接白屏)。
> 教训:**能力边界要实测或查版本,不要从系统版本号推**。
**与 WebView 版本无关的硬约束(务必遵守)**
| 约束 | 说明 | 对策 |
|---|---|---|
| 媒体查询里的 `rem` 按初始 16px 解析 | CSS 规范行为,任何版本都一样:写 `20.48rem` 实际是 327px,永不触发 | 断点用真实 px(第 1 节) |
| 新页面早期视口可能是 0×0 | 此时 `vw/vh` 全为 0 → rem 归零 → 白屏(真机实测过) | `viewport-fix.js` 已自愈,见下文「真机坑」 |
| `html { font-size: 7.8125vw }` 不能取整 | 取整会让 1rem 不是整 100px | 保持原值 |
| `content-box` 下加边框会撑大尺寸 | 给 0.36rem 盒子加 0.01rem 边框实际占 38px | 写 `box-sizing: border-box`(第 12 节) |
**新 API / 新语法:先确认再用(不要照抄旧结论)**
- 历史上为“老 WebView”规避过:flex `gap`、`replaceChildren`、`Element.append/prepend/before/after`、CSS `min()/max()/clamp()`、CSS Grid、无前缀 `position: sticky`。
其中 **`gap` 已实测可用**;其余**没有实测过是否必需**,属于保守写法:
- 视图层 renderjs 保持 ES5 写法(少一层降级不确定性);
- `position: sticky` 同时写 `-webkit-sticky`(老 WebView 只认前缀;新 Chrome 前缀仍有效、无副作用);
- 换 DOM 节点用 `appendChild` / `removeChild` 就够,没必要引入新 API。
- **要用新的 CSS/JS 特性前,先用上面的命令查真机版本或在真机上实测**,别拿本文件的历史结论当限制。
### 14. 页面规范:结构 / 骨架 / 公共类 / 新增页面自查
**页面文件结构(每个 `.vue`)**
- **只能有 2 个 `<script>` 块**:主逻辑 + `<script module="remInject" lang="renderjs">`;多一个 dev 就报
`Single file component can contain only one <script> element`(遮罩 + 页面卡住)。
- `<style>` 不带 `lang="scss"`(`uni.scss` 的变量在页面里不可用)。
- renderjs 的 `mounted()` **不要用 `#ifdef APP-PLUS … return … #endif` 的写法**(2026-09-26 统一改掉):
- 真机 rem 交给 `App.vue` 的 CSS,所以 rem 初始化包在 **`// #ifndef APP-PLUS`** 里(H5/Electron 照常执行,真机整块被抖掉);
- 视图层副作用(画二维码/条形码、`installZeroViewportFix()`、`installConsoleForward()`)H5 与真机都要跑,**直接写在最外层**,不要包进任何 `#ifdef`;
- 旧写法(`#ifdef APP-PLUS` + `return` + 后续代码)会让 esbuild 报 `[semicolon-after-return]`(真机死代码),而且后续新增的视图层代码会变成真机永不执行 —— 6 个页面已全部改为 `#ifndef` 包裹。
- 双 script 页面改 CSS,dev 下 HMR 会失败 → **必须刷新页面**才看到效果(`npm run build:h5` 不受影响)。
**页面骨架(每页只写差异项)**
| 项 | 基准来源 | 页面要不要写 |
|---|---|---|
| 页面底色 | `.page` → `--wms-page-bg` | 不写(要例外时写 token,不要写死色值) |
| 主体留白 25px | `.page-main` → `--wms-page-pad` | 不写;内层容器不要再加内边距 |
| 左右分栏间距 15px | `--wms-panel-gap`(**用 margin**) | 侧栏自己写 `margin-right` / `margin-left` |
| 顶栏 70px | `.top-nav` / `.mode-topbar`:`0.7rem` + 水平 `var(--wms-page-pad)` | 顶栏内 logo `1.33rem × 0.5rem` |
| 滚动方式 | 无基准 | 自己写:整块滚 `overflow-y: auto`;面板各自滚 `overflow: hidden` + 子面板 `auto` |
- **卡片三级**:页面级容器(`.container` / `.pack-card` / `.popup-card`)`0.13rem` 圆角;信息卡片(`.rp-card`、订单左栏卡片)`0.07rem`;**卡片内边距与卡片间距都 `0.15rem`**。
- **列表/表格**:行高 `0.5rem` 档(订单表格 `0.52`/`0.56rem` 以内容为准);表头要吸顶按第 13 节写前缀 `sticky`。
- **空状态**统一 `.empty-panel`(`0.07rem` 圆角),左栏用 `.empty-panel--left`(`margin-top: 0`)。
- **接入首页菜单**:在 `src/router/menuRoutes.js` 的 `menuRouteMap` 里同时注册短路径(`/order`)与完整路径(`/pages/order/index`),否则 URL 跳转解析不到页面。
**公共类清单(都在 `src/styles/base.css`,新增同类需求先看这里)**
- 骨架:`.page` / `.page-main`
- 工具类:`.scan-hidden-input`(隐藏的扫码输入框,四页共用;打包页只覆盖 `top: 0`)
- 按钮去默认边框的 `::after`:目前 12 个类集中写在 base.css 的选择器列表里,
**新增自定义 `uni-button` 按钮必须把类名补进这个列表**,否则会带上框架默认的 `1px solid rgba(0,0,0,.2)` 边框。
**新增/修改页面的自查(§10 只能盖住可量化部分)**
- [ ] dev 里真看过:用 `getBoundingClientRect()` 量过关键尺寸,或截图对比过
- [ ] 没有新增 flex `gap`;`sticky` 带了 `-webkit-` 前缀;图标符合第 12 节比例
- [ ] 从别的页面复制来的样式,把不属于本页的差异项删掉(内边距、`overflow`、残留 `@media`)
- [ ] 窄屏(H5 缩到 <1280 宽)与真机各看一遍布局没被压坏
## 真机调试热更新(dev:adb)
`npm run dev:adb` 一条命令完成真机调试闭环:
@ -22,7 +260,7 @@ console 转发原理(release 包 console 默认不进 logcat):
## ⚠️ 真机坑:登录页 reLaunch 到打包模式白屏(切后台回前台才恢复)
### 现象
- 真机(RK3288 工控机 / Android 7.1.2,系统 WebView = Chromium 52)上,从登录页 `uni.reLaunch` 到打包模式页(`/pages/packaging/index`)后**整个页面白屏**;
- 真机(RK3288 工控机 / Android 7.1.2,WebView 由 Chrome 应用提供)上,从登录页 `uni.reLaunch` 到打包模式页(`/pages/packaging/index`)后**整个页面白屏**;
- 按 Home 退后台再切回前台,页面恢复正常显示;
- 服务层逻辑正常执行(页面 onLoad/onShow/mounted 都跑了,toast/语音也正常),只有渲染层白屏。