在 VSTO 增益集的執行階段中擴充 Word 文件和 Excel 活頁簿

  • 發行項

您可以使用 VSTO 增益集，以下列方式自訂 Word 文件和 Excel 活頁簿：

  • 將 Managed 控制項加入任何開啟的文件或工作表。

  • 將 Excel 工作表上的現有清單物件轉換成擴充的 ListObject ，這個物件會公開事件，而且可以透過 Windows Form 資料繫結模型繫結至資料。

  • 存取 Word 和 Excel 為特定文件、活頁簿和工作表公開的應用程式層級事件。

    若要使用這項功能，請在執行階段產生可擴充文件或活頁簿的物件。

    適用對象： 本文章資訊適用於 Excel 和 Word 等應用程式的 VSTO 增益集專案。 如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

在 VSTO 增益集產生擴充物件

「擴充物件」 (Extended Object) 是 Visual Studio Tools for Office Runtime 所提供的類型執行個體，可為原本存在於 Word 或 Excel 物件模型中的物件 (稱為 「原生 Office 物件」(Native Office Object)) 新增功能。 若要產生 Word 或 Excel 物件的擴充物件，請使用 GetVstoObject 方法。 第一次呼叫指定 Word 或 Excel 物件的 GetVstoObject 方法時，它會傳回擴充指定物件的新物件。 每次呼叫方法並指定相同的 Word 或 Excel 物件時，都會傳回相同的擴充物件。

擴充物件的類型具有與原生 Office 物件類型相同的名稱，但是該類型是在 Microsoft.Office.Tools.Excel 或 Microsoft.Office.Tools.Word 命名空間中定義的。 例如，如果您呼叫 GetVstoObject 方法以擴充 Document 物件，該方法會傳回 Document 物件。

GetVstoObject 方法原本主要用於 VSTO 增益集專案。 您也可以在文件層級專案中使用這些方法，但運作方式會不同，而且用途較少。

若要判斷是否已為特定原生 Office 物件產生擴充物件，請使用 HasVstoObject 方法。 如需詳細資訊，請參閱判斷是否已擴充 Office 物件。

產生主項目

當您使用 GetVstoObject 擴充文件層級物件 (即 Workbook、Worksheet 或 Document) 時，傳回的物件稱為主項目。 主項目是可包含其他物件 (包括其他擴充物件和控制項) 的類型。 它類似 Word 或 Excel 主要 Interop 組件中的對應類型，但具有額外的功能。 如需主項目的詳細資訊，請參閱主項目和主控制項概觀。

在您產生主項目之後，即可用來將 Managed 控制項加入文件、活頁簿或工作表。 如需詳細資訊，請參閱將受控控制項加入文件和工作表。

產生 Word 文件的主項目

  • 下列程式碼範例示範如何產生現用文件的主項目。

    if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        Globals.Factory.GetVstoObject(nativeDocument);
}

產生 Excel 活頁簿的主項目

  • 下列程式碼範例示範如何產生現用活頁簿的主項目。

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

產生 Excel 工作表的主項目

  • 下列程式碼範例示範如何產生專案中現用工作表的主項目。

    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

產生 ListObject 主控制項

當您使用 GetVstoObject 方法擴充 ListObject 時，該方法會傳回 ListObject。 ListObject 具有原始 ListObject 的所有功能。 它也具有額外的功能，而且可以使用 Windows Forms 資料繫結模型繫結至資料。 如需詳細資訊，請參閱 ListObject 控制項。

產生 ListObject 的主控制項

  • 下列程式碼範例示範如何為專案之現用工作表中的第一個 ListObject 產生 ListObject 。

    Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = 
        sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        Globals.Factory.GetVstoObject(listObject);
}

將受控控制項加入文件和工作表

在您產生 Document 或 Worksheet之後，即可將控制項加入這些擴充物件所代表的文件或工作表。 若要新增控制項，請使用 Document 或 Worksheet 的 Controls 屬性。 如需詳細資訊，請參閱在執行階段將控制項新增至 Office 文件。

您可以加入 Windows Form 控制項或 「主控制項」(Host Control)。 主控制項是 Visual Studio Tools for Office Runtime 所提供的控制項，可包裝 Word 或 Excel 主要 Interop 組件中的對應控制項。 主控制項會公開基礎原生 Office 物件的所有行為。 它還會引發事件，而且可以使用 Windows Forms 資料繫結模型繫結至資料。 如需詳細資訊，請參閱主項目和主控制項概觀。

注意

您無法使用 VSTO 增益集將 XmlMappedRange 控制項加入工作表，或者將 XMLNode 或 XMLNodes 控制項加入文件。 這些主控制項無法以程式設計方式加入。 如需詳細資訊，請參閱主項目和主控制項的程式設計限制。

保存和移除控制項

將 Managed 控制項加入文件或工作表並在儲存與關閉文件時，將無法保存這些控制項。 所有主控制項都會被移除，只留下基礎原生 Office 物件。 例如， ListObject 會變成 ListObject。 所有 Windows Form 控制項也會被移除，但控制項的 ActiveX 包裝函式會留在文件中。 您必須在 VSTO 增益集中包含程式碼，以清除控制項，或在下次開啟文件時重新建立控制項。 如需詳細資訊，請參閱在 Office 文件中保存動態控制項。

存取文件和活頁簿上的應用程式層級事件

原生 Word 和 Excel 物件模型中的某些文件、活頁簿和工作表事件只會在應用程式層級上引發。 例如，在 Word 中開啟文件時會引發 DocumentBeforeSave 事件，但這個事件是在 Application 類別 (而不是 Document 類別) 中定義的。

如果您只在 VSTO 增益集中使用原生 Office 物件，則必須處理這些應用程式層級事件，然後再撰寫額外的程式碼，以判斷引發該事件的文件是否為您已自訂的文件。 主項目會在文件層級提供這些事件，如此就比較容易處理特定文件的事件。 您可以產生主項目，然後再處理這個主項目的事件。

使用原生 Word 物件的範例

下列程式碼範例示範如何處理 Word 文件的應用程式層級事件。 CreateDocument 方法會建立新文件，然後定義防止儲存這份文件的 DocumentBeforeSave 事件處理常式。 此事件是針對 Application 物件引發的應用程式層級事件，事件處理常式必須將 Doc 參數與 document1 物件進行比較，以判斷 document1 是否代表儲存的文件。

private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

主項目的使用範例

下列程式碼範例透過處理 BeforeSave 主項目的 Document 事件，來簡化這個程序。 這些範例中的 CreateDocument2 方法會產生可擴充 Document 物件的 document2，然後定義防止儲存這份文件的 BeforeSave 事件處理常式。 只有在儲存 document2 時才會呼叫這個事件處理常式，所以可以直接取消儲存動作，而不需要執行任何額外的工作來確認已儲存哪個文件。

下列程式碼範例示範這項工作。

private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

判斷是否已擴充 Office 物件

若要判斷是否已為特定原生 Office 物件產生擴充物件，請使用 HasVstoObject 方法。 如果已產生擴充物件，則此方法返回 true。

使用 Globals.Factory.HasVstoObject 方法。 傳入您要針對擴充物件測試的原生 Word 或 Excel 物件，例如 Document 或 Worksheet。

如果您只想在指定的 Office 物件具有擴充物件時才執行程式碼，HasVstoObject 方法會很有用。 例如，如果您有 Word VSTO 增益集處理 DocumentBeforeSave 事件，以在文件儲存之前從文件中移除受控控制項，請使用 HasVstoObject 方法來判斷文件是否已擴充。 如果文件尚未擴充，便無法包含受控控制項，並且事件處理常式可能會傳回，而不嘗試清除文件上的控制項。

相關內容