How to Add a New Component Type to the Editor Sidebar in Luban H5

To add a new component type to the editor sidebar in Luban H5, create a Vue component and a plugin definition object containing metadata (name, label, component, defaultProps, and optional componentsForPropsEditor), register it in src/components/core/plugins/index.js, and add corresponding i18n keys to the locale files.

Luban H5 is an open-source visual page builder that enables developers to extend its component library through a plugin-based architecture. When you add a new component type to the editor sidebar, you are essentially registering a plugin entry that the left-panel component (src/components/core/editor/left-panel/index.js) renders as a draggable item. This guide provides a complete walkthrough of creating the component file, configuring the plugin registry, and adding internationalization support.

Understanding the Plugin Architecture

The Luban H5 editor constructs its left sidebar from the plugins array exported by src/components/core/plugins/index.js. Each object in this array defines a component type available in the Components tab.

According to the source code in src/components/core/editor/left-panel/index.js, the sidebar iterates over this registry to render draggable plugin items. The registry entry must expose specific fields:

• name: A unique identifier for the component type (e.g., lbp-my-button)
• label: An i18n key for the display name in the sidebar
• component: The Vue component rendered on the canvas
• defaultProps: Default property values when the component is first dropped
• componentsForPropsEditor: (Optional) Configuration for the right-panel property editor
• icon: (Optional) Icon displayed in the sidebar list

Step-by-Step Guide to Adding a New Component

Step 1: Create the Component File

Create a new JavaScript file under src/components/core/plugins/. This file exports an object describing your component.

// src/components/core/plugins/lbp-my-button.js
import MyButton from '@/components/core/plugins/lbp-button.vue';

export default {
  name: 'lbp-my-button',
  label: 'myButton.title',
  component: MyButton,
  defaultProps: {
    text: 'Click me',
    type: 'primary',
    size: 'default'
  },
  componentsForPropsEditor: {
    text: { type: 'input', placeholder: 'Button label' },
    type: { type: 'select', options: ['primary', 'default', 'dashed'] }
  },
  icon: require('@/assets/icons/button.svg')
};

The componentsForPropsEditor object defines how the right-panel renders property controls. Each key corresponds to a defaultProps field.

Step 2: Register the Component in the Plugin Index

Edit src/components/core/plugins/index.js to import your new file and add it to the exported plugins array.

// src/components/core/plugins/index.js
import LbpButton from './lbp-button.js';
import LbpMyButton from './lbp-my-button.js';

export const plugins = [
  // ... existing plugins ...
  {
    name: 'lbp-my-button',
    label: 'myButton.title',
    component: LbpMyButton.component,
    defaultProps: LbpMyButton.defaultProps,
    componentsForPropsEditor: LbpMyButton.componentsForPropsEditor,
    icon: LbpMyButton.icon
  }
];

The left-panel component in src/components/core/editor/left-panel/index.js automatically iterates over this array to populate the sidebar.

Step 3: Add Internationalization (i18n) Strings

Add display names and tooltips to the locale files so the sidebar shows human-readable text.

// src/locales/lang/en-US.js
{
  // ...
  "myButton.title": "My Button",
  "myButton.tooltip": "A custom button you can configure"
}

// src/locales/lang/zh-CN.js
{
  // ...
  "myButton.title": "我的按钮",
  "myButton.tooltip": "可自定义的按钮组件"
}

The label field in your plugin entry references the myButton.title key.

Step 4: Add a Custom Icon (Optional)

Place an SVG or PNG file in src/assets/icons/ and reference it in your plugin definition:

icon: require('@/assets/icons/my-button.svg')

If no icon is provided, the sidebar may render a default placeholder.

Complete Working Example

Here is the full implementation combining all steps above.

Plugin Definition:

// src/components/core/plugins/lbp-my-button.js
import MyButton from '@/components/core/plugins/lbp-button.vue';

export default {
  name: 'lbp-my-button',
  label: 'myButton.title',
  component: MyButton,
  defaultProps: {
    text: 'Click me',
    type: 'primary',
    size: 'default'
  },
  componentsForPropsEditor: {
    text: { type: 'input', placeholder: 'Button label' },
    type: { type: 'select', options: ['primary', 'default', 'dashed'] }
  },
  icon: require('@/assets/icons/button.svg')
};

Registry Update:

// src/components/core/plugins/index.js
import LbpMyButton from './lbp-my-button.js';

export const plugins = [
  // ... existing plugins ...
  {
    name: 'lbp-my-button',
    label: 'myButton.title',
    component: LbpMyButton.component,
    defaultProps: LbpMyButton.defaultProps,
    componentsForPropsEditor: LbpMyButton.componentsForPropsEditor,
    icon: LbpMyButton.icon
  }
];

Locale Entries:

// src/locales/lang/en-US.js
"myButton.title": "My Button",
"myButton.tooltip": "A custom button you can configure"

// src/locales/lang/zh-CN.js
"myButton.title": "我的按钮",
"myButton.tooltip": "可自定义的按钮组件"

Key Files Reference

File	Purpose
src/components/core/plugins/index.js	Central registry exporting the plugins array that populates the sidebar.
src/components/core/editor/left-panel/index.js	UI component that iterates over the plugin registry to render draggable items.
src/locales/lang/en-US.js	English translations for component labels and tooltips.
src/locales/lang/zh-CN.js	Chinese translations for component labels and tooltips.
src/assets/icons/	Directory for sidebar icons referenced by plugin entries.

Summary

• Create a plugin definition file in src/components/core/plugins/ containing name, label, component, defaultProps, and optional componentsForPropsEditor and icon.
• Register the plugin by importing it into src/components/core/plugins/index.js and adding it to the exported plugins array.
• Localize the component name by adding entries to src/locales/lang/en-US.js and src/locales/lang/zh-CN.js using the key specified in the label field.
• Verify that the left-panel component (src/components/core/editor/left-panel/index.js) renders your new entry by iterating over the updated registry.

Frequently Asked Questions

Where does the sidebar component list come from in Luban H5?

The sidebar component list is generated dynamically from the plugins array exported by src/components/core/plugins/index.js. The left-panel component (src/components/core/editor/left-panel/index.js) iterates over this array to render each draggable plugin item, using the label and icon fields for display.

What fields are required when defining a new plugin entry?

At minimum, a plugin entry must include name (unique identifier), label (i18n key for the display name), component (the Vue component rendered on canvas), and defaultProps (initial property values). Optional but recommended fields include componentsForPropsEditor (configures the right-panel property editor) and icon (displayed in the sidebar).

How do I add property editing controls to the right panel?

Define a componentsForPropsEditor object in your plugin entry where each key matches a field in defaultProps. Each value should specify the editor type (e.g., input, select) and configuration options like placeholder or options. The editor's right-panel uses this configuration to render the appropriate form controls for your component.

Can I reuse an existing Vue component for my new plugin type?

Yes, you can reference any existing Vue component in the component field of your plugin definition. For example, you could import lbp-button.vue and use it as the canvas component for your new plugin entry while providing different defaultProps or componentsForPropsEditor configurations to create a specialized variant with distinct default behavior or property controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}