真机 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
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),flexgap要 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. 提交前自检
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)。 用法固定为「属性传内容 + 视图层画」:<view class="scan-image" :data-qr-text="scanQrText"></view>// 页面 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.2rem22px),上下各留 7~8px 白边。0.22rem(20- 输入框清除圆标:
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), 所以 flexgap(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、CSSmin()/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包裹。
- 真机 rem 交给
- 双 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 一条命令完成真机调试闭环:
- 自动列出所有 ADB 设备(多台时交互选择,单台自动选中)
- 进程常驻,监听
src/与原生工程源码(simpleDemo/src/main/java、AndroidManifest.xml) - 保存文件后自动:
build:app→ 离线打包(gradle 增量) →adb install -r→ 启动应用(约 20 秒/轮) - 真机 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 tagUniConsole - 视图层:
src/render-common/viewport-fix.js的installConsoleForward(),各页 renderjs 调用,tagUniViewConsole
注意:不要 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 重排自愈; - 新页面接入示例:
// 页面 .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>
后续开发注意
- 不要在页面 renderjs 的 APP 端覆盖
htmlfontSize(真机 rem 统一由App.vue全局纯 CSS 承担,renderjs 覆盖会导致字号/布局异常); - 不要在新页面 WebView 创建早期(onLoad)调用
plus.screen.lockOrientation/plus.webview.currentWebview().setStyle等 native 操作——实测无效且会触发AdaUniWebView的ViewOptions.updateViewDataNPE。横屏由manifest.json的全局screenOrientation配置承担,打包页的 lockLandscape 已因此移除; - 若新增页面在真机出现同样白屏,按上面的示例接入
installZeroViewportFix即可; - 排查白屏类问题先看视口尺寸(renderjs 里打 Log),而不是猜字体/样式——0×0 视口下 CSS 的 vw/vh 全部失效是这类白屏的典型特征。
订单复核页(布局壳)与退出登录白屏(2026-10-25 补充)
同一套 reLaunch 视口问题,还波及两个场景:
-
登录 → 布局壳 → 订单复核页白屏(偶发):订单复核页是布局壳
pages/index里:embedded="true"的动态组件,没有独立的 onLoad/onShow 生命周期,完全依赖布局壳的 lockLandscape。布局壳(pages/index)与订单页(pages/order)的 lockLandscape 只保留plus.screen.lockOrientation('landscape')横屏兜底,禁止调用webview.setStyle——setStyle 在 WebView 未就绪时触发ViewOptions.updateViewDataNPE → 白屏(与上文第 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):
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 + 环形缓存),只有异常才上报服务端(主线程卡顿、真自愈、活动突然中断),正常扫码不再产生上行记录。
五、排查口诀
- 先看诊断面板的
按键到达:keys=0→ 按键根本没到 JS,转第 2 步;有keys但业务没生效 → 看丢弃统计的 reason(属 JS 门控,按 reason 定位)。 keys=0时执行上面那条dmesg | grep -E 'USB disconnect|error -71':有输出 → 供电 / USB 口外接耗电外设(见本节一、二);无输出 → 枪 / 线材 / 系统扫码服务。- 长跑中「突然扫不上、重启才好」几乎都是第 2 步命中的供电类问题:先换电源、拔掉 USB 音响,再复核。