vg-print 1.0.414 → 1.0.415

package/README.en.md

@@ -1,36 +1,497 @@
-# vue-plugin-hiprint-demo
 
-#### Description
-vg-print代码
+An out-of-the-box print designer component library (Vue 3). Currently focused on the single component `FullDesigner`, while exposing underlying `hiprint` capabilities and client direct connection (`hiwebSocket`) configuration, facilitating rapid integration of template design, preview, browser printing, PDF/image export, and direct printing functions.
 
-#### Software Architecture
-Software architecture description
+You can install and experience the features directly. Features are constantly being improved, please update in time. Feedback and suggestions are welcome.
+No domain restrictions, available offline. Provides one-on-one technical support.
+Search `vg-print` on npm.
+Contact me: QQ 984239686 or use the WeChat group on the homepage to solve problems.
 
-#### Installation
+## Silent Printing Client Tool Installer
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+![Silent Printing Client Tool](https://gitee.com/gao111/electron-vg-print/raw/master/electron-hiprint.png)
 
-#### Instructions
+More info and download:
+```text
+https://gitee.com/gao111/electron-vg-print
+```
+Client tool download:
+```text
+https://download.csdn.net/download/github_38400706/92538739
+```
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+## Features
 
-#### Contribution
+- Full-featured page component `FullDesigner`, ready to use, no need to assemble sub-components
+- Supports preview, browser printing, PDF/image export, direct printing (client required)
+- Configure `hiwebSocket` `host`, `token` and auto-connection via props
+- Exposes instance methods: preview, print, export, connection control, etc., for external calls
+- Integrates and exports `hiprint` for advanced customization at the template object level
 
-1.  Fork the repository
-2.  Create Feat_xxx branch
-3.  Commit your code
-4.  Create Pull Request
+## Installation
 
+```bash
+npm i vg-print
+```
 
-#### Gitee Feature
+## Header Component
 
-1.  You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md
-2.  Gitee blog [blog.gitee.com](https://blog.gitee.com)
-3.  Explore open source project [https://gitee.com/explore](https://gitee.com/explore)
-4.  The most valuable open source project [GVP](https://gitee.com/gvp)
-5.  The manual of Gitee [https://gitee.com/help](https://gitee.com/help)
-6.  The most popular members  [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
+- Used for the top area of the page, with built-in common operation buttons and printer settings; supports customization via `props` and `slots`.
+- Embedded in `FullDesigner` by default; can also be used separately.
+
+### Props
+
+- `logoHtml: string` Custom HTML fragment for the left Logo area
+- `title: string` Left title text
+- `printCount: number` Number of copies, default `1` (supports `v-model:printCount`)
+- `printerName: string` Currently selected printer name (supports `v-model:printerName`)
+- `printerList: Array<{ name: string; label: string }>` Printer list
+- `waitShowPrinter: boolean` Show loading state for "Browser Print" button
+- `languages: Array<{ label: string; value: string }>` Language switch dropdown options
+
+### Events (Emits)
+
+- `preview` Open preview
+- `print-view` Browser print
+- `to-pdf` Export PDF
+- `to-image` Export Image
+- `print` Direct print (client required)
+- `clear-paper` Clear (with secondary confirmation)
+- `save` Save (primary key of split button)
+- `edit-template` Open "Edit Template Data" dialog
+- `edit-data` Open "Edit Print Data" dialog
+- `lang-change` Language switch (value is language code: `cn`, `en`, `de`, `es`, `fr`, `it`, `ja`, `ru`, `cn_tw`)
+- `feedback` Feedback/Help
+
+### Slots
+
+- `headerLeft` Left area (default: logo + title)
+- `headerCenter` Middle custom area (default empty)
+- `headerRight` Right operation area (default: printer and a group of buttons)
+
+### Important Note on Styles
+
+If you find page styles missing during external calls, please import the print style.
+Copy `node_modules/@vg-print/hiprint/dist/css/print-lock.css` to your development resource directory (e.g., `public` directory in Vue).
+If your site is `https://www.abcd.com/index.html`, ensure `https://www.abcd.com/print-lock.css` is accessible.
+Add `print-lock.css` to your project's `index.html` with `media="print"`.
+
+```html
+<link rel="stylesheet" type="text/css" media="print" href="/print-lock.css" />
+```
+
+### Usage Example: With FullDesigner
+
+```vue
+<template>
+  <FullDesigner
+    ref="designer"
+    :initial-template="tpl"
+    :initial-print-data="rows"
+    default-lang="cn"
+    :hi-host="host"
+    :hi-token="token"
+    :hi-auto-connect="true"
+    @save="onSave"
+  >
+    <!-- Top area (Header built-in; can be customized via slot) -->
+    <template #headerLeft>
+      <div style="display:flex;align-items:center;color:#fff;">
+        <img src="/logo.svg" style="height:24px;margin-right:8px;" />
+        <span>Custom Title</span>
+      </div>
+    </template>
+    <template #headerCenter>
+      <el-tag type="success">Middle Custom Area</el-tag>
+    </template>
+    <!-- No need to provide headerRight if keeping default buttons; provide if replacing completely -->
+    <template #headerRight>
+      <el-button size="small" @click="designer.value.preView()">Preview</el-button>
+      <el-button size="small" @click="designer.value.printView()">Browser Print</el-button>
+      <el-button type="primary" size="small" @click="designer.value.toPdf()">Export PDF</el-button>
+      <el-button size="small" @click="designer.value.toImage()">Export Image</el-button>
+      <el-button size="small" @click="designer.value.print()">Direct Print</el-button>
+      <el-button type="warning" size="small" @click="onClear()">Clear</el-button>
+      <el-button type="success" size="small" @click="onSaveDirect()">Save</el-button>
+    </template>
+  </FullDesigner>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const designer = ref(null)
+const host = ref('http://127.0.0.1:17521')
+const token = ref('')
+const tpl = { panels: [ /* ... */ ] }
+const rows = [{ title: 'Pathology Report', name: 'DongDong' }]
+const onSave = ({ template, data }) => { /* Save to backend */ }
+const onClear = () => { /* Clear data/elements */ }
+const onSaveDirect = () => designer.value?.save()
+</script>
+```
+
+### Usage Example: Header Alone
+
+```vue
+<template>
+  <Header
+    v-model:printCount="count"
+    v-model:printerName="printer"
+    :printerList="printers"
+    :waitShowPrinter="loading"
+    :languages="langs"
+    title="Print Designer"
+    @preview="onPreview"
+    @print-view="onPrintView"
+    @to-pdf="onToPdf"
+    @to-image="onToImage"
+    @print="onPrint"
+    @clear-paper="onClear"
+    @save="onSave"
+    @lang-change="onLangChange"
+    @feedback="onFeedback"
+  />
+</template>
+```
+
+### Responsive Strategy (Built-in)
+
+- Automatically hides the middle area and secondary buttons when the window shrinks, keeping key operations like "Save" and "Feedback"; left logo/title are unaffected.
+- Breakpoints:
+  - `≤1600px` Hide middle area
+  - `≤1400px` Hide copies, printer selection, preview, browser print, export PDF, export image
+  - `≤1200px` Hide direct print, language switch
+  - `≤992px` Hide clear
+  - `≤768px` Hide title text (keep Logo)
+
+> Tip: If you need fully custom buttons, provide the `headerRight` slot.
+
+---
+
+## Preview Component
+
+- Independent preview modal component, supports rendering template HTML, selecting printer, exporting PDF/image, direct printing, etc.
+- Can be used separately or with `FullDesigner`.
+
+### Props
+
+- `printTemplate: object` Template object (`hiprint.PrintTemplate` or return value of `createTemplate`)
+- `printData: object | array` Print data
+- `printerList: Array<{ name: string; label: string }>` Printer list
+- `selectedPrinter: string` Selected printer name
+- `showPdf: boolean` Show "Export PDF" button, default `true`
+- `showImg: boolean` Show "Export Image" button, default `true`
+- `showPrint2: boolean` Show "Direct Print" button, default `true`
+- `modalShow: boolean` Modal visibility (supports `v-model:modalShow`)
+- `width: string | number` Modal width (default `'80%'`)
+- `defaultLang: string` Component i18n language (used when Standalone); supports `cn`, `en`, `de`, `es`, `fr`, `it`, `ja`, `ru`, `cn_tw`; default `cn`
+
+### Events (Emits)
+
+- `update:modalShow` Two-way binding for modal visibility
+- `update:selectedPrinter` Selected printer change
+- `close` Close modal
+
+### Exposed Methods (defineExpose)
+
+- `show(template, data, width?)` Show and render preview content; can pass template/data and width
+- `hideModal()` Close modal
+- `init()` Initialize (internal use)
+- `getTarget()` Get preview container DOM
+
+### Usage Example (Standalone)
+
+```vue
+<template>
+  <el-button @click="openPreview">Show Preview</el-button>
+  <Preview
+    ref="previewRef"
+    v-model:modalShow="visible"
+    default-lang="cn"
+    :printerList="printers"
+    :selectedPrinter="printer"
+    @update:selectedPrinter="printer = $event"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { Preview, createTemplate } from 'vg-print'
+import 'vg-print/style.css'
+
+const previewRef = ref(null)
+const visible = ref(false)
+const printers = ref([{ name: 'HP_001', label: 'HP Printer' }])
+const printer = ref('')
+
+const tmplJson = { panels: [ /* ... */ ] }
+const data = { title: 'Report', name: 'DongDong' }
+
+const openPreview = () => {
+  const tpl = createTemplate(tmplJson) // Or pass hiprint.PrintTemplate
+  previewRef.value.show(tpl, data, '80%')
+}
+</script>
+```
+
+### Usage Example (With FullDesigner)
+
+```vue
+<template>
+  <FullDesigner ref="designer" default-lang="cn" />
+  <Preview ref="previewRef" v-model:modalShow="visible" />
+  <el-button @click="designer.value.preView()">Use FullDesigner's Preview</el-button>
+  <el-button @click="showCustomPreview">Use Preview Component</el-button>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const designer = ref(null)
+const previewRef = ref(null)
+const visible = ref(false)
+
+const showCustomPreview = () => {
+  const tpl = designer.value.getTemplate()      // Assuming method exposed
+  const data = designer.value.getPrintData()    // Assuming method exposed
+  previewRef.value.show(tpl, data, '80%')
+}
+</script>
+```
+
+### Note
+
+- Please import `vg-print/style.css` when using the component library.
+- `Preview` automatically renders content based on `printTemplate` and `printData`.
+- If using `Preview` separately without plugin installation, set `default-lang`.
+
+Style Import:
+
+```javascript
+// Global style
+import 'vg-print/style.css'
+
+// Print lock style (Recommended)
+// In `index.html`:
+// <link rel="stylesheet" type="text/css" media="print" href="/css/print-lock.css" />
+```
+
+Environment: Vue 3, Node >= 18.18.
+
+## Quick Start
+
+```javascript
+// main.ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import vgPrint from 'vg-print'
+import 'vg-print/style.css'
+
+createApp(App).use(vgPrint).mount('#app')
+```
+
+```vue
+<template>
+  <FullDesigner
+    ref="designer"
+    :hi-host="'http://127.0.0.1:17521'"
+    :hi-token="'your-token'"
+    :hi-auto-connect="true"
+  />
+  <!-- Buttons... -->
+</template>
+<script setup>
+// ... Same as above
+</script>
+```
+
+## API (FullDesigner)
+
+### Props
+
+- `hi-host: string` Client service address
+- `hi-token: string` Client auth token
+- `hi-auto-connect: boolean` Auto connect to client
+- `initial-template: object` Initial template JSON
+- `initial-print-data: object | array` Initial print data
+- `default-lang: string` Default language
+
+### Methods
+
+- `preView()` Open preview
+- `printView()` Browser print
+- `print()` Direct print
+- `toPdf()` Export PDF
+- `toPdf2()` Export PDF with paper layout
+- `toImage()` Export Image
+- `toImage2()` Export Image with paper layout
+- `toImage()` Export Image
+- `setHiwebSocket(host, token, cb)` Set client address/token (Respects autoConnect state)
+- `setHost(host, token, cb)` Set client address/token and connect immediately (Standard API)
+- `connect(cb)` Connect to client
+- `disconnect()` Disconnect
+- `disAutoConnect()` Disable auto-connect
+
+### Events
+
+- `save` Save template and data
+
+## Advanced Usage (hiprint)
+
+```javascript
+import { hiprint, defaultElementTypeProvider } from 'vg-print'
+// Global Config
+hiprint.setConfig({ showAdsorbLine: true, showPosition: true, showSizeBox: true })
+// Register Plugins
+hiprint.register({ authKey: '', plugins: [] })
+// Init
+hiprint.init({ 
+  host: 'http://localhost:17521',
+  token: '',
+  lang: 'en'
+})
+// Create Template
+const tpl = new hiprint.PrintTemplate({ template: {} })
+// Design
+tpl.design('#hiprint-printTemplate', { grid: true })
+// Print
+tpl.print({ name: 'Example' })
+```
+
+### Auth Key and Default Watermark
+
+- **Design State**: No default watermark.
+- **Runtime State**:
+  - No Auth: Default watermark or "Trial Version" suffix.
+  - With Auth: No default watermark.
+
+Register:
+```javascript
+hiprint.register({ authKey: 'YOUR_KEY' });
+```
+
+## Lightweight Runtime API
+
+Use when you only need "Template + Data" capabilities without the designer UI.
+
+```javascript
+import { createTemplate, printBrowser, exportPdf, exportImage } from 'vg-print'
+
+const tpl = createTemplate(tmplJson)
+printBrowser(tpl, printData)
+exportPdf(tpl, printData, 'filename')
+```
+
+### Export PDF / Image
+
+`exportPdf` / `exportImage` are lightweight wrappers around the template instance methods:
+
+- `exportPdf(tpl, data, filename, options)` → `tpl.toPdf(data, filename, options)`
+- `exportPdf2(tpl, data, filename, options)` → `tpl.toPdf2(data, filename, options)`
+
+- `exportImage(tpl, data, options)` → `tpl.toImage(data, options)`
+- `exportImage2(tpl, data, options)` → `tpl.toImage2(data, options)`
+
+#### Export PDF
+
+**Mode A: Normal export (follow template paging)**
+
+```js
+// No paperWidth/paperHeight: export pages exactly like preview pagination
+exportPdf(tpl, printData, 'report', {
+  onProgress: (cur, total) => console.log('toPdf', Math.floor((cur / total) * 100))
+})
+```
+
+**Mode B: Layout export (tile small labels into a big paper, e.g. A4)**
+
+```js
+exportPdf(tpl, printData, 'labels', {
+  paperWidth: 210,     // mm
+  paperHeight: 297,    // mm
+  perPage: 6,          // put 6 labels per sheet (rest goes to next sheet)
+  leftOffset: -1,      // -1: center; >=0: left margin (mm)
+  topOffset: -1,       // -1: center; >=0: top margin (mm)
+  scale: 2,            // clarity vs performance (pixelRatio also supported)
+  onProgress: (cur, total) => console.log('toPdf', Math.floor((cur / total) * 100))
+})
+```
+
+**Layout rules**
+
+- With `paperWidth/paperHeight` (or `usePaperType: true`):
+  - `perPage > 0`: fixed “N per sheet”
+  - `perPage = 0` or omitted: auto-fill “as many as can fit per sheet”
+- Without paper size:
+  - Export follows template pagination; `perPage` does not apply in this mode.
+
+#### Export Image
+
+**Mode A: Normal export (follow template paging)**
+
+```js
+// Recommended: one image per page (avoid very long images)
+await exportImage(tpl, printData, {
+  isDownload: true,
+  name: 'page',
+  splitPages: true,
+  type: 'image/png',   // QR/barcode recommended
+  pixelRatio: 2,
+  toType: 'blob'
+})
+```
+
+**Optional: merge into long images**
+
+```js
+// limit: N pages per output image; limit<=0 merges all pages into one (can be huge)
+await exportImage(tpl, printData, {
+  isDownload: true,
+  name: 'merged',
+  limit: 6,
+  type: 'image/jpeg',
+  pixelRatio: 2,
+  quality: 0.85
+})
+```
+
+**Mode B: Layout export (tile small labels into a big paper, e.g. A4)**
+
+```js
+// In layout mode, `limit` works like “labels per sheet”
+await exportImage(tpl, printData, {
+  paperWidth: 210,
+  paperHeight: 297,
+  limit: 6,
+  isDownload: true,
+  name: 'A4-layout',
+  splitPages: true,
+  type: 'image/png',
+  pixelRatio: 2
+})
+```
+
+**Layout rules**
+
+- With `paperWidth/paperHeight`:
+  - `limit > 0`: fixed “N per sheet”
+  - `limit = 0` or omitted: auto-fill “as many as can fit per sheet”
+- Without paper size:
+  - `splitPages: true`: one image per page (recommended)
+  - `splitPages: false` + `limit > 0`: merge N pages per long image
+  - `splitPages: false` + `limit <= 0`: merge all pages into one long image (not recommended)
+
+#### Common options
+
+- `pixelRatio` / `scale`: render scale (higher = clearer but slower)
+- `forcePng` (PDF): force PNG for QR/barcode
+- `maxCanvasPixels`: cap per-page canvas pixels to reduce freezes
+- `debugPerf`: log per-page render time to console
+
+### Notes
+
+- Inject `print-lock.css` in `index.html`.
+- Direct printing needs a client.
+- SSR compatible.
+
+## Full Example
+
+(See the code block in the Chinese section or above)