---
title: "插入和上传图片的按钮"
description: "添加一个按钮，将图片上传并插入到您的 Tiptap 编辑器中。更多信息请查看文档！"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/components/image-upload-button"
---

# 插入和上传图片的按钮

添加一个按钮，将图片上传并插入到您的 Tiptap 编辑器中。更多信息请查看文档！

一个用于在编辑器中插入和上传图片的按钮。

> **Interactive demo:** [image upload button](https://template.tiptap.dev/preview/tiptap-ui/image-upload-button)

## 安装

您可以通过 Tiptap CLI（适用于 Vite 或 Next.js）添加该组件：

```bash
npx @tiptap/cli@latest add image-upload-button
```

## 组件

### `<ImageUploadButton />`

一个预构建的 React 组件，用于向编辑器中插入图片。

#### 用法

```tsx
import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { Image } from '@tiptap/extension-image'
import { ImageUploadButton } from '@/components/tiptap-ui/image-upload-button'
import { ImageUploadNode } from '@/components/tiptap-node/image-upload-node'
import { handleImageUpload, MAX_FILE_SIZE } from '@/lib/tiptap-utils'

import '@/components/tiptap-node/image-node/image-node.scss'
import '@/components/tiptap-node/paragraph-node/paragraph-node.scss'

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [
      StarterKit,
      Image,
      ImageUploadNode.configure({
        accept: 'image/*',
        maxSize: MAX_FILE_SIZE,
        limit: 3,
        upload: handleImageUpload,
        onError: (error) => console.error('上传失败:', error),
      }),
    ],
    content: `
        <p>点击按钮上传图片。</p>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <ImageUploadButton
        editor={editor}
        text="添加图片"
        hideWhenUnavailable={true}
        showShortcut={true}
        onInserted={() => console.log('图片已插入！')}
      />

      <EditorContent editor={editor} role="presentation" />
    </EditorContext.Provider>
  )
}
```

#### 属性

| 名称                    | 类型               | 默认值         | 描述             |
| --------------------- | ---------------- | ----------- | -------------- |
| `editor`              | `Editor \| null` | `undefined` | Tiptap 编辑器实例   |
| `text`                | `string`         | `undefined` | 按钮旁边要显示的可选文本标签 |
| `hideWhenUnavailable` | `boolean`        | `false`     | 当无法插入图片时隐藏按钮   |
| `onInserted`          | `() => void`     | `undefined` | 成功插入图片后触发的回调函数 |
| `showShortcut`        | `boolean`        | `false`     | 显示快捷键徽章（如果可用）  |

## 钩子

### `useImageUpload()`

这是一个自定义钩子，允许您构建自己的图片上传按钮，完全控制渲染和行为。

#### 用法

```tsx
function MyImageUploadButton() {
  const { isVisible, isActive, canInsert, handleImage, label, shortcutKeys, Icon } = useImageUpload(
    {
      editor: myEditor,
      hideWhenUnavailable: true,
      onInserted: () => console.log('图片已插入！'),
    },
  )

  if (!isVisible) return null

  return (
    <button onClick={handleImage} disabled={!canInsert} aria-label={label} aria-pressed={isActive}>
      <Icon />
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}
```

#### 属性

| 名称                    | 类型               | 默认值         | 描述             |
| --------------------- | ---------------- | ----------- | -------------- |
| `editor`              | `Editor \| null` | `undefined` | Tiptap 编辑器实例   |
| `hideWhenUnavailable` | `boolean`        | `false`     | 无法插入图片时隐藏按钮    |
| `onInserted`          | `() => void`     | `undefined` | 成功插入图片后触发的回调函数 |

#### 返回值

| 名称             | 类型              | 描述                          |
| -------------- | --------------- | --------------------------- |
| `isVisible`    | `boolean`       | 按钮是否应被渲染                    |
| `isActive`     | `boolean`       | 是否当前选中图片                    |
| `canInsert`    | `boolean`       | 是否允许插入图片                    |
| `handleImage`  | `() => boolean` | 插入图片的函数                     |
| `label`        | `string`        | 按钮的无障碍标签文本                  |
| `shortcutKeys` | `string`        | 键盘快捷键（Cmd/Ctrl + Shift + I） |
| `Icon`         | `React.FC`      | 图片上传按钮的图标组件                 |

## 工具函数

### `canInsertImage(editor)`

判断当前编辑器状态是否能插入图片。

```tsx
import { canInsertImage } from '@/components/tiptap-ui/image-upload-button'

const canInsert = canInsertImage(editor) // 判断是否能插入图片
```

### `insertImage(editor)`

编程方式在编辑器中插入图片。

```tsx
import { insertImage } from '@/components/tiptap-ui/image-upload-button'

const success = insertImage(editor)
if (success) {
  console.log('图片插入成功！')
}
```

### `isImageActive(editor)`

判断当前编辑器中是否选中了图片。

```tsx
import { isImageActive } from '@/components/tiptap-ui/image-upload-button'

const active = isImageActive(editor)
```

## 键盘快捷键

图片上传按钮支持以下快捷键：

- **Cmd/Ctrl + Shift + I** ：插入图片

当使用`<ImageUploadButton />`组件或`useImageUpload()`钩子时，快捷键将自动注册。

## 需求

### 依赖

- `@tiptap/react` - Tiptap React 核心集成
- `react-hotkeys-hook` - 键盘快捷键管理

### 使用的引用组件

- `use-tiptap-editor`（钩子）
- `button`（基础组件）
- `badge`（基础组件）
- `tiptap-utils`（工具库）
- `image-plus-icon`（图标）