目录

PreviousNext

Renders a table of contents element with clickable links to headings in the document.

Toc 元素Toc 侧边栏
Loading…

功能特性

  • 自动从文档标题生成目录
  • 平滑滚动至标题位置
  • 滚动时跟踪当前活动标题

套件使用

安装

最快捷的目录功能添加方式是使用 TocKit，它已预配置了 Plate UI 组件的 TocPlugin。

'use client';
 
import { TocPlugin } from '@platejs/toc/react';
 
import { TocElement } from '@/components/ui/toc-node';
 
export const TocKit = [
  TocPlugin.configure({
    options: {
      // isScroll: true,
      topOffset: 80,
    },
  }).withComponent(TocElement),
];
'use client';
 
import { TocPlugin } from '@platejs/toc/react';
 
import { TocElement } from '@/components/ui/toc-node';
 
export const TocKit = [
  TocPlugin.configure({
    options: {
      // isScroll: true,
      topOffset: 80,
    },
  }).withComponent(TocElement),
];

添加套件

将套件加入插件列表：

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

手动配置

安装

pnpm add @platejs/basic-nodes @platejs/toc
pnpm add @platejs/basic-nodes @platejs/toc

添加插件

在创建编辑器时，将 TocPlugin 和 HnPlugin 加入 Plate 插件数组。

import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    H1Plugin,
    H2Plugin,
    H3Plugin,
    TocPlugin,
  ],
});
import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    H1Plugin,
    H2Plugin,
    H3Plugin,
    TocPlugin,
  ],
});

配置插件

使用自定义组件和滚动选项配置 TocPlugin。

import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
import { TocElement } from '@/components/ui/toc-node';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    H1Plugin.withComponent(H1Element),
    H2Plugin.withComponent(H2Element),
    H3Plugin.withComponent(H3Element),
    TocPlugin.configure({
      node: { component: TocElement },
      options: {
        topOffset: 80,
        isScroll: true,
      },
    }),
  ],
});
import { TocPlugin } from '@platejs/toc/react';
import { H1Plugin, H2Plugin, H3Plugin } from '@platejs/basic-nodes/react';
import { createPlateEditor } from 'platejs/react';
import { TocElement } from '@/components/ui/toc-node';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    H1Plugin.withComponent(H1Element),
    H2Plugin.withComponent(H2Element),
    H3Plugin.withComponent(H3Element),
    TocPlugin.configure({
      node: { component: TocElement },
      options: {
        topOffset: 80,
        isScroll: true,
      },
    }),
  ],
});
  • node.component: 指定渲染目录元素的 TocElement
  • options.topOffset: 设置滚动至标题时的顶部偏移量
  • options.isScroll: 启用滚动至标题的行为

添加工具栏按钮

可将此项加入插入工具栏按钮来插入目录元素：

{
  icon: <TableOfContentsIcon />,
  label: '目录',
  value: KEYS.toc,
}
{
  icon: <TableOfContentsIcon />,
  label: '目录',
  value: KEYS.toc,
}

滚动容器设置

  • 若您的滚动元素是 EditorContainer，可跳过此步骤
  • 若您的滚动元素是编辑器容器，将 useEditorContainerRef() 作为 ref 属性传入。例如：
// 在 <Plate> 组件下方
function EditorContainer({ children }: { children: React.ReactNode }) {
  const containerRef = useEditorContainerRef();
 
  return <div ref={containerRef}>{children}</div>;
}
// 在 <Plate> 组件下方
function EditorContainer({ children }: { children: React.ReactNode }) {
  const containerRef = useEditorContainerRef();
 
  return <div ref={containerRef}>{children}</div>;
}
  • 若您的滚动元素是编辑器容器的祖先元素，将 useEditorScrollRef() 作为 ref 属性传入。例如：
// 在 <Plate> 组件下方
function Layout() {
  const scrollRef = useEditorScrollRef();
 
  return (
    <main ref={scrollRef}>
      <EditorContainer>
        <PlateContent />
      </EditorContainer>
    </main>
  );
}
// 在 <Plate> 组件下方
function Layout() {
  const scrollRef = useEditorScrollRef();
 
  return (
    <main ref={scrollRef}>
      <EditorContainer>
        <PlateContent />
      </EditorContainer>
    </main>
  );
}

Plate Plus

  • Sticky TOC sidebar
  • Hover-to-expand: Opens automatically when you move your mouse over it
  • Interactive navigation: Click on items to smoothly scroll to the corresponding heading
  • Visual feedback: Highlights the current section in the sidebar
  • Beautifully crafted UI

插件

TocPlugin

目录生成插件。

Options

    启用滚动行为

    • 默认值: true

    滚动至标题时的顶部偏移量

    • 默认值: 80

    自定义标题查询函数

转换器

tf.insertToc

插入目录元素。

OptionsInsertNodesOptions<SlateEditor>

    节点插入选项

钩子

useTocElementState

管理 TOC 元素状态。

Returns

    当前文档位置对应的活动标题 ID

    文档标题数组

    标题滚动处理器

useTocElement

处理 TOC 元素交互。

Parameters

    来自 useTocElementState 的滚动处理器

Returns

    TOC 元素属性

useTocSideBarState

管理 TOC 侧边栏状态。

Parameters

    初始展开状态

    • 默认值: true

    Intersection Observer 根边距

    • 默认值: '0px 0px 0px 0px'

    滚动顶部偏移量

    • 默认值: 0

Returns

    当前活动区块 ID

    文档标题列表

    鼠标悬停 TOC 状态

    侧边栏展开状态

    设置观察状态

    设置鼠标悬停状态

    TOC 元素引用

    内容滚动处理器

useTocSideBar

该钩子为 TOC 侧边栏组件提供属性和处理器。

Parameters

    鼠标悬停 TOC 状态

    侧边栏展开状态

    设置观察状态

    设置鼠标悬停状态

    TOC 元素引用

    内容滚动处理器

Returns

    导航元素属性

    navProps.onContentClick (e: React.MouseEvent<HTMLElement, MouseEvent>, item: Heading, behavior?: ScrollBehavior) => void

    TOC 项点击处理器