如何在 GrapesJS （2026） 中添加自定义块

方块是用户拖到画布上的

块是出现在 GrapesJS 块面板中的可重用块。你补充道 通过区块经理。本指南添加了普通的HTML模块，并将它们分组 分成类别，给它们图标，并用可重复使用的组件支持一个。

1. 添加一个基本块

editor.BlockManager.add('cta-banner', {
  label: 'CTA Banner',
  category: 'Sections',
  content: `
    <section class="cta py-16 text-center">
      <h2>Ready to start?</h2>
      <a href="#">Get started</a>
    </section>`,
});

它可以 content 是HTML字符串（如上所述）或组件定义 目标是获得更多控制。

2. 添加图标（媒体）

editor.BlockManager.add('image-block', {
  label: 'Image',
  category: 'Basic',
  media: '<svg viewBox="0 0 24 24"><path d="M4 5h16v14H4z"/></svg>',
  content: { type: 'image' },
});

media 接受内联SVG或标签 <img> ，且为 以块缩略图显示。

3. 用可重复使用的组件背对一个块

// content references a custom component type you registered:
editor.BlockManager.add('pricing-card', {
  label: 'Pricing card',
  category: 'Sections',
  content: { type: 'pricing-card' },   // see the custom-components guide
});

丢弃这个方块会生成一个你的 pricing-card实例 组成部分，因此它的行为和特征会自动出现。

小贴士

让方块使用起来更舒适。将相关方块与 category 属性分组，保持面板整齐，并为每个 media 方块提供SVG，方便用户一眼识别。对于超过单个元素的部分，将模块 content 设置为组件定义（{ type: '…' }），并由注册组件支持，这样模块能够承载自身的特性和行为，而不是倾倒惰性的HTML。你可以通过添加选项控制排序和目标面板，也可以在插件内部添加块，这样整个库就能在一行内安装。

前提条件

你需要一个正在运行的GrapesJS编辑器。块通过块管理器添加，该管理器 你可以随时 grapesjs.init 打电话——用你的应用代码或 在插件里，这样整个库就能在一行里安装。

值得了解的封锁选项

在 label、 category和 content之外，一个块可以 设置 media 缩略图，控制丢弃它是否会选择新的 组件（），select: true以及面板的集合 attributes 项目：

editor.BlockManager.add('image-card', {
  label: 'Image card',
  category: 'Cards',
  media: '<svg viewBox="0 0 24 24"><path d="M4 5h16v14H4z"/></svg>',
  select: true,
  content: { type: 'image' },
});

分量支持块

对于非惰性HTML的部分，将块 content 设置为组件 type 定义与你注册的组件匹配 DomComponents.addType。丢弃方块后，生成了该分量，所以 它的特质和行为是自然而然的。

一次性添加一个完整的库

const blocks = [
  { id: 'h1', label: 'Heading', content: '<h1>Title</h1>' },
  { id: 'p', label: 'Paragraph', content: '<p>Text</p>' },
];
blocks.forEach((b) => editor.BlockManager.add(b.id, { ...b, category: 'Basic' }));

最佳实践

将相关区块 category 分组，使面板保持有序，并给予 每个方块都是可 media 识别的图标。保持块 HTML 小巧 语义;将复杂的行为推入一个支持组件，而不是庞大的内容 线。用前缀块ID避免与插件碰撞。

故障排除

一个区块不出现通常 意味着它在区块之前添加 经理已经准备好了，或者处于一个已经关闭的类别下。 放下它确实会 “没有用处 ”通常意味着引用的组件 type 不存在 注册。

下一步

学习如何定义模块可以引用的组件类型 自定义组件指南，或称包装 你的积木变成可重复使用的 GrapesJS 插件。浏览一下 完整的 GrapesJS 插件 目录或 块库插件 GJS。市场。

常见问题

我该如何在GrapesJS中添加一个方块？

呼叫 editor.BlockManager.add(id, { label, category, content }); 方块会在面板中出现，准备拖拽。

我该如何将方块分组？

设置 属性 category ——同一类别的块被分组 在面板里。

模块可以插入可重复使用的组件吗？

是的——设置为 content 一个组件定义，其 type 匹配你注册的 DomComponents.addType组件。