这份文档规定界面长什么样、为什么。它约束的是客户端的外观层,不涉及排版
(书的排版见 architecture.md §8 —— 那里的原则相反:对书不动手)。
之所以需要一份成文规范:这个客户端的界面层不是一个人一次写完的,而是被反复 改出来的。每一次改动单独看都合理,合起来就成了「这个控件 0.35rem、那个 0.6rem, 这个图标是 Unicode 字符、那个是 emoji」。规范的作用是让「再改一处」这件事有一个 可以对照的基准。
图标统一使用 lucide-react 的 SVG,web/src/ui/icon.tsx 集中维护名称映射,也是唯一引入 lucide-react 的文件
(test/icons.test.ts 守住)。界面使用 Icon / IconButton / IconTextButton,不直接嵌入字体码位、emoji 或 ✓ × + 这类字符。
- 名称:一个意思一个名字、一个字形,用本项目自己的英文名(
video、audiobook、lock、folder-browse), 不借用其他图标集的名字。新增图标只改icon.tsx的ICONS。 - 尺寸:不传
size时为 1em(控件里用这个);需要固定尺寸时只取 14 / 16 / 18 / 20 / 24 / 32 六档。 - 线宽:一律 1.8;32px 的空状态大图标用 1.4,否则放大后像粗体图示;导航当前项用
strong(2.1)。filled用文字颜色填充(播放三角、已收藏)。 - 装饰图标默认
aria-hidden;独立表意时传label。没有文字的按钮必须有中文 aria-label。
间距、字号、动效、焦点环、圆角、安全区定义在 web/src/styles/reader.css 的 :root 里;
颜色令牌在 web/src/styles/theme-tokens.css(§6)。界面层不应出现字面量。
--space-1 0.35rem 控件内部的缝隙
--space-2 0.6rem 控件内部的内边距
--space-3 0.9rem 区块之间的间距
--space-4 1.5rem 页面级区块的内边距
只有四档,这是重点。八档的尺度读起来像精确,用起来像建议:一旦
1.75rem 和 2rem 同时存在,一半样式表用一个、一半用另一个,而任何单条规则里
都看不出矛盾。四档强制回答「这是哪一档」——这个问题有答案,而「再大一点点」
没有。
--text-display 1.375rem 页面大标题、空状态标题
--text-title 1.05rem 屏幕标题、卡片标题;也是输入框的下限(见下)
--text-body 0.95rem 阅读侧正文与按钮
--text-ui 0.875rem 应用界面的列表行、设置行(影音正文)
--text-label 0.82rem 字段标签、区块标题、次要按钮
--text-meta 0.75rem 标题下方的元信息:数量、时间、来源
--text-micro 0.625rem 封面与图标上的角标,别处不用
按角色命名而非按尺寸,因为尺寸会变、角色不会:--text-meta 永远是「标题下面
那行」,无论今天是 0.72rem 还是明天 0.75rem。(它确实从 0.72rem 改成了 0.75rem:
影音界面 200 多处 12px 的元信息因此原样落档,阅读侧的元信息只大了半个像素。)
迁移前四档只约束了阅读侧,影音样式表里 8–24px 每个整数都用过。现在 24px 以下的字号
必须用令牌,web/test/design-tokens.test.ts 会拒绝字面量;24px 以上是装饰性大字
(播放页的首字、大数字),保留字面量。
输入框至少 16px:更小的字号会让 iOS Safari 在聚焦时放大视口。需要这条下限的输入框
用 --text-title,不要退到 --text-body。
--motion-duration 0.18s
--motion-ease cubic-bezier(0.32, 0.72, 0, 1)
一个时长,一条曲线,所有过渡都用它们。两个时长和一个时长的问题是同一个: 各自单独看都合理,成对出现就是错的。
prefers-reduced-motion 通过把 --motion-duration 折叠成 0.001s 来满足,
而不是给每条动画各加一个媒体查询。后者的失败是可预期的:下一个新增的动画就是
唯一没加的那条。折叠令牌之后,所有使用令牌的规则(现在是全部)自动被覆盖,
而硬编码自己时长的规则成为显式的例外而不是隐式的漏洞。
--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 必须
始终显示。
统一包在 @media (hover: hover) and (pointer: fine) 里。不加这层的话,触屏上
每次点击都会让最后点的控件停在「悬停」外观上——手指抬起就进入 hover,看起来
像坏了,而不是像有反馈。
test/design-tokens.test.ts 检查 src/ 下每条带 :hover 的规则都在这样一个块里。
.x:hover, .x:focus-visible 这类混写要拆开::focus-visible 留在外面(键盘在触屏
设备上也要有反馈),:hover 那一半紧跟其后放进守卫块,层叠顺序不变。
--radius-xs 4px 角标、标签、进度条
--radius-sm 8px 小控件、菜单项、缩略图、封面
--radius-md 10px 按钮、输入框、菜单、列表卡片(= --reader-radius)
--radius-lg 14px 面板、页面级卡片、浮层
--radius-xl 20px 底部 Sheet、大卡片
--radius-pill 999px 胶囊:芯片、开关、圆角等于半高的按钮
圆形用 50%,直角用 0,这两个不算档位。迁移前样式表里有 2/3/4/5/6/7/8/9/10/11/12/13/14/15/18/19/20/22/24px
外加十几个 rem 值,同一类控件在相邻两屏差 1–2px,单独看都对,放在一起就是两套界面。
胶囊要写 pill,不要写半高。 height: 26px; border-radius: 13px 在高度改成 28px 的那天
就不再是胶囊了;--radius-pill 与高度无关。
没有封面的书、影片按标题取一个色相(web/src/ui/cover-tint.ts,12 档、每档 30°),
写进 --cover-hue,样式表把 hsl(var(--cover-hue) 55% 55%) 以 10–20% 混进当前主题的
surface。这是「组件不写死颜色」的唯一例外,理由与封面图片相同:它是内容的颜色,不是界面的颜色。
- 按标题取,不按位置取:同一本书在书架、书库、搜索里颜色一致,刷新也不变。
- 只混少量:占位上的文字仍用 ink/muted,对比度由主题保证;深色模式下自然变成暗底微染。
- 不加色相之前,一屏全是同一个色块,只能逐个读字找书。
四个 --safe-* 令牌在 :root 定义一次,各处只引用不直接读 env()。
两个理由,第二个才是关键:一个边一个名字,意味着手机、浏览器和 Android 壳不会
各自对「屏幕从哪开始」有略微不同的理解;而且未定义的自定义属性会让整个
calc() 失效并静默丢弃声明——padding: calc(0.9rem + var(--safe-left))
在变量未设置时不是「0.9rem 的内边距」,而是完全没有内边距。
谁贴着哪条边,谁加哪个安全区。 只有真正贴着屏幕边的那一层加,而且只加一次:
- 顶边:贴顶的页头加
--safe-top(书架/书库.shelf-head、.collection-header, 书源.sources-header,手机上的影音页.media-screen,首页与我的,阅读器顶栏与页眉)。 - 底边:手机底栏
.app-nav、Sheet 的底部、阅读器底栏与页脚加--safe-bottom; 浮在底部的东西(Notyf、.pwa-update更新条、迷你播放器)放在这些栏的上方, 偏移量与styles/notifications.css一致,不能盖住导航或阅读器底栏。 - 左右边(横屏刘海):宽度 ≥701px 时手机横屏也会进入侧栏布局。侧栏贴左边,
由它加
--safe-left;内容列贴右边,由.app-shell-body用padding-right统一 承担右侧安全区,并在内部把--safe-left/--safe-right置为 0——内容列里各条带 自己也会加安全区,不置 0 就会被缩进两次,或被一个它根本不挨着的刘海缩进。 阅读器不在外壳里,它的顶栏和底栏左右各加--safe-left/--safe-right。 - 一条规则同时写四个方向的
padding时,核对左右没有写反(.shelf-head曾经把--safe-right加在左边)。
iOS 独立窗口用 apple-mobile-web-app-status-bar-style: default:页面从状态栏下方开始,
竖屏 --safe-top 为 0。black-translucent 会让状态栏文字恒为白色,在默认浅色主题上
看不见,所以不用;上面的顶边规则仍然保留,给会报告顶部安全区的浏览器和方向用。
Android 壳在原生层处理系统栏(MainActivity.applyInsets),WebView 里四个值都是 0。
验证安全区不用真机:Chromium 的 CDP Emulation.setSafeAreaInsetsOverride 可以给
env(safe-area-inset-*) 填任意值。改动贴边的条时,至少用竖屏(上 59 / 下 34)和
横屏(左右 59 / 下 21)各看一遍。
首页、书架、影音、我的共用一条内容列:内容宽度封顶 --page-measure(--collection-measure 80rem 减去书架带内边距,约 1251px),
两侧留白 --page-gutter(手机 16px,侧栏模式 32px),切换标签页时内容边缘不动。宽屏加的是留白而不是更多列。
1600px 窗口排十一个封面、每个书名十二个字,比手机上的三列更难扫——
这与「多出来的宽度是为了好读」正好相反。
图标按钮 2.5rem(40px),页脚里 2.1rem(34px)。翻页器的页码是 2rem(32px): 它是读者会反复瞄准的控件,而 0.72rem 的数字装在一个 16px 的盒子里是需要用眼睛 而不是用拇指去点的。页脚那两个翻页按钮是唯一 小于 40px 的交互目标,理由是它们最常用、且紧邻一个同样大的兄弟控件;四个 2.5rem 的控件加一个章节标签会超出 360px 手机的宽度。
SwitchRow 用按钮而不是复选框:整行是 44px 的命中区,复选框会把命中区缩到
16px 的方块上,拇指按不中。
底线是 28px,由 npm run ui:review 逐屏量过(§7):小于这个数的控件在
拇指上不是「偏小」,而是需要瞄准。
在 (pointer: coarse) 设备上,外观必须小的控件用透明的 ::before 把命中区扩到
约 44px,外观不变:筛选/排序芯片 .chip(29px 高;水平方向只扩一点,免得相邻芯片
互相抢点击)、封面角上的 ⋯(.book-more)和「加入书架」(.book-shelve)。
手指能点到的输入框,字号至少 16px(--text-title)。iOS 不理会
maximum-scale=1,聚焦小于 16px 的输入框会把整页放大;侧栏的全局搜索在
(pointer: coarse) 下因此改用 --text-title。
这是两个屏幕,不是两个标签页。 书架回答「我能读什么」,书库回答「服务端有什么」,
两者的差别不是同一份数据的两个视图——一条是 books 表(带用户自己的上下架状态),
一条是挂载目录本身。所以它们是两个路由:
#/shelf[?page=<页>&sort=…&q=…] 书架
#/sources?tab=explore&source=local 书库浏览:「发现」里的本地书库(见 §3.4.0)
#/library/files[?path=<路径>&page=<页>] 书库文件管理页
书库不再有自己的浏览页。 本地书库是一个内置书源(reader.local),和 Legado、OPDS
一样在书源中心的「发现」里按层浏览:一层是一个文件夹,子文件夹是导航,本层的书是条目。
两个入口浏览同一批书、各有一套搜索和布局,是读者分不清的重复,所以只留一个。
- 入口。 书架的「书库」、我的「书库」都指向
#/sources?tab=explore&source=local(shared/library-link.ts)。source=local指内置书库,不依赖实例 id。 - 旧地址。
#/library、#/library/books重定向到上面的地址;带?q=时打开「搜书」 并直接对本地书库搜索(#/sources?source=local&q=…),全局搜索的「在书库查看全部」同此。 - 已在书架的书画「阅读」。 本地条目带
metadata.publicationId时直接打开,不再画「加入书架」。 - 只有本地书库多出三个动作。 「上传书籍」(服务端允许且目录可写时,传到当前文件夹,
传完重新读这一层)、「刷新」和管理员的「文件管理」(带着当前文件夹进
#/library/files)。 「刷新」重新读当前这一层并作废书架、书库的缓存;管理员的刷新先跑一次增量扫描 (POST /api/v1/library/scan,正在扫描时并入那一次),再说清扫到了什么(「新增 2 本」 或「书库已是最新」)。成员没有扫描权限,只重读——定时扫描(业务设置「阅读书库自动检查 间隔」)负责把新文件收进来。刷新不会把书加入任何人的书架。 - 编辑信息、更换封面。 管理员在本地书库的「详情」里有这两个动作,书架卡片的 ⋯ 里也有,打开的是同一张表单
(
ui/book-metadata-sheet.tsx)和同一张换封面表(ui/change-cover-sheet.tsx)。本地书只有一份信息,改了所有读者 都会看到,所以成员看不到本地书的这两个动作(服务端也会拒绝);成员书架上来自书源的书仍有。 只提交改过的字段(没动的字段不会被钉成手动值);带手动值的字段旁有「恢复」,单独撤销那一项, 回到文件里的值——清空输入框不等于恢复,空值也是一种手动值。 - 列表 / 网格。 「发现」对所有书源提供两种布局,选择记在设置
exploreLayout(默认列表)。 列表行有简介和最新章节;网格只有封面、书名、作者和一个动作,点封面开详情。
下面 §3.4.1–§3.4.1.2 记录的是合并前的浏览页设计,文件管理页的部分(§3.4.4 起)仍然有效。
做成同一个屏幕的两个标签只会更省事一点点,而会让三件事同时变坏:
- 返回键。 标签切换会进同一段历史轨迹,于是 Back 变成「退回上一个标签」而不是 离开这个屏幕。书库的面包屑本来是「走进去的文件夹用面包屑退,不用返回键退」, 加一个标签进去,Back 就得同时扮演两个角色。
- 链接。
#/library?path=科幻是能给别人的;「书架的第 3 页」也是(#/shelf?page=3)。 - 一屏一个标题。 参照稿里两个屏幕各有自己的标题与右侧入口,而标签栏要占一行。
已被 §3.4.0 取代:浏览页并入了「发现」,这里保留当时的取舍。
这一版改了上一版。 上一版把书库做成「一个屏幕、两个页面、一个页签」,理由是 「标签进了历史就是 Back 走标签而不是离开书库」。那一版被 #40 退回来了,理由更大:
书库预览页和管理页拆开,两者列表显示逻辑不一样。预览页需要显示搜索框,类似一个 商城的布局。而书库管理页面只有管理员才能看到使用。
一个页面装不下两个列表,因为它们根本不是同一份数据的两种画法:
| 浏览(读者那一半) | 文件管理(管理员那一半) | |
|---|---|---|
| 问的问题 | 「这里有什么可读的」 | 「我的书在哪,让我挪一下」 |
| 端点 | /api/v1/books?path=…&search=… |
/api/v1/library/browse?path=… |
| 一条是什么 | 一本书(书名、封面、作者) | 一个文件(文件名、大小、扫描标记) |
| 布局 | 商城:搜索框在最上,封面网格铺满窗口 | 清点:面包屑 + 文件行 + 批量条 |
| 一页多少 | 60 本 | 200 条 |
| 谁能用 | 任何登录用户(成员可在这里上传书籍) | 只有管理员 |
做成一个屏幕的两个页面会同时逼出三句假话:
- 一个头部服务两个列表。 浏览页的头部要有搜索框,文件页的头部要有面包屑、 上传和新建;共用之后两边都得让步,让步的产物就是上一版里那个既不像商城也不像 文件管理器的头部。
- 一条可达性规则。
#/library?path=科幻打开的是封面,而文件管理器离它只有一次 「页签」点击——也就是每一个能发给别人的链接都通向一个可以删书的页面。 - 一个页码。 两边分页的列表和每页条数都不同,切换必须重置页码,于是「第 4 页」 按哪个页面在看会是两个意思。
所以是两个路由:
#/library[?path=<路径>&page=<页>&q=<搜索>]
#/library/files[?path=<路径>&page=<页>]
(#/library/books 是浏览页的旧别名。)
#/library?path=科幻是浏览页。没有files段,因为这是读者要的页面,也是 别人发给你的那个链接。搜索是?q=:它是自由文本、可以没有、并且和路径是两个参数 ——这样文件夹里叫什么都无所谓。#/library/files?path=科幻是文件管理页。只有管理员进得来,而这是服务端的规矩 (每一行都写磁盘);客户端这一层是「不给他建那个页面」,见 §3.4.4。
两个路由的代价是:切换从「页签」变成导航,于是 Back 回到你刚才在的那一半。 对两个不同受众的屏幕来说,这正是对的读法,也是这次报告要的。
预览页要的是「这个文件夹里的书」,而那是 /api/v1/books 的形状,所以它问的是
/api/v1/books?path=<目录>&search=<词>。做一个新端点、或者把 /library/browse 的行
渲染成网格,都不行:browse 的一条是文件名,不是书名,而且没有封面——那会是一屏
「把文件名画在书名位置」的格子。path 是对 rel_path 的前缀匹配,
带上分隔符(dir/% 而不是 %dir%),否则「筛选科幻」会把「筛选科学」一起拖进来;
% 和 _ 是合法文件名字符也是 LIKE 通配符,所以两个都转义。
「类似一个商城的布局」落到三条具体规则上:
- 搜索框在最上面,是这一页自己的,筛的是这个文件夹(面包屑是范围)。 它和文件夹、页码一起进 URL,所以一次筛选是一个链接。
- 网格不被
--shelf-measure截住。 书架要截,因为书架是读者自己那一柜、 按他选的大小铺,一屏十一张封面是墙不是列表。书库是服务端的目录,大小是磁盘的 事实,宽屏上读者想要的是多看见一些而不是多两边的留白。所以这一页是auto-fill无上限,并且封面尺寸阶梯比书架高一档——去掉上限以后用书架的阶梯 会立刻退化成一屏 130px 的缩略图,正是阶梯存在的理由。 - 子文件夹是搜索框下的一行芯片(取自
/library/browse的目录项,扫描忽略的不画), 点一个就把范围缩小一级;面包屑负责放大回去。下面的书是「这个文件夹及其子文件夹」的。 - 每张封面一个动作。 「加入书架」只画在不在书架上的那几本上(§3.4.1 末段、§3.5.2)。
「书架的搜索框两边需要增加 margin」是一条经验,但它说的是一件比「加个 margin」更 具体的事:字段原来和封面列同宽,于是胶囊的 1px 边框、以及清除按钮那个 40px 的 圆,都落在封面的同一条竖线上——在那个距离上,边框读起来像封面的一部分,清除按钮 看起来像在第一张封面里面。
所以:
- 留白是一个 token(
--shelf-search-inset),两边相等,否则字段会整体偏移, 那是「什么都没做错但看着歪」的另一种成因; - 它声明在
:root而不是.shelf上。这一条是修出来的:token 原来挂在.shelf上,而书库的搜索框不在.shelf里,padding-inline: var(--undefined)就是padding-inline: 0——留白静默地不出现,跑了一整轮评审 才被「字段左 0px / 右 0px」这句测量抓住; - 输入框
type=search自带的那颗清除按钮要关掉(::-webkit-search-cancel-button), 否则一屏上有两个清除控件,其中一个是浏览器自己的蓝色小叉。
「加入书架」画在 shelfState: 'off' 的书上,而 shelfState 来自这一页自己的书单**。**
这一条修了两遍,第一遍修错了地方,值得记下来——因为错的那个方案在当时看起来更省事:
- 第一版从文件列表上取状态,并且要求「这本书的文件得在本页上」。理由是端点收
的是路径,而
BookDto没有路径,两者只能靠去掉扩展名的文件名去对。 于是文件夹第二页上、文件在第一页的那本书报不出路径,卡片就不画控件。 - 第二版(#40 退回第一版之后)把整个 join 拿掉了:写入带的是
book.id(§3.5.2),所以「文件在哪一页」不再影响任何事,状态也从书单上取。于是三态变成两态:
| 情况 | 画什么 |
|---|---|
shelfState: 'on' |
不画(已经在了) |
shelfState: 'off' |
画「加入书架」——这一页存在的理由 |
shelfState 缺省(老服务端没有这个字段) |
不画(按钮会写出一个没人能预测的结果) |
这一页问的是索引,不是读者自己的书架(/api/v1/books?scope=library&path=…):
问书架的话,返回的每一本都已经在书架上,shelfState 恒为 'on'——
这一页存在的那个动作永远画不出来。这是第一版真正的病根,比 join 更早:
一个商城只陈列你已经买过的东西,就没有东西可以加。
网格上面那行(「这一页有 N 本还不在书架上」)数的是同一份集合,
而不是整个文件夹:一行说 12 本、下面只有一个角标,是一句和自己画的东西矛盾的话。
ui:review 里有一条断言同时盯两边:角标数 > 0 且 < 卡片数——
恒为 0 和恒为全部,都是这一页坏掉的样子。
书架有四个排序:最近阅读(默认)、最近入库、书名、作者。 两个「最近」问的是两个不同的时间——读者上一次读这本书,和这本书进这个库—— 而这个区别曾经被一个「最近更新」盖住了,它问的是第三个时间(文件改动时间)。
三件事因此成立:
- 默认是「最近阅读」。 打开应用要回答的问题是「我上次读到哪」,而它一天问四十次; 「我刚放了什么进来」是扫描完那一次才问的问题。把后者当默认, 等于每次打开都先回答一个没人问的问题。
- 「最近入库」留着。 它差点被删掉,而留着是对的:它就是上面那个「扫描完才问」的问题, 而那时候「书名/作者」都不是读者想要的那个顺序。
- 存储里的
updated向前折叠成added。 名字换过(它本来就是「什么时候进的库」), 而一个存在本地、界面里选不到、服务端也认不出的排序值,会变成「设置被忽略了」。
排序键的归属不一样,这是最要紧的一条:
added/title/author是服务端的键,所以它们由服务端排序、服务端分页。recent也是服务端的键,请求里叫sort=updated:书架范围内它按本账号的阅读进度 更新时间排序(reading_progress.updated_at),没读过的书排在后面、按入库时间新到旧, 所以它和另外三个一样由服务端排序、服务端分页。它曾经按书行的更新时间排——那个时间 在改元数据、换封面、书源更新章节时才动,读书不会动它——结果是读完第二本书回到书架, 「最近阅读」的顺序纹丝不动。离开阅读器时先把进度推上去再重读书架(ReaderPage), 顺序才会是刚读完的那本在最前。
同一个 SortKey 还决定了「离线时怎么画」:服务端排序离线时画的是镜像里的全部,
客户端排序离线时画的是同一段切片——两边的页数才对得上同一个翻页器。
文件管理页的每一个控件都写服务端的磁盘:上传、重命名、移动、删除。所以它只给管理员, 而且是两层,不是一层:
-
入口。 书架的「书库」按钮打开的是浏览页——那是一个读者的按钮。文件管理页 的入口只在浏览页的头部,写着「文件管理」,是一个带文字的控件而不是一个裸图标: 读者需要知道按下去会离开书、进入一个能删东西的页面。
-
路由。 判定在路由组件
LibraryFilesPage,不在按钮上。URL 是用户输入——它从书签、从聊天 消息、从手写的链接过来——藏起一个按钮只是对读者的提示,路由组件里那一句才是 检查。不是管理员却打开#/library/files?path=科幻,落到的是同一个文件夹的浏览页, 而不是一个错误页:书库是允许他去的地方,链接说的那个文件夹就是链接真正要说的东西。 -
成员的上传。 成员没有文件管理入口;业务设置「书库 → 允许成员上传书籍」开启时(默认开启, 客户端从
GET /library/upload的allowed得知),浏览页头部的位置换成「上传书籍」:传到当前 文件夹,重名保留两份(rename)。服务端只收书籍格式、不解包压缩包、不允许覆盖 (见 APIPOST /library/upload),跳过的文件在结果提示里说明原因。上传只新增 书籍,不改动已有文件,所以它不算文件管理。设置关闭时头部没有这个按钮,空书库的提示改为 「书库的书由管理员添加。」
角色在进应用时从 GET /api/v1/auth/me 读一次,没读到之前一律按非管理员算:
「还没问」不能是一段「成员也能打开删文件那个页面」的时间窗。后端仍然是每一行的
权限判定(那个页面上的每个端点都会拒绝),客户端这一层只保证不给他建那个页面。
「移动」的目的地是走出来的,不是打出来的:FolderPicker(web/src/features/library/components/FolderPicker.tsx)
从条目所在的文件夹打开,面包屑和文件夹行逐级进出,答案就是当前显示的文件夹(「移动到这里」)。
条目已经所在的文件夹、只读文件夹不能作为目的地,正在被移动的文件夹不能进入。
两个列表都分页,页是 URL 的一部分,翻页器在列表下方。
书架原来是在滚到底时追加一批(loadMore)。它有两个问题,而且都不是「体验」问题:
列表没有读者能看见的长度,位置也回不去——关掉再打开从第一屏开始,因为「我在第三屏」
只存在于一个滚动偏移里,而重绘会把它扔掉。两千本书是一个地方,地方需要有位置。
#/shelf?page=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 会回到那个被赶走的空页。
翻页是导航,不是本地改数字。 屏幕不自己改页码:它把页码写进 URL 查询参数
(setSearchParams),再从 URL 读回页码去请求。这一趟往返就是页能活过 Back、Forward 和刷新的全部原因。
翻页器也照此画:aria-current="page" 标当前页,两端禁用而不隐藏,页码窗口是
「首、尾、以及当前页的邻居」——50 页在手机上是一排需要读而不是按的按钮。
书库页存在的理由就是回答「我的书去哪了」,所以它必须能说出「这本书不在你的书架上」。 这件事曾经没有,那就是 #40 报的「书库的书不再自动加入书架,需要手动加入」的第一层:
add没有清掉hidden。 服务端把add写成了INSERT OR IGNORE, 而被拿掉过的书已经有一行user_books(remove为了可逆写下的hidden = 1), 于是OR IGNORE跳过它、书继续不在书架上。读者选中它、点「加入书架」、 什么都没发生。可逆性只存在于表结构里而不存在于端点里,就不是可逆性。 现在add/unhide是 upsert:不存在则插入,存在则清标志。- 书库不显示书架状态。
BrowseEntry.shelfState是按调用者解析的字段 (§3.4:书库说的是「你的书架有没有」)。只在"off"的行上画徽章: 给一整个目录的书都画「在书架上」是用一列噪音盖住唯一一行例外, 而例外正是读者来这里找的东西。
这个徽章留下了,那个按钮没有(#40 的下一轮:「书库管理页面去掉 从书架拿掉 按钮」)。 区别不是妥协,是这两件事不同的归属:
- 徽章是「答案」,而这个屏幕的职责就是回答「我的书去哪了」。一条不说自己不在 书架上的行,就是这个屏幕什么都没说。
- 按钮是「写入」,而它写错了地方。 文件页上其他每一个控件(上传、重命名、移动、
删除、改资料)改的都是挂载盘上的东西;
下架改的是一行user_books, 一个文件都不动。它因此是这个菜单里唯一一个后果和这一页的承诺对不上的条目, 而它挨着的就是「删除」。它还答错了人:这一半是管理员的(§3.4.4 路由按角色守), 而书架是每个读者自己的。
所以文件页现在只写盘。两个方向都搬到了读者站的那一屏上(§3.5.2 / §3.4.1)。
书架是每个读者每天打开四十次的那一屏,所以方向落在封面自己上 (#40:「补全完善书架的加入、移除逻辑」):
- 每张封面右上角一个「⋯」,点开是这一本书的动作:标记想读/在读/已读、清除标记, 以及「从书架拿掉」(§10)。即使只有「从书架拿掉」一条它也该是菜单:入口才是「这个方向存在」 的证据,而在每张封面上直接画一个「从书架拿掉」按钮,是在读者想打开书的那根手指下面放一个破坏性控件。
- 它是图标按钮,不是滑动、也不是长按。 书架是纵向滚动的,横向手势跟它所在的
滚动抢事件;长按没有任何可供性——文件管理页的行也是同一条理由,用的是
⋯。 - 先问,再写。
remove是两个方向里唯一拿走东西的那个,也是读者最容易误读 后果的那个。确认框里写的是读者真正在问的那句话:磁盘上的文件一个都不会动。 - 写入之后重读这一页,而不是本地删掉那张卡片。 列表是这次动作的答案,
而只有服务端知道书架现在有什么;本地删卡会让计数、页码和离线镜像三方各说一套。
消息
从书架拿掉 N 本在刷新之后通过全局浮动提示显示,目录摘要继续展示书籍数量。
写入带的是 book.id,不是路径。 这是 #40 报的「从书架移除时,找不到「xxx」
在磁盘上的路径」的根因,而它值得单独说,因为错的那个方案看上去更直接:
卡片手里只有一本 Book(一个 id、以及扫描器记下来的东西),而端点当时收的是
路径。两者之间隔着一个 join,客户端是这么补的:列出书库根目录的第一页,
拿书名去和文件名对(去掉扩展名)。这个猜测有两处必然失手:
- 书名不等于文件名,而这是常态而不是例外——扫描器会从文件里读出书名。 报告里的那本书叫「半小时漫画宇宙大爆炸(半小时读完138亿年宇宙史,一口气搞懂大爆炸、 奇点、黑洞、引力波、暗物质……混子哥陈磊新作!)」,磁盘上那个文件不叫这个, 于是什么都没有匹配上。读者被告知这本书找不到——在他要求把它从自己的书架上 拿掉之后,而那是文件叫什么名字完全无关的一件事。
- 列表是分页的,所以根目录第一页之外的书、以及任何子目录里的书, 在那次查找里根本不存在。
映射其实已经在服务端了(book_files.book_id → rel_path),客户端一直在猜一件
服务端已经知道的事。现在写入带 id,服务端按 id 解析路径:书名和文件的位置都不再参与。
端点两种命名只收一种(paths 与 bookIds 同时给会被拒)——两份命名说的是同一个写,
同时带上就是「客户端自己不知道该说哪一个」,合并还会让同一本书被写两次、被数两次。
浏览页(§3.4.1)用的是同一对方向,也带 id,所以同一本书从书架还是从书库下架, 发出去的是同一句话。文件页两样都不用了(§3.5.1)。
一张卡片一旦带上第二个动作,它就不能再是一个 <button>:<button> 里套
<button> 是非法结构,浏览器对它的处理是把内层搬到外面,那是一种没人设计过的布局。
所以卡片是容器,.book-open 是打开目标,.book-more 是它的兄弟。
配套的两条,都在 ui:review 里有断言:
.book-more的命中区不小于 28px(§3.3)。画在封面右上角的字形,正是手指 最容易按空的那种控件。- 打开区仍然覆盖整张卡。放大字形不能吃掉读者用来开书的那块面积,所以两条 一起量:字形够大,而且打开区没被挤小。
- 静止不透明度 0.55,且始终可聚焦。 只在 hover 时出现的控件在手机上等于不存在,
display: none的控件连键盘和读屏都够不着。@media (hover: hover)里才允许它 完全隐形——有指针的宿主才有"先划过再点"这回事。
两屏的动作文案来自同一个地方(shelf-membership.ts),因为它们是同一个问题从两端问:
加入书架 N 本 / 从书架拿掉 N 本,而不是批量口径的「已更新 N 本」——读者按的是
加入书架,他想知道的只有那本书动没动。applied 为 0 而 failed 非空时,句子说的是
「N 项不是书库里的书」:一个看起来能按的按钮配上「0 本」就是「这个按钮坏了」的来源。
登录、书架、书库、文件管理、阅读、书源和扩展页面的操作反馈统一使用 Notyf。
web/src/ui/notifications.ts 提供全局 notify / dismissNotice 接口;状态驱动的组件
使用无 DOM 输出的 FloatingNotice 适配器,页面不再各自创建提示条或消息计时器。
全局容器固定在视口底部并避开安全区,宽度随内容变化,最大 28rem,手机两侧至少留 1rem。
最多同时显示三条;加载提示持续显示,进度原位更新;普通提示默认 6–12 秒后消失,也可手动关闭。
成功、错误和加载共享主题样式,错误使用 alert,其它消息使用 status。
服务端返回的文案均按纯文本显示,不执行 HTML。
容器和消息正文不拦截点击,关闭按钮可以操作,避免提示挡住阅读按钮。原生弹窗打开时,同一个容器移入弹窗的顶层,
关闭后回到 body;消息不抢焦点。所以在 Sheet 里触发的操作(例如书源结果的「加入书架」)也用 Notyf 报结果,
不在 Sheet 背后的页面上写内联提示——那样读者看不见。提示出现、更新和关闭不得改变内容区尺寸或滚动位置,
这些行为在手机和桌面 Chromium 中验证。数量摘要、搜索统计和操作说明继续作为页面内容展示。
所有设置、编辑表单、选择列表、详情和确认框都用 web/src/ui/sheet.tsx 的 Sheet
(确认框是 ConfirmSheet),样式只在 web/src/styles/sheet.css。不再使用居中弹窗、
SweetAlert、Mantine Modal、自绘遮罩或角落浮动卡片。
唯一的例外是图片查看器(web/src/ui/image-viewer.tsx,§3.10):它要占满整个窗口并且能向任意方向拖动,Sheet 是页面旁的面板,做不到。它仍是原生模态 <dialog>,顶层、背景惰性、Esc 和焦点归还与 Sheet 一致。
| 视口 | 形态 |
|---|---|
| ≤700px | 底部 Sheet:圆角顶边、把手。普通 Sheet 固定高 min(80dvh, 视口减顶部安全区),内容在 Sheet 内部滚动;compact 高度随内容(到上限后同样内部滚动);阅读器内普通 Sheet 固定 min(62dvh, …)、最高 36rem,compact(注释、确认)仍随内容。独立窗口 PWA(data-host="pwa")里普通 Sheet 从视口 20% 处铺到底 |
| ≥701px | 右侧抽屉:距边 1rem,宽 30rem;size="wide" 宽 42rem 给复杂表单 |
≥701px,size="compact" |
确认、单行输入、短选择列表:跟手,出现在触发它的点按位置或聚焦控件的下方(放不下则上方),宽 24rem,始终留在窗口内;找不到触发点时回到右上角 |
- 原生
<dialog>+showModal():顶层、背景惰性、焦点限制在内部,关闭后焦点回到打开它的控件。 - 三个出口始终相同:标题栏 ✕(「关闭」)、Esc、点背景;
busy时三者都禁用。手机上还有第四个:往下拖。 - 手机上可以拖(
web/src/ui/sheet-drag.ts):按住把手或标题栏(标题栏里的按钮除外)。往下拖过自身高度的 三成、或往下快速一甩,就关闭(和 ✕ 同一个出口,busy时弹回);普通 Sheet 往上拖过一半、或往上一甩,展开到 几乎整屏(data-expanded,顶部留出状态栏),展开后往下拖或往下甩先回到原来的高度,要再明显往下拖才关闭;compact只能往下拖关闭。手指跟着走、松手后动画落到 CSS 给的高度;减少动态效果时直接落位。正文区域不响应拖动, 里面的滚动照旧。宽窗口(抽屉、跟手的 compact)不拖。 - 就地渲染、不走 portal,所以继承打开它的页面主题(阅读器黑白灰、影音别名)。
- 调用方的
className只管内容样式,不得设置位置、尺寸、圆角、背景遮罩或标题栏。 - 确认框焦点默认在「取消」;破坏性操作传
danger,按钮用危险色。 ⋯操作菜单和单选筛选(收藏类型等)用web/src/ui/action-menu.tsx的ActionMenu:从触发按钮下方弹出的下拉菜单(手机和桌面一致),没有标题栏和遮罩,选中、Esc、Tab 或点外部即关闭,支持方向键;样式在web/src/styles/action-menu.css。需要以问题形式出现的单选(书架的选择对话框)用ActionSheet,即 compact Sheet 里的同一列菜单项。动作是数据(label、onSelect、danger、checked、description——条目下的一行说明,经aria-describedby读出),菜单先关再执行动作,所以动作可以再开一个 Sheet 或跳转。不再使用 MantineMenu或<details>下拉。- 章节书的目录:条目带
volume时,在该卷第一章上方画一行卷标题(.toc-volume,不可点、不计入章节数);带note时在章节名下显示一行小字(.toc-note,如更新时间)。 - 书源页的“发现”是单独的标签页(
features/sources/components/SourceExplore.tsx),有可浏览的来源时才出现,不再和搜书共用一块区域。一个页面是一层:面包屑是走过的层级,点任意一级返回;下一层的分组、书源、分类画成可换行的圆角按钮,超过 16 个时出现筛选框;书籍是带封面的列表,来源给出nextCursor时底部有“加载更多”,追加而不是翻页。返回和翻页由页面负责,来源只描述当前这一层。本地书库也在这里:一页是一个文件夹,子文件夹是下一层,文件夹里直接放着的书是列表,封面经同一个封面接口读取。 - 来源封面用
ui/lazy-cover.tsx的LazyCover:进入视口后才经 API 取图,固定 3:4 占位。搜书结果每本书显示第一个带封面的书源的封面。书架上每本书的 ⋯ 菜单都有“更换封面”,打开ui/change-cover-sheet.tsx,列出书源中有封面的版本,点选即保存。来自书源的书(format: 'chapters')按书名和作者在其它书源中查找;本地书在读者选的书源库里按书名搜索,只列出书名相同的结果,并可“恢复文件自带的封面”。 - 锚定在控件上的只有
ActionMenu下拉、选择框(MediaSelect、SearchableSelect)和正文选区工具条,它们不是 Sheet。
以下是阅读器面板最初改成底部半屏的理由,仍然适用于手机形态:
目录和阅读设置是从底部升起的半屏面板,带遮罩和把手,上半屏仍然看得见 正文。
之前的做法是 inset: 0 的全屏页,把书完全盖住。全屏对一个目的地是对的,
对一个控件是错的:选章节、调字号都是对下面那一页的调整,全屏让读者为了做
调整而离开那一页,回来时排版已经变了、他也没有了对照。
三条配套,都不是装饰:
- 遮罩:没有遮罩的面板读起来像是页面的一部分。它同时也是「点一下关掉」 的命中区,也就是除 ✕ 之外的第二个出口。
- 把手:从底部升起的面板被理解为可拖拽的,所以它真的能拖:往下关、往上展开 (见上面「手机上可以拖」)。画一个做不到的把手比不画更糟——以前它只是视觉线索, 读者试着拖却没反应,现在把手和标题栏就是拖动的手柄。
- 高度:手机上是固定高度,不随内容:普通 Sheet
min(80dvh, …),阅读器内min(62dvh, …)且不超过 36rem。随内容的高度在部分移动 WebView 里会让 Sheet 内部滚动失效(一千二百章的 目录滚不动),所以只有compact(确认、单行输入、短列表)仍按内容定高。
面板打开时它拥有点击:旁边露出的那一条正文不翻页(§3.8 的优先级)。
一次触摸只属于一个目标,最里面那个赢。ui/gestures.ts 是这条规则的唯一实现,
顺序是:
- 读者按到的是控件(链接、按钮、输入、滑块)→ 控件拿走这次手势,不翻页;
- 面板开着 → 面板拿走(点遮罩=关闭,不是翻页);
- 否则拖动是滑动翻页;
- 否则短按落在点击区里。
点击区域是版心上的 3×3 九宫格,每格一个动作:上一页、下一页、菜单(显隐工具栏)、
上一章、下一章、无操作(ui/tap-zones.ts,设置项 tapZones,按设备保存)。默认等于原来的
「左退右进」三列;旧设备上存的 tapZone: 'reversed' 升级后变成对应的九宫格。设置在
「阅读设置 → 翻页 → 点击区域」,以一张缩小的页面呈现,点格子从菜单里选动作,另有
「左右互换」「恢复默认」。两条规则:
- 至少保留一格「菜单」。最后一格菜单不能改成别的(菜单里说明原因),存储里没有菜单的 九宫格读出时中间格补成菜单——否则工具栏和这个设置本身都再也点不出来。
- 九宫格按从左到右的书描述,从右到左的书左右镜像,与原来的左右互换开关同一条规则。
翻页和换章会顺手收起正在显示的工具栏;无操作什么都不做,也不收起。
翻页模式下页面跟手。 手指明显横向移动(超过 12px 且横向大于纵向)后,
ReaderView.beginDrag 开始让分栏带的 scrollLeft 跟着手指走,看到的就是真正的下一页;
松手时由 onRelease 决定:快速划过(≥48px 且 <800ms)或拖过页宽 30% 就滑到相邻页,
否则弹回原页,两种都从手指离开的位置继续滑完(约 200ms,翻页动画为「无」或系统要求
减少动效时直接到位)。本章没有那一页时立即复位,交给普通翻页去开下一章。跟手期间
snapStrayScroll 不吸附。鼠标拖动仍是选字;滚动模式的纵向拖动本来就是浏览器滚动;
固定版式(漫画)和从右到左排版不跟手。onRelease 返回 true 表示这次手势已由拖动
处理,不再当作滑动或点按。
影音分类的横滑(shared/ui/use-swipe-tabs.ts、swipeCatalogTarget)按分类一格一格走,
到两端停住,不循环。某个频道一个媒体库都没有时,它的分类页都是同一个空页、也不显示
分类标签,逐格滑看起来像没反应,所以改为按频道走(MediaPageFrame emptyChannel)。
频道由路径决定(useMediaChannel),静态路由(audiobook/narrators)也一样;
「演播者」是有声书的第二个分类,和「有声书」同级,保留底部导航栏。
书架的「全部 · 在读 · 想读 · 已读」用同一个 useSwipeTabs 横滑切换。
有三个坑是文档级别的,改这块之前必须先知道:
- 必须用
composedPath(),不能用event.target。 书的正文在 shadow root 里,而 shadow 边界会重定向事件:点正文里的<p>,监听器看到的 target 是 shadow host。用target写不出「段落」和「同一个 shadow 树里的按钮」的区别。 - 阅读面自己是个滚动容器。滚动模式就是让 shadow host 滚起来。所以 「可滚动的祖先拿走手势」这条规则必须排除它——否则它吃掉每一个手势,每一次 点击都归属某个滚动容器,翻页层级正确但永远到不了。这一条是 2026-09 那轮 「点击页面没反应」的真正原因。
- 点击区是布局几何,不是视觉几何。
getBoundingClientRect()和event.clientX都在视觉视口坐标里,两者相减得到的是视觉距离;而点击区是 版心宽、高的三等分,用的是布局像素。页面被捏合放大(或任何祖先变换)时 两者不相等,误差可以超过判定阈值的一半——读者点中间三分之一想收起工具栏, 结果翻了页。所以宽度取offsetWidth,偏移按两个盒子的比例rect.width / offsetWidth换算回布局空间;无变换、无缩放时这个比例正好是 1,那一行是恒等 变换而不是一次单位转换。
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,否则正文会变成第二章 落雨雨来了。)。 分段之前先过cleanTextMarkup:从网页另存的 TXT 常带着<div>、<br/>、 ,原样转义就会把标签画成文字、每个<br/>行都成一段空白。块级标签 (br/p/div/标题/列表项)换成换行、行内标签(span/font/b…)去掉、 常见实体解码、只有空白的行算空行;只认真实的标签名,正文里的a<b、<书名>不动,其余标签照旧转义成文字。 书源(format: 'chapters')的text/html章节是抓下来的网页片段(<div>…<br><br><br>)。 清洗由插件按书源声明的类型决定(bookSourceType:文本源整理成段落,图片/漫画源原样保留)。 阅读器只负责排版:只含文字和换行的章节在读取时(readStagedSection)用htmlToText读回成字符、标成纯文本,走同一套分段和缩进;含图片(漫画章节都是)、表格、媒体的章节保留标记。 在读取时处理,所以服务端早先缓存的章节也会被清洗;EPUB 不会进入这条路径。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 读者打回第一章。
读者报的是「图片缺少样式,移动端显示溢出了」——一张 1400px 宽的插图在一栏 342px 的版心里画出来 1400px,两头都出了屏幕。它属于这一类:没有任何断言覆盖 过它,因为 UI 评审的插图 fixture 只有 240px 宽,塞得进版心,于是评审一边说 「插图能画出来」一边让真实的缺陷完全复现。
所以有一条独立于书的样式表(web/src/ui/shadow.ts 的
CHAPTER_CONTENT_STYLESHEET),它只声明作者自己也会声明的那些属性,并且
位置在书自己的样式表之前——同优先级下后写的赢,所以作者写
img { width: 60% } 仍然有效。三条规则,各有各的理由:
- 图片收进版心:
max-inline-size/max-width取min(100%, …),height: auto。只夹宽度会让图压扁,这是修第一个数字时最容易引入的缺陷, 而它在截图里看不出来(对角线的角度变了但你没得比);auto才保住原比例。 另外给max-block-size,否则一张竖图会把图注挤到下一页,两者一起变得不可读。 - 居中显示:
display: block+margin-inline: auto。行内图片坐在文字基线上, 底下会多出降部那一截行距;block也是「比版心窄的图居中」这条能成立的前提。 - 没有尺寸的图片留出比例:
aspect-ratio让章节目录在图片到达之前就有正确的 高度,否则读者正在读的那一段会被一张还没加载完的图往下顶,位置就丢了。
§3.9 的 TXT 排版走的是另一条路(.txt-body,只挂在纯文本上);这一节管的是
所有格式的章节内容,包括 EPUB 里作者自己写的标记。
- 顶部:返回、书名、当前章节。
- 底部:上一章、本章页数滑杆、下一章;下一行是工具(书内搜索、笔记与书签)、目录、朗读、外观、设置。朗读进行中时“朗读”按钮显示“朗读中”(按下态),因为关掉朗读面板不会停止朗读。
- 滚动模式下手动滑到章末后,从章末开始继续上拉(触屏超过 72px,或滚轮在章末继续滚动)进入下一章;在章首下拉回到上一章。手势必须从边缘开始,只是滑到章末不会翻章;翻章后有约 1 秒冷却,滚轮惯性不会连翻两章。
- 中间滑杆控制本章页数,不能变成全书进度。例外是漫画:它每“章”就是一页,本章页数恒为 1,所以滑杆改为全书页码(“第 7/200 页”),拖动时只更新标签,松手才打开那一页。
- 「书籍信息」(点顶部书名)末尾是「阅读记录」:本账号在这本书里去过的位置,最新在前,每条写章节、进度、设备与相对时间;当前位置标「当前」且不可点,点其他条目回到那里并成为新的保存位置。离线时说明无法读取,读取失败给「重试」。
- 书打不开时(服务端错误、未缓存的离线书),舞台上一直显示原因和“重试”“返回”,不只弹一条会消失的提示。直接打开阅读链接、没有上一页时,“返回”回到书架。
- 键盘:方向键与 PageUp/PageDown 翻页,空格/Shift+空格翻下/上一页,
[/]上一章/下一章,S 开始或暂停朗读,T 打开目录,F 打开工具(书内搜索、笔记),B 为本页加或移除书签,选中文字后 H 直接高亮,专注模式下 ↑/↓ 逐段移动,Esc 收起工具栏;右→左的漫画方向键随方向镜像。字母键不分大小写,带 Ctrl/⌘/Alt 时留给浏览器,输入框内和弹层打开时不响应。焦点在按钮上时空格和回车只按下那个按钮。 - 图片查看:在可重排的书里点一张图片(屏幕上短边 ≥48px,或短边 ≥24px 且长边 ≥120px;更小的是文字里的图标、分隔线,仍按普通点击处理;链接里的图片归链接),全屏打开,深色底。图片按窗口等比放到最大(小图最多放大 3 倍)。左右拖动切换本章的上一张 / 下一张,到头回弹;双击 / 双指 / 滚轮以触点为中心缩放(1–6 倍),放大后拖动平移,不会拖出图片边缘;点图片以外的区域、✕ 或 Esc 关闭。键盘 ←/→ 切换,
+/-/0缩放。左上角显示「2 / 5」,只有一张时不显示;左右箭头按钮只在有鼠标的设备上出现。漫画的一页就是整屏,点击仍是翻页,所以改为长按当前页打开同一个查看器(只有这一页,不显示计数;Android 原生绘制的页面在查看期间先撤下,关闭后重画;触屏上屏蔽浏览器自带的图片长按菜单)。PDF 不提供。 - 专注模式(可选,默认关,按设备保存):「设置」里与「翻页方式」同样式的一行两段选择(关/开;不叫「关闭」,那是弹层关闭按钮的名字),只在滚动模式的可重排书籍中出现。开启后正在读的段落之外盖一层半透明的纸色,不改书的样式。焦点线停在视口 40% 高处,章首从顶边出发、章末到达底边,所以第一段和最后一段都轮得到;章节一屏放得下时不遮。键盘 ↑/↓ 逐段移动(关闭时方向上下键不归阅读器)。翻页模式、漫画和 PDF 没有此模式。
- AI 选区助手:服务端启用后,选区工具条多一个「问AI」,打开普通 Sheet「AI 助手」:引文、「翻译」「解释」两个按钮、一个提问输入框(≥16px)和一个当前回答——新的请求替换旧回答,不做对话列表。请求进行中 Sheet 仍可关闭;失败在回答处说明原因。底部固定一行说明文字会发送到哪里。未启用或旧服务端不显示入口。
- 脚注:点正文里的引用标记(上标、
[1]、①等),注释在 compact Sheet「注释」里原处显示,正文位置不动;「跳到注释处」才真正过去。注释在另一章(书后注)时同样原处显示。不像注释的链接(指向小节、注释回正文)直接在书内跳转。弹层只显示文字。判定规则见architecture.md「脚注在原处读」。 - 顶部左/右、底部左/右阅读信息可在“外观”分别选择书名、章节名、章节进度(章内页码与全书百分比)、时间或不显示。默认顶部左侧章节名,底部左侧章节进度,底部右侧时间。配置按设备保存,工具栏隐藏后仍显示;长文本省略。关闭信息仍保留固定边界,避免改变正文分页。日夜圆形快捷按钮随工具栏一起显隐。
- 正文宿主的上下边界不依赖工具栏状态。工具栏覆盖正文,显隐不得改变页码、滚动位置、正文尺寸。
- 每页底部不出现被切掉一半的行。滚动翻页模式下,页高先按行高取整(
--reader-page-trim,整章一个值,页数由它算);但段间距和标题会让后面的行偏离这个网格,所以每翻一页还要把底边切过的那一行用clip-path遮住(--reader-page-mask,ReaderView.syncPageMask)。下一页从这一行的行首开始,不会漏字。遮罩不改变clientHeight,所以页数和翻页位置都不受影响;翻页动画期间不测量(行框还带着translateY),动画结束后再测。 - 四个面板使用统一底部半屏布局;外观放排版与主题,设置放翻页行为,朗读放语音设置和播放控制。
- “设置”面板首屏是换书时会改的几行:翻页方式、翻页动画,以及只对部分书出现的图片适配、翻页方向。“点击区域”(九宫格,摘要写“默认”或“已自定义”)和“电纸书预设”是设一次就不再动的,收进默认折叠的区块。
- “外观”面板按使用频率排序:纸色(跟随主题、白纸、暖黄、浅绿、灰调、夜间)、字号、行距、主题(阅读主题:“跟随应用”或黑白灰,用各主题真实的底色与墨色绘制的色块)、明暗(跟随系统/浅色/深色)、亮度排在首屏;“更多排版”(页边距、对齐、字体,以及 TXT 的缩进、段间距、编码)和“页眉页脚”(四个阅读信息)收进默认折叠的区块。漫画不显示文字排版,只保留主题、明暗、亮度和“页眉页脚”。
- 纸色是阅读页单独的设置(
AppSettings.paper,按设备保存,与字号一样),只改页面的底色、文字和页眉页脚(.reader-screen[data-paper]覆盖--reader-paper/ink/muted/line),工具栏和面板仍用阅读主题。夜间纸色让阅读器整体变深;浅色纸色在应用为深色时默认让位给主题的深色取值,可在“跟随系统深色模式”开关关掉。外观与主题页也提供同一设置。V3 之前的 sepia/green/dark 页面主题首次读取时迁移成暖黄/浅绿/夜间。 - TXT 默认字号为基准的 1.125 倍、行距 1.8,支持两字缩进与段间距;EPUB 默认保留作者排版。
- 阅读主题默认“跟随应用”;也可选阅读专用的黑白灰,只写在阅读器容器上(
data-theme="gray"),浅色和夜间跟随应用的明暗。日夜快捷按钮把明暗设为浅色或深色(离开“跟随系统”),保留当前应用主题。电纸书预设使用黑白灰浅色。漫画隐藏文字排版选项。
朗读控制集中在朗读面板,朗读中时面板顶部是一张播放卡片:第一行是正在读的句子,其下是与页码滑杆同款的进度滑杆,再下一行是等宽的五个控件。上一句、播放/暂停(主色)、下一句、句数(点它从当前页重读)、停止均有独立按钮;关闭面板不停止播放,再从底部“朗读”进入可暂停或停止。 “从当前位置朗读”使用当前可见正文或选区作为起点,是面板里的第一项和唯一主按钮。其后依次是语速(滑杆加 0.8/1.0/1.2/1.5/2.0 常用档)、语音、章节播完;音调与音量收进默认折叠的“更多”。不可用的语音设置根据引擎能力隐藏。
- 中文,句末不加句号(
我的书架、正在刷新)。界面文本不是段落。 - 说清楚发生了什么,而不是说「出错了」。
已更新 2 本、这一章暂时无法跳转、连不上这个地址。确认服务端已启动,且地址包含端口。 - 失败的那句话走
describeError(web/src/api/errors.ts)。 服务端为界面写的中文原样显示; 传输层和反向代理的诊断(request failed with status 502、Failed to fetch、no route for GET …) 不是写给读者的,换成「这是哪一类失败」的一句话。页面不要直接渲染error.message。 - 不承诺不能兑现的事。 只读挂载上不显示上传按钮(用
hidden而非不渲染, 见 §5),而不是显示一个按了会 403 的按钮。 - 空状态给一条出路。 空书库不是「这里什么都没有」,而是「打开书库 / 刷新」两个按钮;搜不到结果是「清除搜索」。
- 搜索框说出它的范围。 只有一个「搜索」:侧栏(桌面)和搜索页的全局搜索,
搜索书籍和影音,同时查书库和有权访问的影音库。页面里的输入框都是范围内的: 书架是在书架中筛选…(结果标题「筛选结果」),书库是在书库中搜索…。 桌面上全局搜索与书架筛选同屏,两个都写「搜索书名、作者」时,读者无从知道该用哪个。
| 状态 | 用法 | 反例 |
|---|---|---|
| 禁用 | disabled + opacity: 0.55 |
隐藏按钮,让读者以为功能不存在 |
| 不可用(权限) | hidden |
隐藏整个区块,让读者不知道这里能管理书库 |
| 忙碌 | 按钮文案变「正在切换…」,控件 disabled |
只留一个转圈,读者不知道在等什么 |
| 无能力 | 不渲染该行 | 显示一个按了没反应的滑块 |
最后一行值得展开:朗读设置面板在 HTTP 引擎下不显示音调那一行,因为
<audio> 根本没有音调。而不是显示一个拖动无效的滑块。
hidden 而非不渲染的那一条同样是刻意的:能做的和不能做的区别本身就是
信息。全部藏起来,读者学到的是「这个应用的按钮时有时无」。
主题体系见《Reader V3 主题语义令牌》(v3.1):暖陶(默认)、雾蓝、青绿三个应用主题,加阅读专用的黑白灰,每个都有浅色和深色两套取值。
- 组件只读
--color-*语义令牌(web/src/styles/theme-tokens.css)。<html>上的data-theme与data-mode选中一套取值;一个容器可以带自己的这对属性而穿另一套主题(阅读器的黑白灰、视频和音乐播放页的深色沉浸)。 brand和ch-*只作填充,上面的字用on-brand/on-ch;品牌色的文字、链接、选中图标用brand-text(旧名--reader-accent、--media-accent),填充用--reader-fill/--media-fill。选中的标签和分段控件用brand-soft底加brand-text字。- TypeScript 镜像在
web/src/shared/theme/theme.ts(预览色块、对比度);test/theme-tokens.test.ts保证两边取值一致,并按规范 §5 的组合检查 8 套配色的对比度。新增或调色时两边一起改。 - 偏好按服务器和账号存在本机(
reader.theme.v2:<scope>):应用主题、明暗(跟随系统/浅色/深色)、跟随系统时浅色和深色各用哪个主题、阅读主题。第一次读取时把 V3 的六套主题按规范 §8 迁移(蔷薇回落到暖陶并保留浅色)。 - 主题只改界面的颜色。书的颜色由书自己决定——一个硬编码
color: #333的段落,在暗色主题下保持它自己的颜色。这是正确的取舍: 暗色主题悄悄破坏一本印刷取向的书的对比度是缺陷,而一本书在「暗色」背景上 显示深色文字,是读者能看见并自行判断的。 - 亮度是
mix-blend-mode: multiply的覆盖层,不是调色板。换主题应该保留 纸与字的对比关系;直接改颜色会把文字一起压暗——那正是「亮度」滑杆最常见的 失败方式。 - 新增颜色一律走令牌。危险色已经是令牌:
--color-danger/--color-danger-soft(theme-tokens.css,只分浅色和深色,不随主题变)。reader.css里还剩两条规则直接写#c0392b,是已知例外,应当在下次改动时换成--color-danger。
功能测试验证交互和数据,UI 评审验证真实页面在目标视口中的布局、可见性和溢出。两者使用同一份生产 Web bundle,但关注点不同:功能测试不能代替截图检查,截图也不能代替可自动断言的尺寸检查。
当前入口是 npm run ui:review。它运行 web/tools/ui-review/react-app.mjs,用真实 Chromium 加载构建后的 React 应用,覆盖登录、首页、搜索、书架(含深色)、书库、书源、设置和影音页面的移动端与桌面端场景。默认产物写入被 Git 忽略的 artifacts/ui-review/react-app/,包含场景截图和 verification.json。
verification.json 是 CI 读取的机器结果。提交或排查 UI 改动时,先检查 passed、页面错误、横向溢出和场景列表,再查看对应截图。截图数量随场景变化,不在文档中固定写死。
阅读器和书源的专项检查仍可单独运行:
npm run ui:review:reader --prefix web:阅读器舞台、面板、翻页和窄屏场景,输出到artifacts/ui-review/reader/;npm run ui:sources --prefix web:书源页面与扩展流程,输出到artifacts/ui-review/sources/。
这些脚本只生成临时评审产物,不要把截图或报告提交到 docs/。CI(.github/workflows/ci.yml)的 ui-review 任务在每次 CI 都对 Web 任务构建出的 bundle 运行 ui:review:only,并把 artifacts/ui-review/react-app/ 上传为构建产物。
- 新颜色 / 新间距 / 新时长 → 先看
:root里有没有,没有就加令牌, 不要在规则里写字面量。 - 新图标 → 在
web/src/ui/icon.tsx的ICONS里加一个名字映射到 Lucide 图标,名字用这个项目 自己的英语词(不许借别的图标集的名字,test/icons.test.ts会拒),然后用Icon/IconButton引用名字。 已有意思相同的名字就复用,不要为同一个意思再加一个字形。 - 新控件 → 确认它出现在 §2.4 的焦点选择器列表里。
- 新动画 → 用
--motion-duration和--motion-ease,不要自己写时长。 - 有状态变化的控件 → 对照 §5 那张表,确认用的是对的那一种。
- 图标按钮 →
label必填,且这条 label 是这个按钮自己的作用, 不是它所在的区块的名字。 - 图标 + 文字并排 → 用
IconTextButton,不要自己拼一个<button>加一个<span class="icon">;图标加文字正是最容易歪的组合,而它每次歪的方式都 一样(字形落到文字基线上)。 - 动布局 → 跑
npm run ui:review,并且看截图。 断言只覆盖已经量过的那些 规则;新缺陷的第一道防线是眼睛。- 给绝对定位的字形居中时,量墨迹(
Range.getBoundingClientRect()), 不要量盒子——盒子居中而墨迹不居中的缺陷能活过一轮「盒子看起来在中间」的检查。
- 给绝对定位的字形居中时,量墨迹(
- 加一条能一直看着的断言,如果这条规则是能量出来的。下一个人不会看到 这次截图。
- 加一个列表页 → 页数由服务端给,页由服务端切,页是 URL 的一部分(§3.5)。 在客户端切好一页再丢掉、或把页码只放在组件状态里,都会在 Back、Forward 和 刷新这三件事上分别坏一次,而这三件事没有一条是功能测试会先撞上的。
- 动贴边的条(页头、底栏、侧栏、浮在底部的提示)→ 按 §3.1 用模拟安全区看一遍
竖屏和横屏。
ui:review不模拟安全区,刘海下的按钮在它的截图里是看不出来的。
| 路径 | 内容 |
|---|---|
web/src/ui/icon.tsx |
图标集:名称(IconName)到 Lucide SVG 的唯一映射,尺寸档与线宽 |
web/test/icons.test.ts |
没有借来的名字、只有 icon.tsx 引入 lucide-react、.icon 规则与图标按钮的契约 |
web/src/ui/toolkit.tsx |
IconButton / IconTextButton / Button / Segmented / Callout / SwitchRow / SectionTitle |
web/src/ui/action-menu.tsx / web/src/styles/action-menu.css |
每个 ⋯ 菜单的 ActionMenu 下拉,以及 ActionSheet(§3.7) |
web/src/ui/cover-tint.ts |
无封面占位的色相(§2.7) |
web/src/ui/book-grid-skeleton.tsx |
书架与书库加载时的封面网格骨架 |
web/src/features/shelf/pages/ShelfPage.tsx |
书架;排序、分页器与书库入口 |
web/src/features/library/pages/LibraryPage.tsx |
书库浏览、书籍列表和文件管理路由;搜索、面包屑、分页器、上传后重读 |
web/src/ui/shelf-membership.ts |
两个方向的措辞与批量报告那句话的唯一来源(§3.5.2) |
web/src/ui/sheet.tsx / web/src/styles/sheet.css |
唯一的弹层 Sheet 与 ConfirmSheet(§3.7) |
web/src/ui/dialog.tsx |
提问(文本框/确认/选择),基于 Sheet,书架与文件管理共用 |
web/src/ui/pager.tsx |
翻页器组件(§3.5),书架、书库浏览和文件管理共用 |
web/test/react-router-routes.test.tsx |
React Router 的页面、影音嵌套路由和权限边界 |
web/test/media-library-list.test.tsx |
媒体库列表、分页和空状态 |
web/test/media-library-editor.test.tsx |
媒体库编辑、权限和保存后的重读 |
web/src/ui/gestures.ts |
手势与事件层级(§3.8) |
web/src/shared/ui/use-swipe-tabs.ts |
书架与影音分类的横滑切换(§3.8) |
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) |
artifacts/ui-review/react-app/ |
当前 React 评审截图与 verification.json(生成,不提交) |
web/src/styles/reader.css |
令牌、组件样式、交互状态、prefers-reduced-motion |
web/src/styles/theme-tokens.css |
V3.1 颜色语义令牌、四个主题、--reader-* 别名、阅读纸色(§6) |
web/test/design-tokens.test.ts |
圆角与 24px 以下字号必须用令牌、:hover 必须在悬停守卫里(§2) |
web/test/theme-tokens.test.ts |
主题取值与 theme.ts 一致、对比度(§6) |
- 一个导航:手机底部四个标签(首页、书架、影音、我的),701px 以上改为左侧栏,影音下列出影视、音乐、有声书三个频道。取代旧的媒体频道栏。
- 导航按页面类型显示:顶层页面显示;详情、设置、书库文件等二级页面在手机上由自己的返回箭头取代底栏,桌面端侧栏保留;阅读器和播放页不显示。规则在
web/src/app/AppNav.tsx的navMode。 - 主题在应用壳层统一应用(
ThemeController写<html data-theme data-mode>)。登录页在应用主题之前显示,使用暖陶并跟随设备深浅色。书架、书库、书源、首页、阅读器的--reader-*是--color-*的别名(theme-tokens.css),影音页的--text、--media-*别名在presentation.css顶部。 - 频道色(阅读、影视、音乐、有声书)是每个主题自己的
--color-ch-*(填充)、-soft(卡片底)和-text(文字),由theme-tokens.test.ts守住对比度。 - 纯阅读模式:全站或当前用户关闭影音时,导航仅保留首页、书架、我的;首页、搜索、偏好、统计与管理入口均移除影音部分,不创建播放器或请求影音接口。管理员的服务配置与用户管理不受限制,旧影音链接显示未启用提示。以下影音交互仅适用于有效影音权限开启时,详见模块开关。
- 首页:「继续」一行把在读的书、未看完的影视和有声书画成同一种卡片(封面+作品名+集/章+进度,单集显示所属剧集名),最多两本书,按最近时间排序;然后是书架一行,最后是「看点什么」「听本书」「听张专辑」三行影音,各自可在「最近添加」(
browse?sort=added,按作品及其分集/曲目最新文件的修改时间)与「随便看看」(sort=random,可换一批)之间切换,选择记在本机;有内容才出现。我的页只做入口,不拥有任何设置。 - 我的页的每一行都打开一个页面,不在原地弹 sheet(唯一例外是退出登录的确认)。个人偏好只有一行「偏好设置」(
#/me/settings):外观与主题、书架、影音浏览、播放是同一页的四个标签,一次只显示一个,?section=选中标签(缺省为外观与主题),所有控件改动即时生效,不设保存按钮。书架页齿轮弹出的书架设置是这一分区的快捷入口,两处共用ShelfSettingsFields。管理员的用户管理、注册与邀请、服务配置各是一页(#/me/admin/*),与媒体库、扫描与刮削并列;外部阅读器(OPDS)在账号分组(#/me/opds)。 - “跟随系统”= 浅色时用的主题加深色时用的主题(默认都是暖陶),在外观与主题页指定;关掉跟随系统时保留屏幕上当前的主题与明暗,再选浅色或深色。读取与保存只走
web/src/shared/theme/theme.ts的readThemePreference/saveThemePreference;判断当前主题一律用resolveAppTheme/resolveReadingTheme,React 里用useThemeState,不要自己读存储。 - 搜索:桌面侧栏的“搜索书籍和影音”打开搜索页
#/search?q=(页内输入框写“搜索书名、片名、歌曲、有声书”),同时列出书库里的书和有权访问的影音,各自链接到完整的书库搜索和影音搜索。输入停顿约 0.35 秒后自动搜索(replace历史,Back 离开搜索页而不是逐字撤销);没有关键词时显示本机的“最近搜索”(按账号保存,最多 8 条,按回车或点开结果才记一条,可清除)。在搜索页时侧栏的搜索框让位给页内输入框。手机没有侧栏,入口是首页标题右侧的搜索图标。键盘/聚焦搜索框(阅读器、播放页和弹层打开时不响应)。侧栏账号下方显示同步引擎对服务器的判断:已连接、正在同步、离线或同步出错。侧栏和我的页只放得下这个结论;离线或出错时它们链接到账号与连接(#/me/account),那里的“同步”一栏给出原因、上次同步成功的时间和“立即同步”。标签页标题按路由取(web/src/app/page-title.ts,如“书架 · reader”),阅读器载入后改为书名。 - 二级页面的返回键只有一种几何:44px 的点击区距屏幕边 4px(侧栏模式下距内容左缘 −8px)、22px 的箭头、标题在其后 4px。影音页框(
.media-back-button)是基准,书库、文件管理、书源的页头按各自的内边距换算到同一位置(reader.css末尾),ui:review逐页比对。 - 手机上书架的“书库”“书源”两个入口在标题行右侧、设置按钮之前(纯文字按钮);701px 以上仍在搜索框左侧。单独占一行时第一张封面要到屏幕三分之一处才出现,
ui:review断言 390px 下第一张封面的顶边不超过视口高度的三分之一。 - 列表记住滚动位置:从书架、书库打开一本书再返回(浏览器 Back 或页面自己的返回),回到打开它的那张封面,而不是页首。位置按账号和 URL 记在内存里(
web/src/shared/ui/use-scroll-memory.ts,影音的搜索与播放记录用的是同一个);在页面里主动换页、换排序、换筛选或进文件夹是一张新列表,不恢复旧位置。 - 下拉框只有一种:
Select(web/src/ui/select.tsx,样式styles/select.css),用法与<select>相同(同样的属性、<option>子节点、原生change事件)。原生<select>仍在 DOM 里但不可见,值、表单校验和按select[aria-label=…]取值的测试都还落在它上面;看得见的是一个role="combobox"的按钮和浮在顶层的选项列表(在 Sheet 里也能用,Esc 只收起列表)。界面里不再直接写<select>;带搜索的长列表用SearchableSelect。它起源于影音的MediaSelect,那个名字保留为别名。 - 书架:搜索框下是“全部 / 在读 / 想读 / 已读”和“分组”(按书的系列或标签筛选),都写进 URL(
?status=、?series=、?tag=)。封面左上角标出在读、想读、已读;“⋯”菜单可标记想读、在读、已读或清除标记,并保留“从书架拿掉”。状态以手动标记为准,没有标记时按进度推断。 - 视频播放:字幕、音轨、版本是同一个“字幕与音轨”抽屉的三个分页。字幕页列出关闭、外挂(服务器上的 srt/ass/vtt)、内嵌,可“添加外挂字幕”(本机文件在浏览器里转换为 WebVTT,仅本次播放)、以 0.5 秒调整字幕延迟(外挂与本机字幕),并选择字号(小/标准/大,按设备保存)。工具栏的“全屏”进入横屏全屏:选集、倍速、适应屏幕(铺满裁边)、字幕和锁定浮在画面上,随 DPlayer 控制条一起淡出;锁定后点击不再作用于播放器,只留解锁按钮。这些只在网页播放器提供,Android 播放器用自己的菜单。
- 媒体库管理:列表上方是媒体库数量和两个常驻操作“扫描与刮削”“新建媒体库”(没有媒体库时由空状态给出“新建媒体库”)。每个媒体库卡片用频道色图标区分类型,受限库标“指定用户”,⋯ 菜单是编辑、访问权限、扫描记录;底部是缺失文件数(有缺失时用警示色)和最近一次扫描——完成时间和“重新扫描”(从未扫描时为“开始扫描”)、进行中的进度(“已处理 62%”)和“取消”、失败原因和“重试”“查看详情”。右侧“扫描与元数据”是服务器业务配置里的四个开关,逐项保存;旧服务器没有这些开关时卡片占满宽度。样式在
web/src/features/media/styles/manager.css。 - 扫描与刮削:“媒体库扫描”和“AI 扫描”共用一个工具栏——媒体库选择(写进
?library=)、刷新、唯一的主按钮(“扫描全部媒体库”/“扫描此媒体库”);下面是扫描记录,每条在第一行给出名称、状态和一个图标操作,失败原因在警示底色里、“重试”紧随其后,没有记录时显示空状态。“刮削”沿用页面选中的媒体库;表单宽屏时两列,“已选 N”和“开始批量匹配”固定在作品列表底部。 - 播放页的循环模式与定时:音乐的传输行是“循环模式、上一首、播放、下一首、队列”,有声书仍是快退、播放、快进,没有播放模式。循环模式按钮依次切换顺序播放、随机、单曲循环;播放队列面板用分段控件给出同一选择(
web/src/features/media/components/play-mode.tsx,类型与文案在services/play-mode.ts)。随机在所有条目播过一遍前不重复,上一首沿已播顺序回退;单曲循环不受“连续播放”偏好影响,手动下一首仍按队列顺序。睡眠定时抽屉在分钟档位之外提供“播完本章/本曲/本集”:当前条目结束后停下一次并保留进度,与分钟定时互斥,选中项带按下态,触发按钮显示“播完本曲”等。模式与播完即停只在网页播放器可用——Android 原生播放服务没有对应命令,此时循环按钮置灰、队列面板不显示分段控件、“播完…”置灰并说明原因。视频控制与设置页里的睡眠定时暂未接入“播完即停”。