接下來要動手建立並安裝智能文件操作 DLL。在真正撰寫這個實作 ISmartDocument 介面方法的 DLL 之前,先把介面本身摸清楚會省下很多力氣。
當使用者在文件中移動時,你的操作處理程序 DLL 負責建立並管理一組顯示於文件動作工作面板中的控制項,讓你能依文件所在位置提供客製化的使用者介面。對應到文件 XML 樞紐的元素,定義了「使用者目前身處文件何處」;而每個 XML 元素又決定該顯示哪些控制項。下圖列出可用的控制項類型,這些控制項都是透過操作 DLL 中實作的 ISmartDocument 方法建立的。當控制項被觸發(例如游標移入文字方塊、按下某個按鈕),Office 便會經由 ISmartDocument 介面方法呼叫你的自訂程式碼。
圖 2. 智能文件控制項類型
我把 ISmartDocument 的方法分成三類:設定方法,用來向 Office 描述工作面板上要建哪些控制項(圖 3);繪製期方法,在控制項實際繪於工作面板時被呼叫(圖 4);以及變更通知方法,由 Office 在使用者操作工作面板控制項時呼叫(圖 5)。
圖 3. ISmartDocument 設定方法
圖 4. ISmartDocument 控制項繪製方法

圖 5. ISmartDocument 通知方法
大多數 DLL 不會用到全部控制項類型,也不需要實作所有 ISmartDocument 方法。以本例來說,工作面板裡沒有 ActiveX 或清單方塊控制項,那些方法就只保留了樣板實作。事實上,若你只想用一些簡單特性(例如提供超連結或情境式說明文字),甚至完全不必撰寫操作 DLL——只要在 Word 或 Excel 智能文件中附上一份 XML 檔,描述你希望與各 XML 元素關聯的動作即可。
圖 6 摘錄了 ISmartDocument 方法的通用參數。
圖 6. ISmartDocument 通用方法參數
Office 載入你的操作 DLL 時,會先呼叫圖 3 中的設定方法。順序大致如下:
首先呼叫 SmartDocInitialize,給你一個執行一次性初始化的機會。接著透過 get_SmartDocXmlTypeCount 詢問:文件中定義了多少個帶有相關控制項的 XML 元素(沒有關聯控制項的元素當然也可以存在)。本例的動作面板是空的,所以或許你只想為這些元素提供一些標準的說明內容。
取得元素數量後,Office 會連續呼叫 get_SmartDocXmlTypeName 逐一詢問每個元素的名稱,你必須回傳合法且完整的元素名稱(例如 schema#element)。每個元素還有一段說明,當使用者游標落在該元素上時會顯示於工作面板標題,透過 get_SmartDocXmlTypeCaption 回傳。這兩個方法成對出現,每個 XML 元素各呼叫一次。
下一步,Office 想知道每個元素在工作面板上要顯示哪些控制項:
get_ControlCount:指定元素的控制項數量。get_ControlID:依控制項索引(從 1 起算)為每個控制項指定唯一 ID。get_ControlNameFromID:依控制項 ID 回傳控制項名稱。這個名稱不顯示於畫面,而是用來在 Word 或 Excel 物件模型中參照該控制項。get_ControlTypeFromID:依控制項 ID 回傳控制項類型(參見圖 2)。使用者移動游標時,Office 會以對應的控制項更新工作面板,接著呼叫繪製期方法(圖 4)。它會先呼叫 get_ControlCaptionFromID,讓你提供控制項的說明文字。請注意,說明文字不是在設定階段提供的,而是在顯示當下提供,因此可以動態變化。Office 不會繪製說明為空白或 NULL 的控制項——這正好可以用來動態隱藏與顯示控制項:想隱藏某個控制項,只要讓 get_ControlCaptionFromID 對它回傳 NULL 或空字串即可。
接著 Office 會為每個控制項呼叫對應類型的填裝方法(例如 PopulateHelpContent),由你提供內容,例如圖片位置或超連結文字。與該控制項關聯的文件元素,其 XML 與文字內容會被傳入所有填裝方法。要注意的是,C_TYPE_LABEL 與 C_TYPE_SEPARATOR 兩類控制項並沒有對應的填裝方法。等所有控制項都繪製完、面板組裝完成後,Office 會呼叫 OnPaneUpdateComplete。
當使用者與面板控制項互動時,Office 會呼叫圖 5 所列的某個通知方法。標籤與分隔線沒有通知方法;其他控制項的通知方法則表示狀態改變或遭到點擊,可能觸發某個動作(例如開啟超連結或圖片)。
有個實務上的觀察值得記住:通知寧多勿少。例如在 Excel 中儲存格選取變動時(即使 XML 元素本身沒變),Office 也會重畫工作面板並呼叫你的方法,讓面板能呈現真正動態的內容。你可以藉此查詢被選取儲存格的值,據以更新控制項。範例程式正是靠這個特性來更新面板中選中事項的資訊,省去在操作 DLL 裡處理 Excel VBA 事件的麻煩。
多數繪製期方法都帶有一個 ISmartDocProperties 參數。它是一組名稱/值對的屬性集合(繼承自 IPropertyBag),用來承載控制項的額外資訊——控制項的尺寸、字型、對齊方式等都在這裡指定。圖 7 列出適用於所有控制項的關鍵屬性名稱。屬性值一律以 BSTR 形式透過 ISmartDocProperties::Write 傳入,即使是數值型屬性也不例外。例如這行程式碼會把文字方塊寬度設為 50 像素:
Props->Write(CComBSTR("W"), CComBSTR("50"));
圖 7. 所有控制項通用的 ISmartDocProperties
帶有相關標籤的控制項(C_TYPE_TEXTBOX、C_TYPE_CHECKBOX)另有圖 8 所列的屬性,用來描述標籤外觀。請注意這些屬性只影響標籤本身,不會改變控制項的繪製字型。最後還有一批只適用於特定控制項類型的屬性,見圖 9。
圖 8. 控制項標籤的 ISmartDocProperties
圖 9. 其他 ISmartDocProperties 名稱/值對
我選擇以 Visual C++ 搭配活動樣板庫(ATL)來建立操作 DLL。ATL 是個好選擇:涵蓋範圍比 MFC 精簡,卻仍提供了實作智能文件所需的各項 COM 便利功能。如果你更熟悉 MFC,用它也完全可行。
從 MSDN 下載 Office 2003 智能文件 SDK 之後,我在 Visual Studio .NET 中建立一個 ATL 類型的新專案,再用 Add | Class 加入一個 ATL Simple Object,也就是範例中的 CScheduleSmartDoc。接著在類別檢視器(View | Class View)對該物件按右鍵,選擇 Add | Implement Interface 讓它實作 ISmartDocument。
如果開發機上沒裝 Office 2003,你得先從裝有 Office 2003 的機器把型別庫複製過來。它通常位於 C:\Program Files\Common Files\Microsoft Shared\Smart Tag\mstag.tlb,但務必確認拿到的是 1.2 版(對應 Office 2003),而非舊版。之後就可以把範例程式與介面描述當成指南,實作出你需要的方法。
Office 用一個名為「XML 擴充套件資訊清單」的 XML 檔來描述你的解決方案,裡頭包含更新與設定該方案所需的資訊,一般命名為 manifest.xml。範例程式中附了一份骨架 manifest.xml(圖 10),需要修改的部分已標示出來:
圖 10. XML 資訊清單檔
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?XML:NAMESPACE PREFIX = [default] https://schemas.microsoft.com/office/xmlexpansionpacks/2003 NS = "https://schemas.microsoft.com/office/xmlexpansionpacks/2003" />
<MANIFEST xmlns="https://schemas.microsoft.com/office/xmlexpansionpacks/2003">
<VERSION>1.1</VERSION>
<UPDATEFREQUENCY>20160</UPDATEFREQUENCY>
<URI>ScheduleSmartDocument</URI>
<SOLUTION>
<SOLUTIONID>{15960625-1612-46AB-877C-BBCB59503FCE}</SOLUTIONID>
<TYPE>smartDocument</TYPE>
Simple Schedule Smart Document
<TARGETAPPLICATION>Excel.Application.11</TARGETAPPLICATION>
<FILE>
<TYPE>solutionActionHandler</TYPE>
<VERSION>1.0</VERSION>
<FILEPATH>ScheduleSmartDocument.dll</FILEPATH>
<CLSID>{0A9D54DE-12F8-4711-AF10-7D4ACA1D1924}</CLSID>
<REGSVR32></REGSVR32>
</FILE>
<FILE>
<TYPE>Other</TYPE>
<VERSION>1.0</VERSION>
<FILEPATH>ScheduleGraphic.GIF</FILEPATH>
</FILE>
</SOLUTION>
<SOLUTION>
<SOLUTIONID>{443E624C-AE85-4b20-8522-1CFD5B4E7CBC}</SOLUTIONID>
Schedule Smart Document XSL Transform
<TYPE>Transform</TYPE>
<CONTEXT>https://schemas.microsoft.com/Office/word/2003/Wordml</CONTEXT>
<FILE>
<TYPE>primaryTransform</TYPE>
<VERSION>1.0</VERSION>
<FILEPATH>ScheduleReport.xsl</FILEPATH>
</FILE>
</SOLUTION>
</MANIFEST>
若方案還需一併安裝其他檔案(例如 GIF 圖片或含補充說明的 HTML 檔),把它們列在 SOLUTION 元素底下、各自用 FILE 元素描述即可。本例只有一張顯示於工作面板的 GIF。
另一件讓我卡了好幾個小時的事:清單中的 URI 元素名稱,必須與你對應文件元素所用的 XML 樞紐名稱一致。本例中是 ScheduleSmartDocument。
當智能文件與 XML 樞紐都準備好,就能附加一個 XML 擴充套件,把操作處理程序 DLL 關聯到該文件。在 Excel 中透過「Data | XML | XML Expansion Packs」開啟對話方塊,先用它加入擴充套件(指向方案的 manifest.xml),再把擴充套件附加到文件上。這個過程與用 XML 標記文件類似,但只有智能文件開發者需要執行,使用者不必碰這個對話方塊——使用者端的附加作業是透過「Tools | Templates and Add-Ins」的「XML Expansion Packs」頁籤完成的。
使用者開啟附有擴充套件的文件時,Office 會自動安裝或更新本機上的擴充套件檔案。這些檔案通常裝在 C:\Documents and Settings\All Users\Application Data\Microsoft\Schemas,但未來版本的 Office 可能改動這個位置。若使用者沒有系統管理員權限,擴充套件會改裝到個別使用者的應用程式資料目錄(例如 C:\Documents and Settings\Mike\Local Settings\Application Data\Microsoft\Schemas)。清單中標記為 RUNFROMSERVER=true 的檔案不會被下載安裝,而是每次使用時直接從伺服器位置開啟。
這裡有個部署時常踩的陷阱:如果你已經在本機開發好方案,把它複製到部署伺服器之後,Office 仍會沿開發機上的舊路徑去找清單檔。我也遇到過,最後查出 Office 把方案路徑加密存進一個名為 Solution URL 的自訂文件屬性中。檔案部署到伺服器後,你得把這個屬性改成伺服器路徑,或者重新用「XML 擴充套件」對話方塊從部署伺服器附加一次擴充套件(這麼做會重設該屬性的值),再把附了方案的 Excel 活頁簿存回伺服器。
要模擬使用者情境做測試,請先關閉活頁簿,開啟「Data | XML | XML Expansion Packs」(Word 中則在 Tools | Templates and Add-Ins 底下),從本機刪除 ScheduleSmartDocument 的擴充套件檔案,讓開發機看起來像一台對擴充套件一無所知的一般使用者機器。接著從伺服器開啟試算表,此時會跳出詢問是否下載 XML 擴充套件的對話方塊,點選「是」,Office 便會下載清單中列出的檔案並安裝到本機。
XML 擴充套件的能耐其實遠超這個簡單範例所需:它可以用來從伺服器向用戶端分發任何型別的檔案,甚至能把多份清單串成「清單集合」,讓 Word 或 Excel 把數份互鏈的清單當成一份大清單來處理。
【未完待續】