切换按钮以更改列表类型

Available for free

一个用于切换不同列表类型（如无序列表、有序列表和任务列表）的按钮。

安装

通过 Tiptap CLI 添加组件：

npx @tiptap/cli@latest add list-button

组件

`<ListButton />`

一个预构建的 React 组件，可切换指定列表类型的格式。

用法

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [StarterKit, TaskList, TaskItem.configure({ nested: true })],
    content: `
        <ul>
            <li>
                <strong>粗体</strong> 用于强调，使用 <code>**</code> 或 <code>⌘+B</code> 或 <code>B</code> 按钮。
            </li>
            <li>
                <em>斜体</em> 用于细微的区别，使用 <code>*</code> 或 <code>⌘+I</code> 或 <code>I</code> 按钮。
            </li>
            <li>
                <s>删除线</s> 用于显示修订，使用 <code>~~</code> 或 <code>~~S~~</code> 按钮。
            </li>
        </ul>
        <ul data-type="taskList">
          <li data-type="taskItem" data-checked="true">
            <div>测试模板</div>
          </li>
          <li data-type="taskItem" data-checked="false">
            <div>
              <a target="_blank" rel="noopener noreferrer nofollow" href="https://tiptap.dev/pricing">创建账户</a>
            </div>
          </li>
          <li data-type="taskItem" data-checked="false">
            <div>下载免费模板</div>
          </li>
        </ul>
        `,
  })

  return (
    <ListButton
      editor={editor}
      type="bulletList"
      text="Bullet List"
      hideWhenUnavailable={true}
      showShortcut={true}
      onToggled={() => console.log('List toggled!')}
    />
  )
}

属性

名称	类型	默认值	描述
editor	Editor \| null	null	Tiptap 编辑器实例
type	'bulletList' \| 'orderedList' \| 'taskList'	必需	要切换的列表类型
hideWhenUnavailable	boolean	false	当不可用时，按钮是否应隐藏
text	string	-	显示在图标旁边的文本
onToggled	() => void	-	成功切换列表后触发的回调
showShortcut	boolean	false	是否显示快捷键提示

Hooks

`useList()`

一个自定义 Hook，帮助您构建自定义的列表切换按钮，全面控制渲染和行为。

用法

function MyListButton() {
  const { isVisible, isActive, canToggle, handleToggle, label, shortcutKeys, Icon } = useList({
    editor: myEditor,
    type: 'bulletList',
    hideWhenUnavailable: true,
    onToggled: () => console.log('List toggled!'),
  })

  if (!isVisible) return null

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

参数

名称	类型	默认值	描述
editor	Editor \| null	undefined	Tiptap 编辑器实例
type	ListType	必填	要切换的列表类型
hideWhenUnavailable	boolean	false	当无法切换时，是否隐藏按钮
onToggled	() => void	undefined	成功切换列表后触发的回调

返回值

名称	类型	描述
isVisible	boolean	按钮是否应被渲染
isActive	boolean	指定列表类型当前是否激活
canToggle	boolean	当前是否允许切换列表格式
handleToggle	() => boolean	切换列表格式的函数
label	string	按钮的可访问标签文本
shortcutKeys	string	列表类型的键盘快捷键
Icon	React.FC	列表按钮的图标组件

工具函数

`canToggleList(editor, type, turnInto?)`

判断当前编辑器状态是否允许切换指定类型的列表。

import { canToggleList } from '@/components/tiptap-ui/list-button'

const canToggle = canToggleList(editor, 'bulletList') // 判断是否可以切换
const canTurnInto = canToggleList(editor, 'bulletList', true) // 判断是否可以转换为无序列表

`toggleList(editor, type)`

程序化地切换指定类型的列表格式。

import { toggleList } from '@/components/tiptap-ui/list-button'

const success = toggleList(editor, 'orderedList')
if (success) {
  console.log('有序列表切换成功！')
}

`isListActive(editor, type)`

判断指定类型的列表当前是否激活。

import { isListActive } from '@/components/tiptap-ui/list-button'

const active = isListActive(editor, 'taskList')

`getListOption(type)`

获取指定列表类型的配置对象。

import { getListOption } from '@/components/tiptap-ui/list-button'

const option = getListOption('bulletList')
// 返回示例: { label: "Bullet List", type: "bulletList", icon: ListIcon }

键盘快捷键

每种列表类型都有独特的快捷键：

Cmd/Ctrl + Shift + 8：切换无序列表
Cmd/Ctrl + Shift + 7：切换有序列表
Cmd/Ctrl + Shift + 9：切换任务列表

使用 <ListButton /> 组件或 useList() Hook 时，这些快捷键会自动注册。

依赖

@tiptap/react - Tiptap React 核心集成
@tiptap/starter-kit - 包含列表支持的基础扩展
@tiptap/extension-task-list - 任务列表扩展
@tiptap/extension-task-item - 任务项扩展
react-hotkeys-hook - 键盘快捷键管理

参考组件

use-tiptap-editor (hook)
button (基础组件)
badge (基础组件)
tiptap-utils (工具库)
list-icon (图标)
list-ordered-icon (图标)
list-todo-icon (图标)

Previously链接弹出框

Next up列表下拉菜单