Tiptap 中文文档

图像节点 Pro

Available in Start plan

An enhanced image node component for Tiptap editors. Features drag-to-resize, editable captions, floating toolbar controls, image alignment options, download functionality, and advanced management capabilities with responsive styling and accessibility features.

安装

通过 Tiptap CLI 添加该组件：

npx @tiptap/cli@latest add image-node-pro

源码在哪里？

上方预览是一个实时演示。要获取其完整源码——包括图片节点 以及 它引用的每个组件——请运行上面的安装命令。Tiptap UI 组件会以可编辑的源文件形式复制到你的项目中（位于 @/components/… 下），而不是作为 npm 包提供。这就是为什么下面示例中的导入会解析为你自己代码库中的文件，而不是 node_modules 中的某个模块。有关 CLI 为你添加的完整列表，请参见 引用的组件。

Components

<ImageNode />

一个增强型图片节点组件，带浮动工具栏、对齐控制及高级管理功能。

使用示例 

import { useEditor, EditorContent } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { Image } from '@/components/tiptap-node/image-node/image-node-extension'

export default function ImageEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit,
      Image.configure({
        HTMLAttributes: {
          class: 'custom-image-class',
        },
      }),
    ],
    content: '<img src="/images/example.png" alt="Image" data-align="center" />',
  })

  return <EditorContent editor={editor} />
}

特性

  • 拖拽调整大小：悬停在图片上并拖动任一侧的手柄即可设置宽度
  • 可编辑图片说明文字
  • 带对齐控制的浮动工具栏
  • 图片下载功能
  • 删除节点按钮
  • 对齐选项（左对齐、居中、右对齐）
  • 支持自定义 HTML 属性
  • 增强的可访问性
  • 响应式图片尺寸
  • 选中高亮

扩展

Image（增强版）

Tiptap 图片扩展的增强版本，增加了对齐支持及浮动工具栏集成。

使用示例 

import { Image } from '@/components/tiptap-node/image-node/image-node-extension'

const editor = useEditor({
  extensions: [StarterKit, Image],
})

浮动工具栏组件

图片节点包含多个浮动工具栏组件，选中图片时会显示：

<DeleteNodeButton />

从编辑器中移除选中的图片节点。

<ImageDownloadButton />

将图片下载到用户设备。

<ImageAlignButton />

控制图片对齐，支持左对齐、居中、右对齐选项。

工作原理

图片节点系统通过多个集成层次实现：

  1. 增强显示：在基础 Tiptap Image 扩展之上增加了额外样式和响应式行为
  2. 浮动工具栏：在选中图片时提供上下文相关的控制项
  3. 调整大小：悬停图片任一侧的拖拽手柄可交互式设置宽度
  4. 对齐系统：通过左对齐、居中和右对齐选项管理图片位置
  5. 节点管理：通过工具栏操作处理图片删除和下载功能
  6. 状态集成：与 Tiptap 的节点系统和命令架构无缝集成

浮动工具栏在选中图片时自动出现，快速访问对齐控制、下载功能及删除节点操作。

需求

依赖

  • @tiptap/extension-image - 核心图片扩展
  • @tiptap/react - React 集成
  • sass / sass-embedded - 用于 SCSS 编译

相关组件

CLI 会自动在图片节点旁安装以下组件——你无需手动添加。它们是图片节点从你项目内部导入的文件：

  • use-tiptap-editor (hook)
  • tiptap-utils (lib)
  • delete-node-button (component)
  • image-download-button (component)
  • image-align-button (component)
  • image-caption-button (component)
  • image-upload-button (component)
  • refresh-ccw-icon (icon)
  • separator (primitive)
Previously图片节点