@veltra/sheet 2.5.6 → 2.5.8

package/dist/components/sheet/use-formula-suggest.js

@@ -1,4 +1,4 @@
-import { listFormulaFunctions } from "@veltra/sheet-core/core/formula/functions";
+import { listFormulaFunctions } from "@veltra/sheet-core/core/formula/functions.js";
 /**
 * 空前缀时优先展示的常用函数（其余按名称升序补齐至上限）。
 * 纯字典序会把 SUM / OR / ROUND 挤出前 10（ABS…NOT），导致输入 `=` 看不到 SUM。
@@ -15,6 +15,22 @@ const COMMON_FORMULA_NAMES = [
 	"AND",
 	"OR"
 ];
+/**
+* 函数弹框分类导航固定集合（顺序即展示顺序）。
+* 「常用」「全部」是导航概念（非注册表分类）：常用 = COMMON_FORMULA_NAMES 固定清单，
+* 全部 = 全部已注册函数；其余与 sheet-core `FormulaFunctionCategory` 对应。
+*/
+const FUNCTION_POPUP_CATEGORIES = [
+	"常用",
+	"全部",
+	"财务",
+	"日期与时间",
+	"数学",
+	"统计",
+	"查找与引用",
+	"文本",
+	"逻辑"
+];
 /** 函数名 token 前合法的「触发」字符（= / 运算符 / ( / ,） */
 const SUGGEST_TRIGGER_CHARS = /* @__PURE__ */ new Set([
 	"=",
@@ -123,4 +139,4 @@ function moveSuggestIndex(activeIndex, length, delta) {
 	return ((activeIndex % length + length) % length + delta + length) % length;
 }
 //#endregion
-export { COMMON_FORMULA_NAMES, applySuggest, filterFormulaSuggestions, formatFunctionSignature, getSuggestContext, moveSuggestIndex };
+export { COMMON_FORMULA_NAMES, FUNCTION_POPUP_CATEGORIES, applySuggest, filterFormulaSuggestions, formatFunctionSignature, getSuggestContext, moveSuggestIndex };

package/dist/components/sheet/use-sheet-grid.js

@@ -72,7 +72,7 @@ function useSheetGrid(options) {
 			onContextMenu: handleContextMenu,
 			onEditStart: (addr) => formulaBarRef.value?.mirrorGridEdit(addr),
 			onEditEnd: (addr) => formulaBarRef.value?.exitMirror(addr),
-			interceptSelection: () => formulaBarRef.value?.isRefSelecting() ?? false,
+			interceptSelection: () => (formulaBarRef.value?.isRefSelecting() ?? false) || (formulaBarRef.value?.isFunctionPopupOpen() ?? false) || (options.isFunctionPopupOpen?.() ?? false),
 			onSelectionIntercept: (range) => formulaBarRef.value?.handleRefSelect(range)
 		});
 		let dirty = false;

package/dist/components/sheet/use-sheet-state.js

@@ -2,7 +2,7 @@ import { defaultToolRegistry } from "../../tools/registry.js";
 import { createSheetContext } from "../../tools/context.js";
 import { resolveRenderSize } from "./sheet-context-menu.js";
 import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vue";
-import { Workbook } from "@veltra/sheet-core/core/workbook";
+import { Workbook } from "@veltra/sheet-core/core/workbook.js";
 //#region src/components/sheet/use-sheet-state.ts
 /**
 * USheet 的状态源（单一数据源，其余状态由此推导）：

package/dist/components/sheet/use-tool-popup.js

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

package/dist/tools/builtin.js

@@ -1,7 +1,7 @@
 import { registerTool } from "./registry.js";
 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 { AlignBottom, AlignCenter, AlignTop, Bold, Border, Download, Fill, FontSize, Italic, MergeCells, PictureRounded, Rollback, Rollfront, Search, Strikethrough, Underline, UnmergeCells, Upload, Variable, VerticalAlignCenter, VerticalAlignLeft, VerticalAlignRight, Wrap } from "@veltra/icons/normal";
+import { rangesEqual } from "@veltra/sheet-core/core/address.js";
 //#region src/tools/builtin.ts
 /** 取活动格所在首选区；无选区返回 null */
 function selectionRange(ctx) {
@@ -310,6 +310,16 @@ registerTool({
 	popup: "find",
 	onClick: () => {}
 });
+registerTool({
+	id: "functions",
+	title: "函数",
+	icon: Variable,
+	tooltip: "按分类浏览并插入函数",
+	group: "edit",
+	order: 1,
+	popup: "functions",
+	onClick: () => {}
+});
 registerTool({
 	id: "insert-image",
 	title: "插入图片",

package/dist/tools/context.d.ts

@@ -1,14 +1,14 @@
-import { CellAddress, CellRange } from "@veltra/sheet-core/core/address";
-import { CellStyle, CellStylePatch } from "@veltra/sheet-core/core/style/types";
-import { CellData, CellValue } from "@veltra/sheet-core/core/cell-store";
-import { Workbook } from "@veltra/sheet-core/core/workbook";
-import { FrozenState, Sheet } from "@veltra/sheet-core/core/sheet";
-import { HistoryState } from "@veltra/sheet-core/core/command/history";
-import { ImageUpdateFields } from "@veltra/sheet-core/core/command/image";
-import { SetCellValueItem } from "@veltra/sheet-core/core/command/set-cell-value";
-import { ImageInput, SheetImage } from "@veltra/sheet-core/core/image";
-import { CellInfo } from "@veltra/sheet-core/core/merge-manager";
-import { SelectionState } from "@veltra/sheet-core/core/selection";
+import { CellAddress, CellRange } from "@veltra/sheet-core/core/address.js";
+import { CellStyle, CellStylePatch } from "@veltra/sheet-core/core/style/types.js";
+import { CellData, CellValue } from "@veltra/sheet-core/core/cell-store.js";
+import { Workbook } from "@veltra/sheet-core/core/workbook.js";
+import { FrozenState, Sheet } from "@veltra/sheet-core/core/sheet.js";
+import { HistoryState } from "@veltra/sheet-core/core/command/history.js";
+import { ImageUpdateFields } from "@veltra/sheet-core/core/command/image.js";
+import { SetCellValueItem } from "@veltra/sheet-core/core/command/set-cell-value.js";
+import { ImageInput, SheetImage } from "@veltra/sheet-core/core/image.js";
+import { CellInfo } from "@veltra/sheet-core/core/merge-manager.js";
+import { SelectionState } from "@veltra/sheet-core/core/selection.js";
 //#region src/tools/context.d.ts
 /**
  * SheetContext：工具的唯一操作门面。
@@ -19,7 +19,7 @@ import { SelectionState } from "@veltra/sheet-core/core/selection";
  * - 不暴露 Sheet 实例本身，保证门面就是扩展能力的全部边界
  * - USheet 切换 sheet tab 后，同一上下文自动指向新的活动 sheet
  */
-interface SheetContext {
+export interface SheetContext {
   /** 当前活动 sheet 名 */
   readonly sheetName: string;
   /**
@@ -108,7 +108,7 @@ interface SheetContext {
   }) => void): () => void;
 }
 /** createSheetContext 可选配置 */
-interface SheetContextOptions {
+export interface SheetContextOptions {
   /**
    * 当前渲染网格尺寸（与 SheetGrid / resolveRenderSize 一致）。
    * applyStyle / clearStyle 用其判定整行/整列；缺省时不走行列默认样式。
@@ -128,6 +128,5 @@ interface SheetContextOptions {
  *   workbook prop 后导出工具仍导出旧工作簿）
  * @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
  */
-declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook), options?: SheetContextOptions): SheetContext;
-//#endregion
-export { SheetContext, SheetContextOptions, createSheetContext };
+export declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook), options?: SheetContextOptions): SheetContext;
+//#endregion

package/dist/tools/download.js

@@ -1,5 +1,5 @@
 import { saveBlob } from "@cat-kit/fe";
-import { exportSheetCsv, exportWorkbookXlsx } from "@veltra/sheet-core/core/io/export";
+import { exportSheetCsv, exportWorkbookXlsx } from "@veltra/sheet-core/core/io/export.js";
 //#region src/tools/download.ts
 /**
 * 大工作簿的 XLSX 导出（sheet-core 序列化 + ZIP 压缩为秒级同步重活）移入 Web Worker：

package/dist/tools/export.worker.d.ts

@@ -1,16 +1,15 @@
-import { SheetSnapshot } from "@veltra/sheet-core/core/sheet";
+import { SheetSnapshot } from "@veltra/sheet-core/core/sheet.js";
 //#region src/tools/export.worker.d.ts
-interface ExportWorkerPayload {
+export interface ExportWorkerPayload {
   sheets: {
     name: string;
     snapshot: SheetSnapshot;
   }[];
   activeIndex: number;
 }
-interface ExportWorkerResponse {
+export interface ExportWorkerResponse {
   ok: boolean;
   buffer?: Uint8Array;
   error?: string;
 }
-//#endregion
-export { ExportWorkerPayload, ExportWorkerResponse };
+//#endregion

package/dist/tools/export.worker.js

@@ -1,6 +1,6 @@
 //#region src/tools/export.worker.ts
 self.onmessage = (e) => {
-	Promise.all([import("@veltra/sheet-core/core/io/export"), import("@veltra/sheet-core/core/workbook")]).then(([{ exportWorkbookXlsx }, { Workbook }]) => {
+	Promise.all([import("@veltra/sheet-core/core/io/export.js"), import("@veltra/sheet-core/core/workbook.js")]).then(([{ exportWorkbookXlsx }, { Workbook }]) => {
 		const wb = new Workbook();
 		const sheets = e.data.sheets;
 		for (let i = 0; i < sheets.length; i++) {

package/dist/tools/registry.d.ts

@@ -11,9 +11,9 @@ import { SheetContext } from "./context.js";
  *   （与 defaultCommandRegistry 同语义；每个实例的 SheetContext 各自绑定当前 sheet）
  */
 /** 弹层型工具类型：vue 层按类型渲染弹层面板（面板交互走 SheetContext 命令入口） */
-type SheetToolPopupType = 'fill-color' | 'border' | 'font-color' | 'font-size' | 'find' | 'insert-image' | 'export';
+export type SheetToolPopupType = 'fill-color' | 'border' | 'font-color' | 'font-size' | 'find' | 'functions' | 'insert-image' | 'export';
 /** 工具定义 */
-interface SheetTool {
+export interface SheetTool {
   /** 唯一 id；同 id 重复注册视为替换（保留原位置） */
   id: string;
   /** 按钮文本 */
@@ -38,11 +38,11 @@ interface SheetTool {
   onClick(ctx: SheetContext): void;
 }
 /** 分组视图（供工具栏渲染） */
-interface SheetToolGroup {
+export interface SheetToolGroup {
   name: string;
   tools: SheetTool[];
 }
-declare class ToolRegistry {
+export declare class ToolRegistry {
   private entries;
   private seq;
   private emitter;
@@ -62,10 +62,9 @@ declare class ToolRegistry {
  * 全局默认注册表（USheet 默认渲染这里的工具；内置工具也注册于此）。
  * 工具是应用级扩展：注册一次，所有 USheet 实例共享。
  */
-declare const defaultToolRegistry: ToolRegistry;
+export declare const defaultToolRegistry: ToolRegistry;
 /** 注册工具到默认注册表 */
-declare function registerTool(tool: SheetTool): void;
+export declare function registerTool(tool: SheetTool): void;
 /** 从默认注册表注销工具；id 不存在时返回 false */
-declare function unregisterTool(id: string): boolean;
-//#endregion
-export { SheetTool, SheetToolGroup, SheetToolPopupType, ToolRegistry, defaultToolRegistry, registerTool, unregisterTool };
+export declare function unregisterTool(id: string): boolean;
+//#endregion

package/dist/tools/registry.js

@@ -1,4 +1,4 @@
-import { TypedEventEmitter } from "@veltra/sheet-core/core/events";
+import { TypedEventEmitter } from "@veltra/sheet-core/core/events.js";
 //#region src/tools/registry.ts
 /** 缺省分组名 */
 const DEFAULT_TOOL_GROUP = "default";

package/dist/types/sheet.d.ts

@@ -2,11 +2,11 @@ import { SheetContext } from "../tools/context.js";
 import { ComputedRef } from "vue";
 import { DeconstructValue } from "@veltra/utils";
 import { ResolveCellRenderer, ResolveCellStyleHook, ResolveDisplayValue, SheetGrid } from "@veltra/sheet-core/grid";
-import { Workbook } from "@veltra/sheet-core/core/workbook";
-import { Sheet } from "@veltra/sheet-core/core/sheet";
+import { Workbook } from "@veltra/sheet-core/core/workbook.js";
+import { Sheet } from "@veltra/sheet-core/core/sheet.js";
 //#region src/types/sheet.d.ts
 /** 电子表格组件属性 */
-interface SheetProps {
+export interface SheetProps {
   /** 工作簿实例（多 sheet / 跨表公式的载体）；缺省内部自建（单 sheet） */
   workbook?: Workbook;
   /** 渲染行数，默认 100 */
@@ -40,7 +40,7 @@ interface SheetProps {
   /** 只读预览（关闭编辑回写、填充柄等写入口） */
   readonly?: boolean;
 }
-interface SheetEmits {
+export interface SheetEmits {
   /** 激活 sheet 切换（点击 tab 或宿主调用 workbook.activateSheet） */
   (name: 'active-sheet-change', payload: {
     sheet: Sheet;
@@ -48,7 +48,7 @@ interface SheetEmits {
   }): void;
 }
 /** 在组件内部引用 */
-interface _SheetExposed {
+export interface _SheetExposed {
   /** 当前工作簿（props.workbook 缺省时为内部自建实例） */
   workbook: ComputedRef<Workbook>;
   /** 当前活动 sheet */
@@ -59,6 +59,5 @@ interface _SheetExposed {
   getGrid: () => SheetGrid | undefined;
 }
 /** 电子表格组件暴露的属性和方法 */
-type SheetExposed = DeconstructValue<_SheetExposed>;
-//#endregion
-export { SheetEmits, SheetExposed, SheetProps, _SheetExposed };
+export type SheetExposed = DeconstructValue<_SheetExposed>;
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/sheet",
-  "version": "2.5.6",
+  "version": "2.5.8",
   "homepage": "https://github.com/cabinet-fe/ultra-ui#readme",
   "bugs": {
     "url": "https://github.com/cabinet-fe/ultra-ui/issues"
@@ -36,11 +36,11 @@
   "peerDependencies": {
     "@cat-kit/core": ">=1.2.1",
     "@cat-kit/fe": ">=1.2.1",
-    "@veltra/desktop": "^1.7.10",
+    "@veltra/desktop": "^1.7.14",
     "@veltra/icons": "^1.5.0",
-    "@veltra/sheet-core": "^2.5.6",
-    "@veltra/styles": "^1.7.10",
-    "@veltra/utils": "^1.7.10",
+    "@veltra/sheet-core": "^2.5.7",
+    "@veltra/styles": "^1.7.14",
+    "@veltra/utils": "^1.7.14",
     "vue": ">=3.5.42"
   }
 }

package/src/components/sheet/__test__/formula-bar.test.ts

@@ -1,5 +1,6 @@
-import { parseRange } from '@veltra/sheet-core/core/address'
-import { Workbook } from '@veltra/sheet-core/core/workbook'
+import { parseRange } from '@veltra/sheet-core/core/address.js'
+import { Workbook } from '@veltra/sheet-core/core/workbook.js'
+import type { SheetGrid } from '@veltra/sheet-core/grid'
 import { afterEach, describe, expect, it } from 'vitest'
 import { createApp, h, nextTick, type App } from 'vue'
 
@@ -342,6 +343,145 @@ function setFxText(el: HTMLElement, text: string): HTMLTextAreaElement {
   return input
 }
 
+function fxButton(el: HTMLElement): HTMLButtonElement {
+  return el.querySelector<HTMLButtonElement>('button.u-sheet__fx-label')!
+}
+
+/** 函数弹框 Teleport 到 body 级 #pop-container（fx 按钮与工具栏共用同一弹框组件） */
+function functionsPanel(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-panel')
+}
+
+/** 等待弹层渲染：watch flush + Teleport 挂载 */
+async function flushPopup(): Promise<void> {
+  await nextTick()
+  await nextTick()
+}
+
+describe('USheet 公式栏：fx 函数弹框', () => {
+  it('fx 渲染为可点击 button；无活动单元格时禁用且不打开弹框', async () => {
+    const sheet = new Workbook().activeSheet
+    const { el } = mountFormulaBar(sheet)
+    await nextTick()
+
+    // 清空选区（Sheet 构造默认选 A1）：与 fx 输入框同一禁用条件
+    sheet.selection.clear()
+    await nextTick()
+    const button = fxButton(el)
+    expect(button.tagName).toBe('BUTTON')
+    expect(button.disabled).toBe(true)
+    expect(fxInput(el).disabled).toBe(true)
+
+    button.click()
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+
+    // 有活动格 → 可点击
+    sheet.selectCell({ row: 0, col: 0 })
+    await nextTick()
+    expect(button.disabled).toBe(false)
+  })
+
+  it('点击 fx 开弹框；再点 fx / 点击弹框外 / Esc 关闭；开关不改选区、单元格内容与草稿', async () => {
+    const sheet = new Workbook().activeSheet
+    sheet.setCellValue({ row: 0, col: 0 }, 'keep')
+    const { el } = mountFormulaBar(sheet)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    // 挂起草稿编辑（focus + 输入，不提交）
+    const input = setFxText(el, 'draft')
+    const button = fxButton(el)
+    const selectionBefore = sheet.getSelection()
+
+    // 点击 fx → 弹框打开
+    button.click()
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+    // 开弹框不改选区 / 不写单元格 / 草稿保留
+    expect(sheet.getSelection()).toEqual(selectionBefore)
+    expect(sheet.getCellData({ row: 2, col: 0 })).toBeUndefined()
+    expect(input.value).toBe('draft')
+
+    // 再次点击 fx → 关闭
+    button.click()
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+    expect(input.value).toBe('draft')
+
+    // 点击弹框外 → 关闭
+    button.click()
+    await flushPopup()
+    window.dispatchEvent(new MouseEvent('click'))
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+    expect(input.value).toBe('draft')
+
+    // Esc → 关闭；全程单元格未被写入
+    button.click()
+    await flushPopup()
+    functionsPanel()!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+    expect(input.value).toBe('draft')
+    expect(sheet.getCellData({ row: 2, col: 0 })).toBeUndefined()
+    expect(sheet.getCellData({ row: 0, col: 0 })).toMatchObject({ v: 'keep' })
+  })
+
+  it('选中函数：进入编辑态输出 =SUM()，光标在括号内、焦点在 fx 输入框；Enter 提交到活动格', async () => {
+    const sheet = new Workbook().activeSheet
+    const { el } = mountFormulaBar(sheet)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    fxButton(el).click()
+    await flushPopup()
+    // 默认「常用」首项 SUM
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+    expect(input.selectionStart).toBe('=SUM()'.length - 1)
+    expect(input.selectionEnd).toBe('=SUM()'.length - 1)
+    expect(document.activeElement).toBe(input)
+    expect(el.querySelector('.u-sheet__fx-suggest')).toBeNull()
+
+    // 提交 → 写入进入编辑时的目标格（当前活动格 A3）
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: 'SUM()' })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+  })
+
+  it('工具栏「函数」按钮打开同一弹框，选中行为与 fx 按钮一致', async () => {
+    const workbook = new Workbook()
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }))
+    await nextTick()
+
+    const toolbarButton = el.querySelector<HTMLButtonElement>('[data-tool-id="functions"]')!
+    toolbarButton.click()
+    await nextTick()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+    // 公式栏进入编辑态（默认选区 A1）
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+    expect(input.selectionStart).toBe('=SUM()'.length - 1)
+    expect(document.activeElement).toBe(input)
+    // 弹框随选中关闭
+    expect(functionsPanel()).toBeNull()
+  })
+})
+
 function suggestList(el: HTMLElement): HTMLElement | null {
   return el.querySelector('.u-sheet__fx-suggest')
 }
@@ -501,3 +641,175 @@ describe('USheet 公式栏：函数补全与引用选择', () => {
     expect(input.style.height).toBe('')
   })
 })
+
+// ─── 目标格选区高亮保持（弹框打开与参数点选期间）──────────────
+
+/** VTable 事件名（ListTable.EVENT_TYPE 常量值；@veltra/sheet 不直接依赖 @visactor/vtable，不做运行时引入） */
+const EVT_SELECTED_CELL = 'selected_cell'
+const EVT_DRAG_SELECT_END = 'drag_select_end'
+
+type GridTable = ReturnType<SheetGrid['getTable']>
+
+/** 模拟画布点选格（VTable 时序：selectCells → SELECTED_CELL） */
+function canvasClickCell(table: GridTable, col: number, row: number): void {
+  table.selectCells([{ start: { col, row }, end: { col, row } }])
+  table.fireListeners(EVT_SELECTED_CELL, { col, row })
+}
+
+/** 画布当前选区末尾项（表格坐标；VTable 范围对象含额外内部字段，按坐标匹配） */
+function lastCanvasRange(table: GridTable) {
+  return table.getSelectedCellRanges().at(-1)
+}
+
+describe('USheet 公式栏：目标格选区高亮保持', () => {
+  it('fx 弹框打开期间点选画布：目标格高亮与名称框保持、模型选区不变，不插入引用文本', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    fxButton(el).click()
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+
+    // 弹框打开期间点选画布 B2（表格坐标 (2,2)）
+    const table = exposed.value!.getGrid()!.getTable()
+    canvasClickCell(table, 2, 2)
+
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(sheet.getSelection().ranges[0]).toEqual({
+      start: { row: 2, col: 0 },
+      end: { row: 2, col: 0 }
+    })
+    // 画布选区回推为目标格 A3（表格坐标 (1,3)），名称框仍显示 A3
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+    expect(nameBox(el).value).toBe('A3')
+    // 未处于引用选择上下文：不插入引用文本
+    expect(fxInput(el).value).toBe('')
+  })
+
+  it('选中函数后点选画布参数格：只插入引用文本、目标格选区不变；提交后选区与名称框仍指向目标格', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    sheet.setCellValue({ row: 0, col: 0 }, 1)
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    // fx 弹框选中 SUM → 编辑态 =SUM()（目标 = 活动格 A3）
+    fxButton(el).click()
+    await flushPopup()
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+
+    // 点选参数格 A1（表格坐标 (1,1)）→ 只插入引用文本（括号随 =SUM() 模板闭合），目标格选区不变
+    const table = exposed.value!.getGrid()!.getTable()
+    canvasClickCell(table, 1, 1)
+    await nextTick()
+    expect(input.value).toBe('=SUM(A1)')
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+    expect(nameBox(el).value).toBe('A3')
+
+    // 提交 → 写入目标格 A3，选区与名称框仍指向 A3
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: 'SUM(A1)', v: 1 })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+  })
+
+  it('工具栏「函数」入口与 fx 一致：弹框期间点选画布保持目标格；拖选参数后提交仍指向目标格', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    sheet.setCellValue({ row: 0, col: 0 }, 1)
+    sheet.setCellValue({ row: 1, col: 0 }, 2)
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    el.querySelector<HTMLButtonElement>('[data-tool-id="functions"]')!.click()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+
+    // 弹框打开期间点选画布 B2：目标格 A3 高亮保持、模型选区不变、不插入文本
+    const table = exposed.value!.getGrid()!.getTable()
+    canvasClickCell(table, 2, 2)
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+    expect(fxInput(el).value).toBe('')
+
+    // 选中 SUM → 拖选参数区域 A1:A2（SELECTED_CELL → DRAG_SELECT_END 完整时序）
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+    table.selectCells([{ start: { col: 1, row: 1 }, end: { col: 1, row: 2 } }])
+    table.fireListeners(EVT_SELECTED_CELL, { col: 1, row: 2 })
+    table.fireListeners(EVT_DRAG_SELECT_END, {})
+    await nextTick()
+    expect(input.value).toBe('=SUM(A1:A2)')
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+
+    // 提交 → 选区与名称框仍指向目标格 A3
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: 'SUM(A1:A2)', v: 3 })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+  })
+
+  it('公式提交后选区与名称框仍指向目标格（编辑期间名称框跳转离开时回推）', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    // 编辑目标 A3；期间经名称框跳转到 B5（模型选区离开目标格）
+    const input = setFxText(el, '=1+1')
+    typeName(el, 'B5')
+    await nextTick()
+    expect(sheet.getSelection().activeCell).toEqual({ row: 4, col: 1 })
+    expect(nameBox(el).value).toBe('B5')
+
+    // 提交 → 写入 A3，模型选区 / 名称框 / 画布高亮回推目标格
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: '1+1', v: 2 })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+    expect(lastCanvasRange(exposed.value!.getGrid()!.getTable())).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+  })
+})