@veltra/sheet 2.0.1 → 2.2.0

package/src/components/sheet/style.ts

@@ -0,0 +1,13 @@
+// USheet UI 实际渲染的 desktop 组件样式（#15：缺项会导致仅依赖本入口的宿主拿到无样式组件）
+import '@veltra/desktop/components/contextmenu/style'
+import '@veltra/desktop/components/dropdown/style'
+import '@veltra/desktop/components/number-input/style'
+import '@veltra/desktop/components/palette/style'
+import '@veltra/desktop/components/scroll/style'
+import '@veltra/desktop/components/tip/style'
+import '@veltra/desktop/components/loading/style' // v-loading（sheet.vue grid 容器）
+import '@veltra/desktop/components/message/style' // message / messageConfirm（弹层、tabs、公式栏）
+import '@veltra/desktop/components/input/style' // UInput（find-popup）
+import '@veltra/desktop/components/file-picker/style' // UFilePicker（insert-image-popup）
+import '@veltra/desktop/components/icon/style' // UIcon（sheet-toolbar / sheet-tabs）
+import './style.scss'

package/src/components/sheet/use-find-replace.ts

@@ -0,0 +1,200 @@
+import { debounce } from '@cat-kit/core'
+import {
+  inferCellType,
+  normalizeInputValue,
+  type CellData
+} from '@veltra/sheet-core/core/cell-store'
+import {
+  findAll,
+  findNextFrom,
+  findPrevFrom,
+  type FindMatch,
+  type FindOptions
+} from '@veltra/sheet-core/core/find'
+import type { Sheet } from '@veltra/sheet-core/core/sheet'
+import { computed, ref, shallowRef, watch } from 'vue'
+
+import type { SheetContext } from '../../tools/context'
+
+interface UseFindReplaceOptions {
+  /** 目标 sheet（弹层存活期间固定；tab 切换会关闭并销毁弹层） */
+  getSheet: () => Sheet
+  context: SheetContext
+}
+
+/**
+ * 查找条逻辑（关键词 / 上一个 / 下一个 / 命中计数 / 替换）：
+ * - 关键词 / 选项变化 → 重新查找并定位第一个命中
+ * - Enter = 下一个、Shift+Enter = 上一个（行主序、到边界循环）
+ * - 替换当前 = 一次 setCells（一个 undo 单元）；全部替换 = 一次批量 = 单 undo 单元
+ * - 公式格不参与替换（写入 {v,t} 会覆盖公式原文 f，导致公式丢失）
+ */
+export function useFindReplace(options: UseFindReplaceOptions) {
+  const { getSheet, context } = options
+
+  const findQuery = ref('')
+  const findReplace = ref('')
+  const caseSensitive = ref(false)
+  const wholeCell = ref(false)
+  const searchIn = ref<'value' | 'formula'>('value')
+  /** 全部命中（行主序；core/find 纯逻辑，无头可测） */
+  const findMatches = shallowRef<FindMatch[]>([])
+  /** 当前命中在 findMatches 中的下标；-1 = 无命中 */
+  const findCursor = ref(-1)
+
+  const canFind = computed(() => findMatches.value.length > 0)
+  const canReplace = computed(() => canFind.value && findCursor.value >= 0)
+
+  const findCountText = computed(() => {
+    const total = findMatches.value.length
+    if (total === 0) return '0 / 0'
+    return `${Math.min(findCursor.value + 1, total)} / ${total}`
+  })
+
+  function findOptions(): FindOptions {
+    return {
+      caseSensitive: caseSensitive.value,
+      wholeCell: wholeCell.value,
+      searchIn: searchIn.value
+    }
+  }
+
+  /** 上次全扫时的关键词 / 选项快照（识别防抖窗口内的脏缓存，见 ensureFreshMatches） */
+  let scannedQuery = ''
+  let scannedOptions = ''
+
+  function optionsSnapshot(): string {
+    return `${caseSensitive.value}|${wholeCell.value}|${searchIn.value}`
+  }
+
+  /** 关键词或选项变化：重新查找并定位第一个命中（否则保持当前位置附近） */
+  function refreshFind(initial: boolean): void {
+    const matches = findAll(getSheet(), findQuery.value, findOptions())
+    scannedQuery = findQuery.value
+    scannedOptions = optionsSnapshot()
+    findMatches.value = matches
+    if (matches.length === 0) {
+      findCursor.value = -1
+      return
+    }
+    if (initial) {
+      findCursor.value = 0
+      context.selectCell(matches[0]!.addr)
+    } else {
+      findCursor.value = Math.min(findCursor.value, matches.length - 1)
+    }
+  }
+
+  /**
+   * 防抖窗口内（关键词已输入、尚未触发全扫）Enter 导航 / 替换仍持有旧关键词的
+   * 命中缓存——先同步补扫一次，保证导航与替换作用于当前输入框里的关键词
+   * （否则「全部替换」会把旧关键词的命中集批量改写，与屏幕上看到的查找词不符）
+   */
+  function ensureFreshMatches(): void {
+    if (findQuery.value !== scannedQuery || optionsSnapshot() !== scannedOptions) {
+      refreshFind(false)
+    }
+  }
+
+  /** 定位到 findMatches 中与目标地址相同的命中（找不到则保持） */
+  function locateMatch(match: FindMatch): void {
+    const index = findMatches.value.findIndex(
+      (item) => item.addr.row === match.addr.row && item.addr.col === match.addr.col
+    )
+    if (index >= 0) findCursor.value = index
+    context.selectCell(match.addr)
+  }
+
+  function findForward(): void {
+    ensureFreshMatches()
+    const matches = findMatches.value
+    if (matches.length === 0) return
+    const active = context.getSelection().activeCell
+    // 在已缓存的全量命中数组上二分导航——原 findNext 每次重跑 findAll 全表扫描（#9）
+    const next = active ? findNextFrom(matches, active) : matches[0]
+    if (!next) return
+    locateMatch(next)
+  }
+
+  function findPrevious(): void {
+    ensureFreshMatches()
+    const matches = findMatches.value
+    if (matches.length === 0) return
+    const active = context.getSelection().activeCell
+    const prev = active ? findPrevFrom(matches, active) : matches[matches.length - 1]
+    if (!prev) return
+    locateMatch(prev)
+  }
+
+  /** Enter = 下一个；Shift+Enter = 上一个（UInput 的 keydown 透传到外层容器，冒泡可达） */
+  function handleFindKeydown(event: KeyboardEvent): void {
+    if (event.key !== 'Enter') return
+    event.preventDefault()
+    if (event.shiftKey) {
+      findPrevious()
+    } else {
+      findForward()
+    }
+  }
+
+  /** 替换文本 → CellData（空字符串 = 清除单元格；数字/布尔文本规范化后推断类型） */
+  function replaceData(): CellData | undefined {
+    if (findReplace.value === '') return undefined
+    const normalized = normalizeInputValue(findReplace.value)
+    const t = inferCellType(normalized)
+    return t ? { v: normalized, t } : { v: normalized }
+  }
+
+  /** 公式格不参与替换（写入 {v,t} 会覆盖公式原文 f，导致公式丢失） */
+  function isReplaceable(match: FindMatch): boolean {
+    return !context.getCellData(match.addr)?.f
+  }
+
+  /** 替换当前命中格（一次 setCells = 一个 undo 单元）；替换后重新查找 */
+  function replaceCurrent(): void {
+    ensureFreshMatches()
+    const match = findMatches.value[findCursor.value]
+    if (!match || !isReplaceable(match)) return
+    context.setCells([{ addr: match.addr, data: replaceData() }])
+    refreshFind(false)
+  }
+
+  /** 全部替换（一次 setCells 批量 = 单 undo 单元，undo 一次全部还原）；公式格自动跳过 */
+  function replaceAll(): void {
+    ensureFreshMatches()
+    const matches = findMatches.value.filter(isReplaceable)
+    if (matches.length === 0) return
+    context.setCells(matches.map((match) => ({ addr: match.addr, data: replaceData() })))
+    refreshFind(false)
+  }
+
+  // 关键词 / 选项变化 → 重新查找（定位第一个命中）。
+  // 每击键全扫 440ms 级：连续击键时防抖合并（300ms 停键才扫，immediate=false 即
+  // 首键不抢扫，#28），避免每键一次全表扫描把 UI 卡死；若停键前已 Enter / 替换
+  // （ensureFreshMatches 同步补扫），快照已新鲜则跳过多余的补扫
+  const refreshFindDebounced = debounce(
+    () => {
+      if (findQuery.value === scannedQuery && optionsSnapshot() === scannedOptions) return
+      refreshFind(true)
+    },
+    300,
+    false
+  )
+  watch([findQuery, caseSensitive, wholeCell, searchIn], refreshFindDebounced)
+
+  return {
+    findQuery,
+    findReplace,
+    caseSensitive,
+    wholeCell,
+    searchIn,
+    canFind,
+    canReplace,
+    findCountText,
+    findForward,
+    findPrevious,
+    handleFindKeydown,
+    replaceCurrent,
+    replaceAll
+  }
+}

package/src/components/sheet/use-formula-ref-select.ts

@@ -0,0 +1,34 @@
+/** 引用选择上下文：光标前一个非空字符属于此集合时可插入单元格引用 */
+const REF_TRIGGER_CHARS = new Set(['=', '(', ',', '+', '-', '*', '/', '^', '&', '<', '>'])
+
+/**
+ * 判定是否处于「可插入引用」位置（无状态：每次按文本 + 光标重算）。
+ * `-` 的一元/二元歧义基础版不区分（`A1-` 后框选 → `A1-B2`，合法且误判无害）。
+ */
+export function isRefSelectContext(text: string, cursor: number): boolean {
+  if (cursor < 0 || cursor > text.length) return false
+  // 非公式编辑不进入引用选择（普通文本失焦应提交）
+  if (!text.startsWith('=')) return false
+  const before = text.slice(0, cursor).replace(/\s+$/, '')
+  if (before.length === 0) return false
+  return REF_TRIGGER_CHARS.has(before[before.length - 1]!)
+}
+
+export interface InsertRefResult {
+  text: string
+  /** 插入后光标位置（落在引用文本之后） */
+  cursor: number
+}
+
+/** 在光标处插入引用文本（替换空选区；有选区时覆盖选区） */
+export function insertRefText(
+  text: string,
+  cursor: number,
+  rangeText: string,
+  selectionEnd: number = cursor
+): InsertRefResult {
+  const start = Math.min(cursor, selectionEnd)
+  const end = Math.max(cursor, selectionEnd)
+  const next = text.slice(0, start) + rangeText + text.slice(end)
+  return { text: next, cursor: start + rangeText.length }
+}

package/src/components/sheet/use-formula-suggest.ts

@@ -0,0 +1,150 @@
+import {
+  listFormulaFunctions,
+  type FormulaFunctionMeta
+} from '@veltra/sheet-core/core/formula/functions'
+
+/** 补全候选上限 */
+export const FORMULA_SUGGEST_LIMIT = 10
+
+/**
+ * 空前缀时优先展示的常用函数（其余按名称升序补齐至上限）。
+ * 纯字典序会把 SUM / OR / ROUND 挤出前 10（ABS…NOT），导致输入 `=` 看不到 SUM。
+ */
+export const COMMON_FORMULA_NAMES = [
+  'SUM',
+  'AVERAGE',
+  'COUNT',
+  'MAX',
+  'MIN',
+  'IF',
+  'ROUND',
+  'ABS',
+  'AND',
+  'OR'
+] as const
+
+/** 函数名 token 前合法的「触发」字符（= / 运算符 / ( / ,） */
+const SUGGEST_TRIGGER_CHARS = new Set(['=', '(', ',', '+', '-', '*', '/', '^', '&', '<', '>'])
+
+export interface FormulaSuggestItem {
+  name: string
+  params: string[]
+  description: string
+  /** 签名展示：`SUM(number1, number2, ...)`；无 params 时仅名称 */
+  signature: string
+}
+
+export interface FormulaSuggestContext {
+  /** 当前前缀（可能为空：紧跟 `=` 后） */
+  prefix: string
+  /** 前缀在文本中的起始下标（含） */
+  start: number
+  /** 光标位置（= 前缀结束下标） */
+  end: number
+}
+
+/** 格式化函数签名；无 params 时仅返回名称 */
+export function formatFunctionSignature(name: string, params: string[]): string {
+  if (params.length === 0) return name
+  return `${name}(${params.join(', ')})`
+}
+
+/**
+ * 判定补全上下文：光标前向匹配函数名 token（或紧跟 `=` 的空前缀），
+ * 且 token 前一个非空字符 ∈ 触发字符集。
+ * 镜像只读期由调用方跳过，本函数不做只读判断。
+ */
+export function getSuggestContext(text: string, cursor: number): FormulaSuggestContext | null {
+  if (cursor < 0 || cursor > text.length) return null
+  const before = text.slice(0, cursor)
+  const tokenMatch = /[A-Za-z][A-Za-z0-9_.]*$/.exec(before)
+  const prefix = tokenMatch?.[0] ?? ''
+  const start = tokenMatch ? cursor - prefix.length : cursor
+
+  // 空前缀仅在紧跟 `=` 后弹出（验证清单：输入 `=` → 候选出现）。
+  // `<=` / `>=` 的尾随 `=` 是比较运算符一部分，不是函数名起点。
+  if (!tokenMatch) {
+    const trimmed = before.replace(/\s+$/, '')
+    if (!trimmed.endsWith('=')) return null
+    if (trimmed.endsWith('<=') || trimmed.endsWith('>=')) return null
+    return { prefix: '', start, end: cursor }
+  }
+
+  const beforeToken = before.slice(0, start).replace(/\s+$/, '')
+  if (beforeToken.length === 0) return null
+  const last = beforeToken[beforeToken.length - 1]!
+  if (!SUGGEST_TRIGGER_CHARS.has(last)) return null
+  return { prefix, start, end: cursor }
+}
+
+/**
+ * 前缀过滤函数表（大小写不敏感），上限 FORMULA_SUGGEST_LIMIT。
+ * 空前缀：常用函数优先，其余名称升序补齐；有前缀：名称升序。
+ */
+export function filterFormulaSuggestions(prefix: string): FormulaSuggestItem[] {
+  const upper = prefix.toUpperCase()
+  const all = listFormulaFunctions()
+  if (!upper) {
+    const byName = new Map(all.map((fn) => [fn.name, fn]))
+    const items: FormulaSuggestItem[] = []
+    const used = new Set<string>()
+    for (const name of COMMON_FORMULA_NAMES) {
+      const fn = byName.get(name)
+      if (!fn) continue
+      items.push(toSuggestItem(fn))
+      used.add(name)
+      if (items.length >= FORMULA_SUGGEST_LIMIT) return items
+    }
+    for (const fn of all) {
+      if (used.has(fn.name)) continue
+      items.push(toSuggestItem(fn))
+      if (items.length >= FORMULA_SUGGEST_LIMIT) break
+    }
+    return items
+  }
+
+  const items: FormulaSuggestItem[] = []
+  for (const fn of all) {
+    if (!fn.name.startsWith(upper)) continue
+    items.push(toSuggestItem(fn))
+    if (items.length >= FORMULA_SUGGEST_LIMIT) break
+  }
+  return items
+}
+
+function toSuggestItem(fn: { name: string } & FormulaFunctionMeta): FormulaSuggestItem {
+  return {
+    name: fn.name,
+    params: fn.params,
+    description: fn.description,
+    signature: formatFunctionSignature(fn.name, fn.params)
+  }
+}
+
+export interface ApplySuggestResult {
+  text: string
+  /** 替换后光标位置（落在 `NAME()` 的括号内） */
+  cursor: number
+}
+
+/** 将 [start, end) 的 token 替换为 `NAME()`，光标入括号内（免手动补右括号） */
+export function applySuggest(
+  text: string,
+  start: number,
+  end: number,
+  name: string
+): ApplySuggestResult {
+  const insert = `${name}()`
+  const next = text.slice(0, start) + insert + text.slice(end)
+  return { text: next, cursor: start + name.length + 1 }
+}
+
+/**
+ * 键盘导航：↑↓ 循环；返回新的高亮下标。
+ * activeIndex 越界时按 0 处理。
+ */
+export function moveSuggestIndex(activeIndex: number, length: number, delta: 1 | -1): number {
+  if (length <= 0) return 0
+  const cur = ((activeIndex % length) + length) % length
+  return (cur + delta + length) % length
+}

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

@@ -0,0 +1,247 @@
+import { contextmenu } from '@veltra/desktop'
+import type { CellAddress, CellRange } from '@veltra/sheet-core/core/address'
+import type { Sheet } from '@veltra/sheet-core/core/sheet'
+import { SheetGrid, type SheetGridContextMenuInfo } from '@veltra/sheet-core/grid/sheet-grid'
+import { onBeforeUnmount, onMounted, watch } from 'vue'
+
+import type { SheetContext } from '../../tools/context'
+import type { SheetProps } from '../../types'
+import {
+  buildBodyMenus,
+  buildColHeaderMenus,
+  buildRowHeaderMenus,
+  ensureContextMenuSelection,
+  resolveRenderSize
+} from './sheet-context-menu'
+
+/** 模板 ref（useTemplateRef 的只读形态） */
+type ElRef<T> = { readonly value: T | null | undefined }
+
+/** 公式栏暴露接口（镜像 + 引用选择） */
+export interface FormulaBarMirror {
+  mirrorGridEdit: (addr: CellAddress) => void
+  exitMirror: (addr: CellAddress) => void
+  /** fx 编辑中且处于可插入引用位置 */
+  isRefSelecting: () => boolean
+  /** 网格 pointerdown → 挂起 blur 提交 */
+  beginBlurSuppress: () => void
+  /** 画布选区 → 插入引用文本 */
+  handleRefSelect: (range: CellRange) => void
+}
+
+interface UseSheetGridOptions {
+  props: SheetProps
+  gridRef: ElRef<HTMLElement>
+  getActiveSheet: () => Sheet
+  context: SheetContext
+  formulaBarRef: ElRef<FormulaBarMirror>
+}
+
+/** 缓存实例（LRU 淘汰）：每个 sheet 一个独立容器 div，非激活容器 visibility:hidden 堆叠 */
+interface CachedGrid {
+  sheet: Sheet
+  grid: SheetGrid
+  el: HTMLDivElement
+  lastUsed: number
+  /** 释放实例：取消 structure-change 订阅 + grid.release + 移除容器 */
+  release: () => void
+  /** 隐藏期间发生 structure-change（程序化行列变更）→ 切回时需重建 */
+  dirty: boolean
+}
+
+/**
+ * 缓存容量：最近 N 个 sheet 的 SheetGrid 实例常驻（tab 来回切换零重建）。
+ * 大文件多 sheet 场景下切换卡顿的主因是每次重建 VTable（实例创建 + scenegraph
+ * 首屏构建 ~300ms）；缓存命中时仅切换容器可见性 + 选区回驱（≈0）。
+ * 每实例持有一个 canvas + scenegraph，容量即内存上限（含隐藏实例的渲染开销）。
+ */
+const GRID_CACHE_CAPACITY = 3
+
+/**
+ * SheetGrid 生命周期与网格右键菜单（LRU 实例缓存）：
+ * - activateGrid：tab 切换入口——命中缓存 → 显示 + 模型同步（零重建）；
+ *   未命中 → 新建实例入缓存，超容量淘汰最久未用（release + 移除容器）
+ * - rebuildGrid：强制重建激活实例并清空缓存（structure-change / props 尺寸
+ *   变化 / 工作簿切换 / 导入替换——这些场景下缓存实例的 columns / 数据源失效）
+ * - 右键菜单：body / 行号 / 列头
+ * - 公式栏引用选择：interceptSelection 拦截选区回写 + pointerdown 挂起 blur
+ */
+export function useSheetGrid(options: UseSheetGridOptions) {
+  const { props, gridRef, getActiveSheet, context, formulaBarRef } = options
+  const cache = new Map<Sheet, CachedGrid>()
+  let active: CachedGrid | undefined
+  let seq = 0
+  let detachPointerDown: (() => void) | undefined
+
+  function handleContextMenu(info: SheetGridContextMenuInfo): void {
+    const sheet = getActiveSheet()
+    const renderSize = resolveRenderSize(props.rows, props.cols, sheet.rows, sheet.cols)
+    ensureContextMenuSelection(context, info, renderSize)
+
+    const menus =
+      info.kind === 'row-header'
+        ? buildRowHeaderMenus(context)
+        : info.kind === 'col-header'
+          ? buildColHeaderMenus(context)
+          : buildBodyMenus(context)
+
+    // 最小宽度兜底；实际宽度由最长菜单项撑开（勿固定 240 导致空白过大）
+    contextmenu.pop({ mousePosition: { x: info.x, y: info.y }, width: 'max-content', menus })
+  }
+
+  function bindGridPointerDown(container: HTMLElement): void {
+    detachPointerDown?.()
+    const onPointerDown = () => {
+      formulaBarRef.value?.beginBlurSuppress()
+    }
+    // capture：赶在 textarea blur 之前挂起提交
+    container.addEventListener('pointerdown', onPointerDown, true)
+    detachPointerDown = () => {
+      container.removeEventListener('pointerdown', onPointerDown, true)
+      detachPointerDown = undefined
+    }
+  }
+
+  /** 新建实例：创建独立容器 div（absolute 堆叠于 grid 区内）并构造 SheetGrid */
+  function createGrid(sheet: Sheet): CachedGrid {
+    const host = gridRef.value
+    if (!host) throw new Error('useSheetGrid: grid 容器未挂载')
+    const el = document.createElement('div')
+    el.className = 'u-sheet__grid-instance'
+    host.appendChild(el)
+    const grid = new SheetGrid({
+      container: el,
+      sheet,
+      rows: props.rows,
+      cols: props.cols,
+      readonly: props.readonly,
+      resolveDisplayValue: props.resolveDisplayValue,
+      resolveCellStyle: props.resolveCellStyle,
+      resolveCellRenderer: props.resolveCellRenderer,
+      onContextMenu: handleContextMenu,
+      onEditStart: (addr) => formulaBarRef.value?.mirrorGridEdit(addr),
+      onEditEnd: (addr) => formulaBarRef.value?.exitMirror(addr),
+      // 引用选择：不回写模型选区，序列化为 A1 / A1:B2 交给公式栏
+      interceptSelection: () => formulaBarRef.value?.isRefSelecting() ?? false,
+      onSelectionIntercept: (range) => formulaBarRef.value?.handleRefSelect(range)
+    })
+    // 结构变更订阅（vue 层只绑定激活 sheet；隐藏实例必须自持标记，切回时判定过期）
+    let dirty = false
+    const offStructureChange = sheet.on('structure-change', () => {
+      dirty = true
+    })
+    const release = (): void => {
+      offStructureChange()
+      grid.release()
+      el.remove()
+    }
+    return {
+      sheet,
+      grid,
+      el,
+      lastUsed: ++seq,
+      release,
+      get dirty() {
+        return dirty
+      }
+    }
+  }
+
+  /** 切换激活实例：显示目标、隐藏其余（visibility:hidden 保持尺寸，canvas 不重建） */
+  function showOnly(target: CachedGrid): void {
+    for (const item of cache.values()) {
+      const on = item === target
+      item.el.style.visibility = on ? 'visible' : 'hidden'
+      // 隐藏实例停用视图同步（只置脏），激活实例立即同步挂起变更（#12）
+      item.grid.setVisible(on)
+    }
+  }
+
+  /** 淘汰最久未用的缓存实例（保留激活实例） */
+  function evict(): void {
+    while (cache.size > GRID_CACHE_CAPACITY) {
+      let oldest: CachedGrid | undefined
+      for (const item of cache.values()) {
+        if (item === active) continue
+        if (!oldest || item.lastUsed < oldest.lastUsed) oldest = item
+      }
+      if (!oldest) break
+      cache.delete(oldest.sheet)
+      oldest.release()
+    }
+  }
+
+  /** 清空全部缓存实例（workbook 切换 / 导入替换 / 渲染尺寸变化 / 结构变更） */
+  function invalidateAll(): void {
+    for (const item of cache.values()) {
+      item.release()
+    }
+    cache.clear()
+    active = undefined
+    detachPointerDown?.()
+  }
+
+  /**
+   * tab 切换：优先复用缓存实例（零重建）。
+   * 命中时校验实例是否过期（隐藏期间程序化 structure-change——插入/删除/undo
+   * 行列——vue 层只绑定激活 sheet 的 structure-change，隐藏实例靠自持订阅标记
+   * dirty）；过期则释放重建，否则同步模型状态（选区回驱 + 冻结校正；数据/样式/
+   * 行高由实例常驻的 sheet 事件订阅持续同步，隐藏期间跨表重算等模型变更不丢）。
+   */
+  function activateGrid(): void {
+    const sheet = getActiveSheet()
+    const host = gridRef.value
+    if (!host) return
+    const cached = cache.get(sheet)
+    if (cached && !cached.dirty) {
+      cached.lastUsed = ++seq
+      cached.grid.syncFromModel()
+      showOnly(cached)
+      active = cached
+      bindGridPointerDown(cached.el)
+      return
+    }
+    if (cached) {
+      // 隐藏期间结构变更：实例过期，释放后重建（走下方新建路径）
+      cache.delete(sheet)
+      cached.release()
+    }
+    const created = createGrid(sheet)
+    cache.set(sheet, created)
+    created.lastUsed = ++seq
+    showOnly(created)
+    active = created
+    bindGridPointerDown(created.el)
+    evict()
+  }
+
+  /**
+   * 清理已不存在的 sheet 的缓存实例（workbook 删除 sheet 后及时释放，
+   * 避免条目与事件订阅残留到容量淘汰）。
+   */
+  function pruneCache(sheets: ReadonlyArray<Sheet>): void {
+    const alive = new Set(sheets)
+    for (const [sheet, item] of cache) {
+      // 存活或激活的实例保留；已删除的 sheet 释放（含事件订阅）
+      if (alive.has(sheet) || item === active) continue
+      cache.delete(sheet)
+      item.release()
+    }
+  }
+
+  /** 强制重建激活实例并清空缓存（structure-change / props / 工作簿替换） */
+  function rebuildGrid(): void {
+    invalidateAll()
+    activateGrid()
+  }
+
+  onMounted(activateGrid)
+
+  watch(() => [props.rows, props.cols, props.readonly], rebuildGrid)
+
+  onBeforeUnmount(() => {
+    invalidateAll()
+  })
+
+  return { rebuildGrid, activateGrid, pruneCache, getGrid: () => active?.grid }
+}