vkedit

vkedit

基于 Vue 3 与 Konva.js 的可视化画布设计器组件，采用插件化架构，适用于标签、二维码、条码、票据、名片、证书等模板设计与打印排版场景。

English | 在线示例 | 文档

特性

• 插件化架构 - 核心功能与图形元素均以插件形式注册，按需启用；GraphicPlugin<T> 抽象基类简化自定义插件开发
• 5 种图形元素 - 矩形、文本、线条、二维码、条形码
• 撤销/重做 - 基于命令模式，所有修改操作可逆
• 导入/导出 - JSON 序列化、PNG/JPG 图片、PDF 文档
• 对齐与分布 - 左/右/上/下/居中对齐、水平/垂直均分
• 标尺与缩放 - 毫米级精度标尺、可配置 DPM（每毫米点数）
• 事件驱动 - 类型安全的事件系统，插件间松耦合通信
• TypeScript - 完整类型定义，泛型推断插件与元素类型
• 设计令牌系统 - 两层架构（Palette + Semantic），完整 CSS 变量覆盖 spacing、radius、font、shadow、elevation、z-index
• 主题系统 - 默认暗色主题，亮色主题通过 data-vkedit-theme 切换；Teleport 浮层主题继承；resolveVkeditTheme() 工具函数
• VkButton 多变体 - primary、destructive、outline、secondary、ghost、link

安装

pnpm add vkedit vue konva vue-konva

vkedit 将 vue、konva、vue-konva 作为 peerDependencies，需由宿主项目提供。

Node.js 要求：^20.19.0 || >=22.12.0

快速上手

1. 配置入口文件

在 main.ts 中注册 VueKonva 并引入样式：

import { createApp } from 'vue'
import App from './App.vue'
import VueKonva from 'vue-konva'
import 'vkedit/dist/vkedit.css'

const app = createApp(App)
app.use(VueKonva)
app.mount('#app')

2. 使用编辑器组件

<template>
  <Vkedit :host="host" />
</template>

<script setup lang="ts">
import { createEditorHost, Vkedit } from 'vkedit'
import {
  RectPlugin,
  TextPlugin,
  QrcodePlugin,
  BarcodePlugin,
  LinePlugin,
} from 'vkedit'

const host = createEditorHost()

// 安装图形插件
host
  .installPlugin('rect-plugin', RectPlugin)
  .installPlugin('text-plugin', TextPlugin)
  .installPlugin('qr-plugin', QrcodePlugin)
  .installPlugin('barcode-plugin', BarcodePlugin)
  .installPlugin('line-plugin', LinePlugin)

// 设置画布尺寸（A4 纸张，DPM = 8）
host.setStatus({
  dpm: 8,
  width: 210 * 8,
  height: 297 * 8,
  zoom: 0.4,
})
</script>

完整教程、API 文档与在线示例请访问 docs.vkedit.org。

主题与样式

vkedit 内置完整的设计令牌（Design Token）体系。暗色主题为默认值（data-vkedit-theme="dark"），引入 CSS 后即刻生效：

import 'vkedit/dist/vkedit.css'

覆盖品牌色（挂载在编辑器根或包裹容器上）：

.vkedit-editor {
  --vkedit-color-primary: oklch(70% 0.14 185);
  --vkedit-color-primary-hover: oklch(78% 0.12 185);
  --vkedit-color-on-primary: oklch(14% 0 0);
}

令牌体系分两层：

• Palette（:root）— 颜色原始阶梯（neutral、teal、danger 等）以及非颜色尺度（spacing、radius、font、shadow、elevation、z-index）
• Semantic（主题选择器）— 引用 palette 的语义变量，分别定义 data-vkedit-theme="dark"（默认）与 data-vkedit-theme="light" 两套映射

完整变量列表与破坏性变更说明见 MIGRATION.md。

链接

• 官网
• 文档
• npm
• GitHub Releases
• Vue.js
• Konva.js
• vue-konva

License

MIT

社区

• 贡献指南
• 行为准则
• 安全政策
• 第三方许可证声明

联系方式

• QQ: 16871824
• 邮箱: 168715824@qq.com

提供技术支持、功能定制、项目合作。