跳转至

Workbook API参考

Workbook是Symphra Excel的核心类,代表一个完整的Excel工作簿。

构造函数

__init__(filepath=None, mode="default")

创建或加载工作簿。

参数:

  • filepath (str, optional): Excel文件路径。如果提供,则加载现有文件;否则创建新工作簿。
  • mode (str, optional): 工作模式。默认为"default"。
    • "default": 默认模式,完整功能
    • "read_only": 只读模式,节省内存
    • "write_only": 只写模式,适合大数据写入

示例:

from symphra_excel import Workbook

# 创建新工作簿
wb = Workbook()

# 加载现有文件
wb = Workbook("existing.xlsx")

# 只读模式
wb = Workbook("large_file.xlsx", mode="read_only")

工作表管理方法

create_worksheet(title=None)

创建新的工作表。

参数:

  • title (str, optional): 工作表名称。如果不提供,将自动生成(如"Sheet1")。

返回:

  • Worksheet: 新创建的工作表对象

异常:

  • ValueError: 如果工作表名称已存在

示例:

# 创建默认名称的工作表
sheet = wb.create_worksheet()

# 创建指定名称的工作表
sheet = wb.create_worksheet("销售数据")

get_worksheet(name)

获取指定名称的工作表。

参数:

  • name (str): 工作表名称

返回:

  • Worksheet: 工作表对象

异常:

  • WorksheetNotFoundError: 如果工作表不存在

示例:

try:
    sheet = wb.get_worksheet("销售数据")
except WorksheetNotFoundError:
    sheet = wb.create_worksheet("销售数据")

delete_worksheet(name_or_sheet)

删除工作表。

参数:

  • name_or_sheet (str | Worksheet): 工作表名称或工作表对象

示例:

# 通过名称删除
wb.delete_worksheet("临时数据")

# 通过对象删除
wb.delete_worksheet(sheet)

保存方法

save(filepath)

保存工作簿到文件。

参数:

  • filepath (str): 目标文件路径

示例:

wb.save("output.xlsx")
wb.save("/path/to/output.xlsx")

save_to_memory()

将工作簿保存到内存。

返回:

  • bytes: Excel文件的字节数据

示例:

data = wb.save_to_memory()

# 用于网络传输
response.content = data

# 或保存到文件
with open("output.xlsx", "wb") as f:
    f.write(data)

资源管理方法

close()

关闭工作簿并释放资源。

示例:

wb = Workbook()
# ... 操作
wb.close()

# 推荐使用with语句自动管理
with Workbook() as wb:
    # ... 操作
    pass
# 自动调用close()

属性

worksheets

获取所有工作表列表。

类型: list[Worksheet]

示例:

# 获取工作表数量
count = len(wb.worksheets)

# 遍历所有工作表
for sheet in wb.worksheets:
    print(sheet.title)

# 获取第一个工作表
first_sheet = wb.worksheets[0]

worksheet_names

获取所有工作表名称。

类型: list[str]

示例:

names = wb.worksheet_names
print(f"工作表: {', '.join(names)}")

# 检查工作表是否存在
if "数据" in wb.worksheet_names:
    sheet = wb.get_worksheet("数据")

properties

工作簿属性(元数据)。

类型: WorkbookProperties

示例:

wb.properties.title = "销售报表"
wb.properties.author = "张三"
wb.properties.company = "ABC公司"
wb.properties.comments = "2024年度数据"
wb.properties.keywords = "销售,报表"

完整使用示例

基础用法

from symphra_excel import Workbook

# 使用上下文管理器
with Workbook() as wb:
    # 创建工作表
    sheet1 = wb.create_worksheet("一月")
    sheet2 = wb.create_worksheet("二月")

    # 写入数据
    sheet1.set_cell_value("A1", "销售额")
    sheet1.set_cell_value("A2", 10000)

    # 保存
    wb.save("monthly_sales.xlsx")

加载和修改

from symphra_excel import Workbook

# 加载现有文件
wb = Workbook("template.xlsx")

# 获取工作表
sheet = wb.get_worksheet("Sheet1")

# 修改数据
sheet.set_cell_value("A1", "更新的数据")

# 另存为新文件
wb.save("modified.xlsx")

wb.close()

批量创建

from symphra_excel import Workbook

departments = ["销售部", "技术部", "人事部"]

for dept in departments:
    with Workbook() as wb:
        sheet = wb.create_worksheet(dept)
        sheet.set_cell_value("A1", f"{dept}数据")
        wb.properties.title = f"{dept}报表"
        wb.save(f"{dept}.xlsx")

相关链接