@tootix/grapesjs-vue

Vue 3 包装组件与组合式 API，用于围绕 GrapesJS 构建自定义编辑器界面。本库负责画布外围的 UI 控制，不会在画布内部渲染 Vue 组件。

兼容性

• Vue >= 3.5
• GrapesJS >= 0.22.16

安装

pnpm add @tootix/grapesjs-vue grapesjs vue
# 或
npm install @tootix/grapesjs-vue grapesjs vue

应用中需引入 GrapesJS 样式表，或在通过 script URL 加载 GrapesJS 时传入样式表 URL。

快速开始

传入 GrapesJS 模块和标准的编辑器配置，即可使用默认 UI。

<script setup lang="ts">
import grapesjs from 'grapesjs'
import 'grapesjs/dist/css/grapes.min.css'
import Editor from '@tootix/grapesjs-vue'
</script>

<template>
  <Editor
    :grapesjs="grapesjs"
    :options="{
      height: '100vh',
      storageManager: false,
      fromElement: false,
    }"
  />
</template>

自定义 UI + 内置画布

将 <Canvas /> 放置到希望挂载 GrapesJS 画布的位置。一旦提供了 Canvas，包装器会以 customUI 模式初始化 GrapesJS，由 Vue 负责画布周围的控件。

<script setup lang="ts">
import grapesjs from 'grapesjs'
import 'grapesjs/dist/css/grapes.min.css'
import { Canvas, Editor } from '@tootix/grapesjs-vue'
</script>

<template>
  <Editor :grapesjs="grapesjs" :options="{ height: '100%', storageManager: false }">
    <div class="editor-shell">
      <aside class="sidebar">自定义面板</aside>
      <Canvas class="canvas" />
    </div>
  </Editor>
</template>

编辑器组合式 API

• useEditor()：返回已加载的 GrapesJS 编辑器实例；若在编辑器就绪前调用会抛出异常。
• useEditorMaybe()：编辑器未就绪时返回 undefined。

<!-- EditorStatus.vue -->
<script setup lang="ts">
import { useEditorMaybe } from '@tootix/grapesjs-vue'

const maybeEditor = useEditorMaybe()
const ready = Boolean(maybeEditor)
</script>

<template>
  <span>{{ ready ? 'Ready' : 'Loading' }}</span>
</template>

<!-- ClearCanvasButton.vue -->
<script setup lang="ts">
import { useEditor } from '@tootix/grapesjs-vue'

const editor = useEditor()
</script>

<template>
  <button type="button" @click="editor.runCommand('core:canvas-clear')">清空画布</button>
</template>

可通过 <WithEditor> 在编辑器就绪后再渲染子组件，确保子组件中的 useEditor() 调用安全：

<script setup lang="ts">
import { WithEditor } from '@tootix/grapesjs-vue'
import ClearCanvasButton from './ClearCanvasButton.vue'
</script>

<template>
  <WithEditor>
    <ClearCanvasButton />
  </WithEditor>
</template>

Provider 组件

Provider 组件通过 Vue 作用域插槽暴露 GrapesJS 各 Manager 的状态和操作，使自定义 UI 既保持声明式写法，又能完整保留 GrapesJS 的原生行为。

<script setup lang="ts">
import { BlocksProvider } from '@tootix/grapesjs-vue'
</script>

<template>
  <BlocksProvider v-slot="{ blocks, dragStart, dragStop }">
    <button
      v-for="block in blocks"
      :key="block.getId()"
      type="button"
      draggable="true"
      @dragstart="dragStart(block, $event)"
      @dragend="dragStop"
    >
      {{ block.getLabel() }}
    </button>
  </BlocksProvider>
</template>

内置 Provider 列表：

| 组件 | 对应 Manager | | ------------------- | ------------------- | | BlocksProvider | Blocks（积木块） | | DevicesProvider | Devices（设备） | | PagesProvider | Pages（页面） | | LayersProvider | Layers（图层） | | SelectorsProvider | Selectors（选择器） | | StylesProvider | Styles（样式） | | TraitsProvider | Traits（属性） | | AssetsProvider | Assets（资源） | | ModalProvider | Modal（弹窗） |

API 概览

导出

• 组件：Editor（默认导出，也作为 GjsEditor 命名导出）、Canvas、WithEditor
• Provider：BlocksProvider、DevicesProvider、PagesProvider、LayersProvider、SelectorsProvider、StylesProvider、TraitsProvider、AssetsProvider、ModalProvider
• 组合式 API：useEditor、useEditorMaybe
• 类型：EditorProps、PluginToLoad、PluginTypeToLoad，以及各 Provider 的 *ResultProps

<Editor> Props

| Prop | 类型 | 说明 | | ------------- | ----------------------------- | ---------------------------------------------------- | | grapesjs | string \| GrapesJsModule | GrapesJS 模块，或 CDN 脚本 URL | | options | EditorConfig | GrapesJS 标准配置 | | grapesjsCss | string | 通过 URL 加载 GrapesJS 时附带的样式表地址 | | plugins | PluginTypeToLoad[] | 插件列表，支持字符串 / 函数 / { id, src, options } | | waitReady | boolean \| string \| object | 是否等待指定就绪事件后再暴露编辑器实例 |

开发

pnpm install
pnpm dev          # 启动示例
pnpm test:unit    # 单元测试
pnpm build        # 构建产物输出到 dist/

构建产物：

• ESM：dist/grapesjs-vue.js
• CJS：dist/grapesjs-vue.cjs.js
• 类型声明：dist/index.d.ts

发布

npm 发布通过 GitHub Actions 手动触发，并使用 npm Trusted Publishing/OIDC 免 token 发布。

发布前先提交新的 package.json 版本号，然后在 GitHub Actions 中运行 Publish npm package workflow。首次配置 npm Trusted Publisher 时使用以下字段：

• Provider：GitHub Actions
• Repository：navnry/grapesjs-vue
• Workflow filename：publish.yml
• Environment name：npm-publish

workflow 默认 dry_run=true，只运行测试、构建和 npm pack --dry-run。确认后重新运行并选择 dry_run=false 才会发布到 npm。

License

MIT