@veltra/sheet 2.2.0 → 2.3.1

package/src/components/report/report-designer.vue

@@ -35,7 +35,7 @@
 
       <span :class="cls.e('hint')">
         在数据中枢配置连接与 SQL
-        数据集，再将左侧字段点击或拖拽到单元格完成绑定；选中已绑定格可通过悬浮卡片调整角色、聚合与条件样式。
+        数据集，再将左侧字段点击或拖拽到单元格完成绑定；选中已绑定格可通过悬浮卡片调整预设与条件样式。
       </span>
     </div>
 
@@ -59,8 +59,8 @@
           ref="sheetRef"
           :class="cls.e('sheet')"
           :workbook="workbook"
-          :rows="DESIGN_ROWS"
-          :cols="DESIGN_COLS"
+          :rows="gridRows"
+          :cols="gridCols"
           :show-tabs="false"
           :resolve-cell-style="resolveCellStyle"
           :resolve-cell-renderer="resolveCellRenderer"
@@ -84,6 +84,20 @@
           :fallback-label="selectionLabel"
         />
 
+        <u-report-drop-highlight-overlay
+          v-for="addr in pickCandidateCells"
+          :key="`pick-${addr.row}-${addr.col}`"
+          :cell="addr"
+          :host-el="gridHostEl"
+          :get-grid="getDesignGrid"
+          :dragging="false"
+          fallback-label=""
+        />
+
+        <div v-if="parentPick" :class="cls.e('pick-hint')" role="status">
+          {{ parentPick.mode === 'row' ? '点击分组头作为行方向父格' : '点击分组头作为列方向父格' }}
+        </div>
+
         <u-report-float-panel
           :cell="activeCell"
           :binding="activeBinding ?? null"
@@ -93,6 +107,7 @@
           :row-parent-candidates="rowParentCandidates"
           :col-parent-candidates="colParentCandidates"
           :resolve-field-label="resolveFieldLabel"
+          :get-binding-at="getBindingAt"
           :host-el="gridHostEl"
           :get-grid="getDesignGrid"
           @patch="patchActiveBinding"
@@ -111,12 +126,11 @@
         :connector="props.connector"
         :template="previewTemplate"
         :workbook="previewWorkbook"
-        :col-widths="designColWidths"
       />
     </div>
 
     <u-drawer v-model="hubVisible" :class="cls.e('hub-drawer')" show-close>
-      <u-report-dataset-hub :hub="designer" @close="hubVisible = false" />
+      <u-report-dataset-hub :hub="designer" @close="onHubClose" />
     </u-drawer>
 
     <u-report-rules-dialog
@@ -135,7 +149,7 @@ import { UButton, UDrawer } from '@veltra/desktop'
 import type { CellAddress, SheetGrid } from '@veltra/sheet-core'
 import { Workbook } from '@veltra/sheet-core'
 import { bem } from '@veltra/utils'
-import { computed, nextTick, ref, shallowRef, useTemplateRef, watch } from 'vue'
+import { computed, nextTick, onScopeDispose, ref, shallowRef, useTemplateRef, watch } from 'vue'
 
 import type { ReportTemplate } from '../../report/template'
 import type { ConditionalRule } from '../../report/types'
@@ -149,7 +163,7 @@ import type {
 import { USheet } from '../sheet'
 import UReportDatasetHub from './designer-hub.vue'
 import { resolveGridDropAddress } from './designer/cell-coords'
-import { applyGridColWidths, readGridColWidths } from './designer/col-widths'
+import { applyGridColWidths, applySheetColWidths, readGridColWidths } from './designer/col-widths'
 import UReportDropHighlightOverlay from './designer/drop-highlight-overlay.vue'
 import UReportFloatPanel from './designer/float-panel.vue'
 import UReportRulesDialog from './designer/rules-dialog.vue'
@@ -166,7 +180,7 @@ const emit = defineEmits<ReportDesignerEmits>()
 
 const cls = bem('report-designer')
 
-/** 设计态网格尺寸（列宽捕获范围与之一致） */
+/** 设计态网格默认尺寸（新建模板；已声明尺寸后以模型为准，避免删行后被 props 撑回） */
 const DESIGN_ROWS = 24
 const DESIGN_COLS = 10
 
@@ -210,9 +224,38 @@ const {
   getTemplate
 } = designer
 
+/** 渲染行列数跟随模型（删行后不再被固定 props 经 ensureTableSize 撑回） */
+const gridRows = computed(() => {
+  const rows = workbook.value.activeSheet.rows
+  return rows > 0 ? rows : DESIGN_ROWS
+})
+const gridCols = computed(() => {
+  const cols = workbook.value.activeSheet.cols
+  return cols > 0 ? cols : DESIGN_COLS
+})
+
 const hubVisible = ref(false)
 const rulesDialogVisible = ref(false)
 
+const pickCandidateCells = computed((): CellAddress[] => {
+  if (!parentPick.value) return []
+  return parentPick.value.mode === 'row' ? rowParentCandidates.value : colParentCandidates.value
+})
+
+function onHubClose(): void {
+  hubVisible.value = false
+}
+
+watch(hubVisible, (open) => {
+  if (!open) emit('datasets-change')
+})
+
+watch(
+  () => designer.datasets.value,
+  () => emit('datasets-change'),
+  { deep: true }
+)
+
 const sheetRef = useTemplateRef<SheetExposed>('sheetRef')
 const previewViewerRef = useTemplateRef<ReportViewerExposed>('previewViewerRef')
 const gridHostRef = useTemplateRef<HTMLElement>('gridHostRef')
@@ -237,17 +280,21 @@ const isPreview = computed(() => viewMode.value === 'preview')
 const previewTemplate = shallowRef<ReportTemplate | null>(null)
 /** 预览工作簿自持（XLSX 导出需要拿到填充后的 sheet，05 票 workbook? prop 先例） */
 const previewWorkbook = new Workbook()
-/** 当前设计态列宽（sheet-core 列宽未进快照，经 VTable 运行时捕获；导出随快照写宽） */
+/** 当前设计态列宽（与 Sheet 模型同步；getTemplate 经 snapshot.colWidths 吐出） */
 const designColWidths = ref<Array<[number, number]>>([])
 const exporting = ref(false)
 
-/** 从当前设计网格捕获列宽（网格未就绪则保留旧值） */
+/** 从当前设计网格捕获列宽并写回 Sheet 模型（网格未就绪则保留旧值） */
 function captureDesignColWidths(): void {
   const widths = readGridColWidths(
     getDesignGrid(),
-    Array.from({ length: DESIGN_COLS }, (_, col) => col)
+    Array.from({ length: gridCols.value }, (_, col) => col)
   )
-  if (widths) designColWidths.value = widths
+  if (!widths) return
+  // 仅保留相对默认列宽有变化的条目，避免快照膨胀
+  const custom = widths.filter(([, width]) => width > 0)
+  designColWidths.value = custom
+  applySheetColWidths(workbook.value.activeSheet, custom)
 }
 
 /** 设计网格重建后补刷新与列宽（restore 不发 content-reset 的场景由 grid 自行订阅，这里只管列宽） */
@@ -268,11 +315,18 @@ function setViewMode(mode: ViewMode): void {
   if (mode === 'design') void nextTick(syncDesignGridView)
 }
 
-// 模板 prop 更换：组合式函数内完成载入；组件层切回设计态（预览内容随之作废）
+// 模板更换：组合式函数内完成载入；组件层切回设计态并恢复列宽
 watch(
   () => props.template,
-  () => {
+  (template) => {
     viewMode.value = 'design'
+    designColWidths.value = template?.colWidths?.length
+      ? template.colWidths.map(([col, width]) => [col, width] as [number, number])
+      : []
+    if (designColWidths.value.length) {
+      applySheetColWidths(workbook.value.activeSheet, designColWidths.value)
+    }
+    void nextTick(syncDesignGridView)
   }
 )
 
@@ -286,6 +340,11 @@ watch(catalog, () => {
   void nextTick(() => getDesignGrid()?.refresh())
 })
 
+const offStructureChange = workbook.value.activeSheet.on('structure-change', () => {
+  void nextTick(syncDesignGridView)
+})
+onScopeDispose(offStructureChange)
+
 async function exportPreviewXlsx(): Promise<void> {
   if (!isPreview.value || exporting.value) return
   const viewer = previewViewerRef.value
@@ -352,5 +411,10 @@ function onGridDrop(event: DragEvent): void {
   }
 }
 
-defineExpose<_ReportDesignerExposed>({ getTemplate })
+defineExpose<_ReportDesignerExposed>({
+  getTemplate: () => {
+    captureDesignColWidths()
+    return getTemplate()
+  }
+})
 </script>

package/src/components/report/report-viewer.vue

@@ -20,11 +20,13 @@
         ref="sheetRef"
         :class="cls.e('sheet')"
         :workbook="workbook"
-        :rows="renderRows"
-        :cols="renderCols"
+        :rows="renderSize.rows"
+        :cols="renderSize.cols"
         :show-toolbar="false"
         :show-formula-bar="false"
         :show-tabs="false"
+        :show-row-header="false"
+        :show-col-header="false"
         readonly
       />
     </div>
@@ -42,8 +44,9 @@ import { exportFilledReportXlsx } from '../../report/export-xlsx'
 import type { ReportViewerProps, _ReportViewerExposed } from '../../types'
 import type { SheetExposed } from '../../types'
 import { USheet } from '../sheet'
-import { applyGridColWidths, readGridColWidths } from './designer/col-widths'
+import { applyGridColWidths, applySheetColWidths } from './designer/col-widths'
 import UReportFilterBar from './filter-bar.vue'
+import { previewGridSize, type PreviewGridSizeMode } from './preview-grid-size'
 import { useReportViewer } from './use-report-viewer'
 
 defineOptions({ name: 'UReportViewer' })
@@ -52,10 +55,6 @@ const props = defineProps<ReportViewerProps>()
 
 const cls = bem('report-viewer')
 
-/** 网格最小渲染尺寸（与 playground 预览态一致）；Filled Report 超出时按快照尺寸放大 */
-const MIN_RENDER_ROWS = 50
-const MIN_RENDER_COLS = 10
-
 /** 取数未完成时拒绝导出的可读错误 */
 const EXPORT_NOT_READY_MESSAGE = '报表数据尚未就绪，请等待取数完成后再导出'
 const EXPORT_LOADING_MESSAGE = '报表数据加载中，请稍后再导出'
@@ -66,44 +65,54 @@ const workbook = computed(() => props.workbook ?? internalWorkbook)
 
 const sheetRef = useTemplateRef<SheetExposed>('sheetRef')
 
-const { params, values, loading, error, filledSnapshot, refresh, setValues } =
+const { params, values, loading, error, filledSnapshot, filledColWidths, refresh, setValues } =
   useReportViewer(props)
 
-const renderRows = computed(() =>
-  Math.max(MIN_RENDER_ROWS, filledSnapshot.value?.rows ?? 0, props.template.rows)
-)
-const renderCols = computed(() =>
-  Math.max(MIN_RENDER_COLS, filledSnapshot.value?.cols ?? 0, props.template.cols)
-)
+const renderSize = computed(() => {
+  const filled = filledSnapshot.value
+  if (filled) return previewGridSize(filled, 'filled')
+  return previewGridSize(props.template, 'template')
+})
 
-function exportColIndexes(): number[] {
-  return Array.from({ length: renderCols.value }, (_, col) => col)
-}
+/** 宿主显式传入优先；否则取数完成后用展开映射列宽；再回落模板设计态列宽 */
+const effectiveColWidths = computed(() => {
+  if (props.colWidths?.length) return props.colWidths
+  if (filledColWidths.value?.length) return filledColWidths.value
+  return props.template.colWidths
+})
 
-/** 将宿主传入的列宽写入 VTable 运行时（sheet-core 列宽未进快照） */
+/** 将运行时列宽写入模型与 VTable（模型为单一事实源；grid 构造/content-reset 也会回放） */
 function applyRuntimeColWidths(): void {
-  if (!props.colWidths?.length) return
-  applyGridColWidths(sheetRef.value?.getGrid(), props.colWidths)
+  if (!effectiveColWidths.value?.length) return
+  const sheet = workbook.value.activeSheet
+  applySheetColWidths(sheet, effectiveColWidths.value)
+  applyGridColWidths(sheetRef.value?.getGrid(), effectiveColWidths.value)
 }
 
 /**
- * restore 负责尺寸/冻结/行高/选区（静默），restoreContent 发 content-reset
+ * restore 负责尺寸/冻结/行高/列宽/选区（静默），restoreContent 发 content-reset
  * 触发网格全量刷新（grid 层订阅直刷，无需手动 flush）；history.clear 使填充不进 undo
  */
-function applySnapshot(snapshot: SheetSnapshot): void {
+function applySnapshot(snapshot: SheetSnapshot, mode: PreviewGridSizeMode): void {
+  const size = previewGridSize(snapshot, mode)
+  const trimmed: SheetSnapshot = { ...snapshot, rows: size.rows, cols: size.cols }
   const sheet = workbook.value.activeSheet
-  sheet.restore(snapshot)
-  sheet.restoreContent(snapshot)
+  sheet.restore(trimmed)
+  sheet.restoreContent(trimmed)
   sheet.history.clear()
   void nextTick(applyRuntimeColWidths)
 }
 
 // 先铺模板静态结构（取数期间 / 取数失败时可见），取数成功后替换为 Filled Report
-watch(() => props.template, applySnapshot, { immediate: true })
+watch(
+  () => props.template,
+  (template) => applySnapshot(template, 'template'),
+  { immediate: true }
+)
 watch(filledSnapshot, (filled) => {
-  if (filled) applySnapshot(filled)
+  if (filled) applySnapshot(filled, 'filled')
 })
-watch(() => props.colWidths, applyRuntimeColWidths)
+watch(effectiveColWidths, applyRuntimeColWidths)
 
 async function exportXlsx(): Promise<void> {
   if (loading.value) {
@@ -114,8 +123,7 @@ async function exportXlsx(): Promise<void> {
   }
 
   const sheet = workbook.value.activeSheet
-  const colWidths = readGridColWidths(sheetRef.value?.getGrid(), exportColIndexes()) ?? []
-  const buffer = await exportFilledReportXlsx(sheet, colWidths)
+  const buffer = await exportFilledReportXlsx(sheet)
   saveBlob(
     new Blob([buffer as unknown as BlobPart], {
       type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

package/src/components/report/style-designer.scss

@@ -62,6 +62,22 @@
     min-width: 0;
   }
 
+  @include m.e(pick-hint) {
+    position: absolute;
+    left: 50%;
+    bottom: fn.use-var(gap, small);
+    z-index: 17;
+    transform: translateX(-50%);
+    padding: 4px fn.use-var(gap, small);
+    border-radius: fn.use-var(radius, default);
+    background: color-mix(in srgb, fn.use-var(bg-color, top) 92%, transparent);
+    border: 1px dashed fn.use-var(color, primary);
+    font-size: fn.use-var(font-size-main, small);
+    color: fn.use-var(text-color, second);
+    pointer-events: none;
+    white-space: nowrap;
+  }
+
   /* 数据中枢 drawer 面板宽度（class 经 $attrs 落到 .u-drawer 面板；须压过 .u-drawer.is-right 的 320px） */
   @include m.e(hub-drawer) {
     &.u-drawer {
@@ -123,7 +139,7 @@
   }
 }
 
-/* Action Pill：选中绑定格上方的悬浮编辑卡（角色 / 聚合 / 条件样式 / 排序 / 清除绑定） */
+/* Action Pill：选中绑定格上方的悬浮编辑卡（预设 + 互补的展开/聚合 / 条件样式 / 排序 / 清除绑定） */
 @include m.b(report-float-panel) {
   position: absolute;
   z-index: 18;
@@ -223,7 +239,7 @@
   }
 
   @include m.e(parent-select) {
-    width: 88px;
+    width: 180px;
     flex: none;
   }
 
@@ -244,11 +260,12 @@
 @include m.b(report-rules-dialog) {
   display: flex;
   flex-direction: column;
-  gap: 12px;
+  gap: 10px;
 
   @include m.e(hint) {
     margin: 0;
     font-size: 12px;
+    line-height: 1.5;
     color: fn.use-var(text-color, second);
   }
 
@@ -278,17 +295,18 @@
   display: flex;
   align-items: flex-start;
   gap: 8px;
-  padding: 10px;
+  padding: 10px 10px 10px 6px;
   border: fn.use-var(border-muted);
   border-radius: 8px;
-  background: fn.use-var(bg-color, top);
+  background: fn.use-var(bg-color, middle);
 
   @include m.e(handle) {
     flex: none;
-    width: 20px;
-    margin-top: 4px;
-    color: fn.use-var(text-color, second);
-    font-size: 16px;
+    width: 16px;
+    margin-top: 6px;
+    color: fn.use-var(text-color, placeholder);
+    font-size: 12px;
+    letter-spacing: -1px;
     line-height: 1;
     cursor: grab;
     user-select: none;
@@ -307,32 +325,33 @@
     gap: 8px;
   }
 
-  @include m.e(meta) {
+  @include m.e(when) {
     display: flex;
     align-items: center;
-    gap: 8px;
+    gap: 6px;
     flex-wrap: wrap;
   }
 
-  @include m.e(field-select) {
-    width: 120px;
-    flex: none;
+  @include m.e(then) {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    flex-wrap: wrap;
   }
 
-  @include m.e(scope-select) {
-    width: 72px;
+  @include m.e(lead) {
     flex: none;
+    font-size: 12px;
+    color: fn.use-var(text-color, second);
   }
 
-  @include m.e(condition) {
-    display: grid;
-    grid-template-columns: 72px minmax(0, 1fr) auto;
-    align-items: center;
-    gap: 8px;
+  @include m.e(field-select) {
+    width: 128px;
+    flex: none;
   }
 
   @include m.e(operator) {
-    width: 72px;
+    width: 96px;
     flex: none;
   }
 
@@ -345,12 +364,12 @@
   }
 
   @include m.e(scalar-input) {
-    width: 112px;
+    width: 120px;
     flex: none;
   }
 
   @include m.e(between-input) {
-    width: 96px;
+    width: 88px;
     flex: none;
   }
 
@@ -359,18 +378,6 @@
     color: fn.use-var(text-color, second);
   }
 
-  @include m.e(style) {
-    display: flex;
-    align-items: center;
-    gap: 8px;
-    flex-wrap: wrap;
-  }
-
-  @include m.e(style-label) {
-    font-size: 12px;
-    color: fn.use-var(text-color, second);
-  }
-
   @include m.e(toggle) {
     min-width: 28px;
     padding-inline: 6px;
@@ -378,14 +385,11 @@
 
   @include m.e(preview) {
     flex: none;
-    margin-top: 2px;
   }
 
-  @include m.e(actions) {
+  @include m.e(remove) {
     flex: none;
-    display: flex;
-    flex-direction: column;
-    gap: 2px;
+    margin-top: 2px;
   }
 }
 

package/src/components/report/use-report-designer.ts

@@ -8,13 +8,16 @@ import {
   applyReportPreset,
   createReportBinding,
   formatCellAddress,
-  inferColParentCandidate,
   inferDropPreset,
-  inferRowParentCandidate,
+  inferParentsForPreset,
+  isColGroupBinding,
   isHorizontalExpandBinding,
+  isRowGroupBinding,
   isVerticalExpandBinding,
   listColParentCandidates,
-  listRowParentCandidates
+  listRowParentCandidates,
+  prefersGroupParent,
+  presetStillApplies
 } from '../../report/binding'
 import type { DataConnection, QueryResult, Result } from '../../report/connector'
 import { buildParamDefs } from '../../report/params'
@@ -227,10 +230,9 @@ export function useReportDesigner(options: UseReportDesignerOptions): UseReportD
     let binding = createReportBinding(dataset, fieldName)
     binding = applyReportPreset(binding, preset)
 
-    const rowParent = inferRowParentCandidate(target, getBindingAt)
-    if (rowParent) binding.rowParent = rowParent
-    const colParent = inferColParentCandidate(target, getBindingAt)
-    if (colParent) binding.colParent = colParent
+    const parents = inferParentsForPreset(target, preset, getBindingAt)
+    if (parents.rowParent) binding.rowParent = parents.rowParent
+    if (parents.colParent) binding.colParent = parents.colParent
 
     workbook.value.activeSheet.setCellMeta(target, REPORT_META_NAMESPACE, binding)
   }
@@ -276,14 +278,18 @@ export function useReportDesigner(options: UseReportDesignerOptions): UseReportD
     metaTick.value
     const binding = activeBinding.value
     if (!binding) return []
-    return listRowParentCandidates(binding, bindingEntries.value)
+    return listRowParentCandidates(binding, bindingEntries.value, {
+      preferGroup: prefersGroupParent(binding)
+    })
   })
 
   const colParentCandidates = computed((): CellAddress[] => {
     metaTick.value
     const binding = activeBinding.value
     if (!binding) return []
-    return listColParentCandidates(binding, bindingEntries.value)
+    return listColParentCandidates(binding, bindingEntries.value, {
+      preferGroup: prefersGroupParent(binding)
+    })
   })
 
   const bindingEntries = computed((): TopologyBindingEntry[] => {
@@ -296,6 +302,12 @@ export function useReportDesigner(options: UseReportDesignerOptions): UseReportD
     return entries
   })
 
+  function parentNeedsCorrection(addr: CellAddress | undefined): boolean {
+    if (!addr) return true
+    const parent = getBindingAt(addr)
+    return !parent || parent.aggregate === 'list'
+  }
+
   function patchActiveBinding(patch: Partial<ReportBinding>): void {
     const cell = activeCell.value
     const binding = activeBinding.value
@@ -304,7 +316,25 @@ export function useReportDesigner(options: UseReportDesignerOptions): UseReportD
     const next: ReportBinding = { ...binding, ...patch }
     if ('rowParent' in patch && patch.rowParent === undefined) delete next.rowParent
     if ('colParent' in patch && patch.colParent === undefined) delete next.colParent
-    if (('aggregate' in patch || 'expand' in patch) && !('preset' in patch)) delete next.preset
+    if (
+      ('aggregate' in patch || 'expand' in patch) &&
+      !('preset' in patch) &&
+      !presetStillApplies(next)
+    ) {
+      delete next.preset
+    }
+
+    if (patch.preset === 'subtotal') {
+      const inferred = inferParentsForPreset(cell, 'subtotal', getBindingAt)
+      if (parentNeedsCorrection(next.rowParent)) {
+        if (inferred.rowParent) next.rowParent = inferred.rowParent
+        else delete next.rowParent
+      }
+      if (parentNeedsCorrection(next.colParent)) {
+        if (inferred.colParent) next.colParent = inferred.colParent
+        else delete next.colParent
+      }
+    }
 
     workbook.value.activeSheet.setCellMeta(cell, REPORT_META_NAMESPACE, next)
   }
@@ -319,17 +349,36 @@ export function useReportDesigner(options: UseReportDesignerOptions): UseReportD
     parentPick.value = null
   }
 
+  function isValidParentTarget(
+    mode: ParentPickMode,
+    source: ReportBinding,
+    target: ReportBinding | undefined
+  ): boolean {
+    if (!target) return false
+    if (target.dataset !== source.dataset) return false
+    const groupOnly = prefersGroupParent(source)
+    if (mode === 'row') {
+      return groupOnly ? isRowGroupBinding(target) : isVerticalExpandBinding(target)
+    }
+    return groupOnly ? isColGroupBinding(target) : isHorizontalExpandBinding(target)
+  }
+
   function pickParentAt(target: CellAddress): void {
     const pick = parentPick.value
     if (!pick) return
     if (target.row === pick.source.row && target.col === pick.source.col) return
 
     const sourceBinding = getBindingAt(pick.source)
+    if (!sourceBinding) {
+      parentPick.value = null
+      return
+    }
+
     const targetBinding = getBindingAt(target)
-    if (!sourceBinding || !targetBinding) return
-    if (targetBinding.dataset !== sourceBinding.dataset) return
-    if (pick.mode === 'row' && !isVerticalExpandBinding(targetBinding)) return
-    if (pick.mode === 'col' && !isHorizontalExpandBinding(targetBinding)) return
+    if (!isValidParentTarget(pick.mode, sourceBinding, targetBinding)) {
+      workbook.value.activeSheet.selectCell(pick.source)
+      return
+    }
 
     const patch = pick.mode === 'row' ? { rowParent: { ...target } } : { colParent: { ...target } }
     const next: ReportBinding = { ...sourceBinding, ...patch }

package/src/components/report/use-report-viewer.ts

@@ -2,7 +2,8 @@ import type { SheetSnapshot } from '@veltra/sheet-core'
 import { computed, ref, shallowRef, watch, type ComputedRef, type Ref, type ShallowRef } from 'vue'
 
 import type { ConnectorError } from '../../report/connector'
-import { renderReport } from '../../report/render'
+import type { ReportColWidthEntry } from '../../report/export-xlsx'
+import { renderReport, resolveFilledColWidths } from '../../report/render'
 import {
   fetchTemplateRecords,
   resolveParamDefaults,
@@ -22,6 +23,8 @@ export interface UseReportViewerReturn {
   error: ShallowRef<ConnectorError | null>
   /** 最近一次成功展开渲染的 Filled Report 快照（组件壳据此替换网格内容） */
   filledSnapshot: ShallowRef<SheetSnapshot | null>
+  /** 展开后物理列宽（由模板 colWidths 映射；无模板列宽时为 undefined） */
+  filledColWidths: ShallowRef<ReadonlyArray<ReportColWidthEntry> | undefined>
   /** 重新取数并展开渲染 */
   refresh: () => Promise<void>
   /** Filter Bar 改值：写入新参数值并重新取数 */
@@ -36,6 +39,7 @@ export function useReportViewer(props: ReportViewerProps): UseReportViewerReturn
   const loading = ref(false)
   const error = shallowRef<ConnectorError | null>(null)
   const filledSnapshot = shallowRef<SheetSnapshot | null>(null)
+  const filledColWidths = shallowRef<ReadonlyArray<ReportColWidthEntry> | undefined>(undefined)
 
   const params = computed(() => resolveTemplateParams(props.template))
   // 初始值由下方 immediate watch 播种（参数默认值）
@@ -54,9 +58,13 @@ export function useReportViewer(props: ReportViewerProps): UseReportViewerReturn
     loading.value = false
     if (!result.ok) {
       error.value = result.error
+      filledColWidths.value = undefined
       return
     }
     filledSnapshot.value = renderReport(template, result.data)
+    filledColWidths.value = template.colWidths?.length
+      ? resolveFilledColWidths(template, result.data, template.colWidths)
+      : undefined
   }
 
   function setValues(next: ParamValues): void {
@@ -69,11 +77,12 @@ export function useReportViewer(props: ReportViewerProps): UseReportViewerReturn
     () => props.template,
     () => {
       filledSnapshot.value = null
+      filledColWidths.value = undefined
       values.value = resolveParamDefaults(params.value)
       void refresh()
     },
     { immediate: true }
   )
 
-  return { params, values, loading, error, filledSnapshot, refresh, setValues }
+  return { params, values, loading, error, filledSnapshot, filledColWidths, refresh, setValues }
 }