fatcms-clipboard-parser

编辑器无关的 HTML 剪贴板解析工具。MIT 许可，公开可读 ES Module 源码，附 TypeScript 声明。无需 React、编辑器实例或全局变量。

npm install fatcms-clipboard-parser

import { parseHtml, parseText, parseTableGrid } from 'fatcms-clipboard-parser';

const { nodes } = parseHtml('<p><strong>你好</strong></p>');
const values = parseText('姓名\t数量\n张三\t3');

// 在浏览器中解析表格结构；不需要把 table 插入页面。
const document = new DOMParser().parseFromString(html, 'text/html');
const table = document.querySelector('table');
const grid = table ? parseTableGrid(table) : null;

API

• parseHtml(html, options?)：返回 { nodes, warnings }。节点包含 name、type、attrs、style、children 或 data。parent 为父节点引用，因此节点树不可直接 JSON.stringify；转换为业务数据时请忽略 parent。支持实体、br、pre/code 换行、简单标签/类/id/后代选择器及内联样式。默认最多 2000 万字符，可通过 maxLength 调整；normalizeWhitespace: false 保留源文本换行。
• parseStyle(text)：解析 CSS 声明，保留引号、函数内部的分号及值的大小写。
• parseText(text)：按制表符和换行拆成二维数组，保留空格、空单元格和末尾空行。
• parseTableGrid(table, options?)：返回 { rows, rowCount, columnCount, merges }。普通单元格包含原始 DOM element、rowSpan、colSpan；合并覆盖位置包含 coveredBy: { row, col }；缺失位置为 null。merge 为 { row, col, rowCount, colCount }，索引从零开始。默认最多 100 万个网格位置，maxCells 可调整。alignFirstRow: 'right' 兼容省略前导空标题的导出格式，通常使用默认 left。不修改传入 DOM，不做布局测量。
• isSafeUrl(value, image?)：基础 URL 协议检查，供剪贴板适配使用。

范围与限制

本包负责公共解析结构，不负责编辑器内容模型、公式计算、图片上传、粘贴命令、撤销历史或工作簿文件导入。电子表格的 Office 特殊格式预处理、行列尺寸测量和 CSS 样式提取由 parseSpreadsheetHtml 负责；数据类型及编辑器样式字段由宿主适配器映射。

HTML 节点解析可运行在 Node.js 中；表格解析需要 DOM 对象（浏览器，或调用方提供的 jsdom）。无文档级缓存、监听器或全局语言设置，每次调用返回独立结构。返回的 table element 属于调用者，使用完结果即可释放。

样式解析仅支持扁平的简单规则，不实现完整 CSS cascade、继承、伪类、媒体查询或 !important。HTML 解析会忽略部分活动元素和事件属性，但不是完整 HTML/CSS 安全净化器；不要把未经专门净化的剪贴板 HTML 插入可信页面或直接执行。

FatCMS 接入

fatcms-doc-sdk 正常 import 本包并挂载到 window.fatcmsDocDependencies['fatcms-clipboard-parser']；富文本读取公共节点树。fatcms-ysheet-sdk 使用同名 Webpack external，读取公共表格网格，再转换成工作表数据。先加载 doc-sdk，随后加载 ysheet-sdk。仅共享无状态函数，不共享文档数据。

开发

npm ci
npm test
npm pack --dry-run

发布包只包含 src、README 和 LICENSE；测试代码与开发依赖不进入发布文件。源码重新实现公共解析接口，编辑器恢复代码和业务配置不包含在包内。

0.2：完整电子表格 HTML 解析

import { parseSpreadsheetHtml } from 'fatcms-clipboard-parser';
const result = parseSpreadsheetHtml(html, { document });

返回 rows（二维单元格数组）、merges、rowSizes、columnSizes 和 tableAttributes。单元格包括 text、可选 link/image、CSS 风格的 style、Office numberFormat 和原始 attributes。所有结果都是普通数据，不包含 DOM 或循环引用。data-* 属性仅传给适配器，本包不解释编辑器私有协议。

此 API 要求浏览器文档；在屏幕外 Shadow DOM 中测量布局，始终 finally 清理，不加载剪贴板图片，不把来源样式表插入宿主。支持多表格拼接、合并单元格、隐藏行列、Office mso-xlrowspan / mso-ignore:colspan / mso-number-format。业务值、上传策略和保存仍由适配器处理。不导入工作簿 XML，不执行公式。

限制：复杂 CSS 规则沿用 parseHtml 的支持范围；单元格包含多张图片时返回第一张，混合富文本按单元格整体样式表示。测量容器宽度固定为 1200px，默认行高至少 24px。