║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

---

title: 自动格式化 description: 通过短代码和类Markdown快捷方式实现文本自动格式化。 docs:

• route: /docs/basic-blocks title: 基础块元素
• route: /docs/basic-marks title: 基础标记
• route: /docs/code-block title: 代码块
• route: /docs/list title: 列表

---

<ComponentPreview name="autoformat-demo" /> <PackageInfo>

功能特性

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

</PackageInfo>

套件使用

<Steps>

安装

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

<ComponentSource name="autoformat-kit" />

添加套件

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

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

</Steps>

手动配置

<Steps>

安装

npm install @platejs/autoformat

添加插件

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

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

配置插件

自定义自动格式化规则：

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,
  },
});

高级配置

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

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: 根据上下文条件启用/禁用规则的函数

使用正则表达式

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

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>

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║