自动格式化

PreviousNext

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

基础块元素基础标记代码块列表
Loading...

功能特性

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

套件使用

安装

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

添加套件

import { createPlateEditor } from 'platejs/react';
import { AutoformatKit } from '@/components/editor/plugins/autoformat-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    ...AutoformatKit,
  ],
});

手动配置

安装

pnpm add @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)

插件

AutoformatPlugin

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

Options

  • rules optional AutoformatRule[]

    触发规则列表。可以是以下类型之一：AutoformatBlockRule、AutoformatMarkRule、AutoformatTextRule。均继承自AutoformatCommonRule。

    • 默认值: []

  • enableUndoOnDelete optional boolean

    启用删除时撤销自动格式化功能。

    • 默认值: false

预定义规则集

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

名称描述
autoformatSmartQuotes转换"文本"为"文本"
转换'文本'为'文本'
autoformatPunctuation转换--为—
转换...为…
转换>>为»
转换<<为«
autoformatArrow转换->为→
转换<-为←
转换=>为⇒
转换<=和≤=为⇐
autoformatLegal转换(tm)和(TM)为™
转换(r)和(R)为®
转换(c)和(C)为©
autoformatLegalHtml转换&trade;为™
转换&reg;为®
转换&copy;为©
转换&sect;为§
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

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

Attributes

Collapse all

  • match string | string[] | MatchRange | MatchRange[]

    当触发字符和光标前的文本匹配时应用规则。

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

  • trigger optional string | string[]

    触发自动格式化的字符

  • insertTrigger optional boolean

    为true时，在自动格式化后插入触发字符

    • 默认值: false

  • query optional (editor: PlateEditor, options: AutoformatQueryOptions) => boolean

    允许自动格式化的查询函数

    OptionsAutoformatQueryOptions

    Collapse all

    • text string

      insertText文本内容

AutoformatBlockRule

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

Attributes

Collapse all

  • mode 'block'

    块级模式：设置块类型或自定义格式

  • match string | string[]

    自动格式化规则的匹配模式

  • type optional string

    对于mode: 'block'：设置块类型。如果定义了format，则忽略此字段

  • triggerAtBlockStart optional boolean

    是否仅在块起始位置触发

    • 默认值: true

  • allowSameTypeAbove optional boolean

    是否允许上方存在相同块类型时触发

    • 默认值: false

  • preFormat optional (editor: PlateEditor) => void

    在format前调用的函数。用于重置选中块

  • format optional (editor: PlateEditor) => void

    自定义格式化函数

AutoformatMarkRule

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

Attributes

Collapse all

  • mode 'mark'

    标记模式：在匹配项之间插入标记

  • type string | string[]

    要添加的标记（可多个）

  • ignoreTrim optional boolean

    字符串可修剪时是否仍进行格式化

AutoformatTextRule

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

Parameters

Collapse all

  • mode 'text'

    文本模式：插入文本

  • match string | string[]

    自动格式化规则的匹配模式

  • format string | string[] | ((editor: PlateEditor, options: GetMatchPointsReturnType) => void)

    文本替换内容或格式化函数

ToggleAutoformat