@quickspeadsheet/community

基于 Vue 3 的在线 Excel 电子表格 社区版：在浏览器中查看与编辑工作簿，支持 OOXML（.xlsx / .xlsm 等）解析与写回，提供 DOM / Canvas 渲染。

本包为 独立发布的精简包（仅社区版入口与能力），与主包 quickspeadsheet 的 quickspeadsheet/community 子路径能力一致，安装名不同。

社区版能力概要

• 包含：Ribbon、公式栏、工作表标签、导入（Excel/CSV/JSON 等）、查找、公式计算与常见 OOXML 内容展示等。
• 不包含（相对 Pro / Enterprise）：导出 Excel/JSON、打印预览、图表设计器、设置面板、标尺、协同相关 UI 等。

更细的能力表、格式说明见主仓库文档（集成方可自行查阅或随构建复制到 dist/）：

• COMMUNITY_PACKAGE.zh-CN.md
• COMMUNITY_PACKAGE.en.md

安装

npm install @quickspeadsheet/community vue

依赖说明

| 类型 | 包 | 说明 | |------|-----|------| | dependencies（随本包安装） | jszip、cfb、file-saver | 表格读写等核心路径需要 | | peerDependencies（须由项目安装） | vue ^3.4 | 必选 | | peerDependenciesMeta.optional | chart.js、chartjs-chart-financial | 图表增强；不装则部分图表为占位 | | peerDependenciesMeta.optional | pdfjs-dist、heic2any、utif、jpeg2000、@webtoon/psd | 工作表内特殊图片/PDF 等解码；不装则对应格式可能无法前端预览 |

按需安装可选依赖示例：

npm install chart.js
npm install pdfjs-dist

使用 PDF 内嵌图 时，建议在创建/打开工作簿前配置 imageDisplay.pdfWorkerSrc（或等价选项），指向 pdfjs-dist 的 worker，例如 Vite 项目：

pdfWorkerSrc: new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url).href

样式

必须引入包内样式，否则布局与 Ribbon 等无法正常显示。

import '@quickspeadsheet/community/style.css'

package.json 的 exports 中 ./style.css 映射到包内的 community.css（与主包中 community.css 同源）。

Vue：注册插件（推荐）

默认全局注册组件名 SpreadExcelViewer，可通过第二个参数修改组件名。

import { createApp } from 'vue'
import QuickSpeadsheetCommunity from '@quickspeadsheet/community'
import '@quickspeadsheet/community/style.css'
import App from './App.vue'

const app = createApp(App)
app.use(QuickSpeadsheetCommunity)
// app.use(QuickSpeadsheetCommunity, { name: 'MySpreadsheet' })
app.mount('#app')

模板示例：

<template>
  <SpreadExcelViewer
    renderer="canvas"
  />
</template>

• 组件 url prop：用于拉取 工作簿 JSON 的地址（fetch + JSON.parse），不是直接把 .xlsx 的 URL 交给组件解析。
• 打开本地/远程 Excel 文件：请使用 useSpread 的 importFile / importFromUrl（二进制需自行 fetch 后走 ExcelIO.open 等，见下文与主文档）。

组合式 API：useSpread

适合自建容器 DOM、单独做文件按钮、与布局深度集成的场景。

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { useSpread } from '@quickspeadsheet/community'

const containerRef = ref(null)

const { initSpread, destroy, importFile } = useSpread({
  edition: 'community',
  renderer: 'canvas',
})

onMounted(() => {
  const el = containerRef.value
  if (el) initSpread(el)
})

onBeforeUnmount(() => {
  destroy()
})
</script>

<template>
  <div
    ref="containerRef"
    style="width: 100%; height: 70vh; border: 1px solid #ccc"
  />
  <input
    type="file"
    accept=".xlsx,.xlsm,.xlsb,.csv,.json,.ssjson"
    @change="(e) => e.target.files?.[0] && importFile(e.target.files[0], {})"
  />
</template>

useSpread 还返回 excelIO、spread、exportToJSON / exportToExcel（受社区版能力限制，导出类 API 在社区版可能不可用或受策略约束）、协同相关 ref 等，完整字段以类型声明 index.d.ts 与 types/* 为准。

TypeScript

本包提供 types 与 index.d.ts。若 IDE 未解析到类型，可在 tsconfig.json 中确认 moduleResolution 为 bundler 或 node16/nodenext，与 Vue/Vite 模板保持一致即可。

Vite、chunks 与 ExcelIO Worker（assets/）

发布包内含：

• community.js：入口
• chunks/：主逻辑动态分包（文件名带内容哈希）
• assets/：ExcelIO / 解密 / JSON 导出 等 Web Worker 独立脚本（由构建生成，勿删）

从 node_modules 引入时，一般 无需 手工配置 publicPath；若 chunk 或 worker 404，请检查打包工具对 包内相对 URL 的支持（推荐 Vite / Rollup / webpack 5）。

链接

• 仓库主页
• 问题反馈