dex-simple-report-excel 1.0.0

package/src/index.js

@@ -0,0 +1,1051 @@
+import xlsx from 'xlsx-js-style';
+
+/**
+ * 格式转换，将数据按字段顺序转换为 AOA (Array of Arrays) 格式
+ * @param {Array<string>} filterVal - 字段映射顺序
+ * @param {Array<Object>} jsonData - 原始 JSON 数据
+ * @returns {Array<Array>}
+ */
+export function formatJson(filterVal, jsonData) {
+    return jsonData.map(v => filterVal.map(j => v[j]));
+}
+
+/**
+ * 内部警告提示（模拟浏览器端提示，若在非浏览器环境则仅 console.warn）
+ */
+let notification = null;
+export const warning = (message, title = '警告信息') => {
+    if (typeof window !== 'undefined' && window.Notification && window.Notification.warning) {
+        !notification && (notification = window.Notification.warning({
+            title,
+            dangerouslyUseHTMLString: true,
+            message: `<strong>信息：</strong> ${message}`,
+            duration: 2000,
+            onClose: () => notification = null
+        }));
+    } else {
+        console.warn(`${title}: ${message}`);
+    }
+}
+
+/**
+ * 高级版 Excel 导出工具类：支持多级列头与动态行列合并
+ * 提供同步/异步两种导出模式，具备分块计算与性能监控
+ */
+export class ExcelExporter {
+    /**
+     * 导出 Excel 文件（同步）
+     */
+    static exportExcel(options = {}) {
+        try {
+            const {
+                sheets = [],
+                fileName = '导出数据.xlsx',
+                defaultStyles = {},
+                showBorder = true,
+                styleOptions = {}
+            } = options;
+
+            if (!sheets || sheets.length === 0) {
+                console.warn('未提供工作表数据');
+                return false;
+            }
+
+            console.time('ExcelExporter:Total');
+            const workbook = xlsx.utils.book_new();
+
+            const defaultCellStyle = this.getDefaultCellStyle(defaultStyles.cellStyle, showBorder, styleOptions);
+            const defaultTitleCellStyle = this.getDefaultTitleCellStyle(defaultStyles.titleCellStyle, showBorder, styleOptions);
+            const defaultHeadCellStyle = this.getDefaultHeadCellStyle(defaultStyles.headCellStyle, showBorder, styleOptions);
+
+            sheets.forEach(sheet => {
+                this.addSheetToWorkbook(
+                    workbook,
+                    sheet.data || [],
+                    sheet.columns || [],
+                    defaultCellStyle,
+                    defaultTitleCellStyle,
+                    defaultHeadCellStyle,
+                    sheet.sheetName || 'Sheet1',
+                    sheet.title || '',
+                    sheet.customOptions || {},
+                    sheet.mergeOptions || {},
+                    showBorder
+                );
+            });
+
+            xlsx.writeFile(workbook, fileName, { type: 'binary' });
+            console.timeEnd('ExcelExporter:Total');
+            return true;
+        } catch (error) {
+            console.error('导出Excel时发生错误:', error);
+            warning('导出Excel时发生错误，请稍后再试。');
+            return false;
+        }
+    }
+
+    /**
+     * 导出 Excel 文件（异步）
+     */
+    static exportExcelAsync(options = {}) {
+        return new Promise((resolve) => {
+            try {
+                const {
+                    sheets = [],
+                    fileName = '导出数据.xlsx',
+                    defaultStyles = {},
+                    showBorder = true,
+                    styleOptions = {}
+                } = options;
+
+                // 更新警告提示信息，使用项目名称替代硬编码字符串
+                if (!sheets || sheets.length === 0) {
+                    console.warn('未提供工作表数据');
+                    resolve(false);
+                    return;
+                }
+
+
+                console.time('ExcelExporter:TotalAsync');
+                const workbook = xlsx.utils.book_new();
+
+                const defaultCellStyle = this.getDefaultCellStyle(defaultStyles.cellStyle, showBorder, styleOptions);
+                const defaultTitleCellStyle = this.getDefaultTitleCellStyle(defaultStyles.titleCellStyle, showBorder, styleOptions);
+                const defaultHeadCellStyle = this.getDefaultHeadCellStyle(defaultStyles.headCellStyle, showBorder, styleOptions);
+
+                const buildNext = (index) => {
+                    if (index >= sheets.length) {
+                        xlsx.writeFile(workbook, fileName, { type: 'binary' });
+                        console.timeEnd('ExcelExporter:TotalAsync');
+                        resolve(true);
+                        return;
+                    }
+                    const sheet = sheets[index];
+                    this.addSheetToWorkbookAsync(
+                        workbook,
+                        sheet.data || [],
+                        sheet.columns || [],
+                        defaultCellStyle,
+                        defaultTitleCellStyle,
+                        defaultHeadCellStyle,
+                        sheet.sheetName || 'Sheet1',
+                        sheet.title || '',
+                        sheet.customOptions || {},
+                        sheet.mergeOptions || {},
+                        showBorder
+                    ).then(() => {
+                        setTimeout(() => buildNext(index + 1), 0);
+                    }).catch(err => {
+                        console.error('异步添加工作表时发生错误:', err);
+                        warning('导出Excel时发生错误，请稍后再试。');
+                        resolve(false);
+                    });
+                }
+                setTimeout(() => buildNext(0), 0);
+            } catch (error) {
+                console.error('导出Excel(异步)时发生错误:', error);
+                warning('导出Excel时发生错误，请稍后再试。');
+                resolve(false);
+            }
+        });
+    }
+
+    static addSheetToWorkbook(workbook, data, columns, cellStyle, titleCellStyle, headCellStyle, sheetName, title, customOptions, mergeOptions, showBorder) {
+        try {
+            const options = {
+                data,
+                columns,
+                cellStyle,
+                titleCellStyle,
+                headCellStyle,
+                title,
+                merges: [],
+                cols: [...(Array.isArray(columns) ? this.estimateCols(columns) : [])],
+                rows: [...data.map(() => ({ hpt: 30 }))],
+                ...customOptions,
+                mergeOptions: mergeOptions || {},
+                indexColumn: (mergeOptions && mergeOptions.serialNumberColumn)
+                    ? {
+                        enabled: true,
+                        header: mergeOptions.serialNumberHeader || '序号',
+                        startAt: typeof mergeOptions.serialNumberStartAt === 'number' ? mergeOptions.serialNumberStartAt : 1
+                    }
+                    : (customOptions && customOptions.indexColumn) || {},
+                applyBorders: typeof (customOptions && customOptions.applyBorders) === 'boolean' ? customOptions.applyBorders : (showBorder !== false)
+            }
+            const worksheet = this.createSheet(options);
+            xlsx.utils.book_append_sheet(workbook, worksheet, sheetName);
+        } catch (error) {
+            console.error('添加工作表时发生错误:', error);
+            throw new Error('添加工作表时发生错误');
+        }
+    }
+
+    static addSheetToWorkbookAsync(workbook, data, columns, cellStyle, titleCellStyle, headCellStyle, sheetName, title, customOptions, mergeOptions, showBorder) {
+        const options = {
+            data,
+            columns,
+            cellStyle,
+            titleCellStyle,
+            headCellStyle,
+            title,
+            merges: [],
+            cols: [...(Array.isArray(columns) ? this.estimateCols(columns) : [])],
+            rows: [...data.map(() => ({ hpt: 30 }))],
+            ...customOptions,
+            mergeOptions: mergeOptions || {},
+            indexColumn: (mergeOptions && mergeOptions.serialNumberColumn)
+                ? {
+                    enabled: true,
+                    header: mergeOptions.serialNumberHeader || '序号',
+                    startAt: typeof mergeOptions.serialNumberStartAt === 'number' ? mergeOptions.serialNumberStartAt : 1
+                }
+                : (customOptions && customOptions.indexColumn) || {},
+            applyBorders: typeof (customOptions && customOptions.applyBorders) === 'boolean' ? customOptions.applyBorders : (showBorder !== false)
+        }
+        return this.createSheetAsync(options).then(worksheet => {
+            xlsx.utils.book_append_sheet(workbook, worksheet, sheetName);
+        });
+    }
+
+    static createSheet(options) {
+        console.time('ExcelExporter:CreateSheet');
+        try {
+            const { data, columns, cellStyle, titleCellStyle, headCellStyle, title, cols, mergeOptions = {}, rowHeights = {}, indexColumn = {} } = options;
+            const enableIndex = !!indexColumn.enabled;
+            const indexHeader = indexColumn.header || '序号';
+            const indexStartAt = typeof indexColumn.startAt === 'number' ? indexColumn.startAt : 1;
+            const columnsAug = enableIndex ? [{ header: indexHeader, prop: '__index__', mergeable: false }, ...columns] : columns;
+
+            const { headerRows, leafNodes, headerMerges } = this.buildHeaderStructure(columnsAug);
+
+            const leafKeys = leafNodes.map(n => n.prop || n.header || n.key || '');
+            const filterVal = options.filterVal || [...leafKeys];
+
+            const xlsxData = formatJson(filterVal, data);
+
+            const aoa = [];
+            if (title) aoa.push([title]);
+            if (headerRows.length > 0) headerRows.forEach(r => aoa.push(r));
+            aoa.push(...xlsxData);
+
+            const worksheet = xlsx.utils.aoa_to_sheet(aoa);
+
+            if (cols) {
+                worksheet['!cols'] = enableIndex ? [{ wch: 6 }, ...cols] : cols;
+            }
+
+            const merges = [];
+            const titleOffset = title ? 1 : 0;
+            const headerRowCount = headerRows.length;
+            const totalRows = aoa.length;
+            const rowsFull = Array.from({ length: totalRows }, () => ({}));
+            const explicitRows = new Set();
+            const dataDefaultHpt = typeof rowHeights.dataDefault === 'number' ? rowHeights.dataDefault : 30;
+
+            for (let r = titleOffset + headerRowCount; r < totalRows; r++) {
+                rowsFull[r] = { hpt: dataDefaultHpt };
+            }
+            if (title && typeof rowHeights.title === 'number') {
+                rowsFull[0] = { ...(rowsFull[0] || {}), hpt: rowHeights.title };
+                explicitRows.add(0);
+            }
+            if (typeof rowHeights.header === 'number') {
+                for (let r = titleOffset; r < titleOffset + headerRowCount; r++) {
+                    rowsFull[r] = { ...(rowsFull[r] || {}), hpt: rowHeights.header };
+                    explicitRows.add(r);
+                }
+            }
+            if (rowHeights.dataByIndex && typeof rowHeights.dataByIndex === 'object') {
+                Object.keys(rowHeights.dataByIndex).forEach(k => {
+                    const idx = Number(k);
+                    const h = rowHeights.dataByIndex[idx];
+                    if (!Number.isNaN(idx) && typeof h === 'number') {
+                        const row = titleOffset + headerRowCount + idx;
+                        if (row >= titleOffset + headerRowCount && row < totalRows) {
+                            rowsFull[row] = { ...(rowsFull[row] || {}), hpt: h };
+                            explicitRows.add(row);
+                        }
+                    }
+                });
+            }
+
+            if (title) {
+                const totalCols = Math.max(leafNodes.length, (aoa[titleOffset] || []).length);
+                merges.push({ s: { r: 0, c: 0 }, e: { r: 0, c: Math.max(0, totalCols - 1) } });
+            }
+
+            headerMerges.forEach(m => {
+                merges.push({ s: { r: m.s.r + titleOffset, c: m.s.c }, e: { r: m.e.r + titleOffset, c: m.e.c } });
+            });
+
+            const rowMerges = this.computeRowMerges(
+                data,
+                leafNodes,
+                titleOffset + headerRowCount,
+                mergeOptions
+            );
+            merges.push(...rowMerges);
+
+            if (enableIndex && mergeOptions && mergeOptions.mergeKey) {
+                const segments = this.computeKeySegments(data, mergeOptions);
+                let seq = indexStartAt;
+                segments.forEach(seg => {
+                    const startR = titleOffset + headerRowCount + seg.start;
+                    const endR = titleOffset + headerRowCount + seg.end;
+                    const refTop = xlsx.utils.encode_cell({ r: startR, c: 0 });
+                    if (!worksheet[refTop]) worksheet[refTop] = { v: '', t: 's' };
+                    worksheet[refTop].v = seq;
+                    worksheet[refTop].t = 'n';
+                    if (endR > startR) {
+                        merges.push({ s: { r: startR, c: 0 }, e: { r: endR, c: 0 } });
+                    }
+                    seq += 1;
+                });
+            }
+
+            {
+                const dataStart = titleOffset + headerRowCount;
+                const rangeLocal = xlsx.utils.decode_range(worksheet['!ref']);
+                const imgCols = [];
+                for (let c = 0; c < leafNodes.length; c++) {
+                    if (leafNodes[c] && leafNodes[c].cellType === 'image') imgCols.push(c);
+                }
+                if (imgCols.length) {
+                    if (!worksheet['!cols']) worksheet['!cols'] = Array.from({ length: rangeLocal.e.c + 1 }, () => ({ wch: 15 }));
+                    imgCols.forEach(c => {
+                        if (!worksheet['!cols'][c]) worksheet['!cols'][c] = {};
+                        worksheet['!cols'][c].wch = Math.max(worksheet['!cols'][c].wch || 15, 20);
+                    });
+                    for (let r = dataStart; r <= rangeLocal.e.r; r++) {
+                        imgCols.forEach(c => {
+                            const ref = xlsx.utils.encode_cell({ r, c });
+                            const cell = worksheet[ref];
+                            const val = cell ? cell.v : '';
+                            if (this.isValidImageUrl(String(val || ''))) {
+                                const text = '查看图片';
+                                worksheet[ref] = { v: text, t: 's', l: { Target: String(val), Tooltip: '打开图片链接' } };
+                            }
+                        });
+                    }
+                }
+            }
+
+            if (merges.length) worksheet['!merges'] = merges;
+            this.adjustRowHeightsForMerges(
+                rowsFull,
+                merges,
+                titleOffset + headerRowCount,
+                explicitRows,
+                { mode: 'multiply', baseDataHpt: dataDefaultHpt }
+            );
+            worksheet['!rows'] = rowsFull;
+
+            const range = xlsx.utils.decode_range(worksheet['!ref']);
+            for (let R = range.s.r; R <= range.e.r; ++R) {
+                for (let C = range.s.c; C <= range.e.c; ++C) {
+                    const cellRef = xlsx.utils.encode_cell({ r: R, c: C });
+                    if (!worksheet[cellRef]) worksheet[cellRef] = { v: '', t: 's' };
+                    if (title && R === 0) {
+                        worksheet[cellRef].s = titleCellStyle || headCellStyle;
+                    } else if (R >= titleOffset && R < titleOffset + headerRowCount) {
+                        worksheet[cellRef].s = headCellStyle;
+                    } else {
+                        worksheet[cellRef].s = cellStyle;
+                    }
+                }
+            }
+            if (options.applyBorders) {
+                if (merges.length) this.ensureBorderForMergedCells(worksheet, merges);
+                this.ensureBorderForHeaderArea(worksheet, merges, titleOffset, headerRowCount);
+            }
+
+            console.timeEnd('ExcelExporter:CreateSheet');
+            return worksheet;
+        } catch (error) {
+            console.error('创建工作表时发生错误:', error);
+            throw new Error('创建工作表时发生错误');
+        }
+    }
+
+    static createSheetAsync(options) {
+        console.time('ExcelExporter:CreateSheetAsync');
+        return new Promise((resolve, reject) => {
+            try {
+                const { data, columns, cellStyle, titleCellStyle, headCellStyle, title, cols, mergeOptions = {}, rowHeights = {}, indexColumn = {} } = options;
+                const enableIndex = !!indexColumn.enabled;
+                const indexHeader = indexColumn.header || '序号';
+                const indexStartAt = typeof indexColumn.startAt === 'number' ? indexColumn.startAt : 1;
+                const columnsAug = enableIndex ? [{ header: indexHeader, prop: '__index__', mergeable: false }, ...columns] : columns;
+
+                const { headerRows, leafNodes, headerMerges } = this.buildHeaderStructure(columnsAug);
+                const leafKeys = leafNodes.map(n => n.prop || n.header || n.key || '');
+                const filterVal = options.filterVal || [...leafKeys];
+                const xlsxData = formatJson(filterVal, data);
+
+                const aoa = [];
+                if (title) aoa.push([title]);
+                if (headerRows.length > 0) headerRows.forEach(r => aoa.push(r));
+                aoa.push(...xlsxData);
+
+                const worksheet = xlsx.utils.aoa_to_sheet(aoa);
+                if (cols) worksheet['!cols'] = enableIndex ? [{ wch: 6 }, ...cols] : cols;
+
+                const merges = [];
+                const titleOffset = title ? 1 : 0;
+                const headerRowCount = headerRows.length;
+
+                if (title) {
+                    const totalCols = Math.max(leafNodes.length, (aoa[titleOffset] || []).length);
+                    merges.push({ s: { r: 0, c: 0 }, e: { r: 0, c: Math.max(0, totalCols - 1) } });
+                }
+
+                headerMerges.forEach(m => {
+                    merges.push({ s: { r: m.s.r + titleOffset, c: m.s.c }, e: { r: m.e.r + titleOffset, c: m.e.c } });
+                });
+
+                const totalRows = aoa.length;
+                const rowsFull = Array.from({ length: totalRows }, () => ({}));
+                const explicitRows = new Set();
+                const dataDefaultHpt = typeof rowHeights.dataDefault === 'number' ? rowHeights.dataDefault : 30;
+                for (let r = titleOffset + headerRowCount; r < totalRows; r++) {
+                    rowsFull[r] = { hpt: dataDefaultHpt };
+                }
+                if (title && typeof rowHeights.title === 'number') {
+                    rowsFull[0] = { ...(rowsFull[0] || {}), hpt: rowHeights.title };
+                    explicitRows.add(0);
+                }
+                if (typeof rowHeights.header === 'number') {
+                    for (let r = titleOffset; r < titleOffset + headerRowCount; r++) {
+                        rowsFull[r] = { ...(rowsFull[r] || {}), hpt: rowHeights.header };
+                        explicitRows.add(r);
+                    }
+                }
+                if (rowHeights.dataByIndex && typeof rowHeights.dataByIndex === 'object') {
+                    Object.keys(rowHeights.dataByIndex).forEach(k => {
+                        const idx = Number(k);
+                        const h = rowHeights.dataByIndex[idx];
+                        if (!Number.isNaN(idx) && typeof h === 'number') {
+                            const row = titleOffset + headerRowCount + idx;
+                            if (row >= titleOffset + headerRowCount && row < totalRows) {
+                                rowsFull[row] = { ...(rowsFull[row] || {}), hpt: h };
+                                explicitRows.add(row);
+                            }
+                        }
+                    });
+                }
+
+                this.computeRowMergesAsync(
+                    data,
+                    leafNodes,
+                    titleOffset + headerRowCount,
+                    mergeOptions
+                ).then(rowMerges => {
+                    merges.push(...rowMerges);
+                    if (enableIndex && mergeOptions && mergeOptions.mergeKey) {
+                        const segments = this.computeKeySegments(data, mergeOptions);
+                        let seq = indexStartAt;
+                        segments.forEach(seg => {
+                            const startR = titleOffset + headerRowCount + seg.start;
+                            const endR = titleOffset + headerRowCount + seg.end;
+                            const refTop = xlsx.utils.encode_cell({ r: startR, c: 0 });
+                            if (!worksheet[refTop]) worksheet[refTop] = { v: '', t: 's' };
+                            worksheet[refTop].v = seq;
+                            worksheet[refTop].t = 'n';
+                            if (endR > startR) merges.push({ s: { r: startR, c: 0 }, e: { r: endR, c: 0 } });
+                            seq += 1;
+                        });
+                    }
+                    {
+                        const dataStart = titleOffset + headerRowCount;
+                        const range = xlsx.utils.decode_range(worksheet['!ref']);
+                        const imgCols = [];
+                        for (let c = 0; c < leafNodes.length; c++) {
+                            if (leafNodes[c] && leafNodes[c].cellType === 'image') imgCols.push(c);
+                        }
+                        if (imgCols.length) {
+                            if (!worksheet['!cols']) worksheet['!cols'] = Array.from({ length: range.e.c + 1 }, () => ({ wch: 15 }));
+                            imgCols.forEach(c => {
+                                if (!worksheet['!cols'][c]) worksheet['!cols'][c] = {};
+                                worksheet['!cols'][c].wch = Math.max(worksheet['!cols'][c].wch || 15, 20);
+                            });
+                            for (let r = dataStart; r <= range.e.r; r++) {
+                                imgCols.forEach(c => {
+                                    const ref = xlsx.utils.encode_cell({ r, c });
+                                    const cell = worksheet[ref];
+                                    const val = cell ? cell.v : '';
+                                    if (this.isValidImageUrl(String(val || ''))) {
+                                        const text = '查看图片';
+                                        worksheet[ref] = { v: text, t: 's', l: { Target: String(val), Tooltip: '打开图片链接' } };
+                                    }
+                                });
+                            }
+                        }
+                    }
+                    if (merges.length) worksheet['!merges'] = merges;
+                    this.adjustRowHeightsForMerges(
+                        rowsFull,
+                        merges,
+                        titleOffset + headerRowCount,
+                        explicitRows,
+                        { mode: 'multiply', baseDataHpt: dataDefaultHpt }
+                    );
+                    worksheet['!rows'] = rowsFull;
+
+                    const range = xlsx.utils.decode_range(worksheet['!ref']);
+                    for (let R = range.s.r; R <= range.e.r; ++R) {
+                        for (let C = range.s.c; C <= range.e.c; ++C) {
+                            const cellRef = xlsx.utils.encode_cell({ r: R, c: C });
+                            if (!worksheet[cellRef]) worksheet[cellRef] = { v: '', t: 's' };
+                            if (title && R === 0) {
+                                worksheet[cellRef].s = titleCellStyle || headCellStyle;
+                            } else if (R >= titleOffset && R < titleOffset + headerRowCount) {
+                                worksheet[cellRef].s = headCellStyle;
+                            } else {
+                                worksheet[cellRef].s = cellStyle;
+                            }
+                        }
+                    }
+                    if (options.applyBorders) {
+                        if (merges.length) this.ensureBorderForMergedCells(worksheet, merges);
+                        this.ensureBorderForHeaderArea(worksheet, merges, titleOffset, headerRowCount);
+                    }
+
+                    console.timeEnd('ExcelExporter:CreateSheetAsync');
+                    resolve(worksheet);
+                }).catch(err => {
+                    reject(err);
+                });
+            } catch (error) {
+                reject(error);
+            }
+        });
+    }
+
+    static buildHeaderStructure(columns = []) {
+        console.time('ExcelExporter:BuildHeader');
+        try {
+            const isHierarchical = Array.isArray(columns) && columns.some(c => c.children && c.children.length);
+            if (!isHierarchical) {
+                const visible = columns.filter(c => !c.hidden);
+                const simpleHeaders = visible.map(c => c.label || c.header || (c.prop || ''));
+                const leafNodes = visible.map(c => ({ header: c.label || c.header || (c.prop || ''), prop: c.prop, mergeable: c.mergeable === true, hidden: !!c.hidden, cellType: c.cellType || 'text' }));
+                console.timeEnd('ExcelExporter:BuildHeader');
+                return { headerRows: simpleHeaders.length ? [simpleHeaders] : [], leafNodes, headerMerges: [] };
+            }
+
+            const depth = this.getDepth(columns);
+            const leafNodes = [];
+            const headerRows = Array.from({ length: depth }, () => []);
+            const headerMerges = [];
+
+            const traverse = (nodes, level, startCol) => {
+                let colIndex = startCol;
+                nodes.forEach(node => {
+                    const span = this.countLeaf(node);
+                    const headerText = node.header || node.label || '';
+                    for (let i = 0; i < span; i++) {
+                        headerRows[level][colIndex + i] = headerRows[level][colIndex + i] || '';
+                    }
+                    headerRows[level][colIndex] = headerText;
+                    if (node.children && node.children.length) {
+                        headerMerges.push({ s: { r: level, c: colIndex }, e: { r: level, c: colIndex + span - 1 } });
+                        node.children.forEach(child => {
+                            const childSpan = this.countLeaf(child);
+                            traverse([child], level + 1, colIndex);
+                            colIndex += childSpan;
+                        });
+                    } else {
+                        if (!node.hidden) {
+                            const rowSpan = depth - level - 1;
+                            if (rowSpan > 0) {
+                                headerMerges.push({ s: { r: level, c: colIndex }, e: { r: level + rowSpan, c: colIndex } });
+                            }
+                            leafNodes.push({ header: headerText, prop: node.prop, mergeable: node.mergeable === true, hidden: !!node.hidden, cellType: node.cellType || 'text' });
+                            colIndex += 1;
+                        }
+                    }
+                });
+                return colIndex - startCol;
+            }
+
+            const totalLeaf = columns.reduce((sum, n) => sum + this.countLeaf(n), 0);
+            for (let r = 0; r < depth; r++) headerRows[r] = Array.from({ length: totalLeaf }, () => '');
+            traverse(columns, 0, 0);
+
+            console.timeEnd('ExcelExporter:BuildHeader');
+            return { headerRows, leafNodes, headerMerges };
+        } catch (error) {
+            console.error('构建表头结构时发生错误:', error);
+            throw new Error('构建表头结构时发生错误');
+        }
+    }
+
+    static getDepth(node) {
+        if (Array.isArray(node)) return Math.max(0, ...node.map(n => this.getDepth(n)));
+        if (!node || !node.children || node.children.length === 0) return 1;
+        return 1 + Math.max(...node.children.map(n => this.getDepth(n)));
+    }
+
+    static countLeaf(node) {
+        if (!node) return 0;
+        if (!node.children || node.children.length === 0) return node.hidden ? 0 : 1;
+        return node.children.reduce((sum, c) => sum + this.countLeaf(c), 0);
+    }
+
+    static estimateCols(columns) {
+        const isHierarchical = Array.isArray(columns) && columns.some(c => c.children && c.children.length);
+        const leafCount = isHierarchical ? columns.reduce((sum, n) => sum + this.countLeaf(n), 0) : columns.length;
+        return Array.from({ length: leafCount }, () => ({ wch: 20 }));
+    }
+
+    static computeRowMerges(data, leafNodes, startRow, mergeOptions = {}) {
+        console.time('ExcelExporter:RowMerge');
+        const {
+            rowMerge = true,
+            excludeColumns = [],
+            mergeStrategy = 'auto',
+            regex,
+            customComparator,
+            mergeKey,
+            mergeNull = false,
+            childrenStrict = false,
+            mergeChildrenByDefault = false
+        } = mergeOptions;
+        const merges = [];
+        if (!rowMerge || !Array.isArray(data) || data.length === 0 || !mergeKey) {
+            console.timeEnd('ExcelExporter:RowMerge');
+            return merges;
+        }
+        const excludeSet = new Set(excludeColumns || []);
+        const colIndexByProp = new Map();
+        leafNodes.forEach((n, idx) => {
+            const p = n.prop || n.header || n.key || '';
+            colIndexByProp.set(p, idx);
+        });
+        const keyColIndex = colIndexByProp.get(mergeKey);
+        const getVal = (row, prop, fallback) => {
+            if (!row) return undefined;
+            if (prop in row) return row[prop];
+            return row[fallback];
+        }
+        const shouldMerge = (a, b, key) => {
+            if (excludeSet.has(key)) return false;
+            if (!mergeNull && (a === undefined || a === null || a === '')) return false;
+            if (!mergeNull && (b === undefined || b === null || b === '')) return false;
+            if (mergeStrategy === 'custom' && typeof customComparator === 'function') return !!customComparator(a, b, undefined, undefined, key);
+            if (mergeStrategy === 'regex') {
+                const reg = typeof regex === 'string' ? new RegExp(regex) : regex;
+                return reg ? (reg.test(String(a)) && reg.test(String(b)) && String(a) === String(b)) : String(a) === String(b);
+            }
+            return String(a) === String(b);
+        }
+        let r = 0;
+        while (r < data.length) {
+            const start = r;
+            const baseKey = data[r] ? data[r][mergeKey] : undefined;
+            let end = r;
+            while (end + 1 < data.length) {
+                const nextKey = data[end + 1] ? data[end + 1][mergeKey] : undefined;
+                if (shouldMerge(baseKey, nextKey, mergeKey)) {
+                    end += 1;
+                } else {
+                    break;
+                }
+            }
+            if (end > start) {
+                if (keyColIndex !== undefined) {
+                    merges.push({ s: { r: startRow + start, c: keyColIndex }, e: { r: startRow + end, c: keyColIndex } });
+                }
+                for (let c = 0; c < leafNodes.length; c++) {
+                    if (c === keyColIndex) continue;
+                    const node = leafNodes[c];
+                    if (!(mergeChildrenByDefault || node.mergeable)) continue;
+                    const keyName = node.prop || node.header || '';
+                    const baseAll = getVal(data[start], node.prop || node.header, node.prop || node.header);
+                    let allEqual = baseAll !== undefined;
+                    if (allEqual) {
+                        for (let k = start + 1; k <= end; k++) {
+                            const val = getVal(data[k], node.prop || node.header, node.prop || node.header);
+                            if (!shouldMerge(baseAll, val, keyName)) { allEqual = false; break }
+                        }
+                    }
+                    if (allEqual) {
+                        merges.push({ s: { r: startRow + start, c }, e: { r: startRow + end, c } });
+                    } else if (!childrenStrict) {
+                        let i = start;
+                        while (i <= end) {
+                            const base = getVal(data[i], node.prop || node.header, node.prop || node.header);
+                            let j = i;
+                            while (j + 1 <= end) {
+                                const next = getVal(data[j + 1], node.prop || node.header, node.prop || node.header);
+                                if (shouldMerge(base, next, keyName)) {
+                                    j += 1;
+                                } else {
+                                    break;
+                                }
+                            }
+                            if (j > i) merges.push({ s: { r: startRow + i, c }, e: { r: startRow + j, c } });
+                            i = j + 1;
+                        }
+                    }
+                }
+            }
+            r = end + 1;
+        }
+        console.timeEnd('ExcelExporter:RowMerge');
+        return merges;
+    }
+
+    static computeRowMergesAsync(data, leafNodes, startRow, mergeOptions = {}) {
+        console.time('ExcelExporter:RowMergeAsync');
+        return new Promise((resolve) => {
+            const {
+                rowMerge = true,
+                excludeColumns = [],
+                mergeStrategy = 'auto',
+                regex,
+                customComparator,
+                mergeKey,
+                mergeNull = false,
+                childrenStrict = false,
+                chunkSize = 1000,
+                mergeChildrenByDefault = false
+            } = mergeOptions;
+            const merges = [];
+            if (!rowMerge || !Array.isArray(data) || data.length === 0 || !mergeKey) {
+                console.timeEnd('ExcelExporter:RowMergeAsync');
+                resolve(merges);
+                return;
+            }
+            const excludeSet = new Set(excludeColumns || []);
+            const colIndexByProp = new Map();
+            leafNodes.forEach((n, idx) => {
+                const p = n.prop || n.header || n.key || '';
+                colIndexByProp.set(p, idx);
+            });
+            const keyColIndex = colIndexByProp.get(mergeKey);
+            if (keyColIndex === undefined) {
+                console.timeEnd('ExcelExporter:RowMergeAsync');
+                resolve(merges);
+                return;
+            }
+            const getVal = (row, prop, fallback) => {
+                if (!row) return undefined;
+                if (prop in row) return row[prop];
+                return row[fallback];
+            }
+            const shouldMerge = (a, b, key) => {
+                if (excludeSet.has(key)) return false;
+                if (!mergeNull && (a === undefined || a === null || a === '')) return false;
+                if (!mergeNull && (b === undefined || b === null || b === '')) return false;
+                if (mergeStrategy === 'custom' && typeof customComparator === 'function') return !!customComparator(a, b, undefined, undefined, key);
+                if (mergeStrategy === 'regex') {
+                    const reg = typeof regex === 'string' ? new RegExp(regex) : regex;
+                    return reg ? (reg.test(String(a)) && reg.test(String(b)) && String(a) === String(b)) : String(a) === String(b);
+                }
+                return String(a) === String(b);
+            }
+
+            let r = 0;
+            const processChunk = () => {
+                let iterations = 0;
+                while (r < data.length && iterations < chunkSize) {
+                    const start = r;
+                    const baseKey = data[r] ? data[r][mergeKey] : undefined;
+                    let end = r;
+                    while (end + 1 < data.length) {
+                        const nextKey = data[end + 1] ? data[end + 1][mergeKey] : undefined;
+                        if (shouldMerge(baseKey, nextKey, mergeKey)) {
+                            end += 1;
+                        } else {
+                            break;
+                        }
+                    }
+                    if (end > start) {
+                        if (keyColIndex !== undefined) {
+                            merges.push({ s: { r: startRow + start, c: keyColIndex }, e: { r: startRow + end, c: keyColIndex } });
+                        }
+                        for (let c = 0; c < leafNodes.length; c++) {
+                            if (c === keyColIndex) continue;
+                            const node = leafNodes[c];
+                            if (!(mergeChildrenByDefault || node.mergeable)) continue;
+                            const keyName = node.prop || node.header || '';
+                            const baseAll = getVal(data[start], node.prop || node.header, node.prop || node.header);
+                            let allEqual = baseAll !== undefined;
+                            if (allEqual) {
+                                for (let k = start + 1; k <= end; k++) {
+                                    const val = getVal(data[k], node.prop || node.header, node.prop || node.header);
+                                    if (!shouldMerge(baseAll, val, keyName)) { allEqual = false; break }
+                                }
+                            }
+                            if (allEqual) {
+                                merges.push({ s: { r: startRow + start, c }, e: { r: startRow + end, c } });
+                            } else if (!childrenStrict) {
+                                let i = start;
+                                while (i <= end) {
+                                    const base = getVal(data[i], node.prop || node.header, node.prop || node.header);
+                                    let j = i;
+                                    while (j + 1 <= end) {
+                                        const next = getVal(data[j + 1], node.prop || node.header, node.prop || node.header);
+                                        if (shouldMerge(base, next, keyName)) {
+                                            j += 1;
+                                        } else {
+                                            break;
+                                        }
+                                    }
+                                    if (j > i) merges.push({ s: { r: startRow + i, c }, e: { r: startRow + j, c } });
+                                    i = j + 1;
+                                }
+                            }
+                        }
+                    }
+                    r = end + 1;
+                    iterations += (end - start + 1);
+                }
+                if (r < data.length) {
+                    setTimeout(processChunk, 0);
+                } else {
+                    console.timeEnd('ExcelExporter:RowMergeAsync');
+                    resolve(merges);
+                }
+            }
+            setTimeout(processChunk, 0);
+        });
+    }
+
+    static computeKeySegments(data, mergeOptions = {}) {
+        const { mergeKey, mergeNull = false, mergeStrategy = 'auto', regex, customComparator } = mergeOptions;
+        const segments = [];
+        if (!Array.isArray(data) || data.length === 0 || !mergeKey) return segments;
+        const shouldMerge = (a, b) => {
+            if (!mergeNull && (a === undefined || a === null || a === '')) return false;
+            if (!mergeNull && (b === undefined || b === null || b === '')) return false;
+            if (mergeStrategy === 'custom' && typeof customComparator === 'function') return !!customComparator(a, b, undefined, undefined, mergeKey);
+            if (mergeStrategy === 'regex') {
+                const reg = typeof regex === 'string' ? new RegExp(regex) : regex;
+                return reg ? (reg.test(String(a)) && reg.test(String(b)) && String(a) === String(b)) : String(a) === String(b);
+            }
+            return String(a) === String(b);
+        }
+        let r = 0;
+        while (r < data.length) {
+            const start = r;
+            const baseKey = data[r] ? data[r][mergeKey] : undefined;
+            let end = r;
+            while (end + 1 < data.length) {
+                const nextKey = data[end + 1] ? data[end + 1][mergeKey] : undefined;
+                if (shouldMerge(baseKey, nextKey)) {
+                    end += 1;
+                } else {
+                    break;
+                }
+            }
+            segments.push({ start, end });
+            r = end + 1;
+        }
+        return segments;
+    }
+
+    static getDefaultCellStyle(customStyle = {}, showBorder = true, styleOptions = {}) {
+        const bodyOpts = styleOptions.body || {};
+        const borderStyle = showBorder ? {
+            top: { style: 'thin', color: { rgb: '000000' } },
+            bottom: { style: 'thin', color: { rgb: '000000' } },
+            left: { style: 'thin', color: { rgb: '000000' } },
+            right: { style: 'thin', color: { rgb: '000000' } },
+            ...(customStyle.border || {})
+        } : {
+            top: { style: 'none' },
+            bottom: { style: 'none' },
+            left: { style: 'none' },
+            right: { style: 'none' },
+            ...(customStyle.border || {})
+        }
+        return {
+            font: {
+                name: bodyOpts.fontName || '宋体',
+                sz: bodyOpts.fontSize || 11,
+                bold: typeof bodyOpts.bold === 'boolean' ? bodyOpts.bold : false,
+                underline: false,
+                ...(bodyOpts.colorRgb ? { color: { rgb: bodyOpts.colorRgb } } : {}),
+                ...(customStyle.font || {})
+            },
+            alignment: {
+                horizontal: bodyOpts.horizontal || 'center',
+                vertical: bodyOpts.vertical || 'center',
+                wrapText: typeof bodyOpts.wrapText === 'boolean' ? bodyOpts.wrapText : true,
+                ...(customStyle.alignment || {})
+            },
+            border: borderStyle,
+            ...customStyle
+        }
+    }
+
+    static getDefaultHeadCellStyle(customStyle = {}, showBorder = true, styleOptions = {}) {
+        const headerOpts = styleOptions.header || {};
+        const borderStyle = showBorder ? {
+            top: { style: 'none', color: { rgb: '000000' } },
+            bottom: { style: 'thin', color: { rgb: '000000' } },
+            left: { style: 'none', color: { rgb: '000000' } },
+            right: { style: 'none', color: { rgb: '000000' } },
+            ...(customStyle.border || {})
+        } : {
+            top: { style: 'none' },
+            bottom: { style: 'none' },
+            left: { style: 'none' },
+            right: { style: 'none' },
+            ...(customStyle.border || {})
+        }
+        return {
+            alignment: {
+                horizontal: headerOpts.horizontal || 'center',
+                vertical: headerOpts.vertical || 'center',
+                wrapText: typeof headerOpts.wrapText === 'boolean' ? headerOpts.wrapText : true,
+                ...(customStyle.alignment || {})
+            },
+            font: {
+                name: headerOpts.fontName || '宋体',
+                sz: headerOpts.fontSize || 16,
+                bold: typeof headerOpts.bold === 'boolean' ? headerOpts.bold : false,
+                underline: false,
+                ...(headerOpts.colorRgb ? { color: { rgb: headerOpts.colorRgb } } : {}),
+                ...(customStyle.font || {})
+            },
+            border: borderStyle,
+            ...customStyle
+        }
+    }
+
+    static getDefaultTitleCellStyle(customStyle = {}, showBorder = true, styleOptions = {}) {
+        const titleOpts = styleOptions.title || {};
+        const borderStyle = showBorder ? {
+            top: { style: 'none', color: { rgb: '000000' } },
+            bottom: { style: 'thin', color: { rgb: '000000' } },
+            left: { style: 'none', color: { rgb: '000000' } },
+            right: { style: 'none', color: { rgb: '000000' } },
+            ...(customStyle.border || {})
+        } : {
+            top: { style: 'none' },
+            bottom: { style: 'none' },
+            left: { style: 'none' },
+            right: { style: 'none' },
+            ...(customStyle.border || {})
+        }
+        return {
+            alignment: {
+                horizontal: titleOpts.horizontal || 'center',
+                vertical: titleOpts.vertical || 'center',
+                wrapText: typeof titleOpts.wrapText === 'boolean' ? titleOpts.wrapText : true,
+                ...(customStyle.alignment || {})
+            },
+            font: {
+                name: titleOpts.fontName || '宋体',
+                sz: titleOpts.fontSize || 20,
+                bold: typeof titleOpts.bold === 'boolean' ? titleOpts.bold : true,
+                underline: false,
+                ...(titleOpts.colorRgb ? { color: { rgb: titleOpts.colorRgb } } : {}),
+                ...(customStyle.font || {})
+            },
+            border: borderStyle,
+            ...customStyle
+        }
+    }
+
+    static ensureBorderForMergedCells(worksheet, merges) {
+        const thinSide = (obj, side) => ({ ...(obj || {}), [side]: { style: 'thin', color: { rgb: '000000' } } });
+        merges.forEach(m => {
+            for (let r = m.s.r; r <= m.e.r; r++) {
+                for (let c = m.s.c; c <= m.e.c; c++) {
+                    const ref = xlsx.utils.encode_cell({ r, c });
+                    const cell = worksheet[ref] || { v: '', t: 's' };
+                    const style = cell.s || {};
+                    let border = { ...(style.border || {}) };
+                    if (r === m.s.r) border = thinSide(border, 'top');
+                    if (r === m.e.r) border = thinSide(border, 'bottom');
+                    if (c === m.s.c) border = thinSide(border, 'left');
+                    if (c === m.e.c) border = thinSide(border, 'right');
+                    cell.s = { ...style, border };
+                    worksheet[ref] = cell;
+                }
+            }
+        });
+    }
+
+    static ensureBorderForHeaderArea(worksheet, merges, titleOffset, headerRowCount) {
+        const range = xlsx.utils.decode_range(worksheet['!ref']);
+        const isInMerge = (r, c) => {
+            for (let i = 0; i < merges.length; i++) {
+                const m = merges[i];
+                if (r >= m.s.r && r <= m.e.r && c >= m.s.c && c <= m.e.c) return true;
+            }
+            return false;
+        }
+        for (let r = 0; r < titleOffset + headerRowCount; r++) {
+            for (let c = range.s.c; c <= range.e.c; c++) {
+                if (isInMerge(r, c)) continue;
+                const ref = xlsx.utils.encode_cell({ r, c });
+                const cell = worksheet[ref] || { v: '', t: 's' };
+                const style = cell.s || {};
+                const border = {
+                    top: { style: 'thin', color: { rgb: '000000' } },
+                    bottom: { style: 'thin', color: { rgb: '000000' } },
+                    left: { style: 'thin', color: { rgb: '000000' } },
+                    right: { style: 'thin', color: { rgb: '000000' } }
+                }
+                cell.s = { ...style, border: { ...(style.border || {}), ...border } };
+                worksheet[ref] = cell;
+            }
+        }
+    }
+
+    static adjustRowHeightsForMerges(rowsFull, merges, dataStartRow, explicitRows, opts = {}) {
+        if (!Array.isArray(rowsFull) || !Array.isArray(merges)) return;
+        const mode = opts.mode || 'multiply';
+        const baseDataHpt = typeof opts.baseDataHpt === 'number' ? opts.baseDataHpt : 30;
+        if (mode === 'multiply') {
+            merges.forEach(m => {
+                const isDataMerge = m.s.r >= dataStartRow && m.e.r >= dataStartRow && m.e.r >= m.s.r;
+                if (!isDataMerge) return;
+                for (let r = m.s.r; r <= m.e.r; r++) {
+                    if (!rowsFull[r]) rowsFull[r] = {};
+                    rowsFull[r].hpt = baseDataHpt;
+                }
+            });
+            return;
+        }
+        const affected = new Set();
+        merges.forEach(m => {
+            for (let r = m.s.r; r <= m.e.r; r++) {
+                if (r >= dataStartRow) affected.add(r);
+            }
+        });
+        affected.forEach(r => {
+            if (!rowsFull[r]) rowsFull[r] = {};
+            const locked = explicitRows && explicitRows instanceof Set && explicitRows.has(r);
+            if (!locked && rowsFull[r].hpt) delete rowsFull[r].hpt;
+        });
+    }
+
+    static isValidImageUrl(url) {
+        if (typeof url !== 'string' || !/^https?:\/\//i.test(url)) return false;
+        const lower = url.split('?')[0].toLowerCase();
+        return ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp'].some(ext => lower.endsWith(ext));
+    }
+}
+
+/**
+ * 便捷导出（同步）
+ */
+export function exportExcel(options) {
+    return ExcelExporter.exportExcel(options);
+}
+
+/**
+ * 便捷导出（异步）
+ */
+export function exportExcelAsync(options) {
+    return ExcelExporter.exportExcelAsync(options);
+}
+
+export default ExcelExporter;