Python XlsxWriter - 重要类

XlsxWriter 库包含以下类。这些类中定义的所有方法都允许以编程方式对 XLSX 文件执行不同的操作。这些类是：

工作簿类
工作表类
格式类
图表类
图表表类
异常类

工作簿类

这是 XlsxWriter 模块公开的主要类，也是您唯一需要直接实例化的类。它表示写入磁盘上的 Excel 文件。

wb=xlsxwriter.Workbook('filename.xlsx')

工作簿类定义了以下方法：

序号	工作簿类和描述
1	add_worksheet() 向工作簿添加新的工作表。
2	add_format() 用于创建新的 Format 对象，这些对象用于将格式应用于单元格。
3	add_chart() 创建一个新的图表对象，可以通过 insert_chart() 工作表方法将其插入到工作表中。
4	add_chartsheet() 向工作簿添加新的图表表。
5	close() 关闭工作簿对象并写入 XLSX 文件。
6	define_name() 在工作簿中创建一个已定义的名称以用作变量。
7	add_vba_project() 用于使用二进制 VBA 项目文件向工作簿添加宏或函数。
8	worksheets() 返回工作簿中工作表的列表。

工作表类

工作表类表示 Excel 工作表。此类的对象处理写入单元格数据或设置工作表布局等操作。它是通过从 **Workbook()** 对象调用 **add_worksheet()** 方法创建的。

工作表对象可以访问以下方法：

write()	将通用数据写入工作表单元格。参数： row - 单元格行（从零开始索引）。 col - 单元格列（从零开始索引）。 * args - 传递给子方法的附加参数，例如数字、字符串和单元格格式。返回值： 0 - 成功 -1 - 行或列超出工作表范围。
write_string()	将字符串写入由行和列指定的单元格。参数： row (int) - 单元格行（从零开始索引）。 col (int) - 单元格列（从零开始索引）。 string (string) - 要写入单元格的字符串。 cell_format (Format) - 可选的 Format 对象。返回值： 0 - 成功 -1 - 行或列超出工作表范围。 -2 - 字符串截断为 32k 个字符。
write_number()	将数字类型写入由行和列指定的单元格。参数： row (int) - 单元格行（从零开始索引）。 col (int) - 单元格列（从零开始索引）。 string (string) - 要写入单元格的字符串。 cell_format (Format) - 可选的 Format 对象。返回值： 0 - 成功 -1 - 行或列超出工作表范围。
write_formula()	将公式或函数写入由行和列指定的单元格。参数： row (int) - 单元格行（从零开始索引）。 col (int) - 单元格列（从零开始索引）。 formula (string) - 要写入单元格的公式。 cell_format (Format) - 可选的 Format 对象。 value - 可选结果。如果计算了公式，则为该值。返回值： 0 - 成功 -1 - 行或列超出工作表范围。
insert_image()	用于将图像插入工作表。图像可以是 PNG、JPEG、GIF、BMP、WMF 或 EMF 格式。参数： row (int) - 单元格行（从零开始索引）。 col (int) - 单元格列（从零开始索引）。 filename - 图像文件名（如果需要，则包含路径）。返回值： 0 - 成功 -1 - 行或列超出工作表范围。
insert_chart()	用于将图表插入工作表。图表对象是通过 Workbook add_chart() 方法创建的。参数： row (int) - 单元格行（从零开始索引）。 col (int) - 单元格列（从零开始索引）。 chart - 图表对象。
conditional_format()	用于根据用户定义的条件向单元格或单元格范围添加格式。参数： first_row (int) - 范围的第一行。（所有索引均从零开始） first_col (int) - 范围的第一列。 last_row (int) - 范围的最后一行。 last_col (int) - 范围的最后一列。 options (dict) - 条件格式选项。必须是一个包含描述条件格式的类型和样式的参数的字典。返回值： 0 - 成功 -1 - 行或列超出工作表范围。 -2 - 参数或选项不正确。
add_table()	用于将单元格范围分组到 Excel 表中。参数： first_row (int) - 范围的第一行。（所有索引均从零开始） first_col (int) - 范围的第一列。 last_row (int) - 范围的最后一行。 last_col (int) - 范围的最后一列。 options (dict) - 表格格式选项。
autofilter()	设置工作表中的自动筛选区域。它将下拉列表添加到二维工作表数据标题中。用户可以根据简单的条件筛选数据。参数： first_row (int) - 范围的第一行。（所有索引均从零开始） first_col (int) - 范围的第一列。 last_row (int) - 范围的最后一行。 last_col (int) - 范围的最后一列。

格式类

格式对象是通过调用工作簿 **add_format()** 方法创建的。此对象可用的方法和属性与字体、颜色、图案、边框、对齐和数字格式有关。

字体格式方法和属性：

方法名称	描述	属性
set_font_name()	字体类型	'font_name'
set_font_size()	字体大小	'font_size'
set_font_color()	字体颜色	'font_color'
set_bold()	粗体	'bold'
set_italic()	斜体	'italic'
set_underline()	下划线	'underline'
set_font_strikeout()	删除线	'font_strikeout'
set_font_script()	上标/下标	'font_script'

对齐格式方法和属性

方法名称	描述	属性
set_align()	水平对齐	'align'
set_align()	垂直对齐	'valign'
set_rotation()	旋转	'rotation'
set_text_wrap()	文本换行	'text_wrap'
set_reading_order()	阅读顺序	'reading_order'
set_text_justlast()	右对齐	'text_justlast'
set_center_across()	跨列居中	'center_across'
set_indent()	缩进	'indent'
set_shrink()	缩小以适应	'shrink'

图表类

图表对象是通过工作簿对象的 **add_chart()** 方法创建的，其中指定了图表类型。

chart = workbook.add_chart({'type': 'column'})

通过调用 **insert_chart()** 方法将 **chart** 对象插入工作表。

worksheet.insert_chart('A7', chart)

XlsxWriter 支持以下图表类型：

**area** - 创建面积（填充线）样式图表。
**bar** - 创建条形样式（转置直方图）图表。
**column** - 创建柱形样式（直方图）图表。
**line** - 创建折线样式图表。
**pie** - 创建饼图样式图表。
**doughnut** - 创建环形图样式图表。
**scatter** - 创建散点图样式图表。
**stock** - 创建股票样式图表。
**radar** - 创建雷达图样式图表。

图表类定义了以下方法：

add_series(options)	向图表添加数据系列。可以给出以下属性：值、类别名称线条、边框填充、图案、渐变数据标签、点
set_x_axis(options)	设置图表 X 轴选项，包括：名称、名称字体数字字体、数字格式线条、填充、图案、渐变最小值、最大值轴位置标签位置、标签对齐日期轴、文本轴次要单位类型、主要单位类型
set_y_axis(options)	设置图表 Y 轴选项，包括：名称、名称字体数字字体、数字格式线条、填充、图案、渐变最小值、最大值轴位置标签位置、标签对齐日期轴、文本轴次要单位类型、主要单位类型
set_size()	此方法用于设置图表的尺寸。可以通过设置宽度和高度或设置 x_scale 和 y_scale 来修改图表的尺寸。
set_title(options)	设置图表标题选项。参数： options (dict) - 图表大小选项的字典。 name - 设置图表的名称（标题）。名称显示在图表上方。 name_font - 设置图表标题的字体属性。 overlay - 允许标题覆盖在图表上。 layout - 设置标题在图表中相对于单位的 (x, y) 位置。
set_legend()	此方法使用以下属性格式化图表图例：无位置、字体、边框填充、图案、渐变

图表表类

XLSX 文件中的图表表是一个仅包含图表而不包含其他数据的表。通过从工作簿对象调用 **add_chartsheet()** 方法创建一个新的 **chartsheet** 对象：

chartsheet = workbook.add_chartsheet()

**Chartsheet** 类的某些功能类似于数据工作表，例如选项卡选择、页眉、页脚、边距和打印属性。但是，它的主要目的是显示单个图表，而普通数据工作表可以包含一个或多个嵌入式图表。

**chartsheet** 图表的数据必须存在于单独的工作表上。因此，它始终与至少一个数据工作表一起创建，使用 **set_chart()** 方法。

chartsheet = workbook.add_chartsheet()
chart = workbook.add_chart({'type': 'column'})
chartsheet.set_chart(chart)

请记住，图表表只能包含一个图表。

示例

以下代码将数据系列写入工作表名称 sheet1，但打开一个新的图表表以根据 sheet1 中的数据添加柱形图。

import xlsxwriter

wb = xlsxwriter.Workbook('hello.xlsx')
worksheet = wb.add_worksheet()

cs = wb.add_chartsheet()
chart = wb.add_chart({'type': 'column'})

data = [
   [10, 20, 30, 40, 50],
   [20, 40, 60, 80, 100],
   [30, 60, 90, 120, 150],
]
worksheet.write_column('A1', data[0])
worksheet.write_column('B1', data[1])
worksheet.write_column('C1', data[2]) 

chart.add_series({'values': '=Sheet1!$A$1:$A$5'})
chart.add_series({'values': '=Sheet1!$B$1:$B$5'})
chart.add_series({'values': '=Sheet1!$C$1:$C$5'})

cs.set_chart(chart)
cs.activate()

wb.close()

输出

异常类

XlsxWriter 识别各种运行时错误或异常，可以使用 Python 的错误处理技术来捕获这些错误或异常，以避免 Excel 文件损坏。XlsxWriter 中的异常类如下：

序号	异常类和描述
1	XlsxWriterException XlsxWriter 的基本异常。
2	XlsxFileError 所有与文件相关的错误的基本异常。
3	XlsxInputError 所有与输入数据相关的错误的基本异常。
4	FileCreateError 如果写入 xlsx 文件到磁盘时发生文件权限错误或 IO 错误，或者如果该文件已在 Excel 中打开，则会发生此错误。
5	UndefinedImageSize 如果图像不包含高度或宽度信息，则使用 insert_image() 方法引发此异常。该异常在工作簿 close() 期间引发。
6	UnsupportedImageFormat 如果图像不是受支持的文件格式之一：PNG、JPEG、GIF、BMP、WMF 或 EMF，则会引发此异常。
7	EmptyChartSeries 当向工作表添加图表时没有数据系列时，会发生此异常。
8	InvalidWorksheetName 如果工作表名称过长或包含无效字符。
9	DuplicateWorksheetName 当工作表名称已存在时，会引发此异常。

异常 FileCreateError

假设一个名为hello.xlsx的工作簿已使用Excel应用程序打开，则以下代码将引发FileCreateError错误：

import xlsxwriter
workbook = xlsxwriter.Workbook('hello.xlsx')
worksheet = workbook.add_worksheet()
workbook.close()

运行此程序时，将显示以下错误消息：

PermissionError: [Errno 13] Permission denied: 'hello.xlsx'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
   File "hello.py", line 4, in <module>
   workbook.close()
File "e:\xlsxenv\lib\site-packages\xlsxwriter\workbook.py", line 326, in close
   raise FileCreateError(e)
xlsxwriter.exceptions.FileCreateError: [Errno 13] Permission denied: 'hello.xlsx'

异常处理

我们可以为此目的使用Python的异常处理机制。

import xlsxwriter
try:
   workbook = xlsxwriter.Workbook('hello.xlsx')
   worksheet = workbook.add_worksheet()
   workbook.close()
except:
   print ("The file is already open")

现在将显示自定义错误消息。

(xlsxenv) E:\xlsxenv>python ex34.py
The file is already open

EmptyChartSeries异常

在添加包含数据系列的图表时引发异常的另一种情况。

import xlsxwriter
workbook = xlsxwriter.Workbook('hello.xlsx')
worksheet = workbook.add_worksheet()
chart = workbook.add_chart({'type': 'column'})
worksheet.insert_chart('A7', chart)
workbook.close()

这会导致EmptyChartSeries异常：

xlsxwriter.exceptions.EmptyChartSeries: Chart1 must contain at least one data series.

打印页面