xlsx_dj

基于 ExcelJS + BigNumber.js 封装的 Excel 多级表头导出库。

安装

npm i xlsx_dj
# 需同时安装 peer 依赖
npm i exceljs bignumber.js tools_dj

导出

import { BigNumber, ExcelJS, XLSX } from 'xlsx_dj'
// 或默认导出
import xlsx_pkg from 'xlsx_dj' // { BigNumber, ExcelJS, XLSX }

快速开始

import { XLSX } from 'xlsx_dj'

const xlsx = new XLSX({
  header: [
    { name: '姓名', key: 'name' },
    { name: '年龄', key: 'age' },
  ],
  data: [
    { name: '张三', age: 25 },
    { name: '李四', age: 30 },
  ],
})

xlsx.download('人员信息.xlsx')

多级表头

通过 children 嵌套实现多级表头，自动合并单元格：

const xlsx = new XLSX({
  header: [
    {
      name: '基本信息',
      children: [
        { name: '姓名', key: 'name' },
        { name: '年龄', key: 'age' },
      ],
    },
    { name: '部门', key: 'dept' },
  ],
  data: [
    { name: '张三', age: 25, dept: '技术部' },
  ],
})

效果：基本信息 跨两列合并，下方拆分为 姓名 和 年龄。

配置项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | header | Array | [] | 表头配置，支持 children 嵌套 | | data | Array | [] | 行数据数组 | | sheetName | String | 'sheet1' | 工作表名称 | | name | String | 'default' | 下载时的默认文件名 | | defaultWidth | String/Number | '100' | 默认列宽(px)，自动转换为字符宽度 | | defaultHeight | String/Number | '40' | 默认行高(px)，自动转换为pt | | showSame | Boolean | false | 是否启用自定义数据映射（配合 func 使用） | | func | Object | {} | 自定义数据映射，key对应字段名，值为函数或固定值 | | mergeList | Array | [] | 额外的合并单元格地址，如 ['A1:B1'] | | showGridLines | Boolean | true | 是否显示网格线 | | key | String | 'key' | header中字段key的属性名 | | nameKey | String | 'name' | header中表头显示名的属性名 | | childrenKey | String | 'children' | header中子级表头的属性名 | | px_tx | String/Number | '0.136' | px转字符宽度的系数 | | px_pt | String/Number | '0.75' | px转pt行高的系数 | | base | Number | 1 | 尺寸转换的倍率基数 |

header 配置项

| 参数 | 类型 | 说明 | |------|------|------| | name | String | 表头显示名称 | | key | String | 对应数据字段名 | | width | String/Number | 该列宽度(px) | | children | Array | 子级表头配置，嵌套结构 | | exclude | Boolean | 设为 true 则跳过该列 |

方法

download(downName?)

浏览器端下载 xlsx 文件。

xlsx.download()                  // 使用 option.name + '.xlsx' 作为文件名
xlsx.download('自定义名称.xlsx')  // 指定完整文件名（需自行加 .xlsx 后缀）

pxToTx(data)

px 转字符宽度，用于列宽转换。

xlsx.pxToTx(100) // "13.6"

pxToPt(data)

px 转 pt，用于行高转换。

xlsx.pxToPt(40) // "30"

indexToCell(col, row)

列索引+行索引 转 Excel 单元格地址。

xlsx.indexToCell(0, 0)  // "A1"
xlsx.indexToCell(2, 1)  // "C2"

getMergeRow(rowIndex, key, list)

判断某个键在顺序列表中连续相同的个数，用于行合并场景。

const list = [
  { dept: '技术部', name: '张三' },
  { dept: '技术部', name: '李四' },
  { dept: '产品部', name: '王五' },
]

// 单键判断
xlsx.getMergeRow(0, 'dept', list)  // { merge: 2, endIndex: 2 }

// 多键联合判断
xlsx.getMergeRow(0, ['dept', 'name'], list)  // { merge: 1, endIndex: 1 }

返回值：

• merge — 从 rowIndex 开始连续相同的行数
• endIndex — 连续相同区域的结束行索引

showSame + func 自定义数据映射

当 showSame=true 时，可通过 func 对指定字段自定义取值：

const xlsx = new XLSX({
  header: [
    { name: '姓名', key: 'name' },
    { name: '状态', key: 'status' },
  ],
  data: [
    { name: '张三', status: 1 },
    { name: '李四', status: 0 },
  ],
  showSame: true,
  func: {
    status: (row: any) => row.status === 1 ? '在职' : '离职',
  },
})

func 的 key 对应字段名，值可以是函数（接收当前行数据）或固定值。

依赖说明

| 依赖 | 用途 | 安装方式 | |------|------|---------| | exceljs | Excel 文件生成 | peerDependency，消费方安装 | | bignumber.js | 精确数值计算 | peerDependency，消费方安装 | | tools_dj | 工具方法（is、is_empty 等） | peerDependency，消费方安装 |

本库不打包以上依赖，由消费方控制版本。