@veltra/sheet 2.5.8 → 2.7.0

package/src/components/sheet/sheet-context-menu.ts

@@ -4,6 +4,7 @@ import type { NumFmt } from '@veltra/sheet-core/core/style/types.js'
 import { defineComponent, h } from 'vue'
 
 import type { SheetContext } from '../../tools/context'
+import { MIN_ROW_COL_SIZE } from '../../tools/context'
 import { defaultToolRegistry } from '../../tools/registry'
 import InsertCountMenuItem from './insert-count-menu-item.vue'
 import { pickAndInsertImage } from './insert-image'
@@ -16,6 +17,13 @@ export const INSERT_COUNT_MAX = 1000
 export const DECIMAL_PLACES_MIN = 0
 export const DECIMAL_PLACES_MAX = 10
 
+/** 行高/列宽数值项输入上限（下限复用门面 MIN_ROW_COL_SIZE，对齐引擎 resize 最小值） */
+export const AXIS_SIZE_MAX = 1000
+
+/** 数值项默认值回落：未设置自定义尺寸时展示引擎默认行高/列宽（对齐 sheet-core grid-theme） */
+export const FALLBACK_ROW_HEIGHT = 28
+export const FALLBACK_COL_WIDTH = 80
+
 /** 选区覆盖行/列数 → 插入默认 N（min 1 / max 1000） */
 export function defaultInsertCount(range: CellRange | null, axis: 'row' | 'col'): number {
   if (!range) return INSERT_COUNT_MIN
@@ -94,12 +102,46 @@ function insertCountRender(options: {
   return menuNumberRender({ ...options, min: INSERT_COUNT_MIN, max: INSERT_COUNT_MAX })
 }
 
+/** 行号/列头菜单选项（readonly 时尺寸项禁用） */
+export interface HeaderMenuOptions {
+  /** 只读模式：行高/列宽项禁用（尺寸写入属编辑操作） */
+  readonly?: boolean
+}
+
+/**
+ * 行高/列宽菜单项：内嵌数值输入，确认经门面批量应用到选区覆盖行/列。
+ * readonly 时降级为禁用文本项——render 内嵌组件自带点击路径，disabled 拦不住。
+ */
+function axisSizeMenuItem(options: {
+  label: string
+  disabled: boolean
+  defaultValue: number
+  onConfirm: (n: number) => void
+}): ContextmenuItem {
+  if (options.disabled) return { label: options.label, disabled: true }
+  return {
+    label: options.label,
+    keepOpen: true,
+    render: menuNumberRender({
+      prefix: options.label,
+      suffix: '像素',
+      defaultValue: options.defaultValue,
+      min: MIN_ROW_COL_SIZE,
+      max: AXIS_SIZE_MAX,
+      onConfirm: options.onConfirm
+    })
+  }
+}
+
 function primaryRange(ctx: SheetContext): CellRange | null {
   return ctx.getSelection().ranges[0] ?? null
 }
 
-/** 行号右键菜单：插入×2 / 删除 / divider / 冻结 / 取消冻结 */
-export function buildRowHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
+/** 行号右键菜单：插入×2 / 删除 / 行高 / divider / 冻结 / 取消冻结 */
+export function buildRowHeaderMenus(
+  ctx: SheetContext,
+  options?: HeaderMenuOptions
+): ContextmenuItem[] {
   const range = primaryRange(ctx)
   const startRow = range?.start.row ?? 0
   const endRow = range?.end.row ?? startRow
@@ -130,6 +172,12 @@ export function buildRowHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
       })
     },
     { label: '删除行', callback: () => ctx.deleteRows(startRow, deleteCount) },
+    axisSizeMenuItem({
+      label: '行高',
+      disabled: options?.readonly === true,
+      defaultValue: ctx.getRowHeight(startRow) ?? FALLBACK_ROW_HEIGHT,
+      onConfirm: (n) => ctx.setRowHeightBySelection(n)
+    }),
     { divider: true },
     {
       label: freezeActive ? '✓ 冻结到当前行' : '冻结到当前行',
@@ -143,8 +191,11 @@ export function buildRowHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
   ]
 }
 
-/** 列头右键菜单：插入×2 / 删除 / divider / 冻结 / 取消冻结 */
-export function buildColHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
+/** 列头右键菜单：插入×2 / 删除 / 列宽 / divider / 冻结 / 取消冻结 */
+export function buildColHeaderMenus(
+  ctx: SheetContext,
+  options?: HeaderMenuOptions
+): ContextmenuItem[] {
   const range = primaryRange(ctx)
   const startCol = range?.start.col ?? 0
   const endCol = range?.end.col ?? startCol
@@ -175,6 +226,12 @@ export function buildColHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
       })
     },
     { label: '删除列', callback: () => ctx.deleteCols(startCol, deleteCount) },
+    axisSizeMenuItem({
+      label: '列宽',
+      disabled: options?.readonly === true,
+      defaultValue: ctx.getColWidth(startCol) ?? FALLBACK_COL_WIDTH,
+      onConfirm: (n) => ctx.setColWidthBySelection(n)
+    }),
     { divider: true },
     {
       label: freezeActive ? '✓ 冻结到当前列' : '冻结到当前列',

package/src/components/sheet/sheet.vue

@@ -56,6 +56,7 @@
       ref="formulaBarRef"
       :sheet="activeSheet"
       :context="context"
+      :set-selection-anchor="setSelectionAnchor"
     />
 
     <div ref="gridRef" :class="cls.e('grid')">
@@ -110,7 +111,8 @@ const props = withDefaults(defineProps<SheetProps>(), {
   showTabs: true,
   showRowHeader: true,
   showColHeader: true,
-  readonly: false
+  readonly: false,
+  colResize: false
 })
 
 const emit = defineEmits<SheetEmits>()
@@ -129,7 +131,9 @@ const { workbook, activeIndex, sheetList, activeSheet, context, stateTick, syncF
     onBeforeSheetChange: () => closePopup(),
     rebuildGrid: () => rebuildGrid(),
     activateGrid: () => activateGrid(),
-    pruneCache: (sheets) => pruneCache(sheets)
+    pruneCache: (sheets) => pruneCache(sheets),
+    // 行高/列宽菜单确认 → 活动 grid 引擎尺寸即时生效（getGrid 声明于下方，事件时才求值）
+    syncAxisSizes: (axis, indexes) => getGrid()?.applyAxisSizes(axis, indexes)
   })
 
 // ─── 弹层型工具编排（打开 / 关闭 / 面板事务）─────────────────────
@@ -205,14 +209,15 @@ const toolGroups = useToolGroups(context, stateTick)
 const gridRef = useTemplateRef<HTMLElement>('gridRef')
 const formulaBarRef = useTemplateRef<InstanceType<typeof UFormulaBar>>('formulaBarRef')
 
-const { rebuildGrid, activateGrid, pruneCache, getGrid } = useSheetGrid({
+const { rebuildGrid, activateGrid, pruneCache, getGrid, setSelectionAnchor } = useSheetGrid({
   props,
   gridRef,
   getActiveSheet: () => activeSheet.value,
   context,
   formulaBarRef,
   // 工具栏「函数」弹框打开期间与 fx 入口一致：画布点击不清除目标格高亮
-  isFunctionPopupOpen: () => popupTool.value?.popup === 'functions'
+  isFunctionPopupOpen: () => popupTool.value?.popup === 'functions',
+  onColResizeEnd: (event) => emit('col-resize-end', event)
 })
 
 const exposed: _SheetExposed = {

package/src/components/sheet/style.scss

@@ -147,7 +147,7 @@
     gap: fn.use-var(gap, small);
     padding: fn.use-var(gap, small);
     border-bottom: 1px solid fn.use-var(border, muted-color);
-    // 浮起的 fx 输入面板 / 候选列表需盖住下方 grid 与浮动图片叠层（image-layer z-index:1）
+    // 浮起的 fx 输入面板 / 候选列表需盖住下方 grid 与浮动图片叠层（引擎画布分层 z 序）
     position: relative;
     z-index: 30;
   }
@@ -717,7 +717,7 @@
   }
 
   /* LRU 缓存实例容器：absolute 堆叠于 grid 区，非激活实例 visibility:hidden
-     （保持尺寸不触发 VTable resize，切回仅翻转可见性 + 选区回驱） */
+     （保持尺寸不触发引擎表格 resize，切回仅翻转可见性 + 选区回驱） */
   @include m.e(grid-instance) {
     position: absolute;
     inset: 0;

package/src/components/sheet/use-sheet-grid.ts

@@ -39,6 +39,8 @@ interface UseSheetGridOptions {
   formulaBarRef: ElRef<FormulaBarMirror>
   /** 函数弹框打开中（宿主侧入口，如工具栏「函数」按钮） */
   isFunctionPopupOpen?: () => boolean
+  /** 列宽拖拽落定（SheetGrid 透传 → 宿主 emit col-resize-end） */
+  onColResizeEnd?: (event: { col: number; width: number }) => void
 }
 
 /** 缓存实例（LRU 淘汰）：每个 sheet 一个独立容器 div，非激活容器 visibility:hidden 堆叠 */
@@ -55,9 +57,9 @@ interface CachedGrid {
 
 /**
  * 缓存容量：最近 N 个 sheet 的 SheetGrid 实例常驻（tab 来回切换零重建）。
- * 大文件多 sheet 场景下切换卡顿的主因是每次重建 VTable（实例创建 + scenegraph
+ * 大文件多 sheet 场景下切换卡顿的主因是每次重建引擎表格（实例创建 + 画布分层
  * 首屏构建 ~300ms）；缓存命中时仅切换容器可见性 + 选区回驱（≈0）。
- * 每实例持有一个 canvas + scenegraph，容量即内存上限（含隐藏实例的渲染开销）。
+ * 每实例持有一组 [data-layer-kind] 分层画布，容量即内存上限（含隐藏实例的渲染开销）。
  */
 const GRID_CACHE_CAPACITY = 3
 
@@ -84,9 +86,9 @@ export function useSheetGrid(options: UseSheetGridOptions) {
 
     const menus =
       info.kind === 'row-header'
-        ? buildRowHeaderMenus(context)
+        ? buildRowHeaderMenus(context, { readonly: props.readonly })
         : info.kind === 'col-header'
-          ? buildColHeaderMenus(context)
+          ? buildColHeaderMenus(context, { readonly: props.readonly })
           : buildBodyMenus(context)
 
     // 最小宽度兜底；实际宽度由最长菜单项撑开（勿固定 240 导致空白过大）
@@ -126,9 +128,13 @@ export function useSheetGrid(options: UseSheetGridOptions) {
       resolveDisplayValue: props.resolveDisplayValue,
       resolveCellStyle: props.resolveCellStyle,
       resolveCellRenderer: props.resolveCellRenderer,
+      header: props.header,
+      editors: props.editors,
+      colResize: props.colResize,
       onContextMenu: handleContextMenu,
       onEditStart: (addr) => formulaBarRef.value?.mirrorGridEdit(addr),
       onEditEnd: (addr) => formulaBarRef.value?.exitMirror(addr),
+      onColResizeEnd: options.onColResizeEnd,
       // 引用选择：不回写模型选区，序列化为 A1 / A1:B2 交给公式栏；
       // 函数弹框打开期间（fx / 工具栏两入口）同样拦截，画布点击不离开目标格
       interceptSelection: () =>
@@ -198,13 +204,18 @@ export function useSheetGrid(options: UseSheetGridOptions) {
    * 命中时校验实例是否过期（隐藏期间程序化 structure-change——插入/删除/undo
    * 行列——vue 层只绑定激活 sheet 的 structure-change，隐藏实例靠自持订阅标记
    * dirty）；过期则释放重建。命中且未过期只翻可见性：隐藏实例的 cell/merge/
-   * content-reset 已在 GridSyncManager 置脏，setVisible(true) 时一次性 flush，
-   * 不必每次切 tab 都 syncFromModel（会重放全部列宽）。
+   * content-reset 已在 SheetGrid 内部置脏，setVisible(true) 时一次性全量同步，
+   * 无需宿主补推送。
    */
   function activateGrid(): void {
     const sheet = getActiveSheet()
     const host = gridRef.value
     if (!host) return
+    // 换实例前清旧实例的选区锚点：fx 编辑会话随切 sheet 结束（公式栏同步复位
+    // 编辑态），缓存实例复用时不得残留上次会话的高亮
+    if (active && active.sheet !== sheet) {
+      active.grid.setSelectionAnchor(null)
+    }
     const cached = cache.get(sheet)
     if (cached && !cached.dirty) {
       cached.lastUsed = ++seq
@@ -249,10 +260,21 @@ export function useSheetGrid(options: UseSheetGridOptions) {
 
   onMounted(activateGrid)
 
-  // props 尺寸显式增大时先扩张模型，再重建（删行缩小不走这条路径）
+  // props 尺寸显式增大时先扩张模型，再重建（删行缩小不走这条路径）；
+  // header / editors 按引用更替判定（机制对象构造期装配，变化即重建——宿主用
+  // computed 持稳定引用，勿在模板内联对象字面量）
   watch(
     () =>
-      [props.rows, props.cols, props.readonly, props.showRowHeader, props.showColHeader] as const,
+      [
+        props.rows,
+        props.cols,
+        props.readonly,
+        props.showRowHeader,
+        props.showColHeader,
+        props.header,
+        props.editors,
+        props.colResize
+      ] as const,
     ([nextRows, nextCols]) => {
       const sheet = getActiveSheet()
       if (nextRows != null) sheet.ensureTableSize(nextRows, 0)
@@ -265,5 +287,10 @@ export function useSheetGrid(options: UseSheetGridOptions) {
     invalidateAll()
   })
 
-  return { rebuildGrid, activateGrid, pruneCache, getGrid: () => active?.grid }
+  /** fx 引用拾取会话置/清选区锚点（公式栏 → 活动实例透传；无活动实例时静默） */
+  function setSelectionAnchor(addr: CellAddress | null): void {
+    active?.grid.setSelectionAnchor(addr)
+  }
+
+  return { rebuildGrid, activateGrid, pruneCache, getGrid: () => active?.grid, setSelectionAnchor }
 }

package/src/components/sheet/use-sheet-state.ts

@@ -21,6 +21,8 @@ export interface SheetStateHooks {
   activateGrid: () => void
   /** sheet 列表变化（增删）后清理已删除 sheet 的缓存实例 */
   pruneCache?: (sheets: ReadonlyArray<Sheet>) => void
+  /** 行列尺寸经门面写模型后同步活动 grid 引擎 table（菜单数值项画面即时生效） */
+  syncAxisSizes: (axis: 'row' | 'col', indexes: number[]) => void
 }
 
 type Emit = (event: 'active-sheet-change', payload: { sheet: Sheet; index: number }) => void
@@ -51,7 +53,9 @@ export function useSheetState(props: SheetProps, emit: Emit, hooks: SheetStateHo
     () => workbook.value,
     {
       resolveGridSize: () =>
-        resolveRenderSize(props.rows, props.cols, activeSheet.value.rows, activeSheet.value.cols)
+        resolveRenderSize(props.rows, props.cols, activeSheet.value.rows, activeSheet.value.cols),
+      // 行高/列宽菜单写入模型后同步活动 grid 引擎尺寸（Sheet 尺寸 API 不发事件）
+      syncAxisSizes: (axis, indexes) => hooks.syncAxisSizes(axis, indexes)
     }
   )
 

package/src/components/sheet/use-tool-popup.ts

@@ -107,15 +107,16 @@ export function useToolPopup(context: SheetContext, rootEl: ElRef) {
   /** Ctrl/Cmd+F 打开 / 关闭查找条（与工具按钮同一 toggle 逻辑） */
   function onGlobalKeydown(event: KeyboardEvent): void {
     if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== 'f') return
-    // 仅当焦点/事件源落在本实例容器内才响应（#6）：容器外不得 preventDefault，
+    // 仅当事件源落在本实例容器内才响应（#6）：容器外不得 preventDefault，
     // 否则劫持浏览器原生查找（页面任意位置按 Ctrl+F 都被屏蔽）；同页多实例
     // 也各只响应自己容器内的按键，不再每个实例都弹出查找条
     const root = rootEl.value
     if (root) {
+      // 只认事件源：真实键盘事件 target 恒为焦点元素；activeElement 兜底会把
+      // 「容器程序化聚焦后（SheetGrid 挂载即聚焦）的异源合成按键」误判为本实例
+      // 按键，重新劫持容器外的浏览器查找
       const target = event.target instanceof Node ? event.target : null
-      const active = document.activeElement instanceof Node ? document.activeElement : null
-      const inside =
-        (target !== null && root.contains(target)) || (active !== null && root.contains(active))
+      const inside = target !== null && root.contains(target)
       // 例外：弹层 Teleport 到 body 级 #pop-container（不在 root 内），本实例弹层
       // 打开期间焦点在弹层输入框里（如查找条内再按 Ctrl+F）——同样视为本实例的
       // 按键，否则查找条无法 toggle 关闭，且放行浏览器原生查找盖在上面。

package/src/index.ts

@@ -11,6 +11,6 @@ export {
   type SheetToolGroup
 } from './tools/registry'
 
-export { type SheetProps, type SheetEmits, type _SheetExposed, type SheetExposed } from './types'
+export { type SheetProps, type SheetEmits, type SheetExposed } from './types'
 
 export { USheet } from './components/sheet'

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

@@ -1,6 +1,6 @@
 import { createRange } from '@veltra/sheet-core/core/address.js'
 import { Sheet } from '@veltra/sheet-core/core/sheet.js'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vite-plus/test'
 
 import { classifySelectionStyleTarget, type SelectionStyleTarget } from '../apply-style'
 import { createSheetContext } from '../context'

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

@@ -3,7 +3,7 @@ import { createRange } from '@veltra/sheet-core/core/address.js'
 import '../builtin'
 import { Sheet } from '@veltra/sheet-core/core/sheet.js'
 import { Workbook } from '@veltra/sheet-core/core/workbook.js'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vite-plus/test'
 
 import { createSheetContext } from '../context'
 import { exportSheetCsvFile, exportWorkbookFile } from '../download'

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

@@ -1,8 +1,8 @@
 import { createRange } from '@veltra/sheet-core/core/address.js'
 import { Sheet } from '@veltra/sheet-core/core/sheet.js'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vite-plus/test'
 
-import { createSheetContext } from '../context'
+import { createSheetContext, MIN_ROW_COL_SIZE } from '../context'
 import type { SheetTool } from '../registry'
 
 describe('SheetContext', () => {
@@ -180,6 +180,70 @@ describe('SheetContext', () => {
     expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 'keep', t: 's' })
   })
 
+  it('行列尺寸门面：读取 + 按选区覆盖行/列批量应用，不进 undo', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+
+    // 未设置自定义尺寸时读取为 undefined（视图层用默认行高/列宽）
+    expect(ctx.getRowHeight(1)).toBeUndefined()
+    expect(ctx.getColWidth(2)).toBeUndefined()
+
+    ctx.selectRange(createRange({ row: 1, col: 2 }, { row: 3, col: 4 }))
+    ctx.setRowHeightBySelection(40)
+    ctx.setColWidthBySelection(120)
+    // 选区覆盖行 1..3 全部生效，行 0 不受影响
+    expect(ctx.getRowHeight(1)).toBe(40)
+    expect(ctx.getRowHeight(2)).toBe(40)
+    expect(ctx.getRowHeight(3)).toBe(40)
+    expect(ctx.getRowHeight(0)).toBeUndefined()
+    // 选区覆盖列 2..4 全部生效，列 5 不受影响
+    expect(ctx.getColWidth(2)).toBe(120)
+    expect(ctx.getColWidth(3)).toBe(120)
+    expect(ctx.getColWidth(4)).toBe(120)
+    expect(ctx.getColWidth(5)).toBeUndefined()
+
+    // 同 rowHeights/冻结先例：尺寸写入不进 undo 历史
+    expect(ctx.canUndo).toBe(false)
+  })
+
+  it('行列尺寸门面：下限钳制到引擎最小值 20；空选区无操作', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+
+    ctx.selectRange(createRange({ row: 2, col: 3 }, { row: 2, col: 4 }))
+    ctx.setRowHeightBySelection(10)
+    ctx.setColWidthBySelection(5)
+    expect(ctx.getRowHeight(2)).toBe(MIN_ROW_COL_SIZE)
+    expect(ctx.getColWidth(3)).toBe(MIN_ROW_COL_SIZE)
+    expect(ctx.getColWidth(4)).toBe(MIN_ROW_COL_SIZE)
+
+    // 空选区：无写入目标，不产生任何尺寸
+    sheet.selection.clear()
+    ctx.setRowHeightBySelection(60)
+    ctx.setColWidthBySelection(200)
+    expect(ctx.getRowHeight(0)).toBeUndefined()
+    expect(ctx.getColWidth(0)).toBeUndefined()
+  })
+
+  it('行列尺寸门面：写入后经 syncAxisSizes 同步钩子（携带选区覆盖行/列；空选区不触发）', () => {
+    const sheet = new Sheet()
+    const syncAxisSizes = vi.fn()
+    const ctx = createSheetContext(sheet, undefined, { syncAxisSizes })
+
+    ctx.selectRange(createRange({ row: 1, col: 2 }, { row: 2, col: 3 }))
+    ctx.setRowHeightBySelection(40)
+    expect(syncAxisSizes).toHaveBeenCalledWith('row', [1, 2])
+    ctx.setColWidthBySelection(120)
+    expect(syncAxisSizes).toHaveBeenCalledWith('col', [2, 3])
+
+    // 空选区：模型无写入，同步钩子不触发
+    syncAxisSizes.mockClear()
+    sheet.selection.clear()
+    ctx.setRowHeightBySelection(60)
+    ctx.setColWidthBySelection(60)
+    expect(syncAxisSizes).not.toHaveBeenCalled()
+  })
+
   it('图片门面：insertImage / removeImage / updateImage / getImages / onImageChange，经命令可 undo', () => {
     const sheet = new Sheet()
     const ctx = createSheetContext(sheet)

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

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vite-plus/test'
 
 import type { SheetTool } from '../registry'
 import { DEFAULT_TOOL_GROUP, ToolRegistry } from '../registry'

package/src/tools/context.ts

@@ -12,6 +12,9 @@ import type { Workbook } from '@veltra/sheet-core/core/workbook.js'
 
 import { axisStyleItemsForRange, classifySelectionStyleTarget } from './apply-style'
 
+/** 行列尺寸下限：对齐引擎 resize 最小值（`MIN_ROW_HEIGHT` / `MIN_COL_WIDTH` = 20） */
+export const MIN_ROW_COL_SIZE = 20
+
 /**
  * SheetContext：工具的唯一操作门面。
  *
@@ -100,6 +103,16 @@ export interface SheetContext {
   /** 设置冻结行列数（不进 undo，同 rowHeights 先例） */
   setFrozen(rows: number, cols: number): void
 
+  // ─── 行列尺寸（模型状态，不进 undo；随快照序列化） ─────────
+  /** 读取自定义行高；未设置返回 undefined（视图层用默认行高） */
+  getRowHeight(row: number): number | undefined
+  /** 读取自定义列宽；未设置返回 undefined（视图层用默认列宽） */
+  getColWidth(col: number): number | undefined
+  /** 按选区覆盖行批量设置行高（下限钳到 MIN_ROW_COL_SIZE；不进 undo，同 rowHeights 先例） */
+  setRowHeightBySelection(height: number): void
+  /** 按选区覆盖列批量设置列宽（下限钳到 MIN_ROW_COL_SIZE；不进 undo，同 colWidths 先例） */
+  setColWidthBySelection(width: number): void
+
   // ─── 行列插入/删除（结构变更，可 undo） ──────────────────
   /** 插入 count 行到 at 行之前 */
   insertRows(at: number, count?: number): void
@@ -135,6 +148,12 @@ export interface SheetContextOptions {
    * applyStyle / clearStyle 用其判定整行/整列；缺省时不走行列默认样式。
    */
   resolveGridSize?: () => { rows: number; cols: number }
+  /**
+   * 行列尺寸写模型后的即时同步钩子：`Sheet.setRowHeight`/`setColWidth` 不发事件，
+   * 宿主经此把尺寸落到活动 SheetGrid 引擎 table（菜单数值项画面即时生效）；
+   * 缺省（无头 / 测试直挂 Sheet）时仅写模型。
+   */
+  syncAxisSizes?: (axis: 'row' | 'col', indexes: number[]) => void
 }
 
 /**
@@ -146,6 +165,7 @@ export interface SheetContextOptions {
  *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
  *   workbook prop 后导出工具仍导出旧工作簿）
  * @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
+ * @param options.syncAxisSizes 行列尺寸写模型后的即时同步钩子（USheet 接活动 grid）
  */
 export function createSheetContext(
   resolveSheet: Sheet | (() => Sheet),
@@ -156,6 +176,7 @@ export function createSheetContext(
   const resolveWorkbook =
     typeof workbook === 'function' ? workbook : workbook != null ? () => workbook : undefined
   const resolveGridSize = options?.resolveGridSize
+  const syncAxisSizes = options?.syncAxisSizes
   const resolveTarget = (range: CellRange) => {
     const size = resolveGridSize?.()
     return size ? classifySelectionStyleTarget(range, size.rows, size.cols) : 'cell'
@@ -216,6 +237,32 @@ export function createSheetContext(
       return sheet().frozen
     },
     setFrozen: (rows, cols) => sheet().setFrozen(rows, cols),
+
+    getRowHeight: (row) => sheet().getRowHeight(row),
+    getColWidth: (col) => sheet().getColWidth(col),
+    setRowHeightBySelection: (height) => {
+      const size = Math.max(MIN_ROW_COL_SIZE, height)
+      const rows: number[] = []
+      for (const range of sheet().getSelection().ranges) {
+        for (let row = range.start.row; row <= range.end.row; row++) {
+          sheet().setRowHeight(row, size)
+          rows.push(row)
+        }
+      }
+      // 写模型后即时同步活动 grid（Sheet.setRowHeight 不发事件）
+      if (rows.length > 0) syncAxisSizes?.('row', rows)
+    },
+    setColWidthBySelection: (width) => {
+      const size = Math.max(MIN_ROW_COL_SIZE, width)
+      const cols: number[] = []
+      for (const range of sheet().getSelection().ranges) {
+        for (let col = range.start.col; col <= range.end.col; col++) {
+          sheet().setColWidth(col, size)
+          cols.push(col)
+        }
+      }
+      if (cols.length > 0) syncAxisSizes?.('col', cols)
+    },
     insertRows: (at, count) => sheet().insertRows(at, count),
     insertCols: (at, count) => sheet().insertCols(at, count),
     deleteRows: (at, count) => sheet().deleteRows(at, count),

package/src/types/sheet.ts

@@ -4,7 +4,9 @@ import type {
   ResolveCellRenderer,
   ResolveCellStyleHook,
   ResolveDisplayValue,
-  SheetGrid
+  SheetGrid,
+  SheetGridEditorsOptions,
+  SheetGridHeaderOptions
 } from '@veltra/sheet-core/grid'
 import type { DeconstructValue } from '@veltra/utils'
 import type { ComputedRef } from 'vue'
@@ -20,7 +22,7 @@ export interface SheetProps {
   /** 渲染列数，默认 26（A..Z） */
   cols?: number
   /**
-   * 显示值覆盖（设计态 Binding Placeholder 等）：覆盖 VTable record，不写 CellData.v
+   * 显示值覆盖（设计态 Binding Placeholder 等）：覆盖引擎视口显示文本，不写 CellData.v
    */
   resolveDisplayValue?: ResolveDisplayValue
   /**
@@ -28,11 +30,21 @@ export interface SheetProps {
    */
   resolveCellStyle?: ResolveCellStyleHook
   /**
-   * 动态单元格渲染（ADR-0004）：视口布局时按格自定义渲染形态（VTable
-   * customLayout，布局构建用 sheet-core 导出的 CustomLayout），返回 undefined
-   * 回落默认渲染；不写模型、不进快照
+   * 动态单元格渲染（ADR-0004）：视口布局时按格自定义渲染形态（返回引擎
+   * `CellRenderer`，见 `@veltra/sheet-core/grid`），返回 undefined 回落默认渲染；
+   * 不写模型、不进快照
    */
   resolveCellRenderer?: ResolveCellRenderer
+  /**
+   * 列头机制（透传 SheetGrid）：按列列头标题与表头自定义 DOM 渲染，不传保持
+   * 缺省字母表头；传值变化（引用更替）触发网格重建
+   */
+  header?: SheetGridHeaderOptions
+  /**
+   * 类型化编辑器机制（透传 SheetGrid）：多编辑器注册与按格路由，不传保持统一
+   * 文本编辑器；readonly 下忽略；传值变化（引用更替）触发网格重建
+   */
+  editors?: SheetGridEditorsOptions
   /** 是否显示工具栏，默认 true */
   showToolbar?: boolean
   /** 是否显示顶部公式栏（名称框 + fx 输入栏），默认 true */
@@ -45,11 +57,18 @@ export interface SheetProps {
   showColHeader?: boolean
   /** 只读预览（关闭编辑回写、填充柄等写入口） */
   readonly?: boolean
+  /**
+   * 列宽拖拽（透传 SheetGrid）：readonly 下置 true 仅放开列头 resize 手柄，编辑仍
+   * 关闭；缺省 false 行为不变。变化触发网格重建（构造期选项）
+   */
+  colResize?: boolean
 }
 
 export interface SheetEmits {
   /** 激活 sheet 切换（点击 tab 或宿主调用 workbook.activateSheet） */
   (name: 'active-sheet-change', payload: { sheet: Sheet; index: number }): void
+  /** 列宽拖拽落定（写模型之后）：载荷含列索引与最终宽度 */
+  (name: 'col-resize-end', payload: { col: number; width: number }): void
 }
 
 /** 在组件内部引用 */

package/src/components/sheet/parsing.ts

@@ -1,11 +0,0 @@
-import type { InjectionKey, Ref } from 'vue'
-
-/**
- * xlsx 解析中状态（历史 inject key，现由 import-file 直接写 sheet.vue 持有的 ref）。
- * 保留导出以便测试或扩展仍可 provide/inject。
- */
-export const SHEET_PARSING_KEY: InjectionKey<Ref<boolean>> = Symbol('sheet-parsing')
-
-/** 解析进度（worker 分片构建期间 done/total；readXlsx 同步解析段无进度） */
-export const SHEET_PARSE_PROGRESS_KEY: InjectionKey<Ref<{ done: number; total: number }>> =
-  Symbol('sheet-parse-progress')