Loading...
功能特性
- 自动从文档标题生成目录
- 平滑滚动至标题位置
套件使用
安装
最快捷的目录功能添加方式是使用 TocKit
,它已预配置了 Plate UI 组件的 TocPlugin
。
TocElement
: 渲染目录元素
添加套件
将套件加入插件列表:
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
添加插件
在创建编辑器时,将 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,
],
});
配置插件
使用自定义组件和滚动选项配置 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
目录生成插件。
转换器
tf.insertToc
插入目录元素。
钩子
useTocElementState
管理 TOC 元素状态。
useTocElement
处理 TOC 元素交互。
useTocSideBarState
管理 TOC 侧边栏状态。
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 侧边栏组件提供属性和处理器。
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
内容滚动处理器