---
title: "使用按钮切换标题级别"
description: "添加一个按钮，在你的 Tiptap 编辑器中切换不同的标题级别。详细内容请参阅文档！"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/components/heading-button"
---

# 使用按钮切换标题级别

添加一个按钮，在你的 Tiptap 编辑器中切换不同的标题级别。详细内容请参阅文档！

用于切换不同标题级别的按钮。

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

## 安装

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

```bash
npx @tiptap/cli@latest add heading-button
```

### 手动集成

对于除了 Vite 或 Next.js 之外的框架，请从[开源仓库](https://github.com/ueberdosis/tiptap-ui-components/tree/main/apps/web/src/components/tiptap-ui/heading-button)手动添加该组件。

### 引入样式

此组件需要引入我们的样式文件，已添加到 `styles/keyframe-animation.scss` 和 `styles/_variables.scss` 中。

## 使用方法

```tsx
import { HeadingButton } from '@/components/tiptap-ui/heading-button'
import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'

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

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [StarterKit],
    content: `
          <h1>标题 1</h1>
          <h2>标题 2</h2>
          <h3>标题 3</h3>
          <h4>标题 4</h4>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <HeadingButton
        editor={editor}
        level={1}
        text="标题 1"
        hideWhenUnavailable={true}
        showShortcut={true}
        onToggled={() => console.log(`标题 ${level} 已切换！`)}
      />
      <HeadingButton
        editor={editor}
        level={2}
        text="标题 2"
        hideWhenUnavailable={true}
        showShortcut={true}
        onToggled={() => console.log(`标题 ${level} 已切换！`)}
      />

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

## 属性说明

| 名称                  | 类型                         | 默认值   | 说明             |
| ------------------- | -------------------------- | ----- | -------------- |
| editor              | Editor \| null             | null  | Tiptap 编辑器实例   |
| level               | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 必填    | 标题级别           |
| hideWhenUnavailable | boolean                    | false | 当按钮不可用时是否隐藏    |
| text                | string                     | -     | 图标旁显示的文本       |
| onToggled           | () => void                 | -     | 标题切换成功后触发的回调函数 |
| showShortcut        | boolean                    | false | 是否显示快捷键提示      |

## 钩子（Hooks）

### `useHeading()`

一个自定义钩子，用于构建你自己的标题按钮，支持完全控制渲染和行为。

#### 用法

```tsx
function MyHeadingButton() {
  const { isVisible, isActive, canToggle, handleToggle, label, shortcutKeys, Icon } = useHeading({
    editor: myEditor,
    level: 3,
    hideWhenUnavailable: true,
    onToggled: () => console.log('标题 3 已切换！'),
  })

  if (!isVisible) return null

  return (
    <button onClick={handleToggle} disabled={!canToggle} aria-label={label} aria-pressed={isActive}>
      <Icon />
      {label}
      {shortcutKeys && <HeadingShortcutBadge level={3} shortcutKeys={shortcutKeys} />}
    </button>
  )
}
```

#### 属性

| 名称                  | 类型                         | 默认值   | 说明             |
| ------------------- | -------------------------- | ----- | -------------- |
| editor              | Editor \| null             | null  | Tiptap 编辑器实例   |
| level               | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 必填    | 标题级别           |
| hideWhenUnavailable | boolean                    | false | 当标题不可用时是否隐藏    |
| onToggled           | () => void                 | -     | 标题切换成功后触发的回调函数 |

#### 返回值

| 名称           | 类型            | 说明             |
| ------------ | ------------- | -------------- |
| isVisible    | boolean       | 按钮是否应该渲染       |
| isActive     | boolean       | 当前标题级别是否处于激活状态 |
| canToggle    | boolean       | 是否可以切换到该标题     |
| handleToggle | () => boolean | 切换标题格式的函数      |
| label        | string        | 按钮的无障碍标签文本     |
| shortcutKeys | string        | 该标题级别的键盘快捷键    |
| Icon         | React.FC      | 标题级别对应的图标组件    |

## 工具函数

### `canToggle(editor, level?, turnInto?)`

检查当前编辑器状态是否可以切换标题。

```tsx
import { canToggle } from '@/components/tiptap-ui/heading-button'

const canToggleH2 = canToggle(editor, 2) // 检查是否可切换为标题 2
const canTurnInto = canToggle(editor, 1, true) // 检查是否可以转换成标题 1
```

### `isHeadingActive(editor, level?)`

检查指定标题级别当前是否处于激活状态。

```tsx
import { isHeadingActive } from '@/components/tiptap-ui/heading-button'

const isH1Active = isHeadingActive(editor, 1) // 检查标题 1 是否激活
const isAnyHeadingActive = isHeadingActive(editor) // 检查是否有任意标题激活
```

### `toggleHeading(editor, level)`

以编程方式切换当前选区的标题格式。

```tsx
import { toggleHeading } from '@/components/tiptap-ui/heading-button'

const success = toggleHeading(editor, 3) // 切换为标题 3
if (success) {
  console.log('标题切换成功！')
}
```

## 键盘快捷键

标题按钮支持与标题级别对应的键盘快捷键，自动注册如下：

- **Ctrl + Alt + 1**：切换到标题 1
- **Ctrl + Alt + 2**：切换到标题 2
- **Ctrl + Alt + 3**：切换到标题 3
- **Ctrl + Alt + 4**：切换到标题 4
- **Ctrl + Alt + 5**：切换到标题 5
- **Ctrl + Alt + 6**：切换到标题 6

在使用 `<HeadingButton />` 组件或 `useHeading()` 钩子时，快捷键会自动注册。每个标题级别都有专属快捷键。

## 依赖组件

- `use-tiptap-editor`（钩子）
- `button`（基础组件）
- `tiptap-utils`（库）
- `heading-one-icon`（图标）
- `heading-two-icon`（图标）
- `heading-three-icon`（图标）
- `heading-four-icon`（图标）
- `heading-five-icon`（图标）
- `heading-six-icon`（图标）