Tiptap 中文文档

使用按钮切换标题级别

Available for free

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

安装

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

npx @tiptap/cli@latest add heading-button

手动集成

对于除了 Vite 或 Next.js 之外的框架，请从开源仓库手动添加该组件。

引入样式

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

使用方法 

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>
  )
}

属性说明

名称类型默认值说明
editorEditor | nullnullTiptap 编辑器实例
level1 | 2 | 3 | 4 | 5 | 6必填标题级别
hideWhenUnavailablebooleanfalse当按钮不可用时是否隐藏
textstring-图标旁显示的文本
onToggled() => void-标题切换成功后触发的回调函数
showShortcutbooleanfalse是否显示快捷键提示

钩子（Hooks）

useHeading()

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

用法 

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>
  )
}

属性

名称类型默认值说明
editorEditor | nullnullTiptap 编辑器实例
level1 | 2 | 3 | 4 | 5 | 6必填标题级别
hideWhenUnavailablebooleanfalse当标题不可用时是否隐藏
onToggled() => void-标题切换成功后触发的回调函数

返回值

名称类型说明
isVisibleboolean按钮是否应该渲染
isActiveboolean当前标题级别是否处于激活状态
canToggleboolean是否可以切换到该标题
handleToggle() => boolean切换标题格式的函数
labelstring按钮的无障碍标签文本
shortcutKeysstring该标题级别的键盘快捷键
IconReact.FC标题级别对应的图标组件

工具函数

canToggle(editor, level?, turnInto?)

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

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

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

isHeadingActive(editor, level?)

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

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

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

toggleHeading(editor, level)

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

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（图标）
Previously表情符号触发按钮