AsyncTest

Appearance

AstExcel 对象 ​

什么是 AstExcel？ ​

AstExcel 是 AsyncTest 在自定义脚本中提供的 Excel 文件操作对象，基于 openpyxl 封装，用于加载、读取和保存 Excel 文件。

AstExcel 可以与 AstFile 结合使用，实现从系统加载 Excel 文件、读取数据、修改后保存等操作。

你可以通过 at.AstExcel() 创建一个 Excel 对象。

基本用法 ​

python
# 创建 Excel 对象
excel = at.AstExcel()

# 加载 Excel 文件
workbook = await excel.async_load("data.xlsx")

# 读取数据
rows = workbook.get_rows()
print(rows)

加载 Excel ​

async_load() ​

异步方法 - 加载 Excel 文件

python
workbook = await excel.async_load(file, filename=None)

参数：

  • file: 文件来源，支持三种类型：
    • AstFile 对象：从 AstFile 加载
    • BytesIO 对象：从内存文件加载（此时 filename 必填）
    • str 字符串：从系统文件名加载
  • filename: 文件名（仅当 file 为 BytesIO 时必填）

返回值： AstWorkbook 对象（封装了 openpyxl 的 Workbook）

示例：

从系统文件名加载 ​

python
excel = at.AstExcel()
workbook = await excel.async_load("report.xlsx")

从 AstFile 加载 ​

python
ast_file = at.AstFile()
await ast_file.load_from_system("report.xlsx")

excel = at.AstExcel()
workbook = await excel.async_load(ast_file)

从 BytesIO 加载 ​

python
from io import BytesIO

file_data = BytesIO(b"...")  # Excel 文件字节
excel = at.AstExcel()
workbook = await excel.async_load(file_data, filename="data.xlsx")

保存 Excel ​

async_save() ​

异步方法 - 保存 Excel 文件

python
object_unique_key = await excel.async_save(cover_file=False)

参数：

  • cover_file: 是否覆盖原始文件（默认 False）

返回值： 文件唯一标识（字符串），可用于在全局上下文中引用该文件

示例：

python
excel = at.AstExcel()
workbook = await excel.async_load("template.xlsx")

# 修改数据...
sheet = workbook.get_sheet()
sheet.cell(row=1, column=1, value="新数据")

# 保存（不覆盖原文件）
unique_key = await excel.async_save()
at.temp.set("excel_file_key", unique_key)

# 保存（覆盖原文件）
unique_key = await excel.async_save(cover_file=True)

Workbook 操作 ​

async_load() 返回的 AstWorkbook 对象提供了以下方法来读取 Excel 数据：

get_sheet() ​

获取工作表

python
workbook.get_sheet(index=None)

参数：

  • index: 工作表索引，支持三种类型：
    • None 或 -1：返回当前活动工作表
    • int（正整数）：按下标获取工作表（从 0 开始）
    • str：按名称获取工作表

返回值： openpyxl Worksheet 对象

示例：

python
# 获取活动工作表
sheet = workbook.get_sheet()

# 按下标获取（第 2 个工作表）
sheet = workbook.get_sheet(1)

# 按名称获取
sheet = workbook.get_sheet("Sheet1")

get_rows() ​

获取工作表中的所有行数据

python
workbook.get_rows(sheet_index=None)

参数：

  • sheet_index: 工作表索引（同 get_sheet 的 index 参数）

返回值： 二维列表，每个元素是一行数据的元组

示例：

python
# 获取活动工作表的所有行
rows = workbook.get_rows()
for row in rows:
    print(row)
# 输出示例:
# ('姓名', '年龄', '城市')
# ('张三', 25, '北京')
# ('李四', 30, '上海')

# 获取指定工作表的所有行
rows = workbook.get_rows("Sheet2")

get_row() ​

获取指定行的数据

python
workbook.get_row(row_index=0, sheet_index=None)

参数：

  • row_index: 行号（从 1 开始）
  • sheet_index: 工作表索引（同 get_sheet 的 index 参数）

返回值： 列表，包含该行所有单元格的值

示例：

python
# 获取第 1 行（通常是表头）
header = workbook.get_row(1)
print(header)  # ['姓名', '年龄', '城市']

# 获取第 2 行
data = workbook.get_row(2)
print(data)  # ['张三', 25, '北京']

# 获取指定工作表的某一行
data = workbook.get_row(1, "Sheet2")

get_column() ​

获取指定列的数据

python
workbook.get_column(column_index=None, sheet_index=None)

参数：

  • column_index: 列索引，支持两种类型：
    • int：按列号获取（从 1 开始）
    • str：按列字母获取（如 "A"、"B"）
    • None：获取第 1 列
  • sheet_index: 工作表索引（同 get_sheet 的 index 参数）

返回值： 列表，包含该列所有单元格的值

示例：

python
# 获取第 1 列
col = workbook.get_column(1)
print(col)

# 按列字母获取
col_a = workbook.get_column("A")
print(col_a)  # ['姓名', '张三', '李四']

# 获取指定工作表的某一列
col = workbook.get_column("B", "Sheet2")

完整使用示例 ​

读取 Excel 数据并保存到变量 ​

python
excel = at.AstExcel()
workbook = await excel.async_load("test_data.xlsx")

# 获取所有行
rows = workbook.get_rows()

# 第一行为表头
header = rows[0]
print(f"表头: {header}")

# 遍历数据行
for i, row in enumerate(rows[1:], 1):
    print(f"第 {i} 行: {row}")

# 将某个值保存到临时变量
first_row = rows[1]
at.temp.set("username", str(first_row[0]))
at.temp.set("password", str(first_row[1]))

修改 Excel 并保存 ​

python
excel = at.AstExcel()
workbook = await excel.async_load("template.xlsx")

# 获取活动工作表
sheet = workbook.get_sheet()

# 写入数据
sheet.cell(row=1, column=1, value="姓名")
sheet.cell(row=1, column=2, value="年龄")
sheet.cell(row=2, column=1, value=at.cname().value)
sheet.cell(row=2, column=2, value=at.natural(18, 60).value)

# 保存
unique_key = await excel.async_save()
at.temp.set("excel_key", unique_key)

结合 AstFile 使用 ​

python
# 先通过 AstFile 加载文件
ast_file = at.AstFile()
await ast_file.load_from_system("report.xlsx")

# 再通过 AstExcel 加载 AstFile
excel = at.AstExcel()
workbook = await excel.async_load(ast_file)

# 读取数据
rows = workbook.get_rows()
print(f"共 {len(rows)} 行数据")

# 修改后保存
sheet = workbook.get_sheet()
sheet.cell(row=len(rows) + 1, column=1, value="新增数据")

unique_key = await excel.async_save()
print(f"文件唯一标识: {unique_key}")

# 释放 AstFile 内存
ast_file.close()

配合 request 对象上传修改后的 Excel ​

python
# 加载 Excel
excel = at.AstExcel()
workbook = await excel.async_load("upload_template.xlsx")

# 填充数据
sheet = workbook.get_sheet()
sheet.cell(row=2, column=1, value="测试数据")

# 保存并获取唯一标识
unique_key = await excel.async_save()

# 更新请求中的文件
await at.request.async_update_body_file("file", unique_key)

注意事项 ​

  • async_load() 和 async_save() 是异步方法，需要使用 await
  • get_sheet()、get_rows()、get_row()、get_column() 是同步方法，无需 await
  • async_load() 接收 BytesIO 时，filename 参数必填
  • get_row() 的行号从 1 开始，get_column() 的列号也从 1 开始
  • get_sheet() 的下标从 0 开始，传入不存在的下标或名称会抛出 RuntimeError
  • async_save(cover_file=True) 会覆盖原始文件，请谨慎使用
  • AstWorkbook 继承了 openpyxl Workbook 的所有方法，可以直接使用 openpyxl 的 API 操作工作表

总结 ​

AstExcel 提供了完整的 Excel 文件操作能力：

  • 通过 at.AstExcel() 创建 Excel 对象
  • 支持从系统文件名、AstFile 对象、BytesIO 三种方式加载
  • 提供 get_sheet()、get_rows()、get_row()、get_column() 快捷读取方法
  • 保存后返回唯一标识，可在全局上下文中引用
  • 可与 AstFile 和 request 对象配合使用