Tiptap 中文文档

图像

Beta

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

你需要的内容

  • 扩展（推荐）： ConvertKit。它自定义的 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 or REST API. 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.

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'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 扩展会添加一个带有 src、alt、title、width 和 height 属性的 image 节点。它会渲染为标准的 <img> 标签。StarterKit 中不包含它。

npm install @tiptap/extension-image
import Image from '@tiptap/extension-image'

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

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

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

如果没有 Image 扩展，导入的图片节点将无法被 schema 识别。有关处理策略，请参见 invalid schema guide。

Export

Use editor extension or REST API to export images. The extension supports imageOverrides, 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.

Previously结构与媒体