更新记录

1.0.0（2026-10-16）

• 新增 PDF/TXT 系统原生预览与 DOCX/XLS/XLSX/CSV/TSV 社区离线结构化预览。
• 新增 35 种 Office 格式接入路线，按端侧直读、社区离线与私有转换分层处理。
• 新增本地路径、Android content://、iOS security-scoped URL、鉴权 URL、全屏预览和 uni-app x native-view 嵌入。
• 新增 uni-app 与 uni-app x 双宿主 API，以及进度、取消、预取、缓存清理和会话状态查询能力。
• 新增私有内网转换服务部署方案，支持进度查询、超时、PDF 文件头与转换产物 SHA-256 校验。
• 新增主题、起始页、阅读方向、文字水印、工作表切换、Provider 能力清单和统一错误回调。
• 新增随包交付的社区渲染资源、宏与外链隔离、格式能力限制、双宿主示例和 26 类错误码说明。

平台兼容性

uni-app(5.15)

uni-app x(5.15)

其他

lizhao-office-view

介绍

让用户在 Android、iOS App 内阅读合同、报表和办公附件，兼容 uni-app 与 uni-app x。无需跳转 WPS，文件也不必交给公网预览服务。

先看你的文件属于哪一种：

合计覆盖 35 种格式的接入路线，其中 7 种可在端侧离线预览，28 种需要私有转换。社区阅读器以内容可读为目标，复杂排版、图表和特殊字体可能与 Office 不同。PPT/PPTX 暂不提供端侧离线渲染。

平台、格式和文件大小限制请查看本文后半部分；端侧能力与私有转换边界请结合目标平台和实际文件样本验收。

功能特色

请求源文件和访问转换服务使用独立请求头。插件不主动上传文件到公共 SaaS，不执行文档宏；本地社区资源随 App 打包，不加载 CDN。

适合哪些场景

文档编辑、Office 批注写回、电子签章、全文搜索、目录书签、密码解锁、批量多文档切换和防截屏不在当前承诺范围。需要 PDF 签批或文件选择，可查看底部相应作者插件。

下载与导入

1. 发布前使用作者提供的源码目录；正式上架后从插件市场导入。将完整的 uni_modules/lizhao-office-view 放入项目，不要改名或只复制 utssdk。
2. 先选全屏 API 接入。普通 uni-app 使用 .vue 页面脚本，uni-app x 使用 .uvue 和 lang="uts"。
3. 只从插件根目录导入：

import * as OfficeView from '@/uni_modules/lizhao-office-view'

4. 准备一个应用确实有读取权限的本地 PDF/TXT。不要直接照搬另一台设备的路径；Android 系统选择器返回的 content:// 也可以传入 source.path。
5. 在包含插件原生实现的 App 中运行。首次接入需完成对应平台原生联编或制作自定义基座；后续仅修改业务页面、示例和文档，可复用已匹配的原生包。详见“自定义基座说明”。

项目最低工具要求见 package.json 的 engines。Android 插件最低 API 24，iOS 最低系统版本为 12；如果宿主还有其他插件，最终最低版本以整个 App 的合并配置为准。

接入方式选择

完整示例路径

先阅读 uni_modules/lizhao-office-view/example/readme.md，再按项目类型注册对应页面：

• uni-app：uni_modules/lizhao-office-view/example/uniapp/index.vue
• uni-app x：uni_modules/lizhao-office-view/example/uniappx/index.uvue
• uni-app x 标准模式组件：uni_modules/lizhao-office-view/components/lizhao-office-view/lizhao-office-view.uvue
• uni-app/NVue 兼容封装：uni_modules/lizhao-office-view/components/lizhao-office-view/lizhao-office-view.vue

示例按文件来源、35 种格式卡片、私有服务配置、任务日志四个区域组织。在线样例需要联网，URL 可能失效；内网或离线验收请使用自己的可读文件。示例不会内置可用的转换服务或真实凭据。

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

5 分钟跑通：打开一个本地文档

先把下面的完整示例放到已经注册的页面，输入应用可读的绝对路径或 Android 内容 URI，再点击按钮。文件选择和授权由业务页面负责；插件不包含文件选择器。

uni-app：按钮打开全屏预览

<template>
  <view>
    <input v-model="filePath" placeholder="应用可读的本地 PDF/TXT 路径" />
    <button @click="openDocument">打开文档</button>
    <text>{{ message }}</text>
  </view>
</template>

<script>
import * as OfficeView from '@/uni_modules/lizhao-office-view'

export default {
  data() {
    return { filePath: '', message: '', sessionId: '' }
  },
  onUnload() {
    if (this.sessionId.length === 0) return
    OfficeView.closeOfficeDocument({
      sessionId: this.sessionId,
      fail: (err) => console.error('关闭文档', err.errCode, err.errMsg)
    })
  },
  methods: {
    openDocument() {
      if (this.filePath.trim().length === 0) {
        this.message = '请先填写本地文件路径'
        return
      }
      OfficeView.openOfficeDocument({
        source: { path: this.filePath.trim() },
        viewer: { title: '附件预览', theme: 'system' },
        : (event) => {
          this.sessionId = event.sessionId
          this.message = event.message
        },
        success: (res) => { this.message = '文档首屏已显示' },
        fail: (err) => { this.message = `${err.errCode}：${err.errMsg}` },
        complete: () => console.log('打开文档调用完成')
      })
    }
  }
}
</script>

uni-app x：相同 API，使用 UTS

<template>
  <view>
    <input v-model="filePath" placeholder="应用可读的本地 PDF/TXT 路径" />
    <button @click="openDocument">打开文档</button>
    <text>{{ message }}</text>
  </view>
</template>

<script setup lang="uts">
import * as OfficeView from '@/uni_modules/lizhao-office-view'

const filePath = ref<string>('')
const message = ref<string>('')
let sessionId = ''

function openDocument(): void {
  if (filePath.value.trim().length == 0) {
    message.value = '请先填写本地文件路径'
    return
  }
  OfficeView.openOfficeDocument({
    source: { path: filePath.value.trim() },
    viewer: { title: '附件预览', theme: 'system' },
    : (event) => {
      sessionId = event.sessionId
      message.value = event.message
    },
    success: (res) => { message.value = '文档首屏已显示' },
    fail: (err) => { message.value = `${err.errCode}：${err.errMsg}` },
    complete: () => console.log('打开文档调用完成')
  })
}

onUnload(() => {
  if (sessionId.length == 0) return
  OfficeView.closeOfficeDocument({
    sessionId,
    fail: (err) => console.error('关闭文档', err.errCode, err.errMsg)
  })
})
</script>

taskId 是每次异步 API 调用立即返回的任务标识，用来关联调用日志；sessionId 是文档预览会话标识，从进度或结果回调获取，用于关闭、取消、状态查询。两者不能互换。success 表示首屏已经可见，complete 表示本次调用已结束，都不代表用户已经关闭文档。

以下模块沿用上面的 OfficeView 根目录导入。路径、网络地址和临时凭据需由你的业务提供；网络示例域名用于说明配置，不是可用演示服务器。

模块一：合同、制度和文本附件

本地 PDF/TXT 直接使用快速开始中的写法。下载接口没有扩展名时，补上 fileName 和 fileType；插件仍会检查真实文件内容。

OfficeView.openOfficeDocument({
  source: {
    url: 'https://files.intranet.example/attachments/contract',
    fileName: '合同.pdf',
    fileType: 'pdf'
  },
  viewer: { title: '合同预览', startPage: 1 },
  success: (res) => console.log('首屏已显示', res.sessionId, res.pageCount),
  fail: (err) => console.error(err.errCode, err.errMsg, err.suggestion)
})

网络文件会先下载到 App 私有目录。想要真正离线使用，应先保存文件并传入 source.path；“阅读资源不访问 CDN”不意味着网络文件无需下载。

模块二：Word 合同与 Excel 报表

docx、xls、xlsx、csv、tsv 使用随插件打包的社区资源。把快速开始中的路径换为对应本地文件即可，也可显式限制阅读方式：

OfficeView.openOfficeDocument({
  source: { path: '/storage/emulated/0/Download/report.xlsx', fileType: 'xlsx' },
  renderer: { provider: 'community', strictProvider: true },
  success: (res) => console.log('报表已显示', res.sessionId),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

DOCX 使用 docx-preview + JSZip；XLS/XLSX/CSV/TSV 使用 SheetJS CE。表格支持工作表切换与横纵滚动，不把工作表数量伪装成分页；复杂公式、图表、批注和排版不保证与桌面 Office 一致。

iOS community 单文件上限为 20MB；Android 原生社区容器和共享渲染脚本的单文件上限为 50MB。超过对应上限返回 9200024。还存在解压、工作表、行列等保护限制，文件小于此大小不代表一定能渲染。大文件或复杂版式可选择私有转换。

模块三：内网 DOC、PPT 与扩展格式

doc、ppt、pptx 及格式矩阵中的其余转换格式，需要自己的内网服务。服务源码和部署说明位于 uni_modules/lizhao-office-view/intranet-service/README.md。

OfficeView.openOfficeDocument({
  source: {
    url: 'https://files.intranet.example/training.pptx',
    fileName: '培训课件.pptx',
    fileType: 'pptx'
  },
  converter: {
    baseUrl: 'https://office-view.intranet.example',
    headers: { Authorization: 'Bearer <当前会话临时令牌>' },
    timeoutMs: 120000
  },
  renderer: { provider: 'converter', strictProvider: true },
  : (event) => console.log(event.stage, event.progress),
  success: (res) => console.log('转换后的 PDF 已显示', res.sessionId),
  fail: (err) => console.error(err.errCode, err.errMsg, err.suggestion)
})

文件上传到你配置的服务，由服务转为 PDF 后返回。保留内网 HTTPS 和正确证书配置；“私有部署”仍需设备能够访问服务。未配置转换服务时返回明确错误，不会改用公网服务。

模块四：登录后可见的业务附件

源文件和转换服务的鉴权分别配置，不共用令牌：

OfficeView.openOfficeDocument({
  source: {
    url: 'https://files.intranet.example/attachments/report',
    fileName: '报表.xlsx',
    fileType: 'xlsx',
    headers: { 'X-Document-Ticket': '<当前会话文件票据>' }
  },
  renderer: { provider: 'community', strictProvider: true },
  : (event) => console.log(event.stage, event.bytesCompleted),
  success: (res) => console.log('鉴权附件已显示', res.sessionId),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

需要转换时再添加 converter.headers。临时票据应在调用时取得，不要写入源码、日志或示例文件。

模块五：阅读主题、页码与文字水印

在 openOfficeDocument 的 viewer 中按需配置：

import { OfficeViewerOptions } from '@/uni_modules/lizhao-office-view'

const viewerOptions: OfficeViewerOptions = {
  title: '内部资料',
  startPage: 1,
  scrollMode: 'vertical',
  theme: 'system',
  watermark: { text: '内部资料 · 仅供阅读', opacity: 0.12, rotation: -25 }
}

将 viewer: viewerOptions 合并到模块一的调用。light/dark/system 分别为浅色、深色、跟随系统。显示水印不会写回源文档，也不等于防截屏；具体格式对阅读方向和页码的支持以阅读器为准。

PDF/DOCX 的 startPage 定位到对应文档页，超出范围时定位到末页；TXT 固定为 1 / 1。社区表格的 startPage 选择工作表序号，currentPage/pageCount 表示当前工作表和工作表总数，界面不显示纸张页码。首次可见回调及状态查询均以实际显示位置为准。阅读器成功态可从“更多”菜单重新加载；失败后应关闭，再由业务重新调用打开 API。

模块六：先准备文件，再进入详情页

预取只准备本地文件，不打开页面。后续用返回的 localPath 打开，避免再次访问原 URL：

OfficeView.prefetchOfficeDocument({
  source: {
    url: 'https://files.intranet.example/guide.pdf',
    fileType: 'pdf'
  },
  success: (prepared) => {
    // 实际业务可保存路径，进入详情页时再执行下面的打开操作。
    OfficeView.openOfficeDocument({
      source: { path: prepared.localPath, fileType: prepared.format },
      success: (res) => console.log('本地文件已显示', res.sessionId),
      fail: (err) => console.error('打开失败', err.errCode, err.errMsg)
    })
  },
  fail: (err) => console.error('预取失败', err.errCode, err.errMsg)
})

当前 cacheHit 返回 false，不承诺相同 URL 自动命中缓存。cache.enabled、cache.maxAgeSeconds 和 source.checksum 是保留字段，当前原生路径尚未应用；不要用它们实现“禁止落盘”、自动过期或源文件完整性校验。转换产物自己的 SHA-256 校验与这些保留字段不同。

临时文件可能被系统或 clearOfficeCache 清理，使用前需允许预取失败后重试。清理全部缓存应在没有活动预览时执行，避免删除正在使用的文件。

模块七：进度、取消、关闭与排障

打开时保存 onProgress 中的会话 ID，再将其传入下列 API。以下函数可加入 UTS 页面；普通 uni-app 去掉类型标注即可。

function cancelPreview(sessionId: string): void {
  if (sessionId.length == 0) return
  OfficeView.cancelOfficeTask({
    sessionId,
    success: () => console.log('任务已取消'),
    fail: (err) => console.error(err.errCode, err.errMsg)
  })
}

function inspectPreview(sessionId: string): void {
  if (sessionId.length == 0) return
  OfficeView.getOfficeSessionState({
    sessionId,
    success: (state) => console.log(state.state, state.currentPage, state.pageCount),
    fail: (err) => console.error(err.errCode, err.errMsg)
  })
}

OfficeView.getOfficeCapabilities({
  success: (res) => console.log(res.platform, res.providers, res.limitations),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

用户退出页面时使用快速开始中的 closeOfficeDocument。需要清理过期临时文件时，可调用 clearOfficeCache({ olderThanSeconds: 86400, success: (res) => console.log(res.removedFiles), fail: (err) => console.error(err.errMsg) })。

关闭与取消都会释放本会话的全屏或嵌入查看器。关闭操作本身成功后，会话状态为 closed；若原打开或预取尚未结束，原请求以 9200009 结束一次。原请求已经成功时，不会因关闭再次触发失败。取消操作成功与原请求取消回调分别对应各自的任务，不应把取消成功当作文档已显示。

完整示例底部提供“复制详细日志”和“复制下一段日志”。反馈问题时说明文件格式、来源、运行端、报错阶段和错误码；不要发送未脱敏的业务文档或凭据。

模块八：uni-app x 页面内嵌入阅读

标准模式 .uvue 可用 <lizhao-office-view>，给组件明确的高度和可读取的 source。组件负责会话绑定与释放，事件为 ready/progress/error/closed，方法为 reload/close/cancel。

<template>
  <lizhao-office-view
    style="height: 500px;"
    :source="documentSource"
    @ready="onDocumentReady"
    @error="onDocumentError"
  />
</template>

<script setup lang="uts">
import { OfficeViewFail } from '@/uni_modules/lizhao-office-view'

const documentSource = { path: '/storage/emulated/0/Download/guide.pdf', fileType: 'pdf' }
function onDocumentReady(): void { console.log('文档已显示') }
function onDocumentError(error: OfficeViewFail): void {
  console.error('预览失败', error.errCode, error.errMsg)
}
</script>

将示例路径替换为当前应用可读的真实路径。此入口使用 native-view，需要在对应 uni-app x 标准模式宿主中验证；独立原生 APK 不包含这段宿主绑定流程。普通 uni-app Vue 页面继续使用全屏 API。当前不承诺蒸汽模式组件兼容。

API 用途速查

API、参数与返回值

openOfficeDocument(options): string

打开文档并返回任务 ID。只有文档校验完成、查看器已挂载、首屏已渲染且真实可见后才触发 success。

其他 API

所有公开页码从 1 开始；没有活动页面时 currentPage 为 0。社区表格的 currentPage/pageCount 是工作表序号/总数，不代表打印页数；选择工作表后查询返回实际选中项。

关闭、取消和状态查询传入 { sessionId, success, fail }；这里的 sessionId 使用打开/进度回调的值，不是 API 立即返回的任务 ID。clearOfficeCache 可传 sessionId 和 olderThanSeconds 限定清理范围；getOfficeCapabilities 可传 converter 查询已配置服务。

错误码说明

errSubject 固定为 lizhao-office-view。按失败阶段排查输入、下载、转换或渲染，不把取消当作成功。

失败对象还包含 stage、recoverable、sessionId、taskId、nativeCode 和 suggestion。

注意事项

Provider 选择

Provider 表示本次使用的阅读方式，默认 auto。普通业务无需主动指定。

strictProvider 默认为 false。社区路径失败且已配置转换服务时，可按原生路由尝试转换；设为 true 时限定显式选中的 Provider。getOfficeCapabilities 用于探测入口能力，不能替代某份文档的真实打开结果。

内网转换服务接入

服务位于 uni_modules/lizhao-office-view/intranet-service。按该目录 README 配置临时令牌、LibreOffice 容器、内网网关和文件限制，再查询能力。源代码包含以下端点：

GET    /v1/capabilities
POST   /v1/preview-jobs
GET    /v1/preview-jobs/{jobId}
GET    /v1/preview-jobs/{jobId}/artifact
DELETE /v1/preview-jobs/{jobId}

设备要能够访问 converter.baseUrl。请用自己的 DOC/PPT/模板样本确认字体、分页和转换效果，再接入实际业务。

格式支持矩阵

宏和模板中的可执行内容不会运行。转换服务以 LibreOffice 最高宏安全级别启动，并关闭外部链接加载；格式识别以文件内容为准，扩展名只作为提示。xlsb 当前不在能力清单中，不能通过传入 fileType: 'xlsb' 绕过。

权限、隐私与平台差异

Android 只声明网络权限，content:// 权限由宿主选择文件时授予。iOS 只在访问期间持有 security-scoped 权限。缓存位于 App 私有目录。插件不会打印令牌、请求头或文档正文。

自定义基座说明

本插件包含 Android Kotlin、Activity、Manifest、AndroidX 依赖，以及 iOS Swift、PDFKit 和原生控制器。首次接入或修改这些原生文件、依赖、Manifest 或打包阅读资源后，需重新原生联编；使用自定义基座的项目必须重打对应自定义基座并重新安装。

仅修改业务页面、示例文字和文档，可复用源码匹配的原生包，无需每轮制作自定义基座。独立本地原生验收 APK 可先验证 Android 阅读器效果，但不能替代 uni-app / uni-app x 宿主的 UTS 调用链、组件绑定或 iOS 验收。静态语法和 appResource 结果也不代表真机功能通过。

作者系列 UTS 插件

以下为作者已在 DCloud 插件市场上架的 UTS 插件，可按业务场景组合使用。最新发布内容可查看作者主页。