ejsExcel API参考手册：所有函数和配置项的详细说明

ejsExcel API参考手册：所有函数和配置项的详细说明

【免费下载链接】ejsExcelnodejs excel template engine. node export excel项目地址: https://gitcode.com/gh_mirrors/ej/ejsExcel

ejsExcel是一个功能强大的Node.js Excel模板引擎，它允许开发者通过模板文件快速生成Excel文档。本参考手册将详细介绍ejsExcel的核心函数、配置选项和使用方法，帮助开发者充分利用这个工具提升Excel文件生成效率。

核心功能函数

1. renderExcel - 异步渲染Excel模板

renderExcel是ejsExcel的核心函数，用于异步渲染Excel模板并生成最终的Excel文件缓冲区。

函数定义：

async function renderExcel(exlBuf, _data_, opt)

参数说明：

• exlBuf(Buffer)：Excel模板文件的缓冲区
• _data_(Object)：模板渲染所需的数据对象
• opt(Object)：渲染选项配置

返回值：

• Promise ：生成的Excel文件缓冲区

使用示例：

const fs = require('fs'); const ejsExcel = require('ejsExcel'); async function generateExcel() { const templateBuf = fs.readFileSync('template.xlsx'); const data = { title: '销售报表', items: [...] }; const excelBuf = await ejsExcel.renderExcel(templateBuf, data); fs.writeFileSync('output.xlsx', excelBuf); }

2. renderExcelCb - 回调风格的Excel渲染

对于习惯使用回调函数的开发者，ejsExcel提供了renderExcelCb函数，它是renderExcel的回调风格版本。

函数定义：

function renderExcelCb(exlBuf, _data_, opt, callback)

参数说明：

• exlBuf(Buffer)：Excel模板文件的缓冲区
• _data_(Object)：模板渲染所需的数据对象
• opt(Object)：渲染选项配置（可选）
• callback(Function)：渲染完成后的回调函数

回调函数参数：

• err(Error)：错误信息，如果渲染成功则为null
• buf2(Buffer)：生成的Excel文件缓冲区

3. getExcelArr - 解析Excel文件为数组

getExcelArr函数用于将Excel文件解析为JavaScript数组，方便在模板中处理表格数据。

函数定义：

async function getExcelArr(buffer)

参数说明：

• buffer(Buffer)：Excel文件的缓冲区

返回值：

• Promise ：解析后的Excel数据数组

单元格操作函数

4. charToNum - 列字母转数字

将Excel列字母（如"A"、"BC"）转换为对应的数字索引。

函数定义：

function charToNum(str)

参数：

• str(String)：Excel列字母

返回值：

• Number：对应的列索引（从0开始）

示例：

charToNum("A"); // 0 charToNum("B"); // 1 charToNum("AA"); // 26

5. charPlus - 列字母递增

将Excel列字母递增，类似于Excel中的列自动填充功能。

函数定义：

function charPlus(str, num)

参数：

• str(String)：基础列字母
• num(Number)：递增数量

返回值：

• String：递增后的列字母

示例：

charPlus("A", 1); // "B" charPlus("Z", 1); // "AA" charPlus("AB", 3); // "AE"

日期处理函数

6. date2Num - 日期转Excel序列号

将JavaScript日期对象转换为Excel日期序列号。

函数定义：

function date2Num(date)

参数：

• date(Date)：JavaScript日期对象

返回值：

• Number：Excel日期序列号

7. num2Date - Excel序列号转日期

将Excel日期序列号转换为JavaScript日期对象。

函数定义：

function num2Date(valTmp)

参数：

• valTmp(Number)：Excel日期序列号

返回值：

• Date：对应的JavaScript日期对象

模板辅助函数

8.ps- 处理字符串单元格

在模板中用于处理字符串类型的单元格数据，自动处理XML转义和共享字符串。

函数定义：

data._ps_ = function (str, buf)

使用示例：

<%= _ps_(data.title, buffer) %>

9.pi- 处理数字单元格

在模板中用于处理数字类型的单元格数据，支持日期格式化。

函数定义：

data._pi_ = function (str, buf)

使用示例：

<%= _pi_(data.price, buffer) %>

10.pf- 处理公式单元格

在模板中用于处理Excel公式，自动设置单元格类型为公式。

函数定义：

data._pf_ = function (str, buf)

使用示例：

<%= _pf_("SUM(A1:A10)", buffer) %>

工作表操作函数

11.hideSheet- 隐藏工作表

在模板中隐藏指定的工作表。

函数定义：

data._hideSheet_ = function (fileName)

参数：

• fileName(String)：工作表文件名

使用示例：

<% _hideSheet_("xl/worksheets/sheet2.xml") %>

12.showSheet- 显示工作表

在模板中显示指定的工作表（如果之前被隐藏）。

函数定义：

data._showSheet_ = function (fileName)

参数：

• fileName(String)：工作表文件名

13.deleteSheet- 删除工作表

从Excel文件中删除指定的工作表。

函数定义：

data._deleteSheet_ = function (fileName)

参数：

• fileName(String)：工作表文件名

图片和二维码函数

14.img- 插入图片

在Excel工作表中插入图片。

函数定义：

data._img_ = async function(imgOpt, fileName, rowNum, cellNum)

参数：

• imgOpt(Object|String|Buffer)：图片选项或图片路径或图片缓冲区
• fileName(String)：目标工作表文件名
• rowNum(Number)：图片起始行号
• cellNum(Number)：图片起始列号

15.qrcode- 生成二维码

在Excel工作表中生成并插入二维码图片。

函数定义：

data._qrcode_ = async function (imgOpt, fileName, rowNum, cellNum)

参数：

• imgOpt(Object)：二维码选项，必须包含text属性
• fileName(String)：目标工作表文件名
• rowNum(Number)：二维码起始行号
• cellNum(Number)：二维码起始列号

使用示例：

<% _qrcode_({text: 'https://example.com', margin: 2}, 'xl/worksheets/sheet1.xml', 5, 3) %>

配置选项

渲染选项 (opt)

在调用renderExcel或renderExcelCb时，可以传入配置选项对象，控制渲染行为：

• notRenderSheets(Array)：指定不需要渲染的工作表名称数组
• cachePath(String)：缓存路径，用于缓存模板解析结果提高性能

示例：

const opt = { notRenderSheets: ['Sheet2', 'Sheet3'], cachePath: './cache' }; const excelBuf = await ejsExcel.renderExcel(templateBuf, data, opt);

过滤器函数

ejsExcel提供了一系列内置过滤器，位于filters.js文件中，可以在模板中直接使用：

• first- 获取数组第一个元素
• last- 获取数组最后一个元素
• capitalize- 首字母大写
• downcase- 转为小写
• upcase- 转为大写
• sort- 排序数组
• sort_by- 按指定属性排序
• size/length- 获取长度
• plus/minus/times/divided_by- 数学运算
• join- 数组转字符串
• truncate- 截断字符串
• replace- 替换字符串
• prepend/append- 添加元素到数组
• map- 数组映射
• reverse- 反转数组
• get- 获取对象属性
• json- 转为JSON字符串

使用示例：

<%= data.names | join(', ') %> <%= data.price | plus(10) | times(0.8) %> <%= data.description | truncate(50) %>

错误处理

在使用ejsExcel时，建议使用try/catch捕获可能的错误：

try { const excelBuf = await ejsExcel.renderExcel(templateBuf, data); fs.writeFileSync('output.xlsx', excelBuf); } catch (err) { console.error('Excel生成失败:', err); }

常见错误包括：模板文件损坏、数据格式错误、工作表操作不当等。详细错误信息会帮助定位问题所在。

安装与使用

要使用ejsExcel，首先需要通过npm安装：

npm install ejsExcel

或者直接克隆仓库：

git clone https://gitcode.com/gh_mirrors/ej/ejsExcel

基本使用流程：

1. 准备Excel模板文件
2. 准备渲染数据
3. 调用ejsExcel渲染函数
4. 保存生成的Excel文件

ejsExcel为Node.js开发者提供了强大的Excel生成能力，通过模板引擎的方式极大简化了Excel文件的创建过程。无论是生成报表、导出数据还是创建复杂的Excel文档，ejsExcel都能满足你的需求。

【免费下载链接】ejsExcelnodejs excel template engine. node export excel项目地址: https://gitcode.com/gh_mirrors/ej/ejsExcel