@veltra/sheet 2.3.3 → 2.4.0

package/src/report/export-xlsx.ts

@@ -1,113 +1,15 @@
 import type { Sheet } from '@veltra/sheet-core'
-import { rangeToHucre, styleToHucre } from '@veltra/sheet-core/core/io/export'
-import type { Cell, CellValue, ColumnDef, RowDef, WriteSheet } from 'hucre'
-import { writeXlsx } from 'hucre/xlsx'
+import { exportSheetXlsx } from '@veltra/sheet-core/core/io/export'
 
 /** 列宽条目：模型列索引 → 像素宽（与 SheetSnapshot.colWidths 同构） */
 export type ReportColWidthEntry = readonly [number, number]
 
-/** 像素 → Excel points */
-function pxToPt(px: number): number {
-  return px * 0.75
-}
-
-/** VTable 像素列宽 → Excel 字符宽度（近似换算） */
-export function pxToExcelColWidth(px: number): number {
-  return Math.max(1, Math.round((px - 5) / 7))
-}
-
-/** 从列宽条目构建 hucre ColumnDef */
-export function buildColumnDefs(colWidths: ReadonlyArray<ReportColWidthEntry>): ColumnDef[] {
-  if (colWidths.length === 0) return []
-  const maxCol = Math.max(...colWidths.map(([col]) => col))
-  const columns: ColumnDef[] = Array.from({ length: maxCol + 1 }, () => ({}))
-  for (const [col, width] of colWidths) {
-    columns[col] = { width: pxToExcelColWidth(width) }
-  }
-  return columns
-}
-
 /**
- * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
+ * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽 / 浮动图）。
+ * 组装与序列化委托 sheet-core `exportSheetXlsx`（与 `exportWorkbookXlsx` 同一套单表逻辑）；
  * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
  * 列宽取自 sheet 模型（`getColWidths`）。
  */
-export async function exportFilledReportXlsx(sheet: Sheet): Promise<Uint8Array> {
-  const widths: ReportColWidthEntry[] = [...sheet.getColWidths()]
-
-  let maxRow = -1
-  let maxCol = -1
-  for (const [addr] of sheet.store.entries()) {
-    if (addr.row > maxRow) maxRow = addr.row
-    if (addr.col > maxCol) maxCol = addr.col
-  }
-  for (const [row] of sheet.getRowHeights()) {
-    if (row > maxRow) maxRow = row
-  }
-  for (const [col] of widths) {
-    if (col > maxCol) maxCol = col
-  }
-
-  const rows =
-    maxRow < 0
-      ? []
-      : Array.from({ length: maxRow + 1 }, () =>
-          Array.from({ length: maxCol + 1 }, () => null as CellValue)
-        )
-  const cells = new Map<string, Partial<Cell>>()
-
-  for (const [addr, data] of sheet.store.entries()) {
-    const row = rows[addr.row]!
-    const key = `${addr.row},${addr.col}`
-    const cell: Partial<Cell> = {}
-    const style = sheet.getEffectiveStyle(addr)
-    if (style) cell.style = styleToHucre(style)
-    if (data.f != null && data.f !== '') {
-      cell.formula = data.f
-      if (data.v != null) cell.formulaResult = data.v as CellValue
-      row[addr.col] = (data.v as CellValue) ?? null
-      cells.set(key, cell)
-      continue
-    }
-    if (data.t === 'e') {
-      cell.value = data.v as string
-      cell.type = 'error'
-      row[addr.col] = null
-      cells.set(key, cell)
-      continue
-    }
-    if (data.t === 'd') {
-      cell.value = data.v as number
-      cell.type = 'number'
-      cell.style = { ...cell.style, numFmt: 'yyyy-mm-dd' }
-      row[addr.col] = null
-      cells.set(key, cell)
-      continue
-    }
-    row[addr.col] = (data.v as CellValue) ?? null
-    if (Object.keys(cell).length > 0) cells.set(key, cell)
-  }
-
-  const writeSheet: WriteSheet = {
-    name: sheet.name || '报表',
-    rows,
-    ...(cells.size > 0 ? { cells } : {}),
-    ...(sheet.merges.size > 0
-      ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) }
-      : {}),
-    ...(widths.length > 0 ? { columns: buildColumnDefs(widths) } : {})
-  }
-
-  const frozen = sheet.frozen
-  if (frozen.rows > 0 || frozen.cols > 0) {
-    writeSheet.freezePane = { rows: frozen.rows, columns: frozen.cols }
-  }
-
-  const rowDefs = new Map<number, RowDef>()
-  for (const [row, height] of sheet.getRowHeights()) {
-    rowDefs.set(row, { height: pxToPt(height) })
-  }
-  if (rowDefs.size > 0) writeSheet.rowDefs = rowDefs
-
-  return writeXlsx({ sheets: [writeSheet], activeSheet: 0 })
+export function exportFilledReportXlsx(sheet: Sheet): Promise<Uint8Array> {
+  return exportSheetXlsx(sheet, { fallbackName: '报表' })
 }

package/src/report/index.ts

@@ -1,5 +1,6 @@
 // 报表纯 TS 内核（ADR-0003 决策 1）：渲染引擎 / 绑定 / 条件规则 / 查询参数 / 数据连接器 /
-// Report Template（自包含模板与取数）/ Filter Bar 值规范化。
+// Report Template（自包含模板与取数）/ Filter Bar 值规范化 / 下钻配置与下钻栈 /
+// Filled Report XLSX 导出与打印 HTML。
 // 框架无关、无 DOM 依赖；组件壳（UReportDesigner / UReportViewer）落 components/report/。
 
 export * from './types'
@@ -10,4 +11,6 @@ export * from './render'
 export * from './connector'
 export * from './template'
 export * from './filter-bar'
+export * from './drill'
 export * from './export-xlsx'
+export * from './print'

package/src/report/print.ts

@@ -0,0 +1,234 @@
+import type {
+  BorderLineStyle,
+  CellStyle,
+  Sheet,
+  SheetImage,
+  SheetImageType
+} from '@veltra/sheet-core'
+import { BORDER_SIDES } from '@veltra/sheet-core'
+
+/** 报表打印选项 */
+export interface ReportPrintOptions {
+  /** 打印文档标题（打印对话框标题 / 另存 PDF 文件名）；缺省取 sheet 名，再回落「报表」 */
+  title?: string
+  /** 纸张方向（@page size），默认 portrait */
+  orientation?: 'portrait' | 'landscape'
+}
+
+/**
+ * 默认列宽 / 行高（px）：与 grid 层 vtable-theme 的
+ * SHEET_DEFAULT_COL_WIDTH / SHEET_DEFAULT_ROW_HEIGHT 对齐；
+ * report 内核保持 headless，不引 grid 入口。
+ */
+const PRINT_DEFAULT_COL_WIDTH = 80
+const PRINT_DEFAULT_ROW_HEIGHT = 28
+
+const IMAGE_MIME: Record<SheetImageType, string> = {
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp'
+}
+
+/** 模型边框线型 → CSS 线型（thin/medium/thick 为实线粗细分级，宽度由 edge.width 表达） */
+const BORDER_CSS_LINE: Record<BorderLineStyle, string> = {
+  thin: 'solid',
+  medium: 'solid',
+  thick: 'solid',
+  dashed: 'dashed',
+  dotted: 'dotted'
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function escapeAttr(text: string): string {
+  return escapeHtml(text).replace(/"/g, '&quot;')
+}
+
+/** Uint8Array → base64（分块避免栈溢出；btoa 在浏览器 / Node >=16 / Bun / happy-dom 均可用） */
+function bytesToBase64(data: Uint8Array): string {
+  let binary = ''
+  const CHUNK = 0x8000
+  for (let i = 0; i < data.length; i += CHUNK) {
+    binary += String.fromCharCode(...data.subarray(i, i + CHUNK))
+  }
+  return btoa(binary)
+}
+
+/** 模型有效样式 → td 内联 CSS（字号 pt 直出，与屏幕 px ×4/3 物理尺寸一致） */
+function styleToCss(style: CellStyle): string {
+  const decls: string[] = []
+  if (style.fill?.color) decls.push(`background-color:${style.fill.color}`)
+  for (const side of BORDER_SIDES) {
+    const edge = style.border?.[side]
+    if (edge)
+      decls.push(`border-${side}:${edge.width}px ${BORDER_CSS_LINE[edge.style]} ${edge.color}`)
+  }
+  const font = style.font
+  if (font) {
+    if (font.color) decls.push(`color:${font.color}`)
+    if (font.bold) decls.push('font-weight:bold')
+    if (font.italic) decls.push('font-style:italic')
+    const decoration = [font.underline ? 'underline' : '', font.strikethrough ? 'line-through' : '']
+      .filter(Boolean)
+      .join(' ')
+    if (decoration) decls.push(`text-decoration:${decoration}`)
+    if (typeof font.size === 'number') decls.push(`font-size:${font.size}pt`)
+  }
+  const align = style.align
+  if (align) {
+    if (align.horizontal) decls.push(`text-align:${align.horizontal}`)
+    if (align.vertical) decls.push(`vertical-align:${align.vertical}`)
+    if (align.wrap) decls.push('white-space:normal;word-break:break-all')
+  }
+  return decls.join(';')
+}
+
+interface PrintImageRect {
+  left: number
+  top: number
+  width?: number
+  height?: number
+}
+
+/**
+ * 浮动图打印定位（镜像 grid image-layer `computeImageRect`）：
+ * left/top = from 格左上 + 格内像素偏移；宽高优先 image.width/height（两者都有才用），
+ * 缺失且有 to 时按 from→to 跨度兜底，都缺失则省略尺寸（浏览器取自然尺寸）。
+ */
+function computePrintImageRect(
+  image: SheetImage,
+  colWidths: readonly number[],
+  rowHeights: readonly number[]
+): PrintImageRect {
+  const { from, to } = image.anchor
+  let left = from.offsetX ?? 0
+  for (let c = 0; c < from.col; c++) left += colWidths[c] ?? PRINT_DEFAULT_COL_WIDTH
+  let top = from.offsetY ?? 0
+  for (let r = 0; r < from.row; r++) top += rowHeights[r] ?? PRINT_DEFAULT_ROW_HEIGHT
+
+  if (image.width != null && image.height != null) {
+    return { left, top, width: image.width, height: image.height }
+  }
+  if (to) {
+    let width = 0
+    for (let c = from.col; c <= to.col; c++) width += colWidths[c] ?? PRINT_DEFAULT_COL_WIDTH
+    let height = 0
+    for (let r = from.row; r <= to.row; r++) height += rowHeights[r] ?? PRINT_DEFAULT_ROW_HEIGHT
+    return { left, top, width, height }
+  }
+  return { left, top }
+}
+
+/**
+ * 将已填充的 Sheet（Filled Report）构建为打印专用 HTML 文档（纯 TS、headless、无 DOM）。
+ *
+ * 路线说明：网格渲染层是 canvas + 虚拟滚动（视口外不绘制），无法直接 window.print；
+ * 这里从模型单一事实源（与 exportFilledReportXlsx 同一读取路径）重建 `<table>`——
+ * 矢量文字清晰、浏览器原生分页、合并格天然映射 rowspan/colspan。
+ *
+ * 保真范围：值 / 合并 / 有效样式（fill + border + font + align/wrap，条件样式已在
+ * 展开阶段打平进 StylePool）/ 行高 / 列宽 / 浮动图（data URL 内嵌，跨页被裁剪属预期）。
+ * 与 Excel 默认一致：不打印屏幕网格线（仅模型显式边框）。
+ */
+export function buildFilledReportPrintHtml(sheet: Sheet, options?: ReportPrintOptions): string {
+  const title = options?.title ?? sheet.name ?? ''
+  const orientation = options?.orientation ?? 'portrait'
+
+  // 打印范围 = 数据 ∪ 行高 ∪ 列宽 ∪ 合并 ∪ 图片锚点 包围盒（与 xlsx 导出收敛逻辑一致 + 合并/图片）
+  let maxRow = -1
+  let maxCol = -1
+  const grow = (row: number, col: number): void => {
+    if (row > maxRow) maxRow = row
+    if (col > maxCol) maxCol = col
+  }
+  for (const [addr] of sheet.store.peekEntries()) grow(addr.row, addr.col)
+  for (const [row] of sheet.getRowHeights()) grow(row, 0)
+  for (const [col] of sheet.getColWidths()) grow(0, col)
+  const merges = sheet.merges.getMerges()
+  for (const range of merges) grow(range.end.row, range.end.col)
+  const images = sheet.getImages()
+  for (const image of images) {
+    grow(image.anchor.from.row, image.anchor.from.col)
+    if (image.anchor.to) grow(image.anchor.to.row, image.anchor.to.col)
+  }
+
+  const colWidths: number[] = []
+  for (let c = 0; c <= maxCol; c++) colWidths.push(sheet.getColWidth(c) ?? PRINT_DEFAULT_COL_WIDTH)
+  const rowHeights: number[] = []
+  for (let r = 0; r <= maxRow; r++)
+    rowHeights.push(sheet.getRowHeight(r) ?? PRINT_DEFAULT_ROW_HEIGHT)
+
+  // 合并：锚点 → 跨度；被覆盖格集合（跳过客格）
+  const spanByAnchor = new Map<string, { rowSpan: number; colSpan: number }>()
+  const covered = new Set<string>()
+  for (const range of merges) {
+    const rowSpan = range.end.row - range.start.row + 1
+    const colSpan = range.end.col - range.start.col + 1
+    spanByAnchor.set(`${range.start.row},${range.start.col}`, { rowSpan, colSpan })
+    for (let r = range.start.row; r <= range.end.row; r++) {
+      for (let c = range.start.col; c <= range.end.col; c++) {
+        if (r !== range.start.row || c !== range.start.col) covered.add(`${r},${c}`)
+      }
+    }
+  }
+
+  const css = [
+    `@page { size: A4 ${orientation}; margin: 12mm; }`,
+    'html, body { margin: 0; padding: 0; }',
+    "body { font-family: Arial, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif; font-size: 12px; color: #1f2329; -webkit-print-color-adjust: exact; print-color-adjust: exact; }",
+    '.sheet-print-root { position: relative; }',
+    'table { border-collapse: collapse; table-layout: fixed; }',
+    'tr { break-inside: avoid; }',
+    'td { box-sizing: border-box; padding: 2px 6px; overflow: hidden; white-space: nowrap; vertical-align: middle; text-align: left; }',
+    '.sheet-print-root img { position: absolute; }'
+  ].join('\n')
+
+  const parts: string[] = []
+  parts.push('<!doctype html><html><head><meta charset="utf-8">')
+  parts.push(`<title>${escapeHtml(title || '报表')}</title>`)
+  parts.push(`<style>\n${css}\n</style></head><body>`)
+  parts.push('<div class="sheet-print-root">')
+  parts.push('<table>')
+  if (colWidths.length > 0) {
+    parts.push('<colgroup>')
+    for (const width of colWidths) parts.push(`<col style="width:${width}px">`)
+    parts.push('</colgroup>')
+  }
+  for (let r = 0; r <= maxRow; r++) {
+    parts.push(`<tr style="height:${rowHeights[r]}px">`)
+    for (let c = 0; c <= maxCol; c++) {
+      if (covered.has(`${r},${c}`)) continue
+      const attrs: string[] = []
+      const span = spanByAnchor.get(`${r},${c}`)
+      if (span && span.colSpan > 1) attrs.push(`colspan="${span.colSpan}"`)
+      if (span && span.rowSpan > 1) attrs.push(`rowspan="${span.rowSpan}"`)
+      const style = sheet.getEffectiveStyle({ row: r, col: c })
+      const cellCss = style ? styleToCss(style) : ''
+      if (cellCss) attrs.push(`style="${escapeAttr(cellCss)}"`)
+      const value = sheet.getDisplayValue({ row: r, col: c })
+      const text = value == null ? '' : escapeHtml(String(value))
+      parts.push(`<td${attrs.length > 0 ? ` ${attrs.join(' ')}` : ''}>${text}</td>`)
+    }
+    parts.push('</tr>')
+  }
+  parts.push('</table>')
+
+  for (const image of images) {
+    const rect = computePrintImageRect(image, colWidths, rowHeights)
+    const size =
+      rect.width != null && rect.height != null
+        ? `width:${rect.width}px;height:${rect.height}px;`
+        : ''
+    const src = `data:${IMAGE_MIME[image.type]};base64,${bytesToBase64(image.data)}`
+    parts.push(
+      `<img src="${src}" style="left:${rect.left}px;top:${rect.top}px;${size}" alt="${escapeAttr(image.altText ?? '')}">`
+    )
+  }
+
+  parts.push('</div></body></html>')
+  return parts.join('')
+}

package/src/report/render/aggregate.ts

@@ -259,3 +259,31 @@ export function resolvePlacementRecord(
   const rows = aggregateIndex.rowsFor(binding.dataset, filter)
   return rows[placement.listIndex]
 }
+
+/**
+ * 解析落点的上下文记录（下钻字段映射用）：
+ * `list` 明细取源数据行；分组/汇总格取祖先分组过滤值合成的上下文
+ * （分组格含自身分组值，如地区分组格 → `{ region: '华东' }`；
+ * 汇总聚合格如 sum/avg/count/max/min 也将本格聚合计算值并入上下文，如 `{ region: '华东', total: 300 }`）。
+ */
+export function resolvePlacementContext(
+  placement: PhysicalPlacement,
+  index: TemplateIndex,
+  data: DatasetRecords,
+  aggregateIndex: AggregateIndex
+): Record<string, unknown> | undefined {
+  const binding = placement.binding
+  if (!binding) return undefined
+  if (binding.aggregate === 'list') {
+    return resolvePlacementRecord(placement, index, data, aggregateIndex)
+  }
+
+  const filter = resolveAncestorFilters(binding, placement, index, data)
+  if (binding.aggregate === 'group') {
+    const value = filter[binding.field] ?? resolveOwnGroupValue(binding, placement, index, data)
+    return value === undefined ? filter : { ...filter, [binding.field]: value }
+  }
+
+  const value = resolvePlacementValue(placement, index, data, aggregateIndex)
+  return value === undefined ? filter : { ...filter, [binding.field]: value }
+}

package/src/report/types.ts

@@ -30,6 +30,24 @@ export interface ConditionalRule {
   scope?: 'cell' | 'row'
 }
 
+/** 绑定格下钻配置（存于 Cell Meta namespace `report`，随绑定序列化；旧查看器忽略该字段） */
+export interface ReportDrillConfig {
+  /** 目标模板引用（宿主模板列表项的 ref，不支持手填） */
+  target: string
+  /** 字段 → 详情报参数映射：源记录字段名 → 目标报表 Filter Bar 参数 id */
+  mapping: Record<string, string>
+  /** 打开方式：查看器内切换 | UDialog 弹框 */
+  openMode: 'switch' | 'dialog'
+}
+
+/** 宿主提供的可下钻模板列表项（设计器下拉与查看器 resolveTemplate 契约共用） */
+export interface ReportTemplateListItem {
+  /** 模板引用，作为下钻 target 并传给宿主 resolveTemplate */
+  ref: string
+  /** 可读名，用于设计器下拉展示 */
+  label: string
+}
+
 /** 设计格上的报表绑定（存于 Cell Meta namespace `report`） */
 export interface ReportBinding {
   dataset: string
@@ -48,6 +66,8 @@ export interface ReportBinding {
   conditionalRules?: ConditionalRule[]
   /** 设计器预设；引擎不读 */
   preset?: ReportPreset
+  /** 下钻配置；缺省不可下钻 */
+  drill?: ReportDrillConfig
 }
 
 /**

package/src/tools/__test__/builtin.test.ts

@@ -122,7 +122,7 @@ describe('内置工具（dogfood 扩展机制）', () => {
     }
   })
 
-  it('导出 xlsx：sheet 名含 Excel 非法字符时 reject（hucre 1.0 写入校验，错误传播给调用方）', async () => {
+  it('导出 xlsx：sheet 名含 Excel 非法字符时 reject（sheet-core 写入校验，错误传播给调用方）', async () => {
     const workbook = new Workbook()
     workbook.renameSheet('Sheet1', 'a:b')
     const ctx = createSheetContext(workbook.activeSheet, workbook)

package/src/tools/download.ts

@@ -6,7 +6,7 @@ import type { SheetContext } from './context'
 import type { ExportWorkerPayload, ExportWorkerResponse } from './export.worker'
 
 /**
- * 大工作簿的 XLSX 导出（hucre 序列化 + ZIP 压缩为秒级同步重活）移入 Web Worker：
+ * 大工作簿的 XLSX 导出（sheet-core 序列化 + ZIP 压缩为秒级同步重活）移入 Web Worker：
  * 主线程只采集快照（结构化克隆友好的纯数据，行高随 SheetSnapshot.rowHeights
  * 携带），序列化与压缩在 worker 线程进行。worker 不可用（极端环境 / 打包产物
  * 缺文件）回退主线程导出——与导入侧 parseXlsxAsync 同一模式。
@@ -55,7 +55,7 @@ async function exportWorkbookXlsxAsync(workbook: Workbook): Promise<Uint8Array>
 /**
  * 导出当前工作簿为 .xlsx（无 workbook 时空操作）。
  * 下载动作复用 @cat-kit/fe 的 saveBlob（#28：不再自研 Object URL + a.click）。
- * hucre 1.0 起 writeXlsx 会校验 sheet 名（Excel 非法字符 / 超长 / 保留名）并抛
+ * 导出侧 sheet-core 的 writeXlsx 会校验 sheet 名（Excel 非法字符 / 超长 / 保留名）并抛
  * InvalidArgumentError——失败经返回的 Promise 传播，调用方（导出面板）负责提示。
  */
 export async function exportWorkbookFile(ctx: SheetContext): Promise<void> {

package/src/tools/export.worker.ts

@@ -1,6 +1,6 @@
 /// <reference lib="webworker" />
 /**
- * XLSX 导出 Worker：exportWorkbookXlsx（模型 → hucre 序列化 + ZIP 压缩，
+ * XLSX 导出 Worker：sheet-core exportWorkbookXlsx（模型序列化 + ZIP 压缩，
  * 大工作簿为秒级同步重活）移到独立线程，主线程保持空闲。
  *
  * 协议：主线程 postMessage({ sheets: [{ name, snapshot }], activeIndex }）
@@ -36,7 +36,7 @@ self.onmessage = (e: MessageEvent<ExportWorkerPayload>): void => {
       for (let i = 0; i < sheets.length; i++) {
         const { name, snapshot } = sheets[i]!
         // 首个 sheet 复用 Workbook 自带的默认表：先改名对齐（空名/重名保持原名，
-        // 导出侧 hucre 1.0 会校验表名合法性）
+        // 导出侧 sheet-core 的 writeXlsx 会校验表名合法性）
         const sheet = i === 0 ? wb.activeSheet : wb.addSheet(name)
         if (i === 0 && sheet.name !== name) wb.renameSheet(sheet.name, name)
         sheet.restore(snapshot)

package/src/types/report-designer.ts

@@ -1,7 +1,13 @@
 import type { Workbook } from '@veltra/sheet-core/core/workbook'
 import type { DeconstructValue } from '@veltra/utils'
 
-import type { DataConnection, DataConnector, ReportTemplate } from '../report'
+import type {
+  DataConnection,
+  DataConnector,
+  ReportTemplate,
+  ReportTemplateListItem,
+  ResolveReportTemplate
+} from '../report'
 
 /** 报表设计器组件属性（ADR-0003 决策 2） */
 export interface ReportDesignerProps {
@@ -19,6 +25,17 @@ export interface ReportDesignerProps {
   template?: ReportTemplate
   /** 承载设计态的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
   workbook?: Workbook
+  /**
+   * 宿主提供的可下钻目标模板列表（ref + 可读名）：
+   * 传入后绑定格 Action Pill 出现下钻配置入口（目标仅从列表选择，不支持手填引用）；不传则无入口
+   */
+  drillTemplates?: ReportTemplateListItem[]
+  /**
+   * 宿主模板解析契约（按下钻 target 引用取回目标模板，失败抛错）：
+   * 下钻配置对话框据此解析目标模板的查询参数（字段→参数映射）；
+   * 预览模式原样转发给内嵌 UReportViewer，使预览内可下钻（含 switch / dialog）与逐级回退
+   */
+  resolveTemplate?: ResolveReportTemplate
 }
 
 /** 报表设计器组件定义的事件 */

package/src/types/report-viewer.ts

@@ -1,8 +1,9 @@
 import type { Workbook } from '@veltra/sheet-core/core/workbook'
 import type { DeconstructValue } from '@veltra/utils'
 
-import type { DataConnector, ReportTemplate } from '../report'
+import type { DataConnector, ParamValues, ReportTemplate, ResolveReportTemplate } from '../report'
 import type { ReportColWidthEntry } from '../report/export-xlsx'
+import type { ReportPrintOptions } from '../report/print'
 
 /** 报表查看器组件属性（ADR-0003 决策 2） */
 export interface ReportViewerProps {
@@ -20,6 +21,17 @@ export interface ReportViewerProps {
    * 列宽已进 `SheetSnapshot.colWidths`，通常无需再传。
    */
   colWidths?: ReadonlyArray<ReportColWidthEntry>
+  /**
+   * 下钻目标模板解析契约（可选，内核共享类型）：单击配了下钻的绑定格时按 `target` 引用取目标模板。
+   * 解析失败（抛错 / reject，或宿主实现返回空值）时查看器给出可读提示并停留当前报。
+   * 缺省时下钻不生效（无点击行为与可点视觉提示）。
+   */
+  resolveTemplate?: ResolveReportTemplate
+  /**
+   * Filter Bar 初值（可选）：与当前模板参数默认值合并，显式键覆盖默认值。
+   * 仅在根模板载入时播种（下钻弹框传入映射参数）；缺省则只用参数默认值。
+   */
+  initialValues?: ParamValues
 }
 
 /** 在组件内部引用 */
@@ -31,6 +43,11 @@ export interface _ReportViewerExposed {
    * 不内置导出按钮，工具栏由下游决定。
    */
   exportXlsx: () => Promise<void>
+  /**
+   * 打印填充报表（纯前端：模型 → 打印 HTML → 隐藏 iframe 调起浏览器打印；
+   * 取数完成前拒绝）。不内置打印按钮，工具栏由下游决定。
+   */
+  print: (options?: ReportPrintOptions) => void
 }
 
 /** 报表查看器组件暴露的方法 */