xiaodao-spreader 0.1.34 → 0.1.35

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 } from '../core/types';
+import type { CellCoord, CellData, CellStyle, SelectionRange, BorderStyle, BorderSide, FreezePane, ViewportRegion, SheetFilter, FilterColumn, ConditionalFormattingRule, ConditionalFormattingFormat, DataValidationRule, DataValidationResult, DataValidationSeverity } from '../core/types';
 import { type FilterCandidates } from '../core/filter-core';
 /** 选区触发方式，影响「合并单元格是否扩大选区」。
  *  - 'cell'：单元格点击/拖动（默认）→ 保持现有 expandSelectionForMerges 行为
@@ -9,6 +9,20 @@ import { type FilterCandidates } from '../core/filter-core';
  *  - 'all' ：左上角全选按钮 → expandSelectionForMerges 行为
  */
 export type SelectionMode = 'cell' | 'row' | 'col' | 'all';
+/** 数据验证出错警告的用户选择：
+ *  - 'continue'：确认继续（写入非法值）；
+ *  - 'retry'  ：返回编辑态修正（stop 专用）；
+ *  - 'cancel' ：放弃本次输入（不写入）。
+ */
+export type DataValidationAlertAction = 'continue' | 'retry' | 'cancel';
+/** 出错警告弹窗需要展示的信息 */
+export interface DataValidationAlertPayload {
+    severity: DataValidationSeverity;
+    title: string;
+    message: string;
+    col: number;
+    row: number;
+}
 /** AutoFill 拖拽状态 */
 export interface AutoFillState {
     active: boolean;
@@ -157,7 +171,9 @@ export interface CoreState {
     setCellValue: (c: number, r: number, v: string | null | undefined) => void;
     clearCellsInRange: (cS: number, cE: number, rS: number, rE: number) => void;
     startEdit: (initialValue?: string) => void;
-    commitEdit: () => void;
+    /** 提交编辑：数据验证发生在写入之前。
+     *  @returns Promise<boolean> —— true 表示已写入；false 表示被数据验证拦截（仍保持编辑态） */
+    commitEdit: () => Promise<boolean>;
     cancelEdit: () => void;
     moveActive: (dC: number, dR: number) => void;
     ensureVisible: (c: number, r: number) => void;
@@ -203,6 +219,69 @@ export interface CoreState {
     clampScroll?: (sx: number | null, sy: number | null) => void;
     /** 查找高亮钩子：返回某单元格当前的高亮类型（由 find-replace 模块注入） */
     findHighlight?: (col: number, row: number) => 'active' | 'match' | null;
+    /** 当前工作表的全部数据验证规则（规则属于 Sheet，不属于 Cell） */
+    dataValidations: DataValidationRule[];
+    /** 命中该单元格的全部规则（经空间索引，不遍历整表） */
+    getDataValidationRules: (row: number, col: number) => DataValidationRule[];
+    /** 命中该单元格的首条规则（用于「打开数据验证对话框」时回填已有规则） */
+    getDataValidationRule: (row: number, col: number) => DataValidationRule | null;
+    hasDataValidation: (row: number, col: number) => boolean;
+    /** 命中且需要显示下拉箭头的 list 规则 */
+    getListValidation: (row: number, col: number) => DataValidationRule | null;
+    /** 下拉列表数据（去重、跟随源区域变化） */
+    getValidationDropdown: (row: number, col: number) => {
+        rule: DataValidationRule;
+        items: string[];
+    } | null;
+    /** 选中单元格时展示的输入信息 */
+    getValidationInputMessage: (row: number, col: number) => {
+        title: string;
+        message: string;
+    } | null;
+    /** 核心校验入口：编辑 / 粘贴 / AutoFill 等所有输入链路统一调用 */
+    validateCell: (row: number, col: number, value: string | null | undefined) => DataValidationResult;
+    /** 批量校验（粘贴 / 填充等原子操作）：返回最严重的那条失败结果 */
+    validateCells: (entries: {
+        col: number;
+        row: number;
+        value: string | null | undefined;
+    }[]) => DataValidationResult;
+    /** 新建规则（一个完整的规则级 Undo） */
+    createDataValidation: (rule: DataValidationRule, opts?: {
+        silent?: boolean;
+    }) => DataValidationRule;
+    /** 更新既有规则（按 id），不存在则视为新建 */
+    updateDataValidation: (id: string, patch: Partial<DataValidationRule>, opts?: {
+        silent?: boolean;
+    }) => void;
+    removeDataValidation: (id: string, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** 清除指定范围的验证（规则的 Range 会被拆分/缩小）；range 为 null 时清除整个工作表 */
+    clearDataValidation: (range: SelectionRange | null, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** 与给定矩形相交的规则（复制携带规则时用） */
+    getDataValidationsInRange: (range: SelectionRange) => {
+        rule: DataValidationRule;
+        range: SelectionRange;
+    }[];
+    /** 将一批规则应用到目标矩形（先扣除目标区域已有规则，再写入） */
+    applyDataValidationsToRange: (rules: DataValidationRule[], target: SelectionRange, opts?: {
+        silent?: boolean;
+    }) => void;
+    /** 规则集合 / 源区域数据变化后失效索引与列表缓存 */
+    invalidateDataValidationCache: () => void;
+    /** 出错警告弹窗是否打开（编辑器 blur 提交需要避让，避免重入） */
+    isValidationAlertOpen: () => boolean;
+    /** 出错警告弹窗钩子（由 spreader.vue 注入；未注入时按「stop 拒绝 / 其它放行」处理） */
+    showValidationAlert?: (payload: DataValidationAlertPayload) => Promise<DataValidationAlertAction>;
+    /** 复用出错警告流程：传入校验失败结果，返回用户决策（供下拉选择等非编辑器入口调用） */
+    confirmInvalidValue: (res: DataValidationResult, col: number, row: number) => Promise<DataValidationAlertAction>;
+    /** 按 id 或名称取其它工作表的 cells（list 跨表引用，由 spreader.vue 注入） */
+    getSheetCellsById?: (sheetId: string) => Record<string, CellData> | null;
+    /** 请求打开「数据验证」对话框（由 spreader.vue 注入，供右键菜单 / 工具栏使用） */
+    requestDataValidationDialog?: () => void;
     /** AutoFill 拖拽状态：active 时 render 绘制预览，mouseup 触发 applyAutoFill */
     autoFillState: Ref<AutoFillState>;
     /** 一次性提交 AutoFill：saveUndo → ensureCapacity → applyAutoFillPlan → 写入 cells + formulaDeps → selectRange → scheduleRender */

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

@@ -3,7 +3,20 @@ import type { CoreState } from './core-state';
 import type { UndoStylesState } from './undo-styles';
 import type { BordersMergeState } from './borders-merge';
 import type { SheetsOpsState } from './sheets-ops';
-import type { ContextMenuItem } from '../core/types';
+import type { ContextMenuItem, DataValidationRule } from '../core/types';
+/** 数据验证下拉弹窗状态：anchor 为单元格在视口中的位置（client 坐标） */
+export interface ValidationDropdownState {
+    col: number;
+    row: number;
+    rule: DataValidationRule;
+    items: string[];
+    /** 当前单元格原始值（用于标记选中项） */
+    current: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 export interface InteractionsState {
     scheduleRender: () => void;
     render: () => void;
@@ -47,6 +60,15 @@ export interface InteractionsState {
     isFilterButtonHit: (x: number, y: number) => number;
     openFilterPopup: (col: number) => void;
     closeFilterPopup: () => void;
+    validationDropdown: Ref<ValidationDropdownState | null>;
+    /** 屏幕坐标（client）是否命中某单元格的下拉箭头；命中返回该单元格坐标（合并格返回左上角） */
+    isValidationDropdownHit: (x: number, y: number) => {
+        col: number;
+        row: number;
+    } | null;
+    openValidationDropdown: (col: number, row: number) => boolean;
+    closeValidationDropdown: () => void;
+    onValidationDropdownSelect: (value: string) => void;
     dimInputRef: Ref<HTMLInputElement | null>;
     dimPanel: Ref<{
         type: 'row' | 'col';

package/dist/types/components/spreader/core/data-validation.d.ts

@@ -0,0 +1,119 @@
+import type { CellData, SelectionRange, DataValidationRule, DataValidationResult, DataValidationOperator, DataValidationSeverity } from './types';
+/** 数据验证求值上下文（由 core-state 注入，引擎本身保持纯净） */
+export interface DataValidationContext {
+    /** 当前工作表原始单元格数据（供公式引擎引用） */
+    cells: Record<string, CellData>;
+    colCount: number;
+    rowCount: number;
+    locale: string;
+    /** 取单元格计算后的值（公式已求值） */
+    getCellValue: (col: number, row: number) => string;
+    /** 按 id 或名称取其它工作表的 cells；用于 list 类型跨表引用。取不到返回 null */
+    getSheetCells?: (sheetId: string) => Record<string, CellData> | null;
+}
+/** 生成稳定唯一 ID（供新建规则使用，禁止依赖数组 index） */
+export declare function genDataValidationId(): string;
+/** 单元格是否落在任一应用范围之内（含边界） */
+export declare function dvCellInRanges(ranges: SelectionRange[], col: number, row: number): boolean;
+/** 规则范围左上角（所有 ranges 的最小 startCol/startRow），作为相对引用的基准 */
+export declare function dvRuleAnchor(rule: DataValidationRule): {
+    col: number;
+    row: number;
+};
+/**
+ * 空值判定：null / undefined / '' / 纯空白 均视为空。
+ * 与「不存在的单元格」在业务上等价（本项目单元格缺省即空字符串）。
+ */
+export declare function isBlankValue(value: unknown): boolean;
+/** 文本长度：按 Unicode 码点统计（中文 / Emoji 不会像 UTF-16 那样被算成 2） */
+export declare function dvTextLength(value: string): number;
+/**
+ * 将「操作数」（单元格输入值或规则条件值）解析为数值。
+ * - 前导 '=' 视为公式，求值后取数值结果（如 =TODAY()）；公式错误返回 null；
+ * - 复用项目 parseNumericText 处理千分位 / 百分比 / 货币符号；
+ * - 其余走严格数值正则，避免 Number('0x10') 之类的误判。
+ */
+export declare function parseNumericOperand(raw: string, ctx: DataValidationContext): number | null;
+/**
+ * 将操作数解析为「日期序列号」。
+ * - 纯数值 → 直接作为序列号（Excel 日期序列）；
+ * - 日期/日期时间字符串 → 复用项目 parseDateTimeInput（与单元格输入识别同源）；
+ * - 纯时间字符串（如 12:30）不属于日期 → null。
+ */
+export declare function parseDateOperand(raw: string, ctx: DataValidationContext): number | null;
+/**
+ * 将操作数解析为「时间」（一天的分数，0 <= x < 1）。
+ * - 纯时间字符串 → 复用 parseDateTimeInput；
+ * - 日期时间字符串 → 取小数部分；
+ * - 数值 → 取小数部分（Excel 时间即序列的小数部分）。
+ */
+export declare function parseTimeOperand(raw: string, ctx: DataValidationContext): number | null;
+/** 通用比较：op 作用于 (value, v1[, v2])；操作数解析失败或比较数缺失一律视为不通过（返回 false） */
+export declare function compareWithOperator(op: DataValidationOperator, value: number, v1: number | null, v2: number | null): boolean;
+/**
+ * 解析 list 规则的候选项（去重、保序）。
+ * - values：直接使用常量列表；
+ * - range：读取目标区域（默认当前表，可通过 sheetId 跨表），空单元格按 allowBlank 决定是否保留。
+ * 本函数不做缓存（缓存与失效由调用方 core-state 负责）。
+ */
+export declare function resolveListItems(rule: DataValidationRule, ctx: DataValidationContext): string[];
+/** list 规则是否显示单元格内下拉箭头 */
+export declare function hasDropdownIndicator(rule: DataValidationRule | null | undefined): boolean;
+/** 单条规则求值：value 为待写入的原始文本（不含隐式类型转换），col/row 为目标单元格坐标 */
+export declare function evaluateDataValidationRule(rule: DataValidationRule, value: string | null | undefined, col: number, row: number, ctx: DataValidationContext): boolean;
+/** errorStyle → severity（未配置默认 stop） */
+export declare function dvSeverityOf(rule: DataValidationRule): DataValidationSeverity;
+/**
+ * 校验某个单元格的候选值。
+ * 规则：命中范围内的**所有**规则必须全部通过（rules.every）；
+ * 失败时取严重级别最高（stop > warning > information）的那条规则生成提示。
+ */
+export declare function validateCellValue(value: string | null | undefined, col: number, row: number, rules: DataValidationRule[], ctx: DataValidationContext): DataValidationResult;
+/**
+ * 生成默认错误提示文案（用户未自定义 title/message 时使用）。
+ * 文案按类型描述约束条件，便于用户理解「为什么非法」。
+ */
+export declare function defaultDataValidationText(rule: DataValidationRule, locale: string): {
+    title: string;
+    message: string;
+};
+/**
+ * 数据验证规则空间索引。
+ * - rebuild(rules)：重建（随规则变化调用，成本 O(区域总数)）；
+ * - getRules(col,row)：返回命中该单元格且启用的规则列表。
+ */
+export declare class DataValidationIndex {
+    private bands;
+    private dirty;
+    private source;
+    constructor(rules?: DataValidationRule[]);
+    /** 规则集合发生变化（增/删/改/切表/撤销恢复）后调用 */
+    invalidate(): void;
+    private ensure;
+    /** 命中该单元格的规则（保持源数组顺序） */
+    getRules(col: number, row: number, rules?: DataValidationRule[]): DataValidationRule[];
+    /** 该单元格是否存在任何数据验证 */
+    has(col: number, row: number, rules?: DataValidationRule[]): boolean;
+    /**
+     * 命中该单元格且满足 predicate 的首条规则。
+     * 渲染热路径（每格判定是否画下拉箭头）专用：不分配数组，零垃圾。
+     */
+    findRule(col: number, row: number, predicate: (rule: DataValidationRule) => boolean, rules?: DataValidationRule[]): DataValidationRule | null;
+    /** 取某坐标所在行带的候选条目（必要时先重建索引） */
+    private bandsOf;
+}
+/** 删除带（axis='row' 删行 / 'col' 删列）后收缩单个 Range；整段落在删除带内返回 null */
+export declare function adjustDvRangeForDelete(r: SelectionRange, axis: 'row' | 'col', idx: number, count: number): SelectionRange | null;
+/** 插入带（axis='row' 插行 / 'col' 插列）后放大单个 Range */
+export declare function adjustDvRangeForInsert(r: SelectionRange, axis: 'row' | 'col', idx: number, count: number): SelectionRange;
+/** 规则区域是否与给定矩形相交 */
+export declare function dvRangeIntersects(a: SelectionRange, b: SelectionRange): boolean;
+/**
+ * 从规则中扣除给定矩形（用于「清除所选区域的验证」）：
+ * 支持矩形差集拆分，剩余为空时返回空数组。
+ */
+export declare function subtractDvRange(range: SelectionRange, cut: SelectionRange): SelectionRange[];
+/** 平移规则的某个区域（复制粘贴携带规则时使用） */
+export declare function translateDvRange(r: SelectionRange, dCol: number, dRow: number): SelectionRange;
+/** 求两个矩形的交集；不相交返回 null */
+export declare function intersectDvRange(a: SelectionRange, b: SelectionRange): SelectionRange | null;

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

@@ -190,6 +190,68 @@ export interface ConditionalFormattingRule {
     /** 是否启用 */
     enabled: boolean;
 }
+/** 数据验证类型（对齐 Excel：整数 / 小数 / 列表 / 日期 / 时间 / 文本长度 / 自定义） */
+export type DataValidationType = 'any' | 'list' | 'wholeNumber' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+/** 条件运算符（数值 / 日期 / 时间 / 文本长度通用） */
+export type DataValidationOperator = 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual';
+/** 出错警告样式：停止（拒绝提交）/ 警告（可确认继续）/ 信息（提示后由用户决定） */
+export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
+/** 下拉列表数据源：
+ *  - values：直接输入的逗号分隔常量列表；
+ *  - range：引用工作表区域（可跨表），支持动态列表（区域数据变化时下拉项同步更新）。
+ */
+export type DataValidationListSource = {
+    type: 'values';
+    values: string[];
+} | {
+    type: 'range';
+    range: SelectionRange; /** 目标工作表 id 或名称；缺省表示当前工作表 */
+    sheetId?: string;
+};
+/** 单条数据验证规则：属于 Sheet 而非 Cell；仅描述「输入约束 + UI 行为」，不写入 cell style */
+export interface DataValidationRule {
+    /** 稳定唯一 ID（禁止数组 index） */
+    id: string;
+    /** 应用范围（支持多区域） */
+    ranges: SelectionRange[];
+    type: DataValidationType;
+    operator?: DataValidationOperator;
+    /** 条件值 1（between/notBetween 时为下界） */
+    formula1?: string;
+    /** 条件值 2（between/notBetween 时为上界） */
+    formula2?: string;
+    /** list 类型的数据源（优先于 values） */
+    listSource?: DataValidationListSource;
+    /** 兼容字段：list + 常量列表时与 listSource.values 保持同步 */
+    values?: string[];
+    /** 忽略空值（默认 true） */
+    allowBlank?: boolean;
+    /** list 类型是否显示单元格内下拉箭头（默认 true） */
+    showDropdown?: boolean;
+    /** 选中单元格时显示输入信息（默认 false） */
+    showInputMessage?: boolean;
+    inputTitle?: string;
+    inputMessage?: string;
+    /** 无效数据时显示错误警告（默认 true） */
+    showErrorMessage?: boolean;
+    /** 出错警告样式（默认 stop） */
+    errorStyle?: DataValidationErrorStyle;
+    errorTitle?: string;
+    errorMessage?: string;
+    /** 是否启用（默认 true） */
+    enabled?: boolean;
+}
+/** 单条规则的验证结果严重级别（与 errorStyle 对应） */
+export type DataValidationSeverity = 'stop' | 'warning' | 'information';
+/** 数据验证结果：valid=false 时携带最严重的那条失败规则与提示文案 */
+export interface DataValidationResult {
+    valid: boolean;
+    /** 命中的失败规则（多条失败时取严重级别最高的一条） */
+    rule?: DataValidationRule;
+    severity?: DataValidationSeverity;
+    title?: string;
+    message?: string;
+}
 export interface SheetModelData {
     name: string;
     /** 表格级样式池：styles[0] 始终为默认空样式 {} */
@@ -214,6 +276,8 @@ export interface SheetModelData {
     filter?: SheetFilter;
     /** 条件格式规则集合；缺省视为无规则 */
     conditionalFormats?: ConditionalFormattingRule[];
+    /** 数据验证规则集合；旧数据缺省视为无数据验证 */
+    dataValidations?: DataValidationRule[];
 }
 export interface SheetState {
     id: string;
@@ -240,6 +304,8 @@ export interface SheetState {
     filter: SheetFilter | null;
     /** 条件格式规则集合；缺省为空数组 */
     conditionalFormats: ConditionalFormattingRule[];
+    /** 数据验证规则集合；缺省为空数组 */
+    dataValidations: DataValidationRule[];
 }
 /** 视口区域：冻结窗格将画布划分为四个独立滚动区域 */
 export interface ViewportRegion {

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

@@ -1,5 +1,6 @@
 import Spreader from './components/spreader.vue';
 export default Spreader;
 export { Spreader };
-export type { CellCoord, SelectionRange, CellData, CellStyle, BorderStyle, BorderSide, BorderSource, 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, DataValidationRule, DataValidationType, DataValidationOperator, DataValidationErrorStyle, DataValidationListSource, DataValidationResult, DataValidationSeverity, ConditionalFormattingRule, ConditionalFormattingCondition, ConditionalFormattingFormat, } from './core/types';
+export { validateCellValue, evaluateDataValidationRule, resolveListItems, DataValidationIndex, genDataValidationId, } from './core/data-validation';
 export { StylePool, resolveStyle, migrateCells, cloneCells } from './core/style-pool';