paste-cleaner
v0.1.3
Published
Clipboard HTML paste cleaner. Supports Word / WPS / Google Docs / LibreOffice clipboard HTML.
Maintainers
yu_99116Readme
paste-cleaner
剪贴板 HTML 清洗库 —— 将 Word / WPS / Google Docs / LibreOffice 的剪贴板 HTML 清洗为可安全插入富文本编辑器的 HTML。
安装
npm install paste-cleaner快速上手
import { clean } from 'paste-cleaner'
element.addEventListener('paste', (e) => {
const html = e.clipboardData?.getData('text/html')
if (!html) return
const { html: cleaned } = clean(html) // 默认 keep：保留安全内联样式
e.preventDefault()
element.insertAdjacentHTML('beforeend', cleaned)
})clean(input, options?)
CleanOptions
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
| source | SourceType \| 'auto' | 'auto' | 手动指定来源，跳过自动检测 |
| preset | 'default' \| 'editor' \| 'strip' | 'default' | 见「预设」 |
| semantic | Partial<Record<SourceType, SemanticConfig>> | — | 覆盖语义映射（MsoTitle→h1 等） |
| whitespace | WhitespaceOptions | 见下 | 空白归一化 |
| sanitize | false \| SanitizeOptions | — | 清洗白名单扩展；false 关闭清洗 |
| plugins | Plugin[] | — | 追加自定义插件 |
返回 CleanResult
| 字段 | 类型 | 说明 |
|---|---|---|
| html | string | 清洗后的 HTML 片段（不含 <html>/<body> 包裹） |
| source | SourceType | 识别到的来源：word / googledocs / libreoffice / wps / unknown |
| confidence | number | 来源识别置信度 0-1 |
| warnings | Warning[] | 过程警告（如被移除的危险链接） |
| assets | Asset[] | 图片资产，顺序与输出中 <img> 一一对应 |
| metadata | Map | 插件执行记录等元数据 |
预设
| 预设 | 行为 | 用法 |
|---|---|---|
| default | 保留全部安全内联样式（排除 mso-* 与危险值） | clean(html) |
| editor | 只保留白名单属性（font-size/font-family/color/…） | clean(html, editorPreset()) 或 { preset: 'editor' } |
| strip | 剥光表现样式 | clean(html, stripPreset()) 或 { preset: 'strip' } |
WhitespaceOptions
| 选项 | 默认 | 说明 |
|---|---|---|
| nbsp | 'to-space' | 'to-space' 把 转普通空格；'preserve' 保留 |
| collapseRuns | true | 连续空白折叠为单个空格（pre / white-space:pre-wrap 内跳过） |
SanitizeOptions
| 选项 | 说明 |
|---|---|
| allowTags | 额外放行的标签 |
| allowAttrs | 额外放行的属性，{ tag: { attr: 规则 } } |
| allowProtocols | 额外放行的协议，{ attr: ['https:'] } |
| style | 'keep'（默认）保留全部安全内联样式 / 'strip' 剥光 / 'whitelist' 只留 styleProps |
| styleProps | 'whitelist' 模式下的 CSS 属性白名单 |
自定义插件
import { clean, type Plugin } from 'paste-cleaner'
const shout: Plugin = {
name: 'shout',
priority: 30, // 默认 50；100 是 sanitize，之前执行可读到 style
enter(node, ctx) {
if (node.nodeType === 3) node.nodeValue = node.nodeValue?.toUpperCase()
},
}
clean(html, { plugins: [shout] })Plugin 字段：name / priority / enter(node, ctx) / leave(node, ctx)。
enter/leave 返回动作：remove / replace(node) / unwrap / skip / stop。
ctx 提供 warnings / assets / metadata。
图片处理
result.assets 按输出 <img> 的顺序返回图片。file:// 本地临时图片（WPS/Word）的 src 会从输出移除、原路径放进 assets，由宿主上传后回填：
const { html, assets } = clean(clipboardHtml)
// assets[i] 对应输出第 i 个 <img>；用粘贴事件的 clipboardData.files 上传后回填 src