前端富文本UI组件AI 应用【免费下载链接】BlockNoteA React Rich Text Editor thats block-based (Notion style) and extensible. Built on top of Prosemirror and Tiptap.项目地址https://gitcode.com/gh_mirrors/bl/BlockNote点击查看免费下载本文以 BlockNote 仓库中 Markdown 导出快照tests/src/unit/core/formatConversion/export/__snapshots__/markdown/table/mixedColWidths.md为锚点剖析一个三列表格在列宽混合指定第一列 100px、第二列自适应、第三列 300px时从块数据结构columnWidths到 ProseMirrorcolwidth属性、再到 HTML 与 GFM Markdown 输出的完整转换链路。读完本文你将理解 BlockNote 表格列宽在四种格式BlockNote HTML、HTML、Markdown、TipTap 节点之间如何流转、为何 Markdown 快照中三列最终呈现等宽以及如何利用同一测试用例体系验证导出行为不发生回归。快照文件一次 Markdown 导出行为的定版证据被指定为本文主体的文件是一份由测试框架自动生成的快照全文只有 5 行内容为一个标准的 GFM 管道表格| | | | | ---------- | ---------- | ---------- | | Table Cell | Table Cell | Table Cell | | Table Cell | Table Cell | Table Cell | | Table Cell | Table Cell | Table Cell |它记录了table/mixedColWidths这个测试用例经editor.blocksToMarkdownLossy()导出后的精确预期输出。快照是导出行为的定版证据只要实现发生变更导致输出与快照不一致toMatchFileSnapshot就会让测试失败从而把行为锁定下来。快照的生成链路由三部分协作完成测试用例定义tests/src/unit/core/formatConversion/export/exportTestInstances.ts中table/mixedColWidths用例约 L1439-L1566其块数据为{ type: table, content: { type: tableContent, columnWidths: [100, undefined, 300], // 第一列 100px、第二列自适应、第三列 300px rows: [ // 三行 × 三列每个单元格均为 Table Cell ], }, },执行器tests/src/unit/shared/formatConversion/export/exportTestExecutors.ts中的testExportMarkdownL52-L67它先给块补上 id再调用editor.blocksToMarkdownLossy(testCase.content)最后toMatchFileSnapshot(./__snapshots__/markdown/${testCase.name}.md)把结果写入快照目录。测试挂载tests/src/unit/core/formatConversion/export/runTests.test.ts中describe(Export tests (Markdown))L35-L43遍历exportTestInstancesMarkdown数组逐用例执行。在__snapshots__/markdown/table/目录下与mixedColWidths.md并列的还有basic.md、allColWidths.md、headerRows.md、headerRowsAndCols.md、mixedRowspansAndColspans.md、hardBreakInCell.md等 15 份快照共同覆盖表格导出的各个分支场景。输入侧混合列宽如何进入表格块数据BlockNote 的表格块在数据层面由TableContent描述其类型定义位于packages/core/src/schema/blocks/types.tsL353-L364export type TableContentI, S { type: tableContent; columnWidths: (number | undefined)[]; headerRows?: number; headerCols?: number; rows: { cells: InlineContentI, S[][] | TableCellI, S[]; }[]; };columnWidths是一个与表格列一一对应的数组元素为number | undefined数字表示该列的固定像素宽度undefined表示该列不指定宽度自适应。mixedColWidths用例中的[100, undefined, 300]正是这种部分指定混合形态的代表——这也是它区别于allColWidths用例[100, 200, 300]全部指定的关键所在。官方文档docs/content/docs/features/blocks/tables.mdx的 Block Shape 一节L37-L73给出了与源码类型一致的用户视角结构并说明textColor默认值为default。需要留意的是文档同时指出分拆单元格、单元格背景色、文本颜色、表头行/列等高级能力默认关闭需在创建编辑器时通过tables选项开启const editor new BlockNoteEditor({ tables: { splitCells: true, cellBackgroundColor: true, cellTextColor: true, headers: true, }, });中间层列宽在 ProseMirror 节点中的载体colwidth 属性BlockNote 内部基于 ProseMirror/TipTap 的表格节点承载数据列宽的底层载体是单元格的colwidth属性。块数据 → 节点属性packages/core/src/api/nodeConversions/blockToNode.tsL208-L288把TableContent转换为 ProseMirror 节点时做了三件关键事情绝对列索引解析columnWidths是相对于整张表格的绝对索引而单元格在行内的位置可能受colspan影响因此先用getAbsoluteTableCells把相对行列索引换算成绝对列索引L226-L233。单列取值普通单元格取columnWidths[absoluteCellIndex.col]作为其colwidthL236-L240。跨列展开当colspan 1时从绝对列索引开始逐个取出跨度内每一列的宽度可为undefined组成数组赋给colwidthL257-L263。最终通过schema.nodes[tableCell | tableHeader].createChecked({ ..., colwidth }, ...)创建带列宽属性的节点。节点属性 → 块数据反向反向转换在packages/core/src/api/nodeConversions/nodeToBlock.ts的contentNodeToTableContentL35-L66中完成从第一行单元格读取colwidth属性并展开进columnWidths若属性缺失则按colspan数量填充undefinedL58-L65contentNode.content.forEach((rowNode, _offset, rowIndex) { if (rowIndex 0) { rowNode.content.forEach((cellNode) { let colWidth cellNode.attrs.colwidth as null | undefined | number[]; if (colWidth undefined || colWidth null) { colWidth new Array(cellNode.attrs.colspan ?? 1).fill(undefined); } ret.columnWidths.push(...colWidth); }); } // ... });属性的解析与渲染表格单元格节点定义在packages/core/src/blocks/Table/block.tstableHeader的colwidth属性L55-L65与tableCell的colwidth属性L119 起默认值均为nullparseHTML会从 HTML 的colwidth属性按逗号分隔解析为数字数组。而反向的renderHTML会把colwidth写回为colwidth100这样的 HTML 属性——这一点可由 HTML 快照直接验证。HTML 渲染colgroup 保留列宽对照组在导出 HTML 时列宽信息被完整保留。packages/core/src/blocks/Table/block.ts的renderHTMLL177-L211会手动为table追加colgroup遍历首行单元格的colwidth对每个有值的列生成col stylewidth: Xpx /无值的列生成空col /。table/mixedColWidths的 HTML 快照tests/src/unit/core/formatConversion/export/__snapshots__/html/table/mixedColWidths.html精确记录了这一结果table colgroup col stylewidth: 100px; / col / col stylewidth: 300px; / /colgroup tr td colspan1 rowspan1 colwidth100 pTable Cell/p /td td colspan1 rowspan1 pTable Cell/p /td td colspan1 rowspan1 colwidth300 pTable Cell/p /td /tr !-- 共 3 行结构一致 -- /table可以看到100px与300px通过col的style和td的colwidth属性双双保留第二列undefined则不带任何宽度信息。该文件与 Markdown 快照同目录放置构成了同一用例、两种格式的天然对照。Markdown 导出列宽归一化与表格对齐Markdown 快照与 HTML 快照最大的差异在于GFM 管道表格语法没有列宽概念因此columnWidths的数值在 Markdown 导出阶段被归一化为基于内容长度的对齐宽度——这就是快照中三列看起来等宽的根本原因。导出管线packages/core/src/api/exporters/markdown/markdownExporter.ts定义了完整管线L14-L41export function blocksToMarkdown(blocks, schema, editor, options): string { const exporter createExternalHTMLExporter(schema, editor); const externalHTML exporter.exportBlocks(blocks, options); return cleanHTMLToMarkdown(externalHTML); }即块数据 → 外部 HTML → 字符串级 HTML→Markdown 转换。cleanHTMLToMarkdown还会先移除外部 HTML 导出器为保护空块而注入的占位符EMPTY_BLOCK_PLACEHOLDER避免其残留为 Markdown 中的杂散字符。serializeTable 的对齐算法核心实现在packages/core/src/api/exporters/markdown/htmlToMarkdown.ts的serializeTableL416-L522及其辅助函数中列数判定优先从colgroup中的col数量取列数再按行内实际单元格数取最大值L417-L474。合并单元格网格化用二维grid处理colspan/rowspan跨越位置填充占位保证行列对齐L428-L483。内容转义escapeTableCell将单元格内竖线|转义为\|L524-L526。列宽计算L489-L499——这是快照等宽的关键for (let c 0; c colCount; c) { let maxWidth 3; // 分隔行 --- 的最小宽度 for (const row of rows) { const cellWidth c row.length ? row[c].length : 0; maxWidth Math.max(maxWidth, cellWidth); } colWidths.push(Math.max(maxWidth, 10)); // 最小 10与 remark 输出保持一致 }即每列宽度 该列所有单元格内容的最大字符数下限 3保证分隔行至少为---再统一抬升到至少 10对齐 remark 库的输出习惯。Table Cell恰好 10 个字符因此三列宽度全部取 10快照中便呈现为整齐等宽。行输出formatTableRowL528-L539用cell.padEnd(colWidths[c])补齐空白后以|拼接formatSeparatorRowL541-L547按宽度生成-分隔行。表头判定L446-L448、L503-L518首行存在th才作为表头本用例全部是td因此没有表头导出器改为输出一行空表头 分隔行——对应快照第 1、2 行| | | | - 空表头行每格 10 个空格 两侧空格 | ---------- | ---------- | ---------- | - 分隔行每格 10 个短横线这也解释了快照为何第一行是空白的mixedColWidths用例没有配置headerRowsMarkdown 格式又要求表头行存在导出器便以空行补位。与全列宽用例的对比作为旁证同目录的allColWidths.md输入columnWidths: [100, 200, 300]输出与本快照逐字节一致进一步说明 Markdown 导出阶段完全不读列宽数值、只按内容宽度对齐。两份快照共同佐证Markdown 导出是有损的lossy列宽信息不会进入 Markdown。测试基建一个用例四种格式多份快照mixedColWidths快照所在的测试体系有一个值得注意的设计Markdown、HTML、TipTap 节点三组测试复用同一份块数据用例。在exportTestInstances.ts末尾L3112-L3139export const exportTestInstancesHTML: ... exportTestInstancesBlockNoteHTML.map(({ testCase }) ({ testCase, executeTest: testExportHTML, })); export const exportTestInstancesMarkdown: ... exportTestInstancesBlockNoteHTML.map(({ testCase }) ({ testCase, executeTest: testExportMarkdown, })); export const exportTestInstancesNodes: ... exportTestInstancesBlockNoteHTML.map(({ testCase }) ({ testCase, executeTest: testExportNodes, }));因此同一份columnWidths: [100, undefined, 300]用例同时产出了__snapshots__/markdown/table/mixedColWidths.md本文主体列宽归一化后的 GFM 表格__snapshots__/html/table/mixedColWidths.htmlcolgroup 保留列宽__snapshots__/nodes/下的 ProseMirror 节点 JSON携带colwidth属性runTests.test.ts中的四个describeBlockNote HTML / HTML / Markdown / TipTap 节点分别驱动对应执行器。这套单用例、多格式、多快照的架构让任何一侧的序列化行为变化都能被立即捕获是 BlockNote 保证格式转换稳定性的核心手段。实践建议与适用边界基于以上源码与快照证据可以得出以下可操作的结论需要保留表格列宽时不要走 Markdown 导出GFM 语法没有列宽表示columnWidths会在blocksToMarkdownLossy中被内容宽度对齐取代。应改用blocksToHTMLLossy或 BlockNote HTML 导出HTML 快照已证明colgroup与colwidth属性可以完整携带100px/300px这类信息。理解有损是格式的固有属性Markdown 往返导出后再解析无法还原列宽、单元格背景色等视觉属性这是格式能力边界而非实现缺陷测试体系中的exportParseEquality用例专门用于记录这种有损往返的预期结果。自定义导出时对齐 remark 行为若你的应用依赖与 remark 一致的 Markdown 输出如用于文档站渲染serializeTable中Math.max(maxWidth, 10)的最小宽度策略与空表头补位逻辑是必须复刻的细节。开启高级表格能力的前提涉及分拆、颜色、表头等交互能力需在创建编辑器时显式开启tables选项配置说明见 tables.mdx 的 Options 一节。延伸阅读表格块节点定义与 colgroup 渲染packages/core/src/blocks/Table/block.ts块数据与 ProseMirror 节点的双向转换nodeToBlock.ts、blockToNode.tsMarkdown 导出管线与表格序列化markdownExporter.ts、htmlToMarkdown.ts表格测试用例全集与执行器exportTestInstances.ts、exportTestExecutors.ts、runTests.test.ts表格快照目录markdown/table、html/table赞分享前端富文本UI组件AI 应用【免费下载链接】BlockNoteA React Rich Text Editor thats block-based (Notion style) and extensible. Built on top of Prosemirror and Tiptap.项目地址https://gitcode.com/gh_mirrors/bl/BlockNote点击查看免费下载相关推荐BlockNote 表格 Markdown 导出与列宽处理从 columnWidths 到快照文件的完整链路解析BlockNote 表格 Markdown 导出与列宽处理从 columnWidths 到快照文件的完整链路解析 本篇技术指南以 BlockNote 仓库中的前端富文本UI组件AI 应用BlockNote 表格导出空单元格GFM Markdown 快照与列宽对齐实现剖析BlockNote 表格导出空单元格GFM Markdown 快照与列宽对齐实现剖析 导读 在 BlockNote 基于块block的富文本编辑器中表格前端富文本UI组件AI 应用BlockNote 嵌套引用块的 Markdown 导出快照解析从 blockquote 嵌套到 GFM 输出的完整链路BlockNote 嵌套引用块的 Markdown 导出快照解析从 blockquote 嵌套到 GFM 输出的完整链路 在 BlockNote 的 Mark前端富文本UI组件AI 应用上一篇Wagtail 1.5.1 补丁版发布解析富文本链接、页面选择器与后台关键 Bug 修复下一篇FunASR 模型注册机制深度指南从自定义模型接入到安全加载实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考