mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-11 13:31:09 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d489c45cf36b73bafeede4c452f629a06b3b1d9d
reader/docs/ui.md
T

34 KiB
Raw Blame History

界面规范

这份文档规定界面长什么样、为什么。它约束的是客户端的外观层，不涉及排版 （书的排版见 architecture.md §8 —— 那里的原则相反：对书不动手）。

之所以需要一份成文规范：这个客户端的界面层不是一个人一次写完的，而是被反复 改出来的。每一次改动单独看都合理，合起来就成了「这个控件 0.35rem、那个 0.6rem， 这个图标是 Unicode 字符、那个是 emoji」。规范的作用是让「再改一处」这件事有一个 可以对照的基准。

1. 图标

1.1 用字体，不用内联 SVG

图标以字体形式提供：web/src/styles/reader-icons.ttf，40 个字形， 18KB，随 bundle 一起走。

选择字体的理由不是「省事」，而是一致性可以被强制：

字体 内联 SVG
颜色 继承 color 每个组件各自写 fill/stroke
尺寸 继承 font-size，跟着布局缩放 每个组件各自写 width/height
线宽 一个（生成时定死） 每个字形都可能不同
新增图标 加字符 加组件

第二列里的每一项都是「单个字形可以漂移」的位置。内联 SVG 集合最常见的失败 就是这个：三十个组件里总有几个的线宽或视觉重量跟其余不一样，而每个单独看都 说得通。字体把字形变成字符——它没有自己的几何，也就没有可以漂移的地方。

这条约束还有一层：一份产物两个宿主（H5 与 Android WebView）。字体是 bundle 里的 一个相对路径文件，file:// 下能加载；组件化的 SVG 集合则意味着每个宿主都要 正确解析组件，而这一步在 WebView 里是额外的风险面。

1.2 字形名来自 Font Awesome

图标的名字是开源字体图标集 Font Awesome 6 free 的 solid 类名去掉 fa- 前缀： bars（fa-bars）、magnifying-glass（fa-magnifying-glass）、 gear（fa-gear）、table-columns（fa-table-columns）……

这不是为了好看而改名。名字是界面层读的那套词汇（<IconButton icon="magnifying-glass">）， 自己编的时候同一个东西会在三个文件里有三个写法，而不打开 paths.mjs 没人知道一个 名字会画出什么。借一套开源图标的名字，意味着「放大镜」在全项目只有一种拼法，而且 已经熟悉那套图标的人看到名字就知道它画什么。

但轮廓不是 Font Awesome 的。 它们仍然画在同一张 24 单位网格、同一个线宽上， 因为这才是这个生成器能编译成字体的东西（见 §1.2）——而且把一套图标的名字扣在 另一套的轮廓上，恰好是上一段反对的那种混搭。名字是标签，几何是自己的。 test/icons.test.ts 双向钉住了这张对应表。

命名按用途而非形状：sliders（阅读设置）而不是 knobs。

1.3 图标集是生成的

web/tools/icons/ 下的脚本把描边路径编译成字体：

paths.mjs   40 条路径，都画在 24 单位网格上，线宽 3
   ↓        （这是唯一由人编辑的文件）
path.mjs    路径 → 折线
stroke.mjs  折线 → 圆头矩形（每条线段一个）
union.mjs   精确布尔并（Clipper）
build.mjs   → src/styles/reader-icons.ttf + src/ui/icon-names.ts

重新生成：npm run icons。

为什么是「描边 + 布尔并」而不是直接写轮廓：字形要的是填充区域，而图标是 线。两条相接的线段如果只把各自的轮廓放进去，重叠处会有一条发丝缝——在 16px 下那条缝就是整个图标。所以必须做并集，而且必须是精确的并集。

这一步踩过的坑值得记下来，因为它决定了实现方式：先用「栅格化 + 边界追踪」 做过一版，失败了。原因是所有笔画的宽度都只有一个栅格单元，而逐单元的边界 规则无法表达「边界在一格宽的图形上左右交替」——结果是一个圆被追踪成 58 段 碎片。精确布尔没有这种情形。union.mjs 的注释里写了这段。

1.4 垂直度量：为什么图标能对齐

图标「显示正常但对不齐」曾经是个查不出来的问题，因为坏的地方在字体的 垂直度量里，而当时所有测试都只读 cmap 和字形名。记下来，因为只要再动 一次生成器就会重新踩到。

约定（生成器与样式表之间的契约）：

  • 网格中点（12）就是 y = 0，即 em 的中心线；绘制代码用 (GRID / 2 - y)。
  • hhea 与 OS/2 的上升部/下降部各为半个 em（512 / -512），也就是 对称。对称不是审美：UI 里每个容器都在「居中一个盒子」，只有度量对称时 「居中盒子」和「居中字形」才是同一件事。度量不对称时，两者相差正好是那个 不对称量——这就是当初每一行图标歪的幅度都不一样的原因。
  • 每个字形的墨迹必须落在 ±0.5em 内。生成器会检查，越界直接报错。
  • OS/2 的 Windows 度量是无符号的，且必须包住所有字形；fsSelection 打开 USE_TYPO_METRICS（否则引擎会去用 Windows 那一对）。

当初错在哪： 表格声明上升部 960、下降部 -64（基线靠近 em 底部），而字形是 围绕 em 中心画的。于是每个字形的墨迹都画在它所在盒子上边界之上约 0.75em， 而所有布局居中的都是盒子——menu、close、folder 实测偏移一致是 0.496em。

样式表那一半：

.icon {
  line-height: 1;          /* 用字体自己的行盒，而不是自建一个方块 */
  display: inline-block;
  width: 1em;              /* 唯一需要显式给的东西：可预测的前进宽度 */
  text-align: center;
  vertical-align: middle;  /* 非 flex/grid 的行（正文里的行内图标） */
}

line-height: 0 + height: 1em 是错的：那把盒子锚在基线上、向下一整个 em，而墨迹画在基线周围，于是墨迹贴在盒子上沿、盒子下方全空。居中盒子的容器 把盒子居中了，字形却差了半个 em。transform 也不行——它在绘制期移动字形，让 图标占的位置和看起来占的位置不再一致。

代价：web/test/icons.test.ts 会读字体的 hhea / OS/2 / head 与每个字形的 包围盒来断言上面这些，也会读 reader.css 里的 .icon 规则。两边都是之前没被 任何断言覆盖的地方。

1.5 字符编码

  • 码位从 U+E900 起，连续分配，位于私有使用区。
  • 顺序与 paths.mjs 中定义的顺序一致。
  • src/ui/icon-names.ts 由生成器写出，不要手改：码位与字体 cmap 不一致 时渲染成豆腐块，而类型系统查不出这件事。
  • web/test/icons.test.ts 直接解析字体的 cmap 来核对这张表，并断言字体 不映射私有使用区之外的任何码位（否则普通文字在应用了这个字族的元素里 会变成图标）。

1.6 无障碍

Icon 组件的 label 决定语义：

label 行为
字符串 role="img" + aria-label，可访问名就是这个字符串
省略 / null aria-hidden="true"，纯装饰

IconButton 的 label 是必填的，图标本身始终 aria-hidden。 一个没有文字的图标按钮，如果没有名字，屏幕阅读器就只能读出「按钮」—— 而它旁边可能有五个同样的按钮。

这是本次改动之前真实存在的问题：原来的 IconButton 接收任意 children， 调用方传的是 Unicode 字符（☰ ⚙ ✕ ⟨ ⟩ ＋ 🗂 📁）。这带来三个后果：

  1. 八个字形来自八个不同的字族，光学重量各不相同，工具栏看起来是拼的；
  2. 🗂 📁 📄 ⏮ 这些是 emoji，在部分平台被渲染成彩色的——一个彩色 emoji 出现在单色工具栏里，是「这个应用没有设计过」最直接的信号；
  3. 不同平台的字体回退不同，同一个界面在 Android 和桌面浏览器上长得不一样。

现在 IconButton 的 icon 是 IconName，即字形的名字， 传一个不存在的名字是编译错误。

1.7 现在有哪些图标

见 web/tools/icons/paths.mjs。名字就是 Font Awesome 的类名（§1.2）， 所以「这个语义用哪个字形」在改动时不会漂到另一个形状上。

2. 设计令牌

全部定义在 src/styles/reader.css 的 :root 里。界面层不应出现字面量。

2.1 间距：四档

--space-1  0.35rem   控件内部的缝隙
--space-2  0.6rem    控件内部的内边距
--space-3  0.9rem    区块之间的间距
--space-4  1.5rem    页面级区块的内边距

只有四档，这是重点。八档的尺度读起来像精确，用起来像建议：一旦 1.75rem 和 2rem 同时存在，一半样式表用一个、一半用另一个，而任何单条规则里 都看不出矛盾。四档强制回答「这是哪一档」——这个问题有答案，而「再大一点点」 没有。

2.2 字号：按角色

--text-title  1.05rem   屏幕标题
--text-body   0.95rem   正文与按钮
--text-label  0.82rem   字段标签、区块标题
--text-meta   0.72rem   标题下方的元信息

按角色命名而非按尺寸，因为尺寸会变、角色不会：--text-meta 永远是「标题下面 那行」，无论今天是 0.72rem 还是明天 0.75rem。

2.3 动效：一个时长、一条曲线

--motion-duration  0.18s
--motion-ease      cubic-bezier(0.32, 0.72, 0, 1)

一个时长，一条曲线，所有过渡都用它们。两个时长和一个时长的问题是同一个： 各自单独看都合理，成对出现就是错的。

prefers-reduced-motion 通过把 --motion-duration 折叠成 0.001s 来满足， 而不是给每条动画各加一个媒体查询。后者的失败是可预期的：下一个新增的动画就是 唯一没加的那条。折叠令牌之后，所有使用令牌的规则（现在是全部）自动被覆盖， 而硬编码自己时长的规则成为显式的例外而不是隐式的漏洞。

2.4 焦点环

--focus-ring    2px solid color-mix(in srgb, var(--reader-accent) 70%, transparent)
--focus-offset  2px

这是本次改动前完全缺失的一层。 样式表里搜索框有 :focus-visible 规则， 而所有按钮都没有——书架上一整屏控件，用键盘 Tab 走一遍看不到焦点在哪。

现在是一条规则覆盖一组选择器（.button、.icon-button、.chip……）， 而不是每个组件各写一份。新增控件把它加进列表即可，这就是全部工作。

用 :focus-visible 而非 :focus：鼠标点击按钮不应留下焦点环，键盘 Tab 必须 始终显示。

2.5 悬停

统一包在 @media (hover: hover) and (pointer: fine) 里。不加这层的话，触屏上 每次点击都会让最后点的控件停在「悬停」外观上——手指抬起就进入 hover，看起来 像坏了，而不是像有反馈。

3. 布局

3.1 安全区

四个 --safe-* 令牌在 :root 定义一次，各处只引用不直接读 env()。 两个理由，第二个才是关键：一个边一个名字，意味着手机、浏览器和 Android 壳不会 各自对「屏幕从哪开始」有略微不同的理解；而且未定义的自定义属性会让整个 calc() 失效并静默丢弃声明——padding: calc(0.9rem + var(--safe-left)) 在变量未设置时不是「0.9rem 的内边距」，而是完全没有内边距。

3.2 一列，封顶

内容列封顶 68rem（--shelf-measure），宽屏加的是留白而不是更多列。 1600px 窗口排十一个封面、每个书名十二个字，比手机上的三列更难扫—— 这与「多出来的宽度是为了好读」正好相反。

3.3 触控目标

图标按钮 2.5rem（40px），页脚里 2.1rem（34px）。翻页器的页码是 2rem（32px）： 它是读者会反复瞄准的控件，而 0.72rem 的数字装在一个 16px 的盒子里是需要用眼睛 而不是用拇指去点的。页脚那两个翻页按钮是唯一 小于 40px 的交互目标，理由是它们最常用、且紧邻一个同样大的兄弟控件；四个 2.5rem 的控件加一个章节标签会超出 360px 手机的宽度。

SwitchRow 用按钮而不是复选框：整行是 44px 的命中区，复选框会把命中区缩到 16px 的方块上，拇指按不中。

底线是 28px，由 npm run ui:review 逐屏量过（§8）：小于这个数的控件在 拇指上不是「偏小」，而是需要瞄准。

3.4 两个列表屏：书架与书库

这是两个屏幕，不是两个标签页。 书架回答「我能读什么」，书库回答「服务端有什么」， 两者的差别不是同一份数据的两个视图——一条是 books 表（带用户自己的上下架状态）， 一条是挂载目录本身。所以它们是两个路由：

#/shelf[/<页>]            书架
#/library[/<路径>[/<页>]]  书库

做成同一个屏幕的两个标签只会更省事一点点，而会让三件事同时变坏：

  • 返回键。 标签切换会进同一段历史轨迹，于是 Back 变成「退回上一个标签」而不是 离开这个屏幕。书库的面包屑本来是「走进去的文件夹用面包屑退，不用返回键退」， 加一个标签进去，Back 就得同时扮演两个角色。
  • 链接。 #/library/科幻 是能给别人的；「书架的第 3 页」也是（#/shelf/3）。
  • 一屏一个标题。 参照稿里两个屏幕各有自己的标题与右侧入口，而标签栏要占一行。

3.5 翻页，而不是无限滚动

两个列表都分页，页是 URL 的一部分，翻页器在列表下方。

书架原来是在滚到底时追加一批（loadMore）。它有两个问题，而且都不是「体验」问题： 列表没有读者能看见的长度，位置也回不去——关掉再打开从第一屏开始，因为「我在第三屏」 只存在于一个滚动偏移里，而重绘会把它扔掉。两千本书是一个地方，地方需要有位置。 #/shelf/3 就是一个位置：可以返回、可以前进、可以收藏、可以发给别人。

页数是服务端算的，页是服务端切的：

  • 书架：/api/v1/books?page=N&pageSize=60。60 恰好等于原来一次追加的量， 所以一个本来就不卡的书库仍然一个请求铺满一屏。
  • 书库：/api/v1/library/browse?path=…&page=N，一页 200 条。书库面对的是文件系统， 一个放四千张扫描件的 漫画 目录是真实存在的，把四千行发给浏览器丢掉 3940 行 是那个让屏幕显得坏掉的请求。上界 BROWSE_PAGE_SIZE_MAX 保证调用方换不来那个请求。

页码超界在响应之后夹，不在请求之前猜。 唯一知道一共几页的是 total，而它随响应回来—— 读者在第三页时书库缩到两页，问第九页的答案是一个空列表而不是错误；不夹的话读者得到 一张空网格、上面一个页码，没有任何东西告诉他列表其实没问题。夹完再问一次最后一页， 并且把 URL 一起改写，否则 Back 会回到那个被赶走的空页。

翻页是导航，不是本地改数字。 屏幕不自己改页码：它上报意图，shell 写 URL， URL 再回落到 showPage(page)。这一趟往返就是页能活过 Back、Forward 和刷新的全部原因。 翻页器也照此画：aria-current="page" 标当前页，两端禁用而不隐藏，页码窗口是 「首、尾、以及当前页的邻居」——50 页在手机上是一排需要读而不是按的按钮。

3.6 悬浮提示，不占位

状态行（同步中…、离线 · 进度待同步）是浮在正文上方的药丸，不是 插在顶栏和正文之间的横条。

这不是审美。横条在 flex 列里占一行，于是每一次状态变化都会把正文往下推一行 再收回来——读者正在读的那句话会跳。一条他没要过的提示挪动他正在读的字，是 这个界面里最不该发生的事。ui:review 里有一条断言专门盯着这个：把状态行 从空切到有字再切回来，正文顶部的 y 必须三次相同。

同理，提示不吃指针事件（pointer-events: none）：一条挡住读者本来要点的 那一下的提示，代价是读者少翻一页。

3.7 半屏面板

目录和阅读设置是从底部升起的半屏面板，带遮罩和把手，上半屏仍然看得见 正文。

之前的做法是 inset: 0 的全屏页，把书完全盖住。全屏对一个目的地是对的， 对一个控件是错的：选章节、调字号都是对下面那一页的调整，全屏让读者为了做 调整而离开那一页，回来时排版已经变了、他也没有了对照。

三条配套，都不是装饰：

  • 遮罩：没有遮罩的面板读起来像是页面的一部分。它同时也是「点一下关掉」 的命中区，也就是除 ✕ 之外的第二个出口。
  • 把手：从底部升起的面板被理解为可拖拽的。拖动本身没有实现——把手是 可供性，遮罩和 ✕ 是两个真实的出口。画一个做不到的把手比不画更糟，所以 它只是视觉线索，真正移动的是面板自己的滚动。
  • 高度：min(62%, 34rem)，且不超过 78%。一千二百章的目录想要尽可能多的 空间，十一行的设置不想要比它需要更多的空间。

面板打开时它拥有点击：旁边露出的那一条正文不翻页（§7 的优先级）。

3.8 事件层级

一次触摸只属于一个目标，最里面那个赢。ui/gestures.ts 是这条规则的唯一实现， 顺序是：

  1. 读者按到的是控件（链接、按钮、输入、滑块）→ 控件拿走这次手势，不翻页；
  2. 面板开着 → 面板拿走（点遮罩＝关闭，不是翻页）；
  3. 否则拖动是滑动翻页；
  4. 否则短按落在三段点击区里。

有两个坑是文档级别的，改这块之前必须先知道：

  • 必须用 composedPath()，不能用 event.target。 书的正文在 shadow root 里，而 shadow 边界会重定向事件：点正文里的 <p>，监听器看到的 target 是 shadow host。用 target 写不出「段落」和「同一个 shadow 树里的按钮」的区别。
  • 阅读面自己是个滚动容器。滚动模式就是让 shadow host 滚起来。所以 「可滚动的祖先拿走手势」这条规则必须排除它——否则它吃掉每一个手势，每一次 点击都归属某个滚动容器，翻页层级正确但永远到不了。这一条是 2026-09 那轮 「点击页面没反应」的真正原因。

3.9 纯文本（TXT）的排版

TXT 是唯一一种没有作者排版的书，所以它也是唯一一处「我们自己给一套完整 默认值」是对的、而不是侵入的地方。EPUB 的默认必须交给作者自己的样式表， 覆盖它是 bug；TXT 没有作者。

两层分工，改任何一层之前先看清是哪一层。排版全部在客户端， 服务端只负责把章节完整地交出来——这条边界是这一层最重要的一条规定：

  • 服务端（server/src/indexer/formats/text.ts）：只做一件事——把整章 交出来。chapter: 是为流式读取开的窗口，按 size 截断是它的功能； chapter-full:<n>（旧名 chapter-html:<n>，仍兼容）是给读者整章读的，不截断，内容类型是 text/plain。它不再断段、不再提升标题、不再输出 <p>：断段是阅读 决定，服务端做就等于让 windowed 那一份有段落、流式那一份没有，也让读者的 缩进设置变成一次往返。
  • 客户端排版（web/src/formats/segments.ts）：splitTextParagraphs 是 「一段是什么」的唯一定义，本地加载的 TXT、windowed 的 chapter-full:<n>、流式的 chunk: 三条路都走它，所以同一本书不会因为走哪条 传输看起来不一样。它同时负责去掉段前空格（　　正文 里那个全角空格是 「段前空格」的来源，留着就是和读者的缩进叠加），以及章节标题行提升成 <h3>（splitChapterHeading，否则正文会变成 第二章 落雨雨来了。）。 ReaderView 在 retypePlainText 里对拿到的章节过这一段逻辑；如果内容带着 历史的 .txt-body 标记（旧服务端、旧缓存），就按块读回文本再拆，所以旧 响应不会被当成新响应渲染。
  • 客户端样式表（web/src/ui/shadow.ts 的 TXT_STYLESHEET）：只在 ReaderView.isPlainText() 为真时注入，作用域是 .txt-body。默认两字符首行 缩进（2em，不是 2rem——缩进要跟字号缩放）。样式表里没有任何一条规则读 服务端写的属性：「不缩进」是同一个自定义属性取 0，而不是第二条要和第一条 保持一致的分支。
  • 「这一章是不是纯文本」怎么判定：靠声明，不靠嗅探。manifest 的 content item 写 format: 'html' → createStagedDoc 把它落到 Section.plainText → isPlainText() 认它。这条链必须完整：服务端现在发的是 裸字符，没有 .txt-body 包裹，所以「正文里有没有 txt-body」这个老办法 对一章节全是纯文本的章节会答「不是」——读者于是看到一本没有段落、没有缩进、 样式表也没挂上的小说，而这看起来像排版偏好而不像 bug。.txt-body 标记只留作 最后兜底（旧服务端／旧缓存）。
  • 阅读设置：段落缩进、段间距、编码三行，只在 TXT 上出现；设置面板顶部的 「快捷」一行（字号／缩进／段间距／主题）也是同一批值的另一个入口，一次点击 走一档。前两个是写在 stage 上的自定义属性（--reader-txt-indent / --reader-txt-para-gap），所以调整不需要重新注入章节、也不需要请求。

引用保持 chapter:<n> 不变，format: 'html' 字段告诉客户端取哪一份 （renditionRef 据此把它换成不截断的 chapter-full:<n>）。href 同时是 阅读位置的标识，改它会把每个现有 TXT 读者打回第一章。

3.10 沉浸式阅读

顶栏和底栏是一个状态，不是一个状态乘以二。 读者要收起导航就是要看到正文， 上面收了下面没收，就是读者报的「只收起了一半」——底部那条一直压着每一页的最后 两行。所以两条栏由 .reader-screen 上的一个 data-chrome 属性一起开关，写法上 不可能只藏一半，动效、时长、缓动也完全一致（--motion-duration + 同一缓动）。

三条实现约束，改这块之前先知道：

  • 收起的不是浮层，是占位。 两条栏是正常流里的 band，收起时 height 归零、 transform 滑出、visibility: hidden（不是 display: none——那没有东西可以 做动画，也让「隐藏」和「不可点」两件事分家）。归零的高度由 flex: 1 1 auto 的 stage 立刻拿走，所以页面是长进这块空间，而不是先跳一下再填上。
  • visibility 在动画结束后才生效（transition: visibility 0s linear var(--motion-duration)）：滑出的过程中标题还在，动画走完它就既看不见也点不 到了。少写这一行，读者能点到一个看不见的返回按钮。
  • 右侧的快捷按钮列和两条栏一起出现、一起收起（.reader-rail），由同一个 data-chrome 属性开关，和顶栏底栏共用一套动效。读者最常用的四个动作（目录 / 主题 / 字号 / 设置）一步可达，而且按钮住在正文的版心旁边（宽屏时用 --reader-measure 算出的天头地脚里），不压字。它不属于沉浸态：那四个动作 和顶栏是同一批目的地，属于「读者要控件」这个状态；沉浸态多出一列浮在正文右 边缘的按钮，就不是读者要的「只剩正文」。
  • 收起时正文一角仍留两个读数（.reading-indicator）：当前章节名在左上、 页码与总进度在左下。这是「沉浸式」与「应用停止绘制」的区别——读者收起工具栏 就是要看正文，但仍然要知道自己在哪一页，让他为此再点一下正是收起状态要 省掉的那次交互。两个读数 pointer-events: none（它们是读数不是控件，点它们 必须落到下面的翻页区），且只在收起时绘制，不和工具栏重复。

顶栏与底栏各自的形态（对应参照稿）：

  • 顶栏是一排「图标在上、文字在下」的等宽按钮（.top-button），不是「标题 + 返回箭头」。参照稿里它是读者扫着用的一行工具栏，每个控件一样重、一样一步 可达。书的名字曾经写在这里，现在它属于 .reading-indicator——读者找标题时 眼睛去的地方是正文角上，不是工具栏。按钮只保留这个屏幕真能做到的动作 （返回 / 目录 / 设置）：参照稿的「首页/书架/书源」里有阅读页内部走不到的目的地， 一个点了没处的按钮比少一个按钮更糟。
  • 底栏是两行（.progress-row + .chapter-nav）：一行可拖动的章节内页数 滑杆加页码读数，一行「上一章 / 阅读进度 / 下一章」。滑杆取代了原来那条 3px 的 进度条——条只能报告位置，读者想到一章末尾得连点四十次「下一页」； input[type=range] 一个手势就到，而且拇指、轨道、拖动惯性和无障碍（方向键、 aria-valuenow）都是原生的，不用自己实现一遍。
  • 滑杆量的是章节内的页（min=1、max=chapterPages），不是全书百分比。 滑杆旁边写的是「第 3/9 页」，两者必须来自同一个测量，否则一次拖动会落在 读数从没提过的位置上——这正是最初「滑杆拖到中间却跳到第 40 章」的成因。 全书进度是下面那行「阅读进度：xx%」的事，那行只报告，不承载手势。 所以拖动滑杆不会跨章：它只移动当前章节内的位置（见 ReaderView.seekPageInChapter）。

手势上，中间三分之一在两个方向上都是开关；左右三分之一只在 chrome 已经 收起时才充当「叫回来」的出口（§3.8 的优先级第 2 条）。收起状态下任何一条区都 是出口，是因为读者此时没有别的出路；已经显示时还抢左右三分之一，就是把「翻页 没反应」做成常态。

4. 文案

  • 中文，句末不加句号（我的书架、正在刷新）。界面文本不是段落。
  • 说清楚发生了什么，而不是说「出错了」。 已更新 2 本、 这一章暂时无法跳转、连不上这个地址。确认服务端已启动，且地址包含端口。
  • 不承诺不能兑现的事。 只读挂载上不显示上传按钮（用 hidden 而非不渲染， 见 §5），而不是显示一个按了会 403 的按钮。
  • 空状态给一条出路。 空书库不是「这里什么都没有」，而是「打开书库管理 / 刷新」两个按钮；搜不到结果是「清除搜索」。

5. 状态的表达

状态 用法 反例
禁用 disabled + opacity: 0.55 隐藏按钮，让读者以为功能不存在
不可用（权限） hidden 隐藏整个区块，让读者不知道这里能管理书库
忙碌 按钮文案变「正在切换…」，控件 disabled 只留一个转圈，读者不知道在等什么
无能力 不渲染该行 显示一个按了没反应的滑块

最后一行值得展开：朗读设置面板在 HTTP 引擎下不显示音调那一行，因为 <audio> 根本没有音调。而不是显示一个拖动无效的滑块。

hidden 而非不渲染的那一条同样是刻意的：能做的和不能做的区别本身就是 信息。全部藏起来，读者学到的是「这个应用的按钮时有时无」。

6. 暗色与主题

三套主题：light / sepia / dark，通过 :root 上的 data-theme 切换调色板变量。

  • 主题只改界面的颜色。书的颜色由书自己决定——一个硬编码 color: #333 的段落，在暗色主题下保持它自己的颜色。这是正确的取舍： 暗色主题悄悄破坏一本印刷取向的书的对比度是缺陷，而一本书在「暗色」背景上 显示深色文字，是读者能看见并自行判断的。
  • 亮度是 mix-blend-mode: multiply 的覆盖层，不是调色板。换主题应该保留 纸与字的对比关系；直接改颜色会把文字一起压暗——那正是「亮度」滑杆最常见的 失败方式。
  • 新增颜色一律走 :root 变量。样式表里现存三个状态色 （#4a8f5f/#c08a2e/#b6453a）和一处危险色（#c0392b）是已知例外， 它们是语义色不是主题色，但应当在下次改动时提升为令牌。

7. 端到端测试要做 UI 评审，不能只看功能

功能测试问的是「点了会不会变」，UI 评审问的是「变了之后能不能用」。两者可以 同时给出相反的回答，而且这在真实项目里是常态——下面每一条都曾在功能全绿的同时 是错的：

曾经的形态 功能测试怎么看 读者怎么看
目录是 inset: 0 全屏页 ✅ 点开有面板，点条目会跳转 为了选一章而离开那一页
翻页步长 0.9 屏 ✅ scrollTop 变大了 每次翻页留一条上一页的尾巴
页数按内容高度算 ✅ 画出了 本章 x/y 页 翻到最后一页时数字不认账
状态行是 flex 里的一行 ✅ 文案正确渲染 每次同步都把他正在读的那句推走
图标按钮自己拼的 ✅ 点击有反应 图标和文字差半个字高
底栏滑杆量的是全书百分比 ✅ 拖了会动、页码也变了 想翻到本章第 7 页，被带到了第 40 章
快捷按钮列只在沉浸态出现 ✅ 收起工具栏后按钮还在 收起后正文右边仍压着一列浮层

所以 npm run ui:review 做两件事，两件都要：

  1. 截图（docs/ui-review/*.png）。这一步没有断言可以替代。「只是丑」不是 测试失败，但它是缺陷。截图交给评审的人看。
  2. 量尺寸（同一脚本，断言）。可以量的事情不该让人用眼睛判断，而且评审的人 不在流水线里。当前量的是：顶栏/底栏/快捷列三条 band 一起收放、收起时正文占满 且只留两个读数、面板不遮住整页且留出 ≥120px 正文、面板有遮罩和把手、滑杆量 的是章节内页数并且拖到第 N 页就停在第 N 页、状态提示不推动正文、每个控件 ≥28px 且有名字、没有横向溢出、翻页不再成对发 sync。

它跑在真实的生产产物上：npm run build 之后由 tools/ui-review/server.mjs 起一个替身 API，再让真实 Chromium 以 390×844、2x 逐屏加载。不是 storybook—— 组件故事会喂进手写的 state，而上面那些缺陷全都发生在「屏幕对真实响应」的时候。

断言挂在 client-ui-review 流水线上，只在界面相关文件变化时触发。

8. 改动这份界面时的检查单

  1. 新颜色 / 新间距 / 新时长 → 先看 :root 里有没有，没有就加令牌， 不要在规则里写字面量。
  2. 新图标 → 加一条路径到 tools/icons/paths.mjs，键名用 Font Awesome 的 类名去掉 fa-（§1.2），跑 npm run icons，用 IconButton 引用名字。
  3. 新控件 → 确认它出现在 §2.4 的焦点选择器列表里。
  4. 新动画 → 用 --motion-duration 和 --motion-ease，不要自己写时长。
  5. 有状态变化的控件 → 对照 §5 那张表，确认用的是对的那一种。
  6. 图标按钮 → label 必填，且这条 label 是这个按钮自己的作用， 不是它所在的区块的名字。
  7. 图标 + 文字并排 → 用 IconTextButton，不要自己拼一个 <button> 加一个 <span class="icon">；图标加文字正是最容易歪的组合，而它每次歪的方式都 一样（字形落到文字基线上）。
  8. 动图标相关的东西 → 先读 §1.4。图标对齐是字体度量和 CSS 两半一起决定的， 只改一半会得到一个更小的偏移，而不是没有偏移。
  9. 动布局 → 跑 npm run ui:review，并且看截图。 断言只覆盖已经量过的那些 规则；新缺陷的第一道防线是眼睛。
  10. 加一条能一直看着的断言，如果这条规则是能量出来的。下一个人不会看到 这次截图。
  11. 加一个列表页 → 页数由服务端给，页由服务端切，页是 URL 的一部分（§3.5）。 在客户端切好一页再丢掉、或把页码只放在组件状态里，都会在 Back、Forward 和 刷新这三件事上分别坏一次，而这三件事没有一条是功能测试会先撞上的。

9. 相关文件

路径 内容
web/src/ui/icon.tsx Icon 组件
web/src/ui/icon-names.ts 码位表（生成）
web/src/styles/reader-icons.ttf 字体（生成）
web/tools/icons/ 生成器
web/test/icons.test.ts 字体度量、字形包围盒、码位表、Font Awesome 名字表与 .icon 规则的契约
web/src/ui/toolkit.tsx IconButton / Button / Segmented / SwitchRow / Scrim
web/src/ui/shelf-screen.tsx 书架；分页器（§3.5）与书库入口（§3.4）
web/src/ui/manager-screen.tsx 书库；面包屑、分页器、上传后重读（§3.5）
web/test/shelf-screen.test.ts 书架分页的算术：请求哪一页、超界怎么夹、翻页上报而不是自己改
web/test/manager.test.ts 书库分页、上传后的重读，以及「破坏性操作必须先选中再确认」
web/src/ui/gestures.ts 手势与事件层级（§3.6）
web/src/ui/reader-chrome.tsx 阅读页的顶栏/页脚/面板/朗读条/沉浸式按钮列
web/src/ui/shadow.ts 书内容 shadow root；含纯文本排版表（§3.9）
web/src/formats/segments.ts 纯文本分段（「一段是什么」的唯一定义，§3.9）
web/src/ui/reader-view.ts 章节渲染与位置；retypePlainText 是客户端排版落地处（§3.9）
web/test/gestures.test.ts 事件层级的优先级契约
web/test/reader-paging.test.ts 翻页的页序号算术（含子像素取整）
web/tools/ui-review/ UI 评审：截图 + 尺寸断言（§7）
docs/ui-review/ 评审截图与 report.json（生成，随 PR 一起看）
web/src/styles/reader.css 令牌、组件样式、交互状态、prefers-reduced-motion
Reference in new issue View Git Blame Copy Permalink