vg-print-vue2 1.0.601 → 1.0.602

package/README.md

@@ -217,18 +217,38 @@ hiprint.register({
 
 ## Header 顶部工具栏组件
 
-- 用于页面一级头部区域，内置常用操作按钮与打印机设置；支持通过 `props` 与 `slots` 定制。
+- 用于页面一级头部区域，内置常用操作按钮；支持通过 `props` 与 `slots` 定制。
 - 默认嵌入在 `FullDesigner` 中；也可单独使用。
 
 ### 属性（Props）
 
 - `logoHtml: string` 左侧 Logo 区自定义 HTML 片段
 - `title: string` 左侧标题文本
-- `waitShowPrinter: boolean` 显示“浏览器打印”按钮的加载状态
 - `languages: Array<{ label: string; value: string }>` 语言切换下拉选项
 
+所有默认按钮均支持独立的 Boolean 显示配置，默认 `true`，名称和行为与 Vue 3 一致。单独使用 Header 时以属性传入；使用 FullDesigner 时将同名配置放入 `show-option`。
+
+| 配置 | 控制内容 |
+| --- | --- |
+| `showNewTemplate` | 新建 |
+| `showPreview` | 预览 |
+| `showPrintView` | 浏览器打印 |
+| `showPdf` | 导出 PDF；还需已注册 PDF 插件 |
+| `showImage` | 导出图片 |
+| `showClientGenerate` | 客户端生成 |
+| `showSave` | 整个保存按钮组，包括下拉菜单 |
+| `showSaveMenu` | 保存下拉入口及菜单，保留保存主按钮 |
+| `showEditTemplate` | 下拉菜单中的编辑模板数据 |
+| `showEditData` | 下拉菜单中的编辑打印数据 |
+| `showExportTemplate` | 下拉菜单中的导出模板 |
+| `showImportTemplate` | 下拉菜单中的导入模板 |
+| `showFeedback` | 反馈 |
+
+四个下拉菜单项全部关闭时自动隐藏下拉入口。显示配置控制默认按钮，使用方在插槽内创建的按钮由使用方自行控制。
+
 ### 事件（Emits）
 
+- `new-template` 新建模板；FullDesigner 确认名称后删除当前所有旧面板，创建唯一的空白 A4 面板（`index: 0`），清空打印数据和业务 ID；保存时只包含新模板的面板
 - `preview` 打开预览
 - `print-view` 浏览器打印
 - `to-pdf` 导出 PDF
@@ -244,7 +264,7 @@ hiprint.register({
 
 - `headerLeft` 左侧区域（默认：logo + 标题）
 - `headerCenter` 中间自定义区域（默认空）
-- `headerRight` 右侧操作区（默认：打印机与一组按钮）
+- `headerRight` 右侧操作区（默认：新建、预览等常用操作按钮）；提供该插槽时替换全部默认按钮，包括“新建”
 
 ### 如果发现外部调用安装过程页面样式有丢失情况， 可以引入打印样式重要提醒需要复制
 
@@ -344,7 +364,61 @@ export default {
   - `≤992px` 隐藏清空
   - `≤768px` 隐藏标题文本（保留 Logo）
 
-> 提示：如需完全自定义按钮，请提供 `headerRight` 插槽实现自己的按钮布局。
+> 提示：如需完全自定义按钮，请提供 `headerRight` 插槽实现自己的按钮布局，默认“新建”按钮也会被替换。`headerCenter` 只用于中间自定义内容。
+
+单独控制按钮显示：
+
+```vue
+<template>
+  <FullDesigner :show-option="showOption" />
+</template>
+
+<script>
+import { FullDesigner } from 'vg-print-vue2'
+
+export default {
+  components: { FullDesigner },
+  data() {
+    return {
+      showOption: {
+        showNewTemplate: false,
+        showPreview: true,
+        showPrintView: false,
+        showPdf: false,
+        showImage: true,
+        showClientGenerate: false,
+        showSave: true,
+        showSaveMenu: true,
+        showEditTemplate: true,
+        showEditData: false,
+        showExportTemplate: true,
+        showImportTemplate: false,
+        showFeedback: false
+      }
+    }
+  }
+}
+</script>
+```
+
+支持运行时修改。Vue 2 中新增尚未声明的配置键时，请使用 `this.$set(this.showOption, 'showPreview', false)`，或整体替换 `showOption` 对象，确保响应式更新。
+
+单独使用 Header 时传入同名属性：
+
+```vue
+<Header :show-new-template="false" :show-preview="false" :show-save-menu="false" />
+```
+
+自定义 `headerRight` 后，如需调用设计器自带的新建弹窗，可通过 `this.$refs.designer.openNewTemplateDialog()` 调用：
+
+```vue
+<FullDesigner ref="designer">
+  <template #headerRight>
+    <button type="button" @click="$refs.designer.openNewTemplateDialog()">自定义新建</button>
+    <button type="button" @click="$refs.designer.preView()">自定义预览</button>
+  </template>
+</FullDesigner>
+```
 
 ***
 
@@ -556,6 +630,7 @@ import 'vg-print-vue2/style.css'
 
 ### 属性（Props，含描述）
 
+- `template-id: string | number | null` 独立业务模板 ID，默认 `null`；编辑时传自己的 ID，支持 `:template-id.sync`，不读取模板 JSON 的 ID，不使用引擎内部 ID
 - `hi-host: string` 客户端服务地址；示例 `http://127.0.0.1:17521`，用于直连打印
 - `hi-token: string` 客户端鉴权令牌；与客户端配置一致时方可直连打印
 - `hi-auto-connect: boolean` 是否自动连接客户端；默认 `true`，为 `false` 时需手动调用 `connect()`
@@ -578,9 +653,11 @@ import 'vg-print-vue2/style.css'
 - `theme-list: Array<string | object>` 主题列表（用于顶部主题切换菜单），默认：`light/dark/emerald/corporate/bumblebee/retro/cyberpunk/valentine`
 - `show-option: object` 区域显示控制（默认全部显示）：
   - `showHeader: boolean` 是否显示顶部 Header，默认 `true`
+  - `showNewTemplate: boolean` 是否显示默认“新建”按钮，默认 `true`；自定义 `headerRight` 时默认按钮组整体被替换
   - `showToolbar: boolean` 是否显示二级工具栏 Toolbar，默认 `true`
   - `showFooter: boolean` 是否显示底部 Footer，默认 `true`
   - `showTemplateLibrary: boolean` 是否显示左侧模板库页签及内容，默认 `true`；设为 `false` 时仅保留组件库，不影响模板加载和保存功能；动态关闭时自动切回组件库
+- `show-option` 同时支持上方 Header 配置表中的所有按钮显示项：`showPreview`、`showPrintView`、`showPdf`、`showImage`、`showClientGenerate`、`showSave`、`showSaveMenu`、`showEditTemplate`、`showEditData`、`showExportTemplate`、`showImportTemplate`、`showFeedback`；均默认 `true`，支持动态修改
 - `footer-text: string` 底部默认文案（仅在未提供 `#footer` 插槽时展示）
 
 以上属性支持运行时动态修改；组件内部已监听并应用。
@@ -648,6 +725,7 @@ import 'vg-print-vue2/style.css'
 
 ### 方法（通过组件 ref 调用，含描述）
 
+- `setTemplateId(id: string | number | null)` 设置业务模板 ID；首次保存后可回填后端 ID，传 `null` 表示新增；同步触发 `update:templateId`
 - `preView()` 打开预览弹窗；将当前模板与数据渲染为预览 HTML
 - `printView()` 浏览器打印；不依赖客户端，调起系统打印对话框
 - `print()` 直接打印；需客户端已连接，按当前选定打印机输出
@@ -677,7 +755,7 @@ export default {
     /*  保存方法
       template,   // 模板 JSON
       data,       // 当前打印数据（对象或数组）
-      templateId  // 模板标识（若存在）
+      templateId  // 使用方传入的业务模板 ID；新增为 null
     */
     onSave({ template, data, templateId }) {
       // 调用接口持久化到数据库
@@ -696,6 +774,55 @@ export default {
 </script>
 ```
 
+### 自定义业务模板 ID
+
+新增时使用 `null`，编辑时填写后端记录 ID。保存事件中的 `templateId` 与该值一致，首次保存成功后将后端 ID 回填，后续保存即可按编辑处理。
+
+```vue
+<template>
+  <FullDesigner
+    :template-id.sync="businessId"
+    :initial-template="tpl"
+    @save="onSave"
+  />
+</template>
+
+<script>
+import { FullDesigner } from 'vg-print-vue2'
+
+export default {
+  components: { FullDesigner },
+  data() {
+    return {
+      businessId: null, // 新增为 null；编辑时设为你的记录 ID，例如 'report-123'
+      tpl: { panels: [/* 后端模板的面板内容 */] }
+    }
+  },
+  methods: {
+    async onSave({ template, data, templateId }) {
+      // templateId 原样返回当前业务 ID，支持字符串、数字（包括 0）；新增返回 null。
+      // const record = await api.saveTemplate({ template, data, templateId })
+      // this.businessId = record.templateId // 首次新增成功后回填后端 ID
+    }
+  }
+}
+</script>
+```
+
+业务 ID 通过独立的 `template-id` 参数传入，模板 JSON 只承载布局。保存返回 `{ templateId, template, data }`，业务 ID 不写入 `template`。初始化示例：
+
+```js
+// :template-id="businessId" :initial-template="tpl"
+const businessId = 'report-123'
+const tpl = { panels: [/* 你的面板 */] }
+// 动态编辑其他记录
+this.$refs.designer.applyTemplateItem({
+  templateId: record.id,
+  template: record.template,
+  testData: record.data
+})
+```
+
 ### 语言与国际化
 
 - 通过 `default-lang` 设置初始语言（`cn` 默认为中文）；内部会同步 `vue-i18n` 与 `hiprint` 的语言。