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

可以使用 VSTO 外接程序将控件添加到任何打开Microsoft Office Word 文档。本演练演示如何使用功能区让用户能够向文档中添加Button或RichTextContentControl。

适用于： 本主题中的信息适用于 Word 2010 的 VSTO 外接程序项目。有关详细信息，请参阅 Office 应用程序和项目类型提供的功能。

本演练阐释了以下任务：

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

注释

以下说明中的某些 Visual Studio 用户界面元素在计算机上出现的名称或位置可能会不同。这些元素取决于你所使用的 Visual Studio 版本和你所使用的设置。有关详细信息，请参阅个性化设置 IDE。

先决条件

你需要满足以下条件才能完成本演练：

包含 Microsoft Office 开发人员工具的 Visual Studio 版本。有关详细信息，请参阅配置计算机以开发 Office 解决方案。
Word 2013 或 Word 2010。

创建新的 Word 外接程序项目

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

创建新的 Word VSTO 外接程序项目

为 Word 创建名为 WordDynamicControls 的 VSTO 外接程序项目。有关详细信息，请参阅如何：在 Visual Studio 中创建 Office 项目。
添加对 Microsoft.Office.Tools.Word.v4.0.Utilities.dll 程序集的引用。本演练稍后需要此引用以编程方式将 Windows 窗体控件添加到文档中。

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

将自定义标签添加到 Word 中的功能区。用户可以在选项卡上选中复选框，将控件添加到文档。

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

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

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

资产价值

名称 addButtonCheckBox

标签 添加按钮
将第二个复选框添加到 group1，然后更改以下属性。

资产价值

名称 添加富文本复选框

标签 添加 RTF 控件
在功能区设计器中，双击“ 添加按钮”。

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

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

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

资产	价值
名称	addButtonCheckBox
标签	添加按钮

资产	价值
名称	添加富文本复选框
标签	添加 RTF 控件

在活动文档上添加和删除控件

在 VSTO 外接程序代码中，必须先将活动文档转换为 Document宿主项，然后才能添加控件。在 Office 解决方案中，只能将托管控件添加到宿主项，这些项充当控件的容器。在 VSTO 外接程序项目中，可以使用该方法 GetVstoObject 在运行时创建宿主项。

将方法添加到ThisAddIn类中，该方法可用于在活动文档中添加或删除Button或RichTextContentControl。本演练后期，你将从 Ribbon 复选框的事件处理程序中调用这些方法。

在活动文档上添加和删除控件

在 解决方案资源管理器中，双击 ThisAddIn.cs 或 ThisAddIn.vb 在代码编辑器中打开该文件。

将以下代码添加到 ThisAddIn 类。此代码声明 Button 和 RichTextContentControl 表示要添加到文档中的控件的对象。

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

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

将以下方法添加到 ThisAddIn 类。当用户单击功能区上的 “添加按钮” 复选框时，如果选中该复选框，此方法会在文档的当前选定内容中添加一个 Button；如果取消选中该复选框，则会删除 Button。

internal void ToggleButtonOnDocument()
{
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);


    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);
    }
}

Friend Sub ToggleButtonOnDocument()
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    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

将以下方法添加到 ThisAddIn 类。当用户单击功能区上的 “添加富文本控件” 复选框时，如果选中了该复选框，该方法会将在文档的当前选定内容上添加一个 RichTextContentControl ；如果清除了复选框，则将移除 RichTextContentControl 。

internal void ToggleRichTextControlOnDocument()
{

    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);


    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);
    }
}

Friend Sub ToggleRichTextControlOnDocument()

    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    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

保存文档时删除按钮控件

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

在保存文档时删除按钮控件

在 ThisAddIn.cs 或 ThisAddIn.vb 代码文件中，将以下方法添加到 ThisAddIn 类。此方法是DocumentBeforeSave事件的处理程序。如果保存的文档具有 Document 与之关联的主机项，事件处理程序将获取宿主项并删除 Button 该控件（如果存在）。

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    bool isExtended = Globals.Factory.HasVstoObject(Doc);


    if (isExtended)
    {

        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

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

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave

    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)


    If isExtended Then
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)


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

在 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 void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleButtonOnDocument();
}

private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.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

测试解决方案

通过从功能区上的自定义选项卡中选择控件，将控件添加到文档中。保存文档时，将删除Button控件。

测试解决方案。

按 F5 运行项目。
在活动文档中，按 Enter 键多次，以向文档添加新的空段落。
选择第一段。
单击“ 加载项 ”选项卡。
在 “添加控件 ”组中，单击“ 添加按钮”。

第一段中会显示一个按钮。
选择最后一段。
在 “添加控件 ”组中，单击“ 添加 RTF 控件”。

富文本内容控件将添加到最后一段。
保存文档。

按钮已从文档中删除。

后续步骤

可以从以下主题了解有关 VSTO 外接程序中的控件的详细信息：

有关演示如何在运行时向文档添加许多其他类型的控件并在重新打开文档时重新创建控件的示例，请参阅 Office 开发示例和演练中的 Word Add-In 动态控件示例。
有关演示如何使用适用于 Excel 的 VSTO 外接程序将控件添加到工作表的演练，请参阅演练：在 VSTO 外接程序项目中的运行时向工作表添加控件。

反馈

此页面是否有帮助？

Last updated on 2025-12-12

通过

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

先决条件

创建新的 Word 外接程序项目

创建新的 Word VSTO 外接程序项目

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

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

在活动文档上添加和删除控件

在活动文档上添加和删除控件

保存文档时删除按钮控件

在保存文档时删除按钮控件

当用户单击功能区上的复选框时添加和删除控件

当用户单击功能区上的复选框时添加或删除控件

测试解决方案

测试解决方案。

后续步骤

相关内容

反馈

其他资源