颜色高亮按钮

Available for free

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

安装

通过 Tiptap CLI 添加此组件：

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

组件

`<ColorHighlightButton />`

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

使用示例

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，可帮助你构建自定义颜色高亮按钮，完全控制行为和渲染。

使用示例

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 - 是否可以应用高亮

使用示例

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 - 高亮是否激活

使用示例

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 - 是否成功移除高亮

使用示例

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

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

`pickHighlightColorsByValue(values)`

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

参数说明

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

返回值

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

使用示例

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（图标）

Previously代码块按钮

Next up颜色高亮弹出框