更新记录

1.5.2(2026-11-16)

  • 修复 Web 与小程序错误对象缺少 data 与 cause 字段导致 ReaderFailImpl 类型告警的问题,保留原有失败回调结构和原生错误合同。

  • 修复鸿蒙仿真翻页与 Android 不一致的问题,统一二维跟手卷页、纸背字影、折痕阴影、整页页眉页脚和释放、取消回弹。

  • 修复鸿蒙图标形态、尺寸、线宽和选中态不一致,统一使用 Android 同组图标,并修复顶部裁切及动态路径显示。

  • 修复鸿蒙阅读器图标过小、文字遮挡、子控件点击与动态状态刷新,整理书介、目录、设置和听书的布局层次。

  • 修复鸿蒙滚动模式切换与重排时的原文位置恢复、选文端点命中,以及章节、搜索和评论回写的状态一致性。

  • 修复鸿蒙 TXT 流式解码收尾与损坏尾部校验,避免正常文件打不开或截尾内容被静默丢弃。

  • 修复三端沉浸阅读安全区、菜单显隐和系统栏协调;听书与抽屉背景延伸至安全区,显隐时保持正文位置。

  • 修复示例页面和辅助模块使用相对引入路径的问题,统一通过 @/uni_modules/ 引用插件内文件,复制页面到其他目录时无需另行复制辅助代码。

  • 修复 HarmonyOS 系统 TXT 文件选择中异常重新抛出的类型限制,避免原生编译失败。

  • 修复 HarmonyOS 阅读与听书界面内部尺寸字段与 ArkUI 组件成员重名导致的编译失败,保留原有布局和交互。

  • 优化双宿主演示封面,改用小体积本地书店图片,并修复鸿蒙封面及头像的本地文件显示。

  • 优化说明文档,补齐“作者系列 UTS 插件”清单及插件市场链接,便于按能力查找。

1.5.1(2026-10-21)

  • 修复 Android 翻页动画初始尺寸尚未就绪时提前启动,以及动画期间触摸可能误触发翻页的问题。
  • 修复 Android 目录封面和作者头像的包内资源加载;调整目录字体、作者行、搜索入口、章节对齐和背景层级。
  • 修复 Android 间距和更多设置的小屏裁切、间距选中反馈,以及评论失败提示、草稿保留和回复确认。
  • 优化 Android 点击仿真翻页,随点击高度轻微倾斜,保留真实拖动的跟手效果。
  • 优化 Android 评论、笔记、听书与详情界面的字体层级、背景协调、操作状态和长文本展示。

1.5.0(2026-10-16)

  • 新增 Android / iOS / HarmonyOS 五种阅读模式的可见正文选文、拖动端点、显式复制和划线,位置使用原文 UTF-16 偏移。
  • 新增笔记创建、编辑、删除确认与原文定位;支持保存中、失败、30秒超时重试、保留草稿和宿主快照冲突后的重新核对。
  • 新增 noteActionsEnabled、resolveReaderNoteAction、noteChange、可选笔记原文范围与能力查询;由宿主持久化,保存确认后才更新列表,旧接入默认保持原行为。
  • 新增 uni-app / uni-app x 真实本地笔记保存示例,按账号、书籍、修订和章节隔离,重试按操作标识去重。
  • 修复部分原生联编场景中的动态布尔参数类型与可空命令回调初始化问题。
查看更多

平台兼容性

uni-app(5.24)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × × × ×

uni-app x(5.24)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ √ √ ×

lizhao-novel-reader

介绍

为 uni-app / uni-app x 提供 Android、iOS、HarmonyOS 原生全屏小说阅读页,支持文字、章节、本地 TXT、翻页、进度、书签、选文笔记和前台系统朗读。小说正文与书城、付费、评论、下载等业务服务由接入方提供。

补充说明

介绍

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

介绍

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

介绍

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

介绍

提供书架、下载、评论、分享和听书界面。听书可直接使用设备系统语音,也可继续对接已有播放器或 TTS 服务。小说内容由接入项目提供,在线书源、账号、下载任务、评论服务、业务音频、付费授权和云端进度需自行接入。

功能特色

功能 阅读体验与用途
五种翻页,按习惯选择 仿真、覆盖、平移、上下滚动、无动画,满足翻页阅读和连续阅读习惯
TXT 与小说章节阅读 打开本地 TXT、直接传入文字,或接入自己的小说章节内容
记住进度,接着上次读 本地保存阅读位置,再次打开可继续;调整字号后按文字位置重新排版
目录跳转与书签 快速找到想看的章节,把喜欢的段落位置加入书签
字号、行距与背景自定义 调整字体大小、行距、段落间距、页面留白和阅读配色
日间与夜间模式 根据阅读环境切换主题,配合窗口亮度调节
自动阅读调速 选择前进间隔,随时暂停或继续,并获取实际阅读状态
书内搜索与定位 查找标题和可用正文,查看命中片段并跳到原文
选文、划线与笔记 长按选字、拖动端点、复制原文,创建编辑删除笔记;保存结果由你的业务确认
前台系统朗读 使用 Android / iOS / HarmonyOS 系统音色朗读当前正文,支持暂停、继续、倍速、音色和定时停止
沉浸式全屏阅读 点击正文呼出或收起工具栏,正文分页保持稳定
听书、评论等业务扩展 提供听书控制、评论、书架、下载、分享和书籍详情界面,由你的业务处理服务与数据
章节按需加载 只加载当前阅读与预加载的章节,适合章节较多的小说
受限章节接入 显示章节锁定提示,接入自己的会员或付费授权流程
多书籍、多账号记录 按账号与书籍分别保存本地进度和书签

适合哪些场景

场景 推荐用法
小说书城已有章节接口 chapters 目录与按需正文回写
单篇文章或培训文字 text 直接传入正文
阅读用户本地小说 chooseReaderTxt 选择后自动打开;已有路径可用 txtFile
阅读摘记或前台听读 开启笔记动作或 audioMode: system

下载与导入

  1. 在插件市场选择“使用 HBuilderX 导入插件”,导入到自己的 uni-app 或 uni-app x 项目。
  2. 保留完整的 uni_modules/lizhao-novel-reader 目录和插件名称。
  3. 在页面脚本中从插件根目录导入公开 API:
import { openReader, destroyReader } from '@/uni_modules/lizhao-novel-reader'

完整示例位于:

  • uni-app:uni_modules/lizhao-novel-reader/example/uniapp/index.vue
  • uni-app x:uni_modules/lizhao-novel-reader/example/uniappx/index.uvue

完整示例中的书源、付费、评论和下载均为离线演示;系统朗读、搜索、自动阅读与本地笔记调用真实能力。App 使用包含插件的匹配原生包。

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

通用 uni-app 片段使用 Vue2/Vue3 均可使用的选项式写法;uni-app x 的强类型 UTS 页面与参数说明见 uni_modules/lizhao-novel-reader/readme.md(API 用途速查)。下列业务方法应绑定到按钮或页面生命周期,按需调用。

模块:打开第一本小说

<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>

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

模块:先看封面,再开始阅读

需要先展示封面、作者、简介及热门书评时,设置 entryPage: 'bookInfo'。读者可左滑或点击底部开始阅读;原接入不传该参数,仍直接进入正文。

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

function readWithIntro() {
  openReader({
    readerId: 'first-reader', bookId: 'first-book', title: '雨后书店',
    sourceType: 'text', content: '第一章 雨后书店\n雨停后,林舟走进那间亮着灯的书店。',
    entryPage: getReaderCapabilities().bookIntro === true ? 'bookInfo' : 'content',
    audioMode: 'system',
    uiState: {
      author: '林间灯火', bookDescription: '从一本旅行手记出发,寻找城市里的温暖记忆。',
      coverPath: '/uni_modules/lizhao-novel-reader/static/demo-cover.png',
      bookTags: ['都市日常', '治愈'],
      bookReviews: [{ reviewId: 'review-1', nickname: '纸页旅人',
        content: '雨声和书店的开场很有画面感。', rating: 4.5,
        readingTimeText: '阅读2小时后点评' }]
    },
    fail(error) { uni.showToast({ title: error.errMsg, icon: 'none' }) }
  })
}

bookIntro 表示当前原生包支持封面入口。bookReviews 是独立全书书评,最多20项,界面预览前3项;comments 继续表示章评/段评。评分0–5(含半星),未传评分或阅读时长时隐藏对应内容,空数组可清空书评。更多书评通过 bookReviews 菜单事件交给宿主。

显式封面入口在初始正文与恢复位置准备好、介绍页可交互后返回 initialState: 'bookInfo';进入正文只收起介绍层,不额外翻页。初始正文加载失败仍通过原错误流程结束,不把加载占位算成功;封面图片不可读时使用文字占位。普通示例已接好该流程,特色场景继续直接体验相应功能。

模块:翻页与目录

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,避免背景弱化正文。

模式 阅读表现
none 直接切页
slide 页面横向滑动
cover 页面覆盖切换,两端动画方向略有差异
scroll 当前章节纵向滚动,可用底部翻页按钮跨章
curl 原生卷曲翻页;两端具体曲面与手势表现有差异

模块:在线章节——先用离线数据跑通

目录只提供元数据。收到 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

让用户从系统文件管理器选择一本 TXT,选好后直接进入正文。无需其他文件选择插件;一次选择一个文件,最大 50MiB。App 使用包含系统 TXT 选择能力的原生包。

将以下方法绑定到“选择 TXT 并阅读”按钮;取消选择不会打开阅读页。

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

function selectAndRead() {
  chooseReaderTxt({
    readerId: 'txt-reader',
    success(result) {
      const file = result.txtFile
      openReader({
        readerId: 'txt-reader', bookId: 'local-' + file.sha256,
        title: file.fileName.slice(0, -4), sourceType: 'txtFile',
        filePath: file.filePath, encoding: 'auto',
        fail(error) { uni.showToast({ title: error.errMsg, icon: 'none' }) }
      })
    },
    fail(error) {
      if (error.errCode !== 9107013) uni.showToast({ title: error.errMsg, icon: 'none' })
    }
  })
}

chooseReaderTxt 不要求先打开阅读器,返回应用缓存路径、文件名、实际字节数及原文件 SHA-256。阅读器和文件选择不能同时打开;选择期间请禁用重复点击,页面退出后忽略迟到结果,完整示例已处理这些情况。取消返回 9107013,超过大小限制返回 9107008。缓存文件可能被系统清理,长期书架需自行保存副本。

已有可读文件时仍可直接使用 openReader({ sourceType: 'txtFile', filePath, ... })。支持绝对路径及 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 的解锁当成真实购买。

import { setChapterCatalog } from '@/uni_modules/lizhao-novel-reader'
// 已打开 chapters 模式的目录;锁定只是展示,正文仍由服务端校验授权。
function markRestrictedChapter() {
  setChapterCatalog({
    readerId: 'first-reader',
    chapters: [{ chapterId: 'ch1', title: '第一章', locked: true, lockedMessage: '登录后阅读' }],
    fail(error) { console.log(error.errCode, error.errMsg) }
  })
}

模块:自动阅读与调速

需要按自己的阅读节奏自动前进时,可以在阅读设置末尾打开自动阅读面板,选择更快、默认或更慢,也可以由宿主控制。下面在已经打开的阅读器中开启每 3 秒前进一次,并查询状态:

import { setAutoRead, getAutoReadState } from '@/uni_modules/lizhao-novel-reader'

setAutoRead({
  readerId: 'first-reader',
  autoRead: { enabled: true, intervalMs: 3000 },
  success() {
    getAutoReadState({
      readerId: 'first-reader',
      success(result) { console.log('自动阅读状态', result.autoRead) }
    })
  },
  fail(error) { uni.showToast({ title: error.errMsg, icon: 'none' }) }
})

同一个 setAutoRead 方法传 autoRead: { enabled: false } 暂停,传 { enabled: true } 继续;只传 { intervalMs: 8000 } 调整速度,保持当前运行或暂停状态。

参数 类型 必填 说明 默认值 可选参数
enabled boolean,可选 否(至少一项) true 开始或继续,false 暂停;省略或 null 保持原状态 保持当前状态 见说明
intervalMs number,可选 否(至少一项) 1000–60000 毫秒的整数;至少提供此项或 enabled 中的一项 Android/鸿蒙 4200ms,iOS 4500ms 见说明

默认间隔为 Android / 鸿蒙 4.2 秒、iOS 4.5 秒。需要一致的节奏时显式传入 intervalMs,两套示例均使用 3 秒。速度仅在本次会话有效,重新打开不会自动开始。手动翻页或跳转会暂停;加载正文时等待,正文可读后重新计时;受限章节、加载失败时暂停,处理后可继续;全书末尾停止。滚动模式按间隔前进,不是连续匀速滚动。

autoReadChange 事件和查询结果中的 autoRead 包含 status、intervalMs、reason。状态依次可为 idle(未开始)、running(运行中)、waiting(等待正文或恢复)、paused(暂停)、finished(全书读完)。reason 提供手动操作、后台、加载、锁章、错误或读完等原因。若要在调用前判断支持情况,检查 getReaderCapabilities().autoReadControl 是否为 true。

模块:书内搜索与定位

读者想找到某个角色、段落或章节时,可以在已经打开的阅读器中显示搜索面板。面板支持全部、标题、正文三个范围,展示命中片段,点击结果跳回原文。

import { getReaderCapabilities, showReaderSearch } from '@/uni_modules/lizhao-novel-reader'

if (getReaderCapabilities().bookSearch == true) {
  showReaderSearch({
    readerId: 'first-reader',
    search: { query: '林舟', scope: 'all', maxResults: 100 },
    fail(error) { console.log(error.errCode, error.errMsg) }
  })
}

省略 search 可打开空输入面板。原有目录搜索按钮仍发出 catalogSearch 事件;在已有 onEvent 中收到它后调用 showReaderSearch({ readerId: event.readerId }) 即可接入,也可以继续使用自己的搜索页面。

需要用自己的页面展示结果时,调用 searchReader 获取命中;用户选择某条后,将它的 position 交给已有的 gotoPosition:

以下为 uni-app x UTS 写法。

import { searchReader, gotoPosition, cancelReaderSearch } from '@/uni_modules/lizhao-novel-reader'
import { ReaderSearchHit } from '@/uni_modules/lizhao-novel-reader'

searchReader({
  readerId: 'first-reader', search: { query: '书店', scope: 'content' },
  success(result) {
    const found = result.search
    if (found != null) console.log('搜索结果', found.hits, '已搜索正文章节', found.contentChapters, '总章节', found.totalChapters)
  },
  fail(error) { console.log(error.errCode, error.errMsg) }
})

// 自定义列表的点击事件传入用户选中的命中。
function selectSearchHit(hit: ReaderSearchHit): void {
  gotoPosition({ readerId: 'first-reader', position: hit.position })
}

// 用户取消时调用;不要在发起搜索后立即执行。
function stopSearch(): void { cancelReaderSearch({ readerId: 'first-reader' }) }
参数 类型 必填 说明 默认值 可选参数
query string 是 必填,1–128 UTF-16 单元,不能全为空白;区分大小写,按字面查找,不支持正则 无 见说明
scope string,可选 否 all 标题与正文(默认)、title 仅标题、content 仅正文 all 见说明
maxResults number,可选 否 1–200 的整数,默认 100;truncated: true 表示还有更多命中 100 见说明

标题可在完整目录中查找;本地 TXT 可以检索全书。在线章节仅检索当前已加载且仍在缓存中的正文,不为搜索额外请求章节,不搜索尚未解锁的正文。结果中的 titleChapters、contentChapters 是实际检查的章节数,unavailableChapters、lockedChapters 分别是遇到的未加载与受限正文数;达到上限时可能提前停止,尚未遍历的章节不会计作已搜索。

每条命中含 kind、chapterTitle、chapterIndex、snippet、matchStart、matchLength 和 position。片段内偏移与正文位置均按 UTF-16 计数;标题命中定位章首。搜索不改变进度;打开面板或点击结果按手动阅读操作暂停自动阅读,关闭后由读者手动继续。新搜索替换旧搜索、取消、关闭或更新目录时,未完成的搜索以 9107013 结束;自定义列表应在换书或目录更新时清空旧结果。

模块:选文、划线与笔记

读者需要摘录或记下想法时,设置 noteActionsEnabled: true。长按当前可见正文后拖动端点,点击复制、划线或笔记;笔记列表可定位原文、编辑和删除。保存中会等待宿主确认,失败或30秒未确认保留草稿供重试。选文会暂停自动阅读和系统朗读,读者可手动继续。

下面使用随示例提供的真实本地缓存接入;正式项目可把 persistReaderNoteAction 换成服务端事务。uni-app x 将 helper 导入后缀改为 .uts,控制参数使用 ReaderCommandOptions 类型。

import { openReader, getReaderCapabilities, resolveReaderNoteAction } from '@/uni_modules/lizhao-novel-reader'
import { loadReaderNotes, persistReaderNoteAction } from '@/uni_modules/lizhao-novel-reader/example/note-store.js'

const account = 'signed-in-user' // 使用当前账号的稳定隔离键
if (getReaderCapabilities().noteActions === true) {
  openReader({
    readerId: 'notes-reader', bookId: 'notes-book', title: '阅读摘记',
    sourceType: 'text', contentRevision: '1', storageNamespace: account,
    content: '雨停时,书店的灯刚刚亮起。', noteActionsEnabled: true,
    uiState: { notes: loadReaderNotes(account, 'notes-book', '1', 'text') },
    onEvent(event) {
      if (event.type !== 'menuAction' || !['noteCreate', 'noteUpdate', 'noteDelete'].includes(event.menuAction)) return
      const reply = {
        readerId: event.readerId, generation: event.generation,
        bookId: event.bookId, contentRevision: event.contentRevision, chapterId: event.chapterId,
        noteRequestId: event.noteRequestId, operationId: event.operationId, noteStatus: 'failed'
      }
      try {
        const notes = persistReaderNoteAction(account, event)
        if (event.menuAction !== 'noteDelete') reply.note = notes.find(item => item.noteId === event.note.noteId)
        reply.noteStatus = 'saved'
      } catch (error) { reply.message = '保存失败,请重试' }
      resolveReaderNoteAction(reply)
    }
  })
}

noteRequestId 对应一次保存尝试,operationId 在同一操作重试时保持不变。服务端按 operationId 去重,并按固定 noteId 更新或删除;真正提交成功后才能确认 saved。回写失败不修改已确认列表,过期或重复确认返回 9107009。提供 setReaderUiState.uiState.notes 会替换列表并使在途保存确认失效;读者需重新核对宿主内容与草稿,恢复时使用新操作标识,也可放弃草稿。已删除或改换原文的笔记不能恢复旧修改。其它增量字段保持笔记操作。

笔记字段 使用结果
noteId、kind、content、position 固定标识,笔记/划线、用户内容、原文位置;兼容旧笔记
selectedText、selectionEnd 同时提供时绘制原文范围;结束位置不包含字符,长度须等于结束偏移减起点
color、timeText 可选 #RRGGBB 划线色、显示时间

每章最多200条笔记,内容与选中原文各最多5000个 UTF-16 单元。位置基于规范化正文,改字号、纸色和翻页方式后可继续定位。旧笔记没有范围时只显示列表与定位;选区限定当前稳定可见的同章正文,不跨页自动滚动,不跨章选择。旧接入未开启新动作时继续使用 noteOpen 等宿主入口。

模块:听书详情与设置

系统朗读或宿主音频开始后,正文左下显示封面胶囊:封面打开全屏详情,播放键暂停/继续,滑杆打开设置,关闭停止。详情收起和设置返回只切换界面,保留当前播放和文字位置。封面只在前台实际播放时旋转;详情与胶囊根据可读本地封面匹配配色,正文纸色和夜间设置保留。

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

// 已打开audioMode: system的阅读器;同样可以通过原生设置面板调整。
setReaderSpeech({ readerId: 'first-reader', speech: { rate: 1.2, timerMinutes: 30 } })

设置分为定时关闭、语速、音色;子面板返回上一级设置。定时可关闭,或选择10/30/60/90分钟及1–180整数分钟;系统语速0.5–2倍,宿主音频按原合同0.5–4倍;音色名称来自当前设备或宿主。设置结果按实际引擎状态或宿主回写显示。

系统模式显示真实文字进度,不把文字长度换算成音频秒数。宿主模式仅在提供有效 audioPosition/audioDuration 时显示音频进度,定位/调速/停止由宿主处理后回写。audioStop 是新增的明确停止事件,不能用播放暂停开关代替;旧 audioToggle 等事件保持。

模块:监听与页面退出

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 事件和关闭命令成功回调均发生在原生会话释放之后,可在其中重新打开阅读器。

系统朗读的音色、定时停止以及书籍资料、书架、下载、评论等事件回写见 uni_modules/lizhao-novel-reader/readme.md(从基础到进阶:按业务模块使用)。

完整业务示例与接入说明

uni-app x

以下为 uni-app x UTS 页面写法。

<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>

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

完整示例的业务演示范围

两套示例提供相同的业务按钮,包含选文与笔记本地保存、短文、离线段落评论、自动阅读调速、前台系统朗读、书内搜索、章节延迟、章节失败重试、受限章节、初始化取消,以及书架、下载、宿主听书、评论的事件回写。段评示例按书籍、章节和段落分别维护评论,支持本地发送、回复、点赞、排序及分页。正文、解锁和书城业务结果均为离线 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 } })
    } else if (event.menuAction === 'audioStop') {
      await yourAudioPlayer.stop()
      setReaderUiState({ ...identity, uiState: { audioStatus: 'idle' } })
    }
  }
})

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

menuAction 附加字段 宿主职责
bookshelfToggle 无 加入/移出业务书架,回写 bookshelfAdded
download 无 创建下载任务,回写 downloadStatus / downloadProgress;需要时同时入架
comments 无 拉取评论,回写 commentStatus / comments / commentCount
paragraphComments paragraphId、selectionStart / selectionEnd 拉取当前段落评论,按同章同修订身份回写 comments 与 paragraphComments
paragraphCommentsToggle actionValue 为 on / off 当前阅读窗口已切换段评气泡显示,可记录用户显示偏好
commentSettingsChange actionValue 为设置 JSON 当前窗口已应用显示设置,可保存用户偏好
share / bookDetail 无 打开宿主分享或书籍详情流程
audioOpen / audioToggle 无 准备播放器、播放或暂停,回写音频状态
audioStop 无 胶囊关闭的明确停止意图;真实停止完成后回写 audioStatus: idle
audioPreviousChapter / audioNextChapter 无 切换业务音频章节
audioSeekRelative actionNumber 为 ±15 秒 相对快退或快进
audioSeekTo actionNumber 为目标秒数 跳到指定音频位置
audioRate / audioTimer actionNumber 修改实际倍速或停止定时
audioVoice actionValue 为 voiceId 切换宿主提供的音色
commentSort actionValue 为 hot / latest 按选择重新拉取评论
commentSend actionValue 为输入正文 提交评论后回写新列表或 message
commentLike commentId 点赞/取消点赞后回写列表
commentReply / commentMore commentId,回复可带 actionValue 打开回复或评论管理流程
commentsLoadMore 无 拉取下一页评论并增量回写 comments / commentHasMore
noteOpen noteId 打开或定位宿主保存的笔记详情
textSelection selectedText、selectionStart、selectionEnd 处理正文选区;当前由 iOS 上下滚动模式提供
catalogSearch 无 调用 showReaderSearch 打开插件搜索,或沿用宿主自己的搜索页面
authorFollowToggle 无 关注或取消关注作者,完成后回写 authorFollowed
bookReviews 无 打开宿主的全部书评页面

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

顶部评论图标切换当前页段评气泡;点击段尾气泡打开该段评论面板。“设置→评论设置”可选择全部/精选段落,并控制 AI、神评论与作者段评、章末讨论的展示。原章评入口保留在“更多→查看章评”。未提供段落快照时,全部模式显示零条气泡;插件不会将章评复制到每个段落。

段评的 commentSend、commentReply、commentLike、commentMore 沿用上表动作,并附带 paragraphId 和 UTF-16 选区;应按事件中的章节和正文修订处理业务,再回写同一段落数据。显示设置 JSON 的字段为 showBubbles、featuredOnly、showAI、showFeaturedAndAuthor、showChapterDiscussion,仅影响当前窗口的展示,不会向服务端自动提交操作。

模块九:前台系统朗读

读者需要边看边听时,将本次阅读的 audioMode 设为 'system'。阅读页会使用设备的系统语音和系统音色;打开阅读器后仍保持未播放。Android / iOS 点击“听书”直接开始,并在正文中高亮正在朗读的范围;左下播放条可暂停、继续或停止,点击封面可调整语速、音色和定时。鸿蒙在原生朗读面板点击播放,也可由你自己的明确按钮调用 setReaderSpeech 开始。

import {
  openReader, getReaderCapabilities, setReaderSpeech,
  getReaderSpeechState, getReaderSpeechVoices
} from '@/uni_modules/lizhao-novel-reader'

function openWithSystemSpeech() {
  if (getReaderCapabilities().tts != true) return
  openReader({
    readerId: 'speech-reader', bookId: 'speech-book', title: '雨后的小城',
    sourceType: 'text', audioMode: 'system', restoreProgress: false,
    content: '第一章\n雨停后,书店亮起了灯。',
    onEvent(event) {
      if (event.type === 'speechChange') console.log('朗读状态', event.speech)
    },
    success() {
      getReaderSpeechVoices({
        readerId: 'speech-reader',
        success(result) { console.log('系统音色', result.speechVoices) }
      })
      getReaderSpeechState({
        readerId: 'speech-reader',
        success(result) { console.log('当前朗读状态', result.speech) }
      })
      // 此处只查询,不自动播放。
    }
  })
}

// 绑定到用户点击事件;也可直接使用阅读页内的播放按钮。
function startSpeech() {
  setReaderSpeech({
    readerId: 'speech-reader',
    speech: { action: 'start', rate: 1, timerMinutes: 30 }
  })
}
speech 配置 类型 说明
action string,可选 start / pause / resume / stop;开始会从当前文字位置新建任务
rate number,可选 0.5–2,相对设备默认语速
voiceId string,可选 来自 getReaderSpeechVoices;空字符串恢复设备默认中文音色
timerMinutes number,可选 0 关闭定时,1–180 为停止分钟数

setReaderSpeech 至少提供一项配置;只修改语速、音色或定时不会自动开始。speechChange、setReaderSpeech 和 getReaderSpeechState 返回的 speech 包含 status、reason、rate、voiceId、timerMinutes、remainingMs、当前位置及 progressPrecision。可用状态为 idle、initializing、waiting、playing、paused、finished、error。

系统朗读只在阅读页前台运行。进入后台、音频焦点被其他应用占用、手动翻页或跳章、打开搜索面板时会暂停,需要读者手动继续。公开章节可接续朗读;遇到受限章节或供章失败时暂停,处理后再手动继续。系统朗读和自动阅读互斥,开启其中一个会停止另一个。系统模式不提供音频秒数进度或快进后退;需要后台播放、业务音频或云端音色时使用 host 模式。

Android / iOS 高亮由系统语音回调驱动;Android 不支持范围回调的音色按实际播放片段高亮,iOS 使用系统返回的文字范围。暂停、停止或手动翻页后清除高亮。设备需具备可用的中文系统语音服务;缺少引擎或中文音色时会提示原因。Android 可从朗读设置进入系统语音设置;iOS 请先在设备系统设置中下载可用的中文音色。

鸿蒙使用系统离线 TTS,要求设备存在可用的中文语音数据,音色来自系统查询。其 progressPrecision 为 segment;暂停后继续会从尚未播完的短片段开头重读,不提供逐字进度。缺少系统引擎或音色时明确失败,不自动改用网络服务。

接入说明补充

以下保留原说明中的调用前置、业务范围、平台条件与接入顺序,配合上述模块阅读。

适合哪些场景

  • 已有小说接口,希望接入原生阅读页。

适合哪些场景

  • 阅读用户已选择、已授权访问的 TXT 文件。

适合哪些场景

  • 阅读纯文字资料、培训内容或应用内文章合集。

适合哪些场景

当前不提供 EPUB、PDF、漫画、内嵌阅读组件或内置书城。audioMode: 'system' 使用设备自带语音做前台朗读;需要后台听书、网络音频或云端音色时,保留默认 host 模式并接入已有播放器或 lizhao-smart-tts。

API 用途速查

API 用途 结果
openReader 打开原生阅读页 initialState,可带 progress
chooseReaderTxt 系统单选 TXT 并复制到应用缓存 txtFile:路径、文件名、字节数与摘要
closeReader / destroyReader 关闭、取消初始化并释放资源 readerId / action
nextPage / prevPage 翻页,跨章按需请求正文 进度快照或命令受理结果
gotoPosition 跳至稳定文字位置 进度快照或命令受理结果
getProgress 查询当前可读位置 progress
setReaderStyle / setPageMode 修改外观、翻页模式 命令结果
setAutoRead / getAutoReadState 自动阅读启停、调速及查询 autoRead 状态快照
setReaderSpeech 开始、暂停、继续、停止或配置前台系统朗读 speech 状态快照
getReaderSpeechState / getReaderSpeechVoices 查询系统朗读状态与设备音色 speech / speechVoices
showReaderSearch 打开原生搜索面板 命令受理结果;读者点击后定位
searchReader / cancelReaderSearch 自定义搜索结果或取消搜索 search 命中与实际搜索范围 / 取消结果
setReaderUiState 回写宿主已确认的业务状态 uiState 快照或命令结果
resolveReaderNoteAction 确认笔记创建、编辑或删除的真实保存结果 确认受理结果;有效保存后发 noteChange
setChapterCatalog / getChapterCatalog 更新或分页查询目录 更新结果 / chapters + total
resolveChapter / rejectChapter 完成一次章节请求 命令结果;可见页随后更新
addBookmark / removeBookmark 新增或删除书签 bookmark / 命令结果
getBookmarks 分页查询书签 bookmarks + total
onReaderEvent / offReaderEvent 注册或解除独立事件订阅 无返回值
getReaderCapabilities 同步查询当前构建支持能力 ReaderCapabilities

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

完整参数、回调字段、平台差异和扩展流程见 uni_modules/lizhao-novel-reader/readme.md · API 用途速查。

配置 建议
readerId 当前阅读会话的固定 ID,后续控制、取消和关闭均使用它
bookId 长期稳定的书籍 ID,同一本书不要每次随机生成
storageNamespace 登录后使用账号业务 ID;默认 guest,不要传 Token
contentRevision 正文改版时更换修订号,默认 '1'
sourceType text / chapters / txtFile
entryPage 默认 content;显式 bookInfo 先展示封面介绍
style 字号、行高、段距、留白、主题及颜色
uiState 业务已确认的书架、下载、播放器、评论和笔记初始状态
pageMode 默认 curl,可先查询 getReaderCapabilities()
audioMode 默认 host,保留宿主听书事件;设为 system 使用前台系统朗读
restoreProgress 默认 true;首次演示或从头阅读时设为 false
你的内容 使用方式 边界
一篇已加载的短文 sourceType: 'text' + content 最多 200000 个 UTF-16 单元,章节 ID 固定为 text
已有小说目录和章节接口 sourceType: 'chapters' + chapters 目录最多 10000 条;收到请求后提供单章正文
本地 TXT sourceType: 'txtFile' + filePath 最多 50 MiB;后台建立索引并按章读取

完整参数、返回结果与事件

OpenReaderOptions

参数 类型 必填 说明 默认值 可选参数
readerId string 是 1–128 字符的非空会话 ID 无 见说明
bookId string 是 1–128 字符的稳定书籍 ID 无 见说明
title string 是 非空书名 无 见说明
sourceType string 是 text / chapters / txtFile 无 见说明
contentRevision string 否 '1';1–128 字符 '1' 见说明
storageNamespace string 否 'guest';1–128 字符 'guest' 见说明
content string 条件必填 text 正文,不超过 200000 个 UTF-16 单元 无 见说明
chapters ReaderChapter[] 条件必填 chapters 目录,1–10000 条 无 见说明
initialContent string 否 指定初始章的正文,同样受单章大小限制 见说明 见说明
initialChapterId string 否 默认第一章,必须属于目录 见说明 见说明
filePath string 条件必填 txtFile 的本地可读文件 无 见说明
encoding string 否 auto / utf-8 / utf-16le / utf-16be / gb18030 auto 见说明
position ReaderPosition 否 显式位置,优先于本地进度 见说明 见说明
restoreProgress boolean 否 true true 见说明
style ReaderStyle 否 见下表 见说明 见说明
uiState ReaderUiState 否 业务已确认的初始状态;不执行网络或播放器操作 见说明 见说明
pageMode string 否 curl;五种模式见上文 curl 见说明
audioMode string 否 host;设为 system 使用前台设备系统朗读 host 见说明
noteActionsEnabled boolean 否 false;true 开启宿主确认的笔记创建编辑删除 false 见说明
requestTimeoutMs number 否 15000;范围 1000–60000 毫秒 15000 见说明
cacheLimitBytes number 否 8388608;范围 1048576–33554432 字节 8388608 见说明
keepScreenOn boolean 否 false;仅阅读期间保持亮屏,不修改亮度 false 见说明
onEvent (ReaderEvent) => void 否 持续事件 见说明 见说明
success / fail / complete function 否 单次打开回调,见下文 见说明 见说明

ReaderStyle

参数 类型 必填 说明 默认值 可选参数
theme string 否 paper / light / night paper paper / light / night
fontSize number 否 12–40 24 12–40
lineHeight number 否 1–2.5 倍行高 1.85 1–2.5 倍行高
paragraphSpacing number 否 0–32 12 0–32
horizontalPadding number 否 8–48 18 8–48
textColor string 否 #RRGGBB,与背景对比度 ≥ 4.5:1 随主题 #RRGGBB,与背景对比度 ≥ 4.5:1
backgroundColor string 否 #RRGGBB,与正文对比度 ≥ 4.5:1 随主题 #RRGGBB,与正文对比度 ≥ 4.5:1
fontFamily string 否 system / serif,不捆绑商业字体 system system / serif,不捆绑商业字体
bold boolean 否 是否加粗正文 false 是否加粗正文
brightness number 否 -1 跟随系统,或 0–1;只影响阅读窗口 -1 -1 跟随系统,或 0–1;只影响阅读窗口
showStatus boolean 否 显示页码、时间和电量 true 显示页码、时间和电量
singleHand boolean 否 左右点击区均向后翻;右滑仍返回上一页 false 左右点击区均向后翻;右滑仍返回上一页
pullToBookmark boolean 否 下拉正文添加本地书签 true 下拉正文添加本地书签
showSystemStatusBar boolean 否 阅读期间显示系统状态栏 false 阅读期间显示系统状态栏

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

ReaderUiState

字段 类型 说明
author / bookDescription string 作者与简介展示;音色说明字段为 voiceDescription
coverPath / authorAvatarPath string 应用可读的本地书封/头像路径;不负责网络下载,单张最大 10 MiB
bookScoreText / ratingCountText string 已格式化评分与点评人数;未传不显示
readerCountText / bookWordCountText string 已格式化在读人数与全书字数
bookUpdateText string 已格式化更新说明
bookTags string[] 书籍标签,最多 20 项,每项最多 40 字符
authorFollowed boolean 宿主确认后的作者关注状态
bookshelfAdded boolean 宿主确认后的书架状态
downloadStatus string idle / downloading / downloaded / failed
downloadProgress number 0–1 的实际下载进度
audioStatus string idle / loading / playing / paused / error
audioTitle string 当前音频章节名
audioPosition / audioDuration number 实际播放位置与时长,单位秒
audioRate number 0.5–4 的实际倍速
audioVoice / voices string / ReaderVoice[] 当前音色 ID 与可选音色,最多 50 条
audioTimerMinutes number 0 表示关闭,最大 180 分钟
commentStatus string idle / loading / ready / error
commentSort string hot / latest
commentCount / comments number / ReaderComment[] 评论总数与当前列表,列表最多 200 条
paragraphComments ReaderParagraphComment[] 同章同修订的段尾数量快照,最多 200 条;空数组清空,省略保持
commentHasMore boolean 是否还有下一页评论
message string 业务完成或失败提示
notes ReaderNote[] 当前章的业务笔记/划线,最多 200 条

ReaderParagraphComment 必填 paragraphId、chapterId、contentRevision、textOffset、commentCount。textOffset 为规范化章节正文的 UTF-16 段首偏移,范围 0–200000 的整数;commentCount 为真实评论总数,范围 0–1000000000 的整数。可选布尔 featured 表示精选段落;同章同修订下不能重复 paragraphId。段落气泡只显示在该段末尾所在页,切换字体或翻页时保持正文位置。

ReaderComment 原有 commentId、nickname、content 等字段继续有效。可选 avatarPath 使用应用可读的本地图片路径,省略时显示昵称首字;可选 kind 为 user / ai / author / featured / chapterDiscussion,用于评论展示过滤。段评评论须同时提供 paragraphId、chapterId、contentRevision;三项全部省略表示原章评,不会出现在段评面板。段尾数量和评论正文分开提供,例如:

import { setReaderUiState } from '@/uni_modules/lizhao-novel-reader'
// 在当前阅读器的 onEvent 内调用,使用该事件携带的完整会话身份。
function updateComments(event) {
  setReaderUiState({
    readerId: event.readerId, generation: event.generation,
    bookId: event.bookId, contentRevision: event.contentRevision, chapterId: event.chapterId,
    uiState: {
      paragraphComments: [{ paragraphId: 'p1', chapterId: event.chapterId, contentRevision: event.contentRevision, textOffset: 0, commentCount: 1 }],
      comments: [{ commentId: 'c1', nickname: '读者', content: '这一段很有画面感', paragraphId: 'p1', chapterId: event.chapterId, contentRevision: event.contentRevision }]
    },
    fail(error) { console.log(error.errCode, error.errMsg) }
  })
}

该片段是 openReader.uiState 或带完整当前会话身份的 setReaderUiState.uiState 字段;实际章节、修订、段首偏移和数量由宿主提供。发布、回复和点赞只发业务意图,面板等待宿主回写,不显示未经确认的成功状态。

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。其他字段按方法选择:

方法 额外字段
gotoPosition position: ReaderPosition
setReaderStyle style: ReaderStyle
setPageMode pageMode: ReaderPageMode
setAutoRead autoRead: ReaderAutoReadOptions,至少有 enabled 或 intervalMs
setReaderSpeech speech: ReaderSpeechOptions,至少有 action、rate、voiceId、timerMinutes 中的一项
setReaderUiState uiState + generation / bookId / contentRevision / chapterId
setChapterCatalog chapters: ReaderChapter[]
resolveChapter 完整请求身份 + content: string
rejectChapter 完整请求身份 + 可选 message: string
addBookmark 可选 title: string,默认当前章节标题
removeBookmark bookmarkId: string
getBookmarks / getChapterCatalog offset?: number 默认 0,limit?: number 默认 50,最大 200

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

回调与事件

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

openReader.success 默认表示正文首屏或受限页已经可交互;显式 entryPage: bookInfo 表示初始正文已准备且封面介绍可交互,结果为 initialState: bookInfo。加载占位不算成功。初始化失败或取消会触发 fail,释放本次会话。后续章节错误通过事件和原生页重试提示通知。

事件 type 含义
ready 原生阅读页准备完成
progress 阅读位置变化,携带 progress
chapterRequest 需要宿主提供章节,携带完整请求身份
chapterChange 当前章节改变
menuAction 原生菜单或业务动作;业务动作值见“书架、下载、听书与评论”
bookmarkChange 书签变化
positionAdjusted 恢复位置发生修正
autoReadChange 自动阅读状态或间隔变化,携带 autoRead
speechChange 前台系统朗读状态、配置或位置变化,携带 speech
noteChange 宿主确认笔记保存或删除后,携带 menuAction、noteId 与笔记快照
error 阅读中的错误,带 errCode 和中文 message
close 会话已释放,最终事件

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

返回值说明

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

类型 字段
ReaderPosition bookId、contentRevision、chapterId、textOffset、anchorText
ReaderProgress position、chapterIndex、chapterCount、pageIndex、pageCount、chapterProgress
ReaderBookmark bookmarkId、title、position、createdAt(毫秒)
ReaderUiState 作者、书架、下载、播放器、评论、笔记等宿主业务快照
ReaderAutoReadState status、intervalMs、reason
ReaderSpeechState status、reason、rate、voiceId、timerMinutes、remainingMs、position、progressPrecision
ReaderSpeechVoice voiceId、name、language
ReaderCapabilities platform、nativeFullscreen、sourceTypes、pageModes、encodings、epub、tts、embedded、businessActions、autoReadControl、bookSearch、textSelectionModes、noteActions

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

错误码说明

失败对象的 errSubject 为 lizhao-novel-reader,请同时读取 errCode / errMsg。

错误码 说明 处理建议
9107001 参数不合法 检查 ID、目录、样式和必填字段
9107002 平台或模式不支持 查询能力,选择已实现入口
9107003 阅读器不存在或已关闭 不再向旧会话发控制命令
9107004 已有阅读器正在打开或显示 等待关闭后再打开
9107005 文件不存在或不可读 确认真实路径和文件访问授权
9107006 TXT 解码或解析失败 核对编码,必要时显式指定
9107007 正文为空 检查正文接口及空文件
9107008 内容或文件超过限制 分章供稿,遵守大小上限
9107009 章节或笔记请求已过期或已处理 丢弃旧回写,不重放旧尝试标识
9107010 章节加载失败或超时 允许重试并核对业务请求
9107011 位置或列表范围不合法 检查书籍、章节、页边界及分页参数
9107012 本地数据保存失败 检查可用空间并提示记录未保存
9107013 操作已取消 结束本次加载,不当作业务崩溃
9107014 原生阅读页面不可用 在 App 前台且页面可显示时调用
9107015 内部操作失败 记录方法和错误文案以便定位

注意事项

能力 Android iOS HarmonyOS
系统版本要求 Android 7.0 / API 24 iOS 13.4 建议 5.0.3 / API 15 起;uni-app x 蒸汽宿主要求 6.0 / API 20
宿主 uni-app / uni-app x uni-app / uni-app x uni-app / uni-app x(含蒸汽模式)
原生全屏、三种正文入口 已提供实现 已提供实现 已提供实现
五种翻页模式 已提供实现 已提供实现 已提供实现
本地进度、书签、目录 已提供实现 已提供实现 已提供实现
自动阅读调速与状态控制 已提供实现 已提供实现 已提供实现
书内搜索与原文定位 已提供实现 已提供实现 已提供实现
前台系统朗读与系统音色 已提供实现 已提供实现 已提供实现;离线音色、片段进度
业务书架/下载/评论/听书控制 UI 事件接入 事件接入 事件接入
段落气泡、段评与评论显示设置 已提供实现 已提供实现 已提供实现
选文、划线与笔记保存确认 五种模式,需开启笔记动作 五种模式,保留旧滚动选文 五种模式,需开启笔记动作
EPUB / 后台系统朗读 / 嵌入式 不支持 不支持 不支持

Web 和小程序当前不支持。鸿蒙使用 ArkUI 原生阅读页,接入时应使用适配当前 HBuilderX 的 DevEco 工具链与完整原生应用包。getReaderCapabilities() 返回当前构建的入口、翻页模式和编码集合;它是能力查询,不表示当前设备已完成体验验收。上架前请在目标机型检查翻页、长文、旋转和后台恢复。

自动阅读进入后台时会暂停计时。Android / 鸿蒙返回前台会续读离开前仍在运行的会话;iOS 返回后需手动继续。此前已因手动操作、锁章或错误暂停的会话不会因回前台自动开启。

使用书内搜索前请确认 getReaderCapabilities().bookSearch == true;旧原生版本没有此能力时,请更新包含搜索功能的自定义基座后使用。

使用前台系统朗读前请确认 getReaderCapabilities().tts == true。旧原生版本会返回 9107002,不会把 system 模式静默降级成宿主听书事件。

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

平台条件与常见问题补充

常见问题

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

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

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

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

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

系统朗读为什么不能开始? 先确认打开阅读器时使用 audioMode: 'system',再检查 getReaderCapabilities().tts。系统没有可用语音、当前不在前台或使用旧原生版本时会明确失败;插件不会自动切换为宿主播放器。

原来的业务听书如何继续使用? 不传 audioMode,或传 host。原有 audioToggle、audioRate、audioVoice 等事件和 setReaderUiState 回写方式保持不变,可继续接入自己的播放器或 lizhao-smart-tts。

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

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

作者系列 UTS 插件

以下为作者已发布的 UTS 插件,可按能力方向查找。

插件 能力方向 插件市场
lizhao-alipay-kit 支付宝授权登录、App 支付与脱敏诊断 查看插件
lizhao-app-keepalive 应用保活、唤醒、自愈与报告 查看插件
lizhao-apple-iap 苹果内购、交易恢复、订阅管理与服务端验签参考 查看插件
lizhao-apple-login 苹果授权登录、凭证状态与撤销监听 查看插件
lizhao-bg-audio 背景音频播放、队列、倍速与事件 查看插件
lizhao-ble BLE 扫描、连接、读写、通知与自动重连 查看插件
lizhao-call-kit 电话、短信、通讯录原生能力 查看插件
lizhao-camera-pro 原生相机、拍照录像、水印与媒体保存 查看插件
lizhao-cast-screen DLNA 投屏、AirPlay 路由入口 查看插件
lizhao-choose-file 原生文件选择、上传、进度与取消 查看插件
lizhao-device-id 设备标识、隐私策略与诊断 查看插件
lizhao-dingtalk 钉钉授权登录、内容分享与回执诊断 查看插件
lizhao-doc-corrector 文档扫描、矫正、增强与识别 查看插件
lizhao-douyin-kit 抖音授权登录、内容分享与回执诊断 查看插件
lizhao-emu-detect 模拟器环境检测、风险评分与证据 查看插件
lizhao-float-window 悬浮窗、画中画、权限与诊断 查看插件
lizhao-gallery-pro 相册媒体分页、筛选、缩略图与导出 查看插件
lizhao-google-login Google 授权登录、会话管理与脱敏诊断 查看插件
lizhao-hce-card NFC 虚拟卡、APDU 交互与 NDEF 标签模拟 查看插件
lizhao-health 健康数据授权、查询、统计与写入 查看插件
lizhao-http-server 本地 HTTP 服务、文件传输与实时通信 查看插件
lizhao-icon-pro SVG 图标组件、多主题与缓存 查看插件
lizhao-id-photo 证件照制作、尺寸换算、换底色与模板换装 查看插件
lizhao-img-eraser 图片去水印、局部修复与原生编辑器 查看插件
lizhao-live-activity 实时活动、系统胶囊与普通通知降级 查看插件
lizhao-live-photo 实况照片选取、展示预览与原件处理 查看插件
lizhao-map 高德地图、定位、地点搜索、路线规划与导航 查看插件
lizhao-meta Facebook 登录分享、应用事件与深链 查看插件
lizhao-nfc-pro NFC 标签读写、NDEF、IsoDep 与诊断 查看插件
lizhao-notify-pro 本地通知、点击动作、进度与定时提醒 查看插件
lizhao-novel-reader 原生小说阅读、仿真翻页与段落评论 查看插件
lizhao-office-view Office 与 PDF 文件预览、进度与缓存管理 查看插件
lizhao-pdf-pro PDF 阅读、签批、真实写回与页面处理 查看插件
lizhao-play-billing Google Play 商品购买、订阅、恢复与确认消耗 查看插件
lizhao-qq-share QQ 授权码登录、QQ 与 QQ 空间分享 查看插件
lizhao-qrcode 二维码生成、Logo 与样式配置、批量生成及导出 查看插件
lizhao-scan-pro 原生扫码、连续扫码、相册识别 查看插件
lizhao-serial-port 路径串口、USB 串口、多会话收发与诊断 查看插件
lizhao-share-plus 系统分享、远程文件下载后分享 查看插件
lizhao-smart-tts 系统 TTS、云端合成、听书方案 查看插件
lizhao-sqlite-pro 原生 SQLite、迁移、备份与诊断 查看插件
lizhao-sse-pro SSE、Line、JSONL 与 Raw 流式请求 查看插件
lizhao-tcp-pro TCP 客户端、服务端、多连接与诊断 查看插件
lizhao-usb-storage U 盘、移动硬盘文件浏览、读写与批量复制 查看插件
lizhao-video-editor 视频裁剪、压缩、取帧与 FFmpeg/FFprobe 查看插件
lizhao-video-feed 短视频上下滑、短剧选集与分页加载 查看插件
lizhao-video-player 原生视频播放器、清晰度与播放交互 查看插件
lizhao-video-thumb 视频封面、批量取帧与 Base64 返回 查看插件
lizhao-vpn-pro 企业 VPN、IKEv2、安全接入与脱敏诊断 查看插件
lizhao-wechat-kit 微信登录、分享、支付、小程序与客服 查看插件
lizhao-wecom 企业微信授权登录、内容分享与脱敏诊断 查看插件
lizhao-xhs-share 小红书图文视频分享与回执诊断 查看插件

隐私、权限声明

1. 本插件需要申请的系统权限列表:

读取接入项目已授权的本地文件;插件不主动请求全部文件访问权限。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

正文由接入项目提供;阅读进度和书签保存于应用本地,不上传插件作者服务器。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无