---
title: "粘贴处理程序"
description: "在 Tiptap 编辑器中自动清理和规范化来自 Microsoft Excel、Word 和 Google Docs 的粘贴内容。"
canonical_url: "https://tiptap.zhcndoc.com/editor/extensions/functionality/paste-handler"
---

# 粘贴处理程序

在 Tiptap 编辑器中自动清理和规范化来自 Microsoft Excel、Word 和 Google Docs 的粘贴内容。

`PasteHandler` 扩展会智能地转换粘贴的 HTML，以确保与外部来源的内容兼容。它会对粘贴内容执行一系列转换，在保留用户意图的同时清理特定来源的格式标记。

> **Interactive demo:** [PasteHandler](https://embed-pro.tiptap.dev/preview/Extensions/PasteHandler)

## 支持的来源

| 来源                | macOS 桌面 | Windows 桌面 |    Web（浏览器）    |
| ----------------- | :------: | :--------: | :------------: |
| Microsoft Excel   |     ✓    |      ✓     |  ✓（SharePoint） |
| Microsoft Word    |     ✓    |      ✓     |  ✓（SharePoint） |
| Microsoft Outlook |     ✓    |      ✓     | ✓（Outlook Web） |
| Google Docs       |     —    |      —     |        ✓       |
| Google Sheets     |     —    |      —     |        ✓       |

## 安装

```bash
npm install @tiptap-pro/extension-paste-handler
```

## 用法

该扩展无需配置。只需将其添加到编辑器，它将自动工作。

```js
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import PasteHandler from '@tiptap-pro/extension-paste-handler'

const editor = new Editor({
  extensions: [
    StarterKit,
    PasteHandler,
  ],
})
```

## 处理内容

该扩展会对粘贴的 HTML 应用一系列转换，按特定顺序执行：

| 转换          | 描述                                                    |
| ----------- | ----------------------------------------------------- |
| CSS 类解析     | 将基于类的 CSS 格式（例如来自 Excel）解析为内联样式                       |
| Office 标记清理 | 移除 Microsoft Office 特有的元素和属性，如 `<o:p>` 标签和 `mso-*` 样式 |
| 书签移除        | 清除 Word 书签标记和空的书签锚点                                   |
| 表格单元格文本样式   | 确保编辑器能正确识别表格单元格中的文本格式                                 |
| 背景色转换       | 将 `background-color` 样式转换为高亮标记，以便与“高亮”扩展配合使用          |
| ARIA 标题转换   | 将 ARIA 标题元素（来自 SharePoint Word）转换为语义化 HTML 标题         |
| 水平线检测       | 检测基于文本的水平线（例如来自 Google Docs），并将其转换为 `<hr>` 元素         |
| 软换行合并       | 将连续的零边距段落（来自 Google Docs）合并为适当的换行                     |
| 嵌套列表重建      | 将扁平列表结构（来自 SharePoint）重建为正确嵌套的列表                      |
| 有序列表标准化     | 移除内联 `list-style-type`，让编辑器的 CSS 控制列表样式               |
| 孤立换行清理      | 移除块元素之间导致多余间距的孤立 `<br>` 标签                            |

> **错误处理:**
>
> 如果任何转换失败，扩展会优雅地回退到原始粘贴的 HTML，以确保粘贴功能始终可用。

## 已知限制

### Safari 剪贴板会移除表格单元格样式

当在 Safari 中从 SharePoint Excel（或类似来源）复制表格单元格并粘贴到编辑器时，单元格内的格式（如粗体、斜体、颜色和链接）会丢失。Safari 会将一个简化后的 HTML 负载写入剪贴板，其中只包含表格结构和单元格文本——样式信息在到达编辑器之前就已被移除。

这是 WebKit 层面的行为，无法由粘贴处理器恢复。在 Safari 中粘贴到其他编辑器时也会出现相同结果（例如 SharePoint Word）。从基于 Chromium 的浏览器或 Firefox 复制则不受影响。