文字按钮

Available in Start plan

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

安装

通过 Tiptap CLI 添加该组件：

npx @tiptap/cli@latest add text-button

组件

`<TextButton />`

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

用法

<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()`

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

用法

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

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

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

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

`toggleParagraph(editor)`

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

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

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

`isParagraphActive(editor)`

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

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 - 键盘快捷键管理

安装

组件

<TextButton />

用法

属性

钩子

useText()

用法

属性

返回值

工具函数

canToggleText(editor, turnInto?)

toggleParagraph(editor)

isParagraphActive(editor)