製作報告幾乎是每一種工程領域的必備工作，目的可以是為了要記錄系統、確認設計符合需求與否、或者產生認證文件等等。若要以手動的方式產生龐大、複雜系統的報告則相當困難且耗時；而當報告必須依循特定的企業佈局或者使用特殊的格式時，挑戰程度就又更高了。

透過MATLAB報告產生器，則可以快速地產生出一個報告範本—再透過DOM API（註1），就能夠以Microsoft Word、PowerPoint、PDF或HTML為各種類型的應用產生量身訂作的報告。

本文將以Microsoft Word文件為例，說明如何利用DOM API來產生簡單版的報告以及更複雜的客製化報告。

建立一個範本

使用DOM API產生報告的第一步，我們先建立一個文件範本。範本包含了固定內容，像是頁首或頁尾，與將以MATLAB函數動態地填入的預留區域（holes）。

在這個範例，我們從Word範本開始。為了建立範本，我們到上述連結提供的下載檔案中的SimpleReport目錄，並執行copyTemplate腳本。這個腳本從MATLAB安裝資料夾複製了一個空的範本到我們所在的資料夾，並且將範本重新命名為myTemplate.dotx。接下來，我們從Word打開myTemplate.dotx檔案。

提醒：有時Word把檔案打開後標題列會顯示”文件1”，而不是範本的名稱，這種情況下無法儲存你對範本進行的變更。如果從Windows命令行以/N參數開啟Word應用程式或”openTemplate2013”腳本來呼叫Word打開範本就可以避免這樣的問題。

打開文件之後，我們前往開發人員（Developer）頁籤並選擇設計模式。開發人員頁籤是被預設為停用的。透過以下步驟可以啟用該頁籤：

1.點選檔案頁籤後，選擇”選項”，並點選自訂功能區。

2.從畫面上自訂功能區的下拉式選單選取”主要索引標籤”，再將”開發人員”旁的方框打勾。

設計模式可把預留區域標示出來，幫助我們區別固定內容與預留區域。

我們在新增一個新的預留區域時，先用游標定出要建立預留區域的位置，並點選RTF內容控制按鈕（“Aa”圖示處）。按下屬性按鈕可以變更預留區域的屬性（圖1）。這裡雖然還不需要在預留區域裡面輸入文字，不過如果加入文字來註記預留區域的目的，可以讓範本更容易理解。這些文字內容不會顯示於最終報告上。

圖1 : 在Word 2013開啟的報告範本。開發人員頁籤已啟用，紅色方框標示處為設計模式、RTF內容控制選項、與屬性。

我們開啟內容控制屬性視窗來指定標題與頁籤（這兩者必須一致）。接下來，我們關閉對話框，儲存並關閉範本。

把內容填入預留區塊

開啟MATLAB，執行fillFirstHole函式來產生一個新的文件。

新文件firstDocument是一種以myTemplate（.dotx）為依據的docx檔案。我們指示DOM API移動到第一個預留區域，接著建立一個Text種類的物件，其中包含"Hello World”文字。我們把這項物件附加到文件裡面，然後關閉文件，再打開firstDocument.docx來檢視。

提醒：如果執行fillFirstHole函式的時候出現錯誤訊息，先確認一下myTemplate.dotx和firstDocument.docx兩個檔案是否都關閉了。

區塊層級與進線預留區域

我們可以在Microsoft Word建立兩種類型的預留區域：進線（inline）與區塊層級（block-level）（圖2）。進線型預留區域會出現在段落中，它只能接受能夠存在於段落之中的內容，比如文字、圖片、與超連結。區塊層級的預留區域則可以容納各種類型的內容，甚至是其他段落。

圖2 : Word建立進線與區塊層級的介面

要建立一個進線預留區域時，先把游標移到範本的任何一個位置，接著點選RTF內容控制按鈕。建立區塊層級的預留區域時則是先標出空白段落之後再點選按鈕。

提醒：如果要把進線預留區域直接放在一個段落之前，必須在段落之前加上一個空格，否則Word可能會建立成區塊層級預留區域。你可以在預留區域建立好之後再清除空格。

加上不同樣式

現在來改變一下報告上的文字字型。在前面的步驟，我們附加了一個文字物件到文件裡。我們有幾種改變文字物件外觀的選擇。

你可以改變個別的文字屬性，像是粗體字、字體顏色，或利用StyleName 屬性來定義外觀。StyleName 屬性可以把Word樣式套用到物件，也就是說物件的外觀是由你在範本定義的樣式來決定。

如果沒有指定StyleName ，可以直接沿用範本內段落的樣式。

如果你想要自訂Word報告外觀，則可以建立自己的樣式定義或使用內建的樣式。

DOM API只能使用範本內定義的樣式。常用的樣式已經建入提供的範本。如果要把不同的內建樣式複製到範本，可以把新的樣式先套用到一段暫時建立的文字，之後再把文字刪除。

我們不建議改變或套用Word內建樣式到你的範本。原因是，你的報告函式必須使用內建樣式的內部名稱，這些名稱可能跟在Word裡的名稱不同。建議改為使用Word編輯器來依據內建樣式建立出新的樣式，再使用新樣式在報告函式裡面的名稱。圖3說明了如何設置Word來顯示使用中的樣式。

圖3 : 只顯示使用中樣式的Word樣式選項視窗格設定。

要定義或改變一個Word內樣式，還是要透過DOM API來控制外觀是依據任務來決定：如果你經常使用一個特定的格式或圖案，可以考慮定義一個Word樣式。Word也有提供設定表格及清單的樣式的選項。如果你只需要改變文件中特定的一小段，可能透過MATLAB函式來控制外觀會更方便。

產生更進階的報告

提醒：所有的樣式都是依據Word正常樣式。如果改變或使用這種樣式，將會限制了你的自訂選項。舉例來說，改變字體會讓你無法在表格樣式使用不同的字體。

DOM API廣泛的類別函式庫藏讓你可以在報告中加入許多不同種類的物件，像是文字、圖片、連結、與表格。在開始建立包含多個物件的報告之前，要先定義一個建立報告的函式與收集顯示在報告中之資料的函式之間的介面。

讓每一個結構的欄位名稱與預留區域都有一致的名稱是最簡單的方法。如此一來，要被填充進預留區域的物件在MATLAB函式裡的程式碼就會是一個簡單的while-迴圈。

加入圖片與表格

我們從AdvancedReport資料夾內getAdvancedReportData函式蒐集資料開始。這個函式定義了報告與資料之間的介面。有些元件是靜態的文字，例如標題。其他則視系統的環境變數而定，像是作者資料等。兩個表格都被填入以MATLAB why函式隨機產生的句子。

接下來，我們依據我們的設計要求準備範本以及由介面定義的預留區域。這些項目都已經定義在AdvancedReportTemplate.dotx：

‧ 我們想要使用的Word樣式：

- AR_Heading 1-3使用在自訂章節標題（章節標題被用來建立目錄）。

- AR_Title與AR_SubTitle用於封面的進線預留區域

- AR_Image與AR_Caption用在中心圖片與經過編號的圖片標題。

- AR_Normal用於字型與正常樣式不同的文字。

- AR_Table使用在改變過外觀的簡易表格。

‧ 期望的段落與預留區域樣式

‧ 上面有公司標誌的靜態頁首和有標示頁碼的頁尾

‧ 內容目錄與圖表目錄

‧ 由靜態章節與子章節標題定義的大綱架構

最後，我們以MATLAB函式createAdvancedReport來建立報告。我們在一個while迴圈處理所有預留區域。切換迴圈會從以下幾種情況做出決定。

“標準”預留區域。在”其他”的切換情形，這些預留區域只會取得被分派到的文字。圖形表示是由Word依據套用的樣式來決定。

圖片。在這種情況，我們的reportData架構包含了要加入至報告的圖片路徑。在processImage 函式，圖片物件被加入至一個樣式為AR_Image的段落。這個樣式為置中對齊，因此圖片也會被置中。圖片的標題會以另一個樣式為AR_Caption的段落表示。該樣式可讓數字自動編號，被用來建立圖表目錄。

簡易表格。在processSimpleTable函式，我們在區塊層級的預留區域建立一個完整的子章節。在加入表格之前，我們附加一個套用了AR_Heading2的新段落，來把新的第二層標題加進報告。我們也建立一個帶有表格類別（Table-class）的簡易表格。這裡只需要表格資料與表格樣式AR_Table。Word裡的表格樣式會負責繪製與設定表格格式。

進階表格。在processAdvancedTable，我們使用另一個區塊層級預留區域來建立一個新的子章節及另一個表格—這次使用的是FormalTable類別。這個類別讓我們可以建立一個完整的手繪表格。我們需要把每一個表格單元加進來，但我們可以完全掌控表格的外觀。為了展示這一點，我們把每個單元格隨機加上背景顏色。

現在我們已經做好執行createAdvancedReport並產生進階報告的準備了。

在這個範例，我們建立了一個簡易的架構，之後也可以很輕鬆地對這個架構作加強，使它可以涵蓋幾乎是所有的文件要求。所產生的文件可以用來進行要求管理或認證，也可以再做更進一步的處理—例如儲存或封存為PDF檔以方便攜帶、保留文字獨立性，及避免內容被更改。

（本文作者Thomas Deck任職於MathWorks公司）

註1：DOM（文件物件模型, document object model）API可在你的系統記憶體建立一個代表性報告。