pl-export-excel

简单、高效、灵活的 JavaScript Excel 导出工具

快速开始 查看示例

简单易用

极简 API 设计，一行代码即可实现 Excel 导出，无需复杂配置和学习成本

高度灵活

支持自定义表头、多级表头、单元格合并、样式定制等高级功能，满足各种导出需求

跨平台兼容

兼容所有现代浏览器，支持桌面端和移动端使用

轻量高效

体积小巧，无冗余依赖，导出速度快，即使处理大量数据也能保持流畅体验

样式定制

支持自定义字体、颜色、背景、边框等样式，导出的 Excel 美观专业

灵活扩展

支持自定义回调函数，可根据需求扩展功能，满足复杂业务场景

快速开始

只需三步，即可实现 Excel 导出功能

1

安装或引入

通过NPM or CDN 直接引入

<!-- npm 引入 -->
npm i pl-export-excel

<!-- CDN 引入 -->
<script src="https://gcore.jsdelivr.net/npm/pl-export-excel/dist/index.full.min.js"></script>
2

准备数据

准备表头和表格数据，支持数组格式

// 表头配置
const headers = [
  { title: "经销商名称", key: "names" },
  { title: "下单时间", key: "date" },
  { title: "订单编号", key: "orderNumber" },
  { title: "客户名称", key: "customerName" }
];

// 表格数据
const datas = Array.from({ length: 10 }, (_, idx) => ({
  names: "娃哈哈",
  date: "2023-11-20",
  orderNumber: idx + 1,
  customerName: "王小虎" + idx + 1
}));
3

调用导出函数

调用 exportJsonToExcel 函数，即可完成导出

// 导出 Excel
import { exportJsonToExcel } from 'pl-export-excel'
exportJsonToExcel({
  headers,
  datas,
  filename: "订单表格" // 可选，指定文件名
});

API 文档

详细的 API 配置说明，满足各种导出需求

exportJsonToExcel(options)

Excel 导出主函数，接收配置参数对象，方法返回Promise<void>

参数名 类型 是否必填 说明
datas Array 是 表格数据
headers Array 是 表头部配置, 配置描述请看文档下面
titleConfig Object 否 主标题配置, 配置描述请看文档下面
merges Array 否 合并单元格配置, 配置描述请看文档下面
multiHeader Array 否 多级头, 给表格设置多行头部,需要自己去合并单元格。
filename String 否 导出文件名称，默认值为 "excel-list"
autoWidth Boolean 否 宽度是否自适应, 默认值为false
bookType String 否 文件类型，默认值为 "xlsx"
styleCb Function 否 样式表? 自定义回调函数，可自定义单元格样式
xlsxStyleResourceUrl String 否 自定义xlsx样式资源地址，基本用不到

excelToJson(options)

把一个Excel File转成数组Json, 方法返回Promise<{ originalList: any[]; formatList: any[] }>

参数名 类型 是否必填 说明
file File 是 转换的文件
startRow number 否 指定某一行之前为消除标题条目；当表格有标题时，或者某些行你想跳过时这是非常有用的。
keys Array 否 转成数组对象必填，单元格每列它所对应的key值
xlsxStyleResourceUrl String 否 自定义xlsx样式资源地址，基本用不到

ts type declare

```ts
/** 主标题配置 */
export type ISubTitle = {
  /** 标题文本 */
  title: string | number;
  /** 需要合并行数 */
  rowNum: number;
  /** 需要合并列数-默认为headers字段的长度 */
  colNum?: number;
};

/** 表头部配置, 导出后表格头部的顺序就是数组的顺序 */
export type IHeaders = {
  /** 表头标题文本 */
  title: string | number;
  /** key值: 对应表格数据中的字段key名 */
  key: string;
}[];

/**
 * 合并单元格配置： c or r: 0开始计算
 * 示例：
 * {
     s: {
        // s为开始
        c: 0, //开始列, 0开始计算
        r: 0 //开始行, 0开始计算
      },
     e: {
        // e结束
        c: 5, //结束列, 0开始计算
        r: 1 //结束行, 0开始计算
      }
   }
 */
export type IMerges = { s: { c: number; r: number }; e: { c: number; r: number } };
```

示例演示

点击下方按钮，体验不同场景下的 Excel 导出效果

基础导出

最简单的 Excel 导出，包含基本表头和数据

// 指定某些字段导出
const headers = [
  { title: "经销商名称", key: "names" },
  { title: "下单时间", key: "date" },
  { title: "订单编号", key: "orderNumber" },
  { title: "客户名称", key: "customerName" }
];

const datas = Array.from({ length: 200 }, (_, idx) => ({
  names: "娃哈哈",
  date: "2023-11-20",
  orderNumber: idx + 1,
  orderState: "在线",
  orderPayState: "全付款",
  customerName: "王小虎" + idx + 1
}));

exportJsonToExcel({ headers, datas });

带标题导出

导出带有标题的 Excel，支持设置标题占用行数

exportJsonToExcel({
  headers: [
    { title: "经销商名称", key: "names" },
    { title: "下单时间", key: "date" },
    { title: "订单编号", key: "orderNumber" },
    { title: "客户名称", key: "customerName" },
    { title: "城市", key: "city" },
    { title: "地址", key: "address" }
  ],
  datas: list,
  filename: "11月订单表格",
  // 标题配置
  titleConfig: {
    title: "11月订单表格",
    rowNum: 2 // 标题占用2行
  }
});

高级导出（合并单元格 + 自定义样式）

支持多级表头、单元格合并和自定义样式的高级导出功能

exportJsonToExcel({
  headers: [
    { title: "经销商名称", key: "names" },
    { title: "下单时间", key: "date" },
    { title: "订单编号", key: "orderNumber" },
    { title: "客户名称", key: "customerName" },
    { title: "城市", key: "city" },
    { title: "地址", key: "address" }
  ],
  datas: list,
  filename: "12月订单表格",
  // 多级头, 二维数组里面的每一个数组代表一行
  multiHeader: [
    ["标题1", "", "", "", "", ""],
    // 为了合并头，需要设置当前行的每一个单元格，属于占位单元格
    ["", "", "", "", "", ""],
    ["标题2", "", "", "", "", ""]
  ],
  // 合并多级头为一个单元
  merges: [
    {
      s: {
        //s为开始
        c: 0, //开始列, 0开始计算
        r: 0 //开始行, 0开始计算
      },
      e: {
        //e结束
        c: 5, //结束列, 0开始计算
        r: 1 //结束行, 0开始计算
      }
    },
    {
      s: {
        //s为开始
        c: 0, //开始列, 0开始计算
        r: 2 //开始行, 0开始计算
      },
      e: {
        //e结束
        c: 5, //结束列, 0开始计算
        r: 2 //结束行, 0开始计算
      }
    }
  ],
  // 自定义单元格样式
  styleCb: function (cellKeys) {
    console.log(cellKeys)
    const obj = {};
    /**
      * 返回一个如obj = {
        // A1代表第一个单元格，对象为一个样式对象类型为：（IOriginalStyles）
      A1: {
        ...
      }
      }
    */
    obj[cellKeys[0]] = {
      fontFamily: "微软雅黑",
      fontSize: 16,
      color: "#CD0000",
      isBold: true,
      fgColor: "#AEEEEE"
    };
    obj[cellKeys[2]] = {
      fontFamily: "微软雅黑",
      fontSize: 16,
      color: "#33ff99",
      fgColor: "#CD950C"
    };

    for (let i = 0; i < cellKeys.length; i++) {
      // 给地址这一列设置样式
      if (cellKeys[i].includes("F")) {
        obj[cellKeys[i]] = {
          wrapText: true
        }
      }
    }

    return obj;
  }
});

excelToJson的使用

假如传入电子表格如图：

调用如下方法

const res = await excelToJson({
  file,
  startRow: 3,
  keys: ["names", "date", "orderNumber", "customerName", "city", "address"]
});
console.log(res);
/**
输出res:
[
 {
  address: "上海金沙江路200号",
  city: "上海",
  customerName: "王小虎01",
  date: "2023-11-20",
  names: "娃哈哈",
  orderNumber: "1"
 },
 ....
 ....
]
*/