@veltra/sheet 2.0.0 → 2.1.1

package/src/tools/builtin.ts

@@ -1,17 +1,83 @@
-import { rangesEqual } from '../core/address'
+import { FontColor } from '@veltra/icons/colorful'
+import {
+  AlignBottom,
+  AlignCenter,
+  AlignTop,
+  Bold,
+  Border,
+  Download,
+  Fill,
+  FontSize,
+  Italic,
+  MergeCells,
+  PictureRounded,
+  Rollback,
+  Rollfront,
+  Search,
+  Strikethrough,
+  Underline,
+  UnmergeCells,
+  Upload,
+  VerticalAlignCenter,
+  VerticalAlignLeft,
+  VerticalAlignRight,
+  Wrap
+} from '@veltra/icons/normal'
+import { rangesEqual } from '@veltra/sheet-core/core/address'
+import type { HorizontalAlign, VerticalAlign } from '@veltra/sheet-core/core/style/types'
+
+import type { SheetContext } from './context'
 import { registerTool } from './registry'
 
+/** 取活动格所在首选区；无选区返回 null */
+function selectionRange(ctx: SheetContext) {
+  const { activeCell, ranges } = ctx.getSelection()
+  const range = ranges[0]
+  if (!activeCell || !range) return null
+  return { activeCell, range }
+}
+
+/** 字体 toggle：以活动格当前值为基准，对选区统一翻转（Excel 语义） */
+function toggleFontFlag(
+  ctx: SheetContext,
+  field: 'bold' | 'italic' | 'underline' | 'strikethrough'
+): 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 } })
+}
+
+/** 对齐 toggle：点当前档 = 清除，点其它档 = 切换 */
+function toggleAlign(
+  ctx: SheetContext,
+  axis: 'horizontal' | 'vertical',
+  value: HorizontalAlign | VerticalAlign
+): void {
+  const sel = selectionRange(ctx)
+  if (!sel) return
+  const current = ctx.getCellStyle(sel.activeCell)?.align?.[axis]
+  if (current === value) {
+    ctx.setCellStyle(sel.range, { align: { [axis]: null } })
+  } else {
+    ctx.setCellStyle(sel.range, { align: { [axis]: value } })
+  }
+}
+
 /**
- * 内置工具（dogfood 扩展机制）：undo/redo + 合并/取消合并。
+ * 内置工具（dogfood 扩展机制）。
  *
+ * 分组：history ｜ cell ｜ text ｜ edit ｜ insert ｜ file。
  * 与第三方工具走同一注册通道，可由宿主 unregisterTool 移除或同 id 覆盖。
- * 本模块由 tools/index.ts 引入（与 core/command 的 default-registry 同构）：
- * 经包入口导入即完成注册，无头使用 core 深导入不涉及此全局副作用。
+ * 本模块由包入口引入：经包入口导入即完成注册。
  */
 
+// ─── history ───────────────────────────────────────────────
+
 registerTool({
   id: 'undo',
   title: '撤销',
+  icon: Rollback,
   tooltip: '撤销（Ctrl/Cmd+Z）',
   group: 'history',
   order: 0,
@@ -24,6 +90,7 @@ registerTool({
 registerTool({
   id: 'redo',
   title: '重做',
+  icon: Rollfront,
   tooltip: '重做（Ctrl/Cmd+Shift+Z 或 Ctrl+Y）',
   group: 'history',
   order: 1,
@@ -33,12 +100,39 @@ registerTool({
   }
 })
 
+// ─── cell（边框 / 填充颜色 / 合并 / 取消合并）────────────────
+
+registerTool({
+  id: 'border',
+  title: '边框',
+  icon: Border,
+  tooltip: '设置单元格边框',
+  group: 'cell',
+  order: 0,
+  popup: 'border',
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  onClick: () => {}
+})
+
+registerTool({
+  id: 'fill-color',
+  title: '填充颜色',
+  icon: Fill,
+  tooltip: '设置单元格背景填充',
+  group: 'cell',
+  order: 1,
+  popup: 'fill-color',
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  onClick: () => {}
+})
+
 registerTool({
   id: 'merge',
   title: '合并',
+  icon: MergeCells,
   tooltip: '合并选中区域',
   group: 'cell',
-  order: 0,
+  order: 2,
   disabled: (ctx) => {
     const { activeCell, ranges } = ctx.getSelection()
     const range = ranges[0]
@@ -59,9 +153,10 @@ registerTool({
 registerTool({
   id: 'unmerge',
   title: '取消合并',
+  icon: UnmergeCells,
   tooltip: '取消活动格所在合并',
   group: 'cell',
-  order: 1,
+  order: 3,
   disabled: (ctx) => {
     const { activeCell } = ctx.getSelection()
     if (!activeCell) return true
@@ -73,3 +168,252 @@ registerTool({
     ctx.unmergeCells(ranges[0])
   }
 })
+
+// ─── text（B/I/U/S / 字体颜色 / 字号 / 对齐×6 / 自动换行）────
+
+registerTool({
+  id: 'bold',
+  title: '加粗',
+  icon: Bold,
+  tooltip: '加粗',
+  group: 'text',
+  order: 0,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.font?.bold === true
+  },
+  onClick: (ctx) => toggleFontFlag(ctx, 'bold')
+})
+
+registerTool({
+  id: 'italic',
+  title: '斜体',
+  icon: Italic,
+  tooltip: '斜体',
+  group: 'text',
+  order: 1,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.font?.italic === true
+  },
+  onClick: (ctx) => toggleFontFlag(ctx, 'italic')
+})
+
+registerTool({
+  id: 'underline',
+  title: '下划线',
+  icon: Underline,
+  tooltip: '下划线',
+  group: 'text',
+  order: 2,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.font?.underline === true
+  },
+  onClick: (ctx) => toggleFontFlag(ctx, 'underline')
+})
+
+registerTool({
+  id: 'strikethrough',
+  title: '删除线',
+  icon: Strikethrough,
+  tooltip: '删除线',
+  group: 'text',
+  order: 3,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.font?.strikethrough === true
+  },
+  onClick: (ctx) => toggleFontFlag(ctx, 'strikethrough')
+})
+
+registerTool({
+  id: 'font-color',
+  title: '字体颜色',
+  icon: FontColor,
+  tooltip: '设置字体颜色',
+  group: 'text',
+  order: 4,
+  popup: 'font-color',
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  onClick: () => {}
+})
+
+registerTool({
+  id: 'font-size',
+  title: '字号',
+  icon: FontSize,
+  tooltip: '设置字体大小',
+  group: 'text',
+  order: 5,
+  popup: 'font-size',
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  onClick: () => {}
+})
+
+registerTool({
+  id: 'align-left',
+  title: '左对齐',
+  icon: VerticalAlignLeft,
+  tooltip: '水平左对齐',
+  group: 'text',
+  order: 6,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.align?.horizontal === 'left'
+  },
+  onClick: (ctx) => toggleAlign(ctx, 'horizontal', 'left')
+})
+
+registerTool({
+  id: 'align-center',
+  title: '居中',
+  icon: VerticalAlignCenter,
+  tooltip: '水平居中',
+  group: 'text',
+  order: 7,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.align?.horizontal === 'center'
+  },
+  onClick: (ctx) => toggleAlign(ctx, 'horizontal', 'center')
+})
+
+registerTool({
+  id: 'align-right',
+  title: '右对齐',
+  icon: VerticalAlignRight,
+  tooltip: '水平右对齐',
+  group: 'text',
+  order: 8,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.align?.horizontal === 'right'
+  },
+  onClick: (ctx) => toggleAlign(ctx, 'horizontal', 'right')
+})
+
+registerTool({
+  id: 'valign-top',
+  title: '顶端对齐',
+  icon: AlignTop,
+  tooltip: '垂直顶端对齐',
+  group: 'text',
+  order: 9,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.align?.vertical === 'top'
+  },
+  onClick: (ctx) => toggleAlign(ctx, 'vertical', 'top')
+})
+
+registerTool({
+  id: 'valign-middle',
+  title: '垂直居中',
+  icon: AlignCenter,
+  tooltip: '垂直居中对齐',
+  group: 'text',
+  order: 10,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.align?.vertical === 'middle'
+  },
+  onClick: (ctx) => toggleAlign(ctx, 'vertical', 'middle')
+})
+
+registerTool({
+  id: 'valign-bottom',
+  title: '底端对齐',
+  icon: AlignBottom,
+  tooltip: '垂直底端对齐',
+  group: 'text',
+  order: 11,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(active)?.align?.vertical === 'bottom'
+  },
+  onClick: (ctx) => toggleAlign(ctx, 'vertical', 'bottom')
+})
+
+registerTool({
+  id: 'wrap-text',
+  title: '自动换行',
+  icon: Wrap,
+  tooltip: '自动换行',
+  group: 'text',
+  order: 12,
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  active: (ctx) => {
+    const active = ctx.getSelection().activeCell
+    return !!active && ctx.getCellStyle(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 } })
+  }
+})
+
+// ─── edit（查找）───────────────────────────────────────────
+
+registerTool({
+  id: 'find',
+  title: '查找',
+  icon: Search,
+  tooltip: '查找与替换（Ctrl/Cmd+F）',
+  group: 'edit',
+  order: 0,
+  popup: 'find',
+  onClick: () => {}
+})
+
+// ─── insert（插入图片）─────────────────────────────────────
+
+registerTool({
+  id: 'insert-image',
+  title: '插入图片',
+  icon: PictureRounded,
+  tooltip: '插入浮动图片',
+  group: 'insert',
+  order: 0,
+  popup: 'insert-image',
+  disabled: (ctx) => !ctx.getSelection().activeCell,
+  onClick: () => {}
+})
+
+// ─── file（导入 / 导出）────────────────────────────────────
+// 导出 = 弹层选 xlsx / csv；导入 = 点击直接系统文件选择（vue/import-file.ts，
+// sheet.vue 覆盖 onClick；tools 层不 import vue）。
+// 下载逻辑见 tools/download.ts（core/io 保持纯 TS 无头可测）。
+
+registerTool({
+  id: 'import',
+  title: '导入',
+  icon: Download,
+  tooltip: '从 .xlsx / .csv 文件导入',
+  group: 'file',
+  order: 0,
+  onClick: () => {}
+})
+
+registerTool({
+  id: 'export',
+  title: '导出',
+  icon: Upload,
+  tooltip: '导出为 Excel 或 CSV',
+  group: 'file',
+  order: 1,
+  popup: 'export',
+  onClick: () => {}
+})

package/src/tools/context.ts

@@ -1,10 +1,14 @@
-import type { CellAddress, CellRange } from '../core/address'
-import type { CellData, CellValue } from '../core/cell-store'
-import type { HistoryState } from '../core/command/history'
-import type { SetCellValueItem } from '../core/command/set-cell-value'
-import type { CellInfo } from '../core/merge-manager'
-import type { SelectionState } from '../core/selection'
-import type { Sheet } from '../core/sheet'
+import type { CellAddress, CellRange } from '@veltra/sheet-core/core/address'
+import type { CellData, CellValue } from '@veltra/sheet-core/core/cell-store'
+import type { HistoryState } from '@veltra/sheet-core/core/command/history'
+import type { ImageUpdateFields } from '@veltra/sheet-core/core/command/image'
+import type { SetCellValueItem } from '@veltra/sheet-core/core/command/set-cell-value'
+import type { ImageInput, SheetImage } from '@veltra/sheet-core/core/image'
+import type { CellInfo } from '@veltra/sheet-core/core/merge-manager'
+import type { SelectionState } from '@veltra/sheet-core/core/selection'
+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'
 
 /**
  * SheetContext：工具的唯一操作门面。
@@ -18,12 +22,17 @@ import type { Sheet } from '../core/sheet'
 export interface SheetContext {
   /** 当前活动 sheet 名 */
   readonly sheetName: string
+  /**
+   * 当前工作簿（导入导出等需要工作簿级操作的场景；无头/单 sheet 场景可能为 undefined）。
+   * 只读引用：sheet 增删改名等结构操作仍应经宿主直接操作 Workbook（Phase 3 门面边界）。
+   */
+  readonly workbook?: Workbook
 
   // ─── 选区 ────────────────────────────────────────────────
   getSelection(): SelectionState
   /** 选中单格（被覆盖格自动定位锚点） */
   selectCell(addr: CellAddress): void
-  selectRange(range: CellRange): void
+  selectRange(range: CellRange, active?: CellAddress): void
 
   // ─── 读取 ────────────────────────────────────────────────
   /** 原始存储语义读取（被合并覆盖格 → undefined） */
@@ -33,6 +42,14 @@ export interface SheetContext {
   /** 合并语义下的单元格信息（普通格 / 合并锚点 / 被覆盖格） */
   getCellInfo(addr: CellAddress): CellInfo
 
+  // ─── 样式（写入经命令系统，可 undo） ───────────────────────
+  /** 设置区域样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
+  setCellStyle(range: CellRange, partial: CellStylePatch): void
+  /** 清除区域样式（保留值 / 公式） */
+  clearCellStyle(range: CellRange): void
+  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined） */
+  getCellStyle(addr: CellAddress): CellStyle | undefined
+
   // ─── 写入（全部经命令系统，可 undo） ───────────────────────
   setCellValue(addr: CellAddress, value: CellValue): void
   setCellFormula(addr: CellAddress, formula: string): void
@@ -54,26 +71,67 @@ export interface SheetContext {
   readonly canUndo: boolean
   readonly canRedo: boolean
 
+  // ─── 冻结（模型状态，不进 undo；随快照序列化） ──────────────
+  /** 当前冻结状态（rows = 冻结顶部行数，cols = 冻结左侧列数） */
+  readonly frozen: FrozenState
+  /** 设置冻结行列数（不进 undo，同 rowHeights 先例） */
+  setFrozen(rows: number, cols: number): void
+
+  // ─── 行列插入/删除（结构变更，可 undo） ──────────────────
+  /** 插入 count 行到 at 行之前 */
+  insertRows(at: number, count?: number): void
+  /** 插入 count 列到 at 列之前 */
+  insertCols(at: number, count?: number): void
+  /** 删除 [at, at+count) 行 */
+  deleteRows(at: number, count?: number): void
+  /** 删除 [at, at+count) 列 */
+  deleteCols(at: number, count?: number): void
+
+  // ─── 浮动图片（写入经命令系统，可 undo） ──────────────────
+  /** 插入浮动图片；返回生成的 id */
+  insertImage(input: ImageInput): string
+  /** 删除浮动图片；不存在则无操作 */
+  removeImage(id: string): void
+  /** 更新浮动图片锚点/尺寸/文案；不存在或无变更则无操作 */
+  updateImage(id: string, patch: ImageUpdateFields): void
+  /** 只读图片列表（快照副本） */
+  getImages(): readonly SheetImage[]
+
   // ─── 事件订阅（订阅时绑定到当前活动 sheet；tab 切换后需重新订阅） ──
   onSelectionChange(handler: (state: SelectionState) => void): () => void
   onHistoryChange(handler: (state: HistoryState) => void): () => void
+  onFrozenChange(handler: (state: FrozenState) => void): () => void
+  /** 图片集合变化（单图带 id；整表替换时 id 缺省） */
+  onImageChange(handler: (payload: { id?: string }) => void): () => void
 }
 
 /**
  * 创建工具上下文。
  * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
  *   tab 切换后上下文自动指向当前 sheet）；也可直接传 Sheet 实例（无头 / 测试场景）
+ * @param workbook 当前工作簿（导入导出等工具需要；无头 / 单 sheet 场景可省略）。
+ *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
+ *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
+ *   workbook prop 后导出工具仍导出旧工作簿）
  */
-export function createSheetContext(resolveSheet: Sheet | (() => Sheet)): SheetContext {
+export function createSheetContext(
+  resolveSheet: Sheet | (() => Sheet),
+  workbook?: Workbook | (() => Workbook)
+): SheetContext {
   const sheet = typeof resolveSheet === 'function' ? resolveSheet : () => resolveSheet
+  const resolveWorkbook =
+    typeof workbook === 'function' ? workbook : workbook != null ? () => workbook : undefined
   return {
+    get workbook() {
+      return resolveWorkbook?.()
+    },
     get sheetName() {
       return sheet().name
     },
 
     getSelection: () => sheet().getSelection(),
     selectCell: (addr) => sheet().selectCell(addr),
-    selectRange: (range) => sheet().selectRange(range),
+    selectRange: (range, active) => sheet().selectRange(range, active),
 
     getCellData: (addr) => sheet().getCellData(addr),
     getDisplayValue: (addr) => sheet().getDisplayValue(addr),
@@ -84,9 +142,27 @@ export function createSheetContext(resolveSheet: Sheet | (() => Sheet)): SheetCo
     setCells: (items) => sheet().setCells(items),
     mergeCells: (range) => sheet().mergeCells(range),
     unmergeCells: (range) => sheet().unmergeCells(range),
+
+    setCellStyle: (range, partial) => sheet().setCellStyle(range, partial),
+    clearCellStyle: (range) => sheet().clearCellStyle(range),
+    getCellStyle: (addr) => sheet().getCellStyle(addr),
     executeCommand: <R = void>(commandId: string, params: unknown): R | undefined =>
       sheet().executeCommand<R>(commandId, params),
 
+    get frozen() {
+      return sheet().frozen
+    },
+    setFrozen: (rows, cols) => sheet().setFrozen(rows, cols),
+    insertRows: (at, count) => sheet().insertRows(at, count),
+    insertCols: (at, count) => sheet().insertCols(at, count),
+    deleteRows: (at, count) => sheet().deleteRows(at, count),
+    deleteCols: (at, count) => sheet().deleteCols(at, count),
+
+    insertImage: (input) => sheet().insertImage(input),
+    removeImage: (id) => sheet().removeImage(id),
+    updateImage: (id, patch) => sheet().updateImage(id, patch),
+    getImages: () => sheet().getImages(),
+
     beginTransaction: () => sheet().beginTransaction(),
     commit: () => sheet().commit(),
     rollback: () => sheet().rollback(),
@@ -101,6 +177,8 @@ export function createSheetContext(resolveSheet: Sheet | (() => Sheet)): SheetCo
     },
 
     onSelectionChange: (handler) => sheet().on('selection-change', handler),
-    onHistoryChange: (handler) => sheet().on('history-change', handler)
+    onHistoryChange: (handler) => sheet().on('history-change', handler),
+    onFrozenChange: (handler) => sheet().on('frozen-change', handler),
+    onImageChange: (handler) => sheet().on('image-change', handler)
   }
 }

package/src/tools/download.ts

@@ -0,0 +1,82 @@
+import { saveBlob } from '@cat-kit/fe'
+import { exportSheetCsv, exportWorkbookXlsx } from '@veltra/sheet-core/core/io/export'
+import type { Workbook } from '@veltra/sheet-core/core/workbook'
+
+import type { SheetContext } from './context'
+import type { ExportWorkerPayload, ExportWorkerResponse } from './export.worker'
+
+/**
+ * 大工作簿的 XLSX 导出（hucre 序列化 + ZIP 压缩为秒级同步重活）移入 Web Worker：
+ * 主线程只采集快照（结构化克隆友好的纯数据，行高随 SheetSnapshot.rowHeights
+ * 携带），序列化与压缩在 worker 线程进行。worker 不可用（极端环境 / 打包产物
+ * 缺文件）回退主线程导出——与导入侧 parseXlsxAsync 同一模式。
+ */
+async function exportWorkbookXlsxAsync(workbook: Workbook): Promise<Uint8Array> {
+  let worker: Worker | undefined
+  try {
+    // new URL 模式：dev（vite）与 build（rolldown）都支持把 worker 提为独立
+    // chunk（与 import.worker 一致）；onerror 再兜底降级主线程
+    const url = import.meta.env?.DEV
+      ? new URL('./export.worker.ts', import.meta.url)
+      : new URL('./export.worker.js', import.meta.url)
+    worker = new Worker(url, { type: 'module' })
+  } catch {
+    return exportWorkbookXlsx(workbook)
+  }
+  const payload: ExportWorkerPayload = {
+    sheets: workbook.getSheets().map((sheet) => ({ name: sheet.name, snapshot: sheet.snapshot() })),
+    activeIndex: workbook.activeSheetIndex
+  }
+  return await new Promise<Uint8Array>((resolve, reject) => {
+    let settled = false
+    // worker 加载/启动失败（如打包产物缺文件）→ 降级主线程导出
+    const fallback = (): void => {
+      if (settled) return
+      settled = true
+      worker!.terminate()
+      resolve(exportWorkbookXlsx(workbook))
+    }
+    worker!.onmessage = (e: MessageEvent<ExportWorkerResponse>) => {
+      if (settled) return
+      settled = true
+      worker!.terminate()
+      const data = e.data
+      if (!data.ok || !data.buffer) {
+        reject(new Error(data.error ?? 'worker 导出失败'))
+        return
+      }
+      resolve(data.buffer)
+    }
+    worker!.onerror = () => fallback()
+    worker!.postMessage(payload)
+  })
+}
+
+/**
+ * 导出当前工作簿为 .xlsx（无 workbook 时空操作）。
+ * 下载动作复用 @cat-kit/fe 的 saveBlob（#28：不再自研 Object URL + a.click）。
+ * hucre 1.0 起 writeXlsx 会校验 sheet 名（Excel 非法字符 / 超长 / 保留名）并抛
+ * InvalidArgumentError——失败经返回的 Promise 传播，调用方（导出面板）负责提示。
+ */
+export async function exportWorkbookFile(ctx: SheetContext): Promise<void> {
+  const workbook = ctx.workbook
+  if (!workbook) return
+  const buffer = await exportWorkbookXlsxAsync(workbook)
+  saveBlob(
+    new Blob([buffer as unknown as BlobPart], {
+      type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    }),
+    `${workbook.activeSheet.name || 'workbook'}.xlsx`
+  )
+}
+
+/** 导出当前工作表为 .csv（无 workbook 时空操作；同步，异常直接抛给调用方） */
+export function exportSheetCsvFile(ctx: SheetContext): void {
+  const workbook = ctx.workbook
+  if (!workbook) return
+  const csv = exportSheetCsv(workbook.activeSheet)
+  saveBlob(
+    new Blob([csv], { type: 'text/csv;charset=utf-8' }),
+    `${workbook.activeSheet.name || 'sheet'}.csv`
+  )
+}