使用 Lume 照亮数据

Lume 是一个轻量级的、无偏见的静态站点生成器。它拥有丰富的 JavaScript 驱动的插件生态系统 [^1]

¥Lume is a lightweight unopinionated static site generator. It has a rich ecosystem of JavaScript-powered plugins[^1]

SheetJS 是一个用于从电子表格读取和写入数据的 JavaScript 库。

¥SheetJS is a JavaScript library for reading and writing data from spreadsheets.

该演示使用 Lume 和 SheetJS（通过官方 "Sheets" 插件）从电子表格中提取数据并将内容显示在 HTML 表格中。

¥This demo uses Lume and SheetJS (through the official "Sheets" plugin) to pull data from a spreadsheet and display the content in an HTML table.

"完整示例" 部分包括一个由 XLSX 电子表格提供支持的完整网站。

¥The "Complete Example" section includes a complete website powered by an XLSX spreadsheet.

集成详情

¥Integration Details

官方的 "Sheets" 插件 [^2] 使用 SheetJS 从电子表格加载数据。在底层，该插件使用 SheetJS read[^3] 方法来解析文件，并使用 sheet_to_json[^4] 方法来生成对象数组。

¥The official "Sheets" plugin[^2] uses SheetJS to load data from spreadsheets. Under the hood, the plugin uses the SheetJS read[^3] method to parse files and the sheet_to_json[^4] method to generate arrays of objects.

Lume 支持开发过程中刷新数据。生成的静态站点包含原始数据，而不引用底层电子表格文件。

¥Lume supports refreshing data during development. The generated static sites include the raw data without referencing the underlying spreadsheet files.

安装

¥Installation

sheets 插件可以在 _config.ts 中导入并调用：

¥The sheets plugin can be imported and invoked in _config.ts:

_config.ts
import lume from "lume/mod.ts";
import sheets from "lume/plugins/sheets.ts";

const site = lume();

site.use(sheets());

export default site;

如果在设置过程中启用了 sheets 插件，则会自动添加这些行。

¥The lines are automatically added if sheets plugin is enabled during setup.

用法

¥Usage

添加到 _data 子目录中的电子表格文件可以使用名称 Stem 从模板文件中访问。

¥Spreadsheet files added in the _data subdirectory are accessible from template files using the name stem.

例如，可以使用模板中的变量 pres 来访问 pres.xlsx。

¥For example, pres.xlsx can be accessed using the variable pres in a template.

单页练习册

¥Single-Sheet Workbooks

当工作簿有一个工作表时，数据是一组行对象：

¥When a workbook has one worksheet, the data is an array of row objects:

single.njk
<table><thead><tr><th>Name</th><th>Index</th></tr></thead>
  <tbody>
  {% for row in pres %}
    <tr>
      <td>{{ row.Name }}</td>
      <td>{{ row.Index }}</td>
    </tr>
  {% endfor %}
  </tbody>
</table>

多页工作簿

¥Multi-Sheet Workbooks

阅读第一个工作表

¥Reading the First Worksheet

sheets 插件接受选项参数。如果 sheets 属性设置为 "first"，则插件将公开第一个工作表的行对象：

¥The sheets plugin accepts an options argument. If the sheets property is set to "first", then the plugin will expose row objects for the first sheet:

_config.ts
// the first sheet of each file will be parsed and converted to row objects
site.use(sheets({ sheets: "first" }));

阅读所有工作表

¥Reading all Worksheets

当工作簿有多个工作表时，默认行为是显示键为工作表名称、值为行对象数组的对象。

¥The default behavior, when workbooks have multiple sheets, is to present objects whose keys are worksheet names and whose values are arrays of row objects.

例如，如果 pres.xlsx 有一个名为 "Presidents" 的工作表和另一个名为 "VicePresidents" 的工作表，则以下代码片段将打印 "Presidents" 工作表中的数据：

¥For example, if pres.xlsx had a sheet named "Presidents" and another sheet named "VicePresidents", then the following snippet would print data from the "Presidents" sheet:

multi.njk
<table><thead><tr><th>Name</th><th>Index</th></tr></thead>
  <tbody>
  {% for row in pres["Presidents"] %}
    <tr>
      <td>{{ row.Name }}</td>
      <td>{{ row.Index }}</td>
    </tr>
  {% endfor %}
  </tbody>
</table>

文件格式

¥File Formats

正如官方插件文档 [^5] 中所解释的，加载器加载 XLSX。数字和 CSV 文件。其他扩展可以通过 sheets 插件参数中的 extensions 属性添加：

¥As explained in the official plugin documentation[^5], the loader loads XLSX. NUMBERS, and CSV files. Other extensions can be added through the extensions property in the argument to the sheets plugin:

site.use(sheets({
  extensions: [".xlsx", ".xlsb", ".xls"]
}));

完整示例

¥Complete Example

测试部署

本 demo 在以下环境下进行了测试：

¥This demo was tested in the following environments:

Lume	日期
`1.19.4`	2025-01-02
`2.4.3`	2025-01-02

此示例使用 Nunjucks 模板格式。Lume 插件支持其他模板格式，包括 Markdown 和 JSX。

¥This example uses the Nunjucks template format. Lume plugins support additional template formats, including Markdown and JSX.

初始设置

¥Initial Setup

安装 Deno[^6]

¥Install Deno[^6]
创建股票网站：

¥Create a stock site:

mkdir -p sheetjs-lume
cd sheetjs-lume
deno run -Ar https://deno.land/x/lume@v2.4.3/init.ts

出现提示时，输入以下选项。初始化脚本随着时间的推移而发生了变化，因此不会询问所有问题。

¥When prompted, enter the following options. The initialization script has changed over time, so not all questions will be asked.

What kind of setup do you want?：选择 Basic + plugins

¥What kind of setup do you want?: select Basic + plugins
Choose the configuration file format：选择 _config.ts

¥Choose the configuration file format: select _config.ts
Do you want to install some plugins now?：选择 Yes

¥Do you want to install some plugins now?: select Yes
Select the plugins to install：选择 sheets 和 nunjucks

¥Select the plugins to install: select sheets and nunjucks
Do you want to setup a CMS?：选择 No 或 Maybe later

¥Do you want to setup a CMS?: select No or Maybe later

将配置项目并安装模块。

¥The project will be configured and modules will be installed.

Lume 版本 1 中默认包含 nunjucks 插件。

¥The nunjucks plugin was included by default in Lume version 1.

下载 https://xlsx.nodejs.cn/pres.xlsx 并将其放入 _data 子文件夹中：

¥Download https://xlsx.nodejs.cn/pres.xlsx and place in a _data subfolder:

mkdir -p _data
curl -L -o _data/pres.xlsx https://xlsx.nodejs.cn/pres.xlsx

创建引用该文件的 index.njk 文件：

¥Create a index.njk file that references the file:

index.njk
<h2>Presidents</h2>
<table><thead><tr><th>Name</th><th>Index</th></tr></thead>
  <tbody>
  {% for row in pres %}
    <tr>
      <td>{{ row.Name }}</td>
      <td>{{ row.Index }}</td>
    </tr>
  {% endfor %}
  </tbody>
</table>

由于文件名为 pres.xlsx，因此参数名为 pres。

¥Since the file name is pres.xlsx, the parameter name is pres.

实时刷新

¥Live Refresh

运行开发服务器：

¥Run the development server:

deno task serve --port 7262

要验证站点，请从 Web 浏览器访问 "本地" URL（通常为 http://localhost:7262）。该页面将显示电子表格的内容。

¥To verify the site, access the "Local" URL (typically http://localhost:7262) from a web browser. The page will show the contents of the spreadsheet.

当服务器运行时，在电子表格编辑器中打开 _data/pres.xlsx。

¥While the server is running, open _data/pres.xlsx in a spreadsheet editor.

将单元格 A7 设置为 "SheetJS 开发"，将 B7 设置为 47。保存电子表格。

¥Set cell A7 to "SheetJS Dev" and set B7 to 47. Save the spreadsheet.

保存电子表格后，页面将刷新并显示新内容。

¥After saving the spreadsheet, the page will refresh and show the new contents.

静态站点

¥Static Site

停止服务器（在终端窗口中按 CTRL+C）。

¥Stop the server (press CTRL+C in the terminal window).
构建静态站点：

¥Build the static site:

deno task lume

这将在 _site 文件夹中创建一个静态站点

¥This will create a static site in the _site folder

通过启动 Web 服务器来测试生成的站点：

¥Test the generated site by starting a web server:

npx -y http-server _site

程序将显示一个 URL（通常为 http://localhost:8080）。访问该页面将显示电子表格的内容。

¥The program will display a URL (typically http://localhost:8080). Accessing the page will show the contents of the spreadsheet.

查看页面源并确认该页面仅包含 HTML 表格。此页面中不包含任何脚本。

¥View the page source and confirm that the page only includes an HTML table. No scripts are included in this page.

该站点是独立的，可以部署！

¥This site is self-contained and ready for deployment!

[^1]: 请参阅 Lume 文档中的 "插件"

¥See "Plugins" in the Lume documentation

[^2]: 请参阅 Lume 文档中的 "Sheets"

¥See "Sheets" in the Lume documentation

[^3]: 见 read 于 "读取文件"

¥See read in "Reading Files"

[^4]: 见 sheet_to_json 于 "实用工具"

¥See sheet_to_json in "Utilities"

[^5]: 请参阅 Lume 文档中的 "格式"

¥See "Formats" in the Lume documentation

[^6]: 请参阅 Deno 文档中的 "安装"

¥See "Installation" in the Deno documentation

集成详情​

安装​

用法​

单页练习册​

多页工作簿​

文件格式​

完整示例​

初始设置​

实时刷新​

静态站点​