Python Xlsxwriter 简明教程

Python XlsxWriter - Important Classes

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

  1. Workbook class

  2. Worksheet class

  3. Format class

  4. Chart class

  5. Chartsheet class

  6. Exception class

Workbook Class

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

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

工作簿类别定义了以下方法 -

Sr.No

Workbook Class & Description

1

add_worksheet() 向工作簿中添加一个新工作表。

2

add_format() 用于创建新的格式对象，这些对象用于将格式应用于单元格。

3

add_chart() 创建新的图表对象，可以通过 insert_chart() Worksheet 方法插入到工作表中。

4

add_chartsheet() 向工作簿中新增一个图表工作表。

5

close() 关闭 Workbook 对象并编写 XLSX 文件。

6

define_name() 在工作簿中创建已定义的名称，用作变量。

7

add_vba_project() 用于使用二进制 VBA 项目文件向工作簿添加宏或函数。

8

worksheets() 返回工作簿中的工作表列表。

Worksheet Class

Worksheet 类表示 Excel 工作表。此类的对象处理操作，例如将数据写入单元格或格式化工作表布局。它通过从 add_worksheet() 对象调用 Workbook() 方法创建。

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

write()

将泛型数据写入工作表单元格。 Parameters − row −单元格行（从零开始）。 col −单元格列（从零开始）。 *args −传递给子方法的其他参数，如数字、字符串和 cell_format。 Returns − 0 −成功 -1 −行或列超出工作表边界。

write_string()

向由行和列指定单元格中写入字符串。 Parameters − row (int) −单元格行（从零开始）。 col (int) −单元格列（从零开始）。 string (string) −要写入单元格的字符串。 cell_format (Format) −可选的格式对象。 Returns − 0 −成功 -1 −行或列超出工作表边界。 -2 −字符串被截断为 32k 个字符。

write_number()

向由行和列指定单元格中写入数字类型。 Parameters − row (int) −单元格行（从零开始）。 col (int) −单元格列（从零开始）。 string (string) −要写入单元格的字符串。 cell_format (Format) −可选的格式对象。 Returns − 0 −成功 -1 −行或列超出工作表边界。

write_formula()

将公式或函数写入由行和列指定单元格。 Parameters − row (int) −单元格行（从零开始）。 col (int) −单元格列（从零开始）。 formula (string) −要写入单元格的公式。 cell_format (Format) −可选的格式对象。 value −可选的结果。该值为公式计算的结果。 Returns − 0 −成功 -1 −行或列超出工作表边界。

insert_image()

用于向工作表中插入图像。图像可以为 PNG、JPEG、GIF、BMP、WMF 或 EMF 格式。 Parameters − row (int) −单元格行（从零开始）。 col (int) −单元格列（从零开始）。 filename −图像文件名（如果需要，包括路径）。 Returns − 0 −成功 -1 −行或列超出工作表边界。

insert_chart()

用于向工作表中插入图表。可以通过 Workbook add_chart() 方法创建图表对象。 Parameters − row (int) −单元格行（从零开始）。 col (int) −单元格列（从零开始）。 chart −图表对象。

conditional_format()

用于根据用户定义的条件向单元格或单元格范围添加格式。 Parameters − first_row (int) −该范围的第一行。（全部从零开始） first_col (int) −该范围的第一列。 last_row (int) −该范围的最后一行。 last_col (int) −该范围的最后一列。 options (dict) −条件格式选项。必须是一个包含描述条件格式类型和样式的参数的字典 Returns − 0 −成功 -1 −行或列超出工作表边界。 -2 −不正确的参数或选项。

add_table()

用于将单元格范围分组到 Excel 表中。 Parameters − first_row (int) −该范围的第一行。（全部从零开始） first_col (int) −该范围的第一列。 last_row (int) −该范围的最后一行。 last_col (int) −该范围的最后一列。 options (dict) −表格格式选项。

autofilter()

在工作表中设置自动筛选区域。它向二维范围的工作表数据标题添加下拉列表。用户可以基于简单条件来筛选数据。 Parameters − first_row (int) −该范围的第一行。（全部从零开始） first_col (int) −该范围的第一列。 last_row (int) −该范围的最后一行。 last_col (int) −该范围的最后一列。

Format Class

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

Font formatting methods and properties −

Method Name

Description

Property

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'

Alignment formatting methods and properties

Method Name

Description

Property

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 Class

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

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

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

worksheet.insert_chart('A7', chart)

XlxsWriter 支持以下图表类型 −

  1. area − 创建一个区域（填充线）样式图表。

  2. bar − 创建一个条形样式（转置直方图）图表。

  3. column − 创建一个列样式（直方图）图表。

  4. line − 创建一个线样式图表。

  5. pie − 创建一个饼样式图表。

  6. doughnut − 创建一个甜甜圈样式图表。

  7. scatter − 创建一个散点样式图表。

  8. stock − 创建一个股票样式图表。

  9. radar − 创建一个雷达样式图表。

Chart 类定义了以下方法 −

add_series(options)

将数据系列添加到图表。可以给出以下属性 −Values、categoriesnameline、borderfill、pattern、gradientdata_labels、points

set_x_axis(options)

设置图表 X 轴选项，包括 name、name_fontnum_font、num_formatline、fill、pattern、gradientmin、maxposition_axislabel_position、label_aligndate_axis、text_axisminor_unit_type、major_unit_type

set_y_axis(options)

设置图表 Y 轴选项，包括 −name、name_fontnum_font、num_formatline、fill、pattern、gradientmin、maxposition_axislabel_position、label_aligndate_axis、text_axisminor_unit_type、major_unit_type

set_size()

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

set_title(options)

设置图表标题选项。 Parameters − options (dict) − 图表尺寸选项的词典。 name − 设置图表的名称（标题）。该名称显示在图表上方。 name_font − 设置图表标题的字体属性。 overlay − 允许标题叠加在图表上。 layout − 设置标题在图表中的 (x, y) 位置（相对单位）。

set_legend()

此方法使用以下属性格式化图表图例 −noneposition、font、borderfill、pattern、gradient

Chartsheet Class

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)

请记住，图表表仅可包含一张图表。

Example

以下代码在工作表名称 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()

Output

chartsheet class

Exception Class

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

Sr.No

Exception Classes & Description

1

XlsxWriterException Base exception for 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 当工作表名称已存在时引发此异常。

Exception 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'

Handling the Exception

我们可以使用 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

Exception 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.