---
title: "文字按钮"
description: "在 Tiptap 编辑器中智能检测节点，支持键盘快捷键和无障碍，转换所选内容为段落。"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/components/text-button"
---

# 文字按钮

在 Tiptap 编辑器中智能检测节点，支持键盘快捷键和无障碍，转换所选内容为段落。

一个完全无障碍的 Tiptap 编辑器文字按钮。支持键盘快捷键，轻松将内容转换为段落/文本格式，并提供灵活的自定义选项。

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

## 安装

通过 Tiptap CLI 添加该组件：

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

## 组件

### `<TextButton />`

一个预构建的 React 组件，将内容转换为段落/文本格式。

#### 用法

```tsx
<TextButton
  editor={editor}
  text="文本"
  hideWhenUnavailable={true}
  showShortcut={true}
  onToggled={() => console.log('已转换为文本！')}
/>
```

#### 属性

| 名称                    | 类型               | 默认值         | 说明              |
| --------------------- | ---------------- | ----------- | --------------- |
| `editor`              | `Editor \| null` | `undefined` | Tiptap 编辑器实例    |
| `text`                | `string`         | `undefined` | 按钮的可选文本标签       |
| `hideWhenUnavailable` | `boolean`        | `false`     | 当无法转换为文本格式时隐藏按钮 |
| `onToggled`           | `() => void`     | `undefined` | 成功转换后触发的回调函数    |
| `showShortcut`        | `boolean`        | `false`     | 显示键盘快捷键标识（如果可用） |

## 钩子

### `useText()`

一个自定义钩子，可让你构建自己的文字按钮，完全控制渲染和行为。

#### 用法

```tsx
function MyTextButton() {
  const { isVisible, isActive, canToggle, handleToggle, label, shortcutKeys, Icon } = useText({
    editor: myEditor,
    hideWhenUnavailable: true,
    onToggled: () => console.log('已转换为文本！'),
  })

  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 编辑器实例    |
| `hideWhenUnavailable` | `boolean`        | `false`     | 当无法转换为文本格式时隐藏按钮 |
| `onToggled`           | `() => void`     | `undefined` | 成功转换后触发的回调函数    |

#### 返回值

| 名称             | 类型              | 说明                        |
| -------------- | --------------- | ------------------------- |
| `isVisible`    | `boolean`       | 是否应该渲染按钮                  |
| `isActive`     | `boolean`       | 当前是否处于段落/文本格式激活状态         |
| `canToggle`    | `boolean`       | 当前是否允许转换为文本格式             |
| `handleToggle` | `() => boolean` | 用于将内容转换为文本格式的函数           |
| `label`        | `string`        | 按钮的无障碍标签文本                |
| `shortcutKeys` | `string`        | 键盘快捷键（Cmd/Ctrl + Alt + 0） |
| `Icon`         | `React.FC`      | 文字按钮的图标组件                 |

## 工具函数

### `canToggleText(editor, turnInto?)`

检查当前编辑器状态下内容是否可转换为文本/段落格式。

```tsx
import { canToggleText } from '@/components/tiptap-ui/text-button'

const canToggle = canToggleText(editor) // 检查是否能转换为文本
const canTurnInto = canToggleText(editor, true) // 检查是否能转换为段落
```

### `toggleParagraph(editor)`

以编程方式将当前选区或节点转换为段落格式。

```tsx
import { toggleParagraph } from '@/components/tiptap-ui/text-button'

const success = toggleParagraph(editor)
if (success) {
  console.log('内容已成功转换为文本！')
}
```

### `isParagraphActive(editor)`

检查当前是否处于段落/文本格式激活状态。

```tsx
import { isParagraphActive } from '@/components/tiptap-ui/text-button'

const active = isParagraphActive(editor)
```

## 键盘快捷键

文字按钮支持以下键盘快捷键：

- **Cmd/Ctrl + Alt + 0**：将内容转换为文本/段落格式

使用 `<TextButton />` 组件或 `useText()` 钩子时，快捷键将自动注册。

## 依赖项

### 依赖库

- `@tiptap/react` - Tiptap React 核心集成
- `@tiptap/starter-kit` - 包含段落等基本扩展的 Tiptap 套件
- `react-hotkeys-hook` - 键盘快捷键管理

### 相关组件

- `use-tiptap-editor`（钩子）
- `button`（基础组件）
- `badge`（基础组件）
- `tiptap-utils`（库）
- `type-icon`（图标）