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.

列印頁面