在自动化流程开发中，Excel文件操作是一项非常高频的基础需求。无论是批量处理用户数据、导出报表，还是作为配置文件的读写媒介，Excel都是绕不开的环节。本文将系统梳理冰狐平台原生提供的Excel操作API，从创建、写入、读取到行列管理，给出完整的方法说明与代码示例。

一、Excel 对象与文件路径约定

冰狐平台通过内置的Excel构造函数来操作Excel文件。使用前需要先实例化：

var excel = new Excel();

平台对文件路径有明确的约定：文件名不需要添加后缀名（如.xls），平台会自动处理。路径参数为选填，默认为空字符串，此时文件存放在手机目录下的aznfz文件夹里。如果指定path参数，则可以自定义存放路径。

二、创建 Excel 文件（create）

创建新文件使用create方法，返回布尔值表示操作是否成功。

方法签名：

excel.create(fileName, colTitle, path)

示例：创建名为temp的Excel文件，列标题分别为“名称”、“值”、“价格”：

var excel = new Excel(); var ret = excel.create('temp', ['名称', '值', '价格']); console.log('create ret:' + ret);

创建成功后，文件即生成在指定目录下，后续的写入操作基于此文件进行。

三、打开已有文件（open）

如果需要操作已存在的Excel文件，使用open方法。

方法签名：

excel.open(fileName, path)

返回布尔值表示是否成功打开文件。注意：read方法只能在open成功调用后才能使用。

四、写入数据

1. addRow —— 按行写入

addRow用于向文件写入一行数据，返回布尔值。

方法签名：

excel.addRow(data, row)

示例：

excel.addRow(['jack', '经济', 112]);

2. append —— 追加到末尾

append是addRow的简化版本，专门用于在文件末尾添加一行数据。调用成功后会立即写入文件，无需额外操作。

方法签名：

excel.append(data)

示例：

var excel = new Excel(); excel.open('temp'); excel.append(['hello', 111]); excel.close();

append与addRow的核心区别在于：append固定追加到末尾且立即落盘，而addRow可以通过row参数指定任意行号写入。

五、关闭文件（close）

所有操作完成后，务必调用close方法关闭文件。

excel.close();

关闭文件不仅释放资源，也确保所有缓冲数据完整写入磁盘。建议在任何写入操作结束后都显式调用close。

六、读取数据（read）

read方法用于读取Excel中的数据，返回数组。注意：必须先调用open成功打开文件后才能使用read。

方法签名：

excel.read(row)

用法示例：

excel.open('temp'); var allData = excel.read(); // 读取所有数据 var rowData = excel.read(2); // 读取第2行数据 console.log(allData); excel.close();

七、获取行列数（rows / columns）

rows和columns方法分别返回文件的总行数和总列数。

var rowCount = excel.rows(); var colCount = excel.columns(); console.log('总行数：' + rowCount + '，总列数：' + colCount);

这两个方法在遍历数据或进行边界检查时非常实用。

八、删除操作（removeRow / removeColumn）

1. removeRow —— 删除指定行

删除指定行号的数据。

excel.removeRow(3); // 删除第3行

2. removeColumn —— 删除指定列

删除指定列号的数据。

excel.removeColumn(2); // 删除第2列

注意：行号和列号均从1开始计数（与常规表格习惯一致）。

九、完整流程示例

下面是一个完整的操作流程，覆盖创建、写入、读取、修改和关闭的全链路：

// 1. 创建实例 var excel = new Excel(); // 2. 创建新文件 var ret = excel.create('sales_data', ['产品', '销量', '单价']); console.log('创建结果：' + ret); // 3. 写入多行数据 excel.addRow(['手机', 120, 2999]); excel.addRow(['平板', 85, 3999]); excel.append(['耳机', 200, 499]); // 4. 读取所有数据并输出 var all = excel.read(); console.log('当前数据：', all); // 5. 获取行列数 console.log('行数：' + excel.rows() + '，列数：' + excel.columns()); // 6. 删除第2行 excel.removeRow(2); // 7. 再次读取验证 var afterDelete = excel.read(); console.log('删除后数据：', afterDelete); // 8. 关闭文件 excel.close(); console.log('操作完成');

十、常见问题与注意事项

1. 文件名不需要加后缀：无论是create还是open，传入的fileName都不需要带.xls或.xlsx后缀，平台会自动处理。

2. 数据长度必须与列数一致：调用addRow或append时，传入的数据数组长度必须与创建时设定的列标题数量相同，否则操作会失败。

3. read 必须在 open 之后：read方法依赖已打开的文件句柄，未调用open直接read会导致错误。

4. 及时 close：写入操作完成后建议立即调用close，避免数据丢失或文件占用问题。

5. 路径说明：不指定path时，文件默认存放在手机目录的aznfz文件夹下。如需存放到其他位置，可通过path参数指定绝对路径。