gs-fabric-image-editor

基于 Vue 3 + Fabric.js 的嵌入式图片编辑器组件，侧重像素级锐利渲染（关闭图像平滑、整数坐标对齐）。

安装

pnpm add gs-fabric-image-editor vue

fabric 已打包进产物，无需宿主机单独安装；仅 vue 为 peer 依赖。样式随 JS 自动注入，无需单独 import CSS。

快速开始

<script setup lang="ts">
import { FabricImageEditor } from 'gs-fabric-image-editor'
</script>

<template>
  <div class="editor-wrap">
    <FabricImageEditor />
  </div>
</template>

<style scoped>
.editor-wrap {
  width: 100%;
  height: 600px; /* 父容器必须有明确高度 */
}
</style>

样式（可选）

默认 import 组件即可，样式会运行时注入 <style>。若希望用 <link> 或自行控制样式加载，可额外引入：

import 'gs-fabric-image-editor/style.css'

本地 Demo

本仓库内置 playground，用于开发调试组件：

pnpm install
pnpm dev

浏览器访问 http://localhost:3000。入口为 src/App.vue，在 900×600 容器内渲染 <FabricImageEditor />。

| 命令 | 说明 | |------|------| | pnpm dev | 启动 demo 开发服务器 | | pnpm build | 构建 demo 静态站 | | pnpm build:lib | 构建 npm 库产物（dist/） | | pnpm preview | 预览 demo 构建结果 |

Props

| 属性 | 类型 | 说明 | |------|------|------| | options | FabricImageEditorOptions | 功能与 UI 配置，见下文 | | teleportTo | string \| HTMLElement | 浮层挂载目标（也可用 options.teleportTo） |

Options 配置

左侧 Tab 显隐

options: {
  tools: {
    adjust: true,
    finetune: true,
    filters: true,
    watermark: false,
    annotate: false,
    resize: true,
  },
  defaultTool: 'adjust',
}

未指定的 Tab 默认为显示。

头部按钮显隐

options: {
  header: {
    showUpload: true,
    showSave: true,
    showExport: true,
    showCompare: true,
    showResetView: true,
    showResetImage: true,
    showZoom: true,
    showClose: false,   // 默认 false；弹窗/抽屉等需要关闭入口时开启
  },
}

导出配置

options: {
  export: {
    // defaultFileName 不传或传空字符串时，使用上传图片原始文件名（不含扩展名）
    defaultFormat: 'png',
    formats: ['png', 'jpg'],
    defaultQuality: 92,
    showDialog: true,
    showSizeFields: true,
    showQuality: true,
  },
}

showDialog: false 时点击导出按钮将按默认配置直接下载。

保存配置（options.save）

与导出独立，未传的项会继承 export 对应配置：

options: {
  save: {
    // defaultFileName 未传 → 继承 export，再回退原图名
    defaultFormat: 'jpg',
    defaultQuality: 90,
    includeBlob: false,     // 默认 false
    includeBase64: false,   // 默认 false，按需开启
  },
}

保存与导出分离：保存只发 save 事件，不下载；导出走下载/弹窗。

事件

| 事件 | 载荷 | 说明 | |------|------|------| | ready | api | 画布 API 就绪 | | image-load | File | 图片加载完成 | | image-change | { width, height } | 显示尺寸变化 | | tool-change | EditorToolId | 切换左侧 Tab | | save | EditorSavePayload | 保存成功（blob / base64 按 options.save 配置） | | save-error | Error | 保存失败 | | close | 'button' \| 'api' | 请求关闭（点头部关闭按钮为 'button'，调用 requestClose() 为 'api'）；header.showClose: true 时头部才显示关闭按钮 | | export | { blob, fileName, format } | 导出成功（下载后） | | export-error | Error | 导出失败 |

EditorSavePayload 字段：fileName、format、width、height，以及可选的 blob、base64。

Ref 方法

<FabricImageEditor ref="editorRef" />

| 方法 | 说明 | |------|------| | getApi() | 获取底层 useFabric API | | loadImage(file) | 程序化加载图片 | | exportImage(opts?) | 导出 Blob（不自动下载） | | save(opts?) | 保存并返回 EditorSavePayload（不自动下载）；可单次覆盖 format / width / height / quality / includeBlob / includeBase64 | | resetView() | 重置视图缩放/平移 | | resetImage() | 恢复原图 | | getDisplaySize() | 当前显示宽高 | | requestClose() | 触发 close 事件（reason: 'api'）；用于弹窗遮罩/ESC 等外部关闭入口 |

弹窗 / 抽屉嵌入

组件本身不含遮罩容器，只在 header.showClose: true 时显示关闭按钮并发出 close 事件，是否关闭由宿主机决定。

弹窗内使用时务必把 teleportTo 指向弹窗节点，否则导出弹窗、缩放下拉会挂到 body 底层导致被遮挡。

<script setup lang="ts">
import { ref } from 'vue'
import { FabricImageEditor } from 'gs-fabric-image-editor'

const open = ref(false)
const modalEl = ref<HTMLElement | null>(null)
const editorRef = ref<InstanceType<typeof FabricImageEditor> | null>(null)
</script>

<template>
  <button @click="open = true">编辑图片</button>

  <Teleport to="body">
    <div v-if="open" class="host-overlay" @click.self="editorRef?.requestClose()">
      <div ref="modalEl" class="host-modal">
        <FabricImageEditor
          ref="editorRef"
          :options="{ teleportTo: modalEl, header: { showClose: true } }"
          @close="open = false"
        />
      </div>
    </div>
  </Teleport>
</template>

<style scoped>
.host-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.45);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1000;
}
.host-modal {
  width: 90vw;
  height: 85vh;
  background: #fff;
  border-radius: 8px;
  overflow: hidden;
}
</style>

• v-if="open" 关闭时会卸载组件并释放 canvas
• 非弹窗（页面内嵌）默认不显示关闭按钮；如需在抽屉/可折叠区域使用，也可开 header.showClose: true，@close 后自行隐藏
• 保存与关闭解耦：save 事件后是否关弹窗由业务决定

类型导出

import type {
  FabricImageEditorOptions,
  EditorToolId,
  EditorExportOptions,
  EditorSaveOptions,
  EditorSavePayload,
  ExportFormat,
  ExportOptions,
  CropPreset,
} from 'gs-fabric-image-editor'

发布到 npm

一键脚本（推荐）

Git Bash / WSL / macOS / Linux：

chmod +x scripts/publish.sh   # 首次赋予执行权限

./scripts/publish.sh              # 构建 + 试发布 + 确认后发布当前版本
./scripts/publish.sh patch        # patch 版本 + 构建 + 发布
./scripts/publish.sh --dry-run    # 仅验证构建与打包，不发布
./scripts/publish.sh patch -y     # 无交互发布 patch 版本

或通过 pnpm：

pnpm run publish:sh
pnpm run publish:patch
pnpm run publish:minor
pnpm run publish:major

脚本流程：拉取 npm 线上版本 → 递增版本号（首次为 0.0.1）→ 写入 package.json → build:lib → npm pack → npm publish --dry-run → 确认后 npm publish。

手动发布

npm login
pnpm run build:lib
npm publish --dry-run
pnpm run release

依赖

• vue ^3.5.0（peer 依赖，需宿主机安装）
• fabric ^7.4.0（已打包进产物，无需单独安装）
• 组件样式已内置于 JS，import 组件后自动注入；也可选用 gs-fabric-image-editor/style.css