xiaodao-spreader 0.1.19 → 0.1.21

package/dist/types/components/spreader/core/border-pool.d.ts

@@ -0,0 +1,101 @@
+/**
+ * BorderPool — 边框池，用于减少重复边框数据的存储体积。
+ *
+ * 核心思路：
+ *  - 每个 Sheet 维护一个 borders: BorderStyle[] 数组，borders[0] 始终为默认空边框 {}。
+ *  - 单元格样式通过 borderId（数组下标）引用边框，而非内联存储完整边框对象。
+ *  - 相同内容的边框（即使属性顺序不同）自动复用同一 borderId。
+ *  - 已注册的边框对象禁止直接修改（Object.freeze），修改必须创建副本后重新注册。
+ *
+ * 持久化注意：
+ *  - index（Map<string, number>）仅运行时使用，不参与序列化。
+ *  - 序列化时只需输出 borders 数组 + cells 中 style 的 borderId。
+ */
+import type { BorderStyle, BorderSide, CellData, CellStyle } from './types';
+/**
+ * 边框池结构化接口：BorderPool 实例与运行时适配器（如 CoreState 的 borders 数组 + 索引）均可满足。
+ */
+export interface BorderPoolLike {
+    get(borderId: number): BorderStyle;
+    getId(border: BorderStyle): number;
+}
+export declare class BorderPool {
+    /** 边框数组：borders[0] 始终为默认空边框 {} */
+    private borders;
+    /** 运行时去重索引：stableKey → borderId，不参与持久化 */
+    private index;
+    constructor(existingBorders?: BorderStyle[]);
+    /**
+     * 生成稳定的边框 key：对属性名排序后 JSON.stringify。
+     * 保证属性顺序不同但内容相同的边框产生相同的 key。
+     */
+    private stableKey;
+    /**
+     * 根据 borderId 获取边框对象（只读）。
+     * 返回 Object.freeze 冻结的对象，禁止直接修改。
+     */
+    get(borderId: number): BorderStyle;
+    /**
+     * 查找或注册边框，返回对应的 borderId。
+     * 相同内容的边框自动复用已有 id。
+     */
+    getId(border: BorderStyle): number;
+    /** 判断边框是否为空 */
+    private isEmptyBorder;
+    /** 深拷贝边框对象 */
+    private deepCloneBorder;
+    /** 返回 borders 数组的浅拷贝（用于持久化/快照） */
+    getBorders(): BorderStyle[];
+    /** 直接设置 borders 数组（用于恢复快照），同时重建 index */
+    setBorders(borders: BorderStyle[]): void;
+    /**
+     * Border GC（垃圾回收）：
+     * 扫描 styles 中实际使用的 borderId，删除未被引用的 borders，
+     * 重新生成连续的 borderId 并同步更新所有 styles。
+     * borders[0] 始终保留。
+     *
+     * 建议在保存/持久化/导出时调用，不要在每次编辑时执行。
+     */
+    compactBorders(styles: CellStyle[]): BorderStyle[];
+}
+/**
+ * 获取单元格的 BorderSide。
+ * 通过 cell.styleId → style.borderId → borderPool → BorderStyle[side]
+ */
+export declare function getCellBorderSide(cell: CellData | undefined, side: 'top' | 'right' | 'bottom' | 'left', styles: CellStyle[], borderPool: BorderPoolLike): BorderSide | undefined;
+/**
+ * 获取单元格的完整 BorderStyle。
+ */
+export declare function getCellBorder(cell: CellData | undefined, styles: CellStyle[], borderPool: BorderPoolLike): BorderStyle | undefined;
+/**
+ * 设置单元格的某一侧边框。
+ * 读取旧 BorderStyle → 创建副本 → 修改指定边 → 注册到 BorderPool → 更新 style.borderId。
+ * 不会影响其他共享相同 borderId 的单元格。
+ */
+export declare function setCellBorderSide(cell: CellData, side: 'top' | 'right' | 'bottom' | 'left', borderSide: BorderSide | undefined, styles: CellStyle[], borderPool: BorderPoolLike, registerStyle: (style: CellStyle) => number): void;
+/**
+ * 设置单元格的完整边框（四边）。
+ */
+export declare function setCellBorder(cell: CellData, border: BorderStyle, styles: CellStyle[], borderPool: BorderPoolLike, registerStyle: (style: CellStyle) => number): void;
+/**
+ * 清除单元格的边框。
+ */
+export declare function clearCellBorder(cell: CellData, styles: CellStyle[], registerStyle: (style: CellStyle) => number): void;
+/**
+ * 迁移旧版边框数据（borderTopWidth 等）到新的 BorderPool 机制。
+ * 扫描 styles 数组中所有含旧边框属性的样式，转换为 BorderStyle 注册到 BorderPool。
+ */
+export declare function migrateBordersInStyles(styles: CellStyle[]): {
+    styles: CellStyle[];
+    borders: BorderStyle[];
+};
+/**
+ * 清理 merge 内部的边框数据（可选，保存时调用）。
+ * merge 内部 grid cell 的边框在渲染时会被忽略，此函数清理这些冗余数据。
+ */
+export declare function cleanupMergeInternalBorders(cells: Record<string, CellData>, merges: Record<string, {
+    startCol: number;
+    startRow: number;
+    endCol: number;
+    endRow: number;
+}>, styles: CellStyle[], borderPool: BorderPoolLike, cellKey: (c: number, r: number) => string, registerStyle: (style: CellStyle) => number): void;

package/dist/types/components/spreader/core/border-resolve.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Border Resolve — 公共边统一解析。
+ *
+ * 核心函数 resolveSharedBorder 负责处理相邻两个 BorderSide 的冲突，
+ * 产生唯一的最终视觉边框结果。
+ *
+ * 冲突规则（按优先级）：
+ * 1. 两侧都 undefined/空 → 不绘制
+ * 2. 一侧存在、另一侧不存在 → 使用存在的一侧
+ * 3. 两侧都存在：
+ *    a. width 更大者优先
+ *    b. width 相同时：first 侧优先（稳定 tie-break）
+ * 4. merge 不无条件覆盖 cell（firstSource/secondSource 预留但当前不影响优先级）
+ */
+import type { BorderSide, BorderSource } from './types';
+/**
+ * 判断 BorderSide 是否有效（有实际宽度）。
+ */
+export declare function hasBorderSide(border: BorderSide | undefined): boolean;
+/**
+ * 判断 BorderSide 是否为空。
+ */
+export declare function isEmptyBorderSide(border: BorderSide | undefined): boolean;
+/**
+ * 统一解析两个相邻 BorderSide 的冲突，返回最终要绘制的 BorderSide。
+ *
+ * @param first - 第一个候选边框（对于水平公共边：上方 cell 的 bottom；对于垂直公共边：左方 cell 的 right）
+ * @param second - 第二个候选边框（对于水平公共边：下方 cell 的 top；对于垂直公共边：右方 cell 的 left）
+ * @param _firstSource - 第一个候选的来源（'cell' 或 'merge'），预留参数，当前不影响优先级
+ * @param _secondSource - 第二个候选的来源（'cell' 或 'merge'），预留参数，当前不影响优先级
+ * @returns 最终要绘制的 BorderSide，或 undefined（不绘制）
+ *
+ * 规则：
+ * 1. 两侧都空 → undefined
+ * 2. 一侧空 → 另一侧
+ * 3. 两侧都有：
+ *    a. width 更大者优先
+ *    b. width 相同 → first 优先（稳定 tie-break）
+ */
+export declare function resolveSharedBorder(first: BorderSide | undefined, second: BorderSide | undefined, _firstSource?: BorderSource, _secondSource?: BorderSource): BorderSide | undefined;
+/**
+ * 获取公共边的宽度（便捷函数）。
+ */
+export declare function resolveSharedBorderWidth(first: BorderSide | undefined, second: BorderSide | undefined, firstSource?: BorderSource, secondSource?: BorderSource): number;
+/**
+ * 获取公共边的颜色（便捷函数）。
+ */
+export declare function resolveSharedBorderColor(first: BorderSide | undefined, second: BorderSide | undefined, firstSource?: BorderSource, secondSource?: BorderSource): string | undefined;

package/dist/types/components/spreader/core/number-format.d.ts

@@ -94,6 +94,53 @@ export declare function isFormatOverflowsToHashes(format: string | undefined | n
  * 主要用于渲染端直接复用，避免再次 parseNumberFormat。
  */
 export declare function isInvalidDisplayValue(value: string, format: string | undefined | null): boolean;
+/** 最大小数位数（与数字格式对话框一致：0–30） */
+export declare const NF_MAX_DECIMALS = 30;
+/** 最小小数位数 */
+export declare const NF_MIN_DECIMALS = 0;
+/** 判断原始值是否可解析为有限数字（常规格式下的"数值"语义） */
+export declare function isNumericValue(value: string): boolean;
+/**
+ * 判断某单元格（格式 + 值）的小数位数是否可调整：
+ * - 文本 / 日期 / 时间 / 持续时间 → 不支持
+ * - 数值类格式（含数字占位符）→ 支持（与单元格内容无关）
+ * - 常规 → 仅当值可解析为数字时支持（识别为数字格式）
+ */
+export declare function isDecimalsAdjustable(format: string | undefined | null, value: string): boolean;
+/**
+ * 获取单元格当前有效小数位数：
+ * - 常规（含值为数值的常规）→ 0；文本/日期类 → -1（不支持）
+ * - 数值类 → 第一个含数字占位符区段的 decimals（最大允许小数位）
+ */
+export declare function getEffectiveDecimals(format: string | undefined | null, value: string): number;
+/**
+ * 将格式代码调整为指定的小数位数，返回新代码；不支持或越界时返回 null。
+ * - 常规格式：生成纯数值格式（'0' 或 '0.000...'）
+ * - 文本 / 日期 / 时间 / 持续时间：不支持 → null
+ * - 数值类（含百分比/货币/会计/财务/科学计数/多区段自定义）：逐区段调整，纯文本区段保留
+ */
+export declare function adjustNumberFormatDecimals(format: string | undefined | null, target: number): string | null;
+/**
+ * 将任意格式代码归类映射为工具栏下拉的预设值，用于回显：
+ * 增减小数位、对话框改符号/日期/自定义代码等产生的代码不在预设列表中，
+ * 按分类归到对应预设（分类规则与对话框 detectFromCode 一致），无法识别时返回 NF_CUSTOM。
+ * 注意：仅用于显示，不得用于替代真实格式代码存储。
+ */
+export declare function normalizeNumberFormatForDisplay(format: string | undefined | null, locale: string): string;
+/** 日期/时间字符串解析结果：Excel 序列号 + 建议套用的格式代码 */
+export interface DateTimeParseResult {
+    serial: number;
+    format: string;
+}
+/**
+ * 对常规单元格的输入做常见日期/时间/日期时间字符串自动识别（对齐 Excel 输入语义）：
+ * - 日期：yyyy-m-d、yyyy/m/d、yyyy年m月d日、m-d / m/d（年份补当前年）
+ * - 时间：h:mm、h:mm:ss
+ * - 日期时间：上述日期 + 空格或 T + 时间
+ * 识别成功返回序列号 + 建议格式代码（跟随 locale）；不识别返回 null。
+ * 纯数字与公式不会命中；月/日/时/分/秒越界、日期不存在（如 2023-2-29）均不识别。
+ */
+export declare function parseDateTimeInput(input: string, locale: string, now?: Date): DateTimeParseResult | null;
 /** 根据分类 + 小数位数 + 千位分隔符生成格式代码 */
 export declare function buildNumberFormatCode(locale: string, category: NFDialogCategory, decimals: number, thousands: boolean): string;
 /** 构造工具栏下拉框的选项（含「格式…」自定义项） */

package/dist/types/components/spreader/core/style-pool.d.ts

@@ -0,0 +1,84 @@
+/**
+ * StylePool — 样式池，用于减少重复样式数据的存储体积。
+ *
+ * 核心思路：
+ *  - 每个 Sheet 维护一个 styles: CellStyle[] 数组，styles[0] 始终为默认空样式 {}。
+ *  - 单元格通过 styleId（数组下标）引用样式，而非内联存储完整样式对象。
+ *  - 相同内容的样式（即使属性顺序不同）自动复用同一 styleId。
+ *  - 已注册的样式对象禁止直接修改（Object.freeze），修改必须创建副本后重新注册。
+ *
+ * 持久化注意：
+ *  - index（Map<string, number>）仅运行时使用，不参与序列化。
+ *  - 序列化时只需输出 styles 数组 + cells 中的 styleId。
+ */
+import type { CellData, CellStyle } from './types';
+export declare class StylePool {
+    /** 样式数组：styles[0] 始终为默认空样式 {} */
+    private styles;
+    /** 运行时去重索引：stableKey → styleId，不参与持久化 */
+    private index;
+    constructor(existingStyles?: CellStyle[]);
+    /**
+     * 生成稳定的样式 key：对属性名排序后 JSON.stringify。
+     * 保证属性顺序不同但内容相同的样式产生相同的 key。
+     */
+    private stableKey;
+    /**
+     * 根据 styleId 获取样式对象（只读）。
+     * 返回 Object.freeze 冻结的对象，禁止直接修改。
+     */
+    get(styleId: number): CellStyle;
+    /**
+     * 查找或注册样式，返回对应的 styleId。
+     * 相同内容的样式自动复用已有 id。
+     */
+    getId(style: CellStyle): number;
+    /** 返回 styles 数组的浅拷贝（用于持久化/快照） */
+    getStyles(): CellStyle[];
+    /** 直接设置 styles 数组（用于恢复快照），同时重建 index */
+    setStyles(styles: CellStyle[]): void;
+    /**
+     * Style GC（垃圾回收）：
+     * 扫描 cells 中实际使用的 styleId，删除未被引用的 styles，
+     * 重新生成连续的 styleId 并同步更新所有 cells。
+     * styles[0] 始终保留。
+     *
+     * 建议在保存/持久化/导出时调用，不要在每次编辑时执行。
+     */
+    compactStyles(cells: Record<string, CellData>): CellStyle[];
+}
+/**
+ * 解析单元格样式：根据 styleId 从 styles 数组中获取样式对象。
+ * styleId 不存在或为 0 时返回 null（表示默认样式）。
+ */
+export declare function resolveStyle(cell: CellData | undefined, styles: CellStyle[]): CellStyle | null;
+/**
+ * 统一的单元格样式修改：读取旧样式 → 创建副本 → 合并 patch → 注册到 StylePool → 更新 styleId。
+ * 不会影响其他共享相同 styleId 的单元格。
+ */
+export declare function updateCellStyle(cell: CellData, patch: Record<string, unknown>, pool: StylePool): void;
+/**
+ * 删除单元格的某个样式属性。
+ */
+export declare function unsetCellStyle(cell: CellData, key: string, pool: StylePool): void;
+/**
+ * 批量修改多个单元格的样式。
+ */
+export declare function updateCellsStyle(cells: CellData[], patch: Record<string, unknown>, pool: StylePool): void;
+/**
+ * 一次性迁移旧格式 cells（{value, style}）到新格式（{value, styleId}）。
+ * 扫描所有 cells，对 style 去重，创建 styles[]，将 cell.style 转换为 cell.styleId。
+ * 迁移前后视觉效果和数据语义完全一致。
+ */
+export declare function migrateCells(oldCells: Record<string, {
+    value: string;
+    style?: Record<string, unknown> | null;
+    styleId?: number;
+}>): {
+    cells: Record<string, CellData>;
+    styles: CellStyle[];
+};
+/**
+ * 深拷贝 cells（同时保留 styleId 引用）。
+ */
+export declare function cloneCells(src: Record<string, CellData>): Record<string, CellData>;

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

@@ -8,9 +8,57 @@ export interface SelectionRange {
     endCol: number;
     endRow: number;
 }
+/** 单边边框 */
+export interface BorderSide {
+    width?: number;
+    color?: string;
+    style?: string;
+}
+/** 四边边框组合 */
+export interface BorderStyle {
+    top?: BorderSide;
+    right?: BorderSide;
+    bottom?: BorderSide;
+    left?: BorderSide;
+}
+/** 边框来源标识 */
+export type BorderSource = 'cell' | 'merge';
+/** 单元格样式：所有属性均为可选，方便后续扩展数字格式、边框、字体、填充、对齐等 */
+export interface CellStyle {
+    fontFamily?: string;
+    fontSize?: number | string;
+    fontWeight?: string;
+    fontStyle?: string;
+    underline?: string;
+    strikethrough?: string;
+    color?: string;
+    backgroundColor?: string;
+    textAlign?: string;
+    verticalAlign?: string;
+    wrap?: string;
+    borderId?: number;
+    /** @deprecated 旧版边框属性，兼容历史数据使用，新代码请通过 borderId 访问 */
+    borderTopWidth?: number;
+    /** @deprecated 旧版边框属性，兼容历史数据使用，新代码请通过 borderId 访问 */
+    borderBottomWidth?: number;
+    /** @deprecated 旧版边框属性，兼容历史数据使用，新代码请通过 borderId 访问 */
+    borderLeftWidth?: number;
+    /** @deprecated 旧版边框属性，兼容历史数据使用，新代码请通过 borderId 访问 */
+    borderRightWidth?: number;
+    /** @deprecated 旧版边框颜色，兼容历史数据使用，新代码请通过 BorderStyle.color 访问 */
+    borderColor?: string;
+    numberFormat?: string;
+    /**
+     * 数字格式分类标记：'custom' 表示该格式由「增加/减少小数位数」等操作在常规单元格上自动生成，
+     * 下拉/对话框应按「自定义」展示。仅存标记，渲染不受影响。
+     */
+    numberFormatCategory?: 'custom';
+    [key: string]: unknown;
+}
+/** 单元格数据：value 始终为 string，样式通过 styleId 引用表格级 styles 池 */
 export interface CellData {
     value: string;
-    style: Record<string, unknown> | null;
+    styleId?: number;
 }
 /** 搜索范围：当前工作表 / 整个工作簿 / 当前选区 */
 export type FindScope = 'sheet' | 'workbook' | 'selection';
@@ -33,14 +81,20 @@ export interface SpreadsheetOptions {
 export interface SpreadsheetData {
     [cellRef: string]: {
         value: string;
-        style?: Record<string, unknown>;
+        styleId?: number;
+        style?: CellStyle;
     };
 }
 export interface SheetModelData {
     name: string;
+    /** 表格级样式池：styles[0] 始终为默认空样式 {} */
+    styles?: CellStyle[];
+    /** 表格级边框池：borders[0] 始终为默认空边框 {} */
+    borders?: BorderStyle[];
     cells: Record<string, {
         value: string;
-        style?: Record<string, unknown>;
+        styleId?: number;
+        style?: CellStyle;
     }>;
     merges?: Record<string, SelectionRange>;
     colWidths?: Record<number, number>;
@@ -50,6 +104,10 @@ export interface SheetState {
     id: string;
     name: string;
     cells: Record<string, CellData>;
+    /** 表格级样式池：styles[0] 始终为默认空样式 {} */
+    styles: CellStyle[];
+    /** 表格级边框池：borders[0] 始终为默认空边框 {} */
+    borders: BorderStyle[];
     merges: Record<string, SelectionRange>;
     selection: SelectionRange | null;
     activeCell: CellCoord;
@@ -60,6 +118,8 @@ export interface SheetState {
 }
 export interface UndoSnapshot {
     cells: Record<string, CellData>;
+    styles: CellStyle[];
+    borders: BorderStyle[];
     colWidths: number[];
     rowHeights: (number | undefined)[];
 }

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

@@ -1,4 +1,5 @@
 import Spreader from './components/spreader.vue';
 export default Spreader;
 export { Spreader };
-export type { CellCoord, SelectionRange, CellData, Range, SpreadsheetOptions, SpreadsheetData, SheetModelData, SheetState, UndoSnapshot, ContextMenuItem, ThemeColors, Point, } from './core/types';
+export type { CellCoord, SelectionRange, CellData, CellStyle, BorderStyle, BorderSide, BorderSource, Range, SpreadsheetOptions, SpreadsheetData, SheetModelData, SheetState, UndoSnapshot, ContextMenuItem, ThemeColors, Point, } from './core/types';
+export { StylePool, resolveStyle, migrateCells, cloneCells } from './core/style-pool';

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
 export { default, Spreader } from './components/spreader';
-export type { CellCoord, SelectionRange, CellData, Range, SpreadsheetOptions, SpreadsheetData, SheetModelData, SheetState, UndoSnapshot, ContextMenuItem, ThemeColors, Point, } from './components/spreader';
+export type { CellCoord, SelectionRange, CellData, CellStyle, BorderStyle, BorderSide, BorderSource, Range, SpreadsheetOptions, SpreadsheetData, SheetModelData, SheetState, UndoSnapshot, ContextMenuItem, ThemeColors, Point, } from './components/spreader';