Tiptap 中文文档

颜色文本弹出框

Available in Start plan

一个对 Tiptap 编辑器完全可访问的文本颜色按钮。支持键盘快捷键应用前景色到选中文本，并提供灵活的自定义选项。

安装

通过 Tiptap CLI 添加该组件：

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

组件

<ColorTextPopover />

一个预构建的 React 组件，提供文本和高亮颜色选择的弹出界面。

用法 

export default function MyEditor() {
  return (
    <ColorTextPopover
      editor={editor}
      hideWhenUnavailable={true}
      onColorChanged={({ type, label, value }) =>
        console.log(`应用了 ${type} 颜色: ${label} (${value})`)
      }
    />
  )
}

属性（Props）

名称类型默认值描述
editorEditor | nullundefinedTiptap 编辑器实例
hideWhenUnavailablebooleanfalse当颜色样式不可用时隐藏弹出框
onColorChangedColorChangeHandlerundefined颜色应用时触发的回调

Hooks

useColorTextPopover()

一个自定义 Hook，帮助你构建自己的颜色弹出框，完全控制行为与渲染。

用法 

function MyColorPopover() {
  const {
    isVisible,
    canToggle,
    activeTextStyle,
    activeHighlight,
    handleColorChanged,
    label,
    Icon,
  } = useColorTextPopover({
    editor: myEditor,
    hideWhenUnavailable: true,
    onColorChanged: ({ type, label, value }) => {
      console.log(`颜色变更: ${type} - ${label} (${value})`)
    },
  })

  if (!isVisible) return null

  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button disabled={!canToggle} aria-label={label}>
          <Icon
            style={{
              color: activeTextStyle.color,
              backgroundColor: activeHighlight.color,
            }}
          />
        </Button>
      </PopoverTrigger>
      <PopoverContent>
        <TextStyleColorPanel onColorChanged={handleColorChanged} />
      </PopoverContent>
    </Popover>
  )
}

属性（Props）

名称类型默认值描述
editorEditor | nullundefinedTiptap 编辑器实例
hideWhenUnavailablebooleanfalse当颜色功能不可用时是否隐藏弹出框
onColorChangedColorChangeHandlerundefined颜色变更时的回调函数

返回值

名称类型描述
isVisibleboolean弹出框是否应当渲染
canToggleboolean当前是否允许更改颜色
activeTextStyleobject当前文本样式属性（包含颜色）
activeHighlightobject当前高亮样式属性（包含颜色）
handleColorChangedColorChangeHandler处理颜色选择变化的函数
labelstring触发按钮的辅助文本（无障碍）
IconReact.FC颜色弹出按钮使用的图标组件

颜色管理

最近使用颜色

该弹出框自动跟踪并显示最近使用的颜色，使用 useRecentColors Hook：

const { recentColors, addRecentColor, isInitialized } = useRecentColors(3)

// 最近颜色会自动存储于 localStorage

工具函数

getColorByValue(value, colorArray)

根据颜色值从颜色数组中查找对应颜色对象。

import { getColorByValue, TEXT_COLORS } from '@/components/tiptap-ui/color-text-popover'

const blueColor = getColorByValue('var(--tt-color-text-blue)', TEXT_COLORS)
// 返回: { label: "蓝色文本", value: "var(--tt-color-text-blue)", ... }

shouldShowColorTextPopover(params)

根据编辑器状态判断颜色弹出框是否应该显示。

import { shouldShowColorTextPopover } from '@/components/tiptap-ui/color-text-popover'

const shouldShow = shouldShowColorTextPopover({
  editor: myEditor,
  hideWhenUnavailable: true,
})

依赖要求

依赖包

  • @tiptap/react - Tiptap React 核心集成
  • @tiptap/extension-text-style - 支持颜色的文本样式扩展
  • @tiptap/extension-highlight - 支持文本高亮的扩展

关联组件

  • use-tiptap-editor（Hook）
  • use-menu-navigation（Hook）
  • button（基础组件）
  • popover（基础组件）
  • card（基础组件）
  • chevron-down-icon（图标）
  • text-color-small-icon（图标）
  • color-text-button（组件）
  • color-highlight-button（组件）
  • tiptap-utils（库）
Previously文字颜色按钮