更新记录

1.0.0（2026-08-25）

• 首次发布 XLSX 预览解析插件。
• 新增 parseXlsx，支持 .xlsx 和 .xlsm 文件。
• 支持 Android 和 iOS：HBuilderX 5.15+、Android API 24+、iOS 13+。
• 返回自包含的 HTML 和工作簿信息，依赖 hans-office-core。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

Office 表格预览

uni-app 和 uni-app x 的 UTS 插件，用于将 .xlsx 和 .xlsm 文件解析为自包含的预览 HTML 和工作簿元数据。Android 和 iOS 的解析使用 hans-office-core 提供的共享原生渲染器。

使用要求

• HBuilderX 5.15 或更高版本。
• 当前项目已安装 hans-office-core。
• Android App：minSdk 24 或更高版本。
• iOS App：最低支持 iOS 13.0。
• 标准基座可以编译插件，但运行时无法加载该原生依赖。请使用 Android 自定义基座和 iOS 自定义基座，或使用包含原生产物的正式构建包。
• Harmony、Web 和小程序端暂不支持。

安装

请将本插件和 hans-office-core 安装到 uni_modules。hans-office-core 包负责提供原生 AAR 和 iOS XCFramework。请勿将这些产物复制到本插件中，也不要在旁边安装其他版本的 hans-office-core。

uni-app Vue3 使用

本插件支持普通 uni-app Vue3 项目的 App-Plus 端。页面使用普通 .vue 文件和 <script setup>，不需要使用 lang="uts"。H5、小程序和 Harmony 端不支持。

下面示例假设 demo.xlsx 已放在项目的 static 目录。writeOfficePreviewHtml 是宿主项目工具，用于将结果 HTML 写入 _doc 私有目录并返回可供 web-view 使用的本地 URL：

<template>
  <button @click="parseFile">解析并预览 XLSX</button>
  <web-view v-if="previewUrl" :src="previewUrl"></web-view>
</template>

<script setup>
import { ref } from 'vue'

// #ifdef APP-PLUS
import { parseXlsx } from '@/uni_modules/hans-office-sheet'
import { writeOfficePreviewHtml } from '@/utils/office-preview'
// #endif

const previewUrl = ref('')

function parseFile() {
  // #ifdef APP-PLUS
  const filePath = plus.io.convertLocalFileSystemURL('_www/static/demo.xlsx')
  parseXlsx({
    filePath,
    title: 'demo.xlsx',
    maxRenderedSheets: 12,
    success: async (result) => {
      try {
        const file = await writeOfficePreviewHtml(result.html, 'demo-xlsx.html')
        previewUrl.value = file.url
      } catch (error) {
        console.error(error)
      }
    },
    fail: (error) => {
      console.error(error.errCode, error.errMsg)
    },
  })
  // #endif
}
</script>

writeOfficePreviewHtml 不是本插件 API，也可以按业务项目的文件 API 自行实现。不要将 HTML 字符串直接作为 web-view 的 src，需要先写入本地文件。用户选择的文件也必须传入 App-Plus 可读取的本地路径。

API

import { parseXlsx } from '@/uni_modules/hans-office-sheet'

parseXlsx({
  filePath: `${uni.env.USER_DATA_PATH}/demo.xlsx`,
  title: 'demo.xlsx',
  maxRenderedSheets: 12,
  success: (res) => {
    console.log(res.title, res.sheetCount, res.renderedSheetCount, res.html.length)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  },
  complete: (_) => {
    console.log('parseXlsx complete')
  },
})

参数

filePath 可以使用 uni.env.USER_DATA_PATH 等路径。插件会在打开文件前，将路径转换为当前原生平台所需的格式。

成功结果

错误码

渲染 HTML

返回的 HTML 会将文档资源以内嵌的 data: URL 形式包含其中。插件不提供 UI 组件、URL scheme 或展示控制栏。 普通 uni-app Vue3 请先将 HTML 写入本地文件，再通过 <web-view :src="..."> 加载，参见上面的“uni-app Vue3 使用”。 下面的 UniWebViewElement.loadData 示例仅适用于 uni-app x：

// 在初始 <web-view src="about:blank"> 加载事件之后执行。
const webview = uni.getElementById('office-preview-webview') as UniWebViewElement | null
webview?.loadData({
  data: res.html,
  baseURL: 'about:blank',
  mimeType: 'text/html',
  encoding: 'utf-8',
})

宿主应用负责 WebView 生命周期、文件创建、导航和展示样式。

限制与安全

• 这是预览解析器，不是 Office 编辑器。
• 不会执行 VBA 宏。
• 渲染数量受 maxRenderedSheets 限制；对于大型工作簿，请设置合适的上限。
• 解析器只读取本地文件，不会上传文档内容。
• 除非宿主应用有明确理由，否则请保持文档 JavaScript、网络访问、文件访问和持久化存储处于禁用状态。

兼容性与问题排查

通过内置的 hans-office-core XCFramework 和 UTS 适配器启用 iOS 插件包支持（u）。

• 9010302 或标准基座找不到原生类：请使用自定义基座或正式构建包。
• 9010303：确认文件存在，并且应用进程可以读取该路径。
• 9010304 且错误信息提示版本不匹配：请同步更新 hans-office-core 和格式插件。

原生第三方许可证和声明文件由 hans-office-core 提供，必须保留。

支持

使用问题和兼容性问题，请通过插件 IM 交流群联系。