分栏 - Plate — ContextQMD

功能特性

在文档中添加分栏布局
通过 column-group-node 工具栏选择多种分栏样式
可调整栏宽

</PackageInfo>

套件使用

<Steps>

安装

最快捷的方式是使用 ColumnKit，它包含预配置的 ColumnPlugin 和 ColumnItemPlugin 以及 Plate UI 组件。

ColumnGroupElement: 渲染分栏组容器
ColumnElement: 渲染单个分栏项

添加套件

将套件加入插件列表：

tsx

import { createPlateEditor } from 'platejs/react';
import { ColumnKit } from '@/components/editor/plugins/column-kit';

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

</Steps>

手动配置

<Steps>

安装

bash

npm install @platejs/layout

添加插件

在创建编辑器时将分栏插件加入 Plate 插件数组。

tsx

import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
import { createPlateEditor } from 'platejs/react';

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

配置插件

通过自定义组件配置插件来渲染分栏布局。

tsx

import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
import { createPlateEditor } from 'platejs/react';
import { ColumnGroupElement, ColumnElement } from '@/components/ui/column-node';

const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    ColumnPlugin.withComponent(ColumnGroupElement),
    ColumnItemPlugin.withComponent(ColumnElement),
  ],
});

withComponent: 指定 ColumnGroupElement 渲染分栏组容器，ColumnElement 渲染单个分栏。

转换为工具栏按钮

可将此功能添加至转换为工具栏按钮来将区块转为分栏布局：

tsx

{
  icon: <Columns3Icon />,
  label: '3栏布局',
  value: 'action_three_columns',
}

</Steps>

插件

`ColumnPlugin`

为文档添加分栏功能。

`ColumnItemPlugin`

为文档添加分栏项功能。

类型定义

`TColumnGroupElement`

继承自 TElement。

`TColumnElement`

继承自 TElement。

转换方法

`insertColumnGroup`

插入包含两个空栏的分栏组。

<API name="insertColumnGroup"> <APIOptions type="InsertNodesOptions & { columns?: number[] | number }"> - `columns`: 栏宽数组或等宽分栏数量（默认：2） - 其他 `InsertNodesOptions` 用于控制插入行为 <APIItem name="columns" type="number[] | number" optional> 栏宽数组或等宽分栏数量（默认：2） </APIItem> <APIItem name="...InsertNodesOptions" type="InsertNodesOptions"> 其他控制插入行为的选项 </APIItem> </APIOptions> </API>

`insertColumn`

插入一个空栏。

<API name="insertColumn"> <APIOptions type="InsertNodesOptions & { width?: string }"> <APIItem name="width" type="string" optional> 分栏宽度（默认："33%"） </APIItem> <APIItem name="...InsertNodesOptions" type="InsertNodesOptions"> 其他控制插入行为的选项 </APIItem> </APIOptions> </API>

`moveMiddleColumn`

将中间栏向左或向右移动。

<API name="moveMiddleColumn"> <APIParameters> <APIItem name="nodeEntry" type="NodeEntry"> 分栏元素的节点 entry </APIItem> <APIItem name="options" type="{ direction: 'left' | 'right' }"> 控制中间栏移动方向 </APIItem> </APIParameters> <APIReturns type="boolean"> 若中间节点为空则返回 `false`（并移除该节点），否则返回 `true`。 </APIReturns> </API>

`toggleColumnGroup`

将区块转换为分栏组布局或更新现有分栏组的布局。

<API name="toggleColumnGroup"> - 若目标区块不是分栏组，则将其包裹在新的分栏组中并创建指定数量的分栏 - 若目标区块已是分栏组，则使用 `setColumns` 更新其布局 - 原始内容将成为第一栏的内容 - 其他栏将创建空段落 <APIOptions type="object"> <APIItem name="at" type="Location" optional> 切换分栏组的位置 </APIItem> <APIItem name="columns" type="number" optional> 要创建的等宽分栏数量（默认：2） </APIItem> <APIItem name="widths" type="string[]" optional> 栏宽数组（如 ['50%', '50%']），优先级高于 `columns` </APIItem> </APIOptions> </API>

`setColumns`

更新现有分栏组的布局。

<API name="setColumns"> - 增加分栏时： - 保留现有栏内容 - 添加指定宽度的新空栏 - 减少分栏时： - 将被移除栏的内容合并到最后一栏 - 更新剩余栏的宽度 - 分栏数量不变时： - 仅更新栏宽 <APIOptions type="object"> <APIItem name="at" type="Path"> 分栏组元素的路径 </APIItem> <APIItem name="columns" type="number" optional> 要创建的等宽分栏数量 </APIItem> <APIItem name="widths" type="string[]" optional> 栏宽数组（如 ['33%', '67%']），优先级高于 `columns` </APIItem> </APIOptions> </API>

钩子函数

`useDebouncePopoverOpen`

<API name="useDebouncePopoverOpen"> <APIReturns type="boolean"> 弹窗是否处于打开状态 </APIReturns> </API>