[前端/JavaScript] 实作汇出excel下载按钮的超好用套件：ExcelJS（上）- 基础介绍与教学

简介

官方github连结： 英文文档 、 中文文档

ExcelJS 这个套件可以高弹性的将资料汇出成excel档案
（原理：透过套件转成blob格式，再透过创建URL并触发来触发下载）

也可以汇入excel变成json格式的资料

官方文件中提供了相当多操作的介绍，包括设定样式、插入图片、对资料做处理等等
接下来介绍的内容，只是会简单的讲解如何将资料汇出成excel档案（.xslx、.csv）

有时候真的没有需要那么华丽
只想要先有一颗可把资料变成excel可供人下载的按钮

而这个套件本身是透过JS ES6的class来把方法封装
让工程师自行使用这些方法来建构你各位想要的excel资料

和按钮啊、画面啊、事件绑定之类的没有关连
这一篇会着重在如何用js去控制你的excel内容

预告：下一篇教学会讲解如何在react中使用这个套件

环境建置

开始使用

接下来大致上分三个步骤：建立表格、填塞资料、汇出excel并触发下载
而这些步骤都是在触发按下按钮之后所执行的，也就是说机制与流程是：

按下按钮
⇒ 触发onClick function
⇒ 在function内建立表格、填塞资料、汇出excel并触发下载

真的懒得看分解的话
最后面也有简易的程式码示範这个onClick function的全貌

那我们先开始分步骤讲解这个onClick function内的内容：

1. 建立表格

这个套件汇出的是一个class，并把所有资料操作、设定方法都封装在class内
所以第一步我们先new出这个class 的实例

const workbook = new ExcelJs.Workbook();

接下来所有操作都会围绕着这个名称为 workbook 的物件上

目前的workbook里面是一个空档案，里面没有任何工作表
所以我们要添加工作表的时候就使用：

const sheet = workbook.addWorksheet('工作表名称');

工作表名称可自订任意type为string的内容
使用addWorksheet 这个方法
会在我们的workbook 物件中增加一个表格，并回传他的物件

顺带解释一下，
所谓的「工作表」就是这个下面像是分页一样的东西

一个试算表里面可以有多个工作表

因此如果要第二个表格就只要继续使用

const sheet2 = workbook.addWorksheet('工作表2'); 这样的形式就可以了

2. 填塞资料

在一个工作表内，可以从任意位置开始塞任意大小的资料
将会使用 sheet.addTable 方法 ，参数塞这个表格的资料与格式，
根据columns和rows 这两个参数提供的阵列（array)，在向右和向下的格子里进行绘製

最基本的範例如下

sheet.addTable({    name: 'table名称',  // 表格内看不到的，算是key值，让你之后想要针对这个table去做额外设定的时候，可以指定到这个table    ref: 'A1', // 从A1开始    columns: [{name:'名字'},{name:'年龄'},{name:'电话'}],    rows: [['小明','20','0987654321'],['小美','23','0912345678']]});

根据这个设定，会跑出来的表格长这样
在这个addTable传递的参数里面
还可以设置style、设置一些有的没有的、冻结窗格之类的功能

那些内容有补充在后方，总之我们先创一个最简单的

进阶补充：表格资料可以不止塞一个

也就是一张sheet中，可以分区块的于各自指定的位置中，新增多个「table」

sheet.addTable({    name: 'table2',     ref: 'E5', // 从E5开始    headerRow: true,  // 有没有要放标头那一行 也就是columns的那行资料，如果设为flase就会那行直接无效    columns: [{name:'栏位1'},{name:'栏位2'},{name:'栏位3'}],    rows: [['小明','20','0987654321'],['小美','23','0912345678']]});

依此类推可以新增多个
就不用明明是两个不一样的资料表想塞在一个工作表
硬要想办法算位置让他们错开之类的

3. 汇出excel并触发下载

在塞完所有的资料之后
使用异步的方法：workbook.xlsx.writeBuffer() 来打包资料
打包好的资料会以Promise 的形式回传

可以用.then去接收
也可以把整个onClick function标记成async ，然后使用await来接收
接收资料、创建连结、触发下载的方式如下

// 表格里面的资料都填写完成之后，订出下载的callback function// 异步的等待他处理完之后，创建url与连结，触发下载workbook.xlsx.writeBuffer().then((content) => {const link = document.createElement("a");  const blobData = new Blob([content], {    type: "application/vnd.ms-excel;charset=utf-8;"  });  link.download = '测试的试算表.xlsx';  link.href = URL.createObjectURL(blobData);  link.click();});

整体範例

onClick function 定义 （js版本）

import ExcelJs from "exceljs";  function onClick(){    const workbook = new ExcelJs.Workbook(); // 创建试算表档案    const sheet = workbook.addWorksheet('工作表範例1'); //在档案中新增工作表 参数放自订名称sheet.addTable({ // 在工作表里面指定位置、格式并用columsn与rows属性填写内容    name: 'table名称',  // 表格内看不到的，让你之后想要针对这个table去做额外设定的时候，可以指定到这个table    ref: 'A1', // 从A1开始    columns: [{name:'名字'},{name:'年龄'},{name:'电话'}],    rows: [['小明','20','0987654321'],['小美','23','0912345678']]});    // 表格里面的资料都填写完成之后，订出下载的callback function// 异步的等待他处理完之后，创建url与连结，触发下载  workbook.xlsx.writeBuffer().then((content) => {const link = document.createElement("a");    const blobData = new Blob([content], {      type: "application/vnd.ms-excel;charset=utf-8;"    });    link.download = '测试的试算表.xlsx';    link.href = URL.createObjectURL(blobData);    link.click();  });}

其实就是把那些步骤合在一起变成 onClick function

实际使用就看你使用什么框架，或原生js、jQuery + html
绘製一个button ，绑定onClick事件
使按钮按下后会进行「建立表格->塞资料->触发下载」的程序

这边提供一个简易的线上Demo: 下载excel按钮範例(原生js+html)

下载之后就会得到这样的档案

进阶：设置表格或栏位样式、以及其他常用的进阶功能

这边不会全部都介绍（真的要全部就去看官方文档，反正有翻译...）
只会提出几个比较实用/常用/简单的功能，
以及讲解到底要怎么把这些功能设置上去

设置属性的方式

设置 工作簿/工作表/Table/栏位 的属性有两种方式

第一种是在使用workbook.addWorksheet / sheet.addTable 等方法的时候
用物件的方式把要设定的属性直接塞到Properties里面，例如：

const sheet = workbook.addWorksheet('sheetName',{views: [{showGridLines: false}]});const table = sheet.addTable({    name: 'table1',    headerRow: true,});

第二种则是先取得操纵该物件的变数，再直接对物件的属性做修改

取得物件变数的方式，除了储存addWorksheet / addTable创建时返回的变数之外
都可以用name或是id的方式 ( 注意： id从1开始不是从0开始 )
使用getWorksheet / getTable / getColumn /getRow 去寻找/指定，例如

// 按 name 提取工作表const sheet = workbook.getWorksheet('My Sheet');// 按 id 提取工作表，得到workbook中第一张添加进去的sheetconst sheet = workbook.getWorksheet(1);// 按 name 提取Tableconst table = workbook.getTable('My Table');// 按 id 提取Table，得到第一个add进去的tableconst table = workbook.getTable(1);// 按 name 提取（直）行const column = workbook.getColumn('My Column');// 按 id 提取行 => 取得第一行 （A）const column = workbook.getColumn(1);// 按 name 提取（横）列const row = workbook.getRow('My Row');// 按 id 提取列 => 取得第一列 （1）const row = workbook.getRow(1);// 然后直接对该物件的属性做赋sheet.views = [{showGridLines: false}]table.headerRow = true

接下来是介绍可以设置的参数们

工作表 (Worksheet) 可设置的参数们

设置样式 views: Array<{[props: string]: any}>

views属性为一个阵列，阵列内可以有多个物件，
每个物件为{key: value}的型态

範例：

sheet.views = [{showGridLines: false},{state: 'frozen', xSplit: 2, ySplit: 3}// 还可以有其他项目]

以下为views中可设定的{ key: value } 们

是否显示网格 : { showGridLines: boolean }
预设：true
若设置为false ⇒ {showGridLines: false}
表格的网格就会消失，如图

冻结窗格： {state: 'frozen', xSplit: number, ySplit: number }
xSplit: 要冻结的（直）行数，如果只要冻结列，就填0或是不设置（undefined）
ySplit: 要冻结的（横）列数，如果只要冻结行，就填0或是不设置（undefined）

範例：{state: 'frozen', xSplit: 1, ySplit: 1} 将冻结第一行＆第一列

设置工作表标籤/分页颜色: properties.tabColor : {argb: string}
预设：undefined
可以设置工作表的标籤颜色 必须吃一个key值为argb的物件
值则为代表0~255的16进位数值共四组

範例: sheetproperties.tabColor = {argb: 'FF00FF00'} 则会把标籤设为绿色

效果图:

可以设置不同颜色真的很可爱

预设栏宽 : properties.defaultColWidth : number
预设: undefined
可以设置表格的预设栏宽，範例: sheetproperties.tabColor = 30

预设栏高: properties.defaultRowHeight: number
预设: 15

合併储存格: worksheet.mergeCells('start:end')
範例: worksheet.mergeCells('C1:D1')

针对指定的（直）行设定宽度: sheet.getColumn(number).width
(其实就是先取得column物件，然后对他的width做赋值)

範例：sheet.getColumn(3).width = 30
C行 （第三行）的宽度就会被拉大为30

结语

以上！ 希望这一篇可以提供给正在找这个套件教学的各位
下一篇将会示範如何在react中使用这个套件
以及示範将这个按钮包装成一个可重複使用的UI元件

[前端/ES6] 实作汇出excel下载按钮的超好用套件：ExcelJS（下）- 用React汇出excel （export excel）