GrapesJS 教程 · 构建你的第一个可视化编辑器

<!-- The editor takes over this element completely.
     Do not render anything inside it yourself. -->
<div id="gjs"></div>

import grapesjs from 'grapesjs';
import 'grapesjs/dist/css/grapes.min.css';

const editor = grapesjs.init({
  // Where the editor mounts: a selector or an HTMLElement.
  container: '#gjs',
  height: '100vh',
  width: 'auto',

  // Do not adopt the markup already inside #gjs...
  fromElement: false,
  // ...load this instead. Strings are parsed into components.
  components: `
    <section class="hero">
      <h1>Hello GrapesJS</h1>
      <p>Drag a block from the panel on the right.</p>
    </section>`,
  style: `
    .hero { padding: 64px 32px; font-family: system-ui, sans-serif; }
    .hero h1 { margin: 0 0 12px; font-size: 40px; }`,

  // Storage is ON by default and writes to localStorage.
  // Turn it off until you have decided where projects really live.
  storageManager: false,
});

// A Block is a palette entry. Dropping it creates Components.
editor.Blocks.add('hero-section', {
  label: 'Hero',
  category: 'Sections',
  // Shown in the palette. Any HTML string works; an inline SVG keeps it sharp.
  media: '<svg viewBox="0 0 24 24" width="22"><rect x="3" y="5" width="18" height="6" rx="1" fill="currentColor"/><rect x="3" y="13" width="11" height="3" rx="1" fill="currentColor" opacity=".5"/></svg>',
  content: `
    <section class="hero">
      <h1>Headline</h1>
      <p>Supporting copy.</p>
      <a href="#" class="btn">Call to action</a>
    </section>`,
});

// The same block, expressed as a component definition instead of HTML.
// Use this form once you have your own component types (step 10).
editor.Blocks.add('product-card', {
  label: 'Product card',
  category: 'Commerce',
  content: { type: 'product-card' },
});

import grapesjs, { usePlugin } from 'grapesjs';
import blocksBasic from 'grapesjs-blocks-basic';

// The core ships no blocks at all. The familiar
// "1 column / 2 columns / text / image" palette is a plugin.
grapesjs.init({
  container: '#gjs',
  plugins: [usePlugin(blocksBasic, { flexGrid: true })],
});

// Every node in the canvas is a Component, and the canvas is a tree.
const wrapper = editor.getWrapper();

wrapper.components().forEach((component) => {
  console.log(
    component.get('type'),      // 'text' | 'image' | 'link' | your own type
    component.getName(),        // label shown in the Layer manager
    component.components().length // number of children
  );
});

// React to what the user selects — the hook most custom UI hangs off.
editor.on('component:selected', (component) => {
  console.log('selected', component.getId(), component.get('type'));
});

// Traits are the settings panel for a component.
// By default a trait writes an HTML attribute.
editor.Components.addType('cta-button', {
  extend: 'link',
  model: {
    defaults: {
      name: 'CTA button',
      attributes: { class: 'btn' },
      components: 'Call to action',
      traits: [
        { name: 'href', label: 'Link' },
        { name: 'title', label: 'Title' },
        {
          type: 'select',
          name: 'target',
          label: 'Opens in',
          options: [
            { id: '', name: 'Same tab' },
            { id: '_blank', name: 'New tab' },
          ],
        },
      ],
    },
  },
});

grapesjs.init({
  container: '#gjs',
  styleManager: {
    // Sectors are the collapsible groups in the right-hand panel.
    // Listing them yourself is how you stop the editor offering
    // 100+ CSS properties to a non-technical author.
    sectors: [
      {
        id: 'typography',
        name: 'Typography',
        open: true,
        properties: [
          'font-family',
          'font-size',
          'font-weight',
          'line-height',
          'color',
          'text-align',
        ],
      },
      { id: 'spacing', name: 'Spacing', properties: ['margin', 'padding'] },
      {
        id: 'dimension',
        name: 'Dimension',
        properties: ['width', 'max-width', 'height'],
      },
      {
        id: 'decorations',
        name: 'Decorations',
        properties: ['background-color', 'border-radius', 'border', 'box-shadow'],
      },
    ],
  },
});

// Structure and styling are separate concerns. A component can accept
// children while refusing to be restyled beyond a fixed allowance.
editor.Components.addType('brand-heading', {
  extend: 'text',
  model: {
    defaults: {
      name: 'Brand heading',
      // Only these properties reach the Style manager for this component.
      stylable: ['color', 'text-align'],
      // Everything else stays on the class in your own stylesheet.
      attributes: { class: 'brand-h2' },
    },
  },
});

grapesjs.init({
  container: '#gjs',
  assetManager: {
    // Seed the panel with images you already host.
    assets: [
      'https://cdn.example.com/hero.jpg',
      { src: 'https://cdn.example.com/team.jpg', name: 'Team', category: 'People' },
    ],
    // Your upload endpoint. Set `upload: false` to disable uploading entirely.
    upload: 'https://api.example.com/uploads',
    uploadName: 'files',
    headers: { Authorization: 'Bearer <token>' },
    multiUpload: true,
    // Add the response's assets to the panel automatically. Your endpoint must
    // answer with { data: [ ...assets ] }.
    autoAdd: true,
  },
});

// Full control: upload wherever you like, then hand the URLs back.
grapesjs.init({
  container: '#gjs',
  assetManager: {
    async uploadFile(event) {
      const files = event.dataTransfer
        ? event.dataTransfer.files
        : event.target.files;

      const urls = await uploadToYourStorage(files); // S3, R2, Cloudinary…
      editor.AssetManager.add(urls);
    },
  },
});

// Without `upload` or `uploadFile`, dropped images are embedded as base64
// straight into the project — convenient in a demo, painful in production.

grapesjs.init({
  container: '#gjs',
  storageManager: {
    type: 'remote',
    autosave: true,
    autoload: true,
    // Batch changes: save after N edits rather than after every keystroke.
    stepsBeforeSave: 5,
    options: {
      remote: {
        urlLoad: '/api/projects/42',
        urlStore: '/api/projects/42',
        headers: { 'X-CSRF-Token': csrfToken },
        credentials: 'include',
        // Shape the request body to match your API…
        onStore: (data) => ({ project: data }),
        // …and pull the project back out of your response.
        onLoad: (result) => result.project,
      },
    },
  },
});

// When `remote` does not fit — GraphQL, a queue, an offline-first cache —
// register a storage of your own and select it by name.
editor.Storage.add('my-api', {
  async load() {
    const res = await fetch('/api/projects/42');
    const { project } = await res.json();
    return project; // the object you previously stored
  },
  async store(data) {
    await fetch('/api/projects/42', {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ project: data }),
    });
  },
});

// storageManager: { type: 'my-api' }

// You can also drive it by hand, with no storage configured at all:
const project = editor.getProjectData();   // plain JSON — store it anywhere
editor.loadProjectData(project);           // and put it back

const html = editor.getHtml();
const css = editor.getCss();

// Two things surprise everyone on their first export:
//
// 1. getHtml() returns the canvas wrapped in <body> … </body>.
//    Strip or template around it before you save a fragment.
// 2. getCss() includes GrapesJS's own canvas reset unless you opt out:
const pageCss = editor.getCss({ avoidProtected: true });

// Export one branch instead of the whole page:
const selected = editor.getSelected();
const partial = editor.getHtml({ component: selected });

// The editable project — NOT the same thing as the exported page.
const project = editor.getProjectData();

import grapesjs, { usePlugin } from 'grapesjs';
import blocksBasic from 'grapesjs-blocks-basic';
import forms from 'grapesjs-plugin-forms';

grapesjs.init({
  container: '#gjs',
  plugins: [
    usePlugin(blocksBasic, { flexGrid: true }),
    usePlugin(forms, {}),
  ],
});

// A plugin is just a function that receives the editor.
// Anything you can do at init you can do inside one.
export default function dividerPlugin(editor, options = {}) {
  const category = options.category ?? 'Basic';

  editor.Blocks.add('divider', {
    label: 'Divider',
    category,
    content: '<hr class="divider" />',
  });

  editor.Commands.add('clear-canvas', {
    run: (ed) => ed.Components.clear(),
  });
}

// Then: plugins: [usePlugin(dividerPlugin, { category: 'Layout' })]

editor.Components.addType('product-card', {
  // Lets GrapesJS recognise the type when parsing saved HTML.
  isComponent: (el) => el.dataset?.gjsType === 'product-card',

  model: {
    defaults: {
      name: 'Product card',
      attributes: { 'data-gjs-type': 'product-card', class: 'product-card' },

      // Author-visible settings. `changeProp` writes to the model
      // instead of to an HTML attribute.
      traits: [
        { name: 'sku', label: 'SKU', changeProp: true },
        {
          type: 'checkbox',
          name: 'showPrice',
          label: 'Show price',
          changeProp: true,
        },
      ],
      sku: '',
      showPrice: true,

      // Fixed structure: the author edits the parts, not the layout.
      components: [
        { type: 'image', attributes: { class: 'product-card__image' } },
        { type: 'text', name: 'Name', components: 'Product name' },
        { type: 'text', name: 'Price', attributes: { class: 'product-card__price' }, components: '$0.00' },
        { type: 'cta-button', components: 'Add to cart' },
      ],

      // Locks that make the card a card and not a free-form div.
      droppable: false,
      stylable: ['background-color', 'border-radius', 'box-shadow'],
    },

    init() {
      this.on('change:showPrice', this.togglePrice);
    },

    togglePrice() {
      const price = this.components().at(2);
      price?.addStyle({ display: this.get('showPrice') ? 'block' : 'none' });
    },
  },
});