React

PreviousNext

为 React 安装和配置 Plate UI

先决条件

开始前，请确保已安装并配置 shadcn/ui（适配您的框架，如 Vite）和 Plate UI。

本指南将逐步引导您在项目中构建 Plate 编辑器。

创建第一个编辑器

首先在项目中添加核心 Editor 组件：

pnpm dlx shadcn@latest add https://platejs.org/r/editor

接下来，在主应用文件（如 src/App.tsx）中创建基础编辑器。此示例在 EditorContainer 内设置了一个简单编辑器。

src/App.tsx
import { Plate, usePlateEditor } from 'platejs/react';
 
import { Editor, EditorContainer } from '@/components/ui/editor';
 
export default function App() {
  const editor = usePlateEditor(); // 初始化编辑器实例
 
  return (
    <Plate editor={editor}>      {/* 提供编辑器上下文 */}
      <EditorContainer>         {/* 设置编辑器区域样式 */}
        <Editor placeholder="输入您精彩的内容..." />
      </EditorContainer>
    </Plate>
  );
}

usePlateEditor 创建了一个记忆化的编辑器实例，确保在重新渲染时保持稳定。如需非记忆化版本，请使用 createPlateEditor。

Loading...

添加基础标记

通过文本格式化功能增强编辑器。添加 Basic Nodes Kit、FixedToolbar 和 MarkToolbarButton 组件：

pnpm dlx shadcn@latest add https://platejs.org/r/basic-nodes-kit https://platejs.org/r/fixed-toolbar https://platejs.org/r/mark-toolbar-button

basic-nodes-kit 包含所有基础插件（粗体、斜体、下划线、标题、引用块等）及后续步骤中将用到的组件。

更新 src/App.tsx 以包含这些组件和基础标记插件。 此示例添加了粗体、斜体和下划线功能。

src/App.tsx
import * as React from 'react';
import type { Value } from 'platejs';
 
import {
  BoldPlugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';
 
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
 
const initialValue: Value = [
  {
    type: 'p',
    children: [
      { text: '您好！试试 ' },
      { text: '粗体', bold: true },
      { text: '、' },
      { text: '斜体', italic: true },
      { text: ' 和 ' },
      { text: '下划线', underline: true },
      { text: ' 格式。' },
    ],
  },
];
 
export default function App() {
  const editor = usePlateEditor({
    plugins: [BoldPlugin, ItalicPlugin, UnderlinePlugin], // 添加标记插件
    value: initialValue,         // 设置初始内容
  });
 
  return (
    <Plate editor={editor}>
      <FixedToolbar className="justify-start rounded-t-lg">
        <MarkToolbarButton nodeType="bold" tooltip="粗体 (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="斜体 (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="下划线 (⌘+U)">U</MarkToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="输入您精彩的内容..." />
      </EditorContainer>
    </Plate>
  );
}
Loading...

添加基础元素

通过自定义组件引入标题和引用块等块级元素。

src/App.tsx
import * as React from 'react';
import type { Value } from 'platejs';
 
import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';
 
import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
import { ToolbarButton } from '@/components/ui/toolbar'; // 通用工具栏按钮
 
const initialValue: Value = [
  {
    children: [{ text: '标题' }],
    type: 'h3',
  },
  {
    children: [{ text: '这是一段引用。' }],
    type: 'blockquote',
  },
  {
    children: [
      { text: '使用一些 ' },
      { bold: true, text: '粗体' },
      { text: ' 文字强调！' },
    ],
    type: 'p',
  },
];
 
export default function App() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: initialValue,
  });
 
  return (
    <Plate editor={editor}>
      <FixedToolbar className="flex justify-start gap-1 rounded-t-lg">
        {/* 元素工具栏按钮 */}
        <ToolbarButton onClick={() => editor.tf.h1.toggle()}>H1</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h2.toggle()}>H2</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h3.toggle()}>H3</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.blockquote.toggle()}>引用</ToolbarButton>
        {/* 标记工具栏按钮 */}
        <MarkToolbarButton nodeType="bold" tooltip="粗体 (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="斜体 (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="下划线 (⌘+U)">U</MarkToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="输入您精彩的内容..." />
      </EditorContainer>
    </Plate>
  );
}
Loading...

组件注册

注意我们如何使用 Plugin.withComponent(Component) 将组件与其对应的插件注册。这是将 React 组件与 Plate 插件关联的推荐方式。

如需快速开始使用预配置的常见插件和组件，可使用 editor-basic 区块：

pnpm dlx shadcn@latest add https://platejs.org/r/editor-basic

这将为您处理大部分样板代码。

处理编辑器值

为了使编辑器内容持久化，我们集成 localStorage 来保存和加载编辑器的值。

src/App.tsx
import * as React from 'react';
import type { Value } from 'platejs';
 
import {
  BlockquotePlugin,
  BoldPlugin,
  H1Plugin,
  H2Plugin,
  H3Plugin,
  ItalicPlugin,
  UnderlinePlugin,
} from '@platejs/basic-nodes/react';
import {
  Plate,
  usePlateEditor,
} from 'platejs/react';
 
import { BlockquoteElement } from '@/components/ui/blockquote-node';
import { Editor, EditorContainer } from '@/components/ui/editor';
import { FixedToolbar } from '@/components/ui/fixed-toolbar';
import { H1Element, H2Element, H3Element } from '@/components/ui/heading-node';
import { MarkToolbarButton } from '@/components/ui/mark-toolbar-button';
import { ToolbarButton } from '@/components/ui/toolbar';
 
const initialValue: Value = [
  {
    children: [{ text: '标题' }],
    type: 'h3',
  },
  {
    children: [{ text: '这是一段引用。' }],
    type: 'blockquote',
  },
  {
    children: [
      { text: '使用一些 ' },
      { bold: true, text: '粗体' },
      { text: ' 文字强调！' },
    ],
    type: 'p',
  },
];
 
export default function App() {
  const editor = usePlateEditor({
    plugins: [
      BoldPlugin,
      ItalicPlugin,
      UnderlinePlugin,
      H1Plugin.withComponent(H1Element),
      H2Plugin.withComponent(H2Element),
      H3Plugin.withComponent(H3Element),
      BlockquotePlugin.withComponent(BlockquoteElement),
    ],
    value: () => {
      const savedValue = localStorage.getItem('installation-react-demo');
      if (savedValue) {
        return JSON.parse(savedValue);
      }
      return initialValue;
    },
  });
 
  return (
    <Plate
      editor={editor}
      onChange={({ value }) => {
        localStorage.setItem('installation-react-demo', JSON.stringify(value));
      }}
    >
      <FixedToolbar className="flex justify-start gap-1 rounded-t-lg">
        <ToolbarButton onClick={() => editor.tf.h1.toggle()}>H1</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h2.toggle()}>H2</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.h3.toggle()}>H3</ToolbarButton>
        <ToolbarButton onClick={() => editor.tf.blockquote.toggle()}>引用</ToolbarButton>
        <MarkToolbarButton nodeType="bold" tooltip="粗体 (⌘+B)">B</MarkToolbarButton>
        <MarkToolbarButton nodeType="italic" tooltip="斜体 (⌘+I)">I</MarkToolbarButton>
        <MarkToolbarButton nodeType="underline" tooltip="下划线 (⌘+U)">U</MarkToolbarButton>
        <div className="flex-1" />
        <ToolbarButton
          className="px-2"
          onClick={() => editor.tf.setValue(initialValue)}
        >
          重置
        </ToolbarButton>
      </FixedToolbar>
      <EditorContainer>
        <Editor placeholder="输入您精彩的内容..." />
      </EditorContainer>
    </Plate>
  );
}
Loading...

后续步骤

恭喜！您已在项目中构建了基础的 Plate 编辑器。

如需进一步扩展编辑器功能：

Plate UI InstallationReact