@borurio-print/print-designer 1.0.6 → 1.0.8

package/README.md

@@ -104,27 +104,159 @@ i18n.global.mergeLocaleMessage('zh-cn', printDesignerZhCN)
 i18n.global.mergeLocaleMessage('en', printDesignerEnUS)
 ```
 
-## npm 发布
-
-首次发布前，需要确认当前 npm 账号拥有 `@borurio-print` 组织作用域的发布权限。先登录并检查
-即将进入安装包的文件：
-
-```bash
-npm login
-pnpm build:lib
-npm pack --dry-run
-```
-
-确认内容无误后发布公开包：
-
-```bash
-pnpm publish --access public
-```
-
-同一个版本号不能重复发布；后续修改需要先更新 `package.json` 中的版本号。
+## npm 发布
+
+包名和 npm registry 已在 `package.json` 中配置：
+
+- 包名：`@borurio-print/print-designer`
+- registry：`https://registry.npmjs.org/`
+- 公开范围：`public`
+- 发布前钩子：`prepublishOnly` 会自动执行 `pnpm build:lib`
+
+### 1. 检查本地和线上版本
+
+进入项目目录，确认当前工作区状态以及本地版本：
+
+```bash
+git status
+node -p "require('./package.json').version"
+```
+
+查询 npm 当前已经发布的版本：
+
+```bash
+npm view @borurio-print/print-designer version --registry=https://registry.npmjs.org/
+```
+
+同一个版本不能重复发布。如果本地版本与线上版本相同，先升级版本号：
+
+```bash
+pnpm version patch --no-git-tag-version
+```
+
+根据实际变更范围，也可以把 `patch` 换成 `minor` 或 `major`。如果上一次发布只是因为
+登录失效或权限不足而失败，并且线上还没有该版本，不要再次升级版本号。
+
+### 2. 检查 npm 登录和发布权限
+
+先检查当前 npm 登录状态：
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+如果返回 `E401 Unauthorized`，重新登录：
+
+```bash
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+```
+
+登录成功后，再检查当前账号是否拥有该包的发布权限：
+
+```bash
+npm owner ls @borurio-print/print-designer --registry=https://registry.npmjs.org/
+```
+
+当前账号必须出现在 owner 列表中。如果不在，需要使用已有 owner 账号登录，或者由已有
+owner 为当前账号授予权限。
+
+### 3. 执行发布前构建和检查
+
+安装锁文件对应的依赖，并完整构建 Web 与 npm 两种产物：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+检查 npm 包最终会包含哪些文件：
+
+```bash
+npm pack --dry-run
+```
+
+至少应确认以下文件存在：
+
+- `dist-lib/index.js`
+- `dist-lib/index.d.ts`
+- `dist-lib/style.css`
+- `dist-lib/PrintDesigner.vue.d.ts`
+- `dist-lib/core/types.d.ts`
+- `dist-lib/core/theme.d.ts`
+- `package.json`
+
+如果仓库跟踪 `dist-lib`，发布前应检查并提交最新构建产物。不要在存在来源不明的工作区
+改动时直接执行批量提交。
+
+### 4. 正式发布
+
+确认版本、账号、权限和打包内容无误后执行：
+
+```bash
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+发布时会再次触发 `prepublishOnly`，自动执行 `pnpm build:lib`。终端出现下面格式的输出才
+表示上传成功：
+
+```text
++ @borurio-print/print-designer@1.0.7
+```
+
+`resolveComponent is imported ... but never used` 和 chunk size 属于构建警告，不等于发布
+失败；应以命令退出码和最后的 npm 发布结果为准。
+
+### 5. 发布后验证
+
+npm 新版本可能需要短暂处理时间。查询线上版本：
+
+```bash
+npm view @borurio-print/print-designer version --registry=https://registry.npmjs.org/
+```
+
+在临时目录或业务系统中安装明确版本进行验证：
+
+```bash
+npm install @borurio-print/print-designer@1.0.7
+```
+
+确认线上版本和业务系统验证正常后，再按团队 Git 流程提交版本变更并创建对应版本标签。
+
+### 常见发布错误
+
+#### `E401 Unauthorized`
+
+当前 npm 登录已失效。重新执行：
+
+```bash
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+#### scoped 包发布时报 `E404 Not Found - PUT`
+
+对于已经存在的 scoped 包，这通常表示当前账号没有发布权限，或者认证信息已经失效，并不
+代表包真的不存在。依次检查：
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+npm owner ls @borurio-print/print-designer --registry=https://registry.npmjs.org/
+npm view @borurio-print/print-designer version --registry=https://registry.npmjs.org/
+```
+
+如果 `npm whoami` 返回 `E401`，重新登录后再发布。如果账号不在 owner 列表中，需要切换
+到有权限的账号或申请权限。权限问题解决前不要继续递增版本号。
+
+#### 版本已经存在
+
+npm 不允许覆盖已经发布的相同版本。确认线上已经存在当前版本后，执行：
+
+```bash
+pnpm version patch --no-git-tag-version
+```
+
+重新构建、检查并发布新版本。
 
 ## 自动生成文件
 
-`src/auto-imports.d.ts` 和 `src/components.d.ts` 由自动按需引入插件生成；`pnpm-lock.yaml` 由 pnpm 生成。这些文件不应手动添加说明或修改内容。
-
-pnpm publish --access public
+`src/auto-imports.d.ts` 和 `src/components.d.ts` 由自动按需引入插件生成；`pnpm-lock.yaml` 由 pnpm 生成。这些文件不应手动添加说明或修改内容。

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

@@ -1,17 +1,19 @@
-import type { BusinessFieldGroup, PrintResult, PrintTemplate } from '@/core/types';
+import type { BusinessFieldGroup, PrintRequest, PrintResult, PrintTemplate, PrintDesignerTheme } from '@/core/types';
 type __VLS_Props = {
     /**
      * 由业务系统提供的可打印字段目录。
      * 设计器只保存字段路径和用户最终选择的展示类型，不感知 WMS、OMS 业务含义。
      */
     fieldGroups?: readonly BusinessFieldGroup[];
+    /** 当前设计器实例使用的主色主题。 */
+    theme?: PrintDesignerTheme;
 };
 declare function getTemplate(): PrintTemplate;
 declare function loadTemplate(template: PrintTemplate): void;
-/** 供业务系统获取 PDF Blob，后续可直接传给本地打印控件。 */
-declare function generatePdf(data: unknown): Promise<Blob>;
-/** 供业务系统直接在浏览器中打开数据打印预览。 */
-declare function previewPdf(data: unknown): Promise<void>;
+/** 供业务系统生成 PDF，结果统一通过 print-result 事件通知。 */
+declare function generatePdf(request: PrintRequest): Promise<void>;
+/** 供业务系统打开 PDF 预览，结果统一通过 print-result 事件通知。 */
+declare function previewPdf(request: PrintRequest): Promise<void>;
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     getTemplate: typeof getTemplate;
     loadTemplate: typeof loadTemplate;

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

@@ -0,0 +1,6 @@
+import { type ComputedRef, type CSSProperties, type InjectionKey } from 'vue';
+import type { PrintDesignerTheme } from './types';
+export type PrintDesignerThemeStyle = CSSProperties & Record<`--bpd-${string}`, string>;
+export declare const printDesignerThemeStyleKey: InjectionKey<ComputedRef<PrintDesignerThemeStyle>>;
+export declare function createPrintDesignerThemeStyle(theme?: PrintDesignerTheme): PrintDesignerThemeStyle;
+export declare function usePrintDesignerThemeStyle(): ComputedRef<PrintDesignerThemeStyle>;

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

@@ -36,13 +36,25 @@ export interface PrintRenderPage {
     data?: Record<string, unknown>;
     tableData: Record<string, TableRuntimeData>;
 }
-/** 设计器完成 PDF 预览或内部测试打印后通知业务系统的结果。 */
+/** 业务系统发起一次 PDF 生成或预览的请求。 */
+export interface PrintRequest<T = unknown> {
+    /** 由调用方生成，用于将异步结果与请求一一对应。 */
+    requestId: string;
+    data: T;
+    /** 只有显式需要获取 PDF 文件时才设置为 true。 */
+    returnBlob?: boolean;
+}
+/** 设计器完成 PDF 生成或预览后通过 print-result 通知的结果。 */
 export interface PrintResult {
-    success: boolean;
-    action: 'preview' | 'testPrint';
-    pageCount: number;
-    blob?: Blob;
-    error?: unknown;
+    requestId: string;
+    result: 'success' | 'failed';
+    /** 成功固定为 ok，失败时为可展示的错误信息。 */
+    message: string;
+    data?: {
+        pageCount: number;
+        /** 只在请求中指定 returnBlob: true 时返回。 */
+        blob?: Blob;
+    };
 }
 /** 业务字段目前允许在标签中使用的三种展示方式。 */
 export type FieldElementType = 'text' | 'textBox' | 'qrcode' | 'barcode';
@@ -62,6 +74,17 @@ export interface BusinessFieldGroup {
     label: string;
     fields: readonly BusinessField[];
 }
+/** 业务系统可为每个设计器实例单独配置的主色主题。 */
+export interface PrintDesignerTheme {
+    /** 主色；未传入衍生色时，设计器会自动生成对应的明暗色阶。 */
+    primaryColor?: string;
+    primaryLight3?: string;
+    primaryLight5?: string;
+    primaryLight7?: string;
+    primaryLight8?: string;
+    primaryLight9?: string;
+    primaryDark2?: string;
+}
 /**
  * 设计器支持的组件类型。
  *