Skip to main content

框架和打包器

每个独立发行包均在 https://cdn.sheetjs.com/ 上提供。NodeJS 包旨在与框架和打包器一起使用。它是一个合适的 ECMAScript 模块版本，可以使用开发者工具进行优化。

¥Each standalone release package is available at https://cdn.sheetjs.com/. The NodeJS package is designed to be used with frameworks and bundlers. It is a proper ECMAScript Module release which can be optimized with developer tools.

https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz is the URL for version 0.20.3

安装​

¥Installation

可以使用包管理器直接安装 Tarball：

¥Tarballs can be directly installed using a package manager:

yarn remove xlsx
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

Yarn 的较新版本可能会引发错误：

¥Newer releases of Yarn may throw an error:

Usage Error: It seems you are trying to add a package using a https:... url; we now require package names to be explicitly specified.
Try running the command again with the package name prefixed: yarn add my-package@https:...

解决方法是将 xlsx@ 添加到 URL 前面：

¥The workaround is to prepend the URL with xlsx@:

yarn add xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

安装后，可以以 xlsx 名称导入该库：

¥Once installed, the library can be imported under the name xlsx:

import { read, writeFileXLSX } from "xlsx";

"打包器" 演示 包含完整的示例。

¥The "Bundlers" demo includes complete examples.

监视存储库 或订阅 RSS 订阅 以在新版本发布时收到通知！

¥Watch the repo or subscribe to the RSS feed to be notified when new versions are released!

斯尼克虫子

Snyk 安全工具可能会报告涉及 "原型污染" 的错误：

¥Snyk security tooling may report errors involving "Prototype Pollution":

Prototype Pollution [Medium Severity][https://security.snyk.io/vuln/SNYK-JS-XLSX-5457926]

正如 斯尼克报告 中所述：

¥As noted in the Snyk report:

该问题已在 0.19.3 版本中解决

¥The issue is resolved in version 0.19.3

Snyk 错误地报告了漏洞。这是 Snyk 工具中的一个错误。

¥Snyk is falsely reporting vulnerabilities. It is a bug in the Snyk tooling.

在 Snyk 修复 bug 之前，官方推荐是 抑制警告。

¥Until Snyk fixes the bugs, the official recommendation is to suppress the warning.

旧版端点​

¥Legacy Endpoints

从技术上讲，较旧的版本可以在公共 npm 注册表中作为 xlsx 获得，但该注册表已过时。该注册表的最新版本是 0.18.5

¥Older releases are technically available on the public npm registry as xlsx, but the registry is out of date. The latest version on that registry is 0.18.5

这是一个已知的注册表错误

¥This is a known registry bug

SheetJS CDN https://cdn.sheetjs.com/ 是 SheetJS 模块的权威来源。

¥The SheetJS CDN https://cdn.sheetjs.com/ is the authoritative source for SheetJS modules.

对于现有项目，最简单的方法是卸载并重新安装：

¥For existing projects, the easiest approach is to uninstall and reinstall:

yarn remove xlsx
yarn add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

当 xlsx 库是依赖的依赖时，package.json 中的 overrides 字段可以控制模块解析：

¥When the xlsx library is a dependency of a dependency, the overrides field in package.json can control module resolution:

package.json
{
  "overrides": {
    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
  }
}

库​

¥Vendoring

为了总体稳定性，强烈建议制作 SheetJS 模块 ("vendoring") 的本地副本。供应将项目与 SheetJS 基础设施解耦。

¥For general stability, making a local copy of SheetJS modules ("vendoring") is strongly recommended. Vendoring decouples projects from SheetJS infrastructure.

  1. 删除对名为 xlsx 的项目的任何现有依赖：

    ¥Remove any existing dependency on a project named xlsx:

yarn remove xlsx

  1. Download the tarball (xlsx-0.20.3.tgz) for the desired version. The current version is available at https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

curl -o https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz

  1. 在项目的根目录中创建一个 vendor 子文件夹：

    ¥Create a vendor subfolder at the root of your project:

mkdir -p vendor

  1. 将步骤 (1) 中的 tarball 移动到 vendor 文件夹：

    ¥Move the tarball from step (1) to the vendor folder:

mv xlsx-0.20.3.tgz vendor

  1. 如果项目使用版本控制系统进行管理，请将 tarball 添加到源存储库。Git VCS 支持 add 子命令：

    ¥If the project is managed with a version control system, add the tarball to the source repository. The Git VCS supports the add subcommand:

git add vendor/xlsx-0.20.3.tgz

  1. 使用包管理器安装 tarball：

    ¥Install the tarball using a package manager:

yarn add file:vendor/xlsx-0.20.3.tgz

Yarn 的较新版本可能会引发错误：

¥Newer releases of Yarn may throw an error:

Usage Error: The file:vendor/xlsx-0.20.3.tgz string didn't match the required format (package-name@range). Did you perhaps forget to explicitly reference the package name?

解决方法是将 xlsx@ 添加到 URI 前面：

¥The workaround is to prepend the URI with xlsx@:

yarn add xlsx@file:vendor/xlsx-0.20.3.tgz

该软件包将作为 xlsx 安装和访问。

¥The package will be installed and accessible as xlsx.

用法​

¥Usage

对于大多数框架和打包工具，建议使用命名导入：

¥With most frameworks and bundler tools, named imports are recommended:

import { read, utils } from 'xlsx';

一些旧版打包程序需要 glob 导入：

¥Some legacy bundlers require the glob import:

import * as XLSX from 'xlsx';
const { read, utils } = XLSX;

对于支持 CommonJS 的旧版打包器，require 可以工作：

¥For legacy bundlers that support CommonJS, require will work:

var XLSX = require("xlsx");
var read = XLSX.read, utils = XLSX.utils;

"打包器" 演示 包含完整的示例。

¥The "Bundlers" demo includes complete examples.

动态导入​

¥Dynamic Imports

使用 import() 进行动态导入只会在需要时下载脚本。

¥Dynamic imports with import() will only download scripts when they are needed.

Dynamic import 将始终下载导入脚本的完整内容！

¥Dynamic import will always download the full contents of the imported scripts!

这是 ECMAScript 模块的设计缺陷

¥This is a design flaw in ECMAScript modules

强烈建议使用封装器脚本来导入和重新导出在特定函数或页面中使用的 SheetJS 库的部分：

¥It is strongly recommended to use a wrapper script that imports and re-exports the parts of the SheetJS library that are used in a specific function or page:

SheetJSWriteWrapper.js (wrapper script)
/* This wrapper pulls `writeFileXLSX` and `utils` from the SheetJS library */
import { utils, writeFileXLSX } from "xlsx";
export { utils, writeFileXLSX };

封装器脚本的动态导入将仅加载请求的功能：

¥A dynamic import of the wrapper script will only load the requested features:

async function export_data() {
  /* dynamically import the SheetJS Wrapper */
  const XLSX = await import ("./SheetJSWriteWrapper");
  const wb = XLSX.utils.book_new();
  const ws = XLSX.utils.aoa_to_sheet([["a","b","c"],[1,2,3]]);
  XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
  XLSX.writeFileXLSX(wb, "SheetJSDynamicWrapperTest.xlsx");
}

编码支持​

¥Encoding support

如果需要编码支持，则必须手动导入 cpexcel.full.mjs：

¥If Encoding support is required, cpexcel.full.mjs must be manually imported:

/* load the codepage support library for extended support with older formats  */
import { set_cptable } from "xlsx";
import * as cptable from 'xlsx/dist/cpexcel.full.mjs';
set_cptable(cptable);