Python XlsxWriter – 重要的类

XlsxWriter库由以下类组成。在这些类中定义的所有方法允许在XLSX文件上以编程方式完成不同的操作。这些类是

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

工作簿类

这是XlsxWriter模块所暴露的主类，也是唯一需要直接实例化的类。它代表了写在磁盘上的Excel文件。

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

工作簿类定义了以下方法

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

工作表类

工作表类代表一个Excel工作表。该类的一个对象处理诸如将数据写入单元格或格式化工作表布局等操作。它是通过从一个 Workbook() 对象中调用 add_worksheet() 方法创建的。

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

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

参数 −

• row − 单元格行（零索引）。
• col − 单元格列（零索引）。
• *args − 传递给子方法的额外参数，如数字、字符串和cell_format。

返回值 −

• 0 − Success
• -1 − 行或列超出了工作表的范围。

write_string() – 向行和列指定的单元格写一个字符串。

参数 −

• row (int) − 单元格行（零索引）。
• col (int) − 单元格列（零索引）。
• string (string) − 要写到单元格的字符串。
• cell_format (Format) − 可选的格式对象。

返回值 −

• 0 − Success
• -1 − 行或列超出了工作表的范围。
• -2 − 字符串被截断为32k字符。

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

参数 −

• row (int) − 单元格行（零索引）。
• col (int) − 单元格列（零索引）。
• string (string) − 要写到单元格的字符串。
• cell_format (Format) − 可选的格式对象。

返回值 −

• 0 − Success
• -1 − 行或列超出了工作表的范围。

write_formula() – 将公式或函数写入行和列所指定的单元格中。

参数 −

• row (int) – 单元格的行（零索引）。
• col (int) – 单元格的列（零索引）。
• formula (string) – 要写到单元格的公式。
• cell_format (Format) – 可选的格式对象。
• value – 可选的结果。如果公式被计算出来，则为值。

返回值 −

• 0 − Success
• -1 − 行或列超出了工作表的范围。

insert_image() – 用于在工作表中插入图像。该图像可以是PNG、JPEG、GIF、BMP、WMF或EMF格式。

参数 −

• row (int) − 单元格行（零索引）。
• col (int) − 单元格列（零索引）。
• filename − 图像文件名（如果需要，还包括路径）。

返回值 −

• 0 − Success
• -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 − Success
• -1 − 行或列超出了工作表的范围。
• -2 − 参数或选项不正确。

add_table() – 用于将一个单元格区域分组到一个Excel表格中。

参数 −

• first_row (int) − 范围的第一行。(全部以零为索引)
• first_col (int) − 范围的第一列。
• last_row (int) − 范围的最后一行。
• last_col (int) − 范围的最后一栏。
• options (dict) − 表的格式化选项。

autofilter() – 在工作表中设置自动筛选区域。它将下拉列表添加到工作表数据的2D范围的表头。用户可以根据简单的条件过滤数据。

参数 −

• first_row (int) − range的第一行。(索引全为0)
• 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()	粗体	‘粗体’。
Set_italic()	斜体	‘斜体
set_underline()	下划线	‘下划线’。
set_font_strikeout()	剔除	‘font_strikeout’。
set_font_script()	超标/下标	‘font_script’。

对齐格式化方法和属性

方法名称	说明	属性
set_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()	缩进	‘缩进’。
Set_shrink()	收缩以适应需要	‘缩减

图表类

一个图表对象是通过指定图表类型的Workbook对象的 add_chart() 方法创建的。

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

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

worksheet.insert_chart('A7', chart)

XlxsWriter支持以下图表类型 −

• area – 创建一个区域（填充线）风格的图表。

• bar – 创建一个Bar风格（换位柱状图）的图表。

• column – 创建一个列式（柱状图）图表。

• line – 创建一个线形风格的图表。

• pie – 创建一个Pie风格的图表。

• doughnut – 创建一个Doughnut风格的图表。

• scatter – 创建一个Scatter风格的图表。

• stock – 创建一个股票风格的图表。

• radar – 创建一个Radar风格的图表。

图表类定义了以下方法

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文件中的图表表是一个只包含图表而不包含其他数据的工作表。一个新的 图表表 对象是通过调用工作簿对象中的 add_chartsheet() 方法创建的。

chartsheet = workbook.add_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!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() 方法中引发。异常在工作簿 关闭() 时被引发。
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.