@borurio-print/print-designer 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# Borurio Print Designer
+
+这是一个 Vue 3 标签打印设计器基础项目，同时支持独立 Web/iframe 页面和 npm 组件包两种使用方式。
+
+## 入口说明
+
+- `src/main.ts`：独立 Web/iframe 入口，创建 Vue 应用并挂载到 `#app`。
+- `src/index.ts`：npm 包入口，只导出组件、类型和语言包，不创建应用。
+- `src/PrintDesigner.vue`：设计器根组件，持有模板、网格和缩放状态。
+
+## 目录职责
+
+- `src/components`：可跨业务模块复用的基础组件，目前包含 Symbol 图标组件。
+- `src/core`：与界面无关的领域类型。
+- `src/locales`：中英文语言包及独立 Web 模式的 i18n 实例。
+- `src/views/print-designer/components`：打印设计器内部使用的界面组件。
+- `src/assets/iconfont`：Iconfont 平台生成的本地 Symbol 脚本，不建议手动修改。
+
+## 构建配置
+
+- `vite.config.ts`：生成可部署到服务器并通过 iframe 打开的 `dist`。
+- `vite.lib.config.ts`：从 `src/index.ts` 生成 npm 使用的 `dist-lib`。
+- `tsconfig.app.json`：检查 Web 应用源码，不输出文件。
+- `tsconfig.lib.json`：为 npm 包生成 TypeScript 声明文件。
+- `tsconfig.node.json`：检查 Vite 配置文件。
+
+## 常用命令
+
+- `pnpm dev`：启动本地 Web 开发服务。
+- `pnpm build:web`：构建 iframe/Web 版本并执行类型检查。
+- `pnpm build:lib`：构建 npm 版本并生成类型声明。
+- `pnpm build`：依次构建 npm 和 Web 两种版本。
+
+## npm 包使用
+
+当前包名为 `@borurio-print/print-designer`。业务项目需要使用 Vue 3，并安装组件声明的
+`vue`、`vue-i18n` 和 `element-plus` peer dependencies。
+
+```bash
+npm install @borurio-print/print-designer
+```
+
+如果业务项目尚未安装上述 peer dependencies，再按 npm 提示补充安装。
+
+在 Vue 页面中引入组件和独立样式文件：
+
+```vue
+<script setup lang="ts">
+import { PrintDesigner } from '@borurio-print/print-designer'
+import '@borurio-print/print-designer/style.css'
+</script>
+
+<template>
+  <div class="print-designer-page">
+    <PrintDesigner />
+  </div>
+</template>
+
+<style scoped>
+.print-designer-page {
+  width: 100%;
+  height: 100vh;
+}
+</style>
+```
+
+组件使用业务应用已经注册的 `vue-i18n` 实例。业务应用需要把组件语言包合并到
+对应语言中：
+
+```ts
+import { createI18n } from 'vue-i18n'
+import {
+  enUS as printDesignerEnUS,
+  zhCN as printDesignerZhCN,
+} from '@borurio-print/print-designer'
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'zh-CN',
+  messages: {
+    'zh-CN': printDesignerZhCN,
+    'en-US': printDesignerEnUS,
+  },
+})
+
+app.use(i18n)
+```
+
+如果业务应用已经存在语言包，可以使用 `mergeLocaleMessage` 合并，避免覆盖原有文案：
+
+```ts
+i18n.global.mergeLocaleMessage('zh-CN', printDesignerZhCN)
+i18n.global.mergeLocaleMessage('en-US', printDesignerEnUS)
+```
+
+## npm 发布
+
+首次发布前，需要确认当前 npm 账号拥有 `@borurio-print` 组织作用域的发布权限。先登录并检查
+即将进入安装包的文件：
+
+```bash
+npm login
+pnpm build:lib
+npm pack --dry-run
+```
+
+确认内容无误后发布公开包：
+
+```bash
+pnpm publish --access public
+```
+
+同一个版本号不能重复发布；后续修改需要先更新 `package.json` 中的版本号。
+
+## 自动生成文件
+
+`src/auto-imports.d.ts` 和 `src/components.d.ts` 由自动按需引入插件生成；`pnpm-lock.yaml` 由 pnpm 生成。这些文件不应手动添加说明或修改内容。

package/dist-lib/PrintDesigner.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist-lib/assets/iconfont/iconfont.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/IconFont.vue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * name 对应 Iconfont Symbol 的 id，例如 icon-wenzi。
+ * size 同时控制 SVG 的宽和高；title 存在时图标会作为可访问图片暴露。
+ */
+type __VLS_Props = {
+    name: string;
+    size?: number | string;
+    title?: string;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    size: number | string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist-lib/core/componentRegistry.d.ts

@@ -0,0 +1,25 @@
+import type { DesignerElementType, ElementPropertyConfig, ElementPropertyKey } from './types';
+/**
+ * 一个左侧组件的完整能力声明。
+ * properties 的顺序同时决定右侧属性编辑器的展示顺序，因此每个组件都能
+ * 在一个位置明确配置“它允许用户进行哪些操作”。
+ */
+export interface ComponentDefinition {
+    field: DesignerElementType;
+    icon: string;
+    titleKey: string;
+    properties: readonly ElementPropertyConfig[];
+}
+/**
+ * 设计器组件注册表。
+ *
+ * - 文字开放内容、字号、加粗和旋转。
+ * - 二维码、条形码开放内容、宽度、高度和旋转。
+ * - 边框开放宽高、线宽和旋转；横线、竖线只开放各自长度方向与线宽。
+ * - 序号和时间暂时保留空属性数组，维持原有入口但不提前引入未完成逻辑。
+ */
+export declare const componentItems: readonly ComponentDefinition[];
+/** 根据元素类型取得其属性能力，供根组件和右侧面板共用。 */
+export declare function getComponentDefinition(field: DesignerElementType): ComponentDefinition | undefined;
+/** 获取指定元素某个属性的约束，供输入组件和拖拽计算共用。 */
+export declare function getElementPropertyConfig(field: DesignerElementType, property: ElementPropertyKey): ElementPropertyConfig | undefined;

package/dist-lib/core/dynamicText.d.ts

@@ -0,0 +1,21 @@
+import type { DesignerElement, TextStyleDesignerElement } from './types';
+/** 打印阶段解析动态文字所需的批次上下文。 */
+export interface DynamicTextContext {
+    /** 当前数据在数组中的零基下标。 */
+    index: number;
+    /** 本次打印数据数组的总长度。 */
+    total: number;
+    /** 整个打印批次共用的时间，避免多页之间出现秒数差异。 */
+    printTime: Date;
+}
+/** 使用稳定格式保存和打印日期，避免浏览器语言环境改变输出顺序。 */
+export declare function formatDesignerDate(value: Date, includeTime?: boolean): string;
+/** 保留明确的日期时间格式化入口，供已有打印调用方继续使用。 */
+export declare function formatDesignerDateTime(value: Date): string;
+/** 集中判断文字类元素，供测量、SVG 渲染和缩放逻辑共同使用。 */
+export declare function isTextStyleElement(element: DesignerElement): element is TextStyleDesignerElement;
+/**
+ * 把设计元素解析成最终打印文本。
+ * 调用方应对同一批次复用同一个 printTime，确保“实时打印时间”完全一致。
+ */
+export declare function resolveDesignerText(element: TextStyleDesignerElement, context: DynamicTextContext): string;

package/dist-lib/core/elementInteraction.d.ts

@@ -0,0 +1,31 @@
+import type { DesignerElement, ElementTransformPatch, ResizeHandle } from './types';
+export interface SvgPoint {
+    x: number;
+    y: number;
+}
+interface ElementGeometrySnapshot {
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    rotation: number;
+    fontSizePt?: number;
+}
+/** 将响应式元素复制为一次交互期间不再变化的初始快照。 */
+export declare function createGeometrySnapshot(element: DesignerElement): ElementGeometrySnapshot;
+/**
+ * 把浏览器客户区坐标转换为 SVG viewBox 坐标。
+ * viewBox 使用毫米，所以该结果天然就是毫米，不需要手动除以画布缩放比例。
+ */
+export declare function clientPointToSvgPoint(svg: SVGSVGElement, clientX: number, clientY: number): SvgPoint | null;
+/**
+ * 计算元素移动结果，并按旋转后的真实外接边界限制在标签内部。
+ */
+export declare function calculateMovePatch(start: ElementGeometrySnapshot, startPointer: SvgPoint, currentPointer: SvgPoint, canvasWidthMm: number, canvasHeightMm: number): ElementTransformPatch;
+/**
+ * 按元素自身旋转后的横轴和纵轴计算缩放。
+ * 这比直接使用屏幕 dx/dy 更重要：元素旋转 90° 后，“右侧控制点”仍应沿
+ * 元素自己的右侧方向改变宽度，而不是沿屏幕水平方向错误拉伸。
+ */
+export declare function calculateResizePatch(element: DesignerElement, start: ElementGeometrySnapshot, handle: ResizeHandle, startPointer: SvgPoint, currentPointer: SvgPoint, canvasWidthMm: number, canvasHeightMm: number): ElementTransformPatch | null;
+export {};

package/dist-lib/core/pdfGenerator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 将已完成动态字段解析的逐页 SVG 生成一个 PDF Blob。
+ * 每个 SVG 对应一个物理页面，页面尺寸严格使用模板设置中的毫米值。
+ */
+export declare function generateTemplatePdf(pageSvgs: SVGSVGElement[], widthMm: number, heightMm: number): Promise<Blob>;

package/dist-lib/core/types.d.ts

@@ -0,0 +1,117 @@
+/** 标签的物理尺寸，统一使用毫米，避免业务数据和屏幕像素混用。 */
+export interface TemplateSize {
+    widthMm: number;
+    heightMm: number;
+}
+/** 当前标签模板的基础信息。 */
+export interface TemplateInfo extends TemplateSize {
+    name: string;
+}
+/**
+ * 设计器支持的组件类型。
+ *
+ * 这里保留尚未实现编辑能力的组件类型，是为了让左侧组件注册表始终使用
+ * 稳定的业务标识；后续实现方框、线条等组件时不需要修改已有模板字段。
+ */
+export type DesignerElementType = 'text' | 'rectangle' | 'horizontalLine' | 'verticalLine' | 'qrcode' | 'barcode' | 'serialNumber' | 'pageNumber' | 'time';
+/** 右侧属性面板中可独立组合的属性编辑器标识。 */
+export type ElementPropertyKey = 'content' | 'width' | 'height' | 'fontSize' | 'fontWeight' | 'strokeWidth' | 'rotation' | 'timeMode' | 'includeTime' | 'fixedTime';
+/**
+ * 单个属性编辑器的能力与数值约束。
+ * 数值范围跟随组件类型配置，输入框和 SVG 控制点共用，避免两处规则不一致。
+ */
+export interface ElementPropertyConfig {
+    key: ElementPropertyKey;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    /** 属性是否适用于元素当前状态，例如固定时间只在“固定”模式下展示。 */
+    visibleWhen?: (element: DesignerElement) => boolean;
+}
+/**
+ * 所有可编辑元素共用的布局数据。
+ * 坐标和尺寸统一使用毫米，rotation 统一使用角度，避免保存屏幕像素后
+ * 在浏览器打印、PDF 和不同 DPI 打印机之间产生尺寸偏差。
+ */
+export interface BaseDesignerElement {
+    id: string;
+    type: 'text' | 'rectangle' | 'horizontalLine' | 'verticalLine' | 'qrcode' | 'barcode' | 'serialNumber' | 'pageNumber' | 'time';
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    rotation: number;
+    zIndex: number;
+}
+/** 普通文字元素独有的排版属性。 */
+export interface TextDesignerElement extends BaseDesignerElement {
+    type: 'text';
+    content: string;
+    fontSizePt: number;
+    fontWeight: 400 | 700;
+}
+/** 带有文字排版能力的动态字段基础结构。 */
+export interface DynamicTextBaseDesignerElement extends BaseDesignerElement {
+    type: 'serialNumber' | 'pageNumber' | 'time';
+    fontSizePt: number;
+    fontWeight: 400 | 700;
+}
+/** 序号在打印阶段根据零基数组下标生成从 1 开始的显示值。 */
+export interface SerialNumberDesignerElement extends DynamicTextBaseDesignerElement {
+    type: 'serialNumber';
+}
+/** 页码在打印阶段根据数组下标和总长度生成“当前页/总页数”。 */
+export interface PageNumberDesignerElement extends DynamicTextBaseDesignerElement {
+    type: 'pageNumber';
+}
+export type TimeMode = 'realtime' | 'fixed';
+/** 时间可在打印时实时生成，也可保存用户选择的固定日期时间。 */
+export interface TimeDesignerElement extends DynamicTextBaseDesignerElement {
+    type: 'time';
+    timeMode: TimeMode;
+    includeTime: boolean;
+    fixedTime: string;
+}
+/** 所有可按文字方式测量、渲染和缩放的元素。 */
+export type TextStyleDesignerElement = TextDesignerElement | SerialNumberDesignerElement | PageNumberDesignerElement | TimeDesignerElement;
+/** 二维码首期只保存内容；纠错等级等高级选项可继续独立注册为属性。 */
+export interface QrcodeDesignerElement extends BaseDesignerElement {
+    type: 'qrcode';
+    content: string;
+}
+/** 条形码首期固定使用通用的 CODE128 编码。 */
+export interface BarcodeDesignerElement extends BaseDesignerElement {
+    type: 'barcode';
+    content: string;
+}
+/** 无填充边框元素，strokeWidthMm 表示实际打印线宽。 */
+export interface RectangleDesignerElement extends BaseDesignerElement {
+    type: 'rectangle';
+    strokeWidthMm: number;
+}
+/**
+ * 横线和竖线共用数据结构。
+ * 横线使用 widthMm 表示长度，竖线使用 heightMm 表示长度；另一个尺寸等于线宽。
+ */
+export interface LineDesignerElement extends BaseDesignerElement {
+    type: 'horizontalLine' | 'verticalLine';
+    strokeWidthMm: number;
+}
+/** 当前已经具备创建、属性编辑和 SVG 渲染能力的元素集合。 */
+export type DesignerElement = TextDesignerElement | RectangleDesignerElement | LineDesignerElement | QrcodeDesignerElement | BarcodeDesignerElement | SerialNumberDesignerElement | PageNumberDesignerElement | TimeDesignerElement;
+/** 独立属性编辑器使用的统一值类型。 */
+export type ElementPropertyValue = string | number | boolean;
+/** SVG 选区八个缩放控制点的稳定标识。 */
+export type ResizeHandle = 'topLeft' | 'top' | 'topRight' | 'right' | 'bottomRight' | 'bottom' | 'bottomLeft' | 'left';
+/**
+ * 拖动或缩放过程中允许画布回写的布局字段。
+ * fontSizePt 只会在文字按比例缩放时出现，其他元素仍只更新毫米几何数据。
+ */
+export interface ElementTransformPatch {
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    fontSizePt?: number;
+}