GrapesJS 自定义组件指南（2026）

组件定义行为，而不仅仅是标记

GrapesJS 组件是一个带有默认值、特征（可编辑设置）的类型模型， 以及可选视图。你注册一个 DomComponents.addType。本指南构建一个自定义组件，包含 并展示了导入的HTML如何映射到它上。

1. 寄存组件类型

editor.DomComponents.addType('rating', {
  // Map matching HTML onto this type when content is loaded.
  isComponent: (el) => el.classList?.contains('rating') && { type: 'rating' },

  model: {
    defaults: {
      tagName: 'div',
      classes: ['rating'],
      // Editable settings shown in the trait panel:
      traits: [
        { type: 'number', name: 'stars', label: 'Stars', min: 1, max: 5 },
      ],
      stars: 5,
    },
  },
});

2. 对视图中的性状变化做出反应

editor.DomComponents.addType('rating', {
  model: {
    defaults: { tagName: 'div', classes: ['rating'], stars: 5,
      traits: [{ type: 'number', name: 'stars', min: 1, max: 5 }] },
  },
  view: {
    init() {
      this.listenTo(this.model, 'change:stars', this.render);
    },
    onRender() {
      const n = this.model.get('stars');
      this.el.textContent = '★'.repeat(n) + '☆'.repeat(5 - n);
    },
  },
});

3. 将其暴露为一个区块

editor.BlockManager.add('rating', {
  label: 'Rating',
  category: 'Widgets',
  content: { type: 'rating', stars: 4 },
});

因为 isComponent 识别 .rating 元素，加载 保存的HTML会重建组件——特征和行为保持完整。

常见错误

自定义组件的故障方式是可预测的。如果匹配isComponentDOM时没有返回真实值（通常是{ type }），加载后的HTML不会映射到你的类型，重载时特征也会消失。如果视图没有listenTo处理模型的change:<trait>事件，特征面板中的编辑就不会重新渲染。在处理程序中重新渲染，而处理程序本身会触发变更，可能导致无限循环——直接更新DOM，而不是尽可能调用完整渲染。并且draggabledroppable故意设置/让你的组件只能放在合理位置。

前提条件

你需要一个运行中的GrapesJS编辑器和基础JavaScript。组件已注册 其中 DomComponents.addType;这三部分是检测 （isComponent），模型（默认值+特征），以及可选视图 （画布行为）。

模型：默认值、特征与约束

模型定义了组件的定义。除了性状，你可以限制它能限制的地方 Go 及其接受条件，droppable且 draggable， ， editable：

editor.DomComponents.addType('rating', {
  isComponent: (el) => el.classList?.contains('rating') && { type: 'rating' },
  model: {
    defaults: {
      tagName: 'div',
      classes: ['rating'],
      droppable: false,
      traits: [{ type: 'number', name: 'stars', min: 1, max: 5 }],
      stars: 5,
    },
  },
});

观点：对性状变化的反应

view: {
  init() { this.listenTo(this.model, 'change:stars', this.render); },
  onRender() {
    const n = this.model.get('stars');
    this.el.textContent = '★'.repeat(n) + '☆'.repeat(5 - n);
  },
}

isComponent 为什么重要

isComponent 当 HTML 加载到编辑器时运行。归还该类型 用于匹配元素的对象是让保存的标记重新注入组件的关键 只要它的特性和行为保持完整——没有它，换弹时你的组件会变回原形 转成纯HTML格式。

最佳实践

保持模型声明式，并将行为置于视图中。避免触发全套 在一个本身导致变更的变更处理程序中渲染——直接将DOM更新为 防止循环。设定 draggable/droppable 故意如此 组件只能放置在合理位置。揭示有意义的特质，以便编辑 可以无需代码即可配置组件。

下一步

作为可拖拽单元的表面组件 自定义方块指南，捆绑包 它们在 自定义插件中，或者 浏览 GrapesJS插件 GJS。市场。

常见问题

我如何在 GrapesJS 中创建自定义组件？

叫声 editor.DomComponents.addType(type, { isComponent, model, view }) ——定义检测、默认值/特征和画布行为。

什么是特质？

特质是特质面板中显示的可编辑设置，针对某个特质 组成部分;在 中声明它们。model.defaults.traits

isComponent是如何工作的？

它接收一个DOM元素并返回一个真实值（通常） { type }而该元素本应成为你的组件，因此导入 HTML映射到你的类型上。