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

---

title: 代码块 docs:

• route: /docs/components/code-block-node title: 代码块元素

---

<ComponentPreview name="code-block-demo" /> <PackageInfo>

功能特性

• 代码块的语法高亮显示
• 支持多种编程语言
• 可自定义语言选择
• 正确处理缩进

</PackageInfo>

套件使用

<Steps>

安装

最快捷添加代码块功能的方式是使用 CodeBlockKit，它包含预配置的 CodeBlockPlugin、CodeLinePlugin 和 CodeSyntaxPlugin，提供语法高亮和 Plate UI 组件。

<ComponentSource name="code-block-kit" />

• CodeBlockElement: 渲染代码块容器
• CodeLineElement: 渲染单行代码
• CodeSyntaxLeaf: 渲染语法高亮文本

添加套件

将套件添加到你的插件中：

import { createPlateEditor } from 'platejs/react';
import { CodeBlockKit } from '@/components/editor/plugins/code-block-kit';

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

</Steps>

手动使用

<Steps>

安装

npm install @platejs/code-block lowlight

添加插件

在创建编辑器时，将代码块插件包含到 Plate 插件数组中。

import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { createPlateEditor } from 'platejs/react';

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

配置插件

配置带有语法高亮和自定义组件的插件。

包含所有语言的基础设置：

import { CodeBlockPlugin, CodeLinePlugin, CodeSyntaxPlugin } from '@platejs/code-block/react';
import { all, createLowlight } from 'lowlight';
import { createPlateEditor } from 'platejs/react';
import { CodeBlockElement, CodeLineElement, CodeSyntaxLeaf } from '@/components/ui/code-block-node';

// 创建包含所有语言的 lowlight 实例
const lowlight = createLowlight(all);

const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    CodeBlockPlugin.configure({
      node: { component: CodeBlockElement },
      options: { lowlight },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});

自定义语言设置（优化包体积）：

为了优化包体积，你可以只注册特定语言：

import { createLowlight } from 'lowlight';
import css from 'highlight.js/lib/languages/css';
import js from 'highlight.js/lib/languages/javascript';
import ts from 'highlight.js/lib/languages/typescript';
import html from 'highlight.js/lib/languages/xml';

// 创建 lowlight 实例
const lowlight = createLowlight();

// 只注册需要的语言
lowlight.register('html', html);
lowlight.register('css', css);
lowlight.register('js', js);
lowlight.register('ts', ts);

const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    CodeBlockPlugin.configure({
      node: { component: CodeBlockElement },
      options: {
        lowlight,
        defaultLanguage: 'js', // 设置默认语言（可选）
      },
      shortcuts: { toggle: { keys: 'mod+alt+8' } },
    }),
    CodeLinePlugin.withComponent(CodeLineElement),
    CodeSyntaxPlugin.withComponent(CodeSyntaxLeaf),
  ],
});

• node.component: 指定 CodeBlockElement 来渲染代码块容器
• options.lowlight: 用于语法高亮的 lowlight 实例
• options.defaultLanguage: 未指定语言时使用的默认语言
• shortcuts.toggle: 定义切换代码块的键盘快捷键
• withComponent: 为代码行和语法高亮指定组件

转换为工具栏按钮

你可以将此项目添加到转换为工具栏按钮中，将块转换为代码块：

{
  icon: <FileCodeIcon />,
  label: '代码',
  value: KEYS.codeBlock,
}

插入工具栏按钮

你可以将此项目添加到插入工具栏按钮中，插入代码块元素：

{
  icon: <FileCodeIcon />,
  label: '代码',
  value: KEYS.codeBlock,
}

</Steps>

插件

CodeBlockPlugin

<API name="CodeBlockPlugin"> <APIOptions> <APIItem name="defaultLanguage" type="string | null" optional> 未指定语言时使用的默认语言。设为 null 可默认禁用语法高亮。 </APIItem> <APIItem name="lowlight" type="ReturnType<typeof createLowlight> | null" optional> 用于高亮的 lowlight 实例。如果未提供，将禁用语法高亮。 </APIItem> </APIOptions> </API>

API

isCodeBlockEmpty

<API name="isCodeBlockEmpty"> <APIReturns type="boolean"> 判断选区是否在空代码块中。 </APIReturns> </API>

isSelectionAtCodeBlockStart

<API name="isSelectionAtCodeBlockStart"> <APIReturns type="boolean"> 判断选区是否位于代码块第一行开头。 </APIReturns> </API>

indentCodeLine

如果选区已展开或光标左侧无非空白字符，则缩进代码行。默认缩进为 2 个空格。

<API name="indentCodeLine"> <APIOptions type="IndentCodeLineOptions"> <APIItem name="codeLine" type="ElementEntry"> 要缩进的代码行。 </APIItem> <APIItem name="indentDepth" type="number"> 代码行的缩进大小。 - **默认值:** `2` </APIItem> </APIOptions> </API>

insertCodeBlock

通过将节点设为代码行并用代码块包裹来插入代码块。如果光标不在块开头，则在代码块前插入换行。

<API name="insertCodeBlock"> <APIParameters> <APIItem name="insertNodesOptions" type="Omit<InsertNodesOptions, 'match'>" optional> 插入节点的选项。 </APIItem> </APIParameters> </API>

insertCodeLine

插入以指定缩进深度开头的代码行。

<API name="insertCodeLine"> <APIParameters> <APIItem name="indentDepth" type="number" optional> 代码行的缩进深度。 - **默认值:** `0` </APIItem> </APIParameters> </API>

outdentCodeLine

减少代码行的缩进，如果存在则移除两个空白字符。

<API name="outdentCodeLine"> <APIOptions type="OutdentCodeLineOptions"> <APIItem name="codeLine" type="ElementEntry"> 要减少缩进的代码行。 </APIItem> <APIItem name="codeBlock" type="ElementEntry"> 包含要减少缩进代码行的代码块。 </APIItem> </APIOptions> </API>

toggleCodeBlock

切换编辑器中的代码块。

unwrapCodeBlock

解除编辑器中的代码块包裹。

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