aurora-admin
f1fbfc2ddb
Regression / regression (push) Canceled after 0s
## 品牌标识（本次会话） 起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」， 那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」， 移动端站已是「K」；移动端文档站则完全没有 favicon）。 - 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边； 描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」 - 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）； 顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)） - 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg） - 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留） - 移动端 7 个模板补 favicon（此前计数 0） 验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/ theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致； 两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。 ## 并行会话成果（本次一并入库） - 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具 + IconPreview 预览页 + ICON-SPEC.md 冻结规格 - 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁 - PC 组件：103 个大后台组件 / 组件11 批次 - uni-app：PC 端试点 + 移动端端实现 + 真实编译验证 ## 工程 - .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库） - CHANGELOG 补品牌标识条目 - ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）
106 lines
8.0 KiB
HTML
106 lines
8.0 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
__THEME_BOOT__
|
||
__BRAND_HEAD__
|
||
<title>常见问题 — Kole UI Mobile</title>
|
||
<meta name="description" content="Kole UI 移动端常见问题：与 PC 端的关系、令牌引入、单位与安全区、手势事件、uni-app 端限制、多实例同一页的定位、版本与回归口径。">
|
||
<link rel="stylesheet" href="../../.design_library/kole-ui-mobile/colors_and_type.css">
|
||
<link rel="stylesheet" href="style.css">
|
||
</head>
|
||
<body>
|
||
__HEADER__
|
||
<div class="m-body">
|
||
__SIDEBAR__
|
||
<main class="m-main">
|
||
<section class="m-hero">
|
||
<h1>常见问题</h1>
|
||
<p>按「接入 → 令牌 → 触控 → uni-app → 排障 → 口径」六组整理。每条都对应仓库里可复现的实测或门禁断言，不是凭印象写的经验。</p>
|
||
</section>
|
||
|
||
<section class="m-block">
|
||
<h2 id="start">接入</h2>
|
||
<table class="m-table">
|
||
<thead><tr><th>问题</th><th>回答</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>组件渲染出来了，但没有样式</td><td>没引令牌或组件样式。最小集合是 <code>kole-ui/mobile/tokens.css</code> + <code>kole-ui/mobile/components/index.css</code>（按需则引单个组件 CSS）。</td></tr>
|
||
<tr><td>能直接拷走一个文件用吗</td><td>能。<code>frameworks-mobile/<Prefix>.html</code> 是零依赖演示页（样式内联 + 原生脚本），拷进工程即可跑；<code>.css</code> 是独立的样式表。</td></tr>
|
||
<tr><td>为什么没有 PC 的那些组件</td><td>移动端与 PC 是两套清单、物理隔离（见 <a href="platform.html">平台与端</a>）。移动端只做触屏优先的组件，B 端中后台的那 __PC_N__ 个在 <a href="../index.html">PC 文档站</a>。</td></tr>
|
||
<tr><td>类名为什么带 <code>-m-</code></td><td><code>kole-m-</code> 是移动端命名空间（PC 是 <code>kole-</code>）。两端样式表各引各的，交叉引用会拿到未定义的样式（门禁 <code>verify:isolation</code> 会拦这类混用）。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="m-block">
|
||
<h2 id="tokens">令牌</h2>
|
||
<table class="m-table">
|
||
<thead><tr><th>问题</th><th>回答</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>--kole-m-*</code> 取不到值</td><td>令牌层没加载。它在 PC 令牌文件之上加了一层，<b>不要</b>只引 PC 的 <code>colors_and_type.css</code>；引移动端的 <code>tokens.css</code>（已 @import PC 令牌）或直接引移动端令牌层。</td></tr>
|
||
<tr><td>改了颜色，移动端为什么跟着变</td><td>这是设计如此：颜色 / 字体 / 圆角 / 阴影令牌两端同源，移动端只加 <code>--kole-m-*</code>（触控尺寸、安全区、字号、动效）。改 PC 令牌文件，两端同时生效。</td></tr>
|
||
<tr><td>暗色模式要单独写一套样式吗</td><td>不用。给根元素加 <code>html.kole-dark</code> 即可（令牌文件里已写好该组）；本站在顶栏「主题模式」里切换，约定与 PC 完全一致 —— 三态存 <code>localStorage['kole-mode']</code>，<code>auto</code> 跟随系统。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="m-block">
|
||
<h2 id="touch">触控</h2>
|
||
<table class="m-table">
|
||
<thead><tr><th>问题</th><th>回答</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>安全区没生效（刘海 / 底部横条）</td><td>页面需要 <code>viewport-fit=cover</code>（演示页都带）。令牌层用 <code>@supports (padding-top: env(safe-area-inset-top))</code> 探测后再取 <code>env()</code>，不支持时为 <code>0px</code>。</td></tr>
|
||
<tr><td>滑动 / 下拉在真机上不触发</td><td>浏览器端组件用 Pointer Events；uni-app 端用 touch 事件。若你的容器截了事件（如自带手势库），需要放行；另外纵向位移更大时组件会主动让位给页面滚动。</td></tr>
|
||
<tr><td>同一页多个 <code>position: fixed</code> 组件叠在一起</td><td>这是浏览器行为（都相对视口定位）。做演示或预览时给容器加 <code>transform: translateZ(0)</code> 建立包含块，组件 CSS 不必改 —— 本站的 TabBar / ActionSheet 演示就是这么做。</td></tr>
|
||
<tr><td>点击热区多大才合规</td><td>44×44（WCAG 2.5.5 / Apple HIG），令牌是 <code>--kole-m-touch-target: 44px</code>；uni-app 端为 <code>88rpx</code>（750rpx = 视口宽度）。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="m-block">
|
||
<h2 id="uniapp">uni-app</h2>
|
||
<table class="m-table">
|
||
<thead><tr><th>问题</th><th>回答</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>为什么 uni-app 端没有 <code>document</code> / PointerEvent</td><td>小程序与 App 端没有 DOM，也没有 PointerEvent。所以该端只用 uni 基础组件（<code>view</code> / <code>text</code>）+ <code>@touch*</code> 事件；<code>verify:uniapp</code> 会静态拦住 DOM API 与 pointer 事件。</td></tr>
|
||
<tr><td>uni-app 端为什么用 <code>rpx</code></td><td><code>rpx</code> 是移动端语义（750rpx = 视口宽度），该端在组件内用同名令牌覆盖成 rpx 值；PC × uni-app 端反过来保持 <code>px</code>。</td></tr>
|
||
<tr><td>uni-app 端真的编译过吗</td><td><b>没有</b>。本仓库只做静态门禁（9 条：SFC 结构 / <code>node --check</code> 语法 / 禁 DOM / 手势必须 touch / 前缀隔离 / 单位策略），真实编译需要 <code>@dcloudio</code> 依赖，复现命令在 <code>tools/verify-uniapp.mjs</code> 头部（ROADMAP S7-P25）。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="m-block">
|
||
<h2 id="debug">排障</h2>
|
||
<table class="m-table">
|
||
<thead><tr><th>现象</th><th>怎么办</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>改了索引但页面没变</td><td>本站是生成物：跑 <code>npm run build:mobile</code> 重建（CI 里有 <code>git diff --quiet -- site/m tests/mobile</code> 断言，防止「改了索引忘了重建」）。</td></tr>
|
||
<tr><td>本地打开是 403 / 404</td><td>dev-server 白名单没有该顶层目录（要加 <code>PUBLIC_ROOTS</code> 与 <code>isPublicPath()</code> 两处）；或 3311 上还挂着改动前启动的实例 —— 现在会自动回退端口并打印实际入口。</td></tr>
|
||
<tr><td>演示帧里样式全丢</td><td>相对路径层数不对（深层页要用三级 <code>../../../</code> 回到仓库根）。这是实测踩过的坑，已由 <code>verify:mobile-site</code>（浏览器实测）卡住。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="m-block">
|
||
<h2 id="scope">口径</h2>
|
||
<table class="m-table">
|
||
<thead><tr><th>问题</th><th>回答</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>版本号以什么为准</td><td><code>package.json</code> 的 <code>version</code>，构建时写进 <code>site/m/data.mobile.json</code> 的 <code>meta.version</code>（顶栏角标读它）。</td></tr>
|
||
<tr><td>回归口径</td><td>移动端断言跑在真实 375×640 设备帧里（引擎与 PC 共用 <code>tests/_runtime.js</code>，触控动词在 <code>tests/mobile/_behaviors.js</code>）；报告 <code>tests/mobile-report.json</code> 含逐页结果。跑法：<code>node tools/run-mobile-regression.mjs</code>。</td></tr>
|
||
<tr><td>规格从哪来</td><td>移动端<b>没有</b>外部规范原文，规格由本仓库撰写：<code>.design_library/kole-ui-mobile/spec/移动端规格.md</code>。契约 JSON 的 <code>sourceKind</code> 是 <code>authored-spec</code>、<code>provenance</code> 是 <code>authored-in-repo</code>。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</section>
|
||
|
||
<footer class="m-foot">
|
||
<p>生成物：本页由 <code>node tools/build-mobile.mjs</code> 生成，请勿手改。</p>
|
||
<p>下一步：<a href="guide.html">快速开始</a> · <a href="design.html">设计规范</a> · <a href="platform.html">平台与端</a></p>
|
||
</footer>
|
||
</main>
|
||
</div>
|
||
__COPY_SCRIPT__
|
||
</body>
|
||
</html>
|