在 Gatsby 中使用 Excel 表格数据：using-excel 示例与 gatsby-transformer-excel 插件深度解析

前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载本指南围绕仓库中的 examples/using-excel 示例项目展开完整演示了如何把.xlsx表格文件作为数据源接入 Gatsby从插件安装、配置到工作表被解析为 GraphQL 节点、再在 React 页面中查询渲染的整条链路。读完本文你将掌握gatsby-transformer-excel插件的配置方法、底层解析算法、常用选项defval、raw以及多工作表数据的查询与渲染技巧。一、示例项目概览examples/using-excel是一个极简但完整的可运行示例它的全部代码只有三个部分examples/using-excel/gatsby-config.jsGatsby 插件配置examples/using-excel/src/pages/index.js首页组件内含 GraphQL 查询与两个 HTML 表格的渲染examples/using-excel/src/data/letters.xlsx示例数据源包含两个工作表Sheet1、Sheet2每行记录一个字母及其 ASCII 码值。依赖声明在 examples/using-excel/package.json 中核心是gatsby、gatsby-source-filesystem、gatsby-transformer-excel三个包均以next版本引用外加react与react-dom^18.2.0。项目的 scripts 提供标准的开发/构建命令scripts: { develop: gatsby develop, build: gatsby build, start: npm run develop }该示例由 SheetJS 维护恰好也是 packages/gatsby-transformer-excel 插件 README 中引用的官方演示项目——它是验证该插件最直接、最完整的参考实现。二、安装依赖与运行示例在仓库中安装并启动该示例npm install npm run develop然后在浏览器访问http://localhost:8000即可看到两个表格分别展示 Sheet1 与 Sheet2 中的字母和 ASCII 值。生产构建使用npm run build从插件自身声明看packages/gatsby-transformer-excel/package.jsongatsby-transformer-excel以gatsby ^5.0.0-next为 peerDependency底层依赖xlsx ^0.18.3要求 Node.js 版本18.0.0 26。在单独项目中使用时可按需安装npm install gatsby-transformer-excel gatsby-source-filesystem三、配置让 Gatsby 认识 Excel 文件示例的完整配置如下examples/using-excel/gatsby-config.jsmodule.exports { siteMetadata: { title: gatsby-example-using-excel, description: Blazing fast modern site generator for React, }, plugins: [ gatsby-transformer-excel, { resolve: gatsby-source-filesystem, options: { path: ${__dirname}/src/data, name: data, }, }, ], }配置里同时出现了两个插件分工明确gatsby-source-filesystem负责把src/data目录下的文件读取为 Gatsby 的File节点。path指向 Excel 文件所在目录name只是该源的标识名gatsby-transformer-excel负责把File节点“转换”为可查询的结构化数据节点。这里的插件书写顺序transformer 在前、source 在后并不影响结果Gatsby 会先由 source 插件创建文件节点再由 transformer 插件通过shouldOnCreateNode拦截并处理这些节点具体机制见下一节。配置项之间是“source 读文件 → transformer 转数据”的依赖关系而不是书写顺序关系。四、底层原理gatsby-transformer-excel 的解析算法插件核心实现在 packages/gatsby-transformer-excel/src/gatsby-node.js。它通过shouldOnCreateNode决定是否处理某个节点只要文件扩展名命中内置列表即进入处理流程function shouldOnCreateNode({ node }) { return extensions.includes((node.extension || ).toLowerCase()) }支持的扩展名列表非常宽泛见源码第 4–29 行除.xlsx外还包括xls, xlsx, xlsm, xlsb, xml, xlw, xlc, csv, txt, dif, sylk, slk, prn, ods, fods, uos, dbf, wks, 123, wq1, qpw, htm, html, numbers也就是说即使数据文件是 CSV 或 OpenDocument 表格也能被同一套逻辑解析。解析动作发生在onCreateNode中核心流程如下源码第 35–105 行用 SheetJS 库读取工作簿有absolutePath时走XLSX.readFile(node.absolutePath, { cellDates: true })否则对loadNodeContent得到的文本走XLSX.read(content, { type: binary, cellDates: true })遍历wb.SheetNames中的每个工作表用XLSX.utils.sheet_to_json(ws, xlsxOptions)把工作表转成 JSON 数组——首行成为字段名其后每一行成为一个对象为数组中的每个对象创建数据节点并调用createParentChildLink建立“文件节点 → 数据节点”的父子关系另外为每个工作表单独创建一个汇总节点只含name、idx同样挂到文件节点之下。节点类型命名规则节点类型的生成是理解 GraphQL 查询的关键源码第 75–78 行与第 95–96 行给出了两条规则// 数据行节点 type _.upperFirst(_.camelCase(${node.name} ${node.extension})) __ _.upperFirst(_.camelCase(${n})) // 工作表汇总节点 type _.upperFirst(_.camelCase(${node.name} ${node.extension}))其中node.name是去掉扩展名的文件名n是工作表名。以示例的letters.xlsx为例工作表数据行节点类型工作表汇总节点类型Sheet1LettersXlsx__Sheet1LettersXlsxSheet2LettersXlsx__Sheet2LettersXlsxGatsby 的节点类型与 GraphQL 顶层查询一一对应因此类型LettersXlsx__Sheet1对应的查询字段就是allLettersXlsxSheet1。工作表名、文件名的大小写与命名方式会直接影响你在 GraphQL 中写出的查询字段——这是最容易踩坑、也最值得先理解的地方。节点内部结构中id默认由createNodeId(${node.id} [${n} ${i}] ${node.extension})生成如果原始数据中恰好有id字段则会优先使用它源码第 68–70 行。选项透传机制插件会把gatsby-config.js中传给它的所有选项原样转发给 SheetJS 的sheet_to_json源码第 41–52 行。这意味着 SheetJS 支持的一切输出选项如header、range、raw、defval等都可以直接配置无需插件额外封装。透传前插件只做了两处兼容性归一化rawOutput是旧版属性名若未显式设置raw则把rawOutput的值赋给raw两者同时存在时raw优先defaultValue是旧版属性名同理归一化为defval。五、准备 Excel 数据源示例数据文件位于 examples/using-excel/src/data/letters.xlsx包含两个结构相同的工作表------ Sheet1 ------ /| A | B | ----------------- 1| letter | value | ----------------- 2| a | 97 | ----------------- 3| b | 98 | ------ Sheet2 ------ /| A | B | ----------------- 1| letter | value | ----------------- 2| A | 65 | ----------------- 3| B | 66 |第一行letter、value是列名之后的每一行数据都会被解析成一个节点。按插件 READMEpackages/gatsby-transformer-excel/README.md中的描述解析后生成的节点等价于[ { letter: a, value: 97, type: LettersXlsxSheet1 }, { letter: b, value: 98, type: LettersXlsxSheet1 }, { letter: A, value: 65, type: LettersXlsxSheet2 }, { letter: B, value: 66, type: LettersXlsxSheet2 } ]六、用 GraphQL 查询工作表数据示例首页 examples/using-excel/src/pages/index.js 底部导出了完整查询query { allLettersXlsxSheet1 { edges { node { letter value } } } allLettersXlsxSheet2 { edges { node { letter value } } } }两个查询分别对应letters.xlsx的两个工作表。查询结果的结构为{ allLettersXlsxSheet1: { edges: [ { node: { letter: a, value: 97 } }, { node: { letter: b, value: 98 } }, ], }, }查询到的字段名就是 Excel 首行的列名letter、value。值得注意的两点若某列名与节点字段系统冲突或包含特殊字符可以借助 GraphQL 别名或查看 GraphiQL 的自动补全gatsby develop时访问http://localhost:8000/___graphql确认最终可查询的字段由于每个工作表都会生成一个汇总节点类型LettersXlsx你同样可以查询allLettersXlsx来遍历所有工作表的基本信息。七、在 React 页面中渲染表格查询结果在组件中通过this.props.data读取示例中用两张table分别渲染两个工作表examples/using-excel/src/pages/index.jsclass IndexComponent extends React.Component { render() { const data1 this.props.data.allLettersXlsxSheet1.edges const data2 this.props.data.allLettersXlsxSheet2.edges return ( div table thead tr th colSpan2Sheet1/th /tr tr thLetter/th thASCII Value/th /tr /thead tbody {data1.map((row, i) ( tr key{${row.node.value} ${i}} td{row.node.letter}/td td{row.node.value}/td /tr ))} /tbody /table {/* 第二个表格结构与上方相同数据取自 allLettersXlsxSheet2 */} /div ) } }这里展示了表格数据接入 Gatsby 的标准模式GraphQL 取数 →edges[].node逐行映射 → 渲染为行。key使用value与下标组合保证行唯一性。把表格行换成卡片、列表或任何其他组件即可复用同一套数据模型。八、常用选项与故障排查插件的完整使用说明见 packages/gatsby-transformer-excel/README.md其中针对实际项目最常遇到的两个问题给出了明确解法。defval为空白单元格填充默认值如果工作表的某些列存在空白单元格默认行为是直接跳过这些空值导致 GraphQL 输出中该列缺失。插件 README 引用 SheetJS 的说明未指定defval时null和undefined值会被跳过一旦指定所有空值都会被填充为defval。// 在 gatsby-config.js 中 module.exports { plugins: [ { resolve: gatsby-transformer-excel, options: { defval: , }, }, ], }配置后所有空白单元格都会被统一填充为空字符串字段因此保持稳定存在。raw / rawOutput统一字段类型解决类型冲突GraphQL 是强类型系统如果同一列在不同行出现不同类型例如既有数字又有字符串构建时会触发字段类型冲突警告该字段的值甚至会被省略。解法是关闭raw选项让所有值统一转为字符串// 在 gatsby-config.js 中 module.exports { plugins: [ { resolve: gatsby-transformer-excel, options: { raw: false, }, }, ], }两个属性名的关系需要特别留意正确属性名为raw旧版本使用的rawOutput仍然可用但它只是raw的别名若同时指定两者raw的取值优先。这一点在源码packages/gatsby-transformer-excel/src/gatsby-node.js 第 43–52 行与测试用例中均有印证rawOutput会在处理前被删除并归一到raw。九、测试验证与源码证据插件的解析行为由单元测试直接锁定见 packages/gatsby-transformer-excel/src/tests/gatsby-node.js 与对应快照 packages/gatsby-transformer-excel/src/tests/snapshots/gatsby-node.js.snap。测试覆盖三个场景默认解析CSV 内容被转换为数据节点 工作表汇总节点断言createNode与createParentChildLink均被调用 3 次2 行数据 1 个工作表节点raw: false布尔值true/false在快照中变成字符串TRUE/FALSE验证了“全部转字符串”的行为旧属性rawOutput: false与raw: false产生一致的节点结构证明别名机制有效。快照还直观展示了节点的内部结构id、parent、children、internal.type如TestCsv__Sheet1、TestCsv等字段与示例中letters.xlsx的节点命名规则一一对应。如果你在自己的项目里遇到“查询不到字段”或“类型冲突”的问题这些测试与快照就是排查时最好的参照物。结语通过examples/using-excel这个最小示例可以看到 Gatsby 处理 Excel 数据的完整范式gatsby-source-filesystem负责读文件gatsby-transformer-excel借助 SheetJS 把每个工作表解析成一行一节点的结构化数据类型名由“文件名 扩展名 工作表名”共同决定最终通过 GraphQL 无缝接入 React 组件。理解节点类型命名规则与raw/defval两个选项就足以把任意.xlsx/.csv表格快速变成站点可查询、可渲染的数据源。赞分享前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载相关推荐在 Gatsby 中使用 HJSONusing-hjson 示例与 gatsby-transformer-hjson 插件全解析在 Gatsby 中使用 HJSONusing hjson 示例与 gatsby transformer hjson 插件全解析 Gatsby 官方仓库的 e前端静态站点Web框架从静态到动态SwiftUI 5 Metal Shader Collection中的TimelineView应用技巧从静态到动态SwiftUI 5 Metal Shader Collection中的TimelineView应用技巧 SwiftUI 5 Metal Shade前端静态站点Web框架Obsidian Excel插件在笔记中打造专业级数据表格Obsidian Excel插件在笔记中打造专业级数据表格 还在为Obsidian中简陋的表格功能而苦恼吗想要在笔记中直接编辑Excel格式的表格却不知道知识管理前端上一篇Windows 11系统瘦身终极指南一键免费提升51%性能的完整方案下一篇如何使用MyKeymap打造你的专属键盘映射方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考