---
title: "颜色高亮按钮"
description: "在 Tiptap 编辑器中，通过预定义颜色、键盘快捷键和完整的无障碍支持，为文本应用颜色高亮。"
canonical_url: "https://tiptap.zhcndoc.com/ui-components/components/color-highlight-button"
---

# 颜色高亮按钮

在 Tiptap 编辑器中，通过预定义颜色、键盘快捷键和完整的无障碍支持，为文本应用颜色高亮。

一个完全无障碍且可定制的颜色高亮按钮，适用于 Tiptap 编辑器。使用键盘快捷键或 UI 为选中文本应用背景色，支持动态颜色集、自定义渲染和无障碍功能。

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

## 安装

通过 Tiptap CLI 添加此组件：

```bash
npx @tiptap/cli@latest add color-highlight-button
```

## 组件

### `<ColorHighlightButton />`

一个可以直接使用的 React 按钮，用于在 Tiptap 编辑器中给选中文本应用颜色高亮。

#### 使用示例

```tsx
import { EditorContent, EditorContext, useEditor } from '@tiptap/react'

// --- Tiptap 核心扩展 ---
import { StarterKit } from '@tiptap/starter-kit'
import { Highlight } from '@tiptap/extension-highlight'

// --- Tiptap UI ---
import { ColorHighlightButton } from '@/components/tiptap-ui/color-highlight-button'

// --- UI 原语 ---
import { ButtonGroup } from '@/components/tiptap-ui-primitive/button'

// --- 节点样式 ---
import '@/components/tiptap-node/code-block-node/code-block-node.scss'
import '@/components/tiptap-node/paragraph-node/paragraph-node.scss'

export default function MyEditor() {
  const editor = useEditor({
    immediatelyRender: false,
    extensions: [StarterKit, Highlight.configure({ multicolor: true })],
    content: `
      <h2>颜色高亮按钮演示</h2>
      <p>欢迎使用颜色高亮按钮！此演示展示了相关功能。</p>
      <h3>使用方法：</h3>
      <p>1. <strong>选择你想高亮的任意文本</strong></p>
      <p>2. <strong>点击颜色按钮</strong>以应用该 <mark data-color="oklch(88.5% 0.062 18.334)" style="background-color: oklch(88.5% 0.062 18.334); color: inherit">高亮</mark></p>
    `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <ButtonGroup orientation="horizontal">
        <ColorHighlightButton tooltip="红色" highlightColor="oklch(88.5% 0.062 18.334)" />
        <ColorHighlightButton
          editor={editor}
          tooltip="橙色"
          highlightColor="oklch(90.1% 0.076 70.697)"
          text="高亮"
          hideWhenUnavailable={true}
          showShortcut={true}
          onApplied={({ color, label }) => console.log(`应用了 ${label} 高亮: ${color}`)}
        />
      </ButtonGroup>

      <EditorContent editor={editor} role="presentation" />
    </EditorContext.Provider>
  )
}
```

#### 属性说明

| 名称                    | 类型                           | 默认值         | 描述                |
| --------------------- | ---------------------------- | ----------- | ----------------- |
| `editor`              | `Editor \| null`             | `undefined` | Tiptap 编辑器实例      |
| `highlightColor`      | `string`                     | 必填          | 要应用的高亮颜色（CSS 颜色值） |
| `text`                | `string`                     | `undefined` | 按钮的可选文本标签         |
| `hideWhenUnavailable` | `boolean`                    | `false`     | 当高亮不可用时隐藏按钮       |
| `onApplied`           | `({ color, label }) => void` | `undefined` | 应用高亮后触发的回调        |
| `showShortcut`        | `boolean`                    | `false`     | 显示键盘快捷键标记（如果有）    |

## Hooks

### `useColorHighlight(config)`

一个强大的 Hook，可帮助你构建自定义颜色高亮按钮，完全控制行为和渲染。

#### 使用示例

```tsx
import { useColorHighlight } from '@/components/tiptap-ui/color-highlight-button'
import { Badge } from '@/components/tiptap-ui-primitive/badge'
import { parseShortcutKeys } from '@/lib/tiptap-utils'

function MyColorHighlightButton() {
  const { isVisible, isActive, canColorHighlight, handleColorHighlight, label, shortcutKeys } =
    useColorHighlight({
      editor: myEditor,
      highlightColor: 'var(--tt-color-highlight-blue)',
      label: '蓝色高亮',
      hideWhenUnavailable: true,
      onApplied: ({ color, label }) => console.log(`已应用：${label}`),
    })

  if (!isVisible) return null

  return (
    <button
      onClick={handleColorHighlight}
      disabled={!canColorHighlight}
      aria-label={label}
      aria-pressed={isActive}
      style={{ backgroundColor: isActive ? highlightColor : 'transparent' }}
    >
      {label}
      {shortcutKeys && <Badge>{parseShortcutKeys({ shortcutKeys })}</Badge>}
    </button>
  )
}
```

#### 属性说明

| 名称                    | 类型                                 | 默认值         | 描述            |
| --------------------- | ---------------------------------- | ----------- | ------------- |
| `editor`              | `Editor \| null`                   | `undefined` | Tiptap 编辑器实例  |
| `highlightColor`      | `string`                           | 必填          | 要应用的高亮颜色      |
| `label`               | `string`                           | 可选          | 按钮的无障碍标签      |
| `hideWhenUnavailable` | `boolean`                          | `false`     | 如果无法应用高亮，隐藏按钮 |
| `mode`                | `"mark" \| "node"`                 | `"mark"`    | 高亮模式（标记或节点背景） |
| `onApplied`           | `({ color, label, mode }) => void` | `undefined` | 应用高亮后触发的回调    |

#### 返回值说明

| 名称                      | 类型                 | 描述                          |
| ----------------------- | ------------------ | --------------------------- |
| `isVisible`             | `boolean`          | 是否应渲染按钮                     |
| `isActive`              | `boolean`          | 高亮当前是否激活                    |
| `canColorHighlight`     | `boolean`          | 是否可以应用高亮                    |
| `handleColorHighlight`  | `() => boolean`    | 应用颜色高亮的函数                   |
| `handleRemoveHighlight` | `() => boolean`    | 移除高亮的函数                     |
| `label`                 | `string`           | 按钮的无障碍标签文本                  |
| `shortcutKeys`          | `string`           | 键盘快捷键（Cmd/Ctrl + Shift + H） |
| `Icon`                  | `React.FC`         | 使用的图标组件（HighlighterIcon）    |
| `mode`                  | `"mark" \| "node"` | 使用的高亮模式                     |

## 工具函数

### `canColorHighlight(editor, mode?)`

检测当前编辑器状态是否可以应用颜色高亮。

#### 参数说明

| 参数名      | 类型                 | 默认值      | 描述            |
| -------- | ------------------ | -------- | ------------- |
| `editor` | `Editor \| null`   | 必填       | Tiptap 编辑器实例  |
| `mode`   | `"mark" \| "node"` | `"mark"` | 高亮模式（标记或节点背景） |

#### 返回值

`boolean` - 是否可以应用高亮

#### 使用示例

```tsx
import { canColorHighlight } from '@/components/tiptap-ui/color-highlight-button'

const canApply = canColorHighlight(editor)
const canApplyNode = canColorHighlight(editor, 'node')
```

### `isColorHighlightActive(editor, highlightColor?, mode?)`

检测当前选区中是否激活了颜色高亮。

#### 参数说明

| 参数名              | 类型                 | 默认值         | 描述            |
| ---------------- | ------------------ | ----------- | ------------- |
| `editor`         | `Editor \| null`   | 必填          | Tiptap 编辑器实例  |
| `highlightColor` | `string`           | `undefined` | 指定检查的颜色       |
| `mode`           | `"mark" \| "node"` | `"mark"`    | 高亮模式（标记或节点背景） |

#### 返回值

`boolean` - 高亮是否激活

#### 使用示例

```tsx
import { isColorHighlightActive } from '@/components/tiptap-ui/color-highlight-button'

const isActive = isColorHighlightActive(editor) // 是否有任何高亮激活
const isYellowActive = isColorHighlightActive(editor, 'var(--tt-color-highlight-yellow)') // 是否激活指定颜色
const isNodeHighlight = isColorHighlightActive(editor, 'var(--tt-color-highlight-blue)', 'node')
```

### `removeHighlight(editor, mode?)`

从选区中移除当前高亮。

#### 参数说明

| 参数名      | 类型                 | 默认值      | 描述            |
| -------- | ------------------ | -------- | ------------- |
| `editor` | `Editor \| null`   | 必填       | Tiptap 编辑器实例  |
| `mode`   | `"mark" \| "node"` | `"mark"` | 高亮模式（标记或节点背景） |

#### 返回值

`boolean` - 是否成功移除高亮

#### 使用示例

```tsx
import { removeHighlight } from '@/components/tiptap-ui/color-highlight-button'

const success = removeHighlight(editor)
const successNode = removeHighlight(editor, 'node')
```

### `pickHighlightColorsByValue(values)`

根据颜色值过滤默认的高亮颜色列表。

#### 参数说明

| 参数名      | 类型         | 描述        |
| -------- | ---------- | --------- |
| `values` | `string[]` | 要过滤的颜色值数组 |

#### 返回值

`HighlightColor[]` - 匹配的高亮颜色对象数组

#### 使用示例

```tsx
import { pickHighlightColorsByValue } from '@/components/tiptap-ui/color-highlight-button'

const colors = pickHighlightColorsByValue([
  'var(--tt-color-highlight-yellow)',
  'var(--tt-color-highlight-blue)',
])
// 返回包含标签、值和边框属性的完整颜色对象数组
```

## 键盘快捷键

颜色高亮按钮支持以下键盘快捷键：

- **Cmd/Ctrl + Shift + H**：应用颜色高亮

使用 `ColorHighlightButton` 组件或 `useColorHighlight()` Hook 时，会自动注册此快捷键，并将配置的高亮颜色应用到当前选区。

## 需求

### 依赖项

- `@tiptap/react` - Tiptap React 核心集成
- `@tiptap/extension-highlight` - 文本高亮扩展
- `react-hotkeys-hook` - 键盘快捷键管理

### 关联组件

- `use-tiptap-editor`（Hook）
- `button`（原语）
- `badge`（原语）
- `tiptap-utils`（库）
- `highlighter-icon`（图标）