xiaodao-spreader 0.1.36 → 0.1.38

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 (29) hide show
  1. package/README.ZH.md +85 -2
  2. package/README.md +83 -2
  3. package/dist/style.css +1 -1
  4. package/dist/types/components/spreader/components/data-validation-input-message.vue.d.ts +2 -2
  5. package/dist/types/components/spreader/components/dropdown.vue.d.ts +4 -1
  6. package/dist/types/components/spreader/components/note-overlay.vue.d.ts +47 -0
  7. package/dist/types/components/spreader/components/pickers/border-picker.vue.d.ts +3 -0
  8. package/dist/types/components/spreader/components/pickers/calc-picker.vue.d.ts +2 -0
  9. package/dist/types/components/spreader/components/pickers/color-picker.vue.d.ts +3 -0
  10. package/dist/types/components/spreader/components/pickers/conditional-format-menu.vue.d.ts +8 -0
  11. package/dist/types/components/spreader/components/pickers/data-validation-dropdown.vue.d.ts +5 -3
  12. package/dist/types/components/spreader/components/pickers/filter-popup.vue.d.ts +2 -0
  13. package/dist/types/components/spreader/components/pickers/merge-picker.vue.d.ts +3 -0
  14. package/dist/types/components/spreader/components/pickers/outline-picker.vue.d.ts +6 -0
  15. package/dist/types/components/spreader/components/pickers/sort-picker.vue.d.ts +3 -0
  16. package/dist/types/components/spreader/components/spreader.vue.d.ts +36 -0
  17. package/dist/types/components/spreader/components/tabbar.vue.d.ts +2 -0
  18. package/dist/types/components/spreader/components/toolbar.vue.d.ts +23 -0
  19. package/dist/types/components/spreader/composables/core-state.d.ts +19 -1
  20. package/dist/types/components/spreader/composables/interactions.d.ts +21 -0
  21. package/dist/types/components/spreader/composables/useFloatMenuPosition.d.ts +39 -0
  22. package/dist/types/components/spreader/core/constants.d.ts +2 -0
  23. package/dist/types/components/spreader/core/notes.d.ts +47 -0
  24. package/dist/types/components/spreader/core/outline-core.d.ts +2 -2
  25. package/dist/types/components/spreader/core/types.d.ts +26 -2
  26. package/dist/types/components/spreader/core/utils.d.ts +20 -0
  27. package/dist/xiaodao-spreader.es.js +8432 -8049
  28. package/dist/xiaodao-spreader.umd.js +9 -9
  29. package/package.json +1 -1
@@ -6,6 +6,7 @@ type __VLS_Props = {
6
6
  height?: number | string;
7
7
  theme?: 'light' | 'dark';
8
8
  locale?: string;
9
+ noteAuthor?: string;
9
10
  };
10
11
  type __VLS_PublicProps = {
11
12
  'data'?: SheetModelData[];
@@ -15,6 +16,7 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
15
16
  }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
16
17
  "onUpdate:data"?: ((value: SheetModelData[]) => any) | undefined;
17
18
  }>, {
19
+ noteAuthor: string;
18
20
  locale: string;
19
21
  rowCount: number;
20
22
  colCount: number;
@@ -48,6 +50,7 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
48
50
  cachedSortOrder: import("@/components/spreader/core/sort-core.ts").SortOrder;
49
51
  canSort: boolean;
50
52
  outlineMenuOpen: boolean;
53
+ outlineAxis?: "rows" | "cols" | null | undefined;
51
54
  canFilter: boolean;
52
55
  filterActive: boolean;
53
56
  selHAlign: string;
@@ -57,6 +60,12 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
57
60
  vAlignOptions: import("../core/constants").FontOption[];
58
61
  mergeMenuOpen: boolean;
59
62
  calcMenuOpen: boolean;
63
+ cfMenuOpen: boolean;
64
+ freezeMenuOpen: boolean;
65
+ fontMenuOpen: boolean;
66
+ hAlignMenuOpen: boolean;
67
+ vAlignMenuOpen: boolean;
68
+ numFmtMenuOpen: boolean;
60
69
  isSingleCell: boolean;
61
70
  hasFreeze: boolean;
62
71
  freezePanesDisabled: boolean;
@@ -65,6 +74,7 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
65
74
  nfOptions: import("../core/number-format").NFOption[];
66
75
  canIncreaseDecimals: boolean;
67
76
  canDecreaseDecimals: boolean;
77
+ boundaryEl?: HTMLElement | null | undefined;
68
78
  }> & Readonly<{
69
79
  onUndo?: (() => any) | undefined;
70
80
  onRedo?: (() => any) | undefined;
@@ -114,6 +124,12 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
114
124
  "onUpdate:outline-menu-open"?: ((v: boolean) => any) | undefined;
115
125
  "onUpdate:merge-menu-open"?: ((v: boolean) => any) | undefined;
116
126
  "onUpdate:calc-menu-open"?: ((v: boolean) => any) | undefined;
127
+ "onUpdate:cf-menu-open"?: ((v: boolean) => any) | undefined;
128
+ "onUpdate:freeze-menu-open"?: ((v: boolean) => any) | undefined;
129
+ "onUpdate:font-menu-open"?: ((v: boolean) => any) | undefined;
130
+ "onUpdate:h-align-menu-open"?: ((v: boolean) => any) | undefined;
131
+ "onUpdate:v-align-menu-open"?: ((v: boolean) => any) | undefined;
132
+ "onUpdate:num-fmt-menu-open"?: ((v: boolean) => any) | undefined;
117
133
  "onBorder-change"?: ((v: import("@/components/spreader/components/pickers/border-picker.vue").BorderType) => any) | undefined;
118
134
  "onSort-change"?: ((v: import("@/components/spreader/core/sort-core.ts").SortOrder) => any) | undefined;
119
135
  "onMerge-change"?: ((v: import("../core/constants").MergeType) => any) | undefined;
@@ -169,6 +185,12 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
169
185
  "update:outline-menu-open": (v: boolean) => void;
170
186
  "update:merge-menu-open": (v: boolean) => void;
171
187
  "update:calc-menu-open": (v: boolean) => void;
188
+ "update:cf-menu-open": (v: boolean) => void;
189
+ "update:freeze-menu-open": (v: boolean) => void;
190
+ "update:font-menu-open": (v: boolean) => void;
191
+ "update:h-align-menu-open": (v: boolean) => void;
192
+ "update:v-align-menu-open": (v: boolean) => void;
193
+ "update:num-fmt-menu-open": (v: boolean) => void;
172
194
  "border-change": (v: import("@/components/spreader/components/pickers/border-picker.vue").BorderType) => void;
173
195
  "sort-change": (v: import("@/components/spreader/core/sort-core.ts").SortOrder) => void;
174
196
  "merge-change": (v: import("../core/constants").MergeType) => void;
@@ -220,6 +242,7 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
220
242
  cachedSortOrder: import("@/components/spreader/core/sort-core.ts").SortOrder;
221
243
  canSort: boolean;
222
244
  outlineMenuOpen: boolean;
245
+ outlineAxis?: "rows" | "cols" | null | undefined;
223
246
  canFilter: boolean;
224
247
  filterActive: boolean;
225
248
  selHAlign: string;
@@ -229,6 +252,12 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
229
252
  vAlignOptions: import("../core/constants").FontOption[];
230
253
  mergeMenuOpen: boolean;
231
254
  calcMenuOpen: boolean;
255
+ cfMenuOpen: boolean;
256
+ freezeMenuOpen: boolean;
257
+ fontMenuOpen: boolean;
258
+ hAlignMenuOpen: boolean;
259
+ vAlignMenuOpen: boolean;
260
+ numFmtMenuOpen: boolean;
232
261
  isSingleCell: boolean;
233
262
  hasFreeze: boolean;
234
263
  freezePanesDisabled: boolean;
@@ -237,6 +266,7 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
237
266
  nfOptions: import("../core/number-format").NFOption[];
238
267
  canIncreaseDecimals: boolean;
239
268
  canDecreaseDecimals: boolean;
269
+ boundaryEl?: HTMLElement | null | undefined;
240
270
  }> & Readonly<{
241
271
  onUndo?: (() => any) | undefined;
242
272
  onRedo?: (() => any) | undefined;
@@ -286,6 +316,12 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
286
316
  "onUpdate:outline-menu-open"?: ((v: boolean) => any) | undefined;
287
317
  "onUpdate:merge-menu-open"?: ((v: boolean) => any) | undefined;
288
318
  "onUpdate:calc-menu-open"?: ((v: boolean) => any) | undefined;
319
+ "onUpdate:cf-menu-open"?: ((v: boolean) => any) | undefined;
320
+ "onUpdate:freeze-menu-open"?: ((v: boolean) => any) | undefined;
321
+ "onUpdate:font-menu-open"?: ((v: boolean) => any) | undefined;
322
+ "onUpdate:h-align-menu-open"?: ((v: boolean) => any) | undefined;
323
+ "onUpdate:v-align-menu-open"?: ((v: boolean) => any) | undefined;
324
+ "onUpdate:num-fmt-menu-open"?: ((v: boolean) => any) | undefined;
289
325
  "onBorder-change"?: ((v: import("@/components/spreader/components/pickers/border-picker.vue").BorderType) => any) | undefined;
290
326
  "onSort-change"?: ((v: import("@/components/spreader/core/sort-core.ts").SortOrder) => any) | undefined;
291
327
  "onMerge-change"?: ((v: import("../core/constants").MergeType) => any) | undefined;
@@ -5,6 +5,8 @@ type __VLS_Props = {
5
5
  activeSheetIndex: number;
6
6
  renTab: number | null;
7
7
  renTabVal: string;
8
+ /** 边界基准元素(通常是表格容器 wrapper):列表菜单不得越出其可视区,见 getFloatBounds */
9
+ boundaryEl?: HTMLElement | null;
8
10
  };
9
11
  declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
10
12
  "tab-click": (i: number) => void;
@@ -31,6 +31,8 @@ type __VLS_Props = {
31
31
  cachedSortOrder: SortOrder;
32
32
  canSort: boolean;
33
33
  outlineMenuOpen: boolean;
34
+ /** 当前选区轴:'rows'=选中整行,'cols'=选中整列,null=未选中行/列。决定「分组」按钮是否可用(置灰提示先选行/列) */
35
+ outlineAxis?: 'rows' | 'cols' | null;
34
36
  /** 工具栏「筛选」按钮是否可用(单选合并单元格且无筛选态时禁用) */
35
37
  canFilter: boolean;
36
38
  /** 当前 worksheet 是否已启用筛选 */
@@ -42,6 +44,12 @@ type __VLS_Props = {
42
44
  vAlignOptions: FontOption[];
43
45
  mergeMenuOpen: boolean;
44
46
  calcMenuOpen: boolean;
47
+ cfMenuOpen: boolean;
48
+ freezeMenuOpen: boolean;
49
+ fontMenuOpen: boolean;
50
+ hAlignMenuOpen: boolean;
51
+ vAlignMenuOpen: boolean;
52
+ numFmtMenuOpen: boolean;
45
53
  isSingleCell: boolean;
46
54
  /** 当前 worksheet 是否已有冻结行或列 */
47
55
  hasFreeze: boolean;
@@ -52,6 +60,9 @@ type __VLS_Props = {
52
60
  nfOptions: NFOption[];
53
61
  canIncreaseDecimals: boolean;
54
62
  canDecreaseDecimals: boolean;
63
+ /** 边界基准元素(通常是表格容器 wrapper):弹出菜单不得越出其可视区。
64
+ * 组件嵌入宿主 Vue 页面时必需——否则菜单会越界盖住宿主内容。缺省时退化为纯视口判定。 */
65
+ boundaryEl?: HTMLElement | null;
55
66
  };
56
67
  declare const _default: import("vue").DefineComponent<__VLS_Props, {
57
68
  closeOverflow: typeof closeOverflow;
@@ -104,6 +115,12 @@ declare const _default: import("vue").DefineComponent<__VLS_Props, {
104
115
  "update:outline-menu-open": (v: boolean) => void;
105
116
  "update:merge-menu-open": (v: boolean) => void;
106
117
  "update:calc-menu-open": (v: boolean) => void;
118
+ "update:cf-menu-open": (v: boolean) => void;
119
+ "update:freeze-menu-open": (v: boolean) => void;
120
+ "update:font-menu-open": (v: boolean) => void;
121
+ "update:h-align-menu-open": (v: boolean) => void;
122
+ "update:v-align-menu-open": (v: boolean) => void;
123
+ "update:num-fmt-menu-open": (v: boolean) => void;
107
124
  "border-change": (v: BorderType) => void;
108
125
  "sort-change": (v: SortOrder) => void;
109
126
  "merge-change": (v: MergeType) => void;
@@ -157,6 +174,12 @@ declare const _default: import("vue").DefineComponent<__VLS_Props, {
157
174
  "onUpdate:outline-menu-open"?: ((v: boolean) => any) | undefined;
158
175
  "onUpdate:merge-menu-open"?: ((v: boolean) => any) | undefined;
159
176
  "onUpdate:calc-menu-open"?: ((v: boolean) => any) | undefined;
177
+ "onUpdate:cf-menu-open"?: ((v: boolean) => any) | undefined;
178
+ "onUpdate:freeze-menu-open"?: ((v: boolean) => any) | undefined;
179
+ "onUpdate:font-menu-open"?: ((v: boolean) => any) | undefined;
180
+ "onUpdate:h-align-menu-open"?: ((v: boolean) => any) | undefined;
181
+ "onUpdate:v-align-menu-open"?: ((v: boolean) => any) | undefined;
182
+ "onUpdate:num-fmt-menu-open"?: ((v: boolean) => any) | undefined;
160
183
  "onBorder-change"?: ((v: BorderType) => any) | undefined;
161
184
  "onSort-change"?: ((v: SortOrder) => any) | undefined;
162
185
  "onMerge-change"?: ((v: MergeType) => any) | undefined;
@@ -1,6 +1,6 @@
1
1
  import { type ComputedRef, type Ref } from 'vue';
2
2
  import { FormulaDeps } from '../core/formula';
3
- import type { CellCoord, CellData, CellStyle, SelectionRange, BorderStyle, BorderSide, FreezePane, ViewportRegion, SheetFilter, FilterColumn, ConditionalFormattingRule, ConditionalFormattingFormat, DataValidationRule, DataValidationResult, DataValidationSeverity, DimensionOutline } from '../core/types';
3
+ import type { CellCoord, CellData, CellStyle, CellNote, SelectionRange, BorderStyle, BorderSide, FreezePane, ViewportRegion, SheetFilter, FilterColumn, ConditionalFormattingRule, ConditionalFormattingFormat, DataValidationRule, DataValidationResult, DataValidationSeverity, DimensionOutline } from '../core/types';
4
4
  import { type FilterCandidates } from '../core/filter-core';
5
5
  import { type OutlineValidationResult } from '../core/outline-core';
6
6
  /** 选区触发方式,影响「合并单元格是否扩大选区」。
@@ -259,6 +259,24 @@ export interface CoreState {
259
259
  clampScroll?: (sx: number | null, sy: number | null) => void;
260
260
  /** 查找高亮钩子:返回某单元格当前的高亮类型(由 find-replace 模块注入) */
261
261
  findHighlight?: (col: number, row: number) => 'active' | 'match' | null;
262
+ /** 当前工作表批注池:按 noteId 存放,cell.noteId 引用之;与 value/style 完全独立 */
263
+ notes: Record<string, CellNote>;
264
+ /** 单元格是否有批注 */
265
+ hasNote: (row: number, col: number) => boolean;
266
+ /** 读取单元格批注(返回池中对象引用) */
267
+ getNote: (row: number, col: number) => CellNote | undefined;
268
+ /** 为单元格创建/覆盖批注(一次独立 Undo),返回新批注 */
269
+ setCellNote: (row: number, col: number, text: string, author?: string, opts?: {
270
+ silent?: boolean;
271
+ }) => CellNote;
272
+ /** 更新现存批注文本(按 id,一次独立 Undo) */
273
+ updateCellNote: (id: string, text: string) => void;
274
+ /** 删除单元格批注(一次独立 Undo) */
275
+ deleteCellNote: (row: number, col: number) => void;
276
+ /** 清理 notes 池中未被任何 cell 引用的孤儿批注(删除/覆盖单元格后调用) */
277
+ gcNotes: () => void;
278
+ /** 批量读取选区内所有批注(key -> note) */
279
+ getNotesInRange: (range: SelectionRange) => Map<string, CellNote>;
262
280
  /** 当前工作表的全部数据验证规则(规则属于 Sheet,不属于 Cell) */
263
281
  dataValidations: DataValidationRule[];
264
282
  /** 命中该单元格的全部规则(经空间索引,不遍历整表) */
@@ -69,6 +69,27 @@ export interface InteractionsState {
69
69
  openValidationDropdown: (col: number, row: number) => boolean;
70
70
  closeValidationDropdown: () => void;
71
71
  onValidationDropdownSelect: (value: string) => void;
72
+ /** 当前显示的批注浮层:mode=view 查看 / edit 编辑;null=关闭 */
73
+ noteUi: Ref<{
74
+ mode: 'view' | 'edit';
75
+ row: number;
76
+ col: number;
77
+ } | null>;
78
+ /** 按逻辑坐标打开批注浮层(view / edit);编辑态需由宿主组件聚焦输入框 */
79
+ openNote: (row: number, col: number, mode: 'view' | 'edit') => void;
80
+ /** 关闭批注浮层 */
81
+ closeNote: () => void;
82
+ /** 右键 / Shift+F2 入口:新建或编辑批注(有则预填、无则新建) */
83
+ editNoteAt: (row: number, col: number) => void;
84
+ /** 编辑态保存:空文本删除现存批注;非空按新建/更新走 setCellNote/updateCellNote */
85
+ saveNoteAt: (row: number, col: number, text: string, author?: string) => void;
86
+ /** 右键:删除批注 */
87
+ removeNoteAt: (row: number, col: number) => void;
88
+ /** 命中测试:点是否落在单元格右上角的批注指示器上 */
89
+ isNoteIndicatorHit: (x: number, y: number) => {
90
+ row: number;
91
+ col: number;
92
+ } | null;
72
93
  dimInputRef: Ref<HTMLInputElement | null>;
73
94
  dimPanel: Ref<{
74
95
  type: 'row' | 'col';
@@ -0,0 +1,39 @@
1
+ export interface FloatMenuPosition {
2
+ /** fixed 定位:右缘(px),与 trigger 右缘对齐后夹回有效右边界 */
3
+ right?: number;
4
+ /** fixed 定位:左缘(px)。默认不使用,仅当右缘锚定不可用时的兜底 */
5
+ left?: number;
6
+ /** fixed 定位:上缘(px) */
7
+ top: number;
8
+ /** 是否向上翻向弹出(trigger 下方放不下且上方有空间) */
9
+ up: boolean;
10
+ }
11
+ /**
12
+ * 主弹出菜单(工具栏下拉框:条件格式 / 分组等)的统一定位逻辑。
13
+ *
14
+ * 与 conditional-format-menu.vue 原实现完全同构,抽出来让所有工具栏下拉框复用同一套,
15
+ * 不再各写一套:
16
+ * - 右缘锚定 trigger 右缘(Math.min(r.right, b.right) 夹回有效右边界),top 先落 trigger 下缘 +4;
17
+ * - 传入 menuEl(已挂载、可量高度)后,按「容器∩视口」有效区做上下翻向 + 夹紧:
18
+ * 下方放得下就向下;下方放不下但上方有空间就向上;两边都放不下→夹紧贴顶/贴底兜底。
19
+ * 夹紧下界取 min(b.top + 8, trigger 下缘 + 4):工具栏按钮在 boundaryEl(表格容器)之上,
20
+ * 此时 b.top + 8 落在按钮下方,若仍以它为下界会把菜单硬推离按钮数十像素(主栏下拉整体下移),
21
+ * 故下界不得高于「紧贴 trigger 下方」这一理想位置。
22
+ *
23
+ * 调用约定(与 cf-menu 一致):先 place(trigger, boundary) 做初始下落放置,
24
+ * 再于 nextTick 后 place(trigger, boundary, menuEl) 量高翻向。
25
+ */
26
+ export declare function useFloatMenuPosition(): {
27
+ pos: import("vue").Ref<{
28
+ right?: number | undefined;
29
+ left?: number | undefined;
30
+ top: number;
31
+ up: boolean;
32
+ }, FloatMenuPosition | {
33
+ right?: number | undefined;
34
+ left?: number | undefined;
35
+ top: number;
36
+ up: boolean;
37
+ }>;
38
+ place: (triggerEl: HTMLElement, boundaryEl: HTMLElement | null | undefined, menuEl?: HTMLElement | null) => void;
39
+ };
@@ -15,6 +15,8 @@ export declare const FILL_HANDLE_HIT_PADDING = 4;
15
15
  export declare const UNDO_MAX = 50;
16
16
  export declare const OUTLINE_PANEL = 16;
17
17
  export declare const OUTLINE_GUTTER = 15;
18
+ /** 新建批注时的默认作者(空串=不记录作者名,显示时用 i18n noteUnnamed 占位) */
19
+ export declare const DEFAULT_NOTE_AUTHOR = "";
18
20
  export declare const i18n: Record<string, Record<string, string>>;
19
21
  export declare function t(locale: string, key: string): string;
20
22
  export declare const DEFAULT_FONT_FAMILY = "-apple-system, BlinkMacSystemFont, \"Segoe UI\", \"Microsoft YaHei\", sans-serif";
@@ -0,0 +1,47 @@
1
+ import type { CellNote, CellData, SelectionRange } from './types';
2
+ /** 生成唯一 Note ID */
3
+ export declare function genNoteId(): string;
4
+ export declare function createEmptyNotes(): Record<string, CellNote>;
5
+ /** 从序列化数据加载批注池(兼容旧数据无 notes 的情况;返回浅拷贝避免共享引用) */
6
+ export declare function loadNotes(serialized?: Record<string, CellNote>): Record<string, CellNote>;
7
+ /** 单元格是否有批注 */
8
+ export declare function hasNote(row: number, col: number, cells: Record<string, CellData>): boolean;
9
+ /** 读取单元格批注(返回池中对象引用) */
10
+ export declare function getNote(row: number, col: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): CellNote | undefined;
11
+ /** 按 ID 读取批注 */
12
+ export declare function getNoteById(id: string, notes: Record<string, CellNote>): CellNote | undefined;
13
+ /** 创建纯批注对象(不落池) */
14
+ export declare function createNote(text: string, author?: string): CellNote;
15
+ /**
16
+ * 为单元格创建/覆盖批注:新建 note 写入池并绑定 cell.noteId。
17
+ * 若 cell 原先已有批注会先清理旧池对象(避免孤儿)。
18
+ * 返回新批注对象。
19
+ */
20
+ export declare function setNote(row: number, col: number, text: string, author: string | undefined, cells: Record<string, CellData>, notes: Record<string, CellNote>): CellNote;
21
+ /** 更新现存批注文本(仅改 text 与 updatedAt) */
22
+ export declare function updateNote(id: string, text: string, notes: Record<string, CellNote>): CellNote;
23
+ /** 删除单元格批注(清理池对象 + cell.noteId),返回被删的 note 或 undefined */
24
+ export declare function removeNote(row: number, col: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): CellNote | undefined;
25
+ /** 批量读取选区内所有批注(key -> note) */
26
+ export declare function getNotesInRange(range: SelectionRange, cells: Record<string, CellData>, notes: Record<string, CellNote>): Map<string, CellNote>;
27
+ /**
28
+ * 复制批注引用:源 cell 有 note 时,目标 cell 复用同一 noteId(共享 note 对象)。
29
+ * 目标原有批注会被覆盖(其池对象交由上层统一 GC)。
30
+ */
31
+ export declare function copyNoteToCell(srcRow: number, srcCol: number, dstRow: number, dstCol: number, cells: Record<string, CellData>): void;
32
+ /** 清理池中没有被任何 cell 引用的孤儿 note */
33
+ export declare function gcOrphanNotes(cells: Record<string, CellData>, notes: Record<string, CellNote>): void;
34
+ /**
35
+ * 插入行后平移全部 cell 引用(row >= insertAt 的行整体下移 count)。
36
+ * 项目本体在 sheets-ops 的 insertRows 中已有整块单元格搬移逻辑,
37
+ * 此处声明为独立函数便于与 notes 联动测试;实际调用时由上层在搬移后同步执行。
38
+ */
39
+ export declare function adjustForInsertRows(insertAt: number, count: number, cells: Record<string, CellData>): void;
40
+ /** 插入列后平移全部 cell 引用 */
41
+ export declare function adjustForInsertCols(insertAt: number, count: number, cells: Record<string, CellData>): void;
42
+ /** 删除行:命中区间的 cell 及其 note 一并删除,后续行整体上移 */
43
+ export declare function adjustForDeleteRows(deleteStart: number, deleteEnd: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): void;
44
+ /** 删除列:命中区间的 cell 及其 note 一并删除,后续列整体左移 */
45
+ export declare function adjustForDeleteCols(deleteStart: number, deleteEnd: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): void;
46
+ /** 交换两个单元格的 noteId 引用(排序时随数据一起移动) */
47
+ export declare function swapNotes(row1: number, col1: number, row2: number, col2: number, cells: Record<string, CellData>): void;
@@ -14,8 +14,8 @@ export declare function countContaining(outlines: DimensionOutline[], start: num
14
14
  * 规则:
15
15
  * - start <= end
16
16
  * - 至少连续 2 个维度
17
- * - 与既有分组要么不相交要么完全包含,禁止部分重叠
18
- * - 层级(countContaining + 1)不超过 MAX_OUTLINE_LEVEL
17
+ * - 与既有分组必须完全不相交,禁止部分重叠与嵌套(仅支持一层分组)
18
+ * - 层级恒为 1(countContaining 必须为 0)
19
19
  */
20
20
  export declare function validateGroup(existing: DimensionOutline[], start: number, end: number): OutlineValidationResult;
21
21
  /** 创建分组后的新集合(校验失败返回原集合,同时给出校验结果供调用方提示) */
@@ -59,6 +59,26 @@ export interface CellStyle {
59
59
  export interface CellData {
60
60
  value: string;
61
61
  styleId?: number;
62
+ /** 批注引用:指向 Sheet 级 notes 池中的一个 CellNote;与 value/style 完全独立 */
63
+ noteId?: string;
64
+ }
65
+ /**
66
+ * 批注是绑定到 Cell 的独立附加元数据,不属于 cell.value / formula / style。
67
+ * 采用「Note Pool」存储:Sheet 级 notes 池按 id 存放,cell 只保存 noteId 引用,
68
+ * 便于扩展 Threaded Comment,且多个操作(排序/插入删除)移动 cell 时 noteId 随数据移动。
69
+ * 第一阶段实现与多人协作 Threaded Comment 无关。
70
+ */
71
+ export interface CellNote {
72
+ /** 稳定唯一 ID(不可用数组 index) */
73
+ id: string;
74
+ /** 批注正文(多行文本,含换行) */
75
+ text: string;
76
+ /** 作者信息(可选) */
77
+ author?: string;
78
+ /** 创建时间(epoch ms) */
79
+ createdAt: number;
80
+ /** 最近修改时间(epoch ms) */
81
+ updatedAt: number;
62
82
  }
63
83
  /** 搜索范围:当前工作表 / 整个工作簿 / 当前选区 */
64
84
  export type FindScope = 'sheet' | 'workbook' | 'selection';
@@ -252,8 +272,8 @@ export interface DataValidationResult {
252
272
  title?: string;
253
273
  message?: string;
254
274
  }
255
- /** 单个行列分组的最大支持层级(与 Excel 一致,最多 8 级) */
256
- export declare const MAX_OUTLINE_LEVEL = 8;
275
+ /** 单个行列分组的最大支持层级:固定为 1,即仅支持一层分组(分组之间互不嵌套) */
276
+ export declare const MAX_OUTLINE_LEVEL = 1;
257
277
  /** 维度分组:属于 Sheet 的结构元数据。start/end 为 0-based 闭区间,且 start <= end */
258
278
  export interface DimensionOutline {
259
279
  /** 稳定唯一 ID(禁止数组 index) */
@@ -296,6 +316,8 @@ export interface SheetModelData {
296
316
  rowOutlines?: DimensionOutline[];
297
317
  /** 列分组集合;旧数据缺省视为无分组 */
298
318
  columnOutlines?: DimensionOutline[];
319
+ /** 单元格批注池:按 noteId 存放,cell.noteId 引用之;与 cell value/style 完全独立 */
320
+ notes?: Record<string, CellNote>;
299
321
  }
300
322
  export interface SheetState {
301
323
  id: string;
@@ -328,6 +350,8 @@ export interface SheetState {
328
350
  rowOutlines: DimensionOutline[];
329
351
  /** 列分组集合;缺省为空数组 */
330
352
  columnOutlines: DimensionOutline[];
353
+ /** 单元格批注池:按 noteId 存放,cell.noteId 引用之 */
354
+ notes: Record<string, CellNote>;
331
355
  }
332
356
  /** 视口区域:冻结窗格将画布划分为四个独立滚动区域 */
333
357
  export interface ViewportRegion {
@@ -24,3 +24,23 @@ export declare function getCanvasXY(e: MouseEvent, canvas: HTMLCanvasElement | n
24
24
  export declare function gridViewW(viewW: number, sbSize: number): number;
25
25
  /** 网格可视区域高度(减去行头和滚动条) */
26
26
  export declare function gridViewH(viewH: number, sbSize: number): number;
27
+ /** 浮层可用的有效边界(视口坐标系)。
28
+ *
29
+ * 取「组件容器(boundaryEl)」∩「浏览器视口」的交集,两者都不能单独作为判据:
30
+ * - 浏览器视口:浮层 Teleport 到 body + position:fixed,挂在视口坐标系,越出视口一定看不见(硬边界)。
31
+ * 但组件作为子组件嵌入宿主页面时只占页面一部分,纯视口判定会漏算两侧留白 → 越界盖住宿主内容。
32
+ * - 组件容器:嵌入场景下把浮层夹在表格可视区内。但容器可能大于视口(页面滚动、边缘在视口外),
33
+ * 纯容器判定会把「其实已在视口外」当成有空间 → 浮层照样看不见。
34
+ *
35
+ * 取交集后:组件全屏时容器≈视口,自然退化为纯视口判定;boundaryEl 为空时同样退化为纯视口。
36
+ */
37
+ export interface FloatBounds {
38
+ left: number;
39
+ right: number;
40
+ top: number;
41
+ bottom: number;
42
+ }
43
+ export declare function getFloatBounds(boundaryEl?: HTMLElement | null): FloatBounds;
44
+ /** 把「视口坐标 x」换算成 fixed 定位的 CSS `right` 值(相对视口右缘的偏移)。
45
+ * 浮层以 position:fixed 挂在视口坐标系,故换算基准恒为 window.innerWidth,与有效边界无关。 */
46
+ export declare function cssRightFromX(x: number): number;