---
title: "图像节点 Pro"
description: "在 Tiptap 编辑器中添加图片，支持对齐控制、下载功能及浮动工具栏管理。"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/node-components/image-node-pro"
---

# 图像节点 Pro

在 Tiptap 编辑器中添加图片，支持对齐控制、下载功能及浮动工具栏管理。

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.

> **Interactive demo:** [image node pro](https://template.tiptap.dev/preview/tiptap-node/image-node-pro)

## 安装

通过 Tiptap CLI 添加该组件：

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

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

## Components

### `<ImageNode />`

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

#### 使用示例

```tsx
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 图片扩展的增强版本，增加了对齐支持及浮动工具栏集成。

#### 使用示例

```tsx
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)