工具栏

PreviousNext

为编辑器提供固定和浮动工具栏。

固定工具栏浮动工具栏
Loading...

功能特性

  • 固定工具栏: 持久固定在编辑器顶部的工具栏
  • 浮动工具栏: 文本选中时出现的上下文工具栏
  • 可定制按钮: 轻松添加、删除和重新排序工具栏按钮
  • 响应式设计: 适配不同屏幕尺寸和内容
  • 插件集成: 与Plate插件和UI组件无缝集成

套件使用

安装

最快捷的方式是使用FixedToolbarKit和FloatingToolbarKit，它们包含预配置的工具栏插件及其Plate UI组件。

添加套件

import { createPlateEditor } from 'platejs/react';
import { FixedToolbarKit } from '@/components/editor/plugins/fixed-toolbar-kit';
import { FloatingToolbarKit } from '@/components/editor/plugins/floating-toolbar-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    ...FixedToolbarKit,
    ...FloatingToolbarKit,
  ],
});

手动配置

创建插件

import { createPlatePlugin } from 'platejs/react';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { FixedToolbarButtons } from '@/components/ui/fixed-toolbar-buttons';
import { FloatingToolbar } from '@/components/ui/floating-toolbar';
import { FloatingToolbarButtons } from '@/components/ui/floating-toolbar-buttons';
 
const fixedToolbarPlugin = createPlatePlugin({
  key: 'fixed-toolbar',
  render: {
    beforeEditable: () => (
      <FixedToolbar>
        <FixedToolbarButtons />
      </FixedToolbar>
    ),
  },
});
 
const floatingToolbarPlugin = createPlatePlugin({
  key: 'floating-toolbar',
  render: {
    afterEditable: () => (
      <FloatingToolbar>
        <FloatingToolbarButtons />
      </FloatingToolbar>
    ),
  },
});
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    fixedToolbarPlugin,
    floatingToolbarPlugin,
  ],
});
  • render.beforeEditable: 在编辑器内容上方渲染FixedToolbar
  • render.afterEditable: 在编辑器后渲染FloatingToolbar作为覆盖层

自定义固定工具栏按钮

FixedToolbarButtons组件包含固定工具栏的默认按钮集。

可以通过编辑components/ui/fixed-toolbar-buttons.tsx来自定义。

自定义浮动工具栏按钮

同样地，可以通过编辑components/ui/floating-toolbar-buttons.tsx来自定义浮动工具栏。

创建自定义按钮

这个示例展示了一个向编辑器插入自定义文本的按钮。

import { useEditorRef } from 'platejs/react';
import { CustomIcon } from 'lucide-react';
import { ToolbarButton } from '@/components/ui/toolbar';
 
export function CustomToolbarButton() {
  const editor = useEditorRef();
 
  return (
    <ToolbarButton
      onClick={() => {
        // 自定义操作
        editor.tf.insertText('自定义文本');
      }}
      tooltip="自定义操作"
    >
      <CustomIcon />
    </ToolbarButton>
  );
}

创建标记按钮

对于切换粗体或斜体等标记，可以使用MarkToolbarButton组件。它会自动处理切换状态和操作。

这个示例创建了一个"粗体"按钮。

import { BoldIcon } from 'lucide-react';
 
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
 
export function BoldToolbarButton() {
  return (
    <MarkToolbarButton nodeType="bold" tooltip="粗体 (⌘+B)">
      <BoldIcon />
    </MarkToolbarButton>
  );
}
  • nodeType: 指定要切换的标记类型(如bold、italic)
  • tooltip: 为按钮提供提示信息
  • MarkToolbarButton使用useMarkToolbarButtonState获取切换状态，使用useMarkToolbarButton获取onClick处理器和其他属性

转换工具栏按钮

TurnIntoToolbarButton提供下拉菜单将当前块转换为不同类型(标题、列表、引用等)。

要添加新的块类型选项，编辑turnIntoItems数组:

const turnIntoItems = [
  // ... 现有项
  {
    icon: <CustomIcon />,
    keywords: ['custom', 'special'],
    label: '自定义块',
    value: 'custom-block',
  },
];

插入工具栏按钮

InsertToolbarButton提供下拉菜单插入各种元素(块、列表、媒体、内联元素)。

要添加新的可插入项，将其添加到groups数组的相应分组中:

{
  group: '基础块',
  items: [
    // ... 现有项
    {
      icon: <CustomIcon />,
      label: '自定义块',
      value: 'custom-block',
    },
  ].map((item) => ({
    ...item,
    onSelect: (editor, value) => {
      insertBlock(editor, value);
    },
  })),
}

插件

FixedToolbarKit

在编辑器内容上方渲染固定工具栏的插件。

Options

  • render.beforeEditable () => ReactNode

    在编辑器内容前渲染固定工具栏。默认包含FixedToolbarButtons。

FloatingToolbarKit

在文本选中时渲染浮动工具栏的插件。

Options

Collapse all

  • render.afterEditable () => ReactNode

    在编辑器后作为覆盖层渲染浮动工具栏。默认包含FloatingToolbarButtons。

TabbableToolbar