@agile-team/mach-report 2.1.0 → 2.3.0

package/dist/vue/index.d.ts

@@ -204,6 +204,7 @@ declare type __VLS_Props = {
         query: string;
         matchIndex: number;
         matchCount: number;
+        searching?: boolean;
     };
     thumbsVisible: boolean;
 };
@@ -324,7 +325,7 @@ export declare function createFetchRequest(options?: FetchRequestOptions): HostR
  * 本地渲染适配器：模板 + 数据 → core 分页引擎 → RenderPlan。
  * 用于本地预览、离线场景和单测。
  */
-export declare function createLocalFetcher(entries: Record<string, LocalTemplateEntry>): PlanFetcher;
+export declare function createLocalFetcher(entries: Record<string, LocalTemplateEntry> | ReportRegistry): PlanFetcher;
 
 declare type DatasetRows = Record<string, Record<string, unknown>[]>;
 
@@ -360,6 +361,10 @@ declare function gotoPage(n: number): void;
 declare interface GridCell {
     text?: string;
     rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
     children?: PlanComponent[];
     colSpan?: number;
     rowSpan?: number;
@@ -377,11 +382,20 @@ export declare type HostRequest = (config: {
 
 export declare function joinReportIds(reportId: ReportIdInput): string;
 
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+
 declare interface ListColumn {
     header: string;
     field: string;
     widthMm: number;
     style?: ComponentStyle;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle;
     /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -391,6 +405,10 @@ declare interface ListColumn {
 declare interface ListComponent {
     kind: "list";
     id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
     leftMm: number;
     topMm: number;
     widthMm: number;
@@ -402,6 +420,11 @@ declare interface ListComponent {
     paddingMm?: number;
     headerEveryPage?: boolean;
     headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -496,6 +519,9 @@ export declare interface MachReportDefaults {
     messages?: Partial<MachReportMessages>;
     /** 校验告警等内部日志通道（默认 console；静默传 { warn: () => {}, info: () => {} }） */
     logger?: MachReportLogger;
+    preview?: MachReportPreviewOptions;
+    /** Excel 出口配置，按字段继承；不配置使用导出器默认值。 */
+    xlsx?: XlsxRenderOptions;
 }
 
 export declare class MachReportError extends Error {
@@ -576,6 +602,8 @@ export declare interface MachReportMessages {
     reset: string;
     /** 必填缺失提示（{label} 占位） */
     paramRequired: string;
+    /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
+    searching?: string;
 }
 
 /**
@@ -919,6 +947,14 @@ fetcher: PlanFetcher | null;
     };
 });
 
+/** 预览按需调优；默认已经启用正文/缩略图虚拟化及可取消的分片搜索。 */
+export declare interface MachReportPreviewOptions {
+    /** 视口前后额外保留的正文页数，默认 1，归一化到 0~10 的整数。 */
+    overscanPages?: number;
+    /** 搜索输入防抖毫秒，默认 200，归一化到 0~2000。 */
+    searchDebounceMs?: number;
+}
+
 /** 只读快照，由组件的同一套状态驱动；无需通过事件另建状态。 */
 export declare interface MachReportState {
     readonly loading: boolean;
@@ -1003,6 +1039,7 @@ declare interface PlanComponent {
     richParagraphs?: RichParagraph[];
     imageData?: string;
     grid?: PlanGrid;
+    table?: PlanTableFragment;
     style?: ComponentStyle;
     meta?: Record<string, unknown>;
     /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
@@ -1027,6 +1064,8 @@ export declare class PlanLoadError extends Error {
 }
 
 declare interface PlanPage {
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
     pageWidthMm: number;
     pageHeightMm: number;
     marginTopMm?: number;
@@ -1036,6 +1075,19 @@ declare interface PlanPage {
     components: PlanComponent[];
 }
 
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+}
+
 declare function print_2(): Promise<void>;
 
 declare interface PrintHtmlResult {
@@ -1067,11 +1119,12 @@ declare interface RenderPlan {
 }
 
 declare interface ReportDefinition {
-    template: ReportTemplate;
+    /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
+    template: ReportTemplate | ReportTemplateLoader;
     /** 静态数据；load 存在时优先使用 load 的结果。 */
     datasets?: DatasetRows;
     load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
-    /** 覆盖模板参数定义，未提供时自动使用 template.params。 */
+    /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
     params?: ReportParamDef[];
     pagination?: PaginateOptions;
 }
@@ -1134,6 +1187,8 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
+
 export declare const ReportToolbar: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 print: () => any;
 export: (format: "html" | "png" | "pdf" | "xlsx" | "word") => any;
@@ -1165,6 +1220,8 @@ export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExpo
     theme: MachReportTheme;
     messages: MachReportMessages;
     logger: MachReportLogger;
+    preview: Required<MachReportPreviewOptions>;
+    xlsx: XlsxRenderOptions;
 };
 
 declare interface RichParagraph {
@@ -1207,6 +1264,8 @@ declare type TemplateComponent = PlanComponent | ListComponent;
 declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
     marginTopMm?: number;
     marginBottomMm?: number;
     marginLeftMm?: number;
@@ -1248,16 +1307,11 @@ export declare function useMachReport(): MachReportHandle;
 /** 组件内部读取当前生效配置层（未提供时返回 null → 走内置缺省） */
 export declare function useMachReportConfig(): ConfigRef;
 
-/**
- * 页级视口虚拟化（DOM 后端）。
- *
- * 坐标口径（与 transform: scale 缩放配合）：
- * - 页高/间距/占位均在"自然坐标系"（未缩放 px）维护
- * - 视口滚动量与视口高换算回自然系（除以 zoom）后再进 computePageWindow
- */
+/** 页级虚拟化；页几何按计划引用缓存，滚动仅更新坐标，不遍历整个计划。 */
 export declare function usePageWindow(plan: Ref<RenderPlan | null>, zoom: Ref<number>, options?: {
     pxPerMm?: number;
     gapPx?: number | Ref<number>;
+    overscan?: number | Ref<number>;
 }): {
     contentSize: ComputedRef<    {
     w: number;
@@ -1269,10 +1323,14 @@ export declare function usePageWindow(plan: Ref<RenderPlan | null>, zoom: Ref<nu
     index: number;
     }[]>;
     makeScrollHandler: (currentPage: Ref<number>, pageCount: Ref<number>) => (vp: HTMLElement) => void;
-    refreshViewport(vp: HTMLElement | null): void;
+    refreshViewport: (vp: HTMLElement | null) => void;
+    pageOffsetPx: (index: number) => number;
+    destroy: () => void;
 };
 
 export declare function usePrintExport(plan: Ref<RenderPlan | null>, hooks: {
+    /** 按导出开始时的配置快照处理，避免输出过程中跟随路由配置变化。 */
+    getXlsxOptions?: () => XlsxRenderOptions;
     getPdfExporter: () => PdfExporter;
     onError: (message: string, code?: string) => void;
     onWarning?: (message: string) => void;
@@ -1304,8 +1362,8 @@ export declare function useReportPreview(): MachReportController | null;
 
 /**
  * 缩放状态（transform: scale 方案）：
- * - fit 模式：按视口宽自适应（clamp 0.3~1）
- * - raw 模式：固定百分比
+ * - fit 模式：按视口宽自适应，超宽表也能完整缩入视口
+ * - raw 模式：固定百分比（30%~300%）
  * transform 而非 CSS zoom：标准属性、跨浏览器、零重排。
  */
 export declare function useZoom(getFitInputs: () => {
@@ -1313,9 +1371,28 @@ export declare function useZoom(getFitInputs: () => {
     pageWidthPx: number;
 } | null): {
     zoom: Ref<number, number>;
-    zoomMode: Ref<"fit" | "raw", "fit" | "raw">;
+    zoomMode: Ref<"raw" | "fit", "raw" | "fit">;
     applyFitZoom: () => void;
     setZoom: (mode: "fit" | number) => void;
 };
 
+/**
+ * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
+ * - 网格组件 → 真表格：列宽（mm→Excel 宽度）、行高（mm→pt）、colSpan/rowSpan 合并、
+ *   加粗/对齐/底色/字号直译（resolveGridLayout 复用单真相源几何）
+ * - 文本组件 → 合并标题行（顺序流式输出，保字号/加粗/对齐；非像素级定位，
+ *   目标是"财务能直接用的对账表"而非复刻版面）
+ * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
+ */
+declare interface XlsxRenderOptions {
+    /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
+    sheetName?: (sheetIndex: number) => string;
+    /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
+    sheetMode?: "auto" | "pages" | "continuous";
+    /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
+    valueMode?: "text" | "raw";
+    /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
+    paperSize?: "auto" | "a3" | "a4" | "a5";
+}
+
 export { }

package/dist/vue-async.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("./plugin-Bl00j_CP.cjs");function i(){return Promise.resolve().then(()=>require("./ReportPreview-VHAIfsz1.cjs")).then(e=>e.ReportPreview$1)}const t={install(e,o={}){r.machReportPlugin.install(e,o)}};exports.MachReportPreview=r.MachReportPreview;exports.default=t;exports.machReportAsyncPlugin=t;exports.preloadMachReport=i;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("./plugin-MSh_OhoW.cjs");function i(){return Promise.resolve().then(()=>require("./ReportPreview-CLENbOCL.cjs")).then(e=>e.ReportPreview$1)}const t={install(e,o={}){r.machReportPlugin.install(e,o)}};exports.MachReportPreview=r.MachReportPreview;exports.default=t;exports.machReportAsyncPlugin=t;exports.preloadMachReport=i;

package/dist/vue-async.js

@@ -1,7 +1,7 @@
-import { m as o } from "./plugin-DVScnZ4C.js";
-import { M as l } from "./plugin-DVScnZ4C.js";
+import { m as o } from "./plugin-uoO9VA6O.js";
+import { M as l } from "./plugin-uoO9VA6O.js";
 function a() {
-  return import("./ReportPreview-Dwdsyk9b.js").then((t) => t.s);
+  return import("./ReportPreview-CwTGfyTq.js").then((t) => t.s);
 }
 const n = {
   install(t, r = {}) {

package/dist/vue.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@agile-team/mach-report"),e=require("./ReportPreview-VHAIfsz1.cjs"),c=require("./plugin-Bl00j_CP.cjs"),s=require("vue");function p(r){const o=u.createReportSource(r),i=async n=>{if(n.reportIds.length===0)throw new e.PlanLoadError("缺少报表 ID");for(const t of n.reportIds)if(!Object.prototype.hasOwnProperty.call(r,t)||!r[t])throw new e.PlanLoadError(`本地模板 ${t} 不存在`);return o(n)};return i.getParamDefs=o.getParamDefs,i}const l=Object.freeze({loading:!1,hasPlan:!1,pageCount:0,currentPage:1,exporting:null,printing:!1,canExport:!1,canPrint:!1,error:null,pdfFont:Object.freeze({status:"unchecked",fontUrl:""})});function P(){const r=s.shallowRef(null),o=()=>r.value?.state??l,i=Object.freeze({get loading(){return o().loading},get hasPlan(){return o().hasPlan},get pageCount(){return o().pageCount},get currentPage(){return o().currentPage},get exporting(){return o().exporting},get printing(){return o().printing},get canExport(){return o().canExport},get canPrint(){return o().canPrint},get error(){return o().error},get pdfFont(){return o().pdfFont}});function n(){if(!r.value)throw new e.MachReportError("config","报表预览尚未挂载，请在 ready 后调用控制器");return r.value}return{ref(t){const a=t;r.value=a&&typeof a.reload=="function"&&typeof a.print=="function"&&typeof a.exportAs=="function"&&typeof a.openPdfWindow=="function"&&typeof a.gotoPage=="function"&&typeof a.setParams=="function"?a:null},ready:s.computed(()=>r.value!==null),state:i,async checkPdfFont(){const t=n();return t.checkPdfFont?t.checkPdfFont():{status:"unverified",fontUrl:"",message:"旧自定义控制器未提供字体检查，请由宿主确认字体配置"}},async reload(){await n().reload()},async print(){await n().print()},async exportAs(t){await n().exportAs(t)},openPdfWindow(){n().openPdfWindow()},gotoPage(t){n().gotoPage(t)},async setParams(t,a){await n().setParams(t,a)}}}function f(){return s.inject(c.MACH_REPORT_CONTROLLER_KEY,null)}exports.DEFAULT_MESSAGES=e.DEFAULT_MESSAGES;exports.DEFAULT_THEME=e.DEFAULT_THEME;exports.MachReportError=e.MachReportError;exports.PlanLoadError=e.PlanLoadError;exports.ReportParamPanel=e.ReportParamPanel;exports.ReportPreview=e.ReportPreview;exports.ReportToolbar=e.ReportToolbar;exports.SILENT_LOGGER=e.SILENT_LOGGER;exports.buildPrintDocument=e.buildPrintDocument;exports.buildWordHtml=e.buildWordHtml;exports.createDefaultPdfExporter=e.createDefaultPdfExporter;exports.createFetchRequest=e.createFetchRequest;exports.defineMachReportConfig=e.defineMachReportConfig;exports.defineMachReportPreset=e.defineMachReportPreset;exports.joinReportIds=e.joinReportIds;exports.normalizeReportIds=e.normalizeReportIds;exports.printPlans=e.printPlans;exports.provideMachReportConfig=e.provideMachReportConfig;exports.resolveConfig=e.resolveConfig;exports.themeToCssVars=e.themeToCssVars;exports.toErrorDetail=e.toErrorDetail;exports.useMachReportConfig=e.useMachReportConfig;exports.usePageWindow=e.usePageWindow;exports.usePrintExport=e.usePrintExport;exports.useZoom=e.useZoom;exports.MACH_REPORT_CONFIG_KEY=c.MACH_REPORT_CONFIG_KEY;exports.MACH_REPORT_CONTROLLER_KEY=c.MACH_REPORT_CONTROLLER_KEY;exports.MACH_REPORT_FETCHER_KEY=c.MACH_REPORT_FETCHER_KEY;exports.MACH_REPORT_PDF_EXPORTER_KEY=c.MACH_REPORT_PDF_EXPORTER_KEY;exports.MachReportPreview=c.MachReportPreview;exports.machReportPlugin=c.machReportPlugin;exports.createLocalFetcher=p;exports.useMachReport=P;exports.useReportPreview=f;Object.keys(u).forEach(r=>{r!=="default"&&!Object.prototype.hasOwnProperty.call(exports,r)&&Object.defineProperty(exports,r,{enumerable:!0,get:()=>u[r]})});
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@agile-team/mach-report"),e=require("./ReportPreview-CLENbOCL.cjs"),c=require("./plugin-MSh_OhoW.cjs"),s=require("vue");function p(r){const o=u.createReportSource(r),i=async n=>{if(n.reportIds.length===0)throw new e.PlanLoadError("缺少报表 ID");for(const t of n.reportIds)if(!Object.prototype.hasOwnProperty.call(r,t)||!r[t])throw new e.PlanLoadError(`本地模板 ${t} 不存在`);return o(n)};return i.getParamDefs=o.getParamDefs,i}const l=Object.freeze({loading:!1,hasPlan:!1,pageCount:0,currentPage:1,exporting:null,printing:!1,canExport:!1,canPrint:!1,error:null,pdfFont:Object.freeze({status:"unchecked",fontUrl:""})});function P(){const r=s.shallowRef(null),o=()=>r.value?.state??l,i=Object.freeze({get loading(){return o().loading},get hasPlan(){return o().hasPlan},get pageCount(){return o().pageCount},get currentPage(){return o().currentPage},get exporting(){return o().exporting},get printing(){return o().printing},get canExport(){return o().canExport},get canPrint(){return o().canPrint},get error(){return o().error},get pdfFont(){return o().pdfFont}});function n(){if(!r.value)throw new e.MachReportError("config","报表预览尚未挂载，请在 ready 后调用控制器");return r.value}return{ref(t){const a=t;r.value=a&&typeof a.reload=="function"&&typeof a.print=="function"&&typeof a.exportAs=="function"&&typeof a.openPdfWindow=="function"&&typeof a.gotoPage=="function"&&typeof a.setParams=="function"?a:null},ready:s.computed(()=>r.value!==null),state:i,async checkPdfFont(){const t=n();return t.checkPdfFont?t.checkPdfFont():{status:"unverified",fontUrl:"",message:"旧自定义控制器未提供字体检查，请由宿主确认字体配置"}},async reload(){await n().reload()},async print(){await n().print()},async exportAs(t){await n().exportAs(t)},openPdfWindow(){n().openPdfWindow()},gotoPage(t){n().gotoPage(t)},async setParams(t,a){await n().setParams(t,a)}}}function f(){return s.inject(c.MACH_REPORT_CONTROLLER_KEY,null)}exports.DEFAULT_MESSAGES=e.DEFAULT_MESSAGES;exports.DEFAULT_THEME=e.DEFAULT_THEME;exports.MachReportError=e.MachReportError;exports.PlanLoadError=e.PlanLoadError;exports.ReportParamPanel=e.ReportParamPanel;exports.ReportPreview=e.ReportPreview;exports.ReportToolbar=e.ReportToolbar;exports.SILENT_LOGGER=e.SILENT_LOGGER;exports.buildPrintDocument=e.buildPrintDocument;exports.buildWordHtml=e.buildWordHtml;exports.createDefaultPdfExporter=e.createDefaultPdfExporter;exports.createFetchRequest=e.createFetchRequest;exports.defineMachReportConfig=e.defineMachReportConfig;exports.defineMachReportPreset=e.defineMachReportPreset;exports.joinReportIds=e.joinReportIds;exports.normalizeReportIds=e.normalizeReportIds;exports.printPlans=e.printPlans;exports.provideMachReportConfig=e.provideMachReportConfig;exports.resolveConfig=e.resolveConfig;exports.themeToCssVars=e.themeToCssVars;exports.toErrorDetail=e.toErrorDetail;exports.useMachReportConfig=e.useMachReportConfig;exports.usePageWindow=e.usePageWindow;exports.usePrintExport=e.usePrintExport;exports.useZoom=e.useZoom;exports.MACH_REPORT_CONFIG_KEY=c.MACH_REPORT_CONFIG_KEY;exports.MACH_REPORT_CONTROLLER_KEY=c.MACH_REPORT_CONTROLLER_KEY;exports.MACH_REPORT_FETCHER_KEY=c.MACH_REPORT_FETCHER_KEY;exports.MACH_REPORT_PDF_EXPORTER_KEY=c.MACH_REPORT_PDF_EXPORTER_KEY;exports.MachReportPreview=c.MachReportPreview;exports.machReportPlugin=c.machReportPlugin;exports.createLocalFetcher=p;exports.useMachReport=P;exports.useReportPreview=f;Object.keys(u).forEach(r=>{r!=="default"&&!Object.prototype.hasOwnProperty.call(exports,r)&&Object.defineProperty(exports,r,{enumerable:!0,get:()=>u[r]})});

package/dist/vue.js

@@ -1,9 +1,9 @@
 import { createReportSource as c } from "@agile-team/mach-report";
 export * from "@agile-team/mach-report";
-import { P as s, M as i } from "./ReportPreview-Dwdsyk9b.js";
-import { D as M, a as T, R as x, b as O, c as F, S as v, d as A, e as D, f as b, g as L, h as S, i as j, j as H, n as I, p as k, k as W, r as Y, t as z, l as G, u as K, m as U, o as N, q } from "./ReportPreview-Dwdsyk9b.js";
-import { a as f } from "./plugin-DVScnZ4C.js";
-import { b as X, c as Z, d as $, M as B, m as J } from "./plugin-DVScnZ4C.js";
+import { P as s, M as i } from "./ReportPreview-CwTGfyTq.js";
+import { D as M, a as T, R as x, b as O, c as F, S as v, d as A, e as D, f as b, g as L, h as S, i as j, j as H, n as I, p as k, k as W, r as Y, t as z, l as G, u as K, m as U, o as N, q } from "./ReportPreview-CwTGfyTq.js";
+import { a as f } from "./plugin-uoO9VA6O.js";
+import { b as X, c as Z, d as $, M as B, m as J } from "./plugin-uoO9VA6O.js";
 import { shallowRef as u, computed as p, inject as l } from "vue";
 function m(n) {
   const t = c(n), a = async (r) => {