---
title: "段落"
description: "Word 段落在 DOCX 转换流程中的处理方式，包括哪些格式会在导入、渲染和导出过程中保留。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/content-types/text-and-formatting/paragraphs"
---

# 段落

Word 段落在 DOCX 转换流程中的处理方式，包括哪些格式会在导入、渲染和导出过程中保留。

段落是任何文档中最基本的内容类型。在 Word 中，它们承载诸如间距、缩进、边框和对齐方式之类的格式。在 Tiptap 中，它们映射到 `paragraph` 节点，[ConvertKit](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md) 会自动注册该节点，并提供一个自定义变体，用于展示导入器生成的、支持 DOCX 的属性。

## 你需要什么

- **扩展：** [`ConvertKit`](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md)。其自定义 Paragraph 会渲染所有导入的属性（间距、缩进、行高、字体大小、上下文间距），并且内置的 `TextAlign` 已预配置为 `['paragraph', 'heading']`。
- **配置：** 无需配置。

> **段落格式需要 ConvertKit 的自定义 Paragraph:**
>
> 文本内容和对齐可在任意 paragraph 节点中往返保留。段落级间距、缩进、行高和上下文间距会在导入期间提取，并由 ConvertKit 的自定义 Paragraph 渲染为内联 CSS。如果你将 ConvertKit 的 Paragraph 替换为标准版本（或禁用该插槽），这些属性会保留在 JSON 中，但在 `setEditorContent()` 时会被剥离。 [转换后内容的样式](https://tiptap.zhcndoc.com/conversion/getting-started/guides/styling-converted-content.md) 指南介绍了如何扩展 schema 以支持更多属性。段落间距、缩进、上下文间距以及比例行高现在也会在导出时往返保留；请参见下方支持概览。

## 支持概览

|           | 导入                                       | 编辑器（使用 ConvertKit）                         | 导出                                       |
| --------- | ---------------------------------------- | ------------------------------------------ | ---------------------------------------- |
| 文本内容      | 支持                                       | 支持                                         | 支持                                       |
| 文本对齐      | 支持                                       | 支持（TextAlign）                              | 支持                                       |
| 行高        | 支持（paragraph attr）                       | 支持（`line-height: <value>`）                 | 比例值可往返保留（无单位倍数或百分比）；固定的 `px`/`pt` 行高不会保留 |
| 段落间距（前/后） | 支持（`spacingBefore`、`spacingAfter` attrs） | 支持（`margin-top` / `margin-bottom`）         | 支持                                       |
| 缩进        | 支持（`indent`、`firstLineIndent` attrs）     | 支持（`padding-left` / `text-indent`）         | 支持（负的首行缩进会变为悬挂缩进）                        |
| 上下文间距     | 支持（`contextualSpacing` attr）             | 支持（`data-contextual-spacing` + 注入的 CSS 规则） | 支持                                       |

## 导入

使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 导入段落。两者都会产生相同的段落输出。

当导入 DOCX 文件时，每个 Word 段落都会变成一个 `paragraph` 节点。转换服务会读取 Word 标记中的属性，并将它们映射到节点属性。

一个基础段落对应的 JSON 如下：

```json
{
  "type": "paragraph",
  "attrs": {
    "textAlign": "left"
  },
  "content": [
    {
      "type": "text",
      "text": "这是一个段落。"
    }
  ]
}
```

### 会保留什么

- 所有文本内容和行内格式（粗体、斜体、链接及其他 mark）
- 当段落在 Word 中具有显式对齐时，文本对齐会被保留

### 会丢失什么

转换服务会从 Word 源中提取段落级属性，例如 `spacingBefore`、`spacingAfter`、`lineHeight`、`indent`、`firstLineIndent` 和 `contextualSpacing`。ConvertKit 的自定义 Paragraph 会将它们全部渲染为内联 CSS。如果你将其替换为标准 Paragraph（或通过 `ConvertKit.configure({ paragraph: false })` 禁用该插槽），这些值会保留在原始 JSON 中，但在内容加载到编辑器时会被剥离。无论哪种设置，段落级边框和背景颜色在导入期间都不会被提取。

## 编辑器渲染

[`Paragraph`](https://tiptap.zhcndoc.com/editor/extensions/nodes/paragraph.md) 扩展由 [`ConvertKit`](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md) 注册，并将每个段落渲染为一个 `<p>` 元素。ConvertKit 会替换为一个自定义 Paragraph，用于添加与 DOCX 感知相关的属性；如果你禁用该插槽，则使用标准 Paragraph 作为回退。

### 文本对齐是内置的

ConvertKit 还会注册 `TextAlign`，并将其预配置为 `['paragraph', 'heading']`，因此来自 Word 的 `textAlign` 属性无需额外设置即可渲染。如果你禁用了捆绑的 `textAlign` 插槽，该属性仍会保留在 JSON 中，但不会被应用。请参阅[无效 schema 指南](https://tiptap.zhcndoc.com/guides/invalid-schema.md)。

### 与 Word 的视觉差异

编辑器渲染段落时使用的是你的 CSS 样式，而不是 Word 的文档样式。Word 的“Normal”样式通常包含特定的字体、字号和间距值，这些都不会带到编辑器中。结构和文本内容会被保留。视觉外观由你通过编辑器的 CSS 来控制。有关如何处理这一点，请参阅[转换后内容的样式](https://tiptap.zhcndoc.com/conversion/getting-started/guides/styling-converted-content.md)指南。

## 导出

使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/export/docx/rest-api.md) 导出段落。该扩展支持 [`paragraphOverrides` 和 `textRunOverrides`](https://tiptap.zhcndoc.com/conversion/export/docx/styles.md#element-overrides)，可对段落和文本运行的默认值进行细粒度控制。REST API 不接受元素覆盖。若要通过 REST API 自定义段落样式，请使用 [`styleOverrides`](https://tiptap.zhcndoc.com/conversion/export/docx/styles.md) 重新定义“Normal”文档样式。

在 DOCX 导出期间，每个 `paragraph` 节点都会被写为一个 Word 段落，并应用“Normal”样式。默认的 Normal 样式使用 Aptos 11pt 字体、段后 10pt 间距以及 1.15 倍行高。

### 会往返保留什么

- 所有文本内容和内联标记
- 文本对齐方式从段落节点属性中读取，并映射为 Word 对齐方式
- 行高从 `lineHeight` 段落属性中读取（块级 `textStyle` 标记仍然优先）。比例值（无单位倍数，如 `1.5`，或百分比，如 `150%`）会写入为 Word 行距；固定的 `px`/`pt` 行高没有对应的比例值，因此不会保留。
- 段落间距（`spacingBefore` / `spacingAfter`）、左缩进和首行缩进（`indent` / `firstLineIndent`）以及上下文间距（`contextualSpacing`）都从段落节点属性中读取。负的首行缩进会写为悬挂缩进。这些属性也适用于带样式的段落，例如引用块。

### 不会导出的内容

无论 JSON 中是否存在，导出时都不会读取段落边框和背景颜色。

### 自定义导出样式

你可以在导出配置中使用 `styleOverrides` 来覆盖默认段落样式：

```ts
ExportDocx.configure({
  styleOverrides: {
    paragraphStyles: [
      {
        id: 'Normal',
        name: 'Normal',
        run: {
          font: 'Calibri',
          size: 24,        // 半磅（24 = 12pt）
        },
        paragraph: {
          spacing: {
            after: 200,    // twips
            line: 276,     // 一行的 1/240（276 = 1.15 倍行高）
          },
        },
      },
    ],
  },
})
```

这让你可以为导出文档中的所有段落控制字体、字号、间距以及其他 Word 级属性。