自动格式化 - Plate

功能特性

块级元素的Markdown风格快捷方式（如#转换为H1，>转换为引用块）
行内标记格式化（如**粗体**，*斜体*，~~删除线~~）
智能标点转换（如--转为—，...转为…）
数学符号和分数
法律符号和箭头
支持通过删除操作撤销自动格式化

</PackageInfo>

套件使用

<Steps>

安装

最快捷的添加自动格式化方式是使用AutoformatKit，它包含了全面的块级、标记级和文本替换的格式化规则。

添加套件

tsx

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

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

</Steps>

手动配置

<Steps>

安装

bash

npm install @platejs/autoformat

添加插件

tsx

import { AutoformatPlugin } from '@platejs/autoformat';
import { createPlateEditor } from 'platejs/react';

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

配置插件

自定义自动格式化规则：

tsx

import { AutoformatPlugin } from '@platejs/autoformat';

AutoformatPlugin.configure({
  options: {
    rules: [
      // 块级规则
      {
        match: '# ',
        mode: 'block',
        type: 'h1',
      },
      {
        match: '> ',
        mode: 'block',
        type: 'blockquote',
      },
      // 标记规则
      {
        match: '**',
        mode: 'mark',
        type: 'bold',
      },
      {
        match: '*',
        mode: 'mark',
        type: 'italic',
      },
    ],
    enableUndoOnDelete: true,
  },
});

高级配置

导入预定义的规则集实现全面自动格式化：

tsx

import { AutoformatPlugin } from '@platejs/autoformat';
import {
  autoformatArrow,
  autoformatLegal,
  autoformatMath,
  autoformatPunctuation,
  autoformatSmartQuotes,
} from '@platejs/autoformat';

AutoformatPlugin.configure({
  options: {
    enableUndoOnDelete: true,
    rules: [
      // 自定义块级规则
      {
        match: '# ',
        mode: 'block',
        type: 'h1',
      },
      // 预定义规则集
      ...autoformatSmartQuotes,
      ...autoformatPunctuation,
      ...autoformatArrow,
      ...autoformatLegal,
      ...autoformatMath,
    ].map((rule) => ({
      ...rule,
      // 在代码块中禁用自动格式化
      query: (editor) =>
        !editor.api.some({
          match: { type: 'code_block' },
        }),
    })),
  },
});

rules: 定义触发条件和格式化操作的规则数组
enableUndoOnDelete: 允许通过退格键撤销自动格式化
query: 根据上下文条件启用/禁用规则的函数

使用正则表达式

对于更复杂的匹配模式，可以使用正则表达式：

tsx

import { AutoformatPlugin } from '@platejs/autoformat';
import { toggleList } from '@platejs/list';

AutoformatPlugin.configure({
  options: {
    rules: [
      {
        match: [String.raw`^\d+\.$ `, String.raw`^\d+\)$ `],
        matchByRegex: true,
        mode: 'block',
        type: 'list',
        format: (editor, { matchString }) => {
          const number = Number(matchString.match(/\d+/)?.[0]) || 1;
          toggleList(editor, {
            listRestartPolite: number,
            listStyleType: 'ol',
          });
        },
      },
    ],
  },
});

matchByRegex: 启用正则模式匹配（替代字符串完全匹配）
注意：正则模式仅适用于mode: 'block'且只在块起始位置生效(triggerAtBlockStart: true)

</Steps>

插件

`AutoformatPlugin`

基于输入模式实现文本自动格式化的插件。

<API name="AutoformatPlugin"> <APIOptions> <APIItem name="rules" type="AutoformatRule[]" optional> 触发规则列表。可以是以下类型之一：`AutoformatBlockRule`、`AutoformatMarkRule`、`AutoformatTextRule`。均继承自`AutoformatCommonRule`。 - **默认值:** `[]` </APIItem> <APIItem name="enableUndoOnDelete" type="boolean" optional> 启用删除时撤销自动格式化功能。 - **默认值:** `false` </APIItem> </APIOptions> </API>

预定义规则集

可导入以下预定义规则集：

名称	描述
`autoformatSmartQuotes`	转换`"文本"`为`"文本"`
	转换`'文本'`为`'文本'`
`autoformatPunctuation`	转换`--`为`—`
	转换`...`为`…`
	转换`>>`为`»`
	转换`<<`为`«`
`autoformatArrow`	转换`->`为`→`
	转换`<-`为`←`
	转换`=>`为`⇒`
	转换`<=`和`≤=`为`⇐`
`autoformatLegal`	转换`(tm)`和`(TM)`为`™`
	转换`(r)`和`(R)`为`®`
	转换`(c)`和`(C)`为`©`
`autoformatLegalHtml`	转换`™`为`™`
	转换`®`为`®`
	转换`©`为`©`
	转换`§`为`§`
`autoformatComparison`	转换`!>`为`≯`
	转换`!<`为`≮`
	转换`>=`为`≥`
	转换`<=`为`≤`
	转换`!>=`为`≱`
	转换`!<=`为`≰`
`autoformatEquality`	转换`!=`为`≠`
	转换`==`为`≡`
	转换`!==`和`≠=`为`≢`
	转换`~=`为`≈`
	转换`!~=`为`≉`
`autoformatFraction`	转换`1/2`为`½`
	转换`1/3`为`⅓`
	...
	转换`7/8`为`⅞`
`autoformatDivision`	转换`//`为`÷`
`autoformatOperation`	转换`+-`为`±`
	转换`%%`为`‰`
	转换`%%%`和`‰%`为`‱`
	包含`autoformatDivision`规则
`autoformatSubscriptNumbers`	转换`~0`为`₀`
	转换`~1`为`₁`
	...
	转换`~9`为`₉`
`autoformatSubscriptSymbols`	转换`~+`为`₊`
	转换`~-`为`₋`
`autoformatSuperscriptNumbers`	转换`^0`为`⁰`
	转换`^1`为`¹`
	...
	转换`^9`为`⁹`
`autoformatSuperscriptSymbols`	转换`^+`为`⁺`
	转换`^-`为`⁻`
`autoformatMath`	包含`autoformatComparison`规则
	`autoformatEquality`规则
	`autoformatOperation`规则
	`autoformatFraction`规则
	`autoformatSubscriptNumbers`规则
	`autoformatSubscriptSymbols`规则
	`autoformatSuperscriptNumbers`规则
	`autoformatSuperscriptSymbols`规则

类型定义

`AutoformatCommonRule`

自动格式化规则的通用接口结构，与模式无关。

<API name="AutoformatCommonRule"> <APIAttributes> <APIItem name="match" type="string | string[] | MatchRange | MatchRange[]" > 当触发字符和光标前的文本匹配时应用规则。

对于mode: 'block': 在光标前查找结束匹配项
对于mode: 'text': 在光标前查找结束匹配项。如果format是数组，还需查找起始匹配项
对于mode: 'mark': 查找起始和结束匹配项
注意：'_*'、['_*']和{ start: '_*', end: '*_' }等效
MatchRange:

<APISubList> <APISubListItem parent="match" name="start" type="string"> 范围的起始点 </APISubListItem> <APISubListItem parent="match" name="end" type="string"> 范围的结束点 </APISubListItem> </APISubList> </APIItem> <APIItem name="trigger" type="string | string[]" optional> 触发自动格式化的字符 </APIItem> <APIItem name="insertTrigger" type="boolean" optional> 为true时，在自动格式化后插入触发字符 - **默认值:** `false` </APIItem> <APIItem name="query" type="(editor: PlateEditor, options: AutoformatQueryOptions) => boolean" optional > 允许自动格式化的查询函数 <APIOptions type="AutoformatQueryOptions"> <APIItem name="text" type="string"> `insertText`文本内容 </APIItem> </APIOptions> </APIItem> </APIAttributes> </API>

`AutoformatBlockRule`

块级模式自动格式化规则接口。

<API name="AutoformatBlockRule"> <APIAttributes> <APIItem name="mode" type="'block'"> 块级模式：设置块类型或自定义格式 </APIItem> <APIItem name="match" type="string | string[]"> 自动格式化规则的匹配模式 </APIItem> <APIItem name="type" type="string" optional> 对于`mode: 'block'`：设置块类型。如果定义了`format`，则忽略此字段 </APIItem> <APIItem name="triggerAtBlockStart" type="boolean" optional> 是否仅在块起始位置触发 - **默认值:** `true` </APIItem> <APIItem name="allowSameTypeAbove" type="boolean" optional> 是否允许上方存在相同块类型时触发 - **默认值:** `false` </APIItem> <APIItem name="preFormat" type="(editor: PlateEditor) => void" optional> 在`format`前调用的函数。用于重置选中块 </APIItem> <APIItem name="format" type="(editor: PlateEditor) => void" optional> 自定义格式化函数 </APIItem> </APIAttributes> </API>

`AutoformatMarkRule`

标记模式自动格式化规则接口。

<API name="AutoformatMarkRule"> <APIAttributes> <APIItem name="mode" type="'mark'"> 标记模式：在匹配项之间插入标记 </APIItem> <APIItem name="type" type="string | string[]"> 要添加的标记（可多个） </APIItem> <APIItem name="ignoreTrim" type="boolean" optional> 字符串可修剪时是否仍进行格式化 </APIItem> </APIAttributes> </API>

`AutoformatTextRule`

文本模式自动格式化规则接口。

<API name="AutoformatTextRule"> <APIParameters> <APIItem name="mode" type="'text'"> 文本模式：插入文本 </APIItem> <APIItem name="match" type="string | string[]"> 自动格式化规则的匹配模式 </APIItem> <APIItem name="format" type="string | string[] | ((editor: PlateEditor, options: GetMatchPointsReturnType) => void)"> 文本替换内容或格式化函数 </APIItem> </APIParameters> </API>