dex-simple-report-excel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# DexSimpleReportExcel
+
+基于 `xlsx-js-style` 的高级 Excel 导出工具，支持多工作表、多级表头、行/列合并、样式配置、序号列、图片链接等功能。
+
+## 功能特性
+
+- **多工作表导出**：支持一次性导出多个 Sheet。
+- **复杂表头**：支持多级表头（通过 `columns` 嵌套配置）。
+- **智能合并**：
+  - 支持按列值自动合并行（`mergeOptions`）。
+  - 支持自定义合并策略（正则、自定义函数）。
+- **样式定制**：
+  - 全局/特定样式配置（标题、表头、正文）。
+  - 支持字体、颜色、对齐、边框等设置。
+- **图片支持**：自动识别图片 URL 并转换为“查看图片”链接。
+- **序号列**：支持自动生成序号列，并与合并行对齐。
+
+## 安装
+
+```bash
+npm install dex-simple-report-excel
+```
+
+## 快速开始
+
+### Node.js (ES Module)
+
+```javascript
+import { ExcelExporter } from 'dex-simple-report-excel';
+
+// 1. 定义数据
+const data = [
+  { dept: '研发部', name: '张三', role: '前端', budget: 10000 },
+  { dept: '研发部', name: '李四', role: '后端', budget: 12000 },
+  { dept: '市场部', name: '王五', role: '销售', budget: 8000 },
+  { dept: '市场部', name: '赵六', role: '推广', budget: 9000 }
+];
+
+// 2. 定义列结构
+const columns = [
+  { header: '部门', prop: 'dept', mergeable: true }, // 开启合并
+  { header: '姓名', prop: 'name' },
+  { header: '职位', prop: 'role' },
+  { header: '预算', prop: 'budget' }
+];
+
+// 3. 导出
+ExcelExporter.exportExcel({
+  fileName: '部门预算表.xlsx',
+  sheets: [
+    {
+      sheetName: 'Q1预算',
+      title: '2024年第一季度部门预算表', // 表格大标题
+      columns: columns,
+      data: data,
+      mergeOptions: {
+        mergeKey: 'dept', // 按部门合并
+        serialNumberColumn: true // 开启序号列
+      }
+    }
+  ],
+  styleOptions: {
+    title: { fontSize: 20, bold: true, colorRgb: '4472C4' },
+    header: { fontSize: 14, bold: true, horizontal: 'center' }
+  }
+});
+```
+
+## API 详细说明
+
+### 核心方法
+
+#### `ExcelExporter.exportExcel(options)`
+同步导出 Excel 文件。适用于中小规模数据量。
+
+#### `ExcelExporter.exportExcelAsync(options)`
+异步导出 Excel 文件。适用于大数据量，内部采用分块处理以避免阻塞主线程。
+
+---
+
+### 配置对象说明
+
+#### 1. `ExportOptions` (顶层配置)
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `sheets` | `SheetOptions[]` | `[]` | **必填**，工作表配置数组 |
+| `fileName` | `string` | `'导出数据.xlsx'` | 导出文件名 |
+| `styleOptions` | `StyleOptions` | `{}` | 全局样式简易配置（推荐） |
+| `defaultStyles` | `DefaultStyles` | `{}` | 底层样式对象直接配置（高级） |
+| `showBorder` | `boolean` | `true` | 是否显示单元格边框 |
+
+#### 2. `SheetOptions` (工作表配置)
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `sheetName` | `string` | 工作表名称（默认 `Sheet1`） |
+| `title` | `string` | 表格大标题，置于首行并整行合并 |
+| `columns` | `ColumnNode[]` | **必填**，列定义（支持嵌套实现多级表头） |
+| `data` | `Object[]` | **必填**，数据源数组 |
+| `mergeOptions` | `MergeOptions` | 行合并配置 |
+| `customOptions` | `CustomOptions` | 高级自定义选项（如行高、列宽等） |
+
+#### 3. `ColumnNode` (列定义)
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `header` | `string` | 表头显示文字 |
+| `prop` | `string` | 数据字段名 |
+| `children` | `ColumnNode[]` | 子表头数组（用于多级表头） |
+| `mergeable` | `boolean` | 是否允许该列参与行合并（需配合 `mergeOptions` 使用） |
+| `hidden` | `boolean` | 是否隐藏该列（隐藏列仍可作为 `mergeKey` 使用） |
+| `cellType` | `'text' \| 'image'` | 单元格类型。`image` 会将 URL 转换为“查看图片”链接 |
+| `width` | `number` | 列宽（字符数） |
+
+#### 4. `MergeOptions` (合并配置)
+
+用于控制行合并行为（例如：相同部门的行合并在一起）。
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `mergeKey` | `string` | - | **必填**，主要合并依据的字段名 |
+| `rowMerge` | `boolean` | `true` | 是否开启行合并功能 |
+| `mergeNull` | `boolean` | `false` | 是否合并空值（null/undefined） |
+| `excludeColumns` | `string[]` | `[]` | 排除参与合并的列名数组 |
+| `childrenStrict` | `boolean` | `false` | 子级合并是否严格依赖父级（通常用于多级合并） |
+| `mergeChildrenByDefault` | `boolean` | `false` | 是否默认合并所有子列（无需显式设 `mergeable`） |
+| `mergeStrategy` | `'auto' \| 'regex' \| 'custom'` | `'auto'` | 合并策略 |
+| `regex` | `RegExp \| string` | - | 正则表达式（当 strategy='regex' 时使用） |
+| `customComparator` | `Function` | - | 自定义比较函数（当 strategy='custom' 时使用） |
+| `serialNumberColumn` | `boolean` | `false` | 是否开启最左侧序号列 |
+| `serialNumberHeader` | `string` | `'序号'` | 序号列表头名称 |
+| `serialNumberStartAt` | `number` | `1` | 序号起始值 |
+
+#### 5. `StyleOptions` (样式配置)
+
+用于快速调整表格各部分的视觉样式。
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | `StyleTuning` | 标题行样式 |
+| `header` | `StyleTuning` | 表头行样式 |
+| `body` | `StyleTuning` | 正文数据行样式 |
+
+**`StyleTuning` 对象属性：**
+
+- `fontName`: 字体名称（如 "宋体"）
+- `fontSize`: 字体大小
+- `bold`: 是否加粗 (boolean)
+- `colorRgb`: 字体颜色 (Hex, 如 "FF0000")
+- `horizontal`: 水平对齐 ('left', 'center', 'right')
+- `vertical`: 垂直对齐 ('top', 'center', 'bottom')
+- `wrapText`: 是否自动换行 (boolean)
+
+#### 6. `CustomOptions` (高级选项)
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `rowHeights` | `Object` | 行高配置 `{ title: 30, header: 25, dataDefault: 20 }` |
+| `cols` | `Array` | 手动指定列宽配置 `[{ wch: 20 }, { wch: 10 }]` |
+
+---
+
+## 场景示例
+
+### 1. 基础多级表头与合并
+
+```javascript
+const columns = [
+  { header: '项目编号', prop: 'id', hidden: true }, // 隐藏列，用作合并主键
+  { 
+    header: '项目基本信息',
+    children: [
+      { header: '项目名称', prop: 'name', mergeable: true },
+      { header: '负责人', prop: 'owner' }
+    ]
+  },
+  {
+    header: '进度详情',
+    children: [
+      { header: '阶段', prop: 'phase', mergeable: true },
+      { header: '完成度', prop: 'percent' }
+    ]
+  }
+];
+
+const data = [
+  { id: 1, name: '项目A', owner: 'Alice', phase: '设计', percent: '100%' },
+  { id: 1, name: '项目A', owner: 'Alice', phase: '开发', percent: '50%' },
+  { id: 2, name: '项目B', owner: 'Bob', phase: '测试', percent: '20%' }
+];
+
+ExcelExporter.exportExcel({
+  sheets: [{
+    sheetName: '多级表头示例',
+    columns,
+    data,
+    mergeOptions: {
+      mergeKey: 'id', // 按 id 合并
+      serialNumberColumn: true // 自动生成序号
+    }
+  }]
+});
+```
+
+### 2. 自定义合并策略
+
+支持三种合并策略：
+- `'auto'`: 全等比较（默认）。
+- `'regex'`: 正则匹配（例如忽略大小写）。
+- `'custom'`: 完全自定义函数。
+
+```javascript
+// 示例：忽略大小写和连字符的合并
+const customComparator = (a, b) => {
+  const normalize = str => String(str).replace(/-/g, '').toLowerCase();
+  return normalize(a) === normalize(b);
+};
+
+ExcelExporter.exportExcel({
+  sheets: [{
+    sheetName: '自定义合并',
+    columns: [{ header: '代码', prop: 'code', mergeable: true }, { header: '值', prop: 'value' }],
+    data: [
+      { code: 'ABC-01', value: 10 },
+      { code: 'abc01', value: 20 }, // 将与上一行合并
+      { code: 'XYZ-99', value: 30 }
+    ],
+    mergeOptions: {
+      mergeKey: 'code',
+      mergeStrategy: 'custom',
+      customComparator: customComparator
+    }
+  }]
+});
+```
+
+### 3. 图片与样式定制
+
+```javascript
+ExcelExporter.exportExcel({
+  fileName: '图片与样式.xlsx',
+  styleOptions: {
+    // 标题样式：大号蓝色字
+    title: { fontSize: 24, bold: true, colorRgb: '0000FF' },
+    // 表头样式：黄色背景（需通过 defaultStyles 深入配置，此处仅演示字体）
+    header: { fontSize: 14, bold: true },
+    // 正文样式：左对齐
+    body: { horizontal: 'left' }
+  },
+  sheets: [{
+    sheetName: '产品图册',
+    title: '2024新品展示',
+    columns: [
+      { header: '产品名称', prop: 'name' },
+      { header: '产品图片', prop: 'imgUrl', cellType: 'image' } // 自动转为链接
+    ],
+    data: [
+      { name: '运动鞋', imgUrl: 'https://example.com/shoe.jpg' },
+      { name: 'T恤', imgUrl: 'not-a-url' } // 非URL保持原样
+    ],
+    // 自定义行高
+    customOptions: {
+      rowHeights: {
+        title: 40,
+        header: 30,
+        dataDefault: 50 // 数据行高一点以便展示
+      }
+    }
+  }]
+});
+```
+
+## 注意事项
+
+1.  **图片导出**：目前仅支持将图片 URL 导出为“查看图片”的超链接文本，不支持直接嵌入图片文件（受限于底层库）。
+2.  **序号列**：启用 `serialNumberColumn` 时，序号是基于 `mergeKey` 的分段生成的，并且会与左侧合并行对齐。
+3.  **大数据量**：对于超过几千行的数据，建议使用 `exportExcelAsync`，以避免浏览器或 Node.js 进程假死。
+4.  **边框**：默认情况下，合并单元格的边框会自动补齐，无需手动处理。
+
+## License
+
+MIT

package/example/demo.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>DexSimpleReportExcel Demo</title>
+    <style>
+        body { font-family: Arial, sans-serif; padding: 20px; }
+        .container { max-width: 800px; margin: 0 auto; }
+        code { background: #f4f4f4; padding: 2px 5px; border-radius: 3px; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>DexSimpleReportExcel Demo</h1>
+        <p>This library is designed primarily for Node.js environments or frontend projects using bundlers (Webpack/Vite).</p>
+        
+        <h2>Usage Example (Node.js)</h2>
+        <pre><code>
+import { ExcelExporter } from 'dex-simple-report-excel';
+
+const sheets = [{
+    sheetName: 'Demo',
+    columns: [{ header: 'Name', prop: 'name' }],
+    data: [{ name: 'Alice' }, { name: 'Bob' }]
+}];
+
+ExcelExporter.exportExcel({ sheets });
+        </code></pre>
+
+        <p>See <code>example/test.js</code> for a runnable Node.js example.</p>
+    </div>
+</body>
+</html>

package/example/test.js

@@ -0,0 +1,40 @@
+import { ExcelExporter } from '../src/index.js';
+import path from 'path';
+
+// Create a simple test
+const testExport = () => {
+    console.log('Starting export test...');
+
+    const sheets = [
+        {
+            sheetName: 'TestSheet',
+            title: 'Test Report',
+            columns: [
+                { header: 'ID', prop: 'id' },
+                { header: 'Name', prop: 'name' },
+                { header: 'Value', prop: 'value' }
+            ],
+            data: [
+                { id: 1, name: 'Item 1', value: 100 },
+                { id: 2, name: 'Item 2', value: 200 }
+            ]
+        }
+    ];
+
+    const result = ExcelExporter.exportExcel({
+        sheets,
+        fileName: 'test_output.xlsx',
+        styleOptions: {
+            title: { fontSize: 18, bold: true },
+            header: { fontSize: 14, bold: true }
+        }
+    });
+
+    if (result) {
+        console.log('Export successful! Check test_output.xlsx');
+    } else {
+        console.error('Export failed.');
+    }
+};
+
+testExport();

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "dex-simple-report-excel",
+    "version": "1.0.0",
+    "description": "DexSimpleReportExcel - 一款敏捷简单的Excel表格前端导出工具，极简API，一键导出，适配前端场景",
+    "main": "src/index.js",
+    "type": "module",
+    "types": "src/index.d.ts",
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "excel",
+        "report",
+        "export",
+        "导出excel",
+        "前端导出excel",
+        "excel export",
+        "DexSimpleReportExcel",
+        "简单excel导出",
+        "敏捷导出工具"
+    ],
+    "author": "無彦祖 <baochunsan@163.com>",
+    "license": "MIT",
+    "dependencies": {
+        "xlsx-js-style": "^1.2.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/baochunsan/dex-simple-report-excel.git"
+    },
+    "bugs": {
+        "url": "https://gitee.com/baochunsan/dex-simple-report-excel/issues"
+    },
+    "homepage": "https://gitee.com/baochunsan/dex-simple-report-excel#readme"
+}

package/src/index.d.ts

@@ -0,0 +1,230 @@
+/**
+ * 样式微调配置
+ */
+export interface StyleTuning {
+    /** 字体名称，例如 "宋体", "Arial" */
+    fontName?: string;
+    /** 字体大小 */
+    fontSize?: number;
+    /** 是否加粗 */
+    bold?: boolean;
+    /** 字体颜色 (RGB Hex)，例如 "FF0000" */
+    colorRgb?: string;
+    /** 水平对齐方式 */
+    horizontal?: 'left' | 'center' | 'right';
+    /** 垂直对齐方式 */
+    vertical?: 'top' | 'center' | 'bottom';
+    /** 是否自动换行 */
+    wrapText?: boolean;
+}
+
+/**
+ * 全局样式配置选项
+ * 用于统一设置标题、表头和正文的样式
+ */
+export interface StyleOptions {
+    /** 表格大标题样式 */
+    title?: StyleTuning;
+    /** 表头样式 */
+    header?: StyleTuning;
+    /** 正文单元格样式 */
+    body?: StyleTuning;
+}
+
+/**
+ * 默认样式对象
+ * 直接传递给 xlsx-js-style 的样式对象
+ */
+export interface DefaultStyles {
+    /** 默认单元格样式 */
+    cellStyle?: object;
+    /** 默认表头样式 */
+    headCellStyle?: object;
+    /** 默认标题样式 */
+    titleCellStyle?: object;
+}
+
+/**
+ * 列定义节点
+ * 支持多级表头嵌套
+ */
+export interface ColumnNode {
+    /** 表头显示文字 */
+    header?: string;
+    /** 标签（别名，通常同 header） */
+    label?: string;
+    /** 数据字段属性名 */
+    prop?: string;
+    /** 是否隐藏该列 */
+    hidden?: boolean;
+    /** 是否允许该列进行行合并 */
+    mergeable?: boolean;
+    /** 单元格类型：'text' 为普通文本，'image' 为图片链接 */
+    cellType?: 'text' | 'image';
+    /** 子表头（用于多级表头） */
+    children?: ColumnNode[];
+    /** 其他自定义属性 */
+    [key: string]: any;
+}
+
+/**
+ * 行合并配置选项
+ */
+export interface MergeOptions {
+    /** 主要合并依据的字段名 */
+    mergeKey: string;
+    /** 是否开启行合并功能 */
+    rowMerge?: boolean;
+    /** 是否合并空值（即字段值为 null/undefined 时是否参与合并） */
+    mergeNull?: boolean;
+    /** 排除合并的列名数组 */
+    excludeColumns?: string[];
+    /** 子级合并是否严格依赖父级（通常用于多级合并） */
+    childrenStrict?: boolean;
+    /** 是否默认合并子级 */
+    mergeChildrenByDefault?: boolean;
+    /** 合并策略：'auto' (自动), 'regex' (正则), 'custom' (自定义) */
+    mergeStrategy?: 'auto' | 'regex' | 'custom';
+    /** 正则表达式配置（当 strategy 为 regex 时使用） */
+    regex?: RegExp | string;
+    /** 自定义比较函数（当 strategy 为 custom 时使用） */
+    customComparator?: (a: any, b: any, rowA?: any, rowB?: any, key?: string) => boolean;
+    /** 分块处理大小（用于优化大数据量性能） */
+    chunkSize?: number;
+    /** 是否添加序号列 */
+    serialNumberColumn?: boolean;
+    /** 序号列的表头名称 */
+    serialNumberHeader?: string;
+    /** 序号起始值 */
+    serialNumberStartAt?: number;
+}
+
+/**
+ * 行高配置
+ */
+export interface RowHeights {
+    /** 标题行高度 */
+    title?: number;
+    /** 表头行高度 */
+    header?: number;
+    /** 数据行默认高度 */
+    dataDefault?: number;
+    /** 指定特定索引行的高度 */
+    dataByIndex?: Record<number, number>;
+}
+
+/**
+ * 序号列配置（旧版兼容或特定场景使用）
+ */
+export interface IndexColumn {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 表头名称 */
+    header?: string;
+    /** 起始值 */
+    startAt?: number;
+}
+
+/**
+ * 自定义选项
+ * 用于传递给 xlsx 处理的底层参数
+ */
+export interface CustomOptions {
+    /** 列宽配置 */
+    cols?: Array<{ wch: number }>;
+    /** 行数据（通常自动生成） */
+    rows?: Array<any>;
+    /** 字段过滤顺序 */
+    filterVal?: string[];
+    /** 表头字段 */
+    tHeader?: string[];
+    /** 是否应用边框 */
+    applyBorders?: boolean;
+    /** 行高配置 */
+    rowHeights?: RowHeights;
+    /** 序号列配置 */
+    indexColumn?: IndexColumn;
+    /** 其他属性 */
+    [key: string]: any;
+}
+
+/**
+ * 工作表配置
+ */
+export interface SheetOptions {
+    /** 工作表名称 */
+    sheetName?: string;
+    /** 表格大标题（合并第一行显示） */
+    title?: string;
+    /** 列定义（支持嵌套） */
+    columns: ColumnNode[];
+    /** 数据源 */
+    data: Array<Record<string, any>>;
+    /** 自定义底层选项 */
+    customOptions?: CustomOptions;
+    /** 合并选项 */
+    mergeOptions?: MergeOptions;
+}
+
+/**
+ * 导出选项
+ */
+export interface ExportOptions {
+    /** 工作表列表 */
+    sheets: SheetOptions[];
+    /** 导出文件名 */
+    fileName?: string;
+    /** 默认样式配置 */
+    defaultStyles?: DefaultStyles;
+    /** 是否显示边框 */
+    showBorder?: boolean;
+    /** 简化的样式配置选项 */
+    styleOptions?: StyleOptions;
+}
+
+/**
+ * 高级 Excel 导出类
+ */
+export class ExcelExporter {
+    /**
+     * 同步导出 Excel
+     * @param options 导出选项
+     * @returns 是否成功
+     */
+    static exportExcel(options: ExportOptions): boolean;
+    
+    /**
+     * 异步导出 Excel
+     * @param options 导出选项
+     * @returns Promise<是否成功>
+     */
+    static exportExcelAsync(options: ExportOptions): Promise<boolean>;
+}
+
+/**
+ * 同步导出 Excel 函数
+ * @param options 导出选项
+ */
+export function exportExcel(options: ExportOptions): boolean;
+
+/**
+ * 异步导出 Excel 函数
+ * @param options 导出选项
+ */
+export function exportExcelAsync(options: ExportOptions): Promise<boolean>;
+
+/**
+ * 格式化 JSON 数据为二维数组
+ * @param filterVal 字段顺序
+ * @param jsonData 原始数据
+ */
+export function formatJson(filterVal: string[], jsonData: any[]): any[][];
+
+/**
+ * 显示警告信息
+ * @param message 消息内容
+ * @param title 标题
+ */
+export function warning(message: string, title?: string): void;
+
+export default ExcelExporter;