如何创建自定义 GrapesJS 插件（逐步，2026）

GrapesJS 插件到底是什么

GrapesJS 插件只是一个接收编辑器和选项的函数 对象： (editor, opts) => { /* register things */ }在里面你 添加模块、命令、组件、面板或存储。没有特殊类别 延伸。本指南构建了一个小巧但真实的插件，并为 npm 打包。

1. 插件函数

// src/index.js
export default (editor, opts = {}) => {
  const options = {
    label: 'My Block',
    category: 'My Plugin',
    ...opts,                       // caller overrides win
  };

  editor.BlockManager.add('my-block', {
    label: options.label,
    category: options.category,
    content: '<section class="my-block"><h2>Hello</h2></section>',
  });
};

2. 在编辑器中使用

import grapesjs from 'grapesjs';
import myPlugin from './src/index.js';

grapesjs.init({
  container: '#gjs',
  plugins: [myPlugin],
  pluginsOpts: {
    // keyed by plugin name when loaded by string; for a function, pass opts here
  },
});

当你通过插件的包名字符串加载插件时，GrapesJS 会读取它的选项 来自 pluginsOpts['package-name']。

3. 添加命令和按钮

editor.Commands.add('say-hi', {
  run: () => editor.Modal.open({ title: 'Hi', content: 'From my plugin' }),
});

editor.Panels.addButton('options', {
  id: 'say-hi',
  className: 'fa fa-smile-o',
  command: 'say-hi',
});

4. 打包成 npm

• 把插件函数导出为包默认值。
• 列表 grapesjs 为 peerDependency，而非依赖。
• 构建一个ESM + UMD捆绑包（Rollup，或官方的GrapesJS插件起始版）。
• 跑 npm publish。

关于强大插件的建议

有几个习惯能区分一次性脚本和可发布插件。你注册的每个 id（块、命令、组件）都用前缀命名空间，这样两个插件就不会冲突。始终将默认对象与输入 opts 对象合并，并从结果中读取，这样调用者可以覆盖行为而无需修改代码。声明 grapesjs 为 peerDependency，而不是依赖，这样主机应用可以控制版本。清理你在编辑器事件中附加 destroy 的内容（DOM监听器、计时器）。并记录你的选项——一个没人能配置的插件会被分叉，而不是重复使用。

前提条件

你需要一个可运行的 GrapesJS 设置和基础的 JavaScript。插件只是一个函数 (editor, opts) => {} ——没有可扩展的类，也没有构建步骤 开始。打包插件时，你只需要一个捆绑器（Vite、Webpack 或 Rollup） 用于分发。

更完整的插件：block + command + button

真正的插件通常会同时注册多个内容。这里，一个插件添加了一个模块、一个命令和一个工具栏按钮：

export default (editor, opts = {}) => {
  const options = { label: 'Hi', ...opts };

  editor.BlockManager.add('callout', {
    label: 'Callout',
    category: 'Custom',
    content: '<div class="callout">Note</div>',
  });

  editor.Commands.add('say-hi', {
    run: () => editor.Modal.open({ title: options.label, content: 'From my plugin' }),
  });

  editor.Panels.addButton('options', {
    id: 'say-hi', className: 'fa fa-smile-o', command: 'say-hi',
  });
};

清理摧毁

如果你的插件附加了DOM监听器、计时器或外部资源，请将其释放到 编辑器 destroy 事件，因此反复嵌入编辑器（常见于 SPA 路由）不会泄露：

const onScroll = () => {/* … */};
window.addEventListener('scroll', onScroll);
editor.on('destroy', () => window.removeEventListener('scroll', onScroll));

最佳实践

你注册的每个ID（块、命令、组件）都用一个前缀命名空间，比如两个 插件之间从不发生碰撞。总是将默认对象与新入的对象合并 opts。声明 grapesjs 为 peerDependency 某人 主机应用控制版本。每个插件和文档都只负责一个职责 它的选项——一个没人能配置的插件会被分叉，而不是重复使用。

打包成 npm

导出函数作为包默认，构建一个ESM + UMD捆绑包（Rollup或 官方 GrapesJS 插件启动器），列表 grapesjs 作为对等依赖， 并跑。 npm publish用户通过名称加载，通过以下方式传递 pluginsOpts。

下一步

想要抢先一步？生成一个带有 GJS。市场插件生成器，然后深入体验 添加自定义块 和 定制组件。浏览完整内容 GrapesJS 插件 目录或从 GJS。市场主页。

常见问题

什么是GrapesJS插件？

一个用于注册区块、命令的函数 (editor, opts) => {} ， 组件、面板或存储。你通过 grapesjs.init plugins 阵列。

我该如何为插件添加选项？

将默认对象与接收 opts 对象合并，然后从 结果。呼叫者通过 pluginsOpts。

我该如何向NPM发布？

导出函数作为默认值，声明 grapesjs 为对等节点 依赖，构建一个捆绑包，运行 npm publish。