逐步解說：在應用程式層級增益集的執行階段中將控制項加入至文件

發行項
08/12/2011

您可以使用應用程式層級增益集，將控制項加入至任何開啟的 Microsoft Office Word 文件。本逐步解說將示範如何使用功能區，讓使用者將 Button 或 RichTextContentControl 加入至文件。

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

這個逐步解說將說明下列工作：

建立新的 Word 增益集專案。
提供可將控制項加入至文件的使用者介面 (UI)。
在執行階段將控制項加入至文件。
從文件移除控制項。

注意事項
您的電腦可能會在下列說明中，以不同名稱或位置顯示某些 Visual Studio 使用者介面項目。您所擁有的 Visual Studio 版本以及使用的設定會決定這些項目。如需詳細資訊，請參閱 Visual Studio 設定。

必要條件

您需要下列元件才能完成此逐步解說：

包含 Microsoft Office 開發者工具的 Visual Studio 2010 版本。 如需詳細資訊，請參閱[設定電腦以開發 Office 方案](bb398242\(v=vs.100\).md)。

Word 2007 或 Word 2010。

建立新的 Word 增益集專案

請從建立 Word 增益集專案開始。

若要建立新的 Word 增益集專案

建立名為 WordDynamicControls 的 Word 應用程式層級增益集專案。如需詳細資訊，請參閱 HOW TO：在 Visual Studio 中建立 Office 專案。
如果專案的目標為 .NET Framework 4，則加入 Microsoft.Office.Tools.Word.v4.0.Utilities.dll 組件的參考。本逐步解說稍後會需要用到此參考，以便使用程式設計的方式將 Windows Form 控制項加入至文件。

提供可將控制項加入至文件的 UI

將自訂索引標籤加入至 Word 中的功能區。使用者可以選取索引標籤上的核取方塊，將控制項加入至文件。

若要提供可將控制項加入至文件的 UI

在 [專案] 功能表上，按一下 [加入新項目]。
選取 [加入新項目] 對話方塊中的 [功能區 (視覺化設計工具)]。
將新功能區的名稱改成 MyRibbon，然後按一下 [加入]。

MyRibbon.cs 或 MyRibbon.vb 檔案會在功能區設計工具中開啟，並顯示預設索引標籤和群組。
在功能區設計工具中，按一下 [group1] 群組。
在 [屬性] 視窗中，將 [group1] 的 [Label] 屬性變更為 [加入控制項]。
從 [工具箱] 的 [Office 功能區控制項] 索引標籤，將 CheckBox 控制項拖曳至 [group1]。
按一下 [CheckBox1] 予以選取。
在 [屬性] 視窗中變更下列屬性。

屬性

值

Name

addButtonCheckBox

Label

加入按鈕
將第二個核取方塊加入至 [group1]，然後變更下列屬性。

屬性

值

Name

addRichTextCheckBox

Label

加入 RTF 控制項
在功能區設計工具中，按兩下 [加入按鈕]。

[加入按鈕] 核取方塊的 Click 事件處理常式隨即在程式碼編輯器中開啟。
回到功能區設計工具，然後按兩下 [加入 RTF 控制項]。

[加入 RTF 控制項] 核取方塊的 Click 事件處理常式隨即在程式碼編輯器中開啟。

屬性	值
Name	addButtonCheckBox
Label	加入按鈕

屬性	值
Name	addRichTextCheckBox
Label	加入 RTF 控制項

在本逐步解說的稍後內容中，您會將程式碼加入至這些事件處理常式，以便加入和移除現用文件上的控制項。

加入和移除現用文件上的控制項

在增益集程式碼中，您必須將現用文件轉換為 Microsoft.Office.Tools.Word.Document「主項目」(Host Item)，才能加入控制項。在 Visual Studio Tools for Office 方案中，Managed 控制項只能加入至可做為控制項之容器 (Container) 的主項目。在應用程式層級增益集專案中，可以在執行階段藉用 GetVstoObject 方法建立主項目。

請在 ThisAddIn 類別中加入方法，以便呼叫這些方法來為現用文件加入或移除 Button 或 RichTextContentControl。在本逐步解說的稍後內容中，您會在功能區的這些核取方塊的 Click 事件處理常式呼叫這些方法。

若要加入和移除現用文件上的控制項

在 [方案總管] 中，按兩下 ThisAddIn.cs 或 ThisAddIn.vb，以便在程式碼編輯器中開啟這個檔案。

將下列程式碼加入至 ThisAddIn 類別。這個程式碼會宣告 Button 和 RichTextContentControl 物件，這些物件代表要加入至文件的控制項。

Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
Private richTextControl As RichTextContentControl = Nothing

private Microsoft.Office.Tools.Word.Controls.Button button = null;
private RichTextContentControl richTextControl = null;

將下列方法加入至 ThisAddIn 類別。當使用者按一下功能區上的 [加入按鈕] 核取方塊時，如果該核取方塊為選取狀態，則這個方法會將 Button 加入至目前在文件中選取的項目，如果該核取方塊為清除狀態，則這個方法會移除 Button。

Friend Sub ToggleButtonOnDocument()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyButton"

    If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            button = vstoDocument.Controls.AddButton( _
                selection.Range, 100, 30, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleButtonOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    string name = "MyButton";

    if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
    {
        Word.Selection selection = this.Application.Selection;
        if (selection != null && selection.Range != null)
        {
            button = vstoDocument.Controls.AddButton(
                selection.Range, 100, 30, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

將下列方法加入至 ThisAddIn 類別。當使用者按一下功能區上的 [加入 RTF 控制項] 核取方塊時，如果該核取方塊為選取狀態，則這個方法會將 RichTextContentControl 加入至目前在文件中選取的項目，如果該核取方塊為清除狀態，則這個方法會移除 RichTextContentControl。

Friend Sub ToggleRichTextControlOnDocument()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyRichTextBoxControl"

    If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                    selection.Range, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleRichTextControlOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    string name = "MyRichTextBoxControl";

    if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
    {
        Word.Selection selection = this.Application.Selection;
        if (selection != null && selection.Range != null)
        {
            richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                selection.Range, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

在文件儲存時移除按鈕控制項

當文件儲存並接著關閉時，並不會保存 Windows Form 控制項。但是，每個控制項的 ActiveX 包裝函式仍會保留在文件中，而且當文件重新開啟時，使用者還可以看見這個包裝函式的框線。您可以使用數種方法，透過增益集清除動態建立的 Windows Form 控制項。您會在這個逐步解說中使用程式設計的方式，在文件儲存時移除 Button 控制項。

若要在文件儲存時移除按鈕控制項

在 ThisAddIn.cs 或 ThisAddIn.vb 程式碼檔中，加入下列程式碼至 ThisAddIn 類別。這個方法是 DocumentBeforeSave 事件的事件處理常式。如果儲存的文件有相關聯的 Document 主項目，事件處理常式就會取得這個主項目，並移除 Button 控制項 (如果存在的話)。

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim isExtended As Boolean = Doc.HasVstoObject()

    If isExtended Then
        ' Use the following line of code in projects that target the .NET Framework 4.
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        ' In projects that target the .NET Framework 3.5, use the following line of code.
        ' Dim vstoDocument As Document = Doc.GetVstoObject()

        If vstoDocument.Controls.Contains(button) Then
            vstoDocument.Controls.Remove(button)
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
        End If
    End If
End Sub

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    // Use the following line of code in projects that target the .NET Framework 4.
    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // bool isExtended = Doc.HasVstoObject();

    if (isExtended)
    {
        // Use the following line of code in projects that target the .NET Framework 4.
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

        // In projects that target the .NET Framework 3.5, use the following line of code.
        // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();

        if (vstoDocument.Controls.Contains(button))
        {
            vstoDocument.Controls.Remove(button);
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
        }
    }
}

在 C# 中，將下列程式碼加入至 ThisAddIn_Startup 事件處理常式。這是在 C# 中連接 Application_DocumentBeforeSave 事件處理常式和 DocumentBeforeSave 事件時的必要程式碼。
```
this.Application.DocumentBeforeSave += 
    new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
    Application_DocumentBeforeSave);
```

在使用者按一下功能區中的核取方塊時加入和移除控制項

最後，請修改您加入至功能區之核取方塊的 Click 事件處理常式，以便加入或移除文件上的控制項。

若要在使用者按一下功能區中的核取方塊時加入和移除控制項

在 MyRibbon.cs 或 MyRibbon.vb 程式碼檔中，以下列程式碼取代產生的 addButtonCheckBox_Click 和 addRichTextCheckBox_Click 事件處理常式。這段程式碼會重新定義這些事件處理常式，使其呼叫稍早在本逐步解說中加入至 ThisAddIn 類別的 ToggleButtonOnDocument 和 ToggleRichTextControlOnDocument 方法。

Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
    Globals.ThisAddIn.ToggleButtonOnDocument()
End Sub

Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
    Globals.ThisAddIn.ToggleRichTextControlOnDocument()
End Sub

private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleButtonOnDocument();
}

private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleRichTextControlOnDocument();
}

測試方案

從功能區上的自訂索引標籤選取控制項，將此控制項加入至文件。當您儲存文件時，Button 控制項就會被移除。

若要測試方案

請按 F5 執行您的專案。
在現用文件中，按 ENTER 數次，將新的空白段落加入至文件。
選取第一個段落。
按一下 [增益集] 索引標籤。
在 [加入控制項] 群組中，按一下 [加入按鈕]。

按鈕隨即出現在第一個段落中。
選取最後一個段落。
在 [加入控制項] 群組中，按一下 [加入 RTF 控制項]。

Rich Text 內容控制項隨即加入至最後一個段落。
儲存文件。

按鈕便會從文件中移除。

後續步驟

您可以從下列主題，進一步了解應用程式層級增益集中的控制項：

如需示範如何在執行階段將許多其他型別的控制項加入至文件，以及在文件重新開啟時重新建立控制項的範例，請參閱 Office 程式開發範例和逐步解說中的＜Word 增益集動態控制項範例＞。
如需示範如何使用 Excel 應用程式層級增益集將控制項加入至工作表的逐步解說，請參閱逐步解說：在應用程式層級專案的執行階段中將控制項加入至工作表。

請參閱

共用方式為