# 使用手册

[项目首页](../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)。