@veltra/sheet 2.0.1 → 2.2.0

package/src/components/sheet/popups/font-size-popup.vue

@@ -0,0 +1,52 @@
+<template>
+  <!-- 下拉排列：每行一个字号；滚动用 desktop UScroll（自定义滚动条） -->
+  <u-scroll :height="280" :class="cls.e('popup-size-scroll')">
+    <div :class="cls.e('popup-size-list')">
+      <button
+        v-for="size in FONT_SIZES"
+        :key="size"
+        type="button"
+        :class="[cls.e('popup-size-item'), bem.is('active', currentSize === size)]"
+        @click="applyFontSize(size)"
+      >
+        {{ size }}
+      </button>
+    </div>
+  </u-scroll>
+</template>
+
+<script lang="ts" setup>
+import { UScroll } from '@veltra/desktop'
+import { bem } from '@veltra/utils'
+import { onMounted, ref } from 'vue'
+
+import type { SheetContext } from '../../../tools/context'
+import { currentRange } from '../popup-helpers'
+
+defineOptions({ name: 'USheetFontSizePopup' })
+
+/** 预设字号列表（pt，与 Excel 常用档对齐） */
+const FONT_SIZES = [9, 10, 11, 12, 14, 16, 18, 20, 24, 28, 32] as const
+
+/**
+ * 字号面板（预设列表；点击写入 font.size）。
+ * 面板打开期间的写入由 use-tool-popup 事务包裹为一个 undo 单元。
+ */
+const props = defineProps<{ context: SheetContext }>()
+
+const cls = bem('sheet')
+const currentSize = ref<number | undefined>(undefined)
+
+onMounted(() => {
+  const active = props.context.getSelection().activeCell
+  const style = active ? props.context.getCellStyle(active) : undefined
+  currentSize.value = style?.font?.size
+})
+
+function applyFontSize(size: number): void {
+  const range = currentRange(props.context)
+  if (!range) return
+  currentSize.value = size
+  props.context.setCellStyle(range, { font: { size } })
+}
+</script>

package/src/components/sheet/popups/import.worker.ts

@@ -0,0 +1,66 @@
+/// <reference lib="webworker" />
+/**
+ * XLSX 解析 Worker：hucre 解析 + 模型构建（大文件 3~4s 同步重活）
+ * 移到独立线程，主线程保持空闲（loading 动画正常、交互不冻结）。
+ *
+ * 协议：主线程 postMessage({ buffer: ArrayBuffer }) → worker 返回
+ * - { type: 'progress', done, total }（模型分片构建进度，readXlsx 同步解析段无进度）
+ * - { type: 'done', ok: true, sheets: [{ name, snapshot }], activeIndex }（快照为
+ *   纯数据，可结构化克隆）；失败 { type: 'done', ok: false, error }。
+ *
+ * 名字唯一化与活动表对齐由 buildWorkbookFromHucre 完成（worker 内），主线程
+ * 直接把快照替换进目标（无 undo 历史——替换语义由确认后的 replaceWorkbook 负责）。
+ *
+ * 注意：必须用**运行时动态 import**——worker 顶层静态 import 在 vite dev 的
+ * worker 上下文中会因模块图加载顺序导致 `Workbook is not defined`（实测）。
+ */
+import type { SheetSnapshot } from '@veltra/sheet-core/core/sheet'
+
+export type ImportWorkerResponse =
+  | { type: 'progress'; done: number; total: number }
+  | {
+      type: 'done'
+      ok: true
+      sheets: { name: string; snapshot: SheetSnapshot }[]
+      activeIndex: number
+    }
+  | { type: 'done'; ok: false; error: string }
+
+self.onmessage = (e: MessageEvent<{ buffer: ArrayBuffer }>): void => {
+  const { buffer } = e.data
+  void (async () => {
+    try {
+      const [{ readXlsx }, { buildWorkbookFromHucre }] = await Promise.all([
+        import('hucre/xlsx'),
+        import('@veltra/sheet-core/core/io/import')
+      ])
+      const hucreWb = await readXlsx(new Uint8Array(buffer), { readStyles: true })
+      // 分片构建：按 10% 粒度回报进度（避免 196 条/秒的消息风暴与文字跳变过快；
+      // 模型构建段约 1s，10 次更新肉眼可见数字推进）
+      let lastPercent = -1
+      const wb = buildWorkbookFromHucre(hucreWb, (done, total) => {
+        const percent = total > 0 ? Math.floor((done / total) * 10) : 10
+        if (percent !== lastPercent || done === total) {
+          lastPercent = percent
+          const progress: ImportWorkerResponse = { type: 'progress', done, total }
+          ;(self as unknown as Worker).postMessage(progress)
+        }
+      })
+      const sheets = wb.getSheets().map((s) => ({ name: s.name, snapshot: s.snapshot() }))
+      const response: ImportWorkerResponse = {
+        type: 'done',
+        ok: true,
+        sheets,
+        activeIndex: wb.activeSheetIndex
+      }
+      ;(self as unknown as Worker).postMessage(response)
+    } catch (err: unknown) {
+      const response: ImportWorkerResponse = {
+        type: 'done',
+        ok: false,
+        error: err instanceof Error ? err.message : String(err)
+      }
+      ;(self as unknown as Worker).postMessage(response)
+    }
+  })()
+}

package/src/components/sheet/popups/insert-image-popup.vue

@@ -0,0 +1,39 @@
+<template>
+  <u-file-picker
+    :accept="INSERT_IMAGE_ACCEPT"
+    :class="cls.e('insert-image-picker')"
+    @pick="handlePick"
+  >
+    <div :class="cls.e('insert-image-hint')">
+      选择图片文件
+      <div :class="cls.e('insert-image-sub')">支持 png / jpeg / gif / svg / webp</div>
+    </div>
+  </u-file-picker>
+</template>
+
+<script lang="ts" setup>
+import { UFilePicker } from '@veltra/desktop'
+import { bem } from '@veltra/utils'
+
+import type { SheetContext } from '../../../tools/context'
+import { INSERT_IMAGE_ACCEPT, insertImageFromFile } from '../insert-image'
+
+defineOptions({ name: 'USheetInsertImagePopup' })
+
+/**
+ * 插入图片面板（UFilePicker）：选文件后走共享 insertImageFromFile，锚定当前选区活动格。
+ * 不参与面板事务（单次插入 = 一个 undo 单元）。
+ */
+const props = defineProps<{ context: SheetContext }>()
+
+const emit = defineEmits<{ close: [] }>()
+
+const cls = bem('sheet')
+
+function handlePick(files: File[]): void {
+  const file = files[0]
+  if (!file) return
+  emit('close')
+  void insertImageFromFile(props.context, file)
+}
+</script>

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

@@ -0,0 +1,229 @@
+import type { ContextmenuItem } from '@veltra/desktop'
+import { createRange, type CellAddress, type CellRange } from '@veltra/sheet-core/core/address'
+import { defineComponent, h } from 'vue'
+
+import type { SheetContext } from '../../tools/context'
+import { defaultToolRegistry } from '../../tools/registry'
+import InsertCountMenuItem from './insert-count-menu-item.vue'
+import { pickAndInsertImage } from './insert-image'
+
+/** 插入数量钳制范围（对齐 univer） */
+export const INSERT_COUNT_MIN = 1
+export const INSERT_COUNT_MAX = 1000
+
+/** 选区覆盖行/列数 → 插入默认 N（min 1 / max 1000） */
+export function defaultInsertCount(range: CellRange | null, axis: 'row' | 'col'): number {
+  if (!range) return INSERT_COUNT_MIN
+  const n =
+    axis === 'row' ? range.end.row - range.start.row + 1 : range.end.col - range.start.col + 1
+  return Math.min(INSERT_COUNT_MAX, Math.max(INSERT_COUNT_MIN, n))
+}
+
+/** 点击行是否落在任一选区内（按行号覆盖） */
+export function isRowInSelection(ranges: CellRange[], row: number): boolean {
+  return ranges.some((r) => r.start.row <= row && row <= r.end.row)
+}
+
+/** 点击列是否落在任一选区内（按列号覆盖） */
+export function isColInSelection(ranges: CellRange[], col: number): boolean {
+  return ranges.some((r) => r.start.col <= col && col <= r.end.col)
+}
+
+/** 整行选区（列跨渲染宽度） */
+export function wholeRowRange(row: number, colCount: number): CellRange {
+  return createRange({ row, col: 0 }, { row, col: Math.max(colCount - 1, 0) })
+}
+
+/** 整列选区（行跨渲染高度） */
+export function wholeColRange(col: number, rowCount: number): CellRange {
+  return createRange({ row: 0, col }, { row: Math.max(rowCount - 1, 0), col })
+}
+
+/** 渲染尺寸 = max(props, sheet.rows/cols)，与 SheetGrid 一致 */
+export function resolveRenderSize(
+  propsRows: number | undefined,
+  propsCols: number | undefined,
+  sheetRows: number,
+  sheetCols: number
+): { rows: number; cols: number } {
+  return { rows: Math.max(propsRows ?? 100, sheetRows), cols: Math.max(propsCols ?? 26, sheetCols) }
+}
+
+function insertCountRender(options: {
+  prefix: string
+  suffix: string
+  defaultValue: number
+  onConfirm: (n: number) => void
+}): ContextmenuItem['render'] {
+  return defineComponent({
+    name: 'SheetInsertCountMenuRender',
+    setup() {
+      return () =>
+        h(InsertCountMenuItem, {
+          prefix: options.prefix,
+          suffix: options.suffix,
+          defaultValue: options.defaultValue,
+          min: INSERT_COUNT_MIN,
+          max: INSERT_COUNT_MAX,
+          onConfirm: options.onConfirm
+        })
+    }
+  })
+}
+
+function primaryRange(ctx: SheetContext): CellRange | null {
+  return ctx.getSelection().ranges[0] ?? null
+}
+
+/** 行号右键菜单：插入×2 / 删除 / divider / 冻结 / 取消冻结 */
+export function buildRowHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
+  const range = primaryRange(ctx)
+  const startRow = range?.start.row ?? 0
+  const endRow = range?.end.row ?? startRow
+  const rowCount = defaultInsertCount(range, 'row')
+  const deleteCount = range ? endRow - startRow + 1 : 1
+  const frozen = ctx.frozen
+  const freezeActive = frozen.rows === endRow + 1
+
+  return [
+    {
+      label: '在上方插入行',
+      keepOpen: true,
+      render: insertCountRender({
+        prefix: '在上方插入',
+        suffix: '行',
+        defaultValue: rowCount,
+        onConfirm: (n) => ctx.insertRows(startRow, n)
+      })
+    },
+    {
+      label: '在下方插入行',
+      keepOpen: true,
+      render: insertCountRender({
+        prefix: '在下方插入',
+        suffix: '行',
+        defaultValue: rowCount,
+        onConfirm: (n) => ctx.insertRows(endRow + 1, n)
+      })
+    },
+    { label: '删除行', callback: () => ctx.deleteRows(startRow, deleteCount) },
+    { divider: true },
+    {
+      label: freezeActive ? '✓ 冻结到当前行' : '冻结到当前行',
+      callback: () => ctx.setFrozen(endRow + 1, frozen.cols)
+    },
+    {
+      label: '取消冻结',
+      disabled: frozen.rows === 0 && frozen.cols === 0,
+      callback: () => ctx.setFrozen(0, 0)
+    }
+  ]
+}
+
+/** 列头右键菜单：插入×2 / 删除 / divider / 冻结 / 取消冻结 */
+export function buildColHeaderMenus(ctx: SheetContext): ContextmenuItem[] {
+  const range = primaryRange(ctx)
+  const startCol = range?.start.col ?? 0
+  const endCol = range?.end.col ?? startCol
+  const colCount = defaultInsertCount(range, 'col')
+  const deleteCount = range ? endCol - startCol + 1 : 1
+  const frozen = ctx.frozen
+  const freezeActive = frozen.cols === endCol + 1
+
+  return [
+    {
+      label: '在左侧插入列',
+      keepOpen: true,
+      render: insertCountRender({
+        prefix: '在左侧插入',
+        suffix: '列',
+        defaultValue: colCount,
+        onConfirm: (n) => ctx.insertCols(startCol, n)
+      })
+    },
+    {
+      label: '在右侧插入列',
+      keepOpen: true,
+      render: insertCountRender({
+        prefix: '在右侧插入',
+        suffix: '列',
+        defaultValue: colCount,
+        onConfirm: (n) => ctx.insertCols(endCol + 1, n)
+      })
+    },
+    { label: '删除列', callback: () => ctx.deleteCols(startCol, deleteCount) },
+    { divider: true },
+    {
+      label: freezeActive ? '✓ 冻结到当前列' : '冻结到当前列',
+      callback: () => ctx.setFrozen(frozen.rows, endCol + 1)
+    },
+    {
+      label: '取消冻结',
+      disabled: frozen.rows === 0 && frozen.cols === 0,
+      callback: () => ctx.setFrozen(0, 0)
+    }
+  ]
+}
+
+/** body 格右键菜单：合并/取消合并 + 插入图片（行列插入/删除仅行号/列头菜单） */
+export function buildBodyMenus(ctx: SheetContext): ContextmenuItem[] {
+  const mergeTool = defaultToolRegistry.get('merge')
+  const unmergeTool = defaultToolRegistry.get('unmerge')
+  const active = ctx.getSelection().activeCell
+
+  return [
+    {
+      label: '合并单元格',
+      disabled: mergeTool?.disabled?.(ctx) ?? true,
+      callback: () => mergeTool?.onClick(ctx)
+    },
+    {
+      label: '取消合并单元格',
+      disabled: unmergeTool?.disabled?.(ctx) ?? true,
+      callback: () => unmergeTool?.onClick(ctx)
+    },
+    { label: '插入图片', disabled: !active, callback: () => pickAndInsertImage(ctx) }
+  ]
+}
+
+/**
+ * 右键落点预处理：body 格落在选区外 → 选中该格；
+ * 行号/列头落在选区外 → 选中整行/整列（渲染尺寸）。
+ */
+export function ensureContextMenuSelection(
+  ctx: SheetContext,
+  info: {
+    kind: 'body' | 'row-header' | 'col-header'
+    addr: CellAddress | null
+    row?: number
+    col?: number
+  },
+  renderSize: { rows: number; cols: number }
+): void {
+  const ranges = ctx.getSelection().ranges
+
+  if (info.kind === 'body' && info.addr) {
+    const inSelection = ranges.some(
+      (range) =>
+        range.start.row <= info.addr!.row &&
+        info.addr!.row <= range.end.row &&
+        range.start.col <= info.addr!.col &&
+        info.addr!.col <= range.end.col
+    )
+    if (!inSelection) ctx.selectCell(info.addr)
+    return
+  }
+
+  if (info.kind === 'row-header' && info.row != null) {
+    if (!isRowInSelection(ranges, info.row)) {
+      ctx.selectRange(wholeRowRange(info.row, renderSize.cols))
+    }
+    return
+  }
+
+  if (info.kind === 'col-header' && info.col != null) {
+    if (!isColInSelection(ranges, info.col)) {
+      ctx.selectRange(wholeColRange(info.col, renderSize.rows))
+    }
+  }
+}

package/src/components/sheet/sheet-tabs.vue

@@ -0,0 +1,162 @@
+<template>
+  <div :class="cls.e('tabs')">
+    <button
+      v-show="showNav"
+      type="button"
+      :class="cls.e('tabs-nav')"
+      :disabled="!canPrev"
+      title="向左滚动"
+      @click="scrollByStep(-1)"
+    >
+      <u-icon><ArrowLeft /></u-icon>
+    </button>
+    <div ref="tabsViewportRef" :class="cls.e('tabs-viewport')">
+      <div ref="tabsListRef" :class="cls.e('tabs-list')">
+        <div
+          v-for="(sheet, index) in sheetList"
+          :key="sheet"
+          :class="[cls.e('tab'), bem.is('active', index === activeIndex)]"
+          title="右键重命名 / 删除"
+          @click="handleTabClick(index)"
+          @contextmenu.prevent="handleTabContextMenu($event, sheet, index)"
+        >
+          <input
+            v-if="renamingIndex === index"
+            ref="renameInputRef"
+            v-model="renameDraft"
+            :class="cls.e('tab-rename-input')"
+            :maxlength="31"
+            @click.stop
+            @keydown.enter.prevent="commitRename"
+            @keydown.esc.prevent="cancelRename"
+            @blur="commitRename"
+          />
+          <span v-else>{{ sheet.name }}</span>
+        </div>
+      </div>
+    </div>
+    <button
+      v-show="showNav"
+      type="button"
+      :class="cls.e('tabs-nav')"
+      :disabled="!canNext"
+      title="向右滚动"
+      @click="scrollByStep(1)"
+    >
+      <u-icon><ArrowRight /></u-icon>
+    </button>
+    <button type="button" :class="cls.e('tab-add')" title="添加工作表" @click="handleAddSheet">
+      +
+    </button>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { contextmenu, message, messageConfirm, UIcon } from '@veltra/desktop'
+import { ArrowLeft, ArrowRight } from '@veltra/icons/normal'
+import type { Sheet } from '@veltra/sheet-core/core/sheet'
+import type { Workbook } from '@veltra/sheet-core/core/workbook'
+import { bem } from '@veltra/utils'
+import { nextTick, ref, toRef, useTemplateRef } from 'vue'
+
+import { useSheetTabsBar } from './use-sheet-tabs-bar'
+
+defineOptions({ name: 'USheetTabs' })
+
+/**
+ * 底部 sheet tabs（可滚动视口 + 左右导航；「+」钉在视口外）：
+ * - tab 点击切换；末尾「+」addSheet + 自动激活新表（激活事件驱动 grid 重建）
+ * - tab 右键菜单「重命名 / 删除」：重命名进入行内输入（Enter 提交、Esc 取消、失焦提交；
+ *   冲突提示且不写入），删除二次确认（最后一个 sheet 的删除项禁用）
+ * - sheet 增删改名是工作簿级结构操作（不走 undo），直接调用 Workbook——
+ *   不经 SheetContext（见 AGENTS.md 门面边界）；UI 刷新由 workbook 事件驱动
+ */
+const props = defineProps<{ workbook: Workbook; sheetList: Sheet[]; activeIndex: number }>()
+
+const cls = bem('sheet')
+
+// ─── 可滚动视口（导航显隐 / 步进滚动 / 活动 tab 滚入视野）────────
+
+const tabsViewportRef = useTemplateRef<HTMLElement>('tabsViewportRef')
+const tabsListRef = useTemplateRef<HTMLElement>('tabsListRef')
+const { showNav, canPrev, canNext, scrollByStep } = useSheetTabsBar({
+  viewportRef: tabsViewportRef,
+  listRef: tabsListRef,
+  sheetList: toRef(props, 'sheetList'),
+  activeIndex: toRef(props, 'activeIndex')
+})
+
+function handleTabClick(index: number): void {
+  if (index === props.activeIndex) return
+  const sheet = props.sheetList[index]
+  if (sheet) props.workbook.activateSheet(sheet.name)
+}
+
+/** 「+」添加 sheet：自动激活新表（激活事件驱动 grid 重建） */
+function handleAddSheet(): void {
+  const sheet = props.workbook.addSheet()
+  props.workbook.activateSheet(sheet.name)
+}
+
+// ─── tab 右键菜单（重命名 / 删除）────────────────────────────
+
+/** 正在行内重命名的 tab 下标（-1 = 无） */
+const renamingIndex = ref(-1)
+const renameDraft = ref('')
+// 输入框在 v-for 内：useTemplateRef 收集为数组（Vue 3.5 v-for ref 语义）
+const renameInputRef = useTemplateRef<HTMLInputElement[]>('renameInputRef')
+
+function handleTabContextMenu(event: MouseEvent, sheet: Sheet, index: number): void {
+  // 右键菜单操作的是该 tab，不切换激活（与 Excel 一致：菜单动作不影响激活）
+  contextmenu.pop({
+    mousePosition: { x: event.clientX, y: event.clientY },
+    width: 160,
+    menus: [
+      { label: '重命名', callback: () => startRename(index) },
+      {
+        label: '删除',
+        disabled: props.sheetList.length <= 1,
+        callback: () => confirmRemoveSheet(sheet)
+      }
+    ]
+  })
+}
+
+/** 进入行内重命名（预填当前名并全选） */
+function startRename(index: number): void {
+  renamingIndex.value = index
+  renameDraft.value = props.sheetList[index]?.name ?? ''
+  // 等输入框渲染后聚焦全选
+  nextTick(() => renameInputRef.value?.[0]?.select())
+}
+
+/** 提交重命名：空名 / 重名（含大小写变体）由 Workbook 拒绝，提示且不写入 */
+function commitRename(): void {
+  const index = renamingIndex.value
+  if (index < 0) return
+  renamingIndex.value = -1
+  const sheet = props.sheetList[index]
+  if (!sheet) return
+  const next = renameDraft.value.trim()
+  if (next === '' || next === sheet.name) return
+  if (!props.workbook.renameSheet(sheet.name, next)) {
+    message.warn(`无法重命名：名称“${next}”无效或已被占用`)
+  }
+}
+
+function cancelRename(): void {
+  renamingIndex.value = -1
+}
+
+/** 删除确认（message-confirm）；最后一个 sheet 在菜单层已禁用，这里再兜底 */
+function confirmRemoveSheet(sheet: Sheet): void {
+  if (props.workbook.sheetCount <= 1) return
+  messageConfirm.danger(`确定删除工作表“${sheet.name}”吗？删除后不可恢复。`, {
+    confirmButtonText: '删除',
+    onClosed: (action) => {
+      if (action !== 'confirm') return
+      props.workbook.removeSheet(sheet.name)
+    }
+  })
+}
+</script>

package/src/components/sheet/sheet-toolbar.vue

@@ -0,0 +1,91 @@
+<template>
+  <div :class="cls.e('toolbar')">
+    <button
+      v-if="showNav"
+      type="button"
+      :class="cls.e('toolbar-nav')"
+      :disabled="!canPrev"
+      :aria-label="'向左滚动工具栏'"
+      @click="scrollByStep(-1)"
+    >
+      <u-icon><ArrowLeft /></u-icon>
+    </button>
+
+    <!-- 单行滚动视口：内容超出时由左右箭头导航（use-toolbar-scroll），不再换行 -->
+    <div ref="scrollRef" :class="cls.e('toolbar-scroll')">
+      <div ref="listRef" :class="cls.e('toolbar-list')">
+        <template v-for="(group, groupIndex) in groups" :key="group.name">
+          <span v-if="groupIndex > 0" :class="cls.e('toolbar-divider')" />
+          <u-tip
+            v-for="item in group.tools"
+            :key="item.tool.id"
+            :content="item.tool.tooltip ?? item.tool.title"
+            trigger="hover"
+            direction="top"
+            alignment="center"
+            :show-delay="400"
+            :disabled="item.disabled"
+          >
+            <button
+              type="button"
+              :class="[cls.e('tool'), bem.is('active', item.active)]"
+              :data-tool-id="item.tool.id"
+              :disabled="item.disabled"
+              :title="item.tool.tooltip ?? item.tool.title"
+              @click="emit('toolClick', item.tool, $event)"
+            >
+              <component :is="item.tool.icon" v-if="item.tool.icon" :class="cls.e('tool-icon')" />
+              <span v-else>{{ item.tool.title }}</span>
+            </button>
+          </u-tip>
+        </template>
+      </div>
+    </div>
+
+    <button
+      v-if="showNav"
+      type="button"
+      :class="cls.e('toolbar-nav')"
+      :disabled="!canNext"
+      :aria-label="'向右滚动工具栏'"
+      @click="scrollByStep(1)"
+    >
+      <u-icon><ArrowRight /></u-icon>
+    </button>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { UIcon } from '@veltra/desktop'
+import { ArrowLeft, ArrowRight } from '@veltra/icons/normal'
+import { bem } from '@veltra/utils'
+import { toRef, useTemplateRef } from 'vue'
+
+import type { SheetTool } from '../../tools/registry'
+import type { ToolGroupView } from './use-tool-groups'
+import { useToolbarScroll } from './use-toolbar-scroll'
+
+defineOptions({ name: 'USheetToolbar' })
+
+/**
+ * 工具栏（渲染 defaultToolRegistry 分组工具 + 分隔符，单行溢出滚动）。
+ * 纯展示：有 icon 时只渲染图标（title/tooltip 经 UTip + 原生 title 兜底）；
+ * 无 icon 时回落文字按钮（自定义工具兼容）。
+ * 内容超出视口时显示左右箭头（点击步进滚动、滚轮横滚），不换行挤压 grid。
+ */
+const props = defineProps<{ groups: ToolGroupView[] }>()
+
+const emit = defineEmits<{ toolClick: [tool: SheetTool, event: MouseEvent] }>()
+
+const cls = bem('sheet')
+
+// ─── 溢出滚动（箭头显隐 / 步进 / 滚轮横滚）────────────────────
+
+const scrollRef = useTemplateRef<HTMLElement>('scrollRef')
+const listRef = useTemplateRef<HTMLElement>('listRef')
+const { showNav, canPrev, canNext, scrollByStep } = useToolbarScroll({
+  viewportRef: scrollRef,
+  listRef,
+  content: toRef(props, 'groups')
+})
+</script>