更新记录

1.9.2（2026-09-29）

1.9.2（2026-09-29）

UTS 电子书阅读内核｜Android / iOS / 鸿蒙 Next｜H5 轻量降级。

• 百搭阅读壳 <ebook-reader>：path / url / content 开箱阅读；点中央显隐菜单、左右翻页、捏合字号、目录/主题/Aa/书签/听书；simulation 为 Canvas 贝塞尔卷曲
• 内核 API：createReader → readerId 全套能力（分页、选区、书签笔记、TTS、水印、访问策略、原生页、选书、下书、简繁、字体等）
• 格式：txt / md / epub 文本层（封面、简介、图片 localPath）；非完整 CSS 图文引擎
• 三端要点：Android TTS 媒体通知+音频焦点；iOS 后台音频会话；鸿蒙 CoreSpeechKit / 环境光；H5 仅 content 降级
• 增值 stub：手写 / AI 未装包时 8040004；实装见 ebook-reader-handwrite、ebook-reader-ai
• 修复：downloadFont / ensureBuiltinFont 返回命名类型 FontInstallResult（UTS110111101）

平台兼容性

uni-app(3.8.4)

其他

ebook-reader

UTS 电子书阅读内核｜Android / iOS / 鸿蒙 Next｜H5 轻量降级。

当前版本 1.9.2：提供可嵌入宿主的 百搭阅读壳 <ebook-reader>（开箱阅读 UI）+ 完整内核 API（可完全自定义）。

适合谁

增值模块（按需安装）

主包同名 API 为 stub：未安装对应包时 reject(8040004)。请从增值包 import，并用其 getHandwriteCapabilities / getAiCapabilities。

import { enableHandwrite } from '@/uni_modules/ebook-reader-handwrite'
import { configureAi, aiLookup } from '@/uni_modules/ebook-reader-ai'

规划中（未随主包发布）：ebook-reader-pdf、ebook-reader-ancient、ebook-reader-secure。

安装

1. 将本目录放入项目 uni_modules/ebook-reader
2. 选书（推荐）：同时安装 ebook-select-files；鸿蒙再装 ebook-select-files-harmony（主包也内置 pickBookFile）
3. 制作自定义调试基座后运行（改 utssdk/ 必须重做基座）
4. Vue2 / Vue3、app-vue / app-nvue / app-uvue 均可；H5 仅 content 试读降级

开箱即用（推荐）

easycom 会自动注册 components/ebook-reader/ebook-reader.vue。宿主页面只需：

<template>
  <ebook-reader
    :path="bookPath"
    :title="bookTitle"
    :show-back="true"
    watermark="仅供内部阅读"
    @progress=""
    @back="onBack"
  />
</template>

<script>
export default {
  data() {
    return {
      bookPath: '', // pickBookFile 后的稳定 path，或业务下发的本地路径
      bookTitle: '我的书'
    }
  },
  methods: {
    (p) {
      // 同步到自有书架：p.page / p.percent / p.position
    },
    onBack() {
      uni.navigateBack()
    }
  }
}
</script>

插件内 index.vue 即为该壳的演示页（挂载阅读壳 + 试读样例），不再是 API 接线板。

书源（三选一）

也可用 ref 命令式打开：

this.$refs.reader.open({ path: '/path/to/a.epub', bookId: 'b1' })
// 或
this.$refs.reader.open({ content: '第一章\n\n正文…', format: 'txt' })
this.$refs.reader.pickAndOpen()
this.$refs.reader.goNext()
this.$refs.reader.goPrev()

常用 Props

事件

ready · open · progress · back · close · error · bookmark · tts · chrome-change

交互（阅读壳内置）

• 点中央：显隐顶/底栏
• 点左/右约 28% 或左右滑：翻页（page 模式）
• simulation：Canvas 贝塞尔仿真卷曲，跟手拖动翻页；可开翻页纸张音效
• 双指捏合：调字号；上下滑：调亮度
• 长按：选区菜单（复制 / 划线 / 笔记 / 朗读）
• 底栏 / 更多：目录 · 主题 · Aa · 书签 · 听书 · 翻页模式 · 简繁 · 音效 · 导出

完全自定义（内核 API）

不需要内置 UI 时，直接调 API 自绘：

import {
  createReader,
  openBook,
  getPageContent,
  nextPage,
  onReaderEvent,
  getReaderCapabilities
} from '@/uni_modules/ebook-reader'

const caps = getReaderCapabilities()
const { readerId } = await createReader({
  theme: 'day',
  viewportWidth: 360,
  viewportHeight: 640,
  statsIntervalMs: 30000
})

onReaderEvent(readerId, 'progress', (p) => {
  console.log(p.page, p.pageCount, p.percent)
})

await openBook(readerId, { path: '/path/to/book.txt', bookId: 'my_book' })
// 或 openBook(readerId, { path: 'content:第一章\n\n正文', format: 'txt' })
// 或 openBook(readerId, { url: 'https://cdn.example.com/a.epub' })
// 或 openBook(readerId, { bytesBase64: '...' })

const page = await getPageContent(readerId)
await nextPage(readerId)

桥接不回传带方法的 class：所有 API 以 readerId 为第一参数（见 utssdk/interface.uts）。

内核能力速查

事件名（onReaderEvent）：ready · error · progress · relayout · tap · chapterChange · close · stats · ttsState · ttsProgress · selection · pageTurn · behavior · gesture · nativeView 等。

与选书

主包已内置 pickBookFile（阅读壳空态也会调）。仍可选用独立插件 ebook-select-files / ebook-select-files-harmony。

const res = await pickBookFile({ count: 1, extensions: ['txt', 'md', 'epub'], copyToCache: true })
if (res.ok) await openBook(readerId, { path: res.files[0].path })

用户取消：errCode = 8040001。

能力矩阵（1.9）

原生页 / 字体（进阶）

await showNativeReader(readerId, { mode: 'overlay' })
// embed：Android 需 uni-app x；iOS 容器 accessibilityIdentifier=containerId

await downloadFont({ url: 'https://example.com/SourceHanSans.otf', family: 'source-han-sans' })
await ensureBuiltinFont(readerId)

epub 说明

• 解析 META-INF/container.xml → OPF manifest/spine → 章节 HTML 抽纯文本
• 图片以 [图 src="..." alt="..."] 写入正文；PageContent.images 提供 src/alt/offset/localPath
• 目录优先 NCX / nav，否则用文内首行
• 选书请加后缀 epub，并 copyToCache: true
• 非完整 CSS 图文混排引擎（后续大版本）

getReaderCapabilities() 可探测运行时能力。

错误码 8040xxx

完整定义见 utssdk/unierror.uts（勿与 keepalive-location 的 803xxxx、选书插件的 8020xxx 冲突）。

踩坑（必读）

完整清单见 PRD §15。开发时至少记住：

1. 改原生后重做自定义基座
2. 目录名 = package.json 的 id = ebook-reader（ASCII -）
3. 禁止导出名为 init 的函数（iOS/Swift 保留字会导致云打包失败）
4. Android Int：(n).toInt()；iOS 勿对已是 Int 的值再 .toInt()
5. 选书务必 copyToCache: true，再用稳定 path 调 openBook
6. 鸿蒙权限若后续增加，必须写 module.json5 + $string:reason，只写 config.json 不进包
7. UTS 禁止 Promise<{...}> 匿名对象返回值，须用命名类型（如 FontInstallResult）
8. simulation：阅读壳走 Canvas 卷曲；原生页仍为轻量位移动画，二者不是同一套实现

隐私声明（市场）

1. 权限：M1 无强制危险权限；选书权限随选书流程；按需网络下书、TTS 后台音频/通知、环境光/距离传感器
2. 数据：默认仅本地存储进度 / 书签 / 笔记；行为事件只抛不传；AI 模块由业务配置服务端
3. 广告：无