# m7_Print_Designer

**Repository Path**: jiangzeyu/m7_print_designer

## Basic Information

- **Project Name**: m7_Print_Designer
- **Description**: m7_Print_Designer
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# m7_print_designer · 通用打印设计器

面向 **Vue 3** 技术栈的可复用打印设计器组件 —— 单据、标签、报表、合同、回执等「**固定版式 + 精确套打**」场景都能用同一套方式设计（仓库内示例为加工单、质检单、采购订单、收货回单、采购合同）。

> **官网**：[m7-print-designer.m7wl.cn](https://m7-print-designer.m7wl.cn) · **开源仓库**：[Gitee](https://gitee.com/jiangzeyu/m7_print_designer) · **版权**：© 2026 [烟台梦起网络科技有限公司](https://m7wl.cn)

## 特性

- **拖拽式设计器**：组件面板 → 画布拖入，画布内自由拖动、8 向缩放、旋转、网格吸附、参考线对齐、撤销/重做
- **打印元素组件**：
  - 文本（支持 `{字段}` 数据绑定）
  - 图片（URL / 本地上传）
  - 二维码（qrcode）
  - 条码（jsbarcode：CODE128 / CODE39 / EAN13 / EAN8 / UPC / ITF14 / MSI / Codabar）
  - 公章（SVG 圆形章，公司名环绕 + 五角星 + 章文字）
  - 手写签名（Canvas 手写板，矢量笔迹存储）
  - 直线、矩形
  - 自定义表格（行列/单元格编辑）
  - 数据表格（绑定数据源数组，打印时自动分页）
- **精确打印**：模板用 **mm 坐标** 建模，打印时生成独立静态 HTML（`@page` 精确尺寸），画布预览与打印共用同一套渲染逻辑
- **模板序列化**：纯 JSON 模板，可存储/复用/后端保存

## 快速开始

```bash
npm install
npm run dev        # 演示页（5 类示例单据）
npm run build:lib  # 构建组件库产物（ES + UMD + d.ts）
```

## 在项目中使用

```ts
import { PrintDesigner, PrintPreview, printTemplate, printBatch, type Template } from 'm7_print_designer'

// 模板数据（可由后端保存/加载的 JSON）
const template: Template = { id, name, version, paper, elements, dataFields }

// 单据数据（打印时绑定 {字段} 占位、数据表格数据源）
const data = { orderNo: 'PO-001', supplier: 'xx公司', items: [...] }
```

```vue
<template>
  <PrintDesigner v-model="template" :data="data" :data-fields="fields" @save="save" @print="print" />
</template>
```

## 使用模式：预览页 + 设计器页

被其他系统引用时，拆成**两个页面**：

```
宿主系统（勾选数据 → 打印）
        │
        ▼
  PrintPreview（预览页）  ──配置模板──▶  PrintDesigner（设计器页）
   · 切换模板                             · 拖拽/缩放/改属性编排
   · 内嵌预览（模板 + 真实数据）           · 保存为不同模板
   · 打印
```

| 组件 | 定位 | 使用方 |
| --- | --- | --- |
| `PrintPreview` | 预览页：切换模板 + 内嵌预览 + 打印 | 业务用户（操作员/文员） |
| `PrintDesigner` | 设计器页：可视化编排模板 | 模板管理员 |

> **批量打印**：勾选多条单据用 `printBatch([{ template, data }, ...])` 合并为一次打印任务（每张单据从新页开始，要求同纸张尺寸）。

**预览页**：

```vue
<PrintPreview
  :template="currentTemplate"
  :templates="templateList"        <!-- 该单据类型下可切换的模板 -->
  :data="recordData"               <!-- 勾选单据的真实数据 -->
  @template-change="t => currentTemplate = t"
  @configure="openDesigner"        <!-- 跳到设计器页 -->
  @print="onPrint"                 <!-- 预览页内部已调 printTemplate -->
/>
```

**设计器页**：

```vue
<PrintDesigner v-model="currentTemplate" :data="recordData" @save="saveTemplate" />
```

`save` 回调拿到模板 JSON，宿主持久化后加入 `templates` 列表，即可实现「保存为不同模板」。完整可运行流程见 `src/App.vue`。

## Props / Events（PrintDesigner）

| Props | 类型 | 说明 |
| --- | --- | --- |
| `modelValue` | `Template` | 模板对象（v-model 双向绑定） |
| `data` | `Record<string, unknown>` | 单据数据，用于 `{字段}` 占位与数据表格 |
| `dataFields` | `DataField[]` | 可绑定字段清单（属性面板「插入字段」下拉） |
| `readonly` | `boolean` | 只读模式（隐藏编辑面板，仅预览） |

| Events | 说明 |
| --- | --- |
| `update:modelValue` | 模板变更 |
| `print` | 触发打印 |
| `save` | 点击「保存模板」，回调携带模板 JSON |

## Props / Events（PrintPreview）

| Props | 类型 | 说明 |
| --- | --- | --- |
| `template` | `Template` | 当前模板 |
| `templates` | `Template[]` | 可切换的模板列表 |
| `data` | `Record<string, unknown>` | 单据真实数据 |
| `dataFields` | `DataField[]` | 可绑定字段清单（可选） |

| Events | 说明 |
| --- | --- |
| `template-change` | 切换模板，回调新模板 |
| `configure` | 点击「配置模板」（宿主跳转到设计器页） |
| `print` | 点击「打印」（组件内部已调 `printTemplate`） |

## 模板 Schema（核心）

```ts
interface Template {
  id: string
  name: string
  version: string
  paper: PaperConfig        // 纸张尺寸 / 方向 / 页边距
  elements: PrintElement[]  // 元素列表（mm 坐标 + 各自属性）
  dataFields?: DataField[]  // 可绑定字段清单
}
```

元素基类：`{ id, type, x, y, width, height, rotation, opacity, visible, locked, zIndex }`，单位均为 **mm**。

## 数据绑定

- 文本 / 二维码 / 条码的内容支持 `{字段名}` 占位（支持 `a.b` 点路径），打印时用 `data` 解析。
- 数据表格通过 `dataSource` 指向 `data` 中的数组字段，按 `rowHeight` 自动计算每页行数并分页。

> 完整的数据源接入契约（字段字典 `DataField`、数据实例 `DataRecord`、`DataSource`、命名约定、后端供数方式）见 [`docs/data-source-spec.md`](docs/data-source-spec.md)。

## 授权与遥测

```ts
import { setupLicense } from 'm7_print_designer'

// 生产环境初始化时调用一次；开发 / 测试环境可不调用
setupLicense({ code: 'M7PD1.xxxxxxxx.yyyyyyyy' })
```

- 授权校验**完全离线**（内置公钥本地验签），**不发网络请求** —— 断网、内网、无法连接公网时照常工作。
- 未授权只在打印与预览输出铺倾斜重复水印，**不限制任何功能**；开发 / 测试环境（`localhost`、`*.local`、`*.test`）不加水印。
- **默认开启使用情况上报**：仅生产环境、每浏览器每月最多一次、未配置授权码也会上报；上报内容**不含用户信息与业务数据**。
- 关闭遥测：`setupLicense({ report: false })`。

详见官网 [授权与遥测](https://m7-print-designer.m7wl.cn/telemetry)。

## 维护者：授权码签发（离线）

私钥只保存在本机 `~/.m7pd/key.json`，不进 git、不上服务器。

**方式一：桌面工具（推荐）** —— 构建一次，之后双击即用

```bash
bash tools/license-tool/build.sh      # 或双击 tools/license-tool/build.bat
```

产物 `tools/license-tool/dist/m7pd-license-tool.exe`（约 6 MB，**私钥编译在 exe 内，运行时不需要任何外部文件**），双击打开签发界面；界面内还可查看 / 导出私钥、**更换密钥对**（应急，含公钥指纹核对），并导出 `pool.csv` / `pool.sql`。详见 [`tools/license-tool/README.md`](tools/license-tool/README.md)。

> ⚠️ 该 exe 内含私钥，**只放自己电脑、不要外发**（销售/代理/外包都不行）；`dist/` 已在 `.gitignore` 中排除。

**方式二：命令行**

```bash
node tools/license-cli.mjs keygen                                # 一次性生成密钥对
node tools/license-cli.mjs issue --customer ABC001 --days 365    # 单客户发码（打印到控制台）
node tools/license-cli.mjs issue --count 100 --start 1           # 批量发码 → pool.csv / pool.sql
node tools/license-cli.mjs verify <code>                         # 校验授权码
```

## 目录结构

```
src/designer/
├── index.ts              # 公共 API
├── types.ts              # 类型 / 模板 Schema
├── schema.ts             # 元素工厂 + 默认值
├── constants.ts          # 纸张尺寸 / mm↔px
├── data.ts               # 数据绑定解析
├── license.ts            # 授权校验（离线验签）+ 遥测 + 打印水印
├── render.ts             # 元素 → HTML（画布/打印共用）
├── print.ts              # 打印 HTML 生成 + 分页
├── seal.ts               # 公章 SVG 生成器
├── composables/          # 状态 / 历史 / 资源
├── components/           # 画布 / 面板 / 元素交互
├── PrintDesigner.vue     # 设计器页（根组件）
└── PrintPreview.vue      # 预览页（切换模板 / 内嵌预览 / 打印）

tools/
├── license-cli.mjs       # 离线发码工具（命令行）
└── license-tool/         # 授权码签发桌面工具（Go，构建为单文件 exe）
```

详细设计见 [`docs/architecture.md`](docs/architecture.md)。