Plate UI 安装指南

PreviousNext

如何在项目中设置 Plate UI。

本指南详细介绍了如何安装 Plate UI（Plate 的组件层）。根据项目需求选择适合的安装方式：

  • CLI 安装（推荐）： 使用 shadcn CLI 快速设置
  • 手动安装： 提供更精细的安装控制

CLI 安装（推荐）

这是集成 Plate UI 核心依赖和基础样式的最快方式。

安装 Plate UI

如果未使用 Next.js，请先参考 shadcn/ui 官方安装指南 配置您的框架环境。

pnpm dlx shadcn@latest add https://platejs.org/r/plate-ui

基础使用

安装 Plate UI 核心后，根据框架选择对应指南：

手动安装

如需逐步安装或未使用 shadcn CLI，请按以下步骤操作：

安装 Plate

pnpm add platejs

插件依赖

手动安装 Plate 时，需要为每个插件单独安装对应包。例如使用 AIMenu 组件需安装 @platejs/ai 及其依赖。可查阅各组件文档获取所需包，或直接使用 CLI 自动安装。

配置 CSS 变量

在全局样式表中添加以下 CSS 变量：

app/globals.css
:root {
  /* Plate UI 组件基础品牌色 */
  --brand: oklch(0.623 0.214 259.815);
}
 
.dark {
  --brand: oklch(0.707 0.165 254.624);
}

添加组件

安装核心后，可添加独立组件构建编辑器界面。例如安装 FixedToolbar 和 MarkToolbarButton：

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

在编辑器中导入使用：

components/editor.tsx
import { Plate } from "platejs/react";
import { FixedToolbar } from "@/components/ui/fixed-toolbar";
import { MarkToolbarButton } from "@/components/ui/mark-toolbar-button";
// ... 其他导入
 
export function MyEditor() {
  // ... 编辑器配置
  return (
    <Plate editor={editor}>
      <FixedToolbar>
        <MarkToolbarButton nodeType="bold" tooltip="加粗">B</MarkToolbarButton>
        {/* ... 其他工具栏按钮 ... */}
      </FixedToolbar>
      {/* ... 编辑器组件 ... */}
    </Plate>
  );
}

浏览可用 UI 组件 和 插件组件 自定义编辑器节点（如段落、标题等），构建功能丰富的编辑体验。

基础使用

安装核心后，根据框架选择对应指南：

组件类型

Plate UI 组件安装时包含多种类型，命名模式统一。以下是各类组件说明：

功能套件

功能套件是添加完整功能的最便捷方式。包含插件配置、UI 组件（节点渲染器和工具栏项）及其 npm 依赖。

# 安装 AI 功能套件（含配置和 UI）
npx shadcn@latest add https://platejs.org/r/ai-kit
 
# 安装拖拽功能套件
npx shadcn@latest add https://platejs.org/r/dnd-kit

不确定需要哪些组件时，建议从功能套件开始。套件提供开箱即用的完整功能，后续可自定义调整。

组件

节点组件

负责渲染编辑器中特定类型内容（element 或 leaf）。如需自定义，请参考 插件组件指南。

# 安装引用块渲染组件
npx shadcn@latest add https://platejs.org/r/blockquote-node
 
# 安装代码文本渲染组件
npx shadcn@latest add https://platejs.org/r/code-node

工具栏组件

为编辑器工具栏添加交互控件（按钮、下拉菜单等）。

# 添加对齐方式下拉菜单
npx shadcn@latest add https://platejs.org/r/align-toolbar-button
 
# 添加 AI 功能工具栏按钮
npx shadcn@latest add https://platejs.org/r/ai-toolbar-button
 
# 添加颜色选择器下拉菜单
npx shadcn@latest add https://platejs.org/r/font-color-toolbar-button

其他组件

Plate UI 还包含高级编辑器组件（悬浮层、菜单、区块包装器等）。

# 安装 AI 功能菜单
npx shadcn@latest add https://platejs.org/r/ai-menu
 
# 安装可拖拽区块组件
npx shadcn@latest add https://platejs.org/r/block-draggable

这些组件通常已包含在对应功能套件中，也可单独安装用于自定义配置。

编辑器模板

预配置的编辑器方案，针对特定用例或作为完整起点。可浏览所有 编辑器模板。

# 安装 AI 功能编辑器模板
npx shadcn@latest add https://platejs.org/r/editor-ai
 
# 安装基础编辑器模板
npx shadcn@latest add https://platejs.org/r/editor-basic

API 路由

提供特定功能所需的服务器端组件或 API 路由处理器。

# 安装 AI 相关 API 路由
npx shadcn@latest add https://platejs.org/r/ai-api
 
# 安装文件上传 API 路由（如 UploadThing 集成）
npx shadcn@latest add https://platejs.org/r/media-uploadthing-api

文档

Plate 各项功能的文档、指南和 API 参考也可添加到本地项目。这对于保持版本化文档与代码同步，以及通过 MCP 为 AI 工具提供上下文特别有用。了解更多 本地文档设置。

# 添加 AI 文档
npx shadcn@latest add https://platejs.org/r/ai-docs
 
# 添加 Plate 插件文档
npx shadcn@latest add https://platejs.org/r/plugin-docs

这些内容由 Markdown 文件组成，可集成到自有文档系统或用于本地搜索和 AI 调用。

Node.jsPlate UI Installation