为高亮添加弹出层

Available for free

一个完全无障碍的 Tiptap 编辑器文本高亮颜色选择弹出层。您可以通过精选的颜色调色板应用背景高亮、移除高亮，并通过键盘快捷键和移动设备支持，提供直观的文本高亮界面。

安装

通过 Tiptap CLI 添加该组件：

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

组件

`<ColorHighlightPopover />`

这是一个预构建的 React 组件，提供紧凑弹出层界面中的高亮颜色选择功能。

使用示例

import { EditorContent, EditorContext, useEditor } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { Highlight } from '@tiptap/extension-highlight'
import { ColorHighlightPopover } from '@/components/tiptap-ui/color-highlight-popover'

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: `
        <p style="text-align: left">
            <mark data-color="var(--tt-color-highlight-purple)" style="background-color: var(--tt-color-highlight-purple); color: inherit">
                <span class="selection">突出显示的文本</span>
            </mark>
            <span class="selection"> </span>
            <mark data-color="var(--tt-color-highlight-red)" style="background-color: var(--tt-color-highlight-red); color: inherit">
                <span class="selection">用</span>
            </mark>
            <span class="selection"> </span>
            <mark data-color="var(--tt-color-highlight-green)" style="background-color: var(--tt-color-highlight-green); color: inherit">
                <span class="selection">不同的</span>
            </mark>
            <span class="selection"> </span>
            <mark data-color="var(--tt-color-highlight-blue)" style="background-color: var(--tt-color-highlight-blue); color: inherit">
                <span class="selection">颜色</span>
            </mark>
            <span class="selection"> 中以突出重点。</span>
        </p>
        `,
  })

  return (
    <EditorContext.Provider value={{ editor }}>
      <ColorHighlightPopover
        editor={editor}
        hideWhenUnavailable={true}
        onApplied={({ color, label }) => console.log(`应用高亮: ${label} (${color})`)}
      />

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

参数说明

名称	类型	默认值	描述
editor	Editor \| null	undefined	Tiptap 编辑器实例
colors	HighlightColor[]	默认高亮色调色板	自定义显示的高亮颜色
hideWhenUnavailable	boolean	false	当高亮功能不可用时是否隐藏弹出层
onApplied	HighlightHandler	undefined	应用或移除高亮时调用的回调函数

`<ColorHighlightPopoverContent />`

这是显示颜色调色板以及删除选项的内容组件。可用于自定义弹出层实现时独立使用。

使用示例

<PopoverContent>
  <ColorHighlightPopoverContent editor={editor} colors={customColors} />
</PopoverContent>

参数说明

名称	类型	默认值	描述
editor	Editor \| null	undefined	Tiptap 编辑器实例
colors	HighlightColor[]	默认调色板	自定义高亮颜色

Hooks

`useColorHighlight()`

一个自定义钩子，用于构建您自己的高亮功能，完全控制行为和渲染。

使用示例

function MyHighlightButton() {
  const {
    isVisible,
    isActive,
    canColorHighlight,
    handleColorHighlight,
    handleRemoveHighlight,
    label,
    shortcutKeys,
    Icon,
  } = useColorHighlight({
    editor: myEditor,
    highlightColor: 'var(--tt-color-highlight-yellow)',
    label: '黄色高亮',
    hideWhenUnavailable: true,
    onApplied: ({ color, label }) => {
      console.log(`应用高亮: ${label} (${color})`)
    },
  })

  if (!isVisible) return null

  return (
    <button
      onClick={handleColorHighlight}
      disabled={!canColorHighlight}
      aria-label={label}
      aria-pressed={isActive}
    >
      <Icon />
      {label}
      <kbd>{shortcutKeys}</kbd>
    </button>
  )
}

参数说明

名称	类型	默认值	描述
editor	Editor \| null	undefined	Tiptap 编辑器实例
highlightColor	string	undefined	高亮的 CSS 颜色值
label	string	undefined	高亮的无障碍文本标签
hideWhenUnavailable	boolean	false	高亮不可用时是否隐藏
onApplied	HighlightHandler	undefined	高亮状态更改时触发的回调

返回值

名称	类型	描述
isVisible	boolean	按钮是否应被渲染
isActive	boolean	高亮当前是否激活
canColorHighlight	boolean	当前是否允许高亮
handleColorHighlight	() => boolean	应用/切换高亮的函数
handleRemoveHighlight	() => boolean	移除任何高亮的函数
label	string	按钮的无障碍标签文本
shortcutKeys	string	键盘快捷键（Cmd/Ctrl + Shift + H）
Icon	React.FC	高亮按钮的图标组件

实用函数

`canColorHighlight(editor)`

检查当前编辑器状态是否允许使用高亮。

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

const canHighlight = canColorHighlight(editor)
if (canHighlight) {
  // 显示高亮选项
}

`removeHighlight(editor)`

程序化地移除当前选择中的所有高亮。

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

const success = removeHighlight(editor)
if (success) {
  console.log('已移除高亮！')
}

键盘快捷键

高亮弹出层支持以下键盘快捷键：

Cmd/Ctrl + Shift + H：切换高亮（在配置具体颜色时生效）

// 使用 useColorHighlight 钩子时该快捷键自动生效
const { shortcutKeys } = useColorHighlight({
  editor,
  highlightColor: 'var(--tt-color-highlight-yellow)',
})

console.log(shortcutKeys) // "mod+shift+h"

依赖

依赖库

@tiptap/react - 核心 Tiptap React 集成
@tiptap/extension-highlight - 提供文本高亮功能的扩展

参考的组件

use-tiptap-editor（钩子）
use-menu-navigation（钩子）
use-mobile（钩子）
button（基础组件）
popover（基础组件）
card（基础组件）
separator（基础组件）
highlighter-icon（图标）
ban-icon（图标）
color-highlight-button（组件）
tiptap-utils（库）

Previously颜色高亮按钮

Next up文字颜色按钮