xiaodao-spreader 0.1.10 → 0.1.12

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

@@ -0,0 +1,100 @@
+export declare const NF_CUSTOM = "__nf_custom__";
+export declare const NF_MIXED = "\u0001";
+export declare const NF_GENERAL = "";
+export declare const NF_TEXT = "@";
+/**
+ * formatNumber 的特殊返回值：表示"当前格式+数值组合在 Excel 语义下非法"，
+ * 例如 date 格式 序列号<0/≥2958466、duration 格式 序列号<0。
+ * 渲染端必须把该字符串按列宽替换为连续 '#' 填充（不显示此标识符本身）。
+ */
+export declare const NF_INVALID_VALUE = "__NF_INVALID__";
+/** Excel 1900 日期系统最大合法序列号（对应 9999-12-31）。超过或为负 → 整格 ###。 */
+export declare const EXCEL_DATE_MAX_SERIAL = 2958465;
+/** Excel 1900 日期系统最小合法序列号（0 = 1900-01-00，作为下界兜底，实际 UI 一般从 1 开始）。 */
+export declare const EXCEL_DATE_MIN_SERIAL = 0;
+/** 判断格式代码是否为 General（含空串、undefined、'General'、'GENERAL' 等） */
+export declare function isGeneralFormat(format: string | undefined | null): boolean;
+export type NFKind = 'general' | 'text' | 'number' | 'date' | 'duration';
+export interface NFSection {
+    /** 是否含有数字占位符（0/#/?）；无占位符的区段视为纯文本字面量 */
+    hasDigits: boolean;
+    /** 小数最大位数（0/#/? 的总数） */
+    decimals: number;
+    /** 强制小数位数（0 的个数，决定尾随 0 的数量） */
+    minDecimals: number;
+    /** 整数部分强制最少位数（0 的个数） */
+    minIntDigits: number;
+    /** 是否使用千位分隔符 */
+    thousands: boolean;
+    /** 缩放倍数（百分比为 100） */
+    scale: number;
+    /** 科学计数法 */
+    scientific: boolean;
+    /** 数字前的字面量（货币符号等） */
+    prefix: string;
+    /** 数字后的字面量（如 %） */
+    suffix: string;
+    /** 区段颜色（[Red] 等，渲染层可忽略） */
+    color?: string;
+}
+export type NFDateTokenType = 'literal' | 'year' | 'month' | 'monthName' | 'day' | 'weekday' | 'hour' | 'minute' | 'second' | 'ampm';
+export interface NFToken {
+    type: NFDateTokenType;
+    /** literal 类型的原始文本 */
+    text?: string;
+    /** 占位符长度（如 yyyy → 4） */
+    len: number;
+}
+export interface NFParsed {
+    kind: NFKind;
+    /** 数值区段（number 类型使用；可能含正/负/零/文本多个区段） */
+    sections: NFSection[];
+    /** 日期/时间/持续时间的 token 序列 */
+    tokens: NFToken[];
+    /** 是否为持续时间（含 [h]/[mm]/[ss]） */
+    isDuration: boolean;
+    raw: string;
+}
+export interface NFOption {
+    label: string;
+    value: string;
+}
+export declare function parseNumberFormat(format: string): NFParsed;
+/** 清空解析缓存（主要用于测试/资源释放） */
+export declare function clearNumberFormatCache(): void;
+/**
+ * 将单元格原始字符串值按格式代码格式化为显示文本。
+ * 绝不修改传入的 value。
+ */
+export declare function formatNumber(value: string, format: string | undefined | null, locale: string): string;
+export type NFDialogCategory = 'general' | 'number' | 'currency' | 'currencyRounded' | 'accounting' | 'financial' | 'percent' | 'scientific' | 'date' | 'time' | 'dateTime' | 'duration' | 'text' | 'custom';
+export declare const NF_DIALOG_CATEGORIES: NFDialogCategory[];
+/**
+ * 判断单元格在「未指定水平对齐」时，是否应该按「数值」默认右对齐显示。
+ * 规则（与 Excel 对齐语义保持一致，仅用于显示，不写入存储）：
+ *   1. 格式代码为 '@'（文本）→ 否，保持左对齐
+ *   2. 常规格式（含空串 / undefined / 'General'）：对原始 value 做 Number() 解析，
+ *      能解析为有限数字且非空字符串 → 视为数值 → 右对齐
+ *   3. 显式设置为数值类格式（number/currency/currencyRounded/accounting/financial/
+ *      percent/scientific 以及 custom 中分类属于数值 kind 并含数字占位符）→ 右对齐
+ *   4. 日期、时间、日期时间、持续时间 → 不算数值（按 Excel 默认左对齐或居中，这里保持左对齐默认）
+ *   5. 其他 custom 中无法判断的 → 回退左对齐
+ */
+export declare function shouldAlignRightByDefault(value: string, format: string | undefined | null): boolean;
+/**
+ * 当前格式在列宽不足时，是否按 Excel 规则替换为连续 '#' 填充：
+ * - General / 文本 '@' / 未设置 → 不会（General 自动科学计数或允许裁切；文本就是原样裁切）
+ * - date / duration 类格式 → 是
+ * - number 类格式且含有数字占位符 → 是
+ * - 纯文本区段的自定义 number（如"前缀"无 0/#/?）→ 按纯文本，不需要 #
+ */
+export declare function isFormatOverflowsToHashes(format: string | undefined | null): boolean;
+/**
+ * 对给定 (value, format) 快速判断是否是 Excel 语义下的"非法值"（需要渲染为 # 填充）。
+ * 主要用于渲染端直接复用，避免再次 parseNumberFormat。
+ */
+export declare function isInvalidDisplayValue(value: string, format: string | undefined | null): boolean;
+/** 根据分类 + 小数位数 + 千位分隔符生成格式代码 */
+export declare function buildNumberFormatCode(locale: string, category: NFDialogCategory, decimals: number, thousands: boolean): string;
+/** 构造工具栏下拉框的选项（含「格式…」自定义项） */
+export declare function buildNumberFormatPresets(locale: string): NFOption[];