在自动化流程开发中，Excel文件操作是一项非常高频的基础需求。无论是批量处理用户数据、导出报表，还是作为配置文件的读写媒介，Excel都是绕不开的环节。本文将系统梳理冰狐平台原生提供的Excel操作API，从创建、写入、读取到行列管理，给出完整的方法说明与代码示例。
一、Excel 对象与文件路径约定
冰狐平台通过内置的Excel构造函数来操作Excel文件。使用前需要先实例化：
var excel = new Excel();
平台对文件路径有明确的约定：文件名不需要添加后缀名（如.xls），平台会自动处理。路径参数为选填，默认为空字符串，此时文件存放在手机目录下的aznfz文件夹里。如果指定path参数，则可以自定义存放路径。
二、创建 Excel 文件（create）
创建新文件使用create方法，返回布尔值表示操作是否成功。
方法签名：
excel.create(fileName, colTitle, path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fileName | string | 是 | 文件名，不需要加后缀 |
| colTitle | array | 是 | 列标题数组 |
| path | string | 否 | 路径，默认为空（aznfz目录） |
示例：创建名为temp的Excel文件，列标题分别为“名称”、“值”、“价格”：
var excel = new Excel(); var ret = excel.create('temp', ['名称', '值', '价格']); console.log('create ret:' + ret);创建成功后，文件即生成在指定目录下，后续的写入操作基于此文件进行。
三、打开已有文件（open）
如果需要操作已存在的Excel文件，使用open方法。
方法签名：
excel.open(fileName, path)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fileName | string | 是 | 文件名，不需要加后缀 |
| path | string | 否 | 路径，默认为空（aznfz目录） |
返回布尔值表示是否成功打开文件。注意：read方法只能在open成功调用后才能使用。
四、写入数据
1. addRow —— 按行写入
addRow用于向文件写入一行数据，返回布尔值。
方法签名：
excel.addRow(data, row)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| data | array | 是 | 数据数组，个数必须与列数一致 |
| row | integer | 否 | 行号，默认为 -1，表示在末尾追加 |
示例：
excel.addRow(['jack', '经济', 112]);
2. append —— 追加到末尾
append是addRow的简化版本，专门用于在文件末尾添加一行数据。调用成功后会立即写入文件，无需额外操作。
方法签名：
excel.append(data)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| data | array | 是 | 数据数组，个数必须与列数一致 |
示例：
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)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| row | integer | 否 | 行号，若不填则返回表格所有数据 |
用法示例：
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参数指定绝对路径。
