---
title: "切换按钮以更改列表类型"
description: "添加一个按钮到您的 Tiptap 编辑器中，可以在无序列表、有序列表或任务列表之间切换。详细信息请查看文档。"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/components/list-button"
---

# 切换按钮以更改列表类型

添加一个按钮到您的 Tiptap 编辑器中，可以在无序列表、有序列表或任务列表之间切换。详细信息请查看文档。

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

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

## 安装

通过 Tiptap CLI 添加组件：

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

## 组件

### `<ListButton />`

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

#### 用法

```tsx
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，帮助您构建自定义的列表切换按钮，全面控制渲染和行为。

#### 用法

```tsx
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?)`

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

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

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

### `toggleList(editor, type)`

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

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

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

### `isListActive(editor, type)`

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

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

const active = isListActive(editor, 'taskList')
```

### `getListOption(type)`

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

```tsx
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` (图标)