演练：运行时在应用程序级外接程序中向文档添加控件

项目
08/12/2011

您可以使用应用程序级外接程序向任何打开的 Microsoft Office Word 文档添加控件。本演练演示如何使用功能区来允许用户向文档添加 Button 或 RichTextContentControl。

**适用于：**本主题中的信息适用于 Word 2007 和 Word 2010 的应用程序级项目。有关更多信息，请参见按 Office 应用程序和项目类型提供的功能。

本演练阐释了以下任务：

创建新的 Word 外接程序项目。
提供用于向文档添加控件的用户界面 (UI)。
在运行时向文档添加控件。
从文档中移除控件。

提示

对于在以下说明中使用的某些 Visual Studio 用户界面元素，您的计算机可能会显示不同的名称或位置。这些元素取决于您所使用的 Visual Studio 版本和您所使用的设置。有关更多信息，请参见 Visual Studio 设置。

系统必备

您需要以下组件来完成本演练：

Visual Studio 2010 的一个版本，其中包含 Microsoft Office 开发工具。有关更多信息，请参见[将计算机配置为开发 Office 解决方案](bb398242\(v=vs.100\).md)。

Word 2007 或 Word 2010。

创建新的 Word 外接程序项目

首先创建 Word 外接程序项目。

创建新的 Word 外接程序项目

为 Word 创建一个名为 WordDynamicControls 的应用程序级外接程序项目。有关更多信息，请参见如何：在 Visual Studio 中创建 Office 项目。
如果项目面向 .NET Framework 4，请添加对 Microsoft.Office.Tools.Word.v4.0.Utilities.dll 程序集的引用。在本演练后面的部分中，需要此引用才能以编程方式向文档中添加 Windows 窗体控件。

提供用于向文档添加控件的 UI

向 Word 的功能区添加一个自定义选项卡。用户可以通过选择该选项卡上的复选框来向文档添加控件。

提供用于向文档添加控件的 UI

在**“项目”菜单上，单击“添加新项”**。
在**“添加新项”对话框中，选择“功能区(可视化设计器)”**。
将新功能区更名为 MyRibbon，然后单击**“添加”**。

MyRibbon.cs 或 MyRibbon.vb 文件将在功能区设计器中打开，并显示一个默认选项卡和组。
在功能区设计器中，单击**“group1”**组。
在**“属性”窗口中，将“group1”的“Label”**属性更改为“添加控件”。
从**“工具箱”的“Office 功能区控件”选项卡中将“CheckBox”控件拖到“group1”**上。
单击**“CheckBox1”**将其选定。
在**“属性”**窗口中，更改下列属性。

Property

值

名称

addButtonCheckBox

标签

添加按钮
向**“group1”**再添加一个复选框，然后更改下列属性。

Property

值

名称

addRichTextCheckBox

标签

添加多格式文本控件
在功能区设计器中，双击“添加按钮”。

“添加按钮”复选框的 Click 事件处理程序将在代码编辑器中打开。
返回到功能区设计器，并双击“添加多格式文本控件”。

“添加多格式文本控件”复选框的 Click 事件处理程序将在代码编辑器中打开。

Property	值
名称	addButtonCheckBox
标签	添加按钮

Property	值
名称	addRichTextCheckBox
标签	添加多格式文本控件

在本演练后面的部分中，您将向这些事件处理程序添加代码，以在活动文档中添加和移除控件。

在活动文档中添加和移除控件

在外接程序代码中，您必须先将活动文档转换为 Microsoft.Office.Tools.Word.Document 宿主项，然后才能添加控件。在 Visual Studio Tools for Office 解决方案中，只能将托管控件添加到充当控件容器的宿主项中。在应用程序级外接程序项目中，可以通过使用 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 类中。当用户单击功能区中的“添加多格式文本控件”复选框时，如果选中了该复选框，此方法会向文档中的当前选定内容中添加一个 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);
    }
}

保存文档后移除 Button 控件

保存并关闭文档后，Windows 窗体控件不会保留在文档中。但是，每个控件的 ActiveX 包装会保留在文档中，并且重新打开文档后，最终用户会看到各包装的边框。可通过多种方法清除在外接程序中动态创建的 Windows 窗体控件。在本演练中，您将以编程方式在保存文档后移除 Button 控件。

保存文档后移除 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 以向文档添加新的空段落。
选择第一个段落。
单击**“外接程序”**选项卡。
在**“添加控件”组中，单击“添加按钮”**。

一个按钮随即显示在第一个段落中。
选择最后一个段落。
在**“添加控件”组中，单击“添加多格式文本控件”**。

一个多格式文本内容控件随即添加到最后一个段落中。
保存文档。

按钮随即从文档中移除。

后续步骤

您可以从以下主题中了解有关应用程序级外接程序中的控件的更多信息：

有关演示如何在运行时向文档添加许多其他类型的控件以及在重新打开文档后重新创建控件的示例，请参见 Office 开发示例和演练中的“Word 外接程序动态控件示例”。
有关演示如何使用 Excel 应用程序级外接程序向工作表添加控件的演练，请参见演练：在运行时在应用程序级项目中向工作表中添加控件。

请参见

通过

演练：运行时在应用程序级外接程序中向文档添加控件

系统必备

创建新的 Word 外接程序项目

创建新的 Word 外接程序项目

提供用于向文档添加控件的 UI

提供用于向文档添加控件的 UI

在活动文档中添加和移除控件

在活动文档中添加和移除控件

保存文档后移除 Button 控件

保存文档后移除 Button 控件

用户单击功能区中的复选框时添加或移除控件

用户单击功能区中的复选框时添加或移除控件

测试解决方案

测试解决方案

后续步骤

请参见

任务

概念

其他资源

其他资源