hucre 表格导出 HTML/Markdown 与 HTML 表格爬取实战：双向流动指南

hucre 表格导出 HTML/Markdown 与 HTML 表格爬取实战：双向流动指南

【免费下载链接】hucreZero-dependency spreadsheet engine. Read & write XLSX, CSV, ODS. Pure TypeScript, works everywhere.项目地址: https://gitcode.com/gh_mirrors/hu/hucre

hucre 是一个零依赖的纯 TypeScript 电子表格引擎，除了读写 XLSX、CSV、ODS 之外，还提供了一套轻量的文本格式互转能力：toHtml与toMarkdown能把工作表一键导出为网页表格或 Markdown 表格，fromHtml则能反向解析任意网页里的 HTML 表格为结构化工作表——让表格数据在 Excel 与网页之间双向流动，是报表发布与数据抓取的实用组合拳。

一分钟了解 hucre

hucre 的核心卖点是「零依赖 + 全格式」：

• 零依赖：没有 npm 依赖树，ESM 原生，可直接跑在 Node、Deno、Bun、Cloudflare Workers 和浏览器里；
• 读多格式：XLSX / ODS / CSV / JSON / XML / XLS / XLSB，read()自动嗅探；
• 写多格式：XLSX / ODS / CSV / TSV / JSON / NDJSON / XML /HTML / Markdown；
• 可摇树（Tree Shaking）：只导入用到的部分，CSV 模块 gzip 后约 3.7 KB。

安装只需一行：

npm install hucre

本文聚焦四个函数：toHtml、toMarkdown、fromHtml，以及 CLI 的convert命令。它们都从包入口直接导出，也可以按需从 src/export/index.ts 对应子模块导入。

从工作表导出 HTML：带样式、深色模式与无障碍

toHtml把一个 Sheet 渲染成标准<table>，默认输出干净、可直接嵌进任何网页：

import { readXlsx, toHtml } from "hucre" const wb = await readXlsx(fileBuffer) const html = toHtml(wb.sheets[0], { hasHeaderRow: true, // 首行渲染为 <thead> styles: true, // 单元格内联 CSS（字体、填充、边框、对齐） classes: true, // 按类型加 hucre-num / hucre-bool / hucre-date 类 })

几个默认关闭但很有用的开关（完整定义见 HtmlExportOptions）：

细节上它处理了不少容易翻车的点：单元格内容会做 HTML 实体转义（& < > " '）防注入；合并单元格自动转成colspan/rowspan（见 buildMergeMap）；日期统一输出为YYYY-MM-DD。

一个典型场景：把月度报表直接嵌入邮件或内部门户，加上includeStyleTag: true就能拿到自带深色模式样式的完整表格，不用手写一行 CSS。

从工作表导出 Markdown：自动对齐与转义

toMarkdown输出标准 GFM 表格，数字列自动右对齐、字符串列左对齐：

import { toMarkdown } from "hucre" const md = toMarkdown(wb.sheets[0]) // | Name | Price | Stock | // |--------|-------:|------:| // | Widget | 9.99 | 142 |

值得了解的行为（实现见 src/export/markdown.ts）：

• 自动对齐：扫描每列首个非空值，数字列输出---:右对齐分隔符；也可用alignment显式指定；
• 转义保护：单元格里的*、_、`、[等内联语法字符会被转义，*not emphasis*就是字面文本；管道符|与换行符无条件转义（换行变成<br>），保证表格结构不碎；
• 宽度截断：超过maxWidth（默认 50 字符）的单元格会被截断加...。

⚠️Markdown 是展示输出，不是数据交换格式。截断和<br>都是单向的，hucre 也没有fromMarkdown——官方明确不会加。需要数据保真时，请用 CSV 或 JSON 做中转。如果你的某列本来就含想被渲染的 Markdown（比如一列**加粗**标签），传escapeInline: false即可。

反向爬取：fromHtml 解析任意网页表格

fromHtml把 HTML 表格字符串解析成一个Sheet——注意，是任何人的表格，不限于 hucre 自己导出的：

import { fromHtml, writeXlsx } from "hucre" const sheet = fromHtml(scrapedHtml, { sheetName: "Scraped", typeInference: true, // 从文本推断数字、布尔、ISO 日期 }) const xlsx = await writeXlsx({ sheets: [sheet] }) // 抓完直接落盘

它对真实网页的「脏数据」相当宽容：

• 类型推断：<td>42</td>读回为数字42，007默认保留为字符串（保护前导零）；
• 实体与换行： 、—等命名实体会解码，<br>变成单元格内换行；
• 结构还原：colspan/rowspan还原为合并单元格；<tfoot>无论声明在何处都会落到表格底部（与浏览器渲染一致）；<caption>写入sheet.a11y.summary，<thead>行写入sheet.a11y.headerRow；
• 脚本隔离：<script>/<style>内容整体跳过，不会被误当成单元格文本；
• 优雅降级：遇到未闭合注释、截断标签等无法完成的标记时，解析停止在出错处并返回已读到的行，而不是抛错丢掉整张表。

多表格页面默认读取第一个<table>，传tableIndex: 1可指定读取第 N 个。

注意：fromHtml 不是 toHtml 的逆函数

HTML 导出面向「展示」，回读时样式信息不会恢复，官方给出了明确对照：

另有两个小不对称：回读时单元格文本会被 trim（<td>周围的空白视为缩进），日期在导出时已丢掉了时分秒。如果你要把抓回来的 Sheet 再导出为 HTML，可以把两个无障碍提示传回去（round-trip 示例）：

toHtml(sheet, { hasHeaderRow: sheet.a11y?.headerRow === 0, caption: sheet.a11y?.summary, })

不想写代码？CLI convert 命令一步转换

hucre 附带命令行工具，convert子命令支持在 XLSX、ODS、CSV、TSV、JSON、NDJSON、XML、HTML、Markdown 之间按扩展名互相转换（实现见 src/cli/commands.ts）：

# 网页表格 → Excel hucre convert in.html out.xlsx # Excel 报表 → Markdown（贴进文档 / Issue / 周报） hucre convert report.xlsx report.md # 管道用法：stdin 进、stdout 出 cat data.csv | hucre convert - - --to html

两点提醒：文本格式转换只携带单元格值（样式、图表等不迁移），这是convert的设计约定；写到 stdout 时必须用--to显式指明格式，避免往终端喷二进制。另外.xls/.xlsb在 CLI 中是只读格式，可作转换的输入但不能作输出。

实战清单：双向流动怎么做才稳

1. 发布报表到网页：toHtml(sheet, { hasHeaderRow: true, styles: true, includeStyleTag: true })，一个调用拿到自适应深色模式的完整表格；
2. 往文档里贴表格：toMarkdown自动对齐、自动转义，放心贴进支持 GFM 的渲染器；
3. 抓取网页表格：fromHtml拿到结构化 Sheet 后，writeXlsx落盘或直接write({ format: "json" })转 JSON 入库；
4. 数据交换别用 Markdown：展示用 Markdown，流转用 CSV / JSON——这是官方定下的边界；
5. 超大文件：配合streamXlsxRows流式读取，再逐行喂给导出函数，内存恒定不随行数增长。

小结

hucre 用三个函数补齐了表格数据的「最后一公里」：toHtml负责带样式地上架，toMarkdown负责进文档，fromHtml负责把散落在网页里的表格变回结构化数据，CLI 的convert则把整条链路压缩成一条命令。零依赖、纯 TypeScript 的它，可以在服务端、边缘函数甚至浏览器里跑同一份逻辑——对于「表格数据双向流动」这类需求，这就是完整、简单且开箱即用的答案。

更多接口速查可参考 README 的 API 总表，规格覆盖情况见 docs/SPEC-COVERAGE.md。

【免费下载链接】hucreZero-dependency spreadsheet engine. Read & write XLSX, CSV, ODS. Pure TypeScript, works everywhere.项目地址: https://gitcode.com/gh_mirrors/hu/hucre