共用方式為

在應用程式層級增益集的執行階段中擴充 Word 文件和 Excel 活頁簿

  • 發行項

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

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

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

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

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

本主題中的資訊適用於應用程式層級專案中下列應用程式的套用: :Excel 2010;Word 2010。如需詳細資訊，請參閱依 Office 應用程式和專案類型提供的功能。

使用增益集產生擴充物件

擴充物件 是將功能加入至原本就存在於 Word 或 Excel 物件模型 (Visual Studio Tools for Office Runtime 提供型別的執行個體 (稱為" 原生 Office 物件)。若要產生 Word 或 Excel物件的擴充物件，請使用 GetVstoObject 方法。第一次呼叫所指定的 Word 或 Excel 物件的 GetVstoObject 方法時，會傳回可擴充指定之物件的新物件。每次呼叫方法並指定相同的 Word 或 Excel 物件時，它會傳回相同的擴充物件。

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

GetVstoObject 方法主要是用於應用程式層級專案。您也可以在文件層級專案中使用這些方法，但它們會有不同的行為，而且用途較少。

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

Cc442981.collapse_all(zh-tw,VS.110).gif產生主項目

當您使用 GetVstoObject 擴充文件層級物件 (也就是 Microsoft.Office.Interop.Excel.Workbook、Microsoft.Office.Interop.Excel.Worksheet 或 Microsoft.Office.Interop.Word.Document) 時，傳回的物件就稱為「主項目」(Host Item)。主項目是可以包含其他物件 (包括其他擴充物件和控制項) 的型別。它類似 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);
}

Cc442981.collapse_all(zh-tw,VS.110).gif產生 ListObject 主控制項

當您使用 GetVstoObject 方法擴充 Microsoft.Office.Interop.Excel.ListObject 時，這個方法會傳回 Microsoft.Office.Tools.Excel.ListObject。Microsoft.Office.Tools.Excel.ListObject 除了擁有原始 Microsoft.Office.Interop.Excel.ListObject 的所有功能，還具備其他功能，例如使用 Windows Form 資料繫結模型繫結至資料的能力。如需詳細資訊，請參閱 ListObject 控制項。

若要產生 ListObject 的主控制項

  • 下列程式碼範例示範如何產生第一 Microsoft.Office.Interop.Excel.ListObject 的 Microsoft.Office.Tools.Excel.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 控制項加入至文件和工作表

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

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

注意事項注意事項

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

Cc442981.collapse_all(zh-tw,VS.110).gif保存和移除控制項

如果將 Managed 控制項加入至文件或工作表，則文件在儲存並關閉時，該控制項無法保存。移除所有主控制項，以便只有基礎原生 Office 物件忘記。例如， Microsoft.Office.Tools.Excel.ListObject 變成 Microsoft.Office.Interop.Excel.ListObject。所有的 Windows Form 控制項也會移除，但是控制項的 ActiveX 包裝函式會留在文件中。您必須用增益集，加入清除控制項的程式碼，或在下次開啟文件時重新建立控制項。如需詳細資訊，請參閱 在 Office 文件中保存動態控制項。

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

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

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

Cc442981.collapse_all(zh-tw,VS.110).gif使用原生 Word 物件的範例

下列程式碼範例將示範如何處理 Word 文件的應用程式層級事件。CreateDocument 方法會建立新文件，然後定義防止儲存這份文件的 DocumentBeforeSave 事件處理常式。因為這是針對 Microsoft.Office.Interop.Word.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;
    }
}

Cc442981.collapse_all(zh-tw,VS.110).gif使用主項目的範例

下列程式碼範例會處理 Microsoft.Office.Tools.Word.Document 主項目的 BeforeSave 事件以簡化這個程序。以下範例中的 CreateDocument2 方法會產生擴充 document2 物件的 Microsoft.Office.Tools.Word.Document，然後再定義防止文件儲存的 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，否則會傳回 false。

請使用 Globals.Factory.HasVstoMethod 方法。在原生 Word 或 Excel 物件的傳遞，例如 Microsoft.Office.Interop.Word.Document 或 Microsoft.Office.Interop.Excel.Worksheet，您會想要為擴充物件測試。

如果您只想在指定的 Office 物件具有擴充物件時才執行程式碼，HasVstoObject 方法會很有用。例如，如果您有一個會處理 DocumentBeforeSave 事件，以便在文件儲存之前移除其中的 Managed 控制項的 Word 增益集，這時您就可以使用 HasVstoObject 方法，判斷該文件是否經過擴充。如果文件尚未擴充，它就無法包含 Managed 控制項，這樣一來，事件處理常式可能會直接返回，而不嘗試清除文件上的控制項。

請參閱

概念

在執行階段將控制項加入至 Office 文件

主項目和主控制項概觀

其他資源

應用程式層級增益集程式設計

Office 程式開發範例和逐步解說