@veltra/sheet 2.5.6 → 2.5.7

package/src/components/sheet/__test__/sheet-component.test.ts

@@ -120,6 +120,7 @@ describe('USheet 组件', () => {
       'valign-bottom',
       'wrap-text',
       'find',
+      'functions',
       'insert-image',
       'import',
       'export'

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

@@ -46,15 +46,16 @@ describe('getSuggestContext', () => {
 })
 
 describe('filterFormulaSuggestions / applySuggest / moveSuggestIndex', () => {
-  it('空前缀优先常用函数（含 SUM），至多 10 条；SU 过滤到 SUM', () => {
+  it('空前缀优先常用函数（含 SUM），至多 10 条；SU 过滤到 SUBSTITUTE / SUM（名称升序）', () => {
     const all = filterFormulaSuggestions('')
     expect(all.length).toBeGreaterThan(0)
     expect(all.length).toBeLessThanOrEqual(FORMULA_SUGGEST_LIMIT)
     expect(all[0]!.name).toBe('SUM')
     expect(all.map((s) => s.name)).toContain('SUM')
     const su = filterFormulaSuggestions('SU')
-    expect(su.map((s) => s.name)).toEqual(['SUM'])
-    expect(su[0]!.signature).toBe(formatFunctionSignature('SUM', su[0]!.params))
+    expect(su.map((s) => s.name)).toEqual(['SUBSTITUTE', 'SUM'])
+    const sum = su.find((s) => s.name === 'SUM')!
+    expect(sum.signature).toBe(formatFunctionSignature('SUM', sum.params))
   })
 
   it('无 meta 函数签名仅为名称', () => {

package/src/components/sheet/formula-bar.vue

@@ -10,7 +10,33 @@
       @blur="handleNameBlur"
       @keydown="handleNameKeydown"
     />
-    <span :class="cls.e('fx-label')">fx</span>
+    <button
+      ref="fxLabelRef"
+      type="button"
+      :class="cls.e('fx-label')"
+      :disabled="fxDisabled"
+      title="插入函数"
+      @mousedown.prevent
+      @click.stop="toggleFunctions"
+    >
+      fx
+    </button>
+    <!-- 函数弹框：锚定 fx 按钮下方（UDropdown Teleport 到 #pop-container，
+         同工具栏弹层机制）；打开 / 关闭不触碰选区与草稿 -->
+    <u-dropdown
+      ref="functionsDropdownRef"
+      trigger="custom"
+      :visible="functionsOpen"
+      width="auto"
+      @keydown="handleFunctionsKeydown"
+      @update:visible="syncFunctionsOpen"
+    >
+      <template #content>
+        <div v-if="functionsOpen" :class="cls.e('functions-popover')" @click.stop>
+          <u-sheet-functions-popup @select="handleFunctionSelect" />
+        </div>
+      </template>
+    </u-dropdown>
     <div
       :class="cls.e('fx-editor')"
       @mouseenter="handleFxMouseEnter"
@@ -68,7 +94,7 @@
 </template>
 
 <script lang="ts" setup>
-import { message } from '@veltra/desktop'
+import { message, UDropdown } from '@veltra/desktop'
 import {
   formatAddress,
   formatRange,
@@ -92,6 +118,7 @@ import {
 
 import type { SheetContext } from '../../tools/context'
 import UFormulaSuggestList from './formula-suggest-list.vue'
+import USheetFunctionsPopup from './popups/functions-popup.vue'
 import { insertRefText, isRefSelectContext } from './use-formula-ref-select'
 import {
   applySuggest,
@@ -107,6 +134,7 @@ defineOptions({ name: 'UFormulaBar' })
  * 公式栏（名称框 + fx 输入栏），USheet 顶部结构之一。
  *
  * - 名称框：显示当前选区（单格 A1 / 区域 A1:B2）；合法地址回车跳转。
+ * - fx 按钮：打开函数弹框（分类导航 + 搜索），选中进入编辑态输出 `=NAME()`。
  * - fx 输入栏：活动格内容；Enter/✓ 提交、Esc/✗ 取消、失焦提交。
  * - 函数补全：`=` 开头且光标在函数名 token 上时弹出候选（↑↓ / Tab / Enter / 点击）。
  * - 引用选择：光标在运算符/`(`/`,` 后时，画布点选/拖选插入引用（blur 抑制防误提交）。
@@ -155,9 +183,9 @@ function beginBlurSuppress(): void {
   suppressBlurCommit = true
 }
 
-/** 选区拦截回调：插入 A1 / A1:B2 到光标处 */
+/** 选区拦截回调：插入 A1 / A1:B2 到光标处（仅引用选择模式；弹框打开但非引用上下文时不插入） */
 function handleRefSelect(range: CellRange): void {
-  if (!editing.value || mirroring.value) return
+  if (!isRefSelecting()) return
   const rangeText = formatRange(range)
   const el = fxRef.value
   const selEnd = el?.selectionEnd ?? fxCursor.value
@@ -432,7 +460,14 @@ function commitEdit(): void {
   editAddr = null
   suppressBlurCommit = false
   closeSuggest()
-  if (addr) props.context.setCellValue(addr, fxDraft.value)
+  if (addr) {
+    props.context.setCellValue(addr, fxDraft.value)
+    // 选区离开目标格（如编辑期间名称框跳转）：回推模型选区，grid 层随之恢复目标格高亮
+    const active = selection.value.activeCell
+    if (!active || active.row !== addr.row || active.col !== addr.col) {
+      props.context.selectCell(addr)
+    }
+  }
   refreshFx()
 }
 
@@ -490,7 +525,94 @@ function exitMirror(addr: CellAddress): void {
   }
 }
 
-defineExpose({ mirrorGridEdit, exitMirror, isRefSelecting, beginBlurSuppress, handleRefSelect })
+// ─── 函数弹框（fx 按钮）────────────────────────────────────
+
+const fxLabelRef = useTemplateRef<HTMLButtonElement>('fxLabelRef')
+const functionsDropdownRef = useTemplateRef<InstanceType<typeof UDropdown>>('functionsDropdownRef')
+const functionsOpen = ref(false)
+
+function toggleFunctions(): void {
+  if (fxDisabled.value) return
+  if (functionsOpen.value) {
+    functionsOpen.value = false
+    return
+  }
+  // 焦点即将移向弹框搜索框：抑制 fx blur 提交，草稿与编辑态原样保留
+  if (editing.value && fxFocused.value) suppressBlurCommit = true
+  functionsOpen.value = true
+}
+
+// 弹框打开必须同步调 open() 传 fx 按钮作锚点（同 sheet.vue 工具弹层时序）
+watch(functionsOpen, () => {
+  const dropdown = functionsDropdownRef.value
+  if (!dropdown) return
+  if (functionsOpen.value) {
+    dropdown.open({ trigger: fxLabelRef.value ?? undefined })
+  } else {
+    dropdown.close()
+  }
+})
+
+/** UDropdown 内部关闭（触发元素位移等）→ 同步本地开合状态 */
+function syncFunctionsOpen(visible: boolean): void {
+  if (!visible) functionsOpen.value = false
+}
+
+/** 弹框内 Esc 关闭（关闭不还原草稿、不退出挂起的编辑态） */
+function handleFunctionsKeydown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return
+  event.preventDefault()
+  functionsOpen.value = false
+}
+
+/** 点击弹框外关闭（弹框内容与 fx 按钮均 @click.stop，到达这里的必是外部点击） */
+function closeFunctionsOnOuterClick(): void {
+  if (!functionsOpen.value) return
+  functionsOpen.value = false
+}
+
+/** 选中函数：关弹框并进入编辑态输出 =NAME()（fx / 工具栏共用路径） */
+function handleFunctionSelect(name: string): void {
+  functionsOpen.value = false
+  insertFunction(name)
+}
+
+/** 插入函数：编辑目标 = 当前活动格，内容覆盖为 =NAME()，光标落在括号内 */
+function insertFunction(name: string): void {
+  const addr = selection.value.activeCell
+  if (!addr) return
+  const text = `=${name}()`
+  const cursor = text.length - 1
+  editing.value = true
+  editAddr = addr
+  mirroring.value = false
+  mirrorAddr = null
+  fxDraft.value = text
+  fxCursor.value = cursor
+  suppressBlurCommit = false
+  closeSuggest()
+  void nextTick(() => {
+    const el = fxRef.value
+    if (!el) return
+    el.focus()
+    // focus 事件里 syncFxCursor 会读到置尾光标，这里用局部值落位覆盖
+    el.setSelectionRange(cursor, cursor)
+    fxCursor.value = cursor
+    autosizeFx()
+    // `=NAME()` 光标在括号内：处于引用选择上下文，不再弹补全
+    refreshSuggest()
+  })
+}
+
+defineExpose({
+  mirrorGridEdit,
+  exitMirror,
+  isRefSelecting,
+  isFunctionPopupOpen: () => functionsOpen.value,
+  beginBlurSuppress,
+  handleRefSelect,
+  insertFunction
+})
 
 // ─── 生命周期 ──────────────────────────────────────────────
 
@@ -512,6 +634,7 @@ watch(
     mirroring.value = false
     mirrorAddr = null
     suppressBlurCommit = false
+    functionsOpen.value = false
     closeSuggest()
     bindSheet(sheet)
     selection.value = sheet.getSelection()
@@ -525,10 +648,12 @@ onMounted(() => {
   selection.value = props.sheet.getSelection()
   refreshName()
   refreshFx()
+  window.addEventListener('click', closeFunctionsOnOuterClick)
 })
 
 onBeforeUnmount(() => {
   for (const off of dispose) off()
   dispose = []
+  window.removeEventListener('click', closeFunctionsOnOuterClick)
 })
 </script>

package/src/components/sheet/popups/functions-popup.vue

@@ -0,0 +1,141 @@
+<template>
+  <div ref="panelRef" :class="cls.e('functions-panel')" @keydown="handleKeydown">
+    <nav :class="cls.e('functions-nav')">
+      <button
+        v-for="cat in FUNCTION_POPUP_CATEGORIES"
+        :key="cat"
+        type="button"
+        :class="[cls.e('functions-nav-item'), bem.is('active', cat === activeCategory)]"
+        @click="selectCategory(cat)"
+      >
+        {{ cat }}
+      </button>
+    </nav>
+    <div :class="cls.e('functions-main')">
+      <u-input
+        v-model="keyword"
+        :placeholder="'搜索函数名或描述'"
+        size="small"
+        :class="cls.e('functions-search')"
+      />
+      <!-- 滚动用 desktop UScroll（自定义滚动条），同字号面板 -->
+      <u-scroll :height="320" :class="cls.e('functions-scroll')">
+        <div v-if="visible.length > 0" :class="cls.e('functions-list')">
+          <div
+            v-for="(fn, index) in visible"
+            :key="fn.name"
+            :class="[cls.e('functions-item'), bem.is('active', index === activeIndex)]"
+            @click="emit('select', fn.name)"
+            @mouseenter="activeIndex = index"
+          >
+            <span :class="cls.e('functions-signature')">{{
+              formatFunctionSignature(fn.name, fn.params)
+            }}</span>
+            <span v-if="fn.description" :class="cls.e('functions-description')">{{
+              fn.description
+            }}</span>
+          </div>
+        </div>
+        <div v-else :class="cls.e('functions-empty')">无匹配函数</div>
+      </u-scroll>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { UInput, UScroll } from '@veltra/desktop'
+import {
+  listFormulaFunctions,
+  type FormulaFunctionMeta
+} from '@veltra/sheet-core/core/formula/functions'
+import { bem } from '@veltra/utils'
+import { computed, onMounted, ref, useTemplateRef, watch } from 'vue'
+
+import {
+  COMMON_FORMULA_NAMES,
+  formatFunctionSignature,
+  FUNCTION_POPUP_CATEGORIES,
+  moveSuggestIndex,
+  type FunctionPopupCategory
+} from '../use-formula-suggest'
+
+defineOptions({ name: 'USheetFunctionsPopup' })
+
+/**
+ * 函数弹框（分类导航 + 搜索 + 可选择）：fx 按钮与工具栏「函数」共用。
+ * 列出全部已注册函数（内置 + 宿主经 registerFormulaFunction 注册的自定义函数），
+ * 选中仅 emit select(name)，由公式栏接管（进入编辑态输出 =NAME()），不写模型。
+ * 弹框随 v-if 挂载 / 销毁，每次打开都是全新状态（关键词清空、回到「常用」）。
+ */
+
+type FunctionItem = { name: string } & FormulaFunctionMeta
+
+const emit = defineEmits<{ select: [name: string] }>()
+
+const cls = bem('sheet')
+
+const panelRef = useTemplateRef<HTMLElement>('panelRef')
+
+const keyword = ref('')
+const activeCategory = ref<FunctionPopupCategory>('常用')
+/** 键盘 / 悬停高亮下标（点击即确认不高亮） */
+const activeIndex = ref(0)
+
+/** 打开时快照一次注册表（弹框存活期间注册表变化不追踪，重开即刷新） */
+const all: FunctionItem[] = listFormulaFunctions()
+
+/** 关键词大小写不敏感子串匹配：名称或中文描述；跨分类（未分类函数也可搜到） */
+function searchResult(key: string): FunctionItem[] {
+  return all.filter(
+    (fn) => fn.name.toLowerCase().includes(key) || fn.description.toLowerCase().includes(key)
+  )
+}
+
+/** 当前展示列表：搜索优先；否则按分类导航过滤 */
+const visible = computed<FunctionItem[]>(() => {
+  const key = keyword.value.trim().toLowerCase()
+  if (key) return searchResult(key)
+  if (activeCategory.value === '全部') return all
+  if (activeCategory.value === '常用') {
+    // 固定清单（顺序即 COMMON_FORMULA_NAMES 顺序）；注册表中缺失的名称跳过
+    const byName = new Map(all.map((fn) => [fn.name, fn]))
+    return COMMON_FORMULA_NAMES.map((name) => byName.get(name)).filter(
+      (fn): fn is FunctionItem => fn != null
+    )
+  }
+  // 分类项只列声明了该 category 的函数（未分类函数不进任何分类）
+  return all.filter((fn) => fn.category === activeCategory.value)
+})
+
+watch(visible, () => {
+  activeIndex.value = 0
+})
+
+function selectCategory(cat: FunctionPopupCategory): void {
+  activeCategory.value = cat
+}
+
+/** 键盘路径：↑↓ 移动高亮（循环），Enter 确认选中（Esc 交由外层弹框关闭） */
+function handleKeydown(event: KeyboardEvent): void {
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    event.preventDefault()
+    activeIndex.value = moveSuggestIndex(
+      activeIndex.value,
+      visible.value.length,
+      event.key === 'ArrowDown' ? 1 : -1
+    )
+    return
+  }
+  if (event.key === 'Enter') {
+    const fn = visible.value[activeIndex.value]
+    if (!fn) return
+    event.preventDefault()
+    emit('select', fn.name)
+  }
+}
+
+// 打开即聚焦搜索框，键盘可直接检索 / 导航（查 DOM 而非组件 expose，stub 环境同样可用）
+onMounted(() => {
+  panelRef.value?.querySelector('input')?.focus()
+})
+</script>

package/src/components/sheet/sheet.vue

@@ -3,7 +3,7 @@
     <div :class="cls.e('toolbar-wrap')">
       <u-sheet-toolbar v-if="showToolbar" :groups="toolGroups" @tool-click="handleToolClick" />
 
-      <!-- 弹层型工具面板（填充/边框/字体色/字号/查找/插入图片/导出）：UDropdown（Teleport 到
+      <!-- 弹层型工具面板（填充/边框/字体色/字号/查找/函数/插入图片/导出）：UDropdown（Teleport 到
            #pop-container + floating-ui 定位：锚点跟随触发按钮、自动翻转/边界位移；
            触发元素滚动/窗口缩放时自动关闭）。面板交互走 SheetContext 命令入口。
            导入无弹层：点击直接系统文件选择（见 handleToolClick → pickAndImportFile） -->
@@ -32,6 +32,10 @@
               :context="context"
               @close="closePopup"
             />
+            <u-sheet-functions-popup
+              v-else-if="popupTool.popup === 'functions'"
+              @select="handleFunctionSelect"
+            />
             <u-sheet-insert-image-popup
               v-else-if="popupTool.popup === 'insert-image'"
               :context="context"
@@ -87,6 +91,7 @@ import USheetFillColorPopup from './popups/fill-color-popup.vue'
 import USheetFindPopup from './popups/find-popup.vue'
 import USheetFontColorPopup from './popups/font-color-popup.vue'
 import USheetFontSizePopup from './popups/font-size-popup.vue'
+import USheetFunctionsPopup from './popups/functions-popup.vue'
 import USheetInsertImagePopup from './popups/insert-image-popup.vue'
 import USheetTabs from './sheet-tabs.vue'
 import USheetToolbar from './sheet-toolbar.vue'
@@ -162,6 +167,12 @@ function handleToolClick(tool: SheetTool, event?: MouseEvent): void {
   openOrRunTool(tool, event)
 }
 
+/** 工具栏「函数」弹框选中 → 关弹层并走公式栏统一插入路径（与 fx 按钮一致） */
+function handleFunctionSelect(name: string): void {
+  closePopup()
+  formulaBarRef.value?.insertFunction(name)
+}
+
 // ─── UDropdown 面板：锚点跟随触发按钮（floating-ui 定位）──────────
 
 const popupDropdownRef = useTemplateRef<InstanceType<typeof UDropdown>>('popupDropdownRef')
@@ -199,7 +210,9 @@ const { rebuildGrid, activateGrid, pruneCache, getGrid } = useSheetGrid({
   gridRef,
   getActiveSheet: () => activeSheet.value,
   context,
-  formulaBarRef
+  formulaBarRef,
+  // 工具栏「函数」弹框打开期间与 fx 入口一致：画布点击不清除目标格高亮
+  isFunctionPopupOpen: () => popupTool.value?.popup === 'functions'
 })
 
 const exposed: _SheetExposed = {

package/src/components/sheet/style.scss

@@ -246,10 +246,25 @@
     flex-shrink: 0;
     align-items: center;
     height: fn.use-var(form-component-height, small);
+    padding: 0 4px;
+    border: none;
+    border-radius: fn.use-var(radius, small);
+    background: transparent;
     color: fn.use-var(text-color, second);
     font-size: fn.use-var(font-size-main, small);
     font-style: italic;
     user-select: none;
+    cursor: pointer;
+
+    &:hover:not(:disabled) {
+      background-color: fn.use-var(bg-color, hover);
+      color: fn.use-var(text-color, main);
+    }
+
+    &:disabled {
+      color: fn.use-var(text-color, disabled);
+      cursor: not-allowed;
+    }
   }
 
   @include m.e(fx-input) {
@@ -531,6 +546,108 @@
     }
   }
 
+  /* ─── 函数弹框（分类导航 + 搜索 + 可选择；fx 按钮与工具栏共用）── */
+
+  @include m.e(functions-popover) {
+    display: flex;
+    flex-direction: column;
+  }
+
+  @include m.e(functions-panel) {
+    display: flex;
+    gap: fn.use-var(gap, small);
+  }
+
+  @include m.e(functions-nav) {
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    gap: 2px;
+    padding: 4px;
+    border-right: 1px solid fn.use-var(border, muted-color);
+    min-width: 96px;
+  }
+
+  @include m.e(functions-nav-item) {
+    padding: 4px 8px;
+    border: none;
+    border-radius: fn.use-var(radius, small);
+    background: transparent;
+    color: fn.use-var(text-color, second);
+    font-size: fn.use-var(font-size-main, small);
+    text-align: left;
+    white-space: nowrap;
+    cursor: pointer;
+
+    &:hover {
+      background-color: fn.use-var(bg-color, hover);
+    }
+
+    @include m.is(active) {
+      background-color: fn.use-var(bg-color, hover);
+      color: fn.use-var(color, primary);
+      font-weight: 600;
+    }
+  }
+
+  @include m.e(functions-main) {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    flex: 1;
+    min-width: 0;
+  }
+
+  @include m.e(functions-search) {
+    width: 320px;
+  }
+
+  @include m.e(functions-scroll) {
+    width: 320px;
+  }
+
+  @include m.e(functions-list) {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+
+  @include m.e(functions-item) {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    padding: 6px 8px;
+    border-radius: fn.use-var(radius, small);
+    cursor: pointer;
+
+    &:hover {
+      background-color: fn.use-var(bg-color, hover);
+    }
+
+    @include m.is(active) {
+      background-color: fn.use-var(bg-color, hover);
+    }
+  }
+
+  @include m.e(functions-signature) {
+    color: fn.use-var(text-color, main);
+    font-size: fn.use-var(font-size-main, small);
+    font-weight: 600;
+    font-family: 'JetBrains Mono', Consolas, 'Courier New', monospace;
+  }
+
+  @include m.e(functions-description) {
+    color: fn.use-var(text-color, second);
+    font-size: fn.use-var(font-size-assist, small);
+  }
+
+  @include m.e(functions-empty) {
+    padding: 16px 0;
+    color: fn.use-var(text-color, second);
+    font-size: fn.use-var(font-size-main, small);
+    text-align: center;
+  }
+
   @include m.e(insert-image-hint) {
     padding: 8px 10px;
     border: 1px dashed fn.use-var(border, muted-color);

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

@@ -23,6 +23,25 @@ export const COMMON_FORMULA_NAMES = [
   'OR'
 ] as const
 
+/**
+ * 函数弹框分类导航固定集合（顺序即展示顺序）。
+ * 「常用」「全部」是导航概念（非注册表分类）：常用 = COMMON_FORMULA_NAMES 固定清单，
+ * 全部 = 全部已注册函数；其余与 sheet-core `FormulaFunctionCategory` 对应。
+ */
+export const FUNCTION_POPUP_CATEGORIES = [
+  '常用',
+  '全部',
+  '财务',
+  '日期与时间',
+  '数学',
+  '统计',
+  '查找与引用',
+  '文本',
+  '逻辑'
+] as const
+
+export type FunctionPopupCategory = (typeof FUNCTION_POPUP_CATEGORIES)[number]
+
 /** 函数名 token 前合法的「触发」字符（= / 运算符 / ( / ,） */
 const SUGGEST_TRIGGER_CHARS = new Set(['=', '(', ',', '+', '-', '*', '/', '^', '&', '<', '>'])
 

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

@@ -23,6 +23,8 @@ export interface FormulaBarMirror {
   exitMirror: (addr: CellAddress) => void
   /** fx 编辑中且处于可插入引用位置 */
   isRefSelecting: () => boolean
+  /** 函数弹框打开中（fx 入口）——画布点击不清除目标格高亮 */
+  isFunctionPopupOpen: () => boolean
   /** 网格 pointerdown → 挂起 blur 提交 */
   beginBlurSuppress: () => void
   /** 画布选区 → 插入引用文本 */
@@ -35,6 +37,8 @@ interface UseSheetGridOptions {
   getActiveSheet: () => Sheet
   context: SheetContext
   formulaBarRef: ElRef<FormulaBarMirror>
+  /** 函数弹框打开中（宿主侧入口，如工具栏「函数」按钮） */
+  isFunctionPopupOpen?: () => boolean
 }
 
 /** 缓存实例（LRU 淘汰）：每个 sheet 一个独立容器 div，非激活容器 visibility:hidden 堆叠 */
@@ -125,8 +129,12 @@ export function useSheetGrid(options: UseSheetGridOptions) {
       onContextMenu: handleContextMenu,
       onEditStart: (addr) => formulaBarRef.value?.mirrorGridEdit(addr),
       onEditEnd: (addr) => formulaBarRef.value?.exitMirror(addr),
-      // 引用选择：不回写模型选区，序列化为 A1 / A1:B2 交给公式栏
-      interceptSelection: () => formulaBarRef.value?.isRefSelecting() ?? false,
+      // 引用选择：不回写模型选区，序列化为 A1 / A1:B2 交给公式栏；
+      // 函数弹框打开期间（fx / 工具栏两入口）同样拦截，画布点击不离开目标格
+      interceptSelection: () =>
+        (formulaBarRef.value?.isRefSelecting() ?? false) ||
+        (formulaBarRef.value?.isFunctionPopupOpen() ?? false) ||
+        (options.isFunctionPopupOpen?.() ?? false),
       onSelectionIntercept: (range) => formulaBarRef.value?.handleRefSelect(range)
     })
     // 结构变更订阅（vue 层只绑定激活 sheet；隐藏实例必须自持标记，切回时判定过期）

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

@@ -9,7 +9,8 @@ type ElRef = { readonly value: HTMLElement | null | undefined }
 /**
  * 面板打开期间的写入是否合并为一个 undo 单元（关闭时提交）：
  * 填充颜色 / 边框 / 字体颜色 / 字号参与事务；查找（每次替换独立 undo）、
- * 导出（下载侧效应，无模型写入）不参与。导入无弹层，不经此路径。
+ * 函数（选中仅进入公式栏编辑态，模型写入待 fx 提交）、导出（下载侧效应，
+ * 无模型写入）不参与。导入无弹层，不经此路径。
  */
 function joinsTransaction(tool: SheetTool): boolean {
   return (
@@ -21,12 +22,13 @@ function joinsTransaction(tool: SheetTool): boolean {
 }
 
 /**
- * 弹层型工具编排（填充颜色 / 边框 / 查找 / 插入图片 / 导出）：
+ * 弹层型工具编排（填充颜色 / 边框 / 查找 / 函数 / 插入图片 / 导出）：
  * - popupTool：当前打开的弹层工具（null = 未打开）
  * - popupAnchor：触发按钮元素（面板定位参照，见 sheet.vue 的 left 计算）
  * - 打开 / 关闭时的事务包裹（面板期间写入合并为一个 undo 单元，关闭时提交）
  * - 点击面板外关闭（面板内 @click.stop 不冒泡到 window）
  * - Ctrl/Cmd+F 开合查找条（与工具按钮同一 toggle 逻辑）
+ * 函数面板选中只进入公式栏编辑态（无直接模型写入），与查找 / 导出一样不参与事务。
  * 导入在 sheet.vue 特殊处理（直接系统文件选择），不经弹层。
  */
 export function useToolPopup(context: SheetContext, rootEl: ElRef) {

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

@@ -52,7 +52,7 @@ describe('内置工具（dogfood 扩展机制）', () => {
       'valign-bottom',
       'wrap-text'
     ])
-    expect(groups[3]!.tools.map((tool) => tool.id)).toEqual(['find'])
+    expect(groups[3]!.tools.map((tool) => tool.id)).toEqual(['find', 'functions'])
     expect(groups[4]!.tools.map((tool) => tool.id)).toEqual(['insert-image'])
     expect(groups[5]!.tools.map((tool) => tool.id)).toEqual(['import', 'export'])
 
@@ -214,6 +214,14 @@ describe('内置工具（dogfood 扩展机制）', () => {
     expect(find.disabled).toBeUndefined()
   })
 
+  it('函数工具：弹层型声明（popup: functions），组 edit；纯查看不依赖选区', () => {
+    const tool = mustGet('functions')
+    expect(tool.popup).toBe('functions')
+    expect(tool.group).toBe('edit')
+    expect(tool.icon).toBeTruthy()
+    expect(tool.disabled).toBeUndefined()
+  })
+
   it('插入图片工具：弹层型声明（popup: insert-image），组 insert；无选区禁用', () => {
     const sheet = new Sheet()
     const ctx = createSheetContext(sheet)