@veltra/sheet 2.3.4 → 2.4.0

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/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
 }
 
 /** 报表查看器组件暴露的方法 */