从菜单中选择标题

Available for free

用于 Tiptap 编辑器的完全可访问的标题下拉菜单。通过简洁的下拉界面和灵活的定制选项，轻松选择并应用标题级别（H1-H6）。

安装

通过 Tiptap CLI 添加此组件：

npx @tiptap/cli@latest add heading-dropdown-menu

组件

`<HeadingDropdownMenu />`

预构建的 React 组件，提供一个用于选择标题级别的下拉菜单。

用法

export default function MyEditor() {
  return (
    <HeadingDropdownMenu
      editor={editor}
      levels={[1, 2, 3, 4, 5, 6]}
      hideWhenUnavailable={true}
      portal={false}
      onOpenChange={(isOpen) => console.log('Dropdown', isOpen ? '打开' : '关闭')}
    />
  )
}

属性

名称	类型	默认值	描述
`editor`	`Editor \| null`	`undefined`	Tiptap 编辑器实例
`levels`	`Level[]`	`[1,2,3,4,5,6]`	下拉菜单中显示的可选标题级别
`hideWhenUnavailable`	`boolean`	`false`	当无法使用标题时隐藏下拉菜单
`portal`	`boolean`	`false`	是否在 Portal 中渲染下拉菜单
`onOpenChange`	`(boolean) => void`	`undefined`	下拉菜单打开或关闭时的回调函数

Hooks

`useHeadingDropdownMenu()`

自定义 Hook，帮助您构建完全可控的标题下拉菜单，实现自定义渲染和行为。

用法

function MyHeadingDropdown() {
  const { isVisible, activeLevel, isActive, canToggle, levels, label, Icon } =
    useHeadingDropdownMenu({
      editor: myEditor,
      levels: [1, 2, 3],
      hideWhenUnavailable: true,
    })

  if (!isVisible) return null

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <button disabled={!canToggle} aria-label={label} aria-pressed={isActive}>
          <Icon />
          {label}
          <ChevronDownIcon />
        </button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        {levels.map((level) => (
          <DropdownMenuItem key={level}>
            <HeadingButton editor={editor} level={level} text={`标题 ${level}`} />
          </DropdownMenuItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

属性

名称	类型	默认值	描述
`editor`	`Editor \| null`	`undefined`	Tiptap 编辑器实例
`levels`	`Level[]`	`[1,2,3,4,5,6]`	下拉菜单中显示的可选标题级别
`hideWhenUnavailable`	`boolean`	`false`	当无法应用标题格式时隐藏下拉菜单

返回值

名称	类型	描述
`isVisible`	`boolean`	是否应渲染下拉菜单
`activeLevel`	`Level \| undefined`	当前激活的标题级别（1-6）
`isActive`	`boolean`	是否处于标题激活状态
`canToggle`	`boolean`	是否可以切换标题格式
`levels`	`Level[]`	可用的标题级别数组
`label`	`string`	下拉菜单的无障碍标签文本
`Icon`	`React.FC`	表示当前标题状态的图标组件

工具函数

`getActiveHeadingLevel(editor, levels?)`

获取当前激活的标题级别（可选指定级别列表）。

import { getActiveHeadingLevel } from '@/components/tiptap-ui/heading-dropdown-menu'

const activeLevel = getActiveHeadingLevel(editor, [1, 2, 3]) // 返回激活级别或 undefined

个别标题函数

标题下拉菜单使用了标题按钮组件的相关函数：

`isHeadingActive(editor, level?)`

判断指定级别标题是否激活，或者任意标题是否激活。

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

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

`canToggle(editor)`

检查当前编辑器状态是否允许切换标题格式。

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

const canApplyHeading = canToggle(editor)

键盘快捷键

使用 HeadingButton 组件时，每个标题级别支持以下快捷键：

Cmd/Ctrl + Alt + 1：切换 H1
Cmd/Ctrl + Alt + 2：切换 H2
Cmd/Ctrl + Alt + 3：切换 H3
Cmd/Ctrl + Alt + 4：切换 H4
Cmd/Ctrl + Alt + 5：切换 H5
Cmd/Ctrl + Alt + 6：切换 H6

下拉菜单本身不注册快捷键，但提供一个界面访问所有标题选项。

依赖

依赖项

@tiptap/react - 核心 Tiptap React 集成
@tiptap/starter-kit - 包含标题支持的基础 Tiptap 扩展

引用组件

use-tiptap-editor（Hook）
use-heading-dropdown-menu（Hook）
heading-button（组件）
button（基础组件）
dropdown-menu（基础组件）
card（基础组件）
chevron-down-icon（图标）
heading-icon（图标）
heading-one-icon（图标）
heading-two-icon（图标）
heading-three-icon（图标）
heading-four-icon（图标）
heading-five-icon（图标）
heading-six-icon（图标）

Previously标题按钮

Next up图片对齐按钮