Python XlsxWriter 重要的类

XlsxWriter库包括以下类。这些类中定义的所有方法允许以编程方式在XLSX文件上进行不同的操作。这些类有：

• Workbook类
• Worksheet类
• Format类
• Chart类
• Chartsheet类
• Exception类

Workbook类

这是XlsxWriter模块提供的主要类，它是唯一需要直接实例化的类。它表示Excel文件在磁盘上的写入情况。

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

Workbook类定义了以下方法−

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

Worksheet类

Worksheet 类表示一个 Excel 工作表。该类的对象处理诸如向单元格写入数据或格式化工作表布局等操作。可以通过从 Workbook() 对象调用 add_worksheet() 方法来创建该对象。

Worksheet 对象可以访问以下方法 –

write(): 将通用数据写入工作表单元格。

参数 −

• row − 单元格行（从零开始计数）。
• col − 单元格列（从零开始计数）。
• *args − 传递给子方法（如number、string和cell_format）的附加参数。

返回值 −

• 0 − 成功
• -1 − 行或列超出工作表范围。

write_string() : 将字符串写入由行和列指定的单元格。

参数 −

• row (int)
• cell_row (int) - 单元格的行数（从零开始计数）。
• cell_column (int) - 单元格的列数（从零开始计数）。
• string (string) - 要写入单元格的字符串。
• cell_format (Format) - 可选的格式对象。

返回值 -

• 0 - 成功。
• -1 - 行或列超出工作表范围。
• -2 - 字符串被截断为32k个字符。

write_number() : 将数字类型写入由行数和列数指定的单元格。

参数 -
* row (int) - 单元格的行数（从零开始计数）。
* col (int) - 单元格列（从零开始计数）。
* string (string) - 要写入单元格的字符串。
* cell_format (Format) - 可选的格式对象。

返回值 -
* 0 - 成功
* -1 - 行或列超出工作表边界。

write_formula() : 向由行和列指定的单元格中写入公式或函数。

参数 -
* row (int) - 单元格行（从零开始计数）。
* col (int) - 单元格列（从零开始计数）。
* formula (string) - 要写入的公式。
* Formula to write to cell.
* cell_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) - 单元格行号（从0开始计数）。
* col (int) - 单元格列号（从0开始计数）。
* 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(): 设置工作表中的自动筛选区域。它在工作表数据的2D范围的标题中添加下拉列表。用户可以根据简单的条件筛选数据。

参数
* first_row (int) − 表示范围的第一行。（全部从零开始计数）
* first_col (int) − 表示范围的第一列。
* last_row (int) − 表示范围的最后一行。
* last_col (int) − 表示范围的最后一列。

Format类

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

字体格式化方法和属性 −

方法名	描述	属性
set_font_name()	Font type	‘font_name’
set_font_size()	Font size	‘font_size’
set_font_color()	Font color	‘font_color’
set_bold()	Bold	‘bold’
set_italic()	Italic	‘italic’
set_underline()	Underline	‘underline’
set_font_strikeout()	Strikeout	‘font_strikeout’
set_font_script()	Super/Subscript	‘font_script’

对齐格式化方法和属性

方法名	描述	属性
set_align()	Horizontal align	‘align’
set_align()	Vertical align	‘valign’
set_rotation()	Rotation	‘rotation’
set_text_wrap()	Text wrap	‘text_wrap’
set_reading_order()	Reading order	‘reading_order’
set_text_justlast()	Justify last	‘text_justlast’
set_center_across()	Center across	‘center_across’
set_indent()	Indentation	‘indent’
set_shrink()	Shrink to fit	‘shrink’

Chart类

通过Workbook对象的add_chart()方法创建图表对象，其中指定了图表类型。

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

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

worksheet.insert_chart('A7', chart)

XlxsWriter支持以下图表类型−

• area − 创建面积（填充线）风格的图表。

• bar − 创建条形（转置直方）风格的图表。

• column − 创建柱形（直方）风格的图表。

• line − 创建线形风格的图表。

• pie − 创建饼状风格的图表。

• doughnut − 创建圆环风格的图表。

• scatter − 创建散点风格的图表。

• stock − 创建股票风格的图表。

• radar − 创建雷达风格的图表。

Chart类定义了以下方法−

add_series(options): 向图表添加一个数据系列。可以给定以下属性：-

• Values, categories
• name
• line, border
• fill , pattern , gradient
• data_labels, points

set_x_axis(options): 设置图表的X轴选项，包括：-

• name, name_font
• num_font, num_format
• line, fill, pattern, gradient
• min, max
• position_axis
• label_position, label_align
• date_axis, text_axis
• minor_unit_type, major_unit_type

set_y_axis(options): 设置图表的Y轴选项，包括：-

• name, name_font
• num_font, num_format
• line, fill, pattern, gradient
• min, max
• position_axis
• label_position, label_align
• date_axis, text_axis
• minor_unit_type, major_unit_type

set_size(): 此方法用于设置图表的尺寸。可以通过设置宽度和高度或设置 x_scale 和 y_scale 来修改图表的大小。

set_title(options): 设置图表标题选项。

参数 -
* options（dict） - 图表大小选项的字典。
* name - 设置图表的名称（标题）。名称显示在图表上方。
* name_font - 设置图表标题的字体属性。
* overlay - 允许标题叠加在图表上。
* layout - 在图表相对单位中设置标题的（x，y）位置。

set_legend(): 此方法使用以下属性格式化图表图例：-

• none
• position, font, border
• fill, pattern, gradient

Chartsheet类

在XLSX文件中，图表表单是仅包含图表而没有其他数据的工作表。通过从Workbook对象调用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)

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

示例

以下代码将数据系列写入名为sheet1的工作表，但是会打开一个新的Chartsheet来添加基于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!A1:A5'})
chart.add_series({'values': '=Sheet1!B1:B5'})
chart.add_series({'values': '=Sheet1!C1:C5'})

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() 方法时引发。该异常在Workbook的 close() 方法期间引发。
6	UnsupportedImageFormat 如果图像不是支持的文件格式之一（PNG、JPEG、GIF、BMP、WMF或EMF），则会引发此异常。
7	EmptyChartSeries 当向工作表添加图表且没有数据系列时，会发生该异常。
8	InvalidWorksheetName 如果工作表名称过长或包含无效字符，则会引发此异常。
9	DuplicateWorksheetName 当工作表名称已存在时，会引发此异常。

文件创建错误 FileCreateError

假设使用Excel应用程序已经打开一个名为 hello.xlsx 的工作簿，那么以下代码将引发一个 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.