xiaodao-spreader 0.1.37 → 0.1.38

package/dist/types/components/spreader/components/spreader.vue.d.ts

@@ -6,6 +6,7 @@ type __VLS_Props = {
     height?: number | string;
     theme?: 'light' | 'dark';
     locale?: string;
+    noteAuthor?: string;
 };
 type __VLS_PublicProps = {
     'data'?: SheetModelData[];
@@ -15,6 +16,7 @@ declare const _default: import("vue").DefineComponent<__VLS_PublicProps, {}, {},
 }, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
     "onUpdate:data"?: ((value: SheetModelData[]) => any) | undefined;
 }>, {
+    noteAuthor: string;
     locale: string;
     rowCount: number;
     colCount: number;

package/dist/types/components/spreader/composables/core-state.d.ts

@@ -1,6 +1,6 @@
 import { type ComputedRef, type Ref } from 'vue';
 import { FormulaDeps } from '../core/formula';
-import type { CellCoord, CellData, CellStyle, SelectionRange, BorderStyle, BorderSide, FreezePane, ViewportRegion, SheetFilter, FilterColumn, ConditionalFormattingRule, ConditionalFormattingFormat, DataValidationRule, DataValidationResult, DataValidationSeverity, DimensionOutline } from '../core/types';
+import type { CellCoord, CellData, CellStyle, CellNote, SelectionRange, BorderStyle, BorderSide, FreezePane, ViewportRegion, SheetFilter, FilterColumn, ConditionalFormattingRule, ConditionalFormattingFormat, DataValidationRule, DataValidationResult, DataValidationSeverity, DimensionOutline } from '../core/types';
 import { type FilterCandidates } from '../core/filter-core';
 import { type OutlineValidationResult } from '../core/outline-core';
 /** 选区触发方式，影响「合并单元格是否扩大选区」。
@@ -259,6 +259,24 @@ export interface CoreState {
     clampScroll?: (sx: number | null, sy: number | null) => void;
     /** 查找高亮钩子：返回某单元格当前的高亮类型（由 find-replace 模块注入） */
     findHighlight?: (col: number, row: number) => 'active' | 'match' | null;
+    /** 当前工作表批注池：按 noteId 存放，cell.noteId 引用之；与 value/style 完全独立 */
+    notes: Record<string, CellNote>;
+    /** 单元格是否有批注 */
+    hasNote: (row: number, col: number) => boolean;
+    /** 读取单元格批注（返回池中对象引用） */
+    getNote: (row: number, col: number) => CellNote | undefined;
+    /** 为单元格创建/覆盖批注（一次独立 Undo），返回新批注 */
+    setCellNote: (row: number, col: number, text: string, author?: string, opts?: {
+        silent?: boolean;
+    }) => CellNote;
+    /** 更新现存批注文本（按 id，一次独立 Undo） */
+    updateCellNote: (id: string, text: string) => void;
+    /** 删除单元格批注（一次独立 Undo） */
+    deleteCellNote: (row: number, col: number) => void;
+    /** 清理 notes 池中未被任何 cell 引用的孤儿批注（删除/覆盖单元格后调用） */
+    gcNotes: () => void;
+    /** 批量读取选区内所有批注（key -> note） */
+    getNotesInRange: (range: SelectionRange) => Map<string, CellNote>;
     /** 当前工作表的全部数据验证规则（规则属于 Sheet，不属于 Cell） */
     dataValidations: DataValidationRule[];
     /** 命中该单元格的全部规则（经空间索引，不遍历整表） */

package/dist/types/components/spreader/composables/interactions.d.ts

@@ -69,6 +69,27 @@ export interface InteractionsState {
     openValidationDropdown: (col: number, row: number) => boolean;
     closeValidationDropdown: () => void;
     onValidationDropdownSelect: (value: string) => void;
+    /** 当前显示的批注浮层：mode=view 查看 / edit 编辑；null=关闭 */
+    noteUi: Ref<{
+        mode: 'view' | 'edit';
+        row: number;
+        col: number;
+    } | null>;
+    /** 按逻辑坐标打开批注浮层（view / edit）；编辑态需由宿主组件聚焦输入框 */
+    openNote: (row: number, col: number, mode: 'view' | 'edit') => void;
+    /** 关闭批注浮层 */
+    closeNote: () => void;
+    /** 右键 / Shift+F2 入口：新建或编辑批注（有则预填、无则新建） */
+    editNoteAt: (row: number, col: number) => void;
+    /** 编辑态保存：空文本删除现存批注；非空按新建/更新走 setCellNote/updateCellNote */
+    saveNoteAt: (row: number, col: number, text: string, author?: string) => void;
+    /** 右键：删除批注 */
+    removeNoteAt: (row: number, col: number) => void;
+    /** 命中测试：点是否落在单元格右上角的批注指示器上 */
+    isNoteIndicatorHit: (x: number, y: number) => {
+        row: number;
+        col: number;
+    } | null;
     dimInputRef: Ref<HTMLInputElement | null>;
     dimPanel: Ref<{
         type: 'row' | 'col';

package/dist/types/components/spreader/core/constants.d.ts

@@ -15,6 +15,8 @@ export declare const FILL_HANDLE_HIT_PADDING = 4;
 export declare const UNDO_MAX = 50;
 export declare const OUTLINE_PANEL = 16;
 export declare const OUTLINE_GUTTER = 15;
+/** 新建批注时的默认作者（空串=不记录作者名，显示时用 i18n noteUnnamed 占位） */
+export declare const DEFAULT_NOTE_AUTHOR = "";
 export declare const i18n: Record<string, Record<string, string>>;
 export declare function t(locale: string, key: string): string;
 export declare const DEFAULT_FONT_FAMILY = "-apple-system, BlinkMacSystemFont, \"Segoe UI\", \"Microsoft YaHei\", sans-serif";

package/dist/types/components/spreader/core/notes.d.ts

@@ -0,0 +1,47 @@
+import type { CellNote, CellData, SelectionRange } from './types';
+/** 生成唯一 Note ID */
+export declare function genNoteId(): string;
+export declare function createEmptyNotes(): Record<string, CellNote>;
+/** 从序列化数据加载批注池（兼容旧数据无 notes 的情况；返回浅拷贝避免共享引用） */
+export declare function loadNotes(serialized?: Record<string, CellNote>): Record<string, CellNote>;
+/** 单元格是否有批注 */
+export declare function hasNote(row: number, col: number, cells: Record<string, CellData>): boolean;
+/** 读取单元格批注（返回池中对象引用） */
+export declare function getNote(row: number, col: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): CellNote | undefined;
+/** 按 ID 读取批注 */
+export declare function getNoteById(id: string, notes: Record<string, CellNote>): CellNote | undefined;
+/** 创建纯批注对象（不落池） */
+export declare function createNote(text: string, author?: string): CellNote;
+/**
+ * 为单元格创建/覆盖批注：新建 note 写入池并绑定 cell.noteId。
+ * 若 cell 原先已有批注会先清理旧池对象（避免孤儿）。
+ * 返回新批注对象。
+ */
+export declare function setNote(row: number, col: number, text: string, author: string | undefined, cells: Record<string, CellData>, notes: Record<string, CellNote>): CellNote;
+/** 更新现存批注文本（仅改 text 与 updatedAt） */
+export declare function updateNote(id: string, text: string, notes: Record<string, CellNote>): CellNote;
+/** 删除单元格批注（清理池对象 + cell.noteId），返回被删的 note 或 undefined */
+export declare function removeNote(row: number, col: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): CellNote | undefined;
+/** 批量读取选区内所有批注（key -> note） */
+export declare function getNotesInRange(range: SelectionRange, cells: Record<string, CellData>, notes: Record<string, CellNote>): Map<string, CellNote>;
+/**
+ * 复制批注引用：源 cell 有 note 时，目标 cell 复用同一 noteId（共享 note 对象）。
+ * 目标原有批注会被覆盖（其池对象交由上层统一 GC）。
+ */
+export declare function copyNoteToCell(srcRow: number, srcCol: number, dstRow: number, dstCol: number, cells: Record<string, CellData>): void;
+/** 清理池中没有被任何 cell 引用的孤儿 note */
+export declare function gcOrphanNotes(cells: Record<string, CellData>, notes: Record<string, CellNote>): void;
+/**
+ * 插入行后平移全部 cell 引用（row >= insertAt 的行整体下移 count）。
+ * 项目本体在 sheets-ops 的 insertRows 中已有整块单元格搬移逻辑，
+ * 此处声明为独立函数便于与 notes 联动测试；实际调用时由上层在搬移后同步执行。
+ */
+export declare function adjustForInsertRows(insertAt: number, count: number, cells: Record<string, CellData>): void;
+/** 插入列后平移全部 cell 引用 */
+export declare function adjustForInsertCols(insertAt: number, count: number, cells: Record<string, CellData>): void;
+/** 删除行：命中区间的 cell 及其 note 一并删除，后续行整体上移 */
+export declare function adjustForDeleteRows(deleteStart: number, deleteEnd: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): void;
+/** 删除列：命中区间的 cell 及其 note 一并删除，后续列整体左移 */
+export declare function adjustForDeleteCols(deleteStart: number, deleteEnd: number, cells: Record<string, CellData>, notes: Record<string, CellNote>): void;
+/** 交换两个单元格的 noteId 引用（排序时随数据一起移动） */
+export declare function swapNotes(row1: number, col1: number, row2: number, col2: number, cells: Record<string, CellData>): void;

package/dist/types/components/spreader/core/types.d.ts

@@ -59,6 +59,26 @@ export interface CellStyle {
 export interface CellData {
     value: string;
     styleId?: number;
+    /** 批注引用：指向 Sheet 级 notes 池中的一个 CellNote；与 value/style 完全独立 */
+    noteId?: string;
+}
+/**
+ * 批注是绑定到 Cell 的独立附加元数据，不属于 cell.value / formula / style。
+ * 采用「Note Pool」存储：Sheet 级 notes 池按 id 存放，cell 只保存 noteId 引用，
+ * 便于扩展 Threaded Comment，且多个操作（排序/插入删除）移动 cell 时 noteId 随数据移动。
+ * 第一阶段实现与多人协作 Threaded Comment 无关。
+ */
+export interface CellNote {
+    /** 稳定唯一 ID（不可用数组 index） */
+    id: string;
+    /** 批注正文（多行文本，含换行） */
+    text: string;
+    /** 作者信息（可选） */
+    author?: string;
+    /** 创建时间（epoch ms） */
+    createdAt: number;
+    /** 最近修改时间（epoch ms） */
+    updatedAt: number;
 }
 /** 搜索范围：当前工作表 / 整个工作簿 / 当前选区 */
 export type FindScope = 'sheet' | 'workbook' | 'selection';
@@ -296,6 +316,8 @@ export interface SheetModelData {
     rowOutlines?: DimensionOutline[];
     /** 列分组集合；旧数据缺省视为无分组 */
     columnOutlines?: DimensionOutline[];
+    /** 单元格批注池：按 noteId 存放，cell.noteId 引用之；与 cell value/style 完全独立 */
+    notes?: Record<string, CellNote>;
 }
 export interface SheetState {
     id: string;
@@ -328,6 +350,8 @@ export interface SheetState {
     rowOutlines: DimensionOutline[];
     /** 列分组集合；缺省为空数组 */
     columnOutlines: DimensionOutline[];
+    /** 单元格批注池：按 noteId 存放，cell.noteId 引用之 */
+    notes: Record<string, CellNote>;
 }
 /** 视口区域：冻结窗格将画布划分为四个独立滚动区域 */
 export interface ViewportRegion {