Loading...

功能特性

  • 自动从文档标题生成目录
  • 平滑滚动至标题位置

套件使用

安装

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

添加套件

将套件加入插件列表:

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

添加插件

在创建编辑器时,将 TocPluginHnPlugin 加入 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,
  ],
});

配置插件

使用自定义组件和滚动选项配置 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,
      },
    }),
  ],
});
  • node.component: 指定渲染目录元素的 TocElement
  • options.topOffset: 设置滚动至标题时的顶部偏移量
  • options.isScroll: 启用滚动至标题的行为

添加工具栏按钮

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

{
  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>;
}
  • 若您的滚动元素是编辑器容器的祖先元素,将 useEditorScrollRef() 作为 ref 属性传入。例如:
// 在 <Plate> 组件下方
function Layout() {
  const scrollRef = useEditorScrollRef();
 
  return (
    <main ref={scrollRef}>
      <EditorContainer>
        <PlateContent />
      </EditorContainer>
    </main>
  );
}

Plate Plus

插件

TocPlugin

目录生成插件。

Options

  • isScroll optional boolean

    启用滚动行为

    • 默认值: true
  • topOffset optional number

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

    • 默认值: 80
  • queryHeading optional (editor: SlateEditor) => Heading[]

    自定义标题查询函数

转换器

tf.insertToc

插入目录元素。

OptionsInsertNodesOptions<SlateEditor>

    节点插入选项

钩子

useTocElementState

管理 TOC 元素状态。

Returns

Collapse all
  • headingList Heading[]

    文档标题数组

  • onContentScroll (el: HTMLElement, id: string, behavior: ScrollBehavior) => void

    标题滚动处理器

useTocElement

处理 TOC 元素交互。

Parameters

Collapse all
  • onContentScroll (el: HTMLElement, id: string, behavior: ScrollBehavior) => void

    来自 useTocElementState 的滚动处理器

Returns

Collapse all
  • props object

    TOC 元素属性

useTocSideBarState

管理 TOC 侧边栏状态。

Parameters

Collapse all
  • open optional boolean

    初始展开状态

    • 默认值: true
  • rootMargin optional string

    Intersection Observer 根边距

    • 默认值: '0px 0px 0px 0px'
  • topOffset optional number

    滚动顶部偏移量

    • 默认值: 0

Returns

Collapse all
  • activeContentId string

    当前活动区块 ID

  • headingList Heading[]

    文档标题列表

  • mouseInToc boolean

    鼠标悬停 TOC 状态

  • open boolean

    侧边栏展开状态

  • setIsObserve React.Dispatch<React.SetStateAction<boolean>>

    设置观察状态

  • setMouseInToc React.Dispatch<React.SetStateAction<boolean>>

    设置鼠标悬停状态

  • tocRef React.RefObject<HTMLElement>

    TOC 元素引用

  • onContentScroll (options: { id: string; behavior?: ScrollBehavior; el: HTMLElement }) => void

    内容滚动处理器

useTocSideBar

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

Parameters

Collapse all
  • mouseInToc boolean

    鼠标悬停 TOC 状态

  • open boolean

    侧边栏展开状态

  • setIsObserve React.Dispatch<React.SetStateAction<boolean>>

    设置观察状态

  • setMouseInToc React.Dispatch<React.SetStateAction<boolean>>

    设置鼠标悬停状态

  • tocRef React.RefObject<HTMLElement>

    TOC 元素引用

  • onContentScroll (options: { id: string; behavior?: ScrollBehavior; el: HTMLElement }) => void

    内容滚动处理器

Returns

Collapse all
  • navProps object

    导航元素属性

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

    TOC 项点击处理器