manifest-label-designer

Vue 3 可视化标签设计器组件，从 manifest-design 主项目提取。内置拖拽画布、属性编辑、模板管理与打印入口，打印能力由 manifest-label-print 提供。

• GitHub：ymf-930/manifest-design
• npm：manifest-label-designer
• 打印引擎：manifest-label-print
• 集成示例：examples/verify-npm-package

目录

• 安装
• 与 manifest-label-print 联用
• 快速开始
• 样式引入（必做）
• Vue 集成方式
• 设计器功能概览
• 模板 JSON 格式
• 支持的组件类型
• 打印集成
• 导出与导入
• 导出 API
• 完整集成示例
• 常见问题
• 开发与发布

安装

npm install manifest-label-designer manifest-label-print

安装 peer 依赖（宿主项目若尚未安装）：

npm install vue pinia ant-design-vue @ant-design/icons-vue jsbarcode qrcode html2canvas

| 包 | 作用 | |----|------| | manifest-label-designer（本包） | 可视化设计器 UI | | manifest-label-print | 模板转换与打印引擎（peer 依赖，必装） |

与 manifest-label-print 联用

┌─────────────────────────┐      toPrintTemplate()      ┌─────────────────────────┐
│  manifest-label-designer │  ────────────────────────►  │  manifest-label-print    │
│  设计 / 编辑 / 导出 JSON  │      executePrint()         │  浏览器 / CLodop 打印    │
└─────────────────────────┘                             └─────────────────────────┘

• 设计器工具栏「打印」按钮内部调用 toPrintTemplate + executePrint
• 导出的 JSON 可直接交给 manifest-label-print 在业务页面中打印
• 若只需打印、不需要设计器 UI，可仅安装 manifest-label-print，详见其 README

快速开始

1. 注册应用

// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import Antd from 'ant-design-vue'
import 'ant-design-vue/dist/reset.css'
import 'manifest-label-designer/style.css'
import { ManifestLabelDesigner } from 'manifest-label-designer'
import App from './App.vue'

const app = createApp(App)

app.use(createPinia()) // 必须在 mount 之前
app.use(Antd)
app.component('ManifestLabelDesigner', ManifestLabelDesigner)
app.mount('#app')

2. 挂载组件

<template>
  <div class="designer-page">
    <ManifestLabelDesigner />
  </div>
</template>

<style scoped>
.designer-page {
  height: 100vh;
  min-height: 620px;
}
</style>

设计器为全功能自包含组件，当前版本无 props / emits，通过工具栏完成全部操作。

样式引入（必做）

设计器自带样式文件，必须在入口显式引入：

import 'ant-design-vue/dist/reset.css'
import 'manifest-label-designer/style.css'

缺少 manifest-label-designer/style.css 会导致布局错乱、面板样式丢失、画布尺寸异常等问题。

同时为容器提供稳定高度：

.designer-page {
  height: 100vh;
  min-height: 620px;
}

Vue 集成方式

方式一：按需注册组件

import { ManifestLabelDesigner } from 'manifest-label-designer'

app.component('ManifestLabelDesigner', ManifestLabelDesigner)

方式二：插件注册

import { ManifestLabelDesignerPlugin } from 'manifest-label-designer'

app.use(ManifestLabelDesignerPlugin)
// 全局注册名：ManifestLabelDesigner

方式三：默认导出

import ManifestLabelDesigner from 'manifest-label-designer'

设计器功能概览

界面布局

| 区域 | 说明 | |------|------| | 顶部工具栏 | 文件操作、编辑、对齐、吸附、画布尺寸、缩放、预览、打印、导出 | | 左侧面板 | 组件 / 图层 / 变量 / 数据源（Tab 切换） | | 中间画布 | 拖拽设计区，支持标尺、网格、参考线 | | 右侧属性面板 | 编辑选中组件属性 |

工具栏能力

| 功能 | 说明 | |------|------| | 新建 / 模板库 / 打开 / 导入 JSON / 保存 | 模板管理与 JSON 导入 | | 撤销 / 重做 | 历史记录（最多 50 步） | | 复制 / 粘贴 / 删除 | 支持 Ctrl+C / Ctrl+V / Delete | | 左 / 中 / 右对齐 | 相对画布对齐 | | 网格吸附 / 组件吸附 / 吸附开关 | 精确定位辅助 | | 画布尺寸 | 预设标签、热敏纸、票据、条码标签、A4/A5/A6 及自定义 mm 尺寸 | | 缩放 | 25%–800%，支持 Ctrl+滚轮、适合窗口（Ctrl+0）、实际尺寸（Ctrl+1） | | 预览 | 新窗口打开预览（需宿主应用提供 /preview-page 路由，见下方说明） | | 打印 | 弹出打印设置，调用 manifest-label-print | | Schema | 查看当前模板 JSON 结构 | | 导出 | JSON 配置 / PNG 图片 |

左侧面板 Tab

| Tab | 说明 | |-----|------| | 组件 | 拖拽或点击添加组件到画布 | | 图层 | 管理组件层级、可见性与锁定 | | 变量 | 定义 ${变量名} 模板变量，供文本等组件引用 | | 数据源 | 导入 Excel / JSON / 手动数据，用于设计时预览数据 |

快捷键

| 快捷键 | 功能 | |--------|------| | Ctrl+Z | 撤销 | | Ctrl+Y | 重做 | | Ctrl+C | 复制 | | Ctrl+V | 粘贴 | | Delete | 删除选中组件 | | Ctrl+S | 保存模板 | | Ctrl+A | 全选 | | Ctrl+0 | 适合窗口 | | Ctrl+1 | 实际尺寸（100%） | | Ctrl+滚轮 | 缩放画布 |

模板 JSON 格式

设计器产出的核心数据结构：

interface DesignExport {
  components: Component[]   // 组件列表
  canvasConfig: {
    width: number           // 画布宽（mm）
    height: number          // 画布高（mm）
    unit: 'mm' | 'px'
    zoom: number
    showGrid: boolean
    showRuler: boolean
    showGuides: boolean
  }
}

导入兼容格式

| 格式 | 示例 | |------|------| | 标准导出格式 | { components, canvasConfig } | | 旧版模板格式 | { name, data: Component[], canvasConfig? } | | 纯组件数组 | Component[]（使用默认 60×40mm 画布） |

导出 JSON 时附加元数据字段 _exportTime（ISO 时间戳），不影响 manifest-label-print 的 toPrintTemplate 解析。

模板持久化使用浏览器 localStorage（键名 design-templates，兼容旧键 design_templates）。

支持的组件类型

基础组件

| 类型 | 说明 | |------|------| | text | 文本 | | date | 日期 | | price | 价格 | | input | 输入框（含标签样式） | | image | 图片 | | horizontal-line | 横线 | | vertical-line | 竖线 | | rectangle | 矩形 | | circle | 圆形 |

高级组件

| 类型 | 说明 | |------|------| | barcode | 条形码（jsbarcode） | | qrcode | 二维码（qrcode） | | table | 表格（支持单元格合并、变量、条码/二维码单元格） |

组件坐标与尺寸单位为毫米（mm）。

CLodop 原生打印支持对照

设计器可设计全部上述组件，但 manifest-label-print 的 CLodop 原生模式仅支持部分类型；其余会自动降级为截图打印：

| 组件类型 | CLodop 原生模式 | |----------|----------------| | text、barcode、qrcode、horizontal-line、vertical-line、rectangle、image | 支持 | | table、input、date、price、circle | 不支持，降级截图 | | 任意组件 rotation !== 0 或 opacity !== 1 | 不支持，降级截图 |

打印集成

设计器通过 manifest-label-print 完成打印，流程如下：

1. 用户点击工具栏「打印」
2. 弹出打印设置对话框，选择引擎与模式
3. 调用 toPrintTemplate({ components, canvasConfig })
4. 调用 executePrint(template, options)

打印设置选项

| 选项 | 值 | 说明 | |------|-----|------| | 打印引擎 | browser | 浏览器截图打印，需画布 DOM | | 打印引擎 | clodop | CLodop 打印，需本机服务 | | 打印模式（仅 CLodop） | image | 截图模式 | | 打印模式（仅 CLodop） | native | 原生指令模式 |

用户选择会写入 localStorage（键名 manifest-print-engine / manifest-print-mode），下次打开自动恢复。

CLodop 环境

设计器内置 LodopFuncs.js（打包进组件资源），打印前自动调用：

ensureClodopReady({ scriptUrl: bundledLodopHelperUrl, timeoutMs: 8000 })

因此使用设计器打印时，无需在业务项目中手动放置 LodopFuncs.js；但仍需本机安装并启动 CLodop 服务。

若你在设计器外部单独使用 manifest-label-print，则需自行提供 helper 脚本路径。

在业务代码中打印设计器数据

import { toPrintTemplate, executePrint, ensureClodopReady } from 'manifest-label-print'

// designJson 来自设计器导出或后端存储
const template = toPrintTemplate(designJson)

const result = await executePrint(template, {
  engine: 'clodop',
  mode: 'native',
  target: document.querySelector('.canvas'), // native 降级时需要
  preview: true
})

导出与导入

导出

| 方式 | 说明 | |------|------| | 工具栏 → 导出 → 导出 JSON | 下载 { components, canvasConfig, _exportTime } | | 工具栏 → 导出 → 导出图片 | 使用 html2canvas 导出画布 PNG | | 工具栏 → Schema | 弹窗查看 / 复制 JSON |

导入

| 方式 | 说明 | |------|------| | 工具栏 → 导入 JSON 配置 | 选择 .json 文件加载 | | 工具栏 → 打开 / 保存 / 模板库 | 基于 localStorage 的模板管理 |

预览页说明

工具栏「预览」会打开 /preview-page?data=... 新窗口。该路由不在 npm 包内，需宿主应用自行实现（可参考 manifest-design 主项目）。

导出 API

本包公开导出：

// 组件
import ManifestLabelDesigner from 'manifest-label-designer'
import { ManifestLabelDesigner, ManifestLabelDesignerPlugin } from 'manifest-label-designer'

// 样式（必须在入口 import）
import 'manifest-label-designer/style.css'

| 导出 | 类型 | 说明 | |------|------|------| | ManifestLabelDesigner | DefineComponent | 设计器主组件 | | ManifestLabelDesignerPlugin | Plugin | Vue 插件，注册全局组件 | | manifest-label-designer/style.css | CSS | 设计器样式 |

类型定义见 index.d.ts。组件内部类型、Store、Composables 未对外导出。

常见问题

布局样式错乱

确认已引入两份 CSS，且容器有固定高度：

import 'ant-design-vue/dist/reset.css'
import 'manifest-label-designer/style.css'

.designer-page { height: 100vh; min-height: 620px; }

Pinia 报错

在 app.mount() 之前调用：

app.use(createPinia())

Ant Design 组件无样式

import 'ant-design-vue/dist/reset.css'
app.use(Antd)

CLodop 打印失败

1. 确认本机 CLodop 服务已启动
2. 含表格等复杂组件时，改用 CLodop 截图模式，或确保画布 DOM（.canvas）可见
3. 查看 manifest-label-print 常见问题

只想打印、不需要设计器

仅安装 manifest-label-print 即可。

Peer Dependencies

宿主项目需提供：

| 包 | 用途 | |----|------| | vue | 框架 | | pinia | 设计器状态管理 | | ant-design-vue | UI 组件 | | @ant-design/icons-vue | 图标 | | jsbarcode | 条形码渲染 | | qrcode | 二维码渲染 | | html2canvas | 导出图片 / 截图打印 | | manifest-label-print | 打印引擎 |

完整集成示例

本仓库提供最小可运行示例，展示设计器组件的完整接入方式：

源码：examples/verify-npm-package

git clone https://github.com/ymf-930/manifest-design.git
cd manifest-design

# 先构建两个 npm 包
npm run build:print-package
npm run build --prefix packages/manifest-label-designer

cd examples/verify-npm-package
npm install
npm run dev

示例项目关键文件：

| 文件 | 作用 | |------|------| | src/main.ts | 注册 Pinia、Ant Design Vue，引入样式 | | src/App.vue | 挂载 <ManifestLabelDesigner /> | | public/LodopFuncs.js | CLodop helper（设计器内置一份；此文件供独立调试 print 包时使用） |

最小 App.vue：

<script setup lang="ts">
import { ManifestLabelDesigner } from 'manifest-label-designer'
</script>

<template>
  <div class="designer-shell">
    <ManifestLabelDesigner />
  </div>
</template>

<style scoped>
.designer-shell {
  height: 100vh;
  min-height: 620px;
}
</style>

开发与发布

# 在 packages/manifest-label-designer
npm run build

npm version patch
npm publish --access public --registry https://registry.npmjs.org/

构建前需先构建依赖包：

# 在 monorepo 根目录
npm run build:print-package

License

MIT