核心概念¶
本页面介绍Symphra Excel的核心概念和架构，帮助您更好地理解和使用这个库。
架构概览¶
Symphra Excel采用模块化设计，主要由以下几个模块组成：
symphra_excel/
├── core/ # 核心模块：Workbook和Worksheet
├── styles/ # 样式系统
├── templates/ # 模板引擎
├── images/ # 图片处理
├── async_support/ # 异步支持
├── memory_ops/ # 内存优化
└── utils/ # 工具函数
核心对象¶
Workbook（工作簿）¶
Workbook是Excel文件的顶层容器，代表一个完整的Excel文件。
from symphra_excel import Workbook
# 创建新工作簿
wb = Workbook()
# 加载现有文件
wb = Workbook("existing.xlsx")
# 保存
wb.save("output.xlsx")
主要功能： - 管理多个工作表 - 文件的加载和保存 - 全局设置和属性
Worksheet（工作表）¶
Worksheet代表工作簿中的一个工作表，是数据的实际容器。
# 创建工作表
sheet = wb.create_worksheet("我的数据")
# 获取工作表
sheet = wb.get_worksheet("我的数据")
# 操作单元格
sheet.set_cell_value("A1", "Hello")
主要功能： - 单元格读写 - 行列操作 - 样式应用 - 合并单元格
Cell（单元格）¶
单元格是数据的最小单位，通过单元格引用（如"A1"）访问。
# 设置单元格值
sheet.set_cell_value("A1", "文本")
sheet.set_cell_value("B1", 123)
sheet.set_cell_value("C1", 3.14)
# 获取单元格值
value = sheet.get_cell_value("A1")
支持的数据类型： - 字符串 - 整数 - 浮点数 - 布尔值 - 日期时间 - 公式
样式系统¶
CellStyle（单元格样式）¶
CellStyle对象封装了单元格的所有样式属性。
from symphra_excel.styles import CellStyle, Color
style = CellStyle()
style.set_font(name="微软雅黑", size=12, bold=True, color=Color.BLUE)
style.set_background_color(Color.LIGHT_YELLOW)
style.set_alignment(horizontal="center", vertical="center")
sheet.apply_style("A1", style)
样式组件： - 字体（Font）: 字体名称、大小、颜色、粗体、斜体等 - 填充（Fill）: 背景颜色、填充模式 - 边框（Border）: 边框样式、颜色、位置 - 对齐（Alignment）: 水平对齐、垂直对齐、文本换行 - 数字格式（NumberFormat）: 数字、日期、货币等格式
预定义样式¶
Symphra Excel提供了一系列预定义样式：
from symphra_excel.styles import PredefinedStyles
# 使用预定义样式
sheet.apply_style("A1", PredefinedStyles.header_style())
sheet.apply_style("A2", PredefinedStyles.title_style())
sheet.apply_style("A3", PredefinedStyles.warning_style())
sheet.apply_style("A4", PredefinedStyles.success_style())
模板引擎¶
TemplateWorkbook¶
基于Jinja2语法的模板渲染系统。
from symphra_excel import TemplateWorkbook
# 加载模板
wb = TemplateWorkbook("template.xlsx")
# 准备数据
data = {
"title": "销售报表",
"items": [
{"name": "产品A", "quantity": 100},
{"name": "产品B", "quantity": 200},
]
}
# 渲染
wb.render(data)
wb.save("output.xlsx")
模板语法：
- {{ variable }} - 变量插值
- {% for item in items %} - 循环
- {% if condition %} - 条件判断
- {{ image:path }} - 图片占位符
异步支持¶
AsyncWorkbook¶
提供异步API，适合处理大量文件或IO密集型任务。
import asyncio
from symphra_excel.async_support import AsyncWorkbook
async def create_report():
async with AsyncWorkbook() as wb:
sheet = await wb.create_worksheet("数据")
await sheet.set_cell_value("A1", "Hello")
await wb.save("output.xlsx")
asyncio.run(create_report())
适用场景： - 批量生成多个Excel文件 - 从网络获取数据并生成报表 - 大规模数据处理 - 与异步框架集成（如FastAPI）
内存优化¶
MemoryOptimizedWorkbook¶
专为大数据集设计的内存优化版本。
from symphra_excel.memory_ops import MemoryOptimizedWorkbook
wb = MemoryOptimizedWorkbook()
sheet = wb.create_worksheet("大数据")
# 处理大量数据不会导致内存溢出
for i in range(1000000):
sheet.set_cell_value(f"A{i+1}", f"Data {i}")
wb.save("large_file.xlsx")
优化策略： - 流式写入 - 分块处理 - 自动内存释放 - 缓冲区管理
图片处理¶
ExcelImage¶
支持在Excel中插入和嵌入图片。
from symphra_excel.images import ExcelImage
# 创建图片对象
img = ExcelImage("logo.png")
# 插入到工作表
sheet.add_image(img, "A1")
# 设置图片大小
img.width = 200
img.height = 100
# 嵌入到单元格
sheet.embed_image("B2", "photo.jpg")
支持格式： - PNG - JPEG - GIF - BMP
工作流程¶
典型的Symphra Excel工作流程：
示例代码¶
from symphra_excel import Workbook
from symphra_excel.styles import PredefinedStyles
# 1. 创建工作簿
wb = Workbook()
# 2. 创建工作表
sheet = wb.create_worksheet("销售数据")
# 3. 写入数据
sheet.set_cell_value("A1", "产品")
sheet.set_cell_value("B1", "销量")
# 4. 应用样式
sheet.apply_style("A1", PredefinedStyles.header_style())
sheet.apply_style("B1", PredefinedStyles.header_style())
# 5. 保存
wb.save("sales.xlsx")
# 6. 关闭（使用with语句自动处理）
wb.close()
最佳实践¶
使用上下文管理器¶
# ✅ 推荐
with Workbook() as wb:
sheet = wb.create_worksheet("数据")
sheet.set_cell_value("A1", "Hello")
wb.save("output.xlsx")
# 自动关闭
# ❌ 不推荐
wb = Workbook()
sheet = wb.create_worksheet("数据")
sheet.set_cell_value("A1", "Hello")
wb.save("output.xlsx")
wb.close() # 容易忘记
样式复用¶
# ✅ 推荐：创建一次，多次使用
header_style = PredefinedStyles.header_style()
for cell in ["A1", "B1", "C1"]:
sheet.apply_style(cell, header_style)
# ❌ 不推荐：重复创建
sheet.apply_style("A1", PredefinedStyles.header_style())
sheet.apply_style("B1", PredefinedStyles.header_style())
sheet.apply_style("C1", PredefinedStyles.header_style())
批量操作¶
# ✅ 推荐：批量处理
data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
for row_idx, row in enumerate(data, start=1):
for col_idx, value in enumerate(row):
sheet.set_cell_value(f"{chr(65+col_idx)}{row_idx}", value)
# ❌ 不推荐：逐个处理
sheet.set_cell_value("A1", 1)
sheet.set_cell_value("B1", 2)
# ... 太多重复代码
下一步¶
现在您已经理解了Symphra Excel的核心概念，可以：