真机 WebView 实测为 com.android.webview 52.0.2743.100(Chromium 52),
flex gap 需 Chrome 84+,因此全站 gap 在真机上一律不生效。
退件页 src/pages/returns/index.vue
- 24 处 gap 全部改用 margin(相邻兄弟 / 子项外距):
左栏卡片 0.15rem、右栏卡片 0.15rem、扫码指令行 0.1rem、
正常/破损 0.1rem、提交/删除/清除 0.1rem、字段标签 0.04rem,
以及明细、对照汇总、备注弹窗、分页等同类间距
- 选择器写成 .容器 > .rp-btn + .rp-btn(0,2,0):.rp-btn 自带 margin:0,
同权重的 > * + * 会被覆盖,间距失效
- 顺带修「扫码指令被压扁 / 与工作台卡片贴住」:
.rp-left > .rp-card { flex-shrink: 0 }(高度不足改为左栏滚动)
.rp-cmd-bc { flex: 0 0 0.36rem }(原 min-height:0 会把条码区压成 0)
订单复核页 src/pages/order/index.vue
- 复核设置分段按钮去掉 gap 改子项 margin-right,补 height/line-height 0.4rem 防真机裁字头
- 工具栏按钮颜色变体改硬编码色值 + 0.02rem 完整 border,并加 !important
压过 uni-button 内置样式(真机曾出现「橙底白字」变「白底黑字」)
README
- 作废 2026-09-26「gap 真机生效」的结论,改回「Chromium 52 不支持 flex gap,间距一律用 margin」
- 新增「按钮颜色被 uni-button 内置样式覆盖」踩坑说明与 !important 对策
验证:adb 截图 + 像素采样(gap:0.15rem 的两卡片之间实测空隙为 0);npm run build:app 通过
EOF
381 lines
30 KiB
Markdown
381 lines
30 KiB
Markdown
# 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-10-27)**:2026-09-26 记的“`gap` 在真机生效”**是错的**。真机 `webview_provider` = `com.android.webview`,
|
||
> `versionName = 52.0.2743.100`(Chromium 52),flex `gap` 要 Chrome 84+ 才有 → **真机上 `gap` 完全失效**
|
||
> (退件页曾用 `gap: 0.15rem` 分隔两张卡片,像素级采样量到空隙为 **0**)。
|
||
> 结论:**间距一律用 `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-10-27)**:2026-09-26 那条“`gap` 在真机生效 / WebView 由 Chrome 应用提供”的结论**已作废**。
|
||
> 实测 `adb shell settings get global webview_provider` = `com.android.webview`,
|
||
> `adb shell dumpsys package com.android.webview | findstr versionName` = **52.0.2743.100(Chromium 52)**,
|
||
> 所以 **flex `gap`(Chrome 84+)不支持**:退件页 `gap: 0.15rem` 的两张卡片,按列采样像素量到的空隙是 0。
|
||
> 验证手法:`adb exec-out screencap -p > shot.png` 后用 `build/measure.ps1`(按列/行采样像素)量真实间距,比肉眼看截图可靠。
|
||
|
||
**与 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` 已实测不可用**(Chromium 52),间距必须用 `margin`;其余**没有实测过是否必需**,属于保守写法:
|
||
- 视图层 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)` 边框。
|
||
- **按钮颜色被框架内置样式覆盖(2026-10-27 踩坑)**:真机 APP-PLUS 的 `<button>` 渲染成 `<uni-button>` 自定义元素,
|
||
框架内置 `uni-button[disabled]:not([type]){background:#f7f7f7}`(特异性 (0,3,1))等规则**优先级高于自定义类**(`.tool-btn--orange` 只有 (0,1,0)),
|
||
会把按钮颜色覆盖成「灰白底黑字」(典型:面单补打应是橙底白字,真机却白底黑字)。
|
||
**给自定义按钮颜色变体的 `background-color` / `border` / `color` 加 `!important` 才能压过内置样式**;
|
||
禁用态同理(`.tool-btn[disabled]` 也要 `!important`,否则被 `uni-button[disabled]:not([type])` 抢走)。排查「web 正常、真机按钮颜色不对」时优先怀疑 uni-button 内置样式,而不是 CSS 变量/颜色值本身。
|
||
|
||
**新增/修改页面的自查(§10 只能盖住可量化部分)**
|
||
|
||
- [ ] dev 里真看过:用 `getBoundingClientRect()` 量过关键尺寸,或截图对比过
|
||
- [ ] 没有新增 flex `gap`;`sticky` 带了 `-webkit-` 前缀;图标符合第 12 节比例
|
||
- [ ] 从别的页面复制来的样式,把不属于本页的差异项删掉(内边距、`overflow`、残留 `@media`)
|
||
- [ ] 窄屏(H5 缩到 <1280 宽)与真机各看一遍布局没被压坏
|
||
|
||
## 真机调试热更新(dev:adb)
|
||
|
||
`npm run dev:adb` 一条命令完成真机调试闭环:
|
||
|
||
1. 自动列出所有 ADB 设备(多台时交互选择,单台自动选中)
|
||
2. 进程常驻,监听 `src/` 与原生工程源码(`simpleDemo/src/main/java`、`AndroidManifest.xml`)
|
||
3. 保存文件后自动:`build:app` → 离线打包(gradle 增量) → `adb install -r` → 启动应用(约 20 秒/轮)
|
||
4. **真机 console 实时打印到终端**(含视图层 renderjs)
|
||
|
||
可选参数:
|
||
- `npm run dev:adb -- --no-launch`:重装后不自动启动应用
|
||
- `npm run dev:adb -- --adb=D:\path\to\adb.exe`:自定义 adb 路径(默认自动探测 SDK)
|
||
|
||
console 转发原理(release 包 console 默认不进 logcat):
|
||
- 逻辑层:`src/main.js` 接管 `console.*` 与 uni-app 内部日志 `uni.__log__`(编译后的 console.log 走它),转发到 logcat tag `UniConsole`
|
||
- 视图层:`src/render-common/viewport-fix.js` 的 `installConsoleForward()`,各页 renderjs 调用,tag `UniViewConsole`
|
||
|
||
注意:不要 watch `simpleDemo/src/main/assets` 与 `res`(构建注入产物),否则构建自触发死循环(已在脚本中排除)。
|
||
|
||
## ⚠️ 真机坑:登录页 reLaunch 到打包模式白屏(切后台回前台才恢复)
|
||
|
||
### 现象
|
||
- 真机(RK3288 工控机 / Android 7.1.2,WebView 由 Chrome 应用提供)上,从登录页 `uni.reLaunch` 到打包模式页(`/pages/packaging/index`)后**整个页面白屏**;
|
||
- 按 Home 退后台再切回前台,页面恢复正常显示;
|
||
- 服务层逻辑正常执行(页面 onLoad/onShow/mounted 都跑了,toast/语音也正常),只有渲染层白屏。
|
||
|
||
### 根因
|
||
- reLaunch 创建的新页面 WebView 初始**视口为 0×0**(`window.innerWidth/innerHeight` 都是 0,`document.body` 尺寸 0×0);
|
||
- 全局 CSS 的 `html { font-size: min(5.2734375vw, 7.91015625vh) }` 依赖视口,视口为 0 时 fontSize 计算为 **0px**;
|
||
- 本项目全站用 rem 布局,fontSize=0 → 所有 rem 尺寸归零 → 白屏;
|
||
- 切后台回前台时 Activity resume 触发原生重排,视口恢复(961×640 CSS 像素,dpr=2 对应物理 1920×1280),页面随即正常。
|
||
|
||
### 诊断方法(重要,后续排查类似问题照此做)
|
||
- **renderjs 的 `console.log` 在 release 包里拿不到**(不会输出到 logcat);
|
||
- 必须用原生日志:`plus.android.importClass('android.util.Log').i('TAG', msg)`,然后 `adb logcat | grep TAG`;
|
||
- 轮询观察视口:`setInterval` 里打印 `window.innerWidth + 'x' + window.innerHeight` 与 `document.documentElement.style.fontSize / getComputedStyle(...).fontSize`。
|
||
|
||
### 修复(已落地,公共逻辑抽离到 `src/render-common/viewport-fix.js`)
|
||
- 在页面 renderjs 的 `mounted` 里 `import { installZeroViewportFix } from '../../render-common/viewport-fix.js'` 并调用一次,检测视口 0×0 时强制原生 Activity 重排自愈;
|
||
- 新页面接入示例:
|
||
|
||
```js
|
||
// 页面 .vue 内的 renderjs 模块
|
||
<script module="remInject" lang="renderjs">
|
||
import { installZeroViewportFix } from '../../render-common/viewport-fix.js'
|
||
|
||
export default {
|
||
mounted() {
|
||
// #ifdef APP-PLUS
|
||
installZeroViewportFix() // 视口自愈(0×0 → requestLayout+invalidate)
|
||
return // 注意:APP 端 renderjs 不覆盖 fontSize,rem 由 App.vue 全局 CSS 承担
|
||
// #endif
|
||
// H5 端 rem 逻辑...
|
||
},
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 后续开发注意
|
||
1. **不要**在页面 renderjs 的 APP 端覆盖 `html` fontSize(真机 rem 统一由 `App.vue` 全局纯 CSS 承担,renderjs 覆盖会导致字号/布局异常);
|
||
2. **不要**在新页面 WebView 创建早期(onLoad)调用 `plus.screen.lockOrientation` / `plus.webview.currentWebview().setStyle` 等 native 操作——实测无效且会触发 `AdaUniWebView` 的 `ViewOptions.updateViewData` NPE。横屏由 `manifest.json` 的全局 `screenOrientation` 配置承担,打包页的 lockLandscape 已因此移除;
|
||
3. 若新增页面在真机出现同样白屏,按上面的示例接入 `installZeroViewportFix` 即可;
|
||
4. 排查白屏类问题先看**视口尺寸**(renderjs 里打 Log),而不是猜字体/样式——0×0 视口下 CSS 的 vw/vh 全部失效是这类白屏的典型特征。
|
||
|
||
### 订单复核页(布局壳)与退出登录白屏(2026-10-25 补充)
|
||
|
||
同一套 reLaunch 视口问题,还波及两个场景:
|
||
|
||
1. **登录 → 布局壳 → 订单复核页白屏(偶发)**:订单复核页是布局壳 `pages/index` 里 `:embedded="true"` 的动态组件,没有独立的 onLoad/onShow 生命周期,完全依赖布局壳的 lockLandscape。布局壳(`pages/index`)与订单页(`pages/order`)的 lockLandscape **只保留 `plus.screen.lockOrientation('landscape')` 横屏兜底,禁止调用 `webview.setStyle`**——setStyle 在 WebView 未就绪时触发 `ViewOptions.updateViewData` NPE → 白屏(与上文第 2 条同源)。
|
||
|
||
2. **退出登录必须用 `plus.runtime.restart()`,禁止 reLaunch**:`top-nav.finishLogout` 若用 reLaunch 回登录页,退出后再登录 reLaunch 到布局壳会白屏;restart 重启进程恢复干净渲染才可靠(代价是闪一下启动图,`manifest.splashscreen.waiting=true` 让启动图持续到登录页渲染完成)。配套:登录页 `onShow` 读取 storage 的 `__logout_msg__` 回显「已退出登录」。
|
||
|
||
⚠️ 上述修复曾被 HBuilderX / 外部编辑器**整体回退**(finishLogout 改回 reLaunch、`__logout_msg__` 逻辑丢失、页面 lockLandscape 重新加了 setStyle)。改动后务必 grep 确认:`plus.runtime.restart`、`__logout_msg__` 仍在,且各页 lockLandscape 内**没有** `setStyle`。
|
||
|
||
## ⚠️ 机型注意:X9R 工控机的供电 / USB 口 / 固件差异(2026-09-25 实测)
|
||
|
||
> 结论先说:这台机器的「扫码突然没反应」**多数不是软件问题**,而是供电不足或 USB 口上挂了耗电外设。
|
||
> 装机、巡检、换电源前请先读本节。实测机型:X9R(RK3288 / Android 7.1.2 / 内核 4.4.112)。
|
||
|
||
### 一、电源:必须 ≥12V/2.5A(推荐 3A)
|
||
|
||
| 电源 | 满载实测(屏幕最亮 + 4 核满载 60s) | 结果 |
|
||
|---|---|---|
|
||
| 12V/**2.5A** | USB 掉线 0 次,扫码枪全程在线(120/120) | ✅ 可用 |
|
||
| 12V/**2.0A**(24W) | dmesg 出现 **2 次 `usb 2-1: USB disconnect`**(内部 USB Hub 与扫码枪一起掉)、`device not accepting address, error -71`、4 次总线复位;采样中枪离线 13/120(约 6.5s) | ❌ 临界,不可用 |
|
||
|
||
24W 是**临界值**:屏背光最亮 + WiFi + 内部 USB Hub + 扫码枪 + 喇叭峰值很容易越过它。
|
||
|
||
### 二、⛔ 绝对不要从平板 USB 口给外设(音响)供电
|
||
|
||
**现象**:插上 USB 音响后「扫着扫着就扫不上」,重启设备才恢复;**12V/2.5A 电源现场同样复现**。
|
||
|
||
**根因**:音响与内部 USB Hub、扫码枪共用同一条 5V 支路(USB 口规范每口仅 0.5A,音响常远超)→ 一放音(尤其每次扫码后的**语音播报峰值**)Hub 就过流跳闸 → 先掉 Hub(`usb 2-1`)再掉枪(`usb 2-1.4`)→ 应用侧表现就是 **`keys=0`(一个按键都收不到)**。
|
||
|
||
**现场判据(不用拆机、不用 root)**:
|
||
|
||
```bash
|
||
adb shell "dmesg | grep -E 'USB disconnect|error -71' | tail -20"
|
||
```
|
||
|
||
- 同时出现 `usb 2-1:`(Hub)与 `usb 2-1.x`(枪)→ **USB 口上挂了耗电外设 / 供电不足**;
|
||
- 只有 `usb 2-1.4`(枪)单独掉 → 更可能是枪的线材/接头。
|
||
|
||
**正确接法**:① 音响自带电源适配器;② 用**带独立供电的 USB Hub**(Hub 自己给音响供电,平板只出信号);③ 蓝牙/自带电池音箱;④ 若必须吃 12V,从 12V 母线单独引一路,不要走平板 USB 口。
|
||
|
||
### 三、其他机型相关注意
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| **adb 认不到设备** | 同一台机器**换个 USB 口可能就认**:实测某个口 Windows 会把 `USB\VID_2207&PID_0006` 绑成通用 WinUSB 驱动,`adb devices` 全空;换口后立刻正常。**先换口/换线,别急着装驱动** |
|
||
| **不要卸载 Chrome** | 该固件 WebView 实现就是 Chrome(`adb shell settings get global webview_provider` = `com.android.chrome`),卸了打包页直接白屏;`com.android.webview` 同样必须保留 |
|
||
| **开机自启的前提** | 自启靠原生 `BootReceiver`(`BOOT_COMPLETED` / `QUICKBOOT_POWERON`)。**新装机或被 `force-stop` 后必须手动启动一次**(Android 3.1+ 规则);检查:`adb shell dumpsys package com.gztbyc.sandan \| grep 'User 0'` 需为 `stopped=false notLaunched=false` |
|
||
| **扫码枪身份** | USB HID 键盘(`Newtologic DW-8200`,VID_060E:PID_0960),挂在 `usb-1.4` → `/dev/input/event4`,供后续排查对照 |
|
||
| **散热** | 4 核满载实测 75℃(室温环境、无散热片);7×24 使用建议加散热片/小风扇,否则会热降频 |
|
||
| **网络** | 建议走网线(`eth0` 存在但默认无链路,先确认机器有没有 RJ45 口);WiFi 是 Broadcom SDIO,做常驻服务不稳 |
|
||
| **有线网重启后变回静态 IP** | 出厂默认就是 `STATIC 10.10.1.100/24`。本 ROM 的以太网服务把配置存在 **`/system/etc/ipconfig.txt`**(不是常见的 `/data/misc/ethernet/`),该文件在只读 `/system` 上,**在安卓设置里改成 DHCP 不会保存**,重启照旧读回静态。改法:`powershell -ExecutionPolicy Bypass -File scripts\set-eth-dhcp.ps1`(自动备份原文件、写入 DHCP 记录、重启并核对),恢复出场值用 `-Restore` |
|
||
|
||
### 四、现场排查工具
|
||
|
||
| 工具 | 用途 |
|
||
|---|---|
|
||
| 诊断面板 | 打包页标题**3 秒内连点 5 次**(退件页为「拆包工作台」同操作):实时看按键到达 / 丢弃原因 / 门控快照 / 自愈次数,可复制与一键上报 |
|
||
| `scripts/scan-forensics.ps1` | 故障**当场**一键取证:内核按键流 + dmesg + App 心跳 + 自动判据(内核有事件而 App `keys=0` → 上层;内核无事件 → 枪/线/供电) |
|
||
| `scripts/power-probe.sh`、`scripts/power-load-test.sh` | 电源/负载对比实测(采样 ADC、温度、CPU 频率、扫码枪是否仍在总线) |
|
||
| `scripts/set-eth-dhcp.ps1` | 把有线网默认改成 DHCP(重写 `/system/etc/ipconfig.txt` 后重启),带 `-Restore` 回滚;开机后网口要约 20s 才 Link Up,属正常 |
|
||
| logcat | `adb logcat -s WMSScan`(扫码链路)、`WMSPage`(页面生命周期)、`UniConsole` / `UniViewConsole`(JS 日志) |
|
||
|
||
> 日志上行已做降噪(2026-09-25):本地明细全部保留(面板 + logcat + 环形缓存),**只有异常才上报服务端**(主线程卡顿、真自愈、活动突然中断),正常扫码不再产生上行记录。
|
||
|
||
### 五、排查口诀
|
||
|
||
1. 先看诊断面板的 `按键到达`:**`keys=0` → 按键根本没到 JS**,转第 2 步;有 `keys` 但业务没生效 → 看 `丢弃统计` 的 reason(属 JS 门控,按 reason 定位)。
|
||
2. `keys=0` 时执行上面那条 `dmesg | grep -E 'USB disconnect|error -71'`:**有输出 → 供电 / USB 口外接耗电外设**(见本节一、二);无输出 → 枪 / 线材 / 系统扫码服务。
|
||
3. 长跑中「突然扫不上、重启才好」几乎都是第 2 步命中的供电类问题:先换电源、拔掉 USB 音响,再复核。
|