编号格式下拉菜单

Available in Start plan

一个用于有序列表的编号样式选择器。它会渲染一个 ListButton 来切换有序列表，并附带一个编号样式下拉菜单——包括十进制、括号样式、嵌套十进制、大小写字母、大小写罗马数字以及前导零格式——每种样式都以一个小型嵌套列表预览的形式显示。

当前激活的格式通过 orderedListNumbering 扩展（属于 @tiptap-pro/extension-convert-kit）读取并应用，因此屏幕上的标记始终与已注册的格式保持一致。所有编辑器逻辑都通过 useNumberingFormatDropdownMenu 钩子暴露，因此你可以在其基础上构建完全自定义的 UI。

Requires the orderedListNumbering extension

这个组件会在最外层有序列表上读取并写入一个 numberingFormat id。对应的级别定义（即每个 id 在屏幕上和导出时的显示方式）由扩展配置提供——见下方的 Setup。如果没有它，选择某种格式不会产生任何可见效果。

安装

通过 Tiptap CLI 添加该组件：

npx @tiptap/cli@latest add numbering-format-dropdown-menu

设置

该组件只在列表上存储一个格式 id；实际的标记渲染由扩展负责。请通过 ConvertKit 配置 orderedListNumbering，为你想提供的每个格式 id 提供一个层级定义，并且同样的定义也可以传递给 ExportDocx，以实现无损往返。

import { ConvertKit } from '@tiptap-pro/extension-convert-kit'

const NUMBERING_FORMATS = [
  {
    id: 'decimal',
    levels: Array.from({ length: 9 }, (_v, depth) => ({
      baseStyle: ['decimal', 'lowerLetter', 'lowerRoman'][depth % 3],
      textTemplate: `%${depth + 1}.`,
    })),
  },
  // …你提供的每个 id 对应一个条目（见 NUMBERING_FORMAT_IDS）
]

const editor = useEditor({
  extensions: [
    ConvertKit.configure({
      orderedListNumbering: {
        formats: NUMBERING_FORMATS,
        defaultFormat: 'decimal',
      },
    }),
    // …
  ],
})

组件

`<NumberingFormatDropdownMenu />`

一个预构建组件，将有序列表切换按钮与编号样式下拉菜单组合在一起。

用法

export default function MyEditor() {
  return (
    <NumberingFormatDropdownMenu
      editor={editor}
      hideWhenUnavailable={true}
      modal={false}
      onOpenChange={(isOpen) => console.log('Dropdown', isOpen ? 'opened' : 'closed')}
    />
  )
}

属性

该组件还会将任何额外的 Button 属性（除 type 外）转发给下拉触发器。

名称	类型	默认值	描述
`editor`	`Editor \| null`	`undefined`	Tiptap 编辑器实例。
`formats`	`NumberingFormat[]`	`DEFAULT_FORMATS`	在下拉菜单中提供的编号格式 id。
`hideWhenUnavailable`	`boolean`	`false`	当有序列表不可用时隐藏下拉菜单。
`modal`	`boolean`	`true`	下拉菜单是否以模态方式捕获焦点。
`onOpenChange`	`(boolean) => void`	`undefined`	下拉菜单打开或关闭时的回调。

`<NumberingFormatButton />`

单个格式选项，以小型嵌套列表预览的形式渲染。可用于构建下拉菜单网格，也可单独使用。

属性

名称	类型	默认值	描述
`editor`	`Editor \| null`	`undefined`	Tiptap 编辑器实例。
`format`	`NumberingFormat`	—	此按钮应用的编号格式。必填。
`hideWhenUnavailable`	`boolean`	`false`	当有序列表不可用时隐藏按钮。
`onFormatSet`	`() => void`	`undefined`	格式成功应用后调用。

钩子

`useNumberingFormatDropdownMenu()`

一个无头钩子，提供构建自定义编号下拉菜单所需的完整状态和操作。

用法

function MyNumberingDropdown() {
  const {
    isVisible,
    currentFormat,
    canToggle,
    formats,
    setFormat,
    isFormatActive,
    getFormatLabel,
  } = useNumberingFormatDropdownMenu({ editor, hideWhenUnavailable: true })

  if (!isVisible) return null

  return (
    <DropdownMenu>
      <DropdownMenuTrigger disabled={!canToggle}>编号</DropdownMenuTrigger>
      <DropdownMenuContent>
        {formats.map((format) => (
          <DropdownMenuItem
            key={format}
            data-active-state={isFormatActive(format) ? 'on' : 'off'}
            onClick={() => setFormat(format)}
          >
            {getFormatLabel(format)}
          </DropdownMenuItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

属性

名称	类型	默认值	描述
`editor`	`Editor \| null`	`undefined`	Tiptap 编辑器实例。
`formats`	`NumberingFormat[]`	`DEFAULT_FORMATS`	提供的编号格式 ID。
`hideWhenUnavailable`	`boolean`	`false`	当有序列表不可用时隐藏下拉菜单。

返回值

名称	类型	描述
`isVisible`	`boolean`	下拉菜单是否应当渲染。
`currentFormat`	`string`	当前应用的格式 ID（如果未设置，则为 `"decimal"`）。
`isActive`	`boolean`	提供的格式中是否有任意一个当前处于激活状态。
`canToggle`	`boolean`	当前状态下是否可以设置编号格式。
`formats`	`NumberingFormat[]`	提供的格式 ID。
`setFormat`	`(format: NumberingFormat) => boolean`	应用某个格式；成功时返回 `true`。
`isFormatActive`	`(format: NumberingFormat) => boolean`	某个给定格式是否为当前激活格式（用于激活标记）。
`getFormatLabel`	`(format: NumberingFormat) => string`	格式的可读预览标签，例如 `"1. 2. 3."`。

`useNumberingFormatButton()`

单个格式选项的状态和处理器。

属性

名称	类型	默认值	描述
`editor`	`Editor \| null`	`undefined`	Tiptap 编辑器实例。
`format`	`NumberingFormat`	—	此按钮应用的格式。必填。
`hideWhenUnavailable`	`boolean`	`false`	当不可用时隐藏按钮。
`onFormatSet`	`() => void`	`undefined`	格式设置后调用。

返回值

名称	类型	描述
`isVisible`	`boolean`	按钮是否应当渲染。
`isActive`	`boolean`	此格式当前是否处于激活状态。
`handleSetFormat`	`() => boolean`	应用该格式；成功时返回 `true`。
`canSet`	`boolean`	当前状态下是否可以设置该格式。
`label`	`string`	该格式的预览标签，例如 `"1. 2. 3."`。

工具

格式化 id 和标签

import {
  NUMBERING_FORMAT_IDS,
  NUMBERING_FORMAT_LABELS,
  DEFAULT_FORMATS,
} from '@/components/tiptap-ui/numbering-format-dropdown-menu'

NumberingFormat 是以下之一：decimal、decimal-paren、decimal-nested、upper-alpha、lower-alpha、upper-roman、lower-roman、decimal-zero。NUMBERING_FORMAT_IDS 按下拉菜单顺序列出它们；DEFAULT_FORMATS 是默认提供的集合；NUMBERING_FORMAT_LABELS 将每个 id 映射到其预览字符串（例如 "A. B. C."）。

编辑器辅助函数

import {
  setNumberingFormat,
  isNumberingFormatActive,
  getCurrentNumberingFormat,
  canSetNumberingFormat,
  getFormatLabel,
} from '@/components/tiptap-ui/numbering-format-dropdown-menu'

setNumberingFormat(editor, 'upper-roman') // 应用该格式，返回布尔值
getCurrentNumberingFormat(editor) // 当前激活的格式 id，若不在列表中则为 null
isNumberingFormatActive(editor, 'decimal') // 布尔值
canSetNumberingFormat(editor) // 布尔值
getFormatLabel('lower-alpha') // "a. b. c."

需求

依赖项

@tiptap/react — Tiptap React 核心集成
@tiptap-pro/extension-convert-kit — 提供 orderedListNumbering 扩展，用于存储和渲染该格式

引用的组件

use-tiptap-editor（hook）
list-button（组件）
button（原始组件）
button-group（原始组件）
dropdown-menu（原始组件）
tiptap-utils（库）
chevron-down-icon（图标）

Previously移动节点按钮

Next upReset all formatting button