更新记录

1.0.0（2026-10-03）

• 新增 Android / iOS 原生沉浸式全屏阅读，支持 uni-app 与 uni-app x。
• 新增直接传入正文、按需加载章节、本地 TXT 三种阅读入口，支持应用可读的绝对路径、file:// 与项目资源路径。
• 新增无动画、滑动、覆盖、滚动、仿真五种翻页方式，Android 支持二维纸角仿真与纸背文字效果。
• 新增字号、字体、行距、段距、主题、亮度、单手翻页、页脚和状态栏等阅读设置。
• 新增书籍详情、目录正倒序与分卷、章节信息、笔记与书签筛选，支持本地书封和作者头像。
• 新增阅读进度保存与文字位置恢复、书签管理、当前章节阅读百分比，支持账号和书籍数据隔离。
• 新增受限章节提示、解锁事件和授权后供章流程，由接入项目完成业务授权。
• 新增书架、下载、分享、听书控制和评论面板，通过业务事件与 setReaderUiState 接入宿主服务；支持评论总数、排序及资料增量回写。
• 新增章节请求身份校验、缓存数量与容量限制、初始化取消和会话资源释放。
• 新增 uni-app / uni-app x 两套离线演示与按业务模块组织的中文接入文档。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

其他

lizhao-novel-reader · 原生小说阅读器

介绍

让你的 App 拥有沉浸式小说阅读体验。

面向 uni-app / uni-app x 的 Android / iOS 原生小说阅读器。一键打开全屏阅读页，支持仿真翻页、本地 TXT、在线章节接入、目录书签和阅读进度记忆，适合小说 App、书城和应用内文字阅读。

喜欢翻书的手感，选择仿真翻页；习惯连续阅读，切换上下滚动。字号、行距、背景和日夜主题按需调整，再次打开同一本书，可接着上次的位置阅读。

提供书架、下载、评论、分享、听书控制界面，可与已有业务系统对接。小说内容由接入项目提供，在线书源、账号、下载任务、评论服务、音频播放、付费授权和云端进度需自行接入。

功能特色

适合哪些场景

• 已有小说接口，希望接入原生阅读页。
• 阅读用户已选择、已授权访问的 TXT 文件。
• 阅读纯文字资料、培训内容或应用内文章合集。

当前不提供 EPUB、PDF、漫画、内嵌阅读组件、内置书城或内置 TTS/音频引擎。听书控制界面会发出业务事件，可接已有播放器、系统 TTS 或 lizhao-smart-tts；getReaderCapabilities().tts 仍为 false，避免把控制界面误报为语音能力。

下载与导入

将完整的 lizhao-novel-reader 目录放入项目 uni_modules，保留目录名。从插件根目录导入公开 API：

import { openReader, destroyReader } from '@/uni_modules/lizhao-novel-reader'

完整示例位于：

• uni-app：example/uniapp/index.vue
• uni-app x：example/uniappx/index.uvue

示例包含短文、章节延迟、章节失败重试、受限章节、初始化取消，以及书架、下载、听书、评论的事件回写。所有正文、解锁和业务结果均为离线 Mock，不发起网络请求、真实下载、音频播放、评论发布或支付。

5 分钟跑通：打开第一本小说

uni-app

<template>
  <view><button @click="read">开始阅读</button></view>
</template>

<script>
import { openReader, destroyReader } from '@/uni_modules/lizhao-novel-reader'

export default {
  methods: {
    read() {
      openReader({
        readerId: 'first-reader',
        bookId: 'first-book',
        title: '雨后的小城',
        sourceType: 'text',
        content: '雨停时，街边的灯刚刚亮起。\n小林收起伞，沿着河边慢慢走向书店。',
        restoreProgress: false,
        onEvent(event) {
          // close 表示原生阅读页已经退出。
          if (event.type === 'close') console.log('阅读已结束')
        },
        fail(error) {
          uni.showToast({ title: error.errMsg, icon: 'none' })
        }
      })
    }
  },
  onUnload() {
    // 已经关闭时返回 9107003；这里无需额外提示。
    destroyReader({ readerId: 'first-reader' })
  }
}
</script>

uni-app x

<template>
  <view><button @click="read">开始阅读</button></view>
</template>

<script setup lang="uts">
import { openReader, destroyReader } from '@/uni_modules/lizhao-novel-reader'
import { OpenReaderOptions, ReaderCommandOptions, ReaderFail } from '@/uni_modules/lizhao-novel-reader'

function read() {
  const options: OpenReaderOptions = {
    readerId: 'first-reader', bookId: 'first-book', title: '雨后的小城',
    sourceType: 'text', restoreProgress: false,
    content: '雨停时，街边的灯刚刚亮起。\n小林收起伞，沿着河边慢慢走向书店。',
    fail: (error: ReaderFail) => {
      uni.showToast({ title: error.errMsg, icon: 'none' })
    }
  }
  openReader(options)
}

onUnload(() => {
  destroyReader({ readerId: 'first-reader' } as ReaderCommandOptions)
})
</script>

打开后默认隐藏工具栏。单击正文中区显示目录、书签、设置、听书等入口；单击两侧或拖动纸角翻页，滚动模式使用纵向阅读。

核心配置

接入方式选择

从基础到进阶：按业务模块使用

以下控制示例假定已经成功打开 readerId: 'first-reader'。每段使用到的方法都从 @/uni_modules/lizhao-novel-reader 导入。uni-app x 中控制参数使用公开的 ReaderCommandOptions 类型；完整强类型写法见随附 .uvue 示例。

一、翻页与目录

import { nextPage, prevPage, getChapterCatalog, gotoPosition } from '@/uni_modules/lizhao-novel-reader'

nextPage({ readerId: 'first-reader' })
// 返回上一页时调用 prevPage({ readerId: 'first-reader' })。

getChapterCatalog({
  readerId: 'first-reader', offset: 0, limit: 50,
  success(result) { console.log('当前目录', result.chapters) }
})

// chapterId 必须来自当前书籍的真实目录。
gotoPosition({
  readerId: 'first-reader',
  position: { bookId: 'first-book', contentRevision: '1', chapterId: 'text', textOffset: 0, anchorText: '' }
})

原生目录可直接选择章节。到书籍首尾时继续翻页返回 9107011，不会循环回到另一端。

二、恢复阅读位置

相同 storageNamespace + bookId 默认恢复本地进度。需要云同步时，在 progress 事件中取得 event.progress.position，由业务限频保存到服务器；再次打开时传入 position，优先于本地记录。

import { getProgress } from '@/uni_modules/lizhao-novel-reader'

getProgress({
  readerId: 'first-reader',
  success(result) {
    if (result.progress != null) {
      // 将 position 保存到你的业务存储，不要把 pageIndex 当作永久位置。
      console.log('当前位置', result.progress.position)
    }
  }
})

textOffset 基于去除开头 BOM、统一换行后的正文，采用 UTF-16 单元计数。正文修订变化时，插件尝试用 anchorText 辅助定位；无法精确恢复会发出 positionAdjusted。书籍和目录 ID 应保持稳定。

三、字号、纸色与翻页方式

import { setReaderStyle, setPageMode } from '@/uni_modules/lizhao-novel-reader'

setReaderStyle({
  readerId: 'first-reader',
  style: { theme: 'night', fontSize: 22, lineHeight: 1.8, paragraphSpacing: 10 }
})

setPageMode({ readerId: 'first-reader', pageMode: 'curl' })

未传入的样式字段保留当前值。显式切换 theme 会重置该主题的文字和背景色；同次提供的自定义颜色优先。字号或窗口尺寸变化后重新排版，以当前文字位置为依据。正文文字与背景的最终对比度必须达到 4.5:1；低对比自定义配色会返回 9107001，避免背景弱化正文。

四、在线章节：先用离线数据跑通

目录只提供元数据。收到 chapterRequest 后，把 readerId、generation、requestId、bookId、contentRevision、chapterId 原样带回。每个请求只能成功或失败一次。

import { openReader, resolveChapter, rejectChapter } from '@/uni_modules/lizhao-novel-reader'

// 离线 Mock；替换成业务请求时也保留完整请求身份和失败回写。
const contentByChapter = {
  c1: '第一章\n清晨，第一班渡船离开了码头。',
  c2: '第二章\n船靠岸时，远处传来了钟声。'
}

openReader({
  readerId: 'chapter-reader', bookId: 'river-story', title: '渡口',
  sourceType: 'chapters', restoreProgress: false,
  chapters: [{ chapterId: 'c1', title: '第一章' }, { chapterId: 'c2', title: '第二章' }],
  onEvent(event) {
    if (event.type !== 'chapterRequest') return
    const identity = {
      readerId: event.readerId, generation: event.generation,
      requestId: event.requestId, bookId: event.bookId,
      contentRevision: event.contentRevision, chapterId: event.chapterId,
      fail(error) {
        // 用户已关闭、目录已更新或超时后的旧请求会明确失败。
        if (error.errCode !== 9107009 && error.errCode !== 9107003) console.log(error.errMsg)
      }
    }
    const content = contentByChapter[event.chapterId]
    if (content != null) resolveChapter({ ...identity, content })
    else rejectChapter({ ...identity, message: '暂时没有这章正文，请稍后重试' })
  },
  fail(error) { uni.showToast({ title: error.errMsg, icon: 'none' }) }
})

该段为 uni-app JavaScript 写法；uni-app x 使用 ReaderEvent、ReaderCommandOptions 显式构造对象，见完整示例的 onReaderEvent。

reason 可为 visible、preload、unlock。可预加载相邻的公开章节，受限章节不会自动预取。首次供章失败会关闭初始化页面并触发 openReader.fail；阅读过程中跨章失败保留页面供重试。initialContent 与 initialChapterId 可减少首次请求；自动恢复到其他章节时仍可能请求那个章节。

需要替换目录时调用 setChapterCatalog({ readerId, chapters })，传完整快照。它会使旧请求失效；新目录中的章节 ID 必须唯一。该操作仅用于 chapters 入口。

五、本地 TXT

import { openReader } from '@/uni_modules/lizhao-novel-reader'

// 将此变量替换为文件选择或下载完成后取得的真实可读本地路径。
const localPath = '/你的应用沙盒目录/book.txt'
openReader({
  readerId: 'txt-reader', bookId: 'my-local-book', title: '本地小说',
  sourceType: 'txtFile', filePath: localPath, encoding: 'auto',
  fail(error) { uni.showToast({ title: error.errMsg, icon: 'none' }) }
})

插件不弹出文件选择器、不请求全部文件访问权限。请先由文件选择或下载流程取得授权，并将文件复制到应用可读的沙盒目录。支持绝对路径及 file://；_doc/ 等项目路径会交由运行时转换。不要传远程 URL 或 Android content:// URI。

auto 根据 BOM 识别 UTF-8 / UTF-16，否则尝试严格 UTF-8；无 BOM 的 GB18030 文件请显式指定 gb18030。解码失败返回 9107006，不会用乱码填充后宣称成功。

TXT 在后台分块解码、建立章节索引，不通过 JS 传递整本内容。可识别常见章节标题；过长章节和无标题正文会按受控长度分段。源文件保持只读，导入产生的会话临时文件在关闭时清理。导入期间可用同一 readerId 调用 closeReader 或 destroyReader 取消。

六、书签

import { addBookmark, getBookmarks, gotoPosition, removeBookmark } from '@/uni_modules/lizhao-novel-reader'

addBookmark({ readerId: 'first-reader', title: '下次从这里重读' })
getBookmarks({
  readerId: 'first-reader', offset: 0, limit: 50,
  success(result) { console.log('我的书签', result.bookmarks) }
})
// 选中书签后，将其 position 传给 gotoPosition。
// 删除时：removeBookmark({ readerId: 'first-reader', bookmarkId: 选中的书签编号 })。

书签按账号命名空间和书籍保存，每本书最多 1000 条。getBookmarks 和 getChapterCatalog 使用 offset / limit 分页，返回列表及 total。不要把返回列表的下标当作书签 ID。

七、受限章节与业务菜单

目录项设置 locked: true，可用 lockedMessage 说明限制。受限页可以正常打开，openReader.success.initialState 为 locked。

用户点击解锁后，收到 menuAction: 'unlock' 及 reason: 'unlock' 的 chapterRequest。业务完成登录、购买或权限校验后，按请求身份 resolveChapter；取消或未获授权时 rejectChapter。本地 locked 是展示标记，服务端仍需校验正文访问权限。

目录、设置、书签由原生页提供；对应菜单事件可用于业务统计，不需要再次弹出一套相同菜单。插件不内置支付 SDK，也不把示例 Mock 的解锁当成真实购买。

八、书籍资料、目录、书架、下载、听书与评论

这些界面由插件原生绘制，但插件不会伪造后端结果。章节展示可传 volumeTitle、wordCountText、updateTimeText、commentCount、summary 和当前章的 chapterProgressText；书籍资料可传 bookScoreText、readerCountText、bookWordCountText、bookUpdateText 与 bookTags。目录和资料面板底部始终保留目录、日夜、设置、听书四个入口。搜索、关注和书评入口会发出 catalogSearch、authorFollowToggle、bookReviews。宿主完成真实业务，再用同一事件携带的 readerId、generation、bookId、contentRevision、chapterId 回写增量状态。旧章节或旧会话的迟到响应会被拒绝。

coverPath 和 authorAvatarPath 只接受应用已有读权限的本地图片，例如 _doc/、static/、file://、unifile:// 或转换后的绝对路径。插件不下载 http/https，不接受 data:、blob: 或 Android content://；单张图片原生解码上限为 10 MiB，路径不可读或解码失败时会显示文字占位。临时文件由宿主管理生命周期；请在阅读会话存续期间保持文件可读，替换素材后用 setReaderUiState 回写新路径。

import { openReader, setReaderUiState } from '@/uni_modules/lizhao-novel-reader'

openReader({
  readerId: 'first-reader', bookId: 'first-book', title: '雨后的小城',
  sourceType: 'text', content: '第一章\n雨停后，书店亮起了灯。',
  uiState: {
    author: '林间灯火', bookDescription: '离线示例简介',
    coverPath: '_doc/books/rain-book-cover.png',
    authorAvatarPath: '_doc/books/rain-book-author.png',
    bookScoreText: '9.1分', ratingCountText: '1.2万人点评', readerCountText: '8.6万人在读',
    bookWordCountText: '12.8万字', bookUpdateText: '今日更新', bookTags: ['都市日常', '治愈'],
    authorFollowed: false, bookshelfAdded: false,
    downloadStatus: 'idle', audioStatus: 'idle', audioRate: 1,
    commentStatus: 'idle', commentSort: 'hot', commentCount: 0
  },
  async onEvent(event) {
    if (event.type !== 'menuAction') return
    const identity = {
      readerId: event.readerId, generation: event.generation,
      bookId: event.bookId, contentRevision: event.contentRevision,
      chapterId: event.chapterId
    }

    if (event.menuAction === 'bookshelfToggle') {
      // 示例直接确认；正式项目应先请求自己的书架接口。
      setReaderUiState({ ...identity, uiState: { bookshelfAdded: true } })
    } else if (event.menuAction === 'comments') {
      setReaderUiState({ ...identity, uiState: { commentStatus: 'loading' } })
      const page = await yourCommentService.list(event.chapterId)
      setReaderUiState({ ...identity, uiState: {
        commentStatus: 'ready', commentCount: page.total, comments: page.items
      } })
    } else if (event.menuAction === 'audioToggle') {
      await yourAudioPlayer.toggle()
      setReaderUiState({ ...identity, uiState: { audioStatus: yourAudioPlayer.status } })
    }
  }
})

上例的 yourCommentService、yourAudioPlayer 是业务占位名，不是插件内置对象。可直接运行的离线 Mock 见两个随附示例。

ReaderUiState 是增量状态；未传字段保持当前值。明确传入 false、0、空字符串仍会更新对应字段；传入空数组可清空对应列表。评论最多回写 200 条、音色最多 50 条。听书界面只控制你接入的播放器，插件不会静默播放、下载或发布评论。

九、监听与页面退出

import { onReaderEvent, offReaderEvent, destroyReader } from '@/uni_modules/lizhao-novel-reader'

onReaderEvent({
  readerId: 'first-reader', listenerId: 'page-observer',
  callback(event) { console.log('阅读事件', event.type, event.message) }
})

// 页面卸载时精确解除自己的订阅，再释放阅读会话。
offReaderEvent({ readerId: 'first-reader', listenerId: 'page-observer' })
destroyReader({ readerId: 'first-reader' })

监听可在打开前注册。同一 readerId + listenerId 再注册会替换旧监听；最多 128 个独立订阅。openReader.onEvent 随会话关闭自动释放，独立订阅在该会话关闭时也会清理。不要在宿主 onHide 中无条件关闭，否则打开原生页时可能立即退出。

closeReader 和 destroyReader 均结束当前会话、保存进度并释放资源。已关闭后再次调用返回 9107003。close 事件和关闭命令成功回调均发生在原生会话释放之后，可在其中重新打开阅读器。

API 用途速查

翻页或跳章如果需要加载正文，命令成功表示请求已受理；实际内容更新以 chapterChange / progress 事件为准。

参数说明

OpenReaderOptions

ReaderStyle

字号使用各端逻辑单位，系统字体设置和设备尺寸可能影响每页字数。

ReaderUiState

ReaderChapter / ReaderCommandOptions

目录项：chapterId: string、title: string 必填；locked?: boolean 默认 false；lockedMessage?: string 为可选提示。展示字段均可选：volumeTitle 为卷名，wordCountText / updateTimeText 是宿主格式化后的字数与更新时间，commentCount 是评论数，summary 用于详细目录摘要，chapterProgressText 是当前章右侧的业务进度文案（例如“读到7%”）。未传 chapterProgressText 时，插件根据当前章实际文字位置生成整数百分比。插件只展示这些数据，不猜业务统计口径。

控制 API 统一使用 ReaderCommandOptions，均需 readerId，支持 success / fail / complete。其他字段按方法选择：

其他控制方法无需额外字段。偏移与条数需为非负整数，limit 至少为 1。

回调与事件

单次方法只结算一次：success(result) 或 fail(error)，随后 complete(resultOrError)。业务回调异步派发，业务函数抛错不会阻止 complete。

openReader.success 表示正文首屏或受限页已经可交互；加载占位不算成功。初始化失败或取消会触发 fail，释放本次会话。后续章节错误通过事件和原生页重试提示通知。

事件公共字段为 readerId、type、message、timestamp（毫秒）。业务事件还带当前 generation、bookId、contentRevision、chapterId，并按动作附加 actionValue、actionNumber、commentId、noteId 或选区字段。页面应按 type 和 menuAction 分发，不要依赖中文文案判断状态。

支持平台

鸿蒙、Web 和小程序当前不支持。getReaderCapabilities() 返回当前构建的入口、翻页模式和编码集合；它是能力查询，不表示当前设备已完成体验验收。上架前请在目标机型检查翻页、长文、旋转和后台恢复。

返回值说明

ReaderResult 始终有 readerId 和 action，其他字段按方法返回。ReaderFail 有 errSubject: 'lizhao-novel-reader'、errCode 和中文 errMsg。

章节与页索引从 0 开始。pageCount 是当前章在当前排版下的页数；chapterProgress 为当前正文位置比例，并非全书已读百分比。改变字体、行高或屏幕尺寸后页码会变化。

错误码说明

常见问题

改了字号，为什么页码不同？ 页码来自当前排版。保存 ReaderPosition，不要长期保存页码。

为什么 TXT 打不开？ 先确认文件已落地到应用可读路径，再核对大小和编码。插件不直接读取网络地址或 content://。

供章已经返回，为什么被拒绝？ 超时、关闭、重复回写、目录更新都会使请求失效；必须原样回传完整身份。

缓存会永久保存整本书吗？ 不会。内存正文缓存有字节预算，当前章受到保护；TXT 会话索引和规范化文本是临时文件。本地进度与书签会保留。

退出后还收到业务网络响应怎么办？ 业务可以取消自己的网络请求；迟到的供章回写会明确失败。不要因此重新打开已关闭的阅读器。

为什么听书按钮可见，但 tts 是 false？ 插件提供原生听书控制界面和事件合同，不内置语音引擎。接入自己的播放器或 TTS 后，再把实际状态用 setReaderUiState 回写。

评论、下载或加入书架为什么没有自动成功？ 这些是宿主业务。插件只发事件；服务端或播放器确认成功后回写，避免 UI 显示虚假结果。

能否做自己的底部会员面板？ 首版为全屏原生页，提供受限章节和事件接入；不支持把页面组件嵌到阅读画布中。

注意事项

• 需要包含当前插件原生实现的应用包。新增或更新原生文件后，请重新进行原生联编或制作匹配的 Android / iOS 自定义基座；仅更新页面资源不能更新原生能力。
• 一次只显示一个阅读会话。readerId 固定到本次会话，bookId 和 contentRevision 固定到实际内容。
• 正文、书签和进度默认在应用本地处理，插件不上传到作者服务器，不内置广告或采集账号凭据。
• 应用卸载、清除数据可能删除本地记录；跨设备恢复请由业务实现云同步。
• 正文缓存预算只约束正文缓存，不等于整个 App 的内存上限。字体排版、页面图像和系统 UI 还会占用额外内存。
• 在业务服务端完成内容授权。不要将本地锁定标记当作付费内容的访问控制。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下插件可按需要搭配使用，本阅读器没有强制依赖它们。