║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: 光标覆盖层 description: 当编辑器失去焦点时，为选中区域和光标位置提供视觉反馈。 docs:

• route: /docs/components/cursor-overlay title: 光标覆盖层

---

<ComponentPreview name="cursor-overlay-demo" /> <PackageInfo>

功能特性

• 当其他元素获得焦点时保持选中高亮
• 动态显示选中区域（例如AI流式输出时）
• 拖拽操作时显示光标位置
• 可自定义光标和选中区域的样式
• 外部UI交互必备功能（如链接工具栏、AI组合框）

</PackageInfo>

套件使用

<Steps>

安装

最快捷的添加光标覆盖功能的方式是使用CursorOverlayKit，它包含预配置的CursorOverlayPlugin和CursorOverlay UI组件。

<ComponentSource name="cursor-overlay-kit" />

• CursorOverlay: 渲染光标和选中区域覆盖层

添加套件

import { createPlateEditor } from 'platejs/react';
import { CursorOverlayKit } from '@/components/editor/plugins/cursor-overlay-kit';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    ...CursorOverlayKit,
  ],
});

</Steps>

手动配置

<Steps>

安装

npm install @platejs/selection

添加插件

import { CursorOverlayPlugin } from '@platejs/selection/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    CursorOverlayPlugin,
  ],
});

配置插件

通过组件配置光标覆盖层的渲染方式：

import { CursorOverlayPlugin } from '@platejs/selection/react';
import { CursorOverlay } from '@/components/ui/cursor-overlay';

CursorOverlayPlugin.configure({
  render: {
    afterEditable: () => <CursorOverlay />,
  },
});

• render.afterEditable: 指定CursorOverlay在可编辑内容之后渲染

编辑器容器设置

光标覆盖层需要容器组件来确保正确定位。如果使用Editor组件，会通过EditorContainer自动处理。

自定义配置时，确保编辑器被带有唯一ID的容器包裹：

import { PlateContainer } from 'platejs/react';

export function EditorContainer(props: React.HTMLAttributes<HTMLDivElement>) {
  return <PlateContainer {...props} />;
}

保持选中焦点

当聚焦UI元素时，要维持编辑器的选中状态，需为这些元素添加data-plate-focus="true"属性：

<ToolbarButton data-plate-focus="true">
  {/* 工具栏内容 */}
</ToolbarButton>

这可以防止与工具栏按钮或其他UI元素交互时光标覆盖层消失。

</Steps>

插件

CursorOverlayPlugin

管理光标和选中区域覆盖层以提供视觉反馈的插件。

<API name="CursorOverlayPlugin"> <APIOptions> <APIItem name="cursors" type="Record<string, CursorState<CursorData>>"> 包含光标状态及其唯一标识符的对象 - **默认值:** `{}` </APIItem> </APIOptions> </API>

API接口

api.cursorOverlay.addCursor

添加指定键和状态的光标覆盖层

<API name="addCursor"> <APIParameters> <APIItem name="key" type="string"> 光标的唯一标识符（如'blur'、'drag'、'custom'） </APIItem> <APIItem name="cursor" type="CursorState<CursorData>"> 包含选中区域和可选样式数据的光标状态 </APIItem> </APIParameters> </API>

api.cursorOverlay.removeCursor

通过键移除光标覆盖层

<API name="removeCursor"> <APIParameters> <APIItem name="key" type="string"> 要移除的光标键名 </APIItem> </APIParameters> </API>

钩子

useCursorOverlay

管理光标和选中区域覆盖层状态的钩子，提供实时光标位置和选中区域矩形。

<API name="useCursorOverlay"> <APIOptions type="object"> <APIItem name="minSelectionWidth" type="number" optional> 选中区域矩形的最小宽度（像素）。可用于使光标插入符更明显 - **默认值:** `1` </APIItem> <APIItem name="refreshOnResize" type="boolean" optional> 容器调整大小时是否重新计算光标位置 - **默认值:** `true` </APIItem> </APIOptions> <APIReturns type="object"> <APIItem name="cursors" type="CursorOverlayState<TCursorData>[]"> 包含对应选中区域矩形和样式数据的光标状态数组 </APIItem> <APIItem name="refresh" type="() => void"> 手动触发重新计算光标位置的函数 </APIItem> </APIReturns> </API>

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║