Canvas Drawing Editor
GitHub

强大的 Canvas 画布编辑器

此组件为 Web Component，需要配合框架或原生 HTML 使用。零依赖，支持 Vue 2/3、React、Angular 和原生 HTML。

立即开始 查看演示
Canvas Editor Interface Preview

核心能力

✨ 功能特性一览

🎨 绘图工具集

画笔、矩形、圆形、线条、箭头、多边形、文本、图片导入，满足多样化创作需求。

✏️ 高级编辑

撤销/重做、图层管理、组合/解组、对齐分布、缩放平移。

💾 导入导出

JSON 保存/加载项目，PNG 导出图像，一键清空画布。

🔥 热区功能

给文本绑定动态变量，实现模板化设计，动态替换文本内容。

⚡ 零依赖轻量

纯 JavaScript 实现，gzip 后仅约 20KB，无框架负担。

🔌 跨框架兼容

Web Component 标准，支持 Vue 2/3、React、Angular 和原生 HTML。

🎬 Tween 动画

对象属性过渡动画，支持位置、大小、旋转、透明度等属性的平滑动画效果。

📱 移动端优化

单指拖拽、双指缩放/旋转、长按选择，工具栏响应式布局。

⭐ 丰富形状

星形、心形、三角形、菱形、贝塞尔曲线、平滑曲线等多种形状，满足复杂设计需求。

🎨 填充模式

支持描边、填充、描边+填充三种模式，让形状更加丰富多彩。

📐 形状库

注册自定义形状，支持带文字的组合形状，可搜索选择快速添加到画布。

快速上手

📦 安装与集成

NPM 安装

通过 npm 或 yarn 安装到您的项目中： 

$ npm install canvas-drawing-editor

（注意：此组件为 Web Component，需要配合框架或原生 HTML 使用）

原生 HTML 使用

直接引入 UMD 包，并在 DOM 中使用自定义标签： 

<!DOCTYPE html>
<html>
<head>
  <style>
    canvas-drawing-editor {
      width: 100%;
      height: 600px;
      display: block;
    }
  </style>
</head>
<body>
  <canvas-drawing-editor title="我的画板"></canvas-drawing-editor>

  <script src="https://unpkg.com/canvas-drawing-editor/dist/canvas-drawing-editor.umd.js"></script>
</body>
</html>

开始使用

🚀 如何使用

Vue 3

在 Vue 3 组件中使用 Web Component：

React

React 中使用 Web Component 的方式与原生类似，但需注意属性传递：

Angular

Angular 中使用 Web Component 需要在模块中添加 CUSTOM_ELEMENTS_SCHEMA： 

// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import 'canvas-drawing-editor';

@NgModule({
  // ...
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }

// app.component.html
<canvas-drawing-editor
  title="Angular 画板"
  style="width: 100%; height: 600px;"
></canvas-drawing-editor>

灵活定制

🎛️ 可配置性

通过简单的 HTML 属性，您可以隐藏/显示任意工具：

  • 灵活控制工具栏：画笔、矩形、圆形、文本、图片、缩放等。
  • 自定义文件操作：导出 PNG、保存/加载 JSON、清空画布按钮。
  • 保持核心 Canvas 逻辑，只暴露所需 UI。
Configurable Editor Preview

详细参考

📖 API 文档

配置属性

属性 类型 默认值 说明
titlestring"Canvas Editor"编辑器标题
show-pencilbooleantrue显示画笔工具
show-rectanglebooleantrue显示矩形工具
show-circlebooleantrue显示圆形工具
show-textbooleantrue显示文本工具
show-imagebooleantrue显示图片导入
show-zoombooleantrue显示缩放控制
show-downloadbooleantrue显示 PNG 导出
show-exportbooleantrue显示 JSON 保存
show-importbooleantrue显示 JSON 加载
show-colorbooleantrue显示颜色选择器
show-clearbooleantrue显示清空画布按钮
langstring"zh"界面语言（"zh" 中文，"en" 英文）
theme-colorstring"#5450dc"主题色（影响按钮、悬停状态等）
initial-datastring-初始化 JSON 数据
enable-hotzonebooleanfalse启用热区功能（管理员模式）
hotzone-datastring-热区变量数据（JSON 格式）
tool-configstring-工具配置对象（JSON 格式，推荐使用）
max-image-sizestring-图片大小限制（支持 "500kb"、"2mb" 格式）
show-linebooleantrue显示线条工具
show-arrowbooleantrue显示箭头工具
show-polygonbooleantrue显示多边形工具
show-undobooleantrue显示撤销按钮
show-redobooleantrue显示重做按钮
show-layersbooleantrue显示图层管理
show-groupbooleantrue显示组合/解组
show-alignbooleantrue显示对齐/分布
show-shape-panelbooleantrue显示形状库面板

事件

editor-change

画布内容发生变化时触发，e.detail.objects 包含所有绘图对象。

editor-close

编辑器关闭时触发。

animation-start

动画开始时触发。

animation-complete

动画完成时触发。

animation-update

动画每帧更新时触发。

对象类型

每个绘图对象都有以下基础属性：

属性 类型 说明
idstring唯一标识符
typestring对象类型: RECTANGLE, CIRCLE, PATH, TEXT, IMAGE
x, ynumber坐标位置
colorstring颜色值 (如 #3b82f6)
lineWidthnumber线条宽度
📦 矩形 (RECTANGLE)

width, height

⚪ 圆形 (CIRCLE)

radius

✏️ 画笔 (PATH)

points - 坐标数组

📝 文本 (TEXT)

text, fontSize, hotzone

🖼️ 图片 (IMAGE)

width, height, dataUrl

📏 线条 (LINE)

x2, y2

➡️ 箭头 (ARROW)

x2, y2

🔷 多边形 (POLYGON)

radius, sides

🖊️ 贝塞尔曲线 (BEZIER)

points, closed

〰️ 平滑曲线 (SMOOTH_CURVE)

points, tension, closed

热区功能

热区功能允许给文本对象绑定动态变量，实现模板化的动态文本替换。

管理员模式（设计模板）

<canvas-drawing-editor
  title="模板设计器"
  enable-hotzone="true"
></canvas-drawing-editor>

右键点击文本 → 新建热区 → 输入变量名 → 保存

用户模式（展示动态数据）

<canvas-drawing-editor
  initial-data='{"objects":[...]}'
  hotzone-data='{"name": "张三", "company": "XX公司"}'
></canvas-drawing-editor>

热区数据结构

{
  "type": "TEXT",
  "text": "姓名",
  "hotzone": {
    "variableName": "name",      // 变量名（必填）
    "defaultValue": "默认值",     // 默认值（可选）
    "description": "用户姓名"     // 描述（可选）
  }
}

形状库 API

形状库功能允许注册自定义形状，用户可以从形状面板中选择并添加到画布。

注册形状

const editor = document.querySelector('canvas-drawing-editor');

// 注册自定义形状
editor.registerShapes([
  {
    id: 'btn-confirm',
    name: '确认按钮',
    type: 'roundedRect',
    category: '按钮',
    fillColor: '#22c55e',
    fillMode: 'fill',
    cornerRadius: 8,
    width: 100,
    height: 40,
    text: '确认',
    textColor: '#ffffff',
    fontSize: 14,
    fontWeight: 'bold'
  }
]);

监听形状添加事件

editor.addEventListener('shape-added', (e) => {
  console.log('形状已添加:', e.detail.shape.name);
  console.log('创建的对象:', e.detail.object);
});

形状配置属性

属性 类型 说明
idstring形状唯一标识
namestring形状名称（显示用）
typestring形状类型：rectangle, circle, triangle, star, heart, diamond, ellipse, roundedRect 等
categorystring分类名称（可选）
fillColorstring填充颜色
fillModestring填充模式：stroke, fill, both
textstring形状中心文字
textColorstring文字颜色
fontSizenumber文字大小
width, heightnumber默认宽高

图片导出 API

通过 getImageData() 方法获取画布图片数据（base64 或 Blob），无需触发下载，适合上传到服务器。

基本用法

const editor = document.querySelector('canvas-drawing-editor');

// 获取 base64 格式（默认）
const dataURL = await editor.getImageData();
console.log(dataURL); // data:image/png;base64,...

// 获取 Blob 格式（适合上传）
const blob = await editor.getImageData({
  type: 'blob',
  format: 'png',        // 'png' | 'jpeg' | 'webp'
  quality: 0.92,        // jpeg/webp 质量 (0-1)
  background: '#ffffff' // 背景色
});

// 上传到服务器
const formData = new FormData();
formData.append('image', blob, 'canvas.png');
await fetch('/api/upload', { method: 'POST', body: formData });

参数说明

参数 类型 默认值 说明
formatstring'png'图片格式：png, jpeg, webp
qualitynumber0.92图片质量（仅 jpeg/webp）
typestring'dataURL'返回类型：dataURL 或 blob
backgroundstring'#ffffff'背景颜色