更新记录

1.0.0（2026-10-07）

xwq-ebook-reader 1.0.0版本

• 阅读台生命周期：spawnReadingDesk / dismissReadingDesk / probeReaderSkills
• 卷册管理：mountBookVolume / ejectBookVolume / queryVolumeMeta / inspectVolumeFile / cacheVolumeRemote
• 格式解析：txt / md / epub（epub 解压 + OPF/spine/NCX·nav 解析，含封面、简介、目录）
• 分页翻页：字符偏移索引、避头尾、段落间距；翻页 / 跳转 / 进度 / 目录 / 叶面渲染 / 概览
• 排版与配色：字号 / 行距 / 段距 / 边距 / 视口 / 字体；day / night / eye / parchment / sepia
• 简繁转换：view 显示层 / all 全文改写，常用字一对一子集
• 书签与批注：增删改查、笔记、划线，本地持久化并自动恢复进度
• 信号订阅：listenReadingSignal 系列
• 语音朗读：系统 TTS，支持读完自动翻页续读、暂停 / 继续
• 体验增强：全文检索、字体登记 / 下载、水印参数、捏合缩放、环境光读取（鸿蒙端）
• 内置开箱即用阅读壳组件（easycom，无需 import）
• 错误码段：8050xxx

平台兼容性

uni-app(5.24)

xwq-ebook-reader

电子书阅读内核 UTS 插件（Android / iOS / HarmonyOS 三端已实现）。

• 格式：txt / md / epub（epub 走解压 + OPF/spine 解析，含封面、简介、目录）
• 能力：分页翻页、目录（txt/md 自动识别「第X章」等标题，epub 读取 NCX/nav）、进度恢复、书签批注、简繁转换、全文检索、语音朗读、水印、网络下书、字体登记（环境光读取仅鸿蒙端）
• 阅读设置：主题 / 字号 / 行距 / 字体 / 页模式（layoutPattern）跨会话持久化
• 书源：本地沙盒路径 / base64 / 内存文本 / 网络地址
• 存储：进度、书签、批注仅存应用沙盒（Android SharedPreferences / iOS UserDefaults / 鸿蒙 preferences），不上传任何服务器

本插件刻意使用与同类阅读插件不同的命名体系（阅读台 desk / 卷册 volume / 叶面 leaf / 信号 signal）， 避免与市场中其它电子书插件的方法名冲突。

平台支持

开箱即用（easycom 组件）

插件内置阅读壳组件 xwq-ebook-reader（位于 uni_modules/xwq-ebook-reader/components/xwq-ebook-reader/xwq-ebook-reader.vue）， 满足 easycom 规则，宿主页面无需 import，直接使用；只需传入小说文件地址即可。

<template>
  <!-- path / url / content 三选一；都不传时读取内置试读样例 -->
  <xwq-ebook-reader
    :path="bookPath"
    title="我的书"
    storage-namespace="myapp"
    @ready="onReady"
    @progress=""
    @back="onBack"
  />
</template>

<script setup>
import { ref } from 'vue'
const bookPath = ref('')       // 本地沙盒绝对路径（选书后 copyToCache 得到）
function onReady(e) { console.log('就绪', e.volumeKey, e.title) }
function (e) { console.log('进度', e.percent, e.chapterTitle) }
function onBack() { uni.navigateBack() }
</script>

组件 Props

组件事件

ready · progress · chapterChange · bookmark · speech · error · back

组件方法（ref 调用）

nextPage() · prevPage() · open(source) · openBook() · retryLoad() · openTheme() · openFont() · toggleToc() · toggleSpeech() · onBack()

交互：点屏幕中央显隐操作台；左右点击约 30% 区域或左右滑动翻页（即时切换）；左右拖动跟手画折页，松手超过阈值翻页、否则回弹。底栏悬浮胶囊含 目录 / 主题 / 字号 / 书签 / 听书；听书支持读完自动翻页续读、暂停 / 继续。

快速开始

import {
  spawnReadingDesk, mountBookVolume, renderLeafContent,
  turnLeafForward, listenReadingSignal, dismissReadingDesk
} from '@/uni_modules/xwq-ebook-reader'

// 1. 创建阅读台
const handle = await spawnReadingDesk({
  viewportWidth: 360,
  viewportHeight: 640,
  typeScale: 18,
  palette: 'day'
})
const deskId = handle.deskId

// 2. 订阅进度信号
listenReadingSignal(deskId, 'progress', (sig) => {
  console.log('进度', sig.percent, '%', sig.chapterTitle)
})

// 3. 挂载书籍
await mountBookVolume(deskId, {
  filePath: '/data/storage/.../book.txt', // 或 rawText / payloadBase64 / remoteUrl
  title: '我的书'
})

// 4. 读当前叶并翻页
const leaf = await renderLeafContent(deskId, 0)
console.log(leaf.text)
await turnLeafForward(deskId)

// 5. 用完销毁
await dismissReadingDesk(deskId)

API 总览

生命周期

卷册（书籍）

翻页与定位

排版与配色

书签与批注

信号（事件）

listenReadingSignal(deskId, signal, handler) / muteReadingSignal / muteAllReadingSignals

signal 取值：ready volumeMounted progress relayout leafTurn chapterChange tap(预留) selection(预留) bookmark annotation speechState volumeEjected closed error。

说明：翻页或跳转跨越章节边界时会补发 chapterChange 信号；tap / selection 为事件协议预留位，宿主可自行归一化。

朗读（TTS）

speakCurrentLeaf(deskId, options) / speakSelection(deskId, text, options) / holdAloudSpeech / proceedAloudSpeech / ceaseAloudSpeech

体验增强

错误码（8050xxx）

注意事项

1. 修改 utssdk/ 下代码后需重新制作自定义调试基座。
2. 目录名与 package.json 的 id 一致为 xwq-ebook-reader，请勿改名。
3. 书源为文件路径时建议 copyToCache 后的稳定沙盒路径。
4. epub 体积校验上限默认 20MB，可通过 ReadingDeskOptions.maxVolumeBytes 调整。
5. 简繁映射为常用字一对一子集，生僻字不做转换。
6. 朗读暂停以引擎 stop 语义实现（各平台系统 TTS 的限制），恢复会从当前叶重新播报。
7. 使用 remoteUrl 下书 / cacheVolumeRemote / fetchTypefaceFile 时，宿主工程需具备网络权限（Android INTERNET、iOS 网络访问、鸿蒙 ohos.permission.INTERNET），本插件不强制申请。
8. 环境光读取（鸿蒙端）基于系统光感传感器，未检测到传感器时 readAmbientLux() 返回 sensorReady: false 的兜底结果，不抛错。
9. 主题、字号、行距、字体、页模式（layoutPattern）等阅读设置按 storageNamespace 持久化到应用沙盒，下次 spawnReadingDesk 自动恢复；显式传入的选项优先于已保存设置。
10. txt / md 目录依赖标题行识别（「第X章/回/节/卷…」及「序章/楔子/番外」等）；无匹配标题时目录退化为单章。