在自动化脚本中如何操作excel文件？

在自动化流程开发中，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 参数指定绝对路径。