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

更新： 2008 年 7 月

從 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 增益集專案

• 建立名為 WordDynamicControls 的 Word 2007 應用程式層級增益集專案。如需詳細資訊，請參閱 HOW TO：建立 Visual Studio Tools for Office 專案。

提供可將控制項加入至文件的 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. 儲存文件。

   按鈕便會從文件中移除。

後續步驟

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

• 如需示範如何在執行階段將許多其他型別的控制項加入至文件，以及在文件重新開啟時重新建立控制項的範例，請參閱 Word 增益集動態控制項範例。

• 如需示範如何使用 Excel 應用程式層級增益集將控制項加入至工作表的逐步解說，請參閱逐步解說：在應用程式層級專案的執行階段中將控制項加入至工作表。

請參閱

工作

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

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

Word 增益集動態控制項範例

概念

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

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

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

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

變更記錄