# dex-simple-report-excel

**Repository Path**: baochunsan/dex-simple-report-excel

## Basic Information

- **Project Name**: dex-simple-report-excel
- **Description**: DexSimpleReportExcel - 一款敏捷简单的Excel表格前端导出工具，极简API，一键导出，适配前端场景
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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