导航反馈

PreviousNext

在 TOC、脚注、搜索或自定义跳转之后高亮落点目标。

功能特性

  • 在导航跳转后短暂高亮落点节点
  • 确定性替换上一次高亮，而不是叠加计时器
  • 为纯高亮和带选择的导航流提供编辑器方法
  • 注入 data-nav-* 属性，便于自定义渲染层样式

导航反馈是一个小型核心插件，用来表达“你跳到了这里”。

它适合：

  • 目录跳转
  • 脚注导航
  • 搜索与查找跳转
  • 自定义锚点或大纲导航

手动使用

核心插件

NavigationFeedbackPlugin 属于 Plate 核心插件的一部分。

如果你使用 createPlateEditor 创建编辑器，它会自动启用。你不需要 为了默认行为单独把它加入 plugins 数组。

配置时长

如果你想调整高亮时长，可以通过根插件配置这个核心插件：

import { createPlateEditor, NavigationFeedbackPlugin } from 'platejs/react';
 
const editor = createPlateEditor({
  rootPlugin: (plugin) =>
    plugin.configurePlugin(NavigationFeedbackPlugin, {
      options: {
        duration: 1200,
      },
    }),
});
import { createPlateEditor, NavigationFeedbackPlugin } from 'platejs/react';
 
const editor = createPlateEditor({
  rootPlugin: (plugin) =>
    plugin.configurePlugin(NavigationFeedbackPlugin, {
      options: {
        duration: 1200,
      },
    }),
});
  • options.duration：默认高亮时长，单位为毫秒
    • 默认值： 800

仅高亮目标

如果跳转本身已经完成，只需要落点确认，用 editor.tf.navigation.flashTarget(...)：

editor.tf.navigation.flashTarget({
  target: {
    path: [12],
    type: 'node',
  },
});
editor.tf.navigation.flashTarget({
  target: {
    path: [12],
    type: 'node',
  },
});

也可以为单次调用覆盖时长或高亮变体：

editor.tf.navigation.flashTarget({
  duration: 1500,
  target: {
    path: [12],
    type: 'node',
  },
  variant: 'navigated',
});
editor.tf.navigation.flashTarget({
  duration: 1500,
  target: {
    path: [12],
    type: 'node',
  },
  variant: 'navigated',
});

在一次调用中导航并高亮

如果同一个动作应该同时：

  • 修改选择
  • 聚焦编辑器
  • 滚动到目标
  • 高亮目标

那就使用 editor.tf.navigation.navigate(...)：

editor.tf.navigation.navigate({
  select: {
    anchor: { offset: 0, path: [12, 0] },
    focus: { offset: 0, path: [12, 0] },
  },
  target: {
    path: [12],
    type: 'node',
  },
});
editor.tf.navigation.navigate({
  select: {
    anchor: { offset: 0, path: [12, 0] },
    focus: { offset: 0, path: [12, 0] },
  },
  target: {
    path: [12],
    type: 'node',
  },
});

也可以细调：

editor.tf.navigation.navigate({
  flash: {
    duration: 1200,
    variant: 'navigated',
  },
  focus: true,
  scroll: true,
  scrollTarget: { offset: 0, path: [12, 0] },
  select: { offset: 0, path: [12, 0] },
  target: {
    path: [12],
    type: 'node',
  },
});
editor.tf.navigation.navigate({
  flash: {
    duration: 1200,
    variant: 'navigated',
  },
  focus: true,
  scroll: true,
  scrollTarget: { offset: 0, path: [12, 0] },
  select: { offset: 0, path: [12, 0] },
  target: {
    path: [12],
    type: 'node',
  },
});
  • flash：当前调用的高亮配置。设为 false 可跳过视觉反馈
  • focus：导航后聚焦编辑器
    • 默认值： true
  • scroll：将目标滚动到可视区域
    • 默认值： true
  • scrollTarget：显式指定滚动点
  • select：高亮前应用的点或范围

自定义落点样式

插件会在激活节点上注入这些临时属性：

  • data-nav-highlight
  • data-nav-cycle
  • data-nav-pulse
  • data-nav-target

还会注入这个 CSS 变量：

  • --plate-nav-feedback-duration

Plate 文档站在自己的 globals.css 中为这些属性提供了默认样式。你也可以在任意编辑器外壳中自定义：

.slate-editor [data-nav-highlight] {
  border-radius: 0.375rem;
}
 
.slate-editor [data-nav-highlight][data-nav-cycle='0'] {
  animation: plate-nav-highlight-a var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}
 
.slate-editor [data-nav-highlight][data-nav-cycle='1'] {
  animation: plate-nav-highlight-b var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}
.slate-editor [data-nav-highlight] {
  border-radius: 0.375rem;
}
 
.slate-editor [data-nav-highlight][data-nav-cycle='0'] {
  animation: plate-nav-highlight-a var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}
 
.slate-editor [data-nav-highlight][data-nav-cycle='1'] {
  animation: plate-nav-highlight-b var(--plate-nav-feedback-duration, 900ms)
    ease-out;
}

插件

NavigationFeedbackPlugin

用于成功导航后短暂“落点高亮”的核心插件。

Options

    默认高亮时长，单位为毫秒。

    • 默认值： 800

API

api.navigation.activeTarget

获取当前高亮目标。

Returns

    当前导航目标元数据；如果没有激活高亮则返回 null。

api.navigation.clear

立即清除当前导航高亮目标。

api.navigation.isTarget

判断某个路径是否就是当前高亮目标。

Parameters

    要比较的路径。

Transforms

tf.navigation.clear

立即清除当前高亮目标。

tf.navigation.flashTarget

只高亮目标节点，不修改选择、焦点或滚动。

Parameters

    需要高亮的节点目标。

    覆盖本次调用的默认时长。

    写入 data-nav-highlight 的高亮变体。

    • 默认值： navigated

tf.navigation.navigate

在一次调用中完成选择、聚焦、滚动与高亮。

Parameters

    需要导航到的节点目标。

    在滚动和高亮前应用的点或范围。

    导航后聚焦编辑器。

    • 默认值： true

    将目标滚动到可视区域。

    • 默认值： true

    显式指定滚动点。

    本次导航调用的高亮配置。

相关文档