@canvas-components/print-design 0.0.0-stage → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,1291 @@
+import { BarcodeFormat } from '@canvas-components/barcode';
+import { QrCodeLevel, QrCodeFormat, QrCodeMode, QrCodeContentTemplate, QrCodeContentFields } from '@canvas-components/qrcode';
+
+/** 设计器显示单位；文档和打印计算始终使用毫米。 */
+type PrintDesignUnit = "mm" | "cm" | "in" | "pt" | "px";
+/** 每个显示单位对应的毫米数；px 按 CSS 96 DPI 换算。 */
+declare const PRINT_DESIGN_UNIT_MM: Record<PrintDesignUnit, number>;
+/** 将毫米值转换为界面显示值。 */
+declare function toDisplayUnit(mm: number, unit?: PrintDesignUnit): number;
+/** 将界面输入值转换回毫米。 */
+declare function fromDisplayUnit(value: number, unit?: PrintDesignUnit): number;
+/** 格式化辅助线和测距标签。 */
+declare function formatDisplayUnit(mm: number, unit?: PrintDesignUnit): string;
+
+/** 打印设计透视表字段区域。 */
+type PrintPivotFieldArea = "filter" | "column" | "row" | "value";
+type PrintPivotAggregator = "sum" | "avg" | "count" | "distinctCount" | "rowCount" | "mergedRowCount" | "min" | "max";
+/** 可序列化的透视字段，路径沿用 ListTable 的 dataIndex 约定。 */
+interface PrintPivotField {
+    key: string;
+    title?: string;
+    /** 打印表格的表头文案；留空时沿用字段名称或自动汇总标题。 */
+    headerTitle?: string;
+    dataIndex?: string | (string | number)[];
+    defaultArea?: PrintPivotFieldArea;
+    indicator?: {
+        title?: string;
+        aggregator?: PrintPivotAggregator;
+        /** 值字段表头是否显示“求和项:”等汇总方式前缀。 */
+        showAggregatorPrefix?: boolean;
+    };
+}
+/** 四个区域各自保留字段顺序。 */
+interface PrintPivotFieldLayout {
+    filters: string[];
+    columns: string[];
+    rows: string[];
+    values: string[];
+}
+interface PrintPivotFilterState {
+    rows: Record<string, {
+        condition?: {
+            operator: "equals";
+            value?: unknown;
+        };
+    }>;
+    columns: Record<string, {
+        condition?: {
+            operator: "equals";
+            value?: unknown;
+        };
+    }>;
+    filters?: Record<string, {
+        condition?: {
+            operator: "equals";
+            value?: unknown;
+        };
+    }>;
+}
+/** 字段在行列筛选间互斥，值区域允许复用维度字段。 */
+declare function movePrintPivotField(layout: PrintPivotFieldLayout, fieldKey: string, area: PrintPivotFieldArea, index?: number, sourceArea?: PrintPivotFieldArea): PrintPivotFieldLayout;
+/** 从全部区域移除字段。 */
+declare function removePrintPivotField(layout: PrintPivotFieldLayout, fieldKey: string): PrintPivotFieldLayout;
+declare function findPrintPivotFieldArea(layout: PrintPivotFieldLayout, fieldKey: string): PrintPivotFieldArea | null;
+declare function printPivotFieldTitle(field: PrintPivotField): string;
+/** 获取字段对应的打印表头标题。 */
+declare function printPivotFieldHeaderTitle(field: PrintPivotField): string;
+declare function printPivotValueTitle(field: PrintPivotField): string;
+
+/** 设计文档当前支持的 schema 版本。 */
+declare const PRINT_DESIGN_SCHEMA_VERSION = 1;
+/** 元素共有的毫米坐标与编辑状态。 */
+interface PrintDesignElementBase {
+    id: string;
+    type: string;
+    name?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 超出纸张时拆分到后续页、整体移到下一页、裁切或以省略号结束。 */
+    overflowPolicy?: "split" | "nextPage" | "clip" | "ellipsis";
+    /** 拆分绘制时，原组件中被裁切的垂直范围。 */
+    overflowCrop?: {
+        offset: number;
+        fullHeight: number;
+    };
+    rotation?: number;
+    opacity?: number;
+    visible?: boolean;
+    /** 组件显隐方式；动态模式从数据字段读取布尔状态。 */
+    visibility?: {
+        mode: "static" | "binding";
+        path?: string;
+    };
+    locked?: boolean;
+    /** 基础组件字段绑定；静态值仍保留在原属性中，切换模式不会丢失。 */
+    dataConfig?: {
+        mode: "static" | "binding";
+        bindings?: Record<string, string>;
+    };
+    /** 从外到内的组合路径，组合成员共用稳定 id。 */
+    groupPath?: {
+        id: string;
+        name: string;
+    }[];
+}
+/** 文本元素。 */
+interface PrintDesignTextElement extends PrintDesignElementBase {
+    type: "text";
+    text: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string;
+    color?: string;
+    /** 文本框边界线，单位毫米；用于打印时核对排版区域。 */
+    borderColor?: string;
+    borderWidth?: number;
+    textAlign?: CanvasTextAlign | "justify" | "distributed";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineHeight?: number;
+    /** 下划线条数；0 表示不绘制。 */
+    underlineCount?: number;
+    underlineStyle?: "solid" | "dashed" | "dotted" | "wavy";
+    underlineColor?: string;
+    /** 下划线宽度与间距，单位毫米。 */
+    underlineWidth?: number;
+    underlineGap?: number;
+    /** 文本超出固定高度时的处理方式。 */
+    heightOverflow?: "clip" | "flow" | "ellipsis";
+    /** 按字数上限选择字号；超过所有区间时使用最大上限的字号。 */
+    fontSizeRules?: Array<{
+        maxChars: number;
+        fontSize: number;
+    }>;
+    /** 可选字体文件地址，与 fontFamily 配合加载。 */
+    fontSource?: string;
+    /** 分页生成的文本已按目标宽度断行，绘制时保留这些断行。 */
+    prewrapped?: boolean;
+}
+/** 打印用列表；单选与复选状态仅控制静态外观。 */
+interface PrintDesignListElement extends PrintDesignElementBase {
+    type: "list";
+    listStyle: "ordered" | "unordered" | "radio" | "checkbox";
+    items: {
+        text: string;
+        checked?: boolean;
+    }[];
+    fontSize?: number;
+    color?: string;
+    rowHeight?: number;
+}
+/** 日期时间元素。 */
+interface PrintDesignDateTimeElement extends PrintDesignElementBase {
+    type: "dateTime";
+    format?: string;
+    value?: string;
+    fontSize?: number;
+    color?: string;
+}
+/** 金额大写元素。 */
+interface PrintDesignMoneyUpperElement extends PrintDesignElementBase {
+    type: "moneyUpper";
+    value: string | number;
+    amountFormat?: "chinese" | "formal" | "number";
+    fontSize?: number;
+    color?: string;
+}
+/** 页码元素。 */
+interface PrintDesignPageNumberElement extends PrintDesignElementBase {
+    type: "pageNumber";
+    prefix?: string;
+    fontSize?: number;
+    color?: string;
+}
+/** 水印元素。 */
+interface PrintDesignWatermarkElement extends PrintDesignElementBase {
+    type: "watermark";
+    text: string;
+    fontSize?: number;
+    color?: string;
+    rotation?: number;
+    /** 水印文字自身的旋转角度，不影响元素选中框。 */
+    textRotation?: number;
+    /** 文字重复行数，1–50。@default 1 */
+    rows?: number;
+    /** 文字重复列数，1–50。@default 1 */
+    columns?: number;
+}
+/** 形状元素。 */
+interface PrintDesignShapeElement extends PrintDesignElementBase {
+    type: "shape";
+    shape: "rect" | "ellipse" | "line" | "triangle" | "circle" | "polygon" | "sector" | "star";
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    radius?: number;
+    /** 正多边形边数，范围 3–12。@default 5 */
+    sides?: number;
+    /** 扇形圆心角，范围 1–359 度。@default 120 */
+    sectorAngle?: number;
+    /** 形状内部居中的文本。 */
+    text?: string;
+    fontSize?: number;
+    textColor?: string;
+}
+/** 分割线元素。线条方向、外观与选择区域由元素属性控制。 */
+interface PrintDesignDividerElement extends PrintDesignElementBase {
+    type: "divider";
+    orientation?: "horizontal" | "vertical";
+    stroke?: string;
+    strokeWidth?: number;
+    lineStyle?: "solid" | "dashed" | "dotted";
+}
+/** 可打印刻度尺。总刻度表示从 0 到该数值的等距区间数。 */
+interface PrintDesignRulerElement extends PrintDesignElementBase {
+    type: "ruler";
+    orientation: "horizontal" | "vertical";
+    /** 数字与刻度位于基线的哪一侧：横向为上/下，纵向为左/右。@default "after" */
+    labelPosition?: "before" | "after";
+    totalTicks: number;
+    middleEvery?: number;
+    majorEvery?: number;
+    minorHeight?: number;
+    middleHeight?: number;
+    majorHeight?: number;
+    lineColor?: string;
+    labelColor?: string;
+    strokeWidth?: number;
+    fontSize?: number;
+}
+/** 网格单元格中的静态标记。 */
+type PrintDesignGridMark = "none" | "x" | "*";
+/** 单格静态标记及独立数据绑定；动态值无效时沿用静态值。 */
+interface PrintDesignGridCell {
+    content?: PrintDesignGridMark;
+    contentMode?: "static" | "binding";
+    contentPath?: string;
+    backgroundColor?: string;
+}
+/** 可按单元格显示标记与背景色的打印网格。 */
+interface PrintDesignGridElement extends PrintDesignElementBase {
+    type: "grid";
+    rows: number;
+    columns: number;
+    /** 在画布点击单元格时使用的标记。 */
+    paintMark?: "x" | "*";
+    /** 二维 0/1 选中数组的默认绑定路径；单元格可覆盖。 */
+    contentPath?: string;
+    /** 按行优先排列；每格可独立绑定选中状态。 */
+    cells?: PrintDesignGridCell[];
+    backgroundColor?: string;
+    /** 带有 X 或米字标记的单元格背景色；独立背景配置优先。 */
+    selectedBackgroundColor?: string;
+    lineColor?: string;
+    lineWidth?: number;
+    markColor?: string;
+}
+/** 条形或环形打印进度。尺寸、边框与圆角以毫米表示。 */
+interface PrintDesignProgressElement extends PrintDesignElementBase {
+    type: "progress";
+    variant: "bar" | "ring";
+    /** 完成百分比，范围 0–100。 */
+    value: number;
+    /** 动态完成百分比字段，缺失或无效时使用静态 value。 */
+    valuePath?: string;
+    completedColor?: string;
+    remainingColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    /** 条形圆角或环形进度端点圆角半径。 */
+    borderRadius?: number;
+    /** 环形轨道厚度。 */
+    thickness?: number;
+    /** 条形右侧或环形中心显示完成百分比。 */
+    showPercent?: boolean;
+    /** 百分比字号，单位 pt。 */
+    percentFontSize?: number;
+    percentColor?: string;
+    /** 按最高命中的阈值覆盖当前进度与百分比文字颜色。 */
+    colorRules?: Array<{
+        min: number;
+        completedColor: string;
+        percentColor: string;
+    }>;
+}
+/** 模拟时钟；颜色分别控制表盘、刻度、数字和三根指针。 */
+interface PrintDesignClockElement extends PrintDesignElementBase {
+    type: "clock";
+    /** ISO 日期时间或 HH:mm[:ss]；为空时使用系统时间。 */
+    value?: string;
+    /** 自动刷新间隔；none 固定显示传入时间。 */
+    refreshInterval?: "none" | "second" | "minute" | "hour";
+    /** 传入时间开始运行的时间戳，修改 value 时同步更新。 */
+    startedAt?: string;
+    showHourHand?: boolean;
+    showMinuteHand?: boolean;
+    showSecondHand?: boolean;
+    hourHandColor?: string;
+    minuteHandColor?: string;
+    secondHandColor?: string;
+    ringColor?: string;
+    /** 旧版统一刻度颜色；各级颜色未设置时作为回退值。 */
+    tickColor?: string;
+    showSmallTicks?: boolean;
+    showMediumTicks?: boolean;
+    showLargeTicks?: boolean;
+    smallTickColor?: string;
+    mediumTickColor?: string;
+    largeTickColor?: string;
+    numberColor?: string;
+    /** 刻度数字字号，单位 pt。 */
+    numberFontSize?: number;
+}
+/** 图片元素。 */
+interface PrintDesignImageElement extends PrintDesignElementBase {
+    type: "image";
+    src: string;
+    fit?: "contain" | "cover" | "fill";
+}
+/** 条形码元素。 */
+interface PrintDesignBarcodeElement extends PrintDesignElementBase {
+    type: "barcode";
+    value: string;
+    format?: BarcodeFormat;
+    color?: string;
+    backgroundColor?: string;
+    displayValue?: boolean;
+}
+/** 二维码元素。 */
+interface PrintDesignQrCodeElement extends PrintDesignElementBase {
+    type: "qrcode";
+    value: string;
+    level?: QrCodeLevel;
+    format?: QrCodeFormat;
+    mode?: QrCodeMode;
+    contentTemplate?: QrCodeContentTemplate;
+    templateFields?: QrCodeContentFields;
+    color?: string;
+    backgroundColor?: string;
+}
+/** 图表数据编辑与绑定配置，字段路径相对于数据源中的每条记录。 */
+interface PrintDesignChartData {
+    mode: "static" | "binding";
+    source?: string;
+    /** 数据源缺失时使用静态分类和系列作为默认内容。 */
+    fallbackToStatic?: boolean;
+    categoryField?: string;
+    categories: string[];
+    series: Array<{
+        name: string;
+        field?: string;
+        values: number[];
+    }>;
+    /** 雷达图指标上限。 */
+    max?: number;
+}
+/** 使用 chart 包现有渲染器绘制的静态图表元素。 */
+interface PrintDesignChartElement extends PrintDesignElementBase {
+    type: "chart";
+    chartType: string;
+    chartData?: PrintDesignChartData;
+    option: unknown;
+    simple?: boolean;
+}
+/** 打印表格列配置，保留常用显示、汇总与编辑字段。 */
+interface PrintDesignTableColumn {
+    key?: string;
+    title?: string | number | {
+        type: string;
+        text?: string;
+        alt?: string;
+    } | Array<{
+        type: string;
+        text?: string;
+        alt?: string;
+    }>;
+    dataIndex?: string | number | Array<string | number>;
+    children?: PrintDesignTableColumn[];
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    align?: "left" | "center" | "right";
+    headerAlign?: "left" | "center" | "right";
+    hidden?: boolean;
+    ellipsis?: boolean;
+    cellType?: string;
+    cellStyle?: {
+        textAlign?: "left" | "center" | "right";
+        verticalAlign?: "top" | "middle" | "bottom";
+        backgroundColor?: string;
+        color?: string;
+    };
+    headerStyle?: {
+        backgroundColor?: string;
+        color?: string;
+    };
+    summaryStyle?: {
+        backgroundColor?: string;
+        color?: string;
+    };
+    summary?: boolean | {
+        type?: string;
+        precision?: number;
+        showTypePrefix?: boolean;
+        preserveTrailingZeros?: boolean;
+        valueGetter?: (record: Record<string, unknown>) => string | number | null | undefined;
+        formatter?: (value: string | number, records: Record<string, unknown>[], column: PrintDesignTableColumn) => string;
+    };
+    summaryTitle?: string;
+    moneyFormat?: {
+        symbol?: string;
+        thousandsSeparator?: boolean | string;
+        decimalPlaces?: number;
+        precision?: number;
+    };
+    render?: (value: unknown, record: Record<string, unknown>, rowIndex: number, column: PrintDesignTableColumn) => unknown;
+}
+/** 表格组件。行高单位毫米，列宽沿用 ListTable 的逻辑像素。 */
+interface PrintDesignTableElement extends PrintDesignElementBase {
+    type: "table";
+    columns: PrintDesignTableColumn[];
+    dataSource: Record<string, unknown>[];
+    dataMode?: "static" | "binding";
+    dataPath?: string;
+    /** 数据源缺失时使用 dataSource 作为默认内容，空数组仍视为有效数据。 */
+    fallbackToStatic?: boolean;
+    rowHeight?: number;
+    headerRowHeight?: number;
+    showHeader?: boolean;
+    fontSize?: number;
+    /** 单元格边框，宽度为逻辑像素；0 表示无边框。 */
+    cellBorder?: {
+        color?: string;
+        width?: number;
+    };
+    /** 默认水平对齐，列级配置优先。 */
+    cellAlign?: "left" | "center" | "right";
+    /** 默认垂直对齐，列级配置优先。 */
+    cellVerticalAlign?: "top" | "middle" | "bottom";
+    /** 单元格超出方式，沿用 ListTable 的换行与省略号模式。 */
+    cellOverflow?: "wrap" | "ellipsis";
+    /** 是否显示列配置生成的汇总行，默认显示。 */
+    showSummary?: boolean;
+    /** 汇总行高，单位毫米，默认沿用数据行高。 */
+    summaryRowHeight?: number;
+    /** 最多打印的数据行数，0 或未设置表示全部；不包含表头和汇总行。 */
+    printRowCount?: number;
+    /** 按打印行数补齐空白行，不修改原始数据，也不计入汇总。 */
+    fillEmptyRows?: boolean;
+    /** 各区域默认透明，列级样式可覆盖对应区域配置。 */
+    colors?: Partial<Record<"header" | "body" | "summary", {
+        backgroundColor?: string;
+        color?: string;
+    }>>;
+}
+/** 基于 ListTable 记录集生成的透视表；字段和区域配置保持可序列化。 */
+interface PrintDesignPivotTableElement extends PrintDesignElementBase {
+    type: "pivotTable";
+    /** 按生成列键保存的列宽，单位为逻辑像素。 */
+    columnWidths?: Record<string, number>;
+    dataSource: Record<string, unknown>[];
+    dataMode?: "static" | "binding";
+    dataPath?: string;
+    fallbackToStatic?: boolean;
+    fields: PrintPivotField[];
+    layout: PrintPivotFieldLayout;
+    filters?: PrintPivotFilterState;
+    rowHeight?: number;
+    headerRowHeight?: number;
+    showHeader?: boolean;
+    fontSize?: number;
+    cellBorder?: {
+        color?: string;
+        width?: number;
+    };
+    colors?: PrintDesignTableElement["colors"];
+    /** 是否显示由透视数据生成的总计行。 */
+    showSummary?: boolean;
+    summaryRowHeight?: number;
+    /** 是否显示列分组的总计列。 */
+    showGrandTotal?: boolean;
+}
+/** 打印甘特图的时间精度。 */
+type PrintGanttScale = "second" | "minute" | "hour" | "day" | "week" | "month";
+/** 打印甘特图任务。 */
+interface PrintGanttTask {
+    id: string;
+    title: string;
+    start?: string | number;
+    end?: string | number;
+    progress?: number;
+    color?: string;
+    progressColor?: string;
+    /** 当前任务的前置任务连线，to 默认为当前任务 ID。 */
+    dependencies?: Omit<PrintGanttDependency, "to">[];
+    tasks?: PrintGanttTask[];
+}
+/** 打印甘特图任务依赖。 */
+interface PrintGanttDependency {
+    from: string;
+    to: string;
+    type?: "finish-to-start" | "start-to-start" | "finish-to-finish";
+    color?: string;
+}
+/** 可打印的甘特图快照。 */
+interface PrintDesignGanttElement extends PrintDesignElementBase {
+    type: "gantt";
+    tasks: PrintGanttTask[];
+    showDependencies?: boolean;
+    dependencyColor?: string;
+    /** 依赖连线宽度，单位为逻辑像素。 */
+    dependencyLineWidth?: number;
+    dependencyArrow?: boolean;
+    dataMode?: "static" | "binding";
+    dataPath?: string;
+    fallbackToStatic?: boolean;
+    scale?: PrintGanttScale;
+    startDate?: string;
+    endDate?: string;
+    taskColumnTitle?: string;
+    taskColumnRatio?: number;
+    /** 任务列正文文字的水平对齐方式。 */
+    taskAlign?: "left" | "center" | "right";
+    taskColor?: string;
+    progressColor?: string;
+    /** 任务进度条圆角半径，单位毫米。 */
+    progressRadius?: number;
+    /** 任务进度条高度，单位毫米；不超过当前行高。 */
+    progressHeight?: number;
+    /** 每条任务的行高，单位毫米；未配置时平均填充组件高度。 */
+    rowHeight?: number;
+    /** 表头可关闭；表头高度以毫米保存。 */
+    showHeader?: boolean;
+    headerHeight?: number;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    /** 任务列标题和时间轴刻度的水平对齐方式。 */
+    headerAlign?: "left" | "center" | "right";
+    cellBackgroundColor?: string;
+    cellTextColor?: string;
+    /** 边框宽度沿用表格的逻辑像素单位；0 表示隐藏。 */
+    frameBorder?: {
+        color?: string;
+        width?: number;
+    };
+    headerBorder?: {
+        color?: string;
+        width?: number;
+    };
+    cellBorder?: {
+        color?: string;
+        width?: number;
+    };
+}
+/** 打印设计器支持的元素联合类型。 */
+type PrintDesignElement = PrintDesignTextElement | PrintDesignListElement | PrintDesignDateTimeElement | PrintDesignMoneyUpperElement | PrintDesignPageNumberElement | PrintDesignWatermarkElement | PrintDesignShapeElement | PrintDesignDividerElement | PrintDesignRulerElement | PrintDesignGridElement | PrintDesignProgressElement | PrintDesignClockElement | PrintDesignImageElement | PrintDesignBarcodeElement | PrintDesignQrCodeElement | PrintDesignChartElement | PrintDesignTableElement | PrintDesignPivotTableElement | PrintDesignGanttElement;
+/** 页面纸张方向。 */
+type PrintDesignOrientation = "portrait" | "landscape";
+/** 页面内边距，单位为毫米。 */
+interface PrintDesignPageMargins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** 打印设计器页面。所有几何尺寸均以毫米保存。 */
+interface PrintDesignPage {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    orientation?: PrintDesignOrientation;
+    margins?: PrintDesignPageMargins;
+    background?: string;
+    /** 以页面原点为基准的辅助线位置，单位毫米；允许超出纸张边界。 */
+    guides?: {
+        vertical?: number[];
+        horizontal?: number[];
+    };
+    elements: PrintDesignElement[];
+}
+/** 可序列化的打印设计文档。 */
+interface PrintDesignDocument {
+    id: string;
+    name: string;
+    schemaVersion: number;
+    dpi?: number;
+    pages: PrintDesignPage[];
+}
+/** 核心实例选项。 */
+interface PrintDesignOptions {
+    /** 界面标尺和尺寸显示单位，文档坐标仍为毫米。@default "mm" */
+    displayUnit?: PrintDesignUnit;
+    document?: PrintDesignDocument;
+    /** 用于预览 {{field.path}} 文本变量的数据。 */
+    data?: Record<string, unknown>;
+    /** 临时显示的分页预览页；不修改设计文档。 */
+    preview?: {
+        page: PrintDesignPage;
+        data: Record<string, unknown>;
+    };
+    /** 模板变化回调。 */
+    onChange?: (document: PrintDesignDocument) => void;
+    /** 鼠标、按钮和 API 改变缩放比例时触发。 */
+    onZoomChange?: (zoom: number) => void;
+    /** 当前页面或元素选区变化回调。 */
+    onSelectionChange?: (selection: PrintDesignSelection) => void;
+    /** 当前活动页变化回调。 */
+    onActivePageChange?: (pageId: string) => void;
+    /** 初始画布缩放比例。@default 1 */
+    zoom?: number;
+    /** 只读模式。 */
+    readonly?: boolean;
+    /** 是否显示网格。@default false */
+    showGrid?: boolean;
+    /** 网格线颜色。默认 rgba(148, 163, 184, 0.24)。 */
+    gridColor?: string;
+    /** 网格步长，单位毫米，最小 0.1。@default 5 */
+    gridStep?: number;
+    /** 是否显示画布刻度尺。@default true */
+    showRulers?: boolean;
+    /** 是否显示并允许编辑辅助线。@default true */
+    showGuides?: boolean;
+    /** 是否显示页面边距辅助线。@default false */
+    showMarginGuides?: boolean;
+    /** 用户辅助线颜色。@default "#06b6d4" */
+    guideColor?: string;
+    /** 打印边距辅助线颜色。@default "#8b5cf6" */
+    marginGuideColor?: string;
+    /** 刻度尺字号，单位 CSS 像素，范围 8–16。@default 9 */
+    rulerFontSize?: number;
+    /** 刻度尺背景色。@default "#f8fafc" */
+    rulerBackground?: string;
+    /** 刻度线及刻度尺边界线颜色。@default "#cbd5e1" */
+    rulerLineColor?: string;
+    /** 刻度数字颜色。@default "#64748b" */
+    rulerTextColor?: string;
+    /** 辅助线数值字号，单位 CSS 像素，范围 8–24。@default 9 */
+    guideFontSize?: number;
+    /** 辅助线数值标签背景色。@default "#cffafe" */
+    guideBackground?: string;
+    /** 选中辅助线数值标签背景色。@default "#ffedd5" */
+    guideSelectedBackground?: string;
+    /** 图层状态标签文字与锁定图标颜色。@default "#ffffff" */
+    indicatorColor?: string;
+    /** 图层状态标签背景色。@default "#2563eb" */
+    indicatorBackground?: string;
+    /** 图层状态标签字号，单位 CSS 像素，范围 8–24。@default 11 */
+    indicatorFontSize?: number;
+    /** 图层状态标签相对组件的位置。@default "top-right" */
+    indicatorPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /** 框选区域填充颜色。 */
+    marqueeFill?: string;
+    /** 框选区域边框颜色。 */
+    marqueeStroke?: string;
+    /** 框选区域边框线型。@default "dashed" */
+    marqueeLineStyle?: "solid" | "dashed" | "dotted";
+    /** 拖拽启动距离，单位 CSS 像素。@default 4 */
+    dragThreshold?: number;
+    /** 启用辅助线吸附。@default true */
+    snapToGuides?: boolean;
+    /** 吸附距离，单位 CSS 像素。@default 6 */
+    snapTolerance?: number;
+    /** 显示选中组件与最近组件的间距。@default true */
+    showMeasurements?: boolean;
+    /** 缩放过渡时长，单位毫秒；0 表示关闭。@default 180 */
+    zoomDuration?: number;
+    /** 调试辅助层配置；传入 true 显示元素边界、选区和命中目标。 */
+    debug?: boolean | PrintDesignDebugOptions;
+}
+/** 打印设计器调试辅助层配置。 */
+interface PrintDesignDebugOptions {
+    enabled?: boolean;
+    showElementBounds?: boolean;
+    showSelectionBounds?: boolean;
+    showHitTarget?: boolean;
+}
+/** 编辑器当前选区。 */
+interface PrintDesignSelection {
+    pageId: string;
+    elementIds: string[];
+    /** 当前选中的辅助线图层；与普通元素选区互斥。 */
+    guide?: {
+        axis: "vertical" | "horizontal";
+        index: number;
+    };
+}
+/** 页面导出选项。 */
+interface PrintDesignExportOptions {
+    /** 导出和打印使用的数据源，默认使用实例 data。 */
+    data?: Record<string, unknown>;
+    /** 输出分辨率。@default 文档 dpi 或 300 */
+    dpi?: number;
+    /** 透明背景。@default false */
+    transparent?: boolean;
+}
+
+/** 创建默认 A4 纵向设计文档。 */
+declare function createPrintDesignDocument(overrides?: Partial<PrintDesignDocument>): PrintDesignDocument;
+/** 创建指定大小的空白页面。 */
+declare function createPrintDesignPage(name?: string, width?: number, height?: number): PrintDesignPage;
+/** 创建稳定性足够的轻量级文档 id。 */
+declare function createPrintDesignId(prefix?: string): string;
+/** 校验并规范化导入的打印文档。 */
+declare function parsePrintDesignDocument(input: unknown): PrintDesignDocument;
+/** 将设计文档编码为格式化 JSON。 */
+declare function serializePrintDesignDocument(document: PrintDesignDocument): string;
+
+/** 将变量文本中的 {{path}} 替换为预览数据字段。 */
+declare function resolveDesignText(text: string, data?: Record<string, unknown>): string;
+
+/**
+ * 绘制单个元素到 Canvas 2D 上下文。
+ */
+declare function drawPrintDesignElement(ctx: CanvasRenderingContext2D, element: PrintDesignElement, scale: number, data?: Record<string, unknown>, onImageLoad?: () => void): void;
+/**
+ * 绘制页面到任意 2D 上下文，输出页面尺寸以毫米和目标 DPI 决定。
+ */
+declare function drawPrintDesignPage(ctx: CanvasRenderingContext2D, page: PrintDesignPage, options?: {
+    dpi?: number;
+    transparent?: boolean;
+    data?: Record<string, unknown>;
+    originX?: number;
+    originY?: number;
+    scale?: number;
+    onImageLoad?: () => void;
+}): void;
+/** 将指定页面渲染到新 Canvas，供高清导出和打印使用。 */
+declare function renderPrintDesignPageToCanvas(document: PrintDesignDocument, pageId: string, options?: PrintDesignExportOptions): HTMLCanvasElement;
+/** 在给定页面上查找坐标命中的最上层元素。 */
+declare function hitTestPrintDesignPage(page: PrintDesignPage, point: {
+    x: number;
+    y: number;
+}, tolerance?: number, data?: Record<string, unknown>): PrintDesignTextElement | PrintDesignListElement | PrintDesignDateTimeElement | PrintDesignMoneyUpperElement | PrintDesignPageNumberElement | PrintDesignWatermarkElement | PrintDesignShapeElement | PrintDesignDividerElement | PrintDesignRulerElement | PrintDesignGridElement | PrintDesignProgressElement | PrintDesignClockElement | PrintDesignImageElement | PrintDesignBarcodeElement | PrintDesignQrCodeElement | PrintDesignChartElement | PrintDesignTableElement | PrintDesignPivotTableElement | PrintDesignGanttElement | undefined;
+/** 将 Canvas 像素坐标换算成页面毫米坐标。 */
+declare function canvasPointToPageMillimeters(point: {
+    x: number;
+    y: number;
+}, origin: {
+    x: number;
+    y: number;
+}, cssPixelsPerMillimeter: number): {
+    x: number;
+    y: number;
+};
+
+/** HTML 打印转换的数据源与页面选择。 */
+interface PrintDesignHtmlOptions {
+    data?: Record<string, unknown>;
+    /** 省略时输出文档中的所有页面。 */
+    pageIds?: readonly string[];
+}
+/** 将设计文档及数据转换为可直接交给浏览器打印的 HTML。 */
+declare function transformPrintDesignToHtml(document: PrintDesignDocument, options?: PrintDesignHtmlOptions): string;
+/** 将转换后的 HTML 写入打印窗口，等待图片加载后唤起浏览器打印。 */
+declare function printPrintDesignHtml(popup: Window, html: string): void;
+
+type ResizeHandle = "nw" | "ne" | "se" | "sw" | "n" | "s" | "w" | "e";
+type Rect = Pick<PrintDesignElement, "x" | "y" | "width" | "height">;
+
+/** 表格列边界拖拽快照，使用打印表格的可见布局宽度。 */
+interface TableColumnResize {
+    elementId: string;
+    boundary: number;
+    widths: number[];
+    columns: PrintDesignTableColumn[];
+    rotation: number;
+}
+
+type GroupResizeHandle = ResizeHandle;
+
+interface DragSession {
+    tableColumn?: TableColumnResize;
+    mode: "table-column" | "move" | "resize" | "rotate" | "guide" | "pan" | "marquee";
+    marquee?: {
+        end: {
+            x: number;
+            y: number;
+        };
+        initialIds: string[];
+    };
+    pointerId: number;
+    start: {
+        x: number;
+        y: number;
+    };
+    startClient?: {
+        x: number;
+        y: number;
+    };
+    activated?: boolean;
+    groupResize?: {
+        handle: GroupResizeHandle;
+        bounds: Rect;
+        elements: PrintDesignElement[];
+    };
+    resize?: {
+        elementId: string;
+        handle: ResizeHandle;
+        initial: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        anchor: {
+            x: number;
+            y: number;
+        };
+        rotation: number;
+    };
+    rotate?: {
+        elementId: string;
+        center: {
+            x: number;
+            y: number;
+        };
+        startAngle: number;
+        initialRotation: number;
+    };
+    elementPositions: Map<string, {
+        x: number;
+        y: number;
+    }>;
+    documentBefore: PrintDesignDocument;
+    changed: boolean;
+    guide?: {
+        axis: "vertical" | "horizontal";
+        index: number;
+        created: boolean;
+    };
+    pan?: {
+        initialX: number;
+        initialY: number;
+    };
+}
+/** 共享打印设计器状态、生命周期与视口基础能力。 */
+declare abstract class PrintDesignBase {
+    protected readonly container: HTMLElement;
+    protected readonly canvas: HTMLCanvasElement;
+    protected readonly context: CanvasRenderingContext2D;
+    protected readonly host: HTMLDivElement;
+    protected resizeObserver?: ResizeObserver;
+    protected options: PrintDesignOptions;
+    protected document: PrintDesignDocument;
+    protected activePageId: string;
+    protected selectedElementIds: string[];
+    protected history: PrintDesignDocument[];
+    protected future: PrintDesignDocument[];
+    protected cssWidth: number;
+    protected cssHeight: number;
+    protected zoom: number;
+    protected panX: number;
+    protected panY: number;
+    protected dragSession: DragSession | null;
+    protected spacePressed: boolean;
+    protected zoomTarget?: number;
+    protected zoomAnimationFrame: number | null;
+    protected selectedGuide: {
+        axis: "vertical" | "horizontal";
+        index: number;
+    } | null;
+    protected bindingHoverId: string | null;
+    protected debugPointer: {
+        x: number;
+        y: number;
+    } | null;
+    protected mounted: boolean;
+    /** 创建实例并准备 Canvas 宿主；调用 mount 后开始渲染。 */
+    constructor(container: HTMLElement, options?: PrintDesignOptions);
+    /** 将 Canvas 宿主挂载到容器并开始观察尺寸。 */
+    mount(): this;
+    /** 更新回调、数据、视口或外部传入的设计文档。 */
+    updateOptions(options: Partial<PrintDesignOptions>): this;
+    /** 清理观察器、事件和宿主节点。 */
+    destroy(): void;
+    protected abstract handleDoubleClick: (event: MouseEvent) => void;
+    protected abstract discardTextEditing(): void;
+    protected abstract handlePointerDown: (event: PointerEvent) => void;
+    protected abstract handlePointerMove: (event: PointerEvent) => void;
+    protected abstract handlePointerUp: (event: PointerEvent) => void;
+    protected abstract handlePointerLeave: (event: PointerEvent) => void;
+    protected abstract handleWheel: (event: WheelEvent) => void;
+    protected abstract handleKeyDown: (event: KeyboardEvent) => void;
+    /** 失焦时释放空格状态，避免再次进入画布后保持平移模式。 */
+    protected handleBlur: () => void;
+    protected abstract handleKeyUp: (event: KeyboardEvent) => void;
+    abstract render(): this;
+    abstract fitToView(): this;
+    abstract getDocument(): PrintDesignDocument;
+    abstract getSelection(): PrintDesignSelection;
+    abstract groupElements(elementIds?: string[]): this;
+    abstract ungroupElements(elementIds?: string[]): this;
+    abstract undo(): this;
+    abstract redo(): this;
+    abstract removeElements(elementIds?: string[]): this;
+    abstract removeGuide(axis: "vertical" | "horizontal", index: number): this;
+    abstract selectElements(elementIds: string[], expandGroups?: boolean): this;
+    abstract setZoom(zoom: number): this;
+    abstract getZoom(): number;
+    /** 停止视口动画，保持当前显示比例。 */
+    protected stopZoomAnimation(): void;
+    protected getActivePage(): PrintDesignPage;
+    /** 视口使用预览页时，保留实际活动页供编辑和导出使用。 */
+    protected getDisplayPage(): PrintDesignPage;
+    protected getPageIn(document: PrintDesignDocument): PrintDesignPage;
+    protected commitMutation(mutator: (document: PrintDesignDocument) => void): void;
+    protected pushHistory(document: PrintDesignDocument): void;
+    protected normalizeActivePageAfterHistory(): void;
+    protected emitChange(): void;
+    protected emitSelection(): void;
+    protected resizeCanvas: () => void;
+    protected normalizeZoom(zoom: number): number;
+    protected pageOrigin(): {
+        scale: number;
+        x: number;
+        y: number;
+    };
+}
+
+/** 静态表格单元格编辑会话与文档历史，独立于文本元素编辑。 */
+declare abstract class PrintDesignTableEditing extends PrintDesignBase {
+    private tableEditing;
+    protected beginTableEditing(element: PrintDesignTableElement, point: {
+        x: number;
+        y: number;
+    }): void;
+    /** 外部变更和选中状态变化使草稿失效；缩放、平移则同步浮层位置。 */
+    protected syncTableEditor(): void;
+    protected discardTableEditing(): void;
+}
+
+/** 原生文本编辑浮层；草稿与文档隔离，提交时只产生一次撤销记录。 */
+declare class PrintDesignTextEditor {
+    private host;
+    readonly elementId: string;
+    readonly pageId: string;
+    readonly initialText: string;
+    private onFinish;
+    private settings;
+    private input;
+    private composing;
+    private currentElement;
+    private currentOrigin;
+    constructor(host: HTMLElement, elementId: string, pageId: string, initialText: string, onFinish: (value: string | undefined, restoreFocus: boolean) => void, settings?: {
+        label?: string;
+        validate?: (value: string) => string | undefined;
+    });
+    /** 创建编辑框并选中原文。 */
+    mount(element: PrintDesignTextElement, origin: {
+        x: number;
+        y: number;
+        scale: number;
+    }): void;
+    /** 同步视口和字体，缩放、平移或容器变化时保持与文本重合。 */
+    update(element: PrintDesignTextElement, origin: {
+        x: number;
+        y: number;
+        scale: number;
+    }): void;
+    /** 关闭前先解除会话，防止移除节点触发 blur 后重复提交。 */
+    finish(commit: boolean, restoreFocus?: boolean): void;
+}
+
+/** 连接原生文本编辑会话、文档历史与画布坐标。 */
+declare abstract class PrintDesignTextEditing extends PrintDesignTableEditing {
+    protected textEditor: PrintDesignTextEditor | null;
+    protected handleDoubleClick: (event: MouseEvent) => void;
+    /** 文档或页面切换后丢弃过期草稿，避免覆盖外部更新。 */
+    protected syncTextEditor(): void;
+    protected discardTextEditing(): void;
+}
+
+/** 负责页面、选区、辅助线及命中反馈的 Canvas 绘制。 */
+declare abstract class PrintDesignRenderer extends PrintDesignTextEditing {
+    private clockTimer;
+    private clockTimerMs;
+    /** 仅为当前页面中启用刷新且可见的时钟维护一个定时器。 */
+    private syncClockTimer;
+    /** 卸载时释放自动刷新定时器。 */
+    destroy(): void;
+    /** 重绘当前页面。 */
+    render(): this;
+    private drawGrid;
+    private drawSelection;
+    /** 组合四边控制柄与外部图层重叠时，优先保留其它图层的选择。 */
+    protected hitTestGroupResizeHandle(point: {
+        x: number;
+        y: number;
+    }, page: PrintDesignPage, scale: number): {
+        handle: ResizeHandle;
+        bounds: Rect;
+    } | undefined;
+    protected hitTestResizeHandle(point: {
+        x: number;
+        y: number;
+    }, page: PrintDesignPage, scale: number): {
+        element: PrintDesignElement;
+        handle: ResizeHandle;
+    } | undefined;
+    protected hitTestRotateHandle(point: {
+        x: number;
+        y: number;
+    }, page: PrintDesignPage, scale: number): {
+        element: PrintDesignElement;
+    } | undefined;
+    protected getRotatedCorner(element: PrintDesignElement, handle: ResizeHandle, scale: number): {
+        x: number;
+        y: number;
+    };
+}
+
+/** 负责选择、拖拽、缩放、键盘和光标交互。 */
+declare abstract class PrintDesignInteraction extends PrintDesignRenderer {
+    private panRenderFrame;
+    /** 平移期间每帧最多重绘一次，避免高频 pointermove 重复绘制整页。 */
+    private schedulePanRender;
+    private startPanDrag;
+    private startGuideDrag;
+    protected handlePointerDown: (event: PointerEvent) => void;
+    protected handlePointerMove: (event: PointerEvent) => void;
+    protected handlePointerUp: (event: PointerEvent) => void;
+    protected handlePointerLeave: () => void;
+    /** 根据当前命中目标显示选择和拖动光标。 */
+    private updateCursor;
+    protected handleKeyDown: (event: KeyboardEvent) => void;
+    protected handleKeyUp: (event: KeyboardEvent) => void;
+    private removeSelectedGuide;
+    protected normalizeSelectedGuide(): void;
+    protected handleWheel: (event: WheelEvent) => void;
+    private resizeElementFromPointer;
+}
+
+/** 管理组合关系，坐标仍保存在元素上，导出与打印共用既有绘制链路。 */
+declare abstract class PrintDesignGrouping extends PrintDesignInteraction {
+    /** 重命名组合，同步更新所有成员的组合信息，支持撤销重做。 */
+    renameGroup(groupId: string, name: string): this;
+    /** 同级图层相对排序，整组移动；after 表示视觉列表中放在目标下方。 */
+    moveLayerRelative(elementId: string, targetId: string, after: boolean, depth?: number): this;
+    /** 将多个元素或已有组合合成一个新组合，并保持内部相对层级。 */
+    groupElements(elementIds?: string[]): this;
+    /** 取消选中组合的最外层，保留其内部嵌套组合。 */
+    ungroupElements(elementIds?: string[]): this;
+}
+
+/** 图层位置对齐与排列；justify 等间距，distribute 等中心距。 */
+type PrintDesignLayerAlignment = "left" | "center" | "right" | "top" | "middle" | "bottom" | "justify-horizontal" | "justify-vertical" | "distribute-horizontal" | "distribute-vertical";
+/** 完整选中的组合视为整体，左侧单独选中的子项保持独立。 */
+declare function getPrintDesignAlignmentUnits(elements: PrintDesignElement[], ids: string[]): PrintDesignElement[][];
+
+/** 菜单批量操作与实例内剪贴板；每次文档操作只提交一条历史。 */
+declare abstract class PrintDesignActions extends PrintDesignGrouping {
+    private elementClipboard;
+    /** 画布右键命中选区；点中已选项保留多选，空白清空选区。 */
+    selectAtClientPoint(clientX: number, clientY: number): this;
+    /** 复制选中元素，保留组合、数据及样式，不使用系统剪贴板。 */
+    copyElements(): this;
+    /** 当前实例是否有可粘贴元素。 */
+    canPasteElements(): boolean;
+    /** 剪切选区；锁定元素不可剪切。 */
+    cutElements(): this;
+    /** 粘贴为新元素及新组合，默认向右下偏移 5mm。 */
+    pasteElements(): this;
+    /** 创建选区副本，不覆盖实例剪贴板。 */
+    duplicateElements(): this;
+    private insertCopies;
+    private selectedElements;
+    /** 设置选区锁定或显隐状态。 */
+    setSelectionState(patch: {
+        locked?: boolean;
+        visible?: boolean;
+    }): this;
+    /** 精确设置指定图层状态；组合节点由调用方传入全部成员，一次操作对应一次撤销。 */
+    setElementsState(elementIds: string[], patch: {
+        locked?: boolean;
+        visible?: boolean;
+    }): this;
+    /** 全部解锁或显示当前页元素。 */
+    setAllElementState(patch: {
+        locked?: boolean;
+        visible?: boolean;
+    }): this;
+    /** 批量调整选区层级，保持组合及选区内部相对顺序。 */
+    moveSelectionLayer(direction: "front" | "back" | "forward" | "backward"): this;
+    /** 单个图层/组合对齐纸张，多选对齐选区；每次操作提交一条历史。 */
+    alignSelection(align: PrintDesignLayerAlignment): this;
+}
+
+/** 负责打印文档、页面与导出 API 的原生设计器实例。 */
+declare class PrintDesign extends PrintDesignActions {
+    /** 获取文档副本。 */
+    getDocument(): PrintDesignDocument;
+    /** 替换当前文档并清空撤销历史。 */
+    setDocument(document: PrintDesignDocument): this;
+    /** 导出当前文档 JSON。 */
+    toJSON(): string;
+    /** 获取当前活动页 id。 */
+    getActivePageId(): string;
+    /** 切换当前活动页。 */
+    setActivePage(pageId: string): this;
+    /** 新增空白页面并切换到该页。 */
+    addPage(page?: PrintDesignPage): string;
+    /** 更新页面纸张、页边距或背景属性。 */
+    updatePage(pageId: string, patch: Partial<PrintDesignPage>): this;
+    /** 删除页面；文档至少保留一页。 */
+    removePage(pageId: string): this;
+    /** 获取当前选区副本。 */
+    getSelection(): PrintDesignSelection;
+    /** 选中指定辅助线图层。 */
+    selectGuide(axis: "vertical" | "horizontal", index: number): this;
+    /** 精确设置辅助线位置（毫米），允许负数及纸张外位置，支持撤销重做。 */
+    updateGuide(axis: "vertical" | "horizontal", index: number, position: number): this;
+    /** 删除指定辅助线图层。 */
+    removeGuide(axis: "vertical" | "horizontal", index: number): this;
+    /** 设置当前选中的元素。 */
+    selectElements(elementIds: string[], expandGroups?: boolean): this;
+    /** 将视口客户区坐标转换为当前页面毫米坐标；画布外或刻度尺区域返回 null。 */
+    clientToPagePoint(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    } | null;
+    /** 新增元素并选中。 */
+    addElement<T extends PrintDesignElement>(element: Omit<T, "id"> & {
+        id?: string;
+    }): string;
+    /** 更新当前页中指定元素的属性。 */
+    updateElement(elementId: string, patch: Partial<PrintDesignElement>): this;
+    /** 删除当前选区或指定元素。 */
+    removeElements(elementIds?: string[]): this;
+    /** 调整元素在图层中的前后顺序。 */
+    moveElementLayer(elementId: string, direction: "forward" | "backward" | "front" | "back"): this;
+    /** 设置元素层级，索引从 0（底层）开始；越界值限制到当前页面范围。 */
+    setElementLayer(elementId: string, layerIndex: number): this;
+    /** 撤销上一条文档操作。 */
+    undo(): this;
+    /** 重做最近撤销的文档操作。 */
+    redo(): this;
+    /** 当前是否存在可撤销操作。 */
+    canUndo(): boolean;
+    /** 当前是否存在可重做操作。 */
+    canRedo(): boolean;
+    /** 获取当前缩放比例。 */
+    getZoom(): number;
+    /** 设置画布缩放比例并保持页面中心。 */
+    setZoom(zoom: number): this;
+    /** 缩放以适配当前画布。 */
+    fitToView(): this;
+    /** 导出指定页面的高分辨率 Canvas。 */
+    exportPageToCanvas(pageId?: string, options?: PrintDesignExportOptions): HTMLCanvasElement;
+    /** 导出指定页面为 PNG Blob。 */
+    exportPageToBlob(pageId?: string, options?: PrintDesignExportOptions): Promise<Blob>;
+    /** 将当前设计文档和数据转换为浏览器可打印的 HTML。 */
+    transformToHtml(options?: PrintDesignHtmlOptions): string;
+    /** 打印当前活动页。 */
+    printActivePage(): boolean;
+    /** 打印文档中的全部源页及其自动续页。 */
+    printDocument(): boolean;
+    /** 将选中的源页写入浏览器打印窗口。 */
+    private printPages;
+}
+/** 获取当前设计器可见性状态的简单快照。 */
+declare function getPrintDesignPageSize(page: PrintDesignPage): {
+    width: number;
+    height: number;
+};
+
+/** CSS 参考分辨率：96 CSS px/in。 */
+declare const PRINT_DESIGN_CSS_DPI = 96;
+declare const PRINT_DESIGN_MM_PER_INCH = 25.4;
+/** 将毫米转换为 CSS 像素。 */
+declare function millimetersToPixels(value: number, dpi?: number): number;
+/** 将 CSS 像素转换为毫米。 */
+declare function pixelsToMillimeters(value: number, dpi?: number): number;
+
+/** 按元素高度与分页策略生成可直接绘制和打印的物理页面。 */
+declare function paginatePrintDesignDocument(document: PrintDesignDocument, data?: Record<string, unknown>): PrintDesignDocument;
+
+/** 按静态开关或绑定字段决定组件是否参与预览和打印。 */
+declare function resolvePrintDesignElementVisible(element: PrintDesignElement, data?: Record<string, unknown>): boolean;
+
+/** `debug: true` 使用的默认调试配置。 */
+declare const DEFAULT_PRINT_DESIGN_DEBUG_OPTIONS: {
+    enabled: true;
+    showElementBounds: true;
+    showSelectionBounds: true;
+    showHitTarget: true;
+};
+/** 将布尔值或对象式配置归一化。 */
+declare function resolvePrintDesignDebugOptions(debug: boolean | PrintDesignDebugOptions | undefined): Required<PrintDesignDebugOptions>;
+
+/** 从已有图表选项提取可编辑数据，兼容未配置 chartData 的历史模板。 */
+declare function readChartData(element: PrintDesignChartElement): PrintDesignChartData;
+/** 生成静态或绑定后的图表选项，不修改原模板；绑定缺失时显示空数据。 */
+declare function resolveChartOption(element: PrintDesignChartElement, data?: Record<string, unknown>): unknown;
+
+/** 按数组路径读取表格记录，可显式开启缺失数据源回退，空数组保持为空。 */
+declare function resolveTableRows(element: PrintDesignTableElement, data?: Record<string, unknown>): Record<string, unknown>[];
+/** 获取动态绑定原始数组，用于编辑器校验和预览。 */
+declare function resolveTableDataSource(data: Record<string, unknown>, path?: string): unknown;
+
+/** 按表格记录集绑定规则取得透视表原始记录。 */
+declare function resolvePivotRows(element: PrintDesignPivotTableElement, data?: Record<string, unknown>): Record<string, unknown>[];
+/** 在打印设计包内生成二维透视矩阵，再复用表格绘制与分页。 */
+declare function materializePivotTable(element: PrintDesignPivotTableElement, data?: Record<string, unknown>): PrintDesignTableElement;
+
+/** 打印设计器接受的可序列化任务列表。 */
+declare function isGanttTasks(value: unknown): value is PrintGanttTask[];
+/** 读取绑定任务；有效空数组不会触发默认内容回退。 */
+declare function resolveGanttTasks(element: PrintDesignGanttElement, data?: Record<string, unknown>): PrintGanttTask[];
+/** 从每条任务的前置关系生成连线，终点为该任务。 */
+declare function resolveGanttDependencies(element: PrintDesignGanttElement, data?: Record<string, unknown>): PrintGanttDependency[];
+
+/** 约束行列数量。 */
+declare function normalizeGridCount(value: number): number;
+/** 调整网格尺寸时保留左上角重叠区域的静态标记。 */
+declare function resizeGridCells(cells: readonly PrintDesignGridCell[] | undefined, oldRows: number, oldColumns: number, newRows: number, newColumns: number): PrintDesignGridCell[];
+/** 将静态值和数据字段解析为按行优先排列的绘制单元格。 */
+declare function resolveGridCells(element: PrintDesignGridElement, data?: Record<string, unknown>): {
+    rows: number;
+    columns: number;
+    cellWidth: number;
+    cellHeight: number;
+    cells: {
+        content: PrintDesignGridMark;
+        backgroundColor: string;
+    }[];
+};
+
+/** 展平嵌套表头，保留隐藏列的数据编辑能力。 */
+declare function tableLeafColumns(columns: PrintDesignTableColumn[]): PrintDesignTableColumn[];
+/** 安全读取列字段。 */
+declare function readTableCell(row: Record<string, unknown>, path: PrintDesignTableColumn["dataIndex"]): unknown;
+/** 复制修改字段路径，保留同级数据及嵌套数组，避免改变原文档。 */
+declare function writeTableCell(row: Record<string, unknown>, path: PrintDesignTableColumn["dataIndex"], value: unknown): Record<string, unknown>;
+
+/** 按可见叶列生成打印表格的汇总值。 */
+declare function computePrintTableSummaryValues(rows: Record<string, unknown>[], columns: PrintDesignTableColumn[]): Map<string, string>;
+
+/** 图层树节点，组合节点以首个成员作为整体排序入口。 */
+interface PrintDesignLayerNode {
+    id: string;
+    name: string;
+    element: PrintDesignElement;
+    children?: PrintDesignLayerNode[];
+    memberIds: string[];
+}
+/** 从自底向上的元素序列构建自顶向下的组合树。 */
+declare function buildPrintDesignLayerTree(elements: PrintDesignElement[], depth?: number): PrintDesignLayerNode[];
+
+/** 读取自有字段，支持点路径和数字数组索引，不访问原型链。 */
+declare function resolvePrintDesignDataPath(data: Record<string, unknown>, path: string): unknown;
+
+/** 基础组件可配置的数据字段；只允许覆盖声明过的内容/外观属性。 */
+interface PrintDesignDataField {
+    key: string;
+    label: string;
+    type: "text" | "color" | "number";
+    fallback: string | number;
+}
+/** 图表、表格沿用各自的数据结构，其余组件共用字段配置。 */
+declare function getPrintDesignDataFields(type: PrintDesignElement["type"]): PrintDesignDataField[];
+/** 兼容已有文本/编码模板，新配置显式区分静态和动态模式。 */
+declare function getPrintDesignElementDataConfig(element: PrintDesignElement): {
+    mode: "static" | "binding";
+    bindings?: Record<string, string>;
+};
+/** 解析绑定值；纯路径保留原始类型，模板用于组合多个字段。 */
+declare function resolvePrintDesignBinding(data: Record<string, unknown>, expression: string): unknown;
+/** 将绑定应用到绘制副本；缺失/类型不匹配时保留静态值，不修改模板。 */
+declare function resolvePrintDesignElementData(element: PrintDesignElement, data: Record<string, unknown>): PrintDesignElement;
+
+/** ListTable 接入数据源：列配置与原始记录一起传入，核心层不依赖 React。 */
+interface PrintDesignTableDataSource {
+    dataSource: Record<string, unknown>[];
+    columns?: PrintDesignTableColumn[];
+}
+interface PrintDesignChartDataSource {
+    labels: string[];
+    keys?: string[];
+    series: Array<{
+        name: string;
+        data: number[];
+    }>;
+}
+/** 识别 ListTable 的记录集数据结构，不把普通对象当作数据行。 */
+declare function isPrintDesignTableDataSource(value: unknown): value is PrintDesignTableDataSource;
+/** 兼容 ReactListTable 图表弹窗所使用的 ListTableChartData。 */
+declare function isPrintDesignChartDataSource(value: unknown): value is PrintDesignChartDataSource;
+
+export { DEFAULT_PRINT_DESIGN_DEBUG_OPTIONS, PRINT_DESIGN_CSS_DPI, PRINT_DESIGN_MM_PER_INCH, PRINT_DESIGN_SCHEMA_VERSION, PRINT_DESIGN_UNIT_MM, PrintDesign, type PrintDesignBarcodeElement, type PrintDesignChartData, type PrintDesignChartDataSource, type PrintDesignChartElement, type PrintDesignClockElement, type PrintDesignDataField, type PrintDesignDebugOptions, type PrintDesignDividerElement, type PrintDesignDocument, type PrintDesignElement, type PrintDesignElementBase, type PrintDesignExportOptions, type PrintDesignGanttElement, type PrintDesignGridCell, type PrintDesignGridElement, type PrintDesignGridMark, type PrintDesignHtmlOptions, type PrintDesignImageElement, type PrintDesignLayerAlignment, type PrintDesignLayerNode, type PrintDesignListElement, type PrintDesignOptions, type PrintDesignOrientation, type PrintDesignPage, type PrintDesignPageMargins, type PrintDesignPivotTableElement, type PrintDesignProgressElement, type PrintDesignQrCodeElement, type PrintDesignRulerElement, type PrintDesignSelection, type PrintDesignShapeElement, type PrintDesignTableColumn, type PrintDesignTableDataSource, type PrintDesignTableElement, type PrintDesignTextElement, type PrintDesignUnit, type PrintGanttDependency, type PrintGanttScale, type PrintGanttTask, type PrintPivotAggregator, type PrintPivotField, type PrintPivotFieldArea, type PrintPivotFieldLayout, type PrintPivotFilterState, buildPrintDesignLayerTree, canvasPointToPageMillimeters, computePrintTableSummaryValues, createPrintDesignDocument, createPrintDesignId, createPrintDesignPage, drawPrintDesignElement, drawPrintDesignPage, findPrintPivotFieldArea, formatDisplayUnit, fromDisplayUnit, getPrintDesignAlignmentUnits, getPrintDesignDataFields, getPrintDesignElementDataConfig, getPrintDesignPageSize, hitTestPrintDesignPage, isGanttTasks, isPrintDesignChartDataSource, isPrintDesignTableDataSource, materializePivotTable, millimetersToPixels, movePrintPivotField, normalizeGridCount, paginatePrintDesignDocument, parsePrintDesignDocument, pixelsToMillimeters, printPivotFieldHeaderTitle, printPivotFieldTitle, printPivotValueTitle, printPrintDesignHtml, readChartData, readTableCell, removePrintPivotField, renderPrintDesignPageToCanvas, resizeGridCells, resolveChartOption, resolveDesignText, resolveGanttDependencies, resolveGanttTasks, resolveGridCells, resolvePivotRows, resolvePrintDesignBinding, resolvePrintDesignDataPath, resolvePrintDesignDebugOptions, resolvePrintDesignElementData, resolvePrintDesignElementVisible, resolveTableDataSource, resolveTableRows, serializePrintDesignDocument, tableLeafColumns, toDisplayUnit, transformPrintDesignToHtml, writeTableCell };