@4399ywkf/editor 0.4.3 → 0.5.0

package/dist/xlsx.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Univer 快照的结构化镜像。
+ *
+ * 为什么不直接 `import type { IWorkbookData } from "@univerjs/core"`：
+ * 那是**可选 peer**。没装 `@univerjs/presets` 的项目一解析不到这个模块，
+ * 整个包的 typecheck 就红了 —— 而「拿快照出 xlsx」恰恰是最不该逼人装 871KB
+ * 渲染引擎的场景（服务端定时导出、Node 里跑批都只有 JSON）。
+ *
+ * 所以这里只声明导出真正读到的字段，字段名与取值语义和 `@univerjs/core`
+ * 逐一对齐。Univer 加字段不会影响这里；改字段含义会 —— 那种时候本文件是
+ * 唯一需要改的地方。
+ */
+type CellValue = string | number | boolean;
+interface ColorStyle {
+    /** `#RRGGBB` / `rgb(r,g,b)` / `rgba(r,g,b,a)` */
+    rgb?: string | null;
+    /** 主题色 token。xlsx 侧解析不了，直接忽略 */
+    th?: number;
+}
+/** 下划线 / 删除线 / 上划线 */
+interface TextDecorationData {
+    /** 0 关 1 开 */
+    s?: number;
+    cl?: ColorStyle | null;
+    t?: number;
+}
+interface BorderStyleData {
+    /** 对齐 `BorderStyleTypes` */
+    s?: number;
+    cl?: ColorStyle | null;
+}
+interface BorderData {
+    t?: BorderStyleData | null;
+    r?: BorderStyleData | null;
+    b?: BorderStyleData | null;
+    l?: BorderStyleData | null;
+}
+interface TextRotation {
+    /** 角度，-90 ~ 90，正数逆时针 */
+    a?: number;
+    /** 1 = 竖排 */
+    v?: number;
+}
+interface StyleData {
+    /** fontFamily */
+    ff?: string | null;
+    /** fontSize，pt */
+    fs?: number;
+    /** italic */
+    it?: number;
+    /** bold */
+    bl?: number;
+    /** underline */
+    ul?: TextDecorationData | null;
+    /** strikethrough */
+    st?: TextDecorationData | null;
+    /** overline —— xlsx 没有对应表达 */
+    ol?: TextDecorationData | null;
+    /** background */
+    bg?: ColorStyle | null;
+    /** border */
+    bd?: BorderData | null;
+    /** font color */
+    cl?: ColorStyle | null;
+    /** 上下标 */
+    va?: number | null;
+    /** 数字格式 */
+    n?: {
+        pattern?: string;
+    } | null;
+    /** textRotation */
+    tr?: TextRotation | null;
+    /** horizontalAlign */
+    ht?: number | null;
+    /** verticalAlign */
+    vt?: number | null;
+    /** wrapStrategy */
+    tb?: number | null;
+}
+/** 富文本单元格。导出只取纯文本 —— xlsx 的富文本要拆成 `<si><r>` 段，收益不抵复杂度 */
+interface RichTextData {
+    body?: {
+        dataStream?: string;
+    } | null;
+}
+interface CellData {
+    v?: CellValue | null;
+    /** 对齐 `CellValueType` */
+    t?: number | null;
+    /** 原始公式，含前导 `=` */
+    f?: string | null;
+    /** 共享公式组 id。同组里只有一个单元格带 `f` */
+    si?: string | null;
+    /** 数组公式的引用范围 */
+    ref?: string | null;
+    /** 样式 id 或内联样式 */
+    s?: StyleData | string | null;
+    /** 富文本 */
+    p?: RichTextData | null;
+}
+interface RowData {
+    /** 高度 px */
+    h?: number;
+    /** 自适应高度 px，`ia` 为 1 时用它 */
+    ah?: number;
+    /** 是否自适应 */
+    ia?: number;
+    /** 隐藏 */
+    hd?: number;
+    s?: StyleData | string | null;
+}
+interface ColumnData {
+    /** 宽度 px */
+    w?: number;
+    hd?: number;
+    s?: StyleData | string | null;
+}
+interface CellRange {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+interface FreezeData {
+    /** 冻结列数 */
+    xSplit: number;
+    /** 冻结行数 */
+    ySplit: number;
+    startRow: number;
+    startColumn: number;
+}
+/** `IObjectMatrixPrimitiveType<T>`：行号 → 列号 → 值，两层都是稀疏对象 */
+type Matrix<T> = Record<number, Record<number, T> | undefined>;
+interface WorksheetData {
+    id?: string;
+    name?: string;
+    /** `#RRGGBB` */
+    tabColor?: string;
+    /** 1 = 隐藏 */
+    hidden?: number;
+    freeze?: FreezeData;
+    rowCount?: number;
+    columnCount?: number;
+    /** px */
+    defaultColumnWidth?: number;
+    /** px */
+    defaultRowHeight?: number;
+    mergeData?: CellRange[];
+    cellData?: Matrix<CellData>;
+    rowData?: Record<number, RowData | undefined>;
+    columnData?: Record<number, ColumnData | undefined>;
+    /** 0 = 不显示网格线 */
+    showGridlines?: number;
+    /** 1 = 从右向左 */
+    rightToLeft?: number;
+    defaultStyle?: StyleData | string | null;
+}
+interface WorkbookData {
+    id?: string;
+    name?: string;
+    /** 工作表顺序。缺省时按 `sheets` 的键序 */
+    sheetOrder?: string[];
+    sheets?: Record<string, WorksheetData | undefined>;
+    /** 样式表：`CellData.s` 为字符串时查这里 */
+    styles?: Record<string, StyleData | null | undefined>;
+    defaultStyle?: StyleData | string | null;
+    /**
+     * 各插件自己序列化的数据（图片、条件格式、数据校验、筛选……）。
+     * 导出读不了它们的私有结构，但**能据此如实报告丢了什么** —— 见 `warnings`。
+     */
+    resources?: Array<{
+        id?: string;
+        name: string;
+        data: string;
+    }>;
+}
+
+/**
+ * Univer 快照 → xlsx 的各个 XML 部件。
+ *
+ * 纯函数、无 DOM、无引擎依赖：Node 里拿一份 JSON 就能出文件，
+ * 不需要把 871KB 的 Univer 渲染引擎拉起来。
+ *
+ * **能保住的**：多工作表、值与类型、公式（含共享公式与缓存值）、数字格式、
+ * 字体/颜色/填充/边框/对齐/换行/旋转、合并单元格、行高列宽、隐藏行列、
+ * 冻结窗格、网格线开关、标签颜色、工作表隐藏。
+ *
+ * **保不住的**：图片、图表、透视表、条件格式、数据校验、筛选、批注、超链接。
+ * 它们不在 `cellData` 里，而是各插件自己序列化进 `resources` 的私有结构 ——
+ * 逐个反解等于把 Univer 的插件模型抄一遍。所以这里不假装支持，
+ * 而是扫一遍 `resources` **如实报告丢了什么**（见 `warnings`），
+ * 让宿主能把话原样告诉用户，而不是让人打开文件才发现。
+ */
+
+interface SerializeXlsxOptions {
+    /**
+     * 是否写入公式的缓存值，默认 true。
+     *
+     * 关掉的话单元格只剩 `<f>`，Excel 打开时自己重算 —— 值一定是对的，
+     * 但在**不重算的**消费方（网页预览、pandas、部分在线表格）里会显示成空。
+     * 开着则 Univer 算出来的值直接可见，代价是 Univer 与 Excel 的函数实现
+     * 有差异时会先看到 Univer 的结果，直到用户在 Excel 里触发重算。
+     */
+    cachedFormulaValues?: boolean;
+    /** docProps 里的作者 */
+    creator?: string;
+    /** docProps 里的时间。传固定值可得到逐字节确定的产物（测试用） */
+    created?: Date;
+}
+interface SerializeXlsxResult {
+    /** zip 条目：路径 → 内容 */
+    files: Record<string, Uint8Array>;
+    /** 导出时丢掉/降级了什么。**要展示给用户**，别吞 */
+    warnings: string[];
+    /** 计数，用于量化保真度 */
+    stats: Record<string, number>;
+}
+declare function serializeXlsx(workbook: WorkbookData, options?: SerializeXlsxOptions): SerializeXlsxResult;
+
+/**
+ * `@4399ywkf/editor/xlsx` —— 表格导出。
+ *
+ * 和 `./docx` 同一套思路：**在本地生成，文档不出内网**，不依赖任何转换服务，
+ * 也不引 SheetJS —— 打包只多出 fflate（本来就有）和这几百行 OOXML 拼装。
+ *
+ * ```ts
+ * import { downloadXlsx } from "@4399ywkf/editor/xlsx"
+ *
+ * // SheetView 的 onReady 给的就是 univerAPI
+ * <DocumentView format="sheet" onReady={(api) => (ref.current = api)} />
+ * downloadXlsx(ref.current, "年度报表.xlsx")
+ * ```
+ *
+ * 服务端 / 定时任务只有 JSON 也能用 —— 整条链路不碰 DOM：
+ *
+ * ```ts
+ * import { xlsxFromSnapshot } from "@4399ywkf/editor/xlsx"
+ * const { bytes, warnings } = xlsxFromSnapshot(snapshot)
+ * ```
+ *
+ * `warnings` 一定要透给用户。Univer 把图片、条件格式、数据校验这些存在插件数据里，
+ * 不在单元格模型内，导出必然丢 —— 打开文件才发现远比导出时被告知糟糕。
+ */
+
+declare const XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+interface XlsxResult {
+    bytes: Uint8Array;
+    /** 导出时丢掉/降级了什么。**请展示给用户** */
+    warnings: string[];
+    stats: Record<string, number>;
+}
+/** 纯函数：Univer 快照 → .xlsx 字节。不依赖 DOM 与引擎，服务端 / 测试直接可用。 */
+declare function xlsxFromSnapshot(workbook: WorkbookData, options?: SerializeXlsxOptions): XlsxResult;
+/**
+ * 从 Univer 实例取快照。
+ *
+ * 参数类型是 `unknown` 而不是 `FUniver`：`@univerjs/presets` 是可选 peer，
+ * 写成具体类型会让没装它的项目 typecheck 直接红。运行时按 facade 的两个
+ * 方法名依次试探（`getSnapshot` 是新名字，`save` 是旧的）。
+ */
+declare function snapshotFromUniver(univerAPI: unknown): WorkbookData;
+/** Univer 实例或快照 → .xlsx 字节 */
+declare function exportXlsx(source: WorkbookData | unknown, options?: SerializeXlsxOptions): XlsxResult;
+/** Univer 实例或快照 → Blob，便于交给上传接口 */
+declare function xlsxBlob(source: WorkbookData | unknown, options?: SerializeXlsxOptions): Blob;
+/**
+ * 触发浏览器下载。返回 warnings / stats —— 别丢，那是「这次导出丢了什么」的唯一出口。
+ *
+ * 只在浏览器里可用；Node 环境请用 `xlsxFromSnapshot` 自己落盘。
+ */
+declare function downloadXlsx(source: WorkbookData | unknown, filename?: string, options?: SerializeXlsxOptions): XlsxResult;
+
+export { type CellData, type CellRange, type CellValue, type ColumnData, type RowData, type SerializeXlsxOptions, type SerializeXlsxResult, type StyleData, type WorkbookData, type WorksheetData, XLSX_MIME, type XlsxResult, downloadXlsx, exportXlsx, serializeXlsx, snapshotFromUniver, xlsxBlob, xlsxFromSnapshot };