@veltra/sheet 3.0.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/dist/components/sheet/float-image-menu.js +59 -0
  2. package/dist/components/sheet/import-file.js +3 -1
  3. package/dist/components/sheet/popup-helpers.js +18 -2
  4. package/dist/components/sheet/popups/hyperlink-popup.js +127 -0
  5. package/dist/components/sheet/popups/import.worker.d.ts +4 -0
  6. package/dist/components/sheet/popups/import.worker.js +3 -1
  7. package/dist/components/sheet/sheet-context-menu.js +81 -7
  8. package/dist/components/sheet/sheet.js +112 -17
  9. package/dist/components/sheet/style2.css +62 -0
  10. package/dist/components/sheet/use-cell-link-tooltip.js +33 -0
  11. package/dist/components/sheet/use-sheet-grid.js +82 -2
  12. package/dist/components/sheet/use-sheet-state.js +1 -0
  13. package/dist/tools/context.d.ts +20 -2
  14. package/dist/tools/context.js +9 -1
  15. package/dist/types/index.d.ts +2 -2
  16. package/dist/types/sheet.d.ts +54 -7
  17. package/package.json +2 -2
  18. package/src/components/sheet/__test__/float-image-menu.test.ts +130 -0
  19. package/src/components/sheet/__test__/grid-test-utils.ts +2 -3
  20. package/src/components/sheet/__test__/hyperlink-popup.test.ts +176 -0
  21. package/src/components/sheet/__test__/import-file.test.ts +33 -2
  22. package/src/components/sheet/__test__/sheet-component.test.ts +476 -18
  23. package/src/components/sheet/__test__/sheet-context-menu.test.ts +255 -2
  24. package/src/components/sheet/__test__/sheet-scrollbar.test.ts +23 -73
  25. package/src/components/sheet/__test__/sheet-theme.test.ts +212 -0
  26. package/src/components/sheet/float-image-menu.ts +78 -0
  27. package/src/components/sheet/import-file.ts +19 -2
  28. package/src/components/sheet/popup-helpers.ts +68 -2
  29. package/src/components/sheet/popups/hyperlink-popup.vue +112 -0
  30. package/src/components/sheet/popups/import.worker.ts +18 -4
  31. package/src/components/sheet/sheet-context-menu.ts +100 -7
  32. package/src/components/sheet/sheet.vue +120 -7
  33. package/src/components/sheet/style.scss +66 -0
  34. package/src/components/sheet/use-cell-link-tooltip.ts +42 -0
  35. package/src/components/sheet/use-sheet-grid.ts +111 -4
  36. package/src/components/sheet/use-sheet-state.ts +8 -2
  37. package/src/tools/__test__/context.test.ts +89 -0
  38. package/src/tools/context.ts +33 -2
  39. package/src/types/sheet.ts +59 -7
@@ -66,6 +66,16 @@
66
66
  <div :class="cls.e('loading-spinner')"></div>
67
67
  <div :class="cls.e('loading-text')">{{ parseText }}</div>
68
68
  </div>
69
+
70
+ <!-- 悬停链接格 tooltip:引擎 cell link hover/leave 事件驱动挂载/卸载,
71
+ 层坐标 + 偏移后绝对定位于 grid 区(不遮指针;pointer-events: none) -->
72
+ <div
73
+ v-if="cellLinkTooltip"
74
+ :class="cls.e('link-tooltip')"
75
+ :style="{ left: `${cellLinkTooltip.left}px`, top: `${cellLinkTooltip.top}px` }"
76
+ >
77
+ {{ cellLinkTooltip.url }}
78
+ </div>
69
79
  </div>
70
80
 
71
81
  <u-sheet-tabs
@@ -74,18 +84,42 @@
74
84
  :sheet-list="sheetList"
75
85
  :active-index="activeIndex"
76
86
  />
87
+
88
+ <!-- 单元格/图片超链接配置弹窗(右键菜单拉起;confirm 按模式路由写入) -->
89
+ <u-sheet-hyperlink-popup
90
+ v-if="hyperlinkPopup"
91
+ :mode="hyperlinkPopup.mode"
92
+ :initial="hyperlinkPopup.initial"
93
+ @confirm="handleHyperlinkConfirm"
94
+ @close="hyperlinkPopup = null"
95
+ />
96
+
97
+ <!-- 图片 lightbox 预览(浮动图/嵌入图右键「预览」拉起;关闭卸载 → objectURL 由组件回收) -->
98
+ <u-image-previewer
99
+ v-if="imagePreview"
100
+ :src="imagePreview.src ?? imagePreview.data"
101
+ :mime="imagePreview.mime"
102
+ @close="imagePreview = null"
103
+ />
77
104
  </div>
78
105
  </template>
79
106
 
80
107
  <script lang="ts" setup>
81
- import { UDropdown } from '@veltra/desktop'
108
+ import { UDropdown, UImagePreviewer } from '@veltra/desktop'
82
109
  import { bem } from '@veltra/utils'
83
- import { computed, ref, useTemplateRef, watch } from 'vue'
110
+ import type { CellAddress, CellLinkPayload } from 'infinitable/sheet'
111
+ import { computed, ref, shallowRef, useTemplateRef, watch } from 'vue'
84
112
 
85
113
  import type { SheetTool } from '../../tools/registry'
86
114
  import type { SheetEmits, SheetProps, _SheetExposed } from '../../types'
87
115
  import UFormulaBar from './formula-bar.vue'
88
116
  import { pickAndImportFile } from './import-file'
117
+ import type {
118
+ HyperlinkConfirmPayload,
119
+ HyperlinkImageTarget,
120
+ HyperlinkPopupMode,
121
+ ImagePreviewSource
122
+ } from './popup-helpers'
89
123
  import USheetBorderPopup from './popups/border-popup.vue'
90
124
  import USheetExportPopup from './popups/export-popup.vue'
91
125
  import USheetFillColorPopup from './popups/fill-color-popup.vue'
@@ -93,9 +127,11 @@ import USheetFindPopup from './popups/find-popup.vue'
93
127
  import USheetFontColorPopup from './popups/font-color-popup.vue'
94
128
  import USheetFontSizePopup from './popups/font-size-popup.vue'
95
129
  import USheetFunctionsPopup from './popups/functions-popup.vue'
130
+ import USheetHyperlinkPopup from './popups/hyperlink-popup.vue'
96
131
  import USheetInsertImagePopup from './popups/insert-image-popup.vue'
97
132
  import USheetTabs from './sheet-tabs.vue'
98
133
  import USheetToolbar from './sheet-toolbar.vue'
134
+ import { useCellLinkTooltip } from './use-cell-link-tooltip'
99
135
  import { useSheetGrid } from './use-sheet-grid'
100
136
  import { useSheetState } from './use-sheet-state'
101
137
  import { useToolGroups } from './use-tool-groups'
@@ -113,10 +149,9 @@ const props = withDefaults(defineProps<SheetProps>(), {
113
149
  showColHeader: true,
114
150
  readonly: false,
115
151
  colResize: false,
116
- // 缺省原生档:引擎在 grid 容器内装配真实 DOM 滚动容器(原生滚动条独立
117
- // gutter,不遮挡单元格),画布悬浮滚动条不再绘制。对象缺省被所有实例共享,
118
- // 只读透传不改动
119
- scrollbar: { mode: 'native' },
152
+ // 缺省画布常驻档:true 经引擎归一化为 canvas always + reserve——滚动条常驻
153
+ // 画在画布内,reserve 只在画布内预留轨道(不占页面布局、不遮挡单元格)
154
+ scrollbar: true,
120
155
  // 显式对齐引擎当前缺省(true 近边增长):boolean prop 不写 default 会被
121
156
  // Vue 铸成 false,把引擎缺省翻成固定尺寸网格
122
157
  growOnScroll: true
@@ -214,6 +249,68 @@ function handlePopupVisible(visible: boolean): void {
214
249
 
215
250
  const toolGroups = useToolGroups(context, stateTick)
216
251
 
252
+ // ─── 单元格超链接 / 图片 UI(右键菜单 → 配置弹窗 → 写入;悬停 tooltip;lightbox)──
253
+
254
+ /** 超链接配置弹层状态(右键菜单拉起):mode + 编辑回填 + 写入目标(cell 格 / image 浮动图或嵌入图) */
255
+ const hyperlinkPopup = shallowRef<{
256
+ mode: HyperlinkPopupMode
257
+ initial?: CellLinkPayload
258
+ addr?: CellAddress
259
+ imageTarget?: HyperlinkImageTarget
260
+ } | null>(null)
261
+
262
+ /** 悬停 tooltip 状态机(引擎 cell link hover/leave 事件驱动,层坐标换算见 use-cell-link-tooltip) */
263
+ const {
264
+ tooltip: cellLinkTooltip,
265
+ onCellLinkHover: showCellLinkTooltip,
266
+ onCellLinkLeave: hideCellLinkTooltip
267
+ } = useCellLinkTooltip()
268
+
269
+ /** 右键菜单超链接项句柄:记录写入目标并拉起弹窗(编辑回填原 url/text) */
270
+ function openHyperlinkPopup(
271
+ mode: HyperlinkPopupMode,
272
+ initial?: CellLinkPayload,
273
+ imageTarget?: HyperlinkImageTarget
274
+ ): void {
275
+ hyperlinkPopup.value = {
276
+ mode,
277
+ initial,
278
+ addr: mode === 'cell' ? (context.getSelection().activeCell ?? undefined) : undefined,
279
+ imageTarget: mode === 'image' ? imageTarget : undefined
280
+ }
281
+ }
282
+
283
+ /**
284
+ * 弹窗确认:关弹层并写目标链接,一次写入 = 一个 undo 单元。
285
+ * cell:setCellLink(显示文本留空不写入 text → 单元格沿用自身内容显示);
286
+ * 浮动图:updateImage(link 字段);嵌入图:insertCellImage 覆盖写(其余载荷保留)。
287
+ */
288
+ function handleHyperlinkConfirm(payload: HyperlinkConfirmPayload): void {
289
+ const current = hyperlinkPopup.value
290
+ hyperlinkPopup.value = null
291
+ if (current?.mode === 'cell') {
292
+ if (current.addr) context.setCellLink(current.addr, payload)
293
+ return
294
+ }
295
+ const target = current?.imageTarget
296
+ if (target?.kind === 'float') {
297
+ context.updateImage(target.id, { link: payload.url })
298
+ return
299
+ }
300
+ if (target?.kind === 'cell') {
301
+ const existing = context.getCellImage(target.addr)
302
+ if (existing) context.insertCellImage(target.addr, { ...existing, link: payload.url })
303
+ }
304
+ }
305
+
306
+ /** lightbox 预览状态(右键「预览」拉起):URL 或字节 + MIME;关闭置 null 卸载(objectURL 由 UImagePreviewer 回收) */
307
+ const imagePreview = shallowRef<ImagePreviewSource | null>(null)
308
+
309
+ /** 右键「预览」句柄:浮动图 / 嵌入图菜单共用 */
310
+ function openImagePreview(source: ImagePreviewSource): void {
311
+ imagePreview.value = source
312
+ }
313
+
217
314
  // ─── grid 生命周期(重建 / 右键菜单 / 公式栏编辑镜像)────────────────
218
315
 
219
316
  const gridRef = useTemplateRef<HTMLElement>('gridRef')
@@ -227,7 +324,23 @@ const { rebuildGrid, activateGrid, pruneCache, getGrid, setSelectionAnchor } = u
227
324
  formulaBarRef,
228
325
  // 工具栏「函数」弹框打开期间与 fx 入口一致:画布点击不清除目标格高亮
229
326
  isFunctionPopupOpen: () => popupTool.value?.popup === 'functions',
230
- onColResizeEnd: (event) => emit('col-resize-end', event)
327
+ onColResizeEnd: (event) => emit('col-resize-end', event),
328
+ // 引擎链接 / 浮动图事件透传(打开行为仍归引擎 openCellLinkOnClick 默认);
329
+ // hover/leave 同时喂给 tooltip 状态机(与组件 emit 同源)
330
+ onCellLinkHover: (event) => {
331
+ emit('cell-link-hover', event)
332
+ showCellLinkTooltip(event)
333
+ },
334
+ onCellLinkLeave: (event) => {
335
+ emit('cell-link-leave', event)
336
+ hideCellLinkTooltip(event)
337
+ },
338
+ onCellLinkClick: (event) => emit('cell-link-click', event),
339
+ onImageLinkClick: (event) => emit('image-link-click', event),
340
+ onFloatContextMenu: (event) => emit('float-context-menu', event),
341
+ // body 菜单超链接项 → 拉起配置弹窗;右键「预览」→ 打开 lightbox
342
+ openHyperlinkPopup,
343
+ openImagePreview
231
344
  })
232
345
 
233
346
  const exposed: _SheetExposed = {
@@ -724,6 +724,72 @@
724
724
  visibility: hidden;
725
725
  }
726
726
 
727
+ /* 悬停链接格 tooltip:引擎 cell link hover/leave 事件驱动挂载/卸载,
728
+ 层坐标 + 偏移后绝对定位于 grid 区;pointer-events: none 避免浮层
729
+ 自身命中指针触发 leave 抖动(DOM 顺序在画布之后,天然盖在画布上) */
730
+ @include m.e(link-tooltip) {
731
+ position: absolute;
732
+ z-index: 10;
733
+ max-width: 320px;
734
+ padding: 2px 8px;
735
+ border: fn.use-var(border);
736
+ border-radius: fn.use-var(radius, small);
737
+ background-color: fn.use-var(bg-color, top);
738
+ box-shadow: fn.use-var(shadow, sm);
739
+ color: fn.use-var(text-color, main);
740
+ font-size: fn.use-var(font-size-main, small);
741
+ white-space: nowrap;
742
+ overflow: hidden;
743
+ text-overflow: ellipsis;
744
+ pointer-events: none;
745
+ }
746
+
747
+ /* ── 超链接配置弹窗(右键菜单拉起,无工具栏锚点:自绘遮罩 + 居中面板,
748
+ 对齐 loading-mask 自绘先例;遮罩半透明黑与 desktop dialog overlay 同口径) ── */
749
+
750
+ @include m.e(link-dialog-mask) {
751
+ position: fixed;
752
+ inset: 0;
753
+ display: flex;
754
+ align-items: center;
755
+ justify-content: center;
756
+ background-color: rgba($color: #000000, $alpha: 0.32);
757
+ }
758
+
759
+ @include m.e(link-dialog) {
760
+ display: flex;
761
+ flex-direction: column;
762
+ gap: fn.use-var(gap, small);
763
+ width: min(380px, 90vw);
764
+ padding: fn.use-var(gap, default);
765
+ border-radius: fn.use-var(radius, large);
766
+ background-color: fn.use-var(bg-color, top);
767
+ box-shadow: fn.use-var(shadow, lg);
768
+ }
769
+
770
+ @include m.e(link-dialog-title) {
771
+ color: fn.use-var(text-color, main);
772
+ font-size: fn.use-var(font-size-title, default);
773
+ font-weight: 600;
774
+ }
775
+
776
+ @include m.e(link-dialog-body) {
777
+ display: flex;
778
+ flex-direction: column;
779
+ gap: fn.use-var(gap, small);
780
+ }
781
+
782
+ @include m.e(link-dialog-input) {
783
+ flex: 1;
784
+ min-width: 0;
785
+ }
786
+
787
+ @include m.e(link-dialog-footer) {
788
+ display: flex;
789
+ justify-content: flex-end;
790
+ gap: fn.use-var(gap, small);
791
+ }
792
+
727
793
  @include m.e(tabs) {
728
794
  display: flex;
729
795
  align-items: center;
@@ -0,0 +1,42 @@
1
+ import type { CellLinkHoverEvent } from 'infinitable'
2
+ import { shallowRef } from 'vue'
3
+
4
+ /**
5
+ * tooltip 相对悬停落点的偏移:右下错开,浮层不遮指针与命中的链接文本。
6
+ */
7
+ const TOOLTIP_OFFSET_X = 8
8
+ const TOOLTIP_OFFSET_Y = 20
9
+
10
+ /** 悬停链接格 tooltip 的视图状态(url + 相对 grid 区的绝对定位坐标) */
11
+ export interface CellLinkTooltipState {
12
+ /** 展示的链接 URL */
13
+ url: string
14
+ /** 浮层左边(层坐标 + 偏移,单位 px;grid 区内绝对定位) */
15
+ left: number
16
+ /** 浮层顶边(层坐标 + 偏移,单位 px) */
17
+ top: number
18
+ }
19
+
20
+ /**
21
+ * 单元格超链接悬停 tooltip(引擎 hover/leave 事件驱动):
22
+ * hover 时记录命中的层坐标 + URL(层坐标相对 grid 实例容器 = grid 区原点,
23
+ * 渲染层直接在 grid 区内绝对定位挂载浮层);leave 时卸载(置 null)。
24
+ * 事件源接线在 use-sheet-grid(与 cell-link-hover/leave 组件 emit 同源)。
25
+ */
26
+ export function useCellLinkTooltip() {
27
+ const tooltip = shallowRef<CellLinkTooltipState | null>(null)
28
+
29
+ function onCellLinkHover(event: CellLinkHoverEvent): void {
30
+ tooltip.value = {
31
+ url: event.url,
32
+ left: event.x + TOOLTIP_OFFSET_X,
33
+ top: event.y + TOOLTIP_OFFSET_Y
34
+ }
35
+ }
36
+
37
+ function onCellLinkLeave(): void {
38
+ tooltip.value = null
39
+ }
40
+
41
+ return { tooltip, onCellLinkHover, onCellLinkLeave }
42
+ }
@@ -1,11 +1,21 @@
1
1
  import { contextmenu } from '@veltra/desktop'
2
+ import { currentTheme } from '@veltra/styles/theme'
3
+ import type {
4
+ CellLinkClickEvent,
5
+ CellLinkHoverEvent,
6
+ CellLinkLeaveEvent,
7
+ ImageLinkClickEvent,
8
+ ThemeOverride
9
+ } from 'infinitable'
2
10
  import type { CellAddress, CellRange } from 'infinitable/sheet'
3
11
  import type { Sheet } from 'infinitable/sheet'
4
12
  import { SheetGrid, type SheetGridContextMenuInfo } from 'infinitable/sheet'
5
13
  import { onBeforeUnmount, onMounted, watch } from 'vue'
6
14
 
7
15
  import type { SheetContext } from '../../tools/context'
8
- import type { SheetProps } from '../../types'
16
+ import type { FloatContextMenuPayload, SheetProps } from '../../types'
17
+ import { popFloatImageMenu } from './float-image-menu'
18
+ import type { ImagePreviewSource, OpenHyperlinkPopup } from './popup-helpers'
9
19
  import {
10
20
  buildBodyMenus,
11
21
  buildColHeaderMenus,
@@ -41,6 +51,20 @@ interface UseSheetGridOptions {
41
51
  isFunctionPopupOpen?: () => boolean
42
52
  /** 列宽拖拽落定(SheetGrid 透传 → 宿主 emit col-resize-end) */
43
53
  onColResizeEnd?: (event: { col: number; width: number }) => void
54
+ /** 单元格超链接悬停(引擎透传 → 宿主 emit cell-link-hover) */
55
+ onCellLinkHover?: (event: CellLinkHoverEvent) => void
56
+ /** 单元格超链接离开(引擎透传 → 宿主 emit cell-link-leave) */
57
+ onCellLinkLeave?: (event: CellLinkLeaveEvent) => void
58
+ /** 单元格超链接单击(引擎透传 → 宿主 emit cell-link-click;打开行为仍归引擎默认) */
59
+ onCellLinkClick?: (event: CellLinkClickEvent) => void
60
+ /** 图片链接单击(引擎透传 → 宿主 emit image-link-click;kind 区分嵌入/浮动) */
61
+ onImageLinkClick?: (event: ImageLinkClickEvent) => void
62
+ /** 浮动图右键(引擎透传 → 宿主 emit float-context-menu;右键不穿透到 body 菜单) */
63
+ onFloatContextMenu?: (event: FloatContextMenuPayload) => void
64
+ /** body 菜单超链接项拉起配置弹窗的句柄(sheet.vue 挂载的弹层状态) */
65
+ openHyperlinkPopup?: OpenHyperlinkPopup
66
+ /** 右键「预览」打开 lightbox 的句柄(sheet.vue 挂载的 UImagePreviewer 状态) */
67
+ openImagePreview?: (source: ImagePreviewSource) => void
44
68
  }
45
69
 
46
70
  /** 缓存实例(LRU 淘汰):每个 sheet 一个独立容器 div,非激活容器 visibility:hidden 堆叠 */
@@ -63,6 +87,34 @@ interface CachedGrid {
63
87
  */
64
88
  const GRID_CACHE_CAPACITY = 3
65
89
 
90
+ /**
91
+ * 画布主题映射:读 grid 宿主元素上生效的 `--u-*` CSS 变量(loadTheme 注入 html、
92
+ * 继承到宿主),换算为引擎 `ThemeOverride`——画布底色 / 表头 / 文字 / 网格线 /
93
+ * 冻结分隔线跟随 UI 主题。rowHeader / corner 由引擎随生效 header 派生,无需单写。
94
+ *
95
+ * 任一变量为空(未 loadTheme)返回 `undefined`:SheetGrid 不传 theme、保持引擎
96
+ * 缺省白底,不破坏无主题环境。
97
+ */
98
+ export function resolveCanvasThemeOverride(el: HTMLElement): ThemeOverride | undefined {
99
+ const style = getComputedStyle(el)
100
+ const bgColorTop = style.getPropertyValue('--u-bg-color-top').trim()
101
+ const bgColorBottom = style.getPropertyValue('--u-bg-color-bottom').trim()
102
+ const textColorMain = style.getPropertyValue('--u-text-color-main').trim()
103
+ const borderColor = style.getPropertyValue('--u-border-color').trim()
104
+ const borderMutedColor = style.getPropertyValue('--u-border-muted-color').trim()
105
+ if (!bgColorTop || !bgColorBottom || !textColorMain || !borderColor || !borderMutedColor) {
106
+ return undefined
107
+ }
108
+ return {
109
+ // 底色与 .u-sheet 外层同底;underlay 是数据区外空白处直接可见的底
110
+ body: { background: bgColorTop, color: textColorMain, borderColor },
111
+ header: { background: bgColorBottom, color: textColorMain, borderColor },
112
+ underlayBackgroundColor: bgColorTop,
113
+ interaction: { freezeDividerColor: borderMutedColor },
114
+ frameStyle: { color: borderColor }
115
+ }
116
+ }
117
+
66
118
  /**
67
119
  * SheetGrid 生命周期与网格右键菜单(LRU 实例缓存):
68
120
  * - activateGrid:tab 切换入口——命中缓存 → 显示 + 模型同步(零重建);
@@ -86,10 +138,14 @@ export function useSheetGrid(options: UseSheetGridOptions) {
86
138
 
87
139
  const menus =
88
140
  info.kind === 'row-header'
89
- ? buildRowHeaderMenus(context, { readonly: props.readonly })
141
+ ? buildRowHeaderMenus(context, { readonly: props.readonly, row: info.row })
90
142
  : info.kind === 'col-header'
91
- ? buildColHeaderMenus(context, { readonly: props.readonly })
92
- : buildBodyMenus(context)
143
+ ? buildColHeaderMenus(context, { readonly: props.readonly, col: info.col })
144
+ : buildBodyMenus(context, {
145
+ readonly: props.readonly,
146
+ openHyperlinkPopup: options.openHyperlinkPopup,
147
+ openImagePreview: options.openImagePreview
148
+ })
93
149
 
94
150
  // 最小宽度兜底;实际宽度由最长菜单项撑开(勿固定 240 导致空白过大)
95
151
  contextmenu.pop({ mousePosition: { x: info.x, y: info.y }, width: 'max-content', menus })
@@ -133,6 +189,9 @@ export function useSheetGrid(options: UseSheetGridOptions) {
133
189
  colResize: props.colResize,
134
190
  scrollbar: props.scrollbar,
135
191
  growOnScroll: props.growOnScroll,
192
+ // 画布跟随 UI 主题:loadTheme 注入的 CSS 变量换算为引擎 override
193
+ //(未 loadTheme 时为 undefined,引擎保持缺省白底)
194
+ theme: resolveCanvasThemeOverride(host),
136
195
  onContextMenu: handleContextMenu,
137
196
  onEditStart: (addr) => formulaBarRef.value?.mirrorGridEdit(addr),
138
197
  onEditEnd: (addr) => formulaBarRef.value?.exitMirror(addr),
@@ -150,8 +209,39 @@ export function useSheetGrid(options: UseSheetGridOptions) {
150
209
  const offStructureChange = sheet.on('structure-change', () => {
151
210
  dirty = true
152
211
  })
212
+ // 引擎链接 / 浮动图事件透传:与 structure-change 订阅同生命周期,release 时解绑
213
+ //(LRU 多实例各持各的订阅,淘汰 / 重建不残留)
214
+ const table = grid.getTable()
215
+ const offEngineEvents = [
216
+ table.onCellLinkHover((event) => options.onCellLinkHover?.(event)),
217
+ table.onCellLinkLeave((event) => options.onCellLinkLeave?.(event)),
218
+ table.onCellLinkClick((event) => options.onCellLinkClick?.(event)),
219
+ table.onImageLinkClick((event) => options.onImageLinkClick?.(event)),
220
+ table.floatObjects.onContextMenu((event) => {
221
+ // 层坐标 → 页面视口坐标(层坐标 + grid 容器偏移,与 body 右键菜单同口径)
222
+ const rect = el.getBoundingClientRect()
223
+ const payload: FloatContextMenuPayload = {
224
+ ...event,
225
+ clientX: rect.left + event.x,
226
+ clientY: rect.top + event.y
227
+ }
228
+ options.onFloatContextMenu?.(payload)
229
+ // 产品侧浮动图独立菜单(预览 / 超链接 / 删除);与宿主 emit 并存,
230
+ // 不穿透到格菜单由引擎保证(floatObjects 命中即不派发单元格右键)
231
+ popFloatImageMenu({
232
+ ctx: context,
233
+ event: payload,
234
+ handles: {
235
+ openImagePreview: options.openImagePreview,
236
+ openHyperlinkPopup: options.openHyperlinkPopup
237
+ },
238
+ readonly: props.readonly
239
+ })
240
+ })
241
+ ]
153
242
  const release = (): void => {
154
243
  offStructureChange()
244
+ for (const off of offEngineEvents) off()
155
245
  grid.release()
156
246
  el.remove()
157
247
  }
@@ -291,6 +381,23 @@ export function useSheetGrid(options: UseSheetGridOptions) {
291
381
  invalidateAll()
292
382
  })
293
383
 
384
+ // 主题切换换肤:loadTheme 换实例(ref 替换)或主题 token 原地改(deep)后,
385
+ // 等 UITheme 把 CSS 变量渲染进 html(flush: 'post' 晚于其渲染)再重读映射,
386
+ // 对缓存中所有实例原地 updateTheme——零重建,滚动 / 选区 / 冻结等运行时状态
387
+ // 不受影响;未 loadTheme(解析为 undefined)时不动,保持引擎缺省白底
388
+ watch(
389
+ [() => currentTheme.value?.theme, currentTheme],
390
+ () => {
391
+ const host = gridRef.value
392
+ const override = host ? resolveCanvasThemeOverride(host) : undefined
393
+ if (!override) return
394
+ for (const item of cache.values()) {
395
+ item.grid.updateTheme(override)
396
+ }
397
+ },
398
+ { deep: true, flush: 'post' }
399
+ )
400
+
294
401
  /** fx 引用拾取会话置/清选区锚点(公式栏 → 活动实例透传;无活动实例时静默) */
295
402
  function setSelectionAnchor(addr: CellAddress | null): void {
296
403
  active?.grid.setSelectionAnchor(addr)
@@ -1,4 +1,4 @@
1
- import type { Sheet } from 'infinitable/sheet'
1
+ import type { CellAddress, Sheet } from 'infinitable/sheet'
2
2
  import { Workbook } from 'infinitable/sheet'
3
3
  import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from 'vue'
4
4
 
@@ -25,7 +25,10 @@ export interface SheetStateHooks {
25
25
  syncAxisSizes: (axis: 'row' | 'col', indexes: number[]) => void
26
26
  }
27
27
 
28
- type Emit = (event: 'active-sheet-change', payload: { sheet: Sheet; index: number }) => void
28
+ type Emit = {
29
+ (event: 'active-sheet-change', payload: { sheet: Sheet; index: number }): void
30
+ (event: 'cell-image-change', payload: { addr?: CellAddress }): void
31
+ }
29
32
 
30
33
  /**
31
34
  * USheet 的状态源(单一数据源,其余状态由此推导):
@@ -86,6 +89,9 @@ export function useSheetState(props: SheetProps, emit: Emit, hooks: SheetStateHo
86
89
  sheet.on('cell-change', bump),
87
90
  sheet.on('merge-change', bump),
88
91
  sheet.on('frozen-change', bump),
92
+ // 按格嵌入图变化 → 宿主 emit cell-image-change(随活动 sheet 重绑,
93
+ // 非活动 sheet 的嵌入图变更不透传)
94
+ sheet.on('cell-image-change', (payload) => emit('cell-image-change', payload)),
89
95
  // 整表内容替换(导入 / undo/redo 回放):restore 静默不发 cell-change,
90
96
  // 状态源需 bump(grid 层自行订阅 content-reset 全量刷新,此处不重建)
91
97
  sheet.on('content-reset', scheduleBump),
@@ -278,4 +278,93 @@ describe('SheetContext', () => {
278
278
  expect(ctx.getImages()).toHaveLength(0)
279
279
  expect(onImage).not.toHaveBeenCalled()
280
280
  })
281
+
282
+ it('updateImage 写/清 SheetImage.link(null 清除),经命令可 undo', () => {
283
+ const sheet = new Sheet()
284
+ const ctx = createSheetContext(sheet)
285
+ const id = ctx.insertImage({
286
+ data: new Uint8Array([1]),
287
+ type: 'png',
288
+ anchor: { from: { row: 0, col: 0 } }
289
+ })
290
+
291
+ ctx.updateImage(id, { link: 'https://example.com' })
292
+ expect(ctx.getImages()[0]?.link).toBe('https://example.com')
293
+
294
+ ctx.updateImage(id, { link: null })
295
+ expect(ctx.getImages()[0]?.link).toBeUndefined()
296
+
297
+ // undo 一次还原清除前的链接
298
+ expect(ctx.undo()).toBe(true)
299
+ expect(ctx.getImages()[0]?.link).toBe('https://example.com')
300
+ })
301
+
302
+ it('cell link 门面:写入 → 读取 → 清除 → undo 还原,均经命令可 undo', () => {
303
+ const sheet = new Sheet()
304
+ const ctx = createSheetContext(sheet)
305
+ const addr = { row: 0, col: 0 }
306
+ const link = { url: 'https://example.com', text: '示例' }
307
+
308
+ ctx.setCellLink(addr, link)
309
+ expect(ctx.getCellLink(addr)).toEqual(link)
310
+ expect(ctx.canUndo).toBe(true)
311
+
312
+ // null 即清除
313
+ ctx.setCellLink(addr, null)
314
+ expect(ctx.getCellLink(addr)).toBeUndefined()
315
+
316
+ // undo 还原写入的链接
317
+ expect(ctx.undo()).toBe(true)
318
+ expect(ctx.getCellLink(addr)).toEqual(link)
319
+
320
+ ctx.clearCellLink(addr)
321
+ expect(ctx.getCellLink(addr)).toBeUndefined()
322
+
323
+ // undo 还原 clear
324
+ expect(ctx.undo()).toBe(true)
325
+ expect(ctx.getCellLink(addr)).toEqual(link)
326
+ })
327
+
328
+ it('cell image 门面:插入 → get/has → 移除 → undo 还原,经命令可 undo', () => {
329
+ const sheet = new Sheet()
330
+ const ctx = createSheetContext(sheet)
331
+ const addr = { row: 1, col: 2 }
332
+ const payload = { src: 'https://example.com/a.png' }
333
+
334
+ expect(ctx.hasCellImage(addr)).toBe(false)
335
+ expect(ctx.getCellImage(addr)).toBeUndefined()
336
+
337
+ ctx.insertCellImage(addr, payload)
338
+ expect(ctx.hasCellImage(addr)).toBe(true)
339
+ expect(ctx.getCellImage(addr)).toEqual(payload)
340
+
341
+ ctx.removeCellImage(addr)
342
+ expect(ctx.hasCellImage(addr)).toBe(false)
343
+ expect(ctx.getCellImage(addr)).toBeUndefined()
344
+
345
+ // undo 还原移除的嵌入图
346
+ expect(ctx.undo()).toBe(true)
347
+ expect(ctx.hasCellImage(addr)).toBe(true)
348
+ expect(ctx.getCellImage(addr)).toEqual(payload)
349
+ })
350
+
351
+ it('onCellImageChange 订阅/退订:单格变更带 addr 定向载荷', () => {
352
+ const sheet = new Sheet()
353
+ const ctx = createSheetContext(sheet)
354
+ const onCellImage = vi.fn()
355
+ const off = ctx.onCellImageChange(onCellImage)
356
+
357
+ const addr = { row: 0, col: 0 }
358
+ ctx.insertCellImage(addr, { src: 'https://example.com/a.png' })
359
+ expect(onCellImage).toHaveBeenCalledWith({ addr })
360
+
361
+ ctx.removeCellImage(addr)
362
+ expect(onCellImage).toHaveBeenCalledTimes(2)
363
+
364
+ // 退订后不再回调
365
+ off()
366
+ onCellImage.mockClear()
367
+ ctx.insertCellImage(addr, { src: 'https://example.com/b.png' })
368
+ expect(onCellImage).not.toHaveBeenCalled()
369
+ })
281
370
  })
@@ -9,6 +9,7 @@ import type { SelectionState } from 'infinitable/sheet'
9
9
  import type { FrozenState, Sheet } from 'infinitable/sheet'
10
10
  import type { CellStyle, CellStylePatch } from 'infinitable/sheet'
11
11
  import type { Workbook } from 'infinitable/sheet'
12
+ import type { CellImagePayload, CellLinkPayload } from 'infinitable/sheet'
12
13
 
13
14
  import { axisStyleItemsForRange, classifySelectionStyleTarget } from './apply-style'
14
15
 
@@ -128,17 +129,37 @@ export interface SheetContext {
128
129
  insertImage(input: ImageInput): string
129
130
  /** 删除浮动图片;不存在则无操作 */
130
131
  removeImage(id: string): void
131
- /** 更新浮动图片锚点/尺寸/文案;不存在或无变更则无操作 */
132
+ /** 更新浮动图片锚点/尺寸/文案/链接(link 传 null 清除);不存在或无变更则无操作 */
132
133
  updateImage(id: string, patch: ImageUpdateFields): void
133
134
  /** 只读图片列表(快照副本) */
134
135
  getImages(): readonly SheetImage[]
135
136
 
137
+ // ─── 单元格超链接(写入经 cell-link 命令,可 undo) ─────────
138
+ /** 写入单元格超链接;link 为 null 时清除该格链接(合并格解析锚点) */
139
+ setCellLink(addr: CellAddress, link: CellLinkPayload | null): void
140
+ /** 读取单元格超链接载荷(副本);无链接返回 undefined(合并格解析锚点) */
141
+ getCellLink(addr: CellAddress): CellLinkPayload | undefined
142
+ /** 清除单元格超链接;无链接则无操作(合并格解析锚点) */
143
+ clearCellLink(addr: CellAddress): void
144
+
145
+ // ─── 按格嵌入图(写入经 cell-image 命令,可 undo) ─────────
146
+ /** 插入(或覆盖)按格嵌入图;相同载荷视为无操作(合并格解析锚点) */
147
+ insertCellImage(addr: CellAddress, image: CellImagePayload): void
148
+ /** 移除按格嵌入图;无图时无操作(合并格解析锚点) */
149
+ removeCellImage(addr: CellAddress): void
150
+ /** 读取按格嵌入图载荷(副本);无图返回 undefined(合并格解析锚点) */
151
+ getCellImage(addr: CellAddress): CellImagePayload | undefined
152
+ /** 该格是否有嵌入图(供右键菜单等判定;合并格解析锚点) */
153
+ hasCellImage(addr: CellAddress): boolean
154
+
136
155
  // ─── 事件订阅(订阅时绑定到当前活动 sheet;tab 切换后需重新订阅) ──
137
156
  onSelectionChange(handler: (state: SelectionState) => void): () => void
138
157
  onHistoryChange(handler: (state: HistoryState) => void): () => void
139
158
  onFrozenChange(handler: (state: FrozenState) => void): () => void
140
159
  /** 图片集合变化(单图带 id;整表替换时 id 缺省) */
141
160
  onImageChange(handler: (payload: { id?: string }) => void): () => void
161
+ /** 按格嵌入图变化(单格带 addr;结构平移/整表替换时缺省) */
162
+ onCellImageChange(handler: (payload: { addr?: CellAddress }) => void): () => void
142
163
  }
143
164
 
144
165
  /** createSheetContext 可选配置 */
@@ -273,6 +294,15 @@ export function createSheetContext(
273
294
  updateImage: (id, patch) => sheet().updateImage(id, patch),
274
295
  getImages: () => sheet().getImages(),
275
296
 
297
+ setCellLink: (addr, link) => sheet().setCellLink(addr, link),
298
+ getCellLink: (addr) => sheet().getCellLink(addr),
299
+ clearCellLink: (addr) => sheet().clearCellLink(addr),
300
+
301
+ insertCellImage: (addr, image) => sheet().insertCellImage(addr, image),
302
+ removeCellImage: (addr) => sheet().removeCellImage(addr),
303
+ getCellImage: (addr) => sheet().getCellImage(addr),
304
+ hasCellImage: (addr) => sheet().hasCellImage(addr),
305
+
276
306
  beginTransaction: () => sheet().beginTransaction(),
277
307
  commit: () => sheet().commit(),
278
308
  rollback: () => sheet().rollback(),
@@ -289,6 +319,7 @@ export function createSheetContext(
289
319
  onSelectionChange: (handler) => sheet().on('selection-change', handler),
290
320
  onHistoryChange: (handler) => sheet().on('history-change', handler),
291
321
  onFrozenChange: (handler) => sheet().on('frozen-change', handler),
292
- onImageChange: (handler) => sheet().on('image-change', handler)
322
+ onImageChange: (handler) => sheet().on('image-change', handler),
323
+ onCellImageChange: (handler) => sheet().on('cell-image-change', handler)
293
324
  }
294
325
  }