# @file-viewer/renderer-spreadsheet 中文文档

规范地址：https://npmcn.com/package/%40file-viewer/renderer-spreadsheet/

版本：3\.3\.3
npm 元数据更新时间：2026-10-31T11:14:00.826Z
中文译文更新时间：2026-11-14T17:42:07.571Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/renderer-spreadsheet
原文对照：https://npmcn.com/package/%40file-viewer/renderer-spreadsheet/?lang=original
项目主页：https://doc.file-viewer.app/guide/on-demand-renderers
源码仓库：https://github.com/flyfish-dev/file-viewer

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，53 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-06-23T06:20:49.515Z
- 最新版本发布：2026-10-31T11:14:00.511Z
- 近 30 天下载量：173027（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

文件查看器的独立电子表格渲染器插件,由风格-exceljs和e-virt-table提供动力.

## 安装

```sh
npm install @file-viewer/renderer-spreadsheet
```

也可以使用：`pnpm add @file-viewer/renderer-spreadsheet`、`yarn add @file-viewer/renderer-spreadsheet`、`bun add @file-viewer/renderer-spreadsheet`

## README

# @file-viewer/renderer-spreadsheet

[English](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/spreadsheet/README.md) · [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/renderers/spreadsheet/README.zh-CN.md)

Flyfish File Viewer 的独立表格 renderer 包。它基于 `styled-exceljs` 与 `e-virt-table` 提供 XLSX、XLSM、XLSB、XLS、CSV、TSV、ODS、FODS、Numbers 等表格文件的浏览器端预览，并通过 File Viewer 统一的 asset manifest 解析可选 Worker 路径，适合企业内网和离线部署。

## 用法

```ts
import FileViewer from '@file-viewer/vue3'
import { spreadsheetRenderer } from '@file-viewer/renderer-spreadsheet'

const options = {
  rendererMode: 'replace',
  renderers: spreadsheetRenderer,
}
```

也可以和其他 renderer 一起组合：

```ts
import { pdfRenderer } from '@file-viewer/renderer-pdf'
import { spreadsheetRenderer } from '@file-viewer/renderer-spreadsheet'

const options = {
  rendererMode: 'replace',
  renderers: [pdfRenderer, spreadsheetRenderer],
}
```

## 能力边界

-   支持 `.xlsx`、`.xltx`、`.xlsm`、`.xlsb`、`.xls`、`.xlt`、`.xltm`、`.csv`、`.tsv`、`.ods`、`.fods`、`.numbers`。
-   CSV / TSV 默认自动识别 UTF-8（含 BOM）与 GBK / GB18030；遇到来源编码已知的文件时，可通过 `options.spreadsheet.textEncoding` 固定为 `utf-8`、`gbk` 或 `gb18030`。
-   默认 `options.spreadsheet.worker: 'auto'`：小文件走主线程兼容路径，大文件达到 `options.spreadsheet.workerAutoThreshold`（默认 1MB）后自动尝试静态 Worker。
-   可以通过 `options.spreadsheet.worker: true` 强制启用静态 Worker，通过 `worker: false` 关闭自动启用；静态路径特殊时配置 `options.spreadsheet.workerUrl`。
-   支持多 sheet、横向滚动标签栏、合并单元格、列宽/行高、边框、填充、对齐、文本颜色、Office 365 / WPS 单元格内嵌图片、workbook drawing 图片、图片双击大图预览、统一缩放 provider 和可选表头拖拽调整列宽。
-   XLSX drawing 中的 TIFF 图片会按需加载 MIT 许可的 UTIF.js，在浏览器内转换为 PNG；普通表格不会加载 TIFF 解码器。
-   表格使用虚拟渲染，适合交互预览；完整打印按钮通常由上层能力判断隐藏，避免只打印当前视口。
-   XLSX 保留文件保存的默认列宽、显式列宽和以磅记录的行高；CSV/TSV 继续按内容调整列宽，大文本解析避免重复创建完整 UTF-8 字节数组。
-   列宽单位以工作簿 Normal 样式为基准。宋体、新宋体的数字宽度先从磅转换为像素，再进行取整；尚未测定的自定义字体沿用标准回退，实际尺寸可能受字体影响。

## 小内容 Excel 填满视口

`options.spreadsheet.fillViewport` 默认 `true`，适用于 Excel、CSV / TSV 等表格格式。按工作表默认行高、列宽补充空白列标题（A / B / …）、行号和网格，让小表或空 Sheet 填满当前预览区域。容器 resize、缩放和切 Sheet 时重新计算，补充部分沿用虚拟画布，不生成整张 Excel 空表，不拉伸已有单元格，也不改变工作簿数据。设为 `false` 可只显示已用区域。

```ts
const options = {
  rendererMode: 'replace',
  renderers: spreadsheetRenderer,
  spreadsheet: { fillViewport: false }, // 可选：只显示已用区域。
}
```

补充部分只用于显示，不改变工作簿数据、used-range、原文件下载/导出、搜索结果或内容统计。

## 离线资产

默认可选 Worker 路径为：

-   `vendor/xlsx/sheet.worker.js`

私有化部署时可以通过 `options.spreadsheet.workerUrl` 覆盖。官方 Vite 插件和 Demo worker 构建脚本会从本包的 worker 入口生成该文件。

## 迁移说明

表格预览已经从 `@file-viewer/core` 中彻底移出，core 只保留资产 manifest、类型和兼容错误提示，不再默认安装 `styled-exceljs`、`e-virt-table` 或 `tinycolor2`。完整表格能力请安装本包并传入 `renderers`，或直接使用 `@file-viewer/preset-all`。

## 未保存计算结果的公式

优先保留文件已保存的公式结果，包括真实的零值。导出器未保存计算结果时，预览可在离线、受限的运算预算内补算本表/跨表引用、区域、算术/比较，以及 `IF`、`ROUND`、`ROW`、`SUM`，并保留单元格数字格式；主线程和 Worker 使用同一逻辑。

这不是完整的 Excel 计算引擎。循环引用、外部引用、不支持或超出预算的公式，会直接显示原始 `=公式` 文本，不再伪装成零。不会执行 JavaScript 或请求远程公式资源。

## 常见问题

### @file-viewer/renderer-spreadsheet 是什么？

文件查看器的独立电子表格渲染器插件,由风格-exceljs和e-virt-table提供动力\.

### 如何安装 @file-viewer/renderer-spreadsheet？

在项目目录运行 npm install @file-viewer/renderer-spreadsheet，或使用 pnpm add / yarn add / bun add。

### @file-viewer/renderer-spreadsheet 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @file-viewer/renderer-spreadsheet 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @file-viewer/renderer-spreadsheet 可以商用吗？

@file-viewer/renderer-spreadsheet 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @file-viewer/renderer-spreadsheet 的下载量有多少？

根据 npm 官方下载统计，@file-viewer/renderer-spreadsheet 在 2026/10/15 – 2026/11/13 这 30 天内被下载 173,027 次，日均约 5,768 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @file-viewer/renderer-spreadsheet 还在维护吗？

最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。