在執行時間于 VSTO 增益集中擴充 Word 檔和 Excel 活頁簿

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

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

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

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

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

    適用于: 本文中的資訊適用于下列應用程式的 VSTO 增益集專案: Excel 和 Word。 如需詳細資訊,請參閱Office 應用程式和專案類型提供的功能

在 VSTO 增益集中產生擴充物件

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

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

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

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

產生主專案

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

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

產生 Word 文件的主項目

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

    If Globals.ThisAddIn.Application.Documents.Count > 0 Then
        Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
            Globals.ThisAddIn.Application.ActiveDocument
        Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
            Globals.Factory.GetVstoObject(NativeDocument)
    End If
    
    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 活頁簿的主項目

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

    Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
        Globals.ThisAddIn.Application.ActiveWorkbook
    If NativeWorkbook IsNot Nothing Then
        Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
            Globals.Factory.GetVstoObject(NativeWorkbook)
    End If
    
    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
        Globals.ThisAddIn.Application.ActiveWorkbook;
    if (nativeWorkbook != null)
    {
        Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
            Globals.Factory.GetVstoObject(nativeWorkbook);
    }
    

產生 Excel 工作表的主項目

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

    Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
        Globals.ThisAddIn.Application.ActiveSheet
    If NativeWorksheet IsNot Nothing Then
        Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
            Globals.Factory.GetVstoObject(NativeWorksheet)
    End If
    
    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 時,該方法會傳回 ListObjectListObject具有原始的所有功能 ListObject 。 它也有其他功能,而且可以使用 Windows Forms 資料系結模型來系結至資料。 如需詳細資訊,請參閱 ListObject 控制項

產生 ListObject 的主控制項

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

    Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
        Globals.ThisAddIn.Application.ActiveSheet
    If sheet.ListObjects.Count > 0 Then
        Dim listObject As Excel.ListObject = sheet.ListObjects(1)
        Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
            Globals.Factory.GetVstoObject(listObject)
    End If
    
    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);
    }
    

將 managed 控制項加入檔和工作表

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

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

注意

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

保存和移除控制項

將 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 document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub
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 document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub
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.HasVstoMethod 方法。 傳入您要針對擴充物件測試的原生 Word 或 Excel 物件,例如 DocumentWorksheet

如果您只想在指定的 Office 物件具有擴充物件時才執行程式碼,HasVstoObject 方法會很有用。 例如,如果您有一個會處理事件的 Word VSTO 增益集, DocumentBeforeSave 以便在檔儲存之前移除其中的 managed 控制項,請使用 HasVstoObject 方法來判斷檔是否已擴充。 如果檔尚未擴充,它就不能有 managed 控制項,而且事件處理常式可以在不嘗試清除檔上的控制項的情況下返回。

另請參閱