@veltra/sheet 2.1.1 → 2.3.0

package/src/tools/__test__/apply-style.test.ts

@@ -0,0 +1,129 @@
+import { createRange } from '@veltra/sheet-core/core/address'
+import { Sheet } from '@veltra/sheet-core/core/sheet'
+import { describe, expect, it } from 'vitest'
+
+import { classifySelectionStyleTarget, type SelectionStyleTarget } from '../apply-style'
+import { createSheetContext } from '../context'
+
+describe('classifySelectionStyleTarget', () => {
+  const cases: Array<{
+    name: string
+    range: ReturnType<typeof createRange>
+    rows: number
+    cols: number
+    expected: SelectionStyleTarget
+  }> = [
+    {
+      name: '整行（行号选区）',
+      range: createRange({ row: 2, col: 0 }, { row: 2, col: 25 }),
+      rows: 100,
+      cols: 26,
+      expected: 'row'
+    },
+    {
+      name: '多行整行',
+      range: createRange({ row: 1, col: 0 }, { row: 3, col: 25 }),
+      rows: 100,
+      cols: 26,
+      expected: 'row'
+    },
+    {
+      name: '整列（列头选区）',
+      range: createRange({ row: 0, col: 4 }, { row: 99, col: 4 }),
+      rows: 100,
+      cols: 26,
+      expected: 'col'
+    },
+    {
+      name: '局部区域',
+      range: createRange({ row: 0, col: 0 }, { row: 2, col: 2 }),
+      rows: 100,
+      cols: 26,
+      expected: 'cell'
+    },
+    {
+      name: '全表（行列皆满）→ 格样式',
+      range: createRange({ row: 0, col: 0 }, { row: 99, col: 25 }),
+      rows: 100,
+      cols: 26,
+      expected: 'cell'
+    }
+  ]
+
+  for (const c of cases) {
+    it(c.name, () => {
+      expect(classifySelectionStyleTarget(c.range, c.rows, c.cols)).toBe(c.expected)
+    })
+  }
+})
+
+describe('SheetContext.applyStyle', () => {
+  it('无 resolveGridSize：一律 setCellStyle', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    const range = createRange({ row: 0, col: 0 }, { row: 0, col: 25 })
+    ctx.applyStyle(range, { fill: { color: '#FF0000' } })
+    expect(sheet.getRowStyle(0)).toBeUndefined()
+    expect(sheet.getCellStyle({ row: 0, col: 0 })).toEqual({ fill: { color: '#FF0000' } })
+    expect(sheet.getCellStyle({ row: 0, col: 25 })).toEqual({ fill: { color: '#FF0000' } })
+  })
+
+  it('整行选区 → setRowStyle；插列后新空格继承填充', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet, undefined, {
+      resolveGridSize: () => ({ rows: 100, cols: 26 })
+    })
+    const range = createRange({ row: 1, col: 0 }, { row: 1, col: 25 })
+    ctx.applyStyle(range, { fill: { color: '#AABBCC' } })
+
+    expect(sheet.getRowStyle(1)).toEqual({ fill: { color: '#AABBCC' } })
+    // 不物化逐格样式
+    expect(sheet.getCellStyle({ row: 1, col: 0 })).toBeUndefined()
+    expect(sheet.getEffectiveStyle({ row: 1, col: 10 })).toEqual({ fill: { color: '#AABBCC' } })
+
+    sheet.insertCols(0, 1)
+    expect(sheet.getEffectiveStyle({ row: 1, col: 0 })).toEqual({ fill: { color: '#AABBCC' } })
+    expect(sheet.getEffectiveStyle({ row: 1, col: 26 })).toEqual({ fill: { color: '#AABBCC' } })
+  })
+
+  it('整列选区 → setColStyle；插行后新空格继承', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet, undefined, {
+      resolveGridSize: () => ({ rows: 50, cols: 10 })
+    })
+    const range = createRange({ row: 0, col: 2 }, { row: 49, col: 2 })
+    ctx.applyStyle(range, { font: { bold: true } })
+
+    expect(sheet.getColStyle(2)).toEqual({ font: { bold: true } })
+    expect(sheet.getCellStyle({ row: 0, col: 2 })).toBeUndefined()
+    expect(sheet.getEffectiveStyle({ row: 20, col: 2 })).toEqual({ font: { bold: true } })
+
+    sheet.insertRows(0, 1)
+    expect(sheet.getEffectiveStyle({ row: 0, col: 2 })).toEqual({ font: { bold: true } })
+  })
+
+  it('局部选区仍走 setCellStyle', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet, undefined, {
+      resolveGridSize: () => ({ rows: 100, cols: 26 })
+    })
+    const range = createRange({ row: 0, col: 0 }, { row: 0, col: 1 })
+    ctx.applyStyle(range, { fill: { color: '#112233' } })
+    expect(sheet.getRowStyle(0)).toBeUndefined()
+    expect(sheet.getCellStyle({ row: 0, col: 0 })).toEqual({ fill: { color: '#112233' } })
+    expect(sheet.getCellStyle({ row: 0, col: 1 })).toEqual({ fill: { color: '#112233' } })
+  })
+
+  it('applyStyle 整行写入进 undo', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet, undefined, {
+      resolveGridSize: () => ({ rows: 100, cols: 26 })
+    })
+    ctx.applyStyle(createRange({ row: 0, col: 0 }, { row: 0, col: 25 }), {
+      fill: { color: '#00FF00' }
+    })
+    expect(sheet.getRowStyle(0)).toBeDefined()
+    expect(ctx.undo()).toBe(true)
+    expect(sheet.getRowStyle(0)).toBeUndefined()
+  })
+})

package/src/tools/apply-style.ts

@@ -0,0 +1,41 @@
+import type { CellRange } from '@veltra/sheet-core/core/address'
+import type { SetAxisStyleItem } from '@veltra/sheet-core/core/command/set-axis-style'
+import type { CellStylePatch } from '@veltra/sheet-core/core/style/types'
+
+/** 样式写入目标：整行 / 整列默认样式，或逐格 */
+export type SelectionStyleTarget = 'row' | 'col' | 'cell'
+
+/**
+ * 按选区相对渲染网格的跨度判定样式写入目标（对齐 Excel）：
+ * - 跨满全部列且未跨满全部行 → 行默认样式（rowStyles）
+ * - 跨满全部行且未跨满全部列 → 列默认样式（colStyles）
+ * - 其余（含全表 / 局部）→ 单元格样式
+ */
+export function classifySelectionStyleTarget(
+  range: CellRange,
+  renderRows: number,
+  renderCols: number
+): SelectionStyleTarget {
+  const cols = Math.max(renderCols, 1)
+  const rows = Math.max(renderRows, 1)
+  const spansAllCols = range.start.col === 0 && range.end.col >= cols - 1
+  const spansAllRows = range.start.row === 0 && range.end.row >= rows - 1
+  if (spansAllCols && !spansAllRows) return 'row'
+  if (spansAllRows && !spansAllCols) return 'col'
+  return 'cell'
+}
+
+/** 整行/整列选区 → set-axis-style 写入项（partial）或清除项（clear） */
+export function axisStyleItemsForRange(
+  range: CellRange,
+  axis: 'row' | 'col',
+  patch: { partial: CellStylePatch } | { clear: true }
+): SetAxisStyleItem[] {
+  const start = axis === 'row' ? range.start.row : range.start.col
+  const end = axis === 'row' ? range.end.row : range.end.col
+  const items: SetAxisStyleItem[] = []
+  for (let index = start; index <= end; index++) {
+    items.push({ index, ...patch })
+  }
+  return items
+}

package/src/tools/builtin.ts

@@ -44,8 +44,8 @@ function toggleFontFlag(
 ): void {
   const sel = selectionRange(ctx)
   if (!sel) return
-  const on = ctx.getCellStyle(sel.activeCell)?.font?.[field] === true
-  ctx.setCellStyle(sel.range, { font: { [field]: on ? null : true } })
+  const on = ctx.getEffectiveStyle(sel.activeCell)?.font?.[field] === true
+  ctx.applyStyle(sel.range, { font: { [field]: on ? null : true } })
 }
 
 /** 对齐 toggle：点当前档 = 清除，点其它档 = 切换 */
@@ -56,11 +56,11 @@ function toggleAlign(
 ): void {
   const sel = selectionRange(ctx)
   if (!sel) return
-  const current = ctx.getCellStyle(sel.activeCell)?.align?.[axis]
+  const current = ctx.getEffectiveStyle(sel.activeCell)?.align?.[axis]
   if (current === value) {
-    ctx.setCellStyle(sel.range, { align: { [axis]: null } })
+    ctx.applyStyle(sel.range, { align: { [axis]: null } })
   } else {
-    ctx.setCellStyle(sel.range, { align: { [axis]: value } })
+    ctx.applyStyle(sel.range, { align: { [axis]: value } })
   }
 }
 
@@ -181,7 +181,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.font?.bold === true
+    return !!active && ctx.getEffectiveStyle(active)?.font?.bold === true
   },
   onClick: (ctx) => toggleFontFlag(ctx, 'bold')
 })
@@ -196,7 +196,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.font?.italic === true
+    return !!active && ctx.getEffectiveStyle(active)?.font?.italic === true
   },
   onClick: (ctx) => toggleFontFlag(ctx, 'italic')
 })
@@ -211,7 +211,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.font?.underline === true
+    return !!active && ctx.getEffectiveStyle(active)?.font?.underline === true
   },
   onClick: (ctx) => toggleFontFlag(ctx, 'underline')
 })
@@ -226,7 +226,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.font?.strikethrough === true
+    return !!active && ctx.getEffectiveStyle(active)?.font?.strikethrough === true
   },
   onClick: (ctx) => toggleFontFlag(ctx, 'strikethrough')
 })
@@ -265,7 +265,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.horizontal === 'left'
+    return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === 'left'
   },
   onClick: (ctx) => toggleAlign(ctx, 'horizontal', 'left')
 })
@@ -280,7 +280,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.horizontal === 'center'
+    return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === 'center'
   },
   onClick: (ctx) => toggleAlign(ctx, 'horizontal', 'center')
 })
@@ -295,7 +295,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.horizontal === 'right'
+    return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === 'right'
   },
   onClick: (ctx) => toggleAlign(ctx, 'horizontal', 'right')
 })
@@ -310,7 +310,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.vertical === 'top'
+    return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === 'top'
   },
   onClick: (ctx) => toggleAlign(ctx, 'vertical', 'top')
 })
@@ -325,7 +325,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.vertical === 'middle'
+    return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === 'middle'
   },
   onClick: (ctx) => toggleAlign(ctx, 'vertical', 'middle')
 })
@@ -340,7 +340,7 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.vertical === 'bottom'
+    return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === 'bottom'
   },
   onClick: (ctx) => toggleAlign(ctx, 'vertical', 'bottom')
 })
@@ -355,13 +355,13 @@ registerTool({
   disabled: (ctx) => !ctx.getSelection().activeCell,
   active: (ctx) => {
     const active = ctx.getSelection().activeCell
-    return !!active && ctx.getCellStyle(active)?.align?.wrap === true
+    return !!active && ctx.getEffectiveStyle(active)?.align?.wrap === true
   },
   onClick: (ctx) => {
     const sel = selectionRange(ctx)
     if (!sel) return
-    const on = ctx.getCellStyle(sel.activeCell)?.align?.wrap === true
-    ctx.setCellStyle(sel.range, { align: { wrap: on ? null : true } })
+    const on = ctx.getEffectiveStyle(sel.activeCell)?.align?.wrap === true
+    ctx.applyStyle(sel.range, { align: { wrap: on ? null : true } })
   }
 })
 
@@ -393,8 +393,8 @@ registerTool({
 })
 
 // ─── file（导入 / 导出）────────────────────────────────────
-// 导出 = 弹层选 xlsx / csv；导入 = 点击直接系统文件选择（vue/import-file.ts，
-// sheet.vue 覆盖 onClick；tools 层不 import vue）。
+// 导出 = 弹层选 xlsx / csv；导入 = 点击直接系统文件选择（components/sheet/import-file.ts，
+// sheet.vue 覆盖 onClick；tools 层不 import 组件层）。
 // 下载逻辑见 tools/download.ts（core/io 保持纯 TS 无头可测）。
 
 registerTool({

package/src/tools/context.ts

@@ -10,6 +10,8 @@ import type { FrozenState, Sheet } from '@veltra/sheet-core/core/sheet'
 import type { CellStyle, CellStylePatch } from '@veltra/sheet-core/core/style/types'
 import type { Workbook } from '@veltra/sheet-core/core/workbook'
 
+import { axisStyleItemsForRange, classifySelectionStyleTarget } from './apply-style'
+
 /**
  * SheetContext：工具的唯一操作门面。
  *
@@ -43,12 +45,33 @@ export interface SheetContext {
   getCellInfo(addr: CellAddress): CellInfo
 
   // ─── 样式（写入经命令系统，可 undo） ───────────────────────
-  /** 设置区域样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
+  /**
+   * 按选区形态写样式（Excel 语义）：
+   * 整行选区 → rowStyles；整列选区 → colStyles；其余 → 逐格。
+   * 判定依赖 createSheetContext 注入的渲染尺寸；未注入时一律走 setCellStyle。
+   */
+  applyStyle(range: CellRange, partial: CellStylePatch): void
+  /**
+   * 选区样式目标（与 applyStyle 同一判定）；未注入渲染尺寸时恒为 'cell'。
+   */
+  resolveStyleTarget(range: CellRange): 'row' | 'col' | 'cell'
+  /**
+   * 按选区形态清除样式：整行/整列清对应默认样式；其余清单元格 s。
+   * 未注入渲染尺寸时一律走 clearCellStyle。
+   */
+  clearStyle(range: CellRange): void
+  /** 设置区域单元格样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
   setCellStyle(range: CellRange, partial: CellStylePatch): void
-  /** 清除区域样式（保留值 / 公式） */
+  /** 清除区域单元格样式（保留值 / 公式） */
   clearCellStyle(range: CellRange): void
-  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined） */
+  /** 设置行默认样式（部分合并，进 undo） */
+  setRowStyle(row: number, partial: CellStylePatch): void
+  /** 设置列默认样式（部分合并，进 undo） */
+  setColStyle(col: number, partial: CellStylePatch): void
+  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined；不含行列默认） */
   getCellStyle(addr: CellAddress): CellStyle | undefined
+  /** 有效样式：列 → 行 → 格字段级叠加（空格可继承行列默认） */
+  getEffectiveStyle(addr: CellAddress): CellStyle | undefined
 
   // ─── 写入（全部经命令系统，可 undo） ───────────────────────
   setCellValue(addr: CellAddress, value: CellValue): void
@@ -105,6 +128,15 @@ export interface SheetContext {
   onImageChange(handler: (payload: { id?: string }) => void): () => void
 }
 
+/** createSheetContext 可选配置 */
+export interface SheetContextOptions {
+  /**
+   * 当前渲染网格尺寸（与 SheetGrid / resolveRenderSize 一致）。
+   * applyStyle / clearStyle 用其判定整行/整列；缺省时不走行列默认样式。
+   */
+  resolveGridSize?: () => { rows: number; cols: number }
+}
+
 /**
  * 创建工具上下文。
  * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
@@ -113,14 +145,21 @@ export interface SheetContext {
  *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
  *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
  *   workbook prop 后导出工具仍导出旧工作簿）
+ * @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
  */
 export function createSheetContext(
   resolveSheet: Sheet | (() => Sheet),
-  workbook?: Workbook | (() => Workbook)
+  workbook?: Workbook | (() => Workbook),
+  options?: SheetContextOptions
 ): SheetContext {
   const sheet = typeof resolveSheet === 'function' ? resolveSheet : () => resolveSheet
   const resolveWorkbook =
     typeof workbook === 'function' ? workbook : workbook != null ? () => workbook : undefined
+  const resolveGridSize = options?.resolveGridSize
+  const resolveTarget = (range: CellRange) => {
+    const size = resolveGridSize?.()
+    return size ? classifySelectionStyleTarget(range, size.rows, size.cols) : 'cell'
+  }
   return {
     get workbook() {
       return resolveWorkbook?.()
@@ -143,9 +182,33 @@ export function createSheetContext(
     mergeCells: (range) => sheet().mergeCells(range),
     unmergeCells: (range) => sheet().unmergeCells(range),
 
+    applyStyle: (range, partial) => {
+      const target = resolveTarget(range)
+      if (target === 'row' || target === 'col') {
+        const items = axisStyleItemsForRange(range, target, { partial })
+        if (items.length === 0) return
+        sheet().executeCommand('sheet.command.set-axis-style', { axis: target, items })
+        return
+      }
+      sheet().setCellStyle(range, partial)
+    },
+    resolveStyleTarget: (range) => resolveTarget(range),
+    clearStyle: (range) => {
+      const target = resolveTarget(range)
+      if (target === 'row' || target === 'col') {
+        const items = axisStyleItemsForRange(range, target, { clear: true })
+        if (items.length === 0) return
+        sheet().executeCommand('sheet.command.set-axis-style', { axis: target, items })
+        return
+      }
+      sheet().clearCellStyle(range)
+    },
     setCellStyle: (range, partial) => sheet().setCellStyle(range, partial),
     clearCellStyle: (range) => sheet().clearCellStyle(range),
+    setRowStyle: (row, partial) => sheet().setRowStyle(row, partial),
+    setColStyle: (col, partial) => sheet().setColStyle(col, partial),
     getCellStyle: (addr) => sheet().getCellStyle(addr),
+    getEffectiveStyle: (addr) => sheet().getEffectiveStyle(addr),
     executeCommand: <R = void>(commandId: string, params: unknown): R | undefined =>
       sheet().executeCommand<R>(commandId, params),
 

package/src/tools/index.ts

@@ -1,2 +1,3 @@
+export * from './apply-style'
 export * from './context'
 export * from './registry'

package/src/types/index.ts

@@ -1,7 +1,3 @@
 export * from './sheet'
-export type {
-  SheetImageType,
-  SheetImageAnchor,
-  SheetImage,
-  ImageInput
-} from '@veltra/sheet-core/core/image'
+export * from './report-viewer'
+export * from './report-designer'

package/src/types/report-designer.ts

@@ -0,0 +1,38 @@
+import type { Workbook } from '@veltra/sheet-core/core/workbook'
+import type { DeconstructValue } from '@veltra/utils'
+
+import type { DataConnection, DataConnector, ReportTemplate } from '../report'
+
+/** 报表设计器组件属性（ADR-0003 决策 2） */
+export interface ReportDesignerProps {
+  /** 数据连接器（如 `createHttpConnector({ endpoint })`）：数据中枢的测试连接 / 字段解析 / 记录预览均经它 */
+  connector: DataConnector
+  /**
+   * 数据连接列表（`v-model:connections`）：纯序列化对象，仅驻留内存；
+   * 凭据的持久化与安全存储完全由宿主掌控（ADR-0003 决策 4）
+   */
+  connections?: DataConnection[]
+  /**
+   * 载入既有 Report Template 继续设计：恢复网格绑定与设计态数据集；
+   * 内嵌连接按 id 合并进 `v-model:connections`（仅缺省时追加，宿主列表是单一事实源）
+   */
+  template?: ReportTemplate
+  /** 承载设计态的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
+  workbook?: Workbook
+}
+
+/** 报表设计器组件定义的事件 */
+export interface ReportDesignerEmits {
+  (e: 'update:connections', value: DataConnection[]): void
+  /** 数据集增删改或数据中枢关闭：宿主可立即持久化工作区 */
+  (e: 'datasets-change'): void
+}
+
+/** 在组件内部引用 */
+export interface _ReportDesignerExposed {
+  /** 取回含 meta 绑定与内嵌数据集定义的可序列化 Report Template */
+  getTemplate: () => ReportTemplate
+}
+
+/** 报表设计器组件暴露的方法 */
+export type ReportDesignerExposed = DeconstructValue<_ReportDesignerExposed>

package/src/types/report-viewer.ts

@@ -0,0 +1,37 @@
+import type { Workbook } from '@veltra/sheet-core/core/workbook'
+import type { DeconstructValue } from '@veltra/utils'
+
+import type { DataConnector, ReportTemplate } from '../report'
+import type { ReportColWidthEntry } from '../report/export-xlsx'
+
+/** 报表查看器组件属性（ADR-0003 决策 2） */
+export interface ReportViewerProps {
+  /** 数据连接器（如 `createHttpConnector({ endpoint })`） */
+  connector: DataConnector
+  /**
+   * 自包含 Report Template（SheetSnapshot + 内嵌数据集定义，见 `ReportTemplate`）：
+   * 查看器据此提取实际绑定数据集的查询参数并集生成 Filter Bar，并经连接器取数展开渲染
+   */
+  template: ReportTemplate
+  /** 承载填充报表的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
+  workbook?: Workbook
+  /**
+   * 列宽显式覆盖（可选）：优先于模板 `colWidths` / 展开映射结果写入模型与网格。
+   * 列宽已进 `SheetSnapshot.colWidths`，通常无需再传。
+   */
+  colWidths?: ReadonlyArray<ReportColWidthEntry>
+}
+
+/** 在组件内部引用 */
+export interface _ReportViewerExposed {
+  /** 重新取数并展开渲染（外部状态变化后主动刷新报表） */
+  refresh: () => Promise<void>
+  /**
+   * 导出填充报表为 XLSX（取数完成前拒绝；内部读取填充 sheet 与运行时列宽）。
+   * 不内置导出按钮，工具栏由下游决定。
+   */
+  exportXlsx: () => Promise<void>
+}
+
+/** 报表查看器组件暴露的方法 */
+export type ReportViewerExposed = DeconstructValue<_ReportViewerExposed>

package/src/types/sheet.ts

@@ -1,6 +1,11 @@
 import type { Sheet } from '@veltra/sheet-core/core/sheet'
 import type { Workbook } from '@veltra/sheet-core/core/workbook'
-import type { SheetGrid } from '@veltra/sheet-core/grid/sheet-grid'
+import type {
+  ResolveCellRenderer,
+  ResolveCellStyleHook,
+  ResolveDisplayValue,
+  SheetGrid
+} from '@veltra/sheet-core/grid/sheet-grid'
 import type { DeconstructValue } from '@veltra/utils'
 import type { ComputedRef } from 'vue'
 
@@ -14,12 +19,32 @@ export interface SheetProps {
   rows?: number
   /** 渲染列数，默认 26（A..Z） */
   cols?: number
+  /**
+   * 显示值覆盖（设计态 Binding Placeholder 等）：覆盖 VTable record，不写 CellData.v
+   */
+  resolveDisplayValue?: ResolveDisplayValue
+  /**
+   * 动态单元格样式：视口渲染时叠加条件样式补丁，不写 CellData.s / StylePool
+   */
+  resolveCellStyle?: ResolveCellStyleHook
+  /**
+   * 动态单元格渲染（ADR-0004）：视口布局时按格自定义渲染形态（VTable
+   * customLayout，布局构建用 sheet-core 导出的 CustomLayout），返回 undefined
+   * 回落默认渲染；不写模型、不进快照
+   */
+  resolveCellRenderer?: ResolveCellRenderer
   /** 是否显示工具栏，默认 true */
   showToolbar?: boolean
   /** 是否显示顶部公式栏（名称框 + fx 输入栏），默认 true */
   showFormulaBar?: boolean
   /** 是否显示底部 sheet 标签栏，默认 true */
   showTabs?: boolean
+  /** 是否显示行号列，默认 true */
+  showRowHeader?: boolean
+  /** 是否显示列字母表头，默认 true */
+  showColHeader?: boolean
+  /** 只读预览（关闭编辑回写、填充柄等写入口） */
+  readonly?: boolean
 }
 
 export interface SheetEmits {