---
title: "图像"
description: "在从 DOCX 导入、在编辑器中渲染以及导出回 DOCX 时，图像是如何处理的。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/content-types/structures-and-media/images"
---

# 图像

在从 DOCX 导入、在编辑器中渲染以及导出回 DOCX 时，图像是如何处理的。

DOCX 文档中的图片会在导入时被提取，在编辑器中渲染，并在导出时重新嵌入。Image 扩展不包含在 StarterKit 中，必须单独安装。

## 你需要的内容

- **扩展（推荐）：** [`ConvertKit`](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md)。它自定义的 Image 在基础 Image 扩展之上声明了 `cropTop`、`cropBottom`、`cropLeft`、`cropRight`，因此 DOCX 的裁剪元数据可以在 schema 验证后保留下来。
- **扩展（最小配置）：** `@tiptap/extension-image`（不在 StarterKit 中）。基础扩展会渲染 `src`、`alt`、`title`、`width`、`height`。在这种配置下，DOCX 的裁剪属性会在 schema 验证时被丢弃。
- **配置：** 无论你使用哪种扩展配置，都需要通过导入扩展上的 `imageUploadConfig` 或 REST API 请求配置一个图片上传端点。

> **导入时需要 imageUploadConfig:**
>
> 导入 DOCX 时，图片会作为二进制 blob 从文件中提取出来。如果没有 `imageUploadConfig`，生成的 `src` 值将无法解析，图片会显示损坏。你必须提供一个上传端点，这样转换器才能为每张图片发送 POST 请求，并用真实 URL 替换内部引用。

## 支持概览

| 功能                       | 导入     | 编辑器                        | 导出      | 说明                                                                          |
| ------------------------ | ------ | -------------------------- | ------- | --------------------------------------------------------------------------- |
| 行内图片                     | 支持     | 支持                         | 支持      | 导入时需要 imageUploadConfig                                                     |
| 浮动/环绕图片                  | 部分支持   | 不支持                        | 不支持     | 锚定图片会被转换，但不会跟踪环绕类型。所有图片都会变成行内图片。背景/水印图片（`behindDoc`）会被跳过。                   |
| 图片尺寸                     | 支持     | 支持                         | 支持      | 宽度和高度会从 EMU 值中提取，并作为像素属性传递到图片节点上。导出时读取 width/height 属性。                     |
| Alt 文本                   | 支持     | 支持                         | 支持      | 会在导入时提取 `wp:docPr` 中的 `descr` 和 `title`。编辑器节点中的 alt 在导出时会映射为 DOCX 的 alt 文本。 |
| 格式（PNG、JPEG、GIF、BMP、SVG） | 支持     | 支持                         | 支持      |                                                                             |
| EMF/WMF                  | 支持（导入） | 取决于浏览器                     | 不支持（导出） | Windows 矢量格式可能无法完整往返                                                        |
| 图片裁剪                     | 支持     | ConvertKit 保留属性；视觉裁剪需要 CSS | 不支持     | `cropTop`、`cropBottom`、`cropLeft`、`cropRight` 会作为属性提取（百分比值）                 |
| 图片大小调整                   | 不适用    | 支持                         | 支持      | 调整后的尺寸可正确导出                                                                 |

## Import

Import images using [editor extension](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) or [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md). Both accept `imageUploadConfig` and produce the same output. The conversion service handles image uploads through both paths.

When importing DOCX, each embedded image is extracted from the zip archive as a blob. If you provide `imageUploadConfig`, the converter will POST each blob to your upload endpoint and replace the internal reference with the URL returned by the server.

```ts
ImportDocx.configure({
  token: 'your-jwt',
  imageUploadConfig: {
    url: 'https://your-api.example.com/upload',
  },
})
```

Without this configuration, imported images will have an unresolved `src` value.

If the source image has cropping applied in Word, the crop values are extracted as `cropTop`, `cropBottom`, `cropLeft`, and `cropRight` properties (percentage values from 0 to 100). [ConvertKit](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md)'s custom Image accepts these properties and outputs them on the rendered `<img>` element as `data-crop-top`, `data-crop-bottom`, `data-crop-left`, and `data-crop-right`. This package does not provide CSS to convert those data attributes into visible cropping. To achieve actual cropping, add CSS that reads these attributes (for example, using `clip-path`, or a wrapper with `overflow: hidden` and a negative `object-position`). If you are not using ConvertKit, these values are discarded during schema validation. Crop values are not preserved on export.

> **Floating images are not fully supported:**
>
> DOCX documents often contain images with text wrapping (square, tight, behind text). Anchored images are converted on import, but the wrapping type is not tracked. All images are inserted as inline nodes regardless of their original position. Background images or watermark images (`behindDoc`) are skipped entirely.

## 编辑器渲染

[`Image`](https://tiptap.zhcndoc.com/editor/extensions/nodes/image.md) 扩展会添加一个带有 `src`、`alt`、`title`、`width` 和 `height` 属性的 `image` 节点。它会渲染为标准的 `<img>` 标签。StarterKit 中不包含它。

```bash
npm install @tiptap/extension-image
```

```ts
import Image from '@tiptap/extension-image'

const editor = new Editor({
  extensions: [
    StarterKit,
    Image.configure({ inline: true }),
  ],
})
```

要启用拖拽调整大小的控制柄，请传入 `resize` 选项：

```ts
Image.configure({
  inline: true,
  resize: { enabled: true },
})
```

如果没有 Image 扩展，导入的图片节点将无法被 schema 识别。有关处理策略，请参见 [invalid schema guide](https://tiptap.zhcndoc.com/guides/invalid-schema.md)。

## Export

Use [editor extension](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) or [REST API](https://tiptap.zhcndoc.com/conversion/export/docx/rest-api.md) to export images. The extension supports [`imageOverrides`](https://tiptap.zhcndoc.com/conversion/export/docx/styles.md#element-overrides), which can be used to customize the default values for images in the output. The REST API does not accept image override configurations.

When exporting, the `src` URL of each image node is fetched and the binary data is embedded into the DOCX. Supported export formats: PNG, JPG, JPEG, GIF, BMP, and SVG.

If a node has `width` and `height` attributes (in pixels), these values are converted to points (1px = 0.75pt). If no dimensions are set, the exporter automatically detects the intrinsic size. If detection fails, the image defaults to 800x400 pixels.

The `alt` attribute on an image node is mapped to the alt text field of the DOCX image.