共用方式為

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

  • 發行項

更新： 2008 年 7 月

適用於

本主題中的資訊僅適用於指定的 Visual Studio Tools for Office 專案和 Microsoft Office 版本。

專案類型

  • 應用程式層級專案

Microsoft Office 版本

  • Word 2007

如需詳細資訊，請參閱依應用程式和專案類型提供的功能。

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

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

  • 建立新的 Word 增益集專案。

  • 提供可將控制項加入至文件的使用者介面 (UI)。

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

  • 從文件移除控制項。

注意事項：

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

必要條件

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

  • Visual Studio Tools for Office (Visual Studio 2008 Professional 和 Visual Studio Team System 的選擇性元件)。

  • Visual Studio 2008 SP1

  • Microsoft Office Word 2007

建立新的 Word 增益集專案

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

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

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

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

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

  1. 在 [專案] 功能表上，按一下 [加入新項目]。

  2. 選取 [加入新項目] 對話方塊中的 [功能區 (視覺化設計工具)]。

  3. 將新功能區的名稱改成 MyRibbon，然後按一下 [加入]。

    MyRibbon.cs 或 MyRibbon.vb 檔案會在功能區設計工具中開啟，並顯示預設索引標籤和群組。

  4. 在功能區設計工具中，按一下 [group1] 群組。

  5. 在 [屬性] 視窗中，將 [group1] 的 [Label] 屬性變更為 [加入控制項]。

  6. 從 [工具箱] 的 [Office 功能區控制項] 索引標籤，將 CheckBox 控制項拖曳至 [group1]。

  7. 按一下 [CheckBox1] 予以選取。

  8. 在 [屬性] 視窗中變更下列屬性。

    屬性

    值

    Name

    addButtonComboBox

    Label

    加入按鈕

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

    屬性

    值

    Name

    addRichTextCheckBox

    Label

    加入 RTF 控制項

  10. 在功能區設計工具中，按兩下 [加入按鈕]。

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

  11. 回到功能區設計工具，然後按兩下 [加入 RTF 控制項]。

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

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

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

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

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

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

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

  2. 將下列程式碼加入至 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;

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

    Friend Sub ToggleButtonOnDocument()
    Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
    Dim vstoDocument As Document = nativeDocument.GetVstoObject()
    Dim name As String = "MyButton"

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

    internal void ToggleButtonOnDocument()
{
    Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
    Document vstoDocument = nativeDocument.GetVstoObject();
    string name = "MyButton";

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

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

    Friend Sub ToggleRichTextControlOnDocument()
    Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
    Dim vstoDocument As Document = nativeDocument.GetVstoObject()
    Dim name As String = "MyRichTextBoxControl"

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

    internal void ToggleRichTextControlOnDocument()
{
    Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
    Document vstoDocument = nativeDocument.GetVstoObject();
    string name = "MyRichTextBoxControl";

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

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

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

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

  1. 在 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
    If Doc.HasVstoObject() Then
        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)
{
    if (Doc.HasVstoObject())
    {
        Document vstoDocument = Doc.GetVstoObject();

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

  2. 在 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 控制項就會被移除。

若要測試方案

  1. 請按 F5 執行您的專案。

  2. 在現用文件中，按 ENTER 數次，將新的空白段落加入至文件。

  3. 選取第一個段落。

  4. 按一下 [增益集] 索引標籤。

  5. 在 [加入控制項] 群組中，按一下 [加入按鈕]。

    按鈕隨即出現在第一個段落中。

  6. 選取最後一個段落。

  7. 在 [加入控制項] 群組中，按一下 [加入 RTF 控制項]。

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

  8. 儲存文件。

    按鈕便會從文件中移除。

後續步驟

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

請參閱

工作

HOW TO：將 Windows Form 控制項加入至 Office 文件

HOW TO：將內容控制項加入至 Word 文件

Word 增益集動態控制項範例

概念

Word 應用程式層級增益集開發

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

在 Office 文件中保存動態控制項

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

變更記錄

日期

記錄

原因

2008 年 7 月

加入主題。

SP1 功能變更。