mtfyun/reader
1
0 Fork 0
mirror of https://github.com/hectorqin/reader.git synced 2026-11-13 06:20:54 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ci/github-actions
reader/docs/user-guide.zh-CN.md
T
Kiro Agent 858a7479bf feat(theme): V3.1 semantic tokens, four themes and a reading theme 
Implements docs/prototypes/Reader V3 主题语义令牌.md (v3.1):

- 暖陶 (default), 雾蓝, 青绿 app themes plus the reading-only 黑白灰, each
  light and dark. Components read --color-* tokens from
  styles/theme-tokens.css, selected by data-theme + data-mode; the
  TypeScript mirror lives in shared/theme/theme.ts.
- Brand is split per the spec: brand/ch-* only fill (with on-brand/on-ch on
  top), brand-text/ch-*-text for text. --reader-accent/--media-accent are now
  brand text; --reader-fill/--media-fill are brand fills. Selected segmented
  controls use brand-soft + brand-text.
- One preference per server+account (reader.theme.v2): app theme, mode
  (system/light/dark), the follow-system light/dark pair, and the reading
  theme. V3 choices migrate per spec §8 (rose falls back to 暖陶 light).
- 外观与主题 rebuilt from prototype 23: follow-system switch with the
  light/dark pair, app-theme cards with light/dark previews, and the
  reading theme (跟随应用 / 黑白灰).
- Reader: 黑白灰 is set on the reader container only; the appearance panel
  offers 跟随应用/黑白灰 and 明暗; day/night sets the mode; the e-ink preset
  uses 黑白灰 light.
- Video and music players wear the current theme's dark values (§4.7).
- Removed the legacy light/sepia/green/dark palettes and the
  <html data-theme> writes from reader settings, which would now collide
  with data-theme="green".
- Tests: theme-tokens.test.ts keeps CSS and TS values identical and checks
  the §5 contrast pairs for all 8 palettes; theme.test.tsx covers migration,
  resolution, the controller and the settings page.
2026-10-20 04:05:35 +00:00

105 lines
8.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 使用手册
[项目首页](../README.md) · [文档中心](README.md) · [安装部署](getting-started.zh-CN.md)
本页介绍安装后的日常使用。部署参数见[配置指南](configuration.zh-CN.md)，协议细节见 [API](api.md)。
## 书架与书库
- **书架**是当前账号的阅读列表，可搜索、排序、调整密度并查看阅读进度。
- **书库**按挂载目录浏览本地书籍，可将书加入书架。
- **文件管理**供管理员检查磁盘目录。挂载可写且目录权限允许时，可上传、改名、移动、删除和新建目录。
从书架移除只改变该账号的书架记录，不删除书文件。文件管理中的删除会修改磁盘，请按界面确认提示操作。书籍的改名或移动按已有身份更新路径，保留阅读记录。
上传 `.zip/.cbz` 时会作为合集解包，保留必要的目录层级。单纯想把 CBZ 作为书籍扫描时，也可以直接把文件放到宿主机书库目录。重名上传支持保留两份、跳过、覆盖或拒绝整批，具体错误语义见 [上传 API](api.md)。
## 支持格式
| 格式 | 日常使用 |
| --- | --- |
| EPUB | 保留出版方排版、内嵌字体、目录、脚注、竖排和振假名等内容 |
| TXT | 自动识别 UTF-8、GB18030、Big5、UTF-16，支持手动切换编码和章节推断 |
| CBZ / ZIP | 按自然顺序展示页面，支持漫画分页 |
| 图片目录 | 将符合条件的图片目录作为漫画书，支持卷结构 |
| PDF | 基础查看，不解析成可重排正文；功能取决于浏览器或设备查看器 |
`.rar/.cbr` 不支持；ZIP64、加密和分卷压缩包不支持。reader 不提供 EPUB、TXT、PDF 之间的通用转换。
## 扫描与元数据
默认每 30 分钟定时扫描、每 60 秒检查变化，管理员可以手动触发扫描。扫描先比较大小和修改时间，再按需计算内容哈希。`.git`、`@eaDir`、`#recycle` 等目录被跳过，符号链接不跟随。
图片目录会结合图片、卷目录和压缩包结构识别。目录中包含其他书籍文件时，不应将这些书吞并为一个漫画目录；目录识别和分页资源规则见[架构](architecture.md)及 [API](api.md)。
书籍身份与内容有关，不直接依赖文件路径。移动或重命名通常保留身份，相同内容副本会合并；修改文件内容可能改变识别结果。
手动元数据覆盖保存在数据库中，优先于书内信息和文件名解析，重新扫描不会覆盖手动值。撤销手动字段后回到提取值。本地书籍当前没有内置在线元数据抓取服务；影音资料匹配见[影音手册](media-user-guide.zh-CN.md)。
## 阅读设置
字号、主题和界面设置按设备保存；阅读进度和笔记随账号同步。
重新打开书籍时会比较本机与服务端进度，采用更新时间较新的位置；离线或服务端暂时不可达时使用本机记录。切到后台会先保存待写入的位置再尝试同步，关闭页面仍受浏览器生命周期限制。出现“阅读位置保存失败”时先保持页面打开，检查设备可用空间后重试，避免刷新丢失尚未保存的记录。
| 设置 | 作用 |
| --- | --- |
| 分页 / 滚动 | 按屏翻页或连续阅读 |
| 字号、行距、页边距、对齐 | 调整正文，部分设置可选择沿用原书 |
| 字体 | 在原字体栈之前加入选定字体 |
| 主题 | 跟随应用或黑白灰；明暗可跟随系统、浅色或深色 |
| 亮度 | 界面叠加调暗，不等同于修改设备系统亮度 |
| 图片适配 | 固定版式内容完整显示或适宽 |
| 翻页方向 | 漫画等固定版式内容支持左右方向切换 |
| TXT 编码 | 自动识别异常时手动选择 |
点击正文中央可切换工具栏，左右区域翻页；也可使用目录跳转章节。工具栏、目录和设置面板覆盖正文，避免显隐时重新挤压正文布局。电脑端支持方向键、PageUp/PageDown；Android 可通过外壳处理音量翻页。
EPUB 章节按需加载，长书的目录与传输窗口分开处理，跨窗口跳转会先取相应章节。图标为 Lucide SVG，界面布局与交互规范见 [UI 文档](ui.md)。
## 朗读
可使用三种语音来源：Android 系统 `TextToSpeech`、浏览器 `speechSynthesis`，或管理员配置的 HTTP 语音服务。
- 从当前位置或选区开始，按句朗读并高亮。
- 支持上一句、下一句、暂停、继续和停止。
- 可调整语速、选择可用语音；音调等选项由引擎能力决定。
- 可设置章末继续下一章或停止。
没有中文语音时，先检查设备安装的语音包和当前引擎。需要服务端语音时，参照 [HTTP 朗读配置](configuration.zh-CN.md#http-朗读)。
## OPDS 书库
从书架的「书源」入口进入书源中心；管理员可在「书源管理」中添加 OPDS 服务地址。需要认证时配置当前账号的凭据。打开来源可浏览、搜索并获取书籍，下载完成后加入书架。也可以通过[只读 OPDS 服务](opds-webdav.zh-CN.md)把 Reader 中的文件书提供给外部阅读器。
## 影音入口
打开站点默认进入影视页（`#/media/video`），也可从书架右上角「影音」入口进入。通过频道导航切换电影、剧集、音乐和有声书，选择「阅读」返回书架。影音拥有独立设置、主题、收藏与播放页面，不改变阅读器和书架设置。
管理员可添加本地目录或 OpenList 媒体库，配置权限、扫描与刮削；用户浏览已授权的内容并播放。建库、歌词、字幕、队列、倍速及睡眠定时见[影音使用说明](media-user-guide.zh-CN.md)。
## 多用户与离线
首个账号是管理员，后续成员默认由管理员创建。每个账号的书架、进度、笔记和高亮独立。阅读界面参数属于当前设备，不随账号覆盖其他设备的设置。
离线时可使用已经缓存的内容，重新连通后同步阅读状态。在阅读器底部「工具 → 离线缓存」可下载TXT 的指定范围，或下载完整 EPUB、PDF、CBZ；自定义目录的 TXT 下载完整文件。任务支持暂停、继续和取消，关闭面板会暂停，已下载内容保留。默认设备账号配额为 256 MiB，可调整或按书清理；不自动淘汰，也不删除原书、进度、笔记。服务端缓存与当前设备缓存独立，只有本设备完成下载的内容才能保证断网读取。图片目录暂不支持整书下载。
## 进一步阅读
- [配置与故障排查](configuration.zh-CN.md)
- [API：目录、资源、进度、上传和来源](api.md)
- [数据边界与实现决策](architecture.md)
## 阅读工具：搜索、笔记与内容整理
- **书内搜索**：打开「工具 → 书内搜索」，输入文字后逐章检索，最多展示 200 个命中，支持停止。点结果定位并高亮原文，再次打开工具可返回搜索前的位置。支持 EPUB/TXT；扫描 PDF 和图片不提供 OCR。未缓存章节需要联网。
- **高亮和批注**：先在正文选择文字，再打开「工具 → 笔记」，选择颜色并保存。填写批注即可形成笔记；无选区也可保存当前位置书签。支持编辑、删除、点击回正文，联网后沿用账号同步。原文变化导致定位不唯一时不会猜测位置。
- **多级目录**：EPUB nav/NCX 保留三级及更深层级和章内锚点，有子项的目录可展开、折叠，选择章节后关闭面板。
- **内容整理**：先选择文字，在「工具 → 内容整理」填写替换内容，留空可以过滤选区。修改以个人覆盖层保存在服务器 DATA_DIR 的 SQLite 中，不修改书籍文件。支持逐项移除和撤销上一次修改；跨设备并发保存冲突时需重新打开书籍。保存需联网，已缓存规则可离线应用。
- **TXT 目录**：可选择中文章回、Chapter、方括号模板，或输入自定义标题前缀，预览后应用；留空恢复默认识别。规则匹配不超过 80 字的标题行，不执行任意正则。重新划分章节后从首章打开，旧笔记保留但可能需要重新定位。预览需要完整 TXT 文件。
- **朗读检测**：按当前引擎试听。HTTP 引擎先实际请求合成，分别提示未配置、鉴权失败、超时、非音频和空音频。关闭面板或点击停止会释放试听；浏览器仍可能要求允许声音播放。
## 电纸书
阅读设置中的“应用电纸书预设”会切换为浅色、分页和无翻页动画，仅影响当前设备；其他选项仍可调整。该预设不控制电纸书全刷或硬件残影。浏览器验收范围与 OPDS/WebDAV 后续边界见 [生态互通方案](ecosystem-roadmap.zh-CN.md)。
Reference in new issue View Git Blame Copy Permalink