---
title: "TaskItem 扩展"
description: "使用 TaskItem 扩展来支持渲染为 的任务项，并带有复选框。更多内容请参见我们的文档！"
canonical_url: "https://tiptap.zhcndoc.com/editor/extensions/nodes/task-item"
---

# TaskItem 扩展

使用 TaskItem 扩展来支持渲染为 的任务项，并带有复选框。更多内容请参见我们的文档！

该扩展渲染一个任务项列表元素，即一个 `<li>` 标签，其 `data-type` 属性设置为 `taskItem`。它还在列表元素内部渲染一个复选框，该复选框会更新 `checked` 属性。

该扩展不需要任何 JavaScript 框架，基于原生 JavaScript。

> **Interactive demo:** [TaskItem](https://embed.tiptap.dev/preview/Nodes/TaskItem)

## 安装

```bash
npm install @tiptap/extension-list
```

该扩展需要 [`TaskList`](https://tiptap.zhcndoc.com/editor/extensions/nodes/task-list.md) 节点。

## 用法

```js
import { Editor } from '@tiptap/core'
import { TaskItem } from '@tiptap/extension-list'

new Editor({
  extensions: [TaskItem],
})
```

该扩展与 `ListKit` 扩展一起默认安装，因此您无需单独安装它。

```ts
import { Editor } from '@tiptap/core'
import { ListKit } from '@tiptap/extension-list'

new Editor({
  extensions: [ListKit],
})
```

## 设置

### HTMLAttributes

应添加到渲染的 HTML 标签中的自定义 HTML 属性。

```js
TaskItem.configure({
  HTMLAttributes: {
    class: 'my-custom-class',
  },
})
```

### nested

是否允许任务项相互嵌套。

```js
TaskItem.configure({
  nested: true,
})
```

### onReadOnlyChecked

当任务项在编辑器处于 `readOnly` 状态时被选中或取消选中时的处理程序。
如果未提供该处理程序，则在编辑器处于 `readOnly` 时，任务项将是不可变的。
如果该函数返回 false，则选中状态将被保留（`readOnly`）。

```js
TaskItem.configure({
  onReadOnlyChecked: (node, checked) => {
    // 执行某些操作
  },
})
```

### taskListTypeName

该任务项所属的任务列表类型名。用于确定父任务列表类型。

```js
TaskItem.configure({
  taskListTypeName: 'taskList',
})
```

### a11y

任务项的无障碍（a11y）特定设置。包括以下选项：

- **`checkboxLabel`**：一个函数，根据任务项的选中状态返回复选框的 aria-label。对于屏幕阅读器来说，这有助于宣布复选框的状态。
  - **参数**：
    - `node`：任务项节点。
    - `checked`：布尔值，表示任务项是否被选中。
  - **返回值**：字符串，作为复选框的 `aria-label`。

```js
TaskItem.configure({
  a11y: {
    // 复选框的 aria-label
    checkboxLabel: (node, checked) => {
      return checked ? '任务已完成' : '任务未完成'
    },
  },
})
```

## 快捷键

| 命令              | Windows/Linux | macOS       |
| --------------- | ------------- | ----------- |
| splitListItem() | Enter         | Enter       |
| sinkListItem()  | Tab           | Tab         |
| liftListItem()  | Shift + Tab   | Shift + Tab |

## 源代码

[packages/extension-list/src/task-item/](https://github.com/ueberdosis/tiptap/blob/main/packages/extension-list/src/task-item/)

## 最小安装

```js
import { Editor } from '@tiptap/core'
import { TaskItem } from '@tiptap/extension-list/task-item'

new Editor({
  extensions: [TaskItem],
})
```