通过

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

  • 项目

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

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

本演练阐释了以下任务：

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

  • 提供用于向文档添加控件的用户界面 (UI)。

  • 在运行时向文档添加控件。

  • 从文档中删除控件。

    注意

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

先决条件

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

创建新的 Word 外接程序项目

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

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

  1. 为 Word 创建名为 WordDynamicControls 的 VSTO 外接程序项目。 有关详细信息，请参阅“如何：在 Visual Studio 中创建办公室项目。

  2. 添加对 Microsoft.Office.Tools.Word.v4.0.Utilities.dll 程序集的引用。 在本演练后面的部分中，需要此引用才能以编程方式向文档中添加 Windows 窗体控件。

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

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

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

  1. 在 “项目” 菜单上，单击 “添加新项”。

  2. 在 “添加新项” 对话框中，选择 “功能区(可视化设计器)”。

  3. 将新功能区更名为 “MyRibbon”，然后单击 “添加”。

    MyRibbon.cs 或 MyRibbon.vb 文件将在功能区设计器中打开，并显示一个默认选项卡和组。

  4. 在功能区设计器中，单击“group1” 组。

  5. 在“属性” 窗口中，将“group1” 的“Label” 属性更改为“添加控件” 。

  6. 从“工具箱” 的“Office 功能区控件” 选项卡中将“CheckBox” 控件拖到“group1” 上。

  7. 单击 CheckBox1 以将其选中。

  8. 在 “属性” 窗口中，更改下列属性。

    属性 值
    Name addButtonCheckBox
    标签 “添加”按钮

  9. 将第二个复选框添加到 group1，然后更改下列属性。

    属性 值
    Name addRichTextCheckBox
    标签 添加 RTF 控件

  10. 在功能区设计器中，双击“添加按钮” 。

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

  11. 返回到功能区设计器，并双击“添加 RTF 控件” 。

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

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

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

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

向 ThisAddIn 类添加相应的方法，调用这些方法可在活动文档中添加或删除 Button 或 RichTextContentControl 。 在本演练后面的部分中，你将在功能区中从复选框的 Click 事件处理程序调用这些方法。

若要在活动文档中添加和删除控件

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

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

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

  3. 将以下方法添加到 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);
    }
}

  4. 将以下方法添加到 ThisAddIn 类。 当用户单击功能区中的“添加 RTF 控件” 复选框时，如果选中了该复选框，此方法会向文档中的当前选定内容添加一个 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);
    }
}

保存文档时删除按钮控件

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

保存文档后删除 Button 控件

  1. 在 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;
        }
    }
}

  2. 在 C# 中，将下面的代码添加到 ThisAddIn_Startup 事件处理程序中。 在 C# 中，此代码是必需的，用于连接 Application_DocumentBeforeSave 事件处理程序和 DocumentBeforeSave 事件。

    this.Application.DocumentBeforeSave += 
    new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
    Application_DocumentBeforeSave);

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

最后，修改Click添加到功能区中的检查框的事件处理程序，以添加或删除文档中的控件。

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

  1. 在 MyRibbon.cs 或 MyRibbon.vb 代码文件中，将生成的 addButtonCheckBox_Click 事件处理程序 addRichTextCheckBox_Click 和事件处理程序替换为以下代码。 此代码重新定义这些事件处理程序，以调用之前在本演练中添加到 ToggleButtonOnDocument 类中的 ToggleRichTextControlOnDocument 和 ThisAddIn 方法。

    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 控件” 。

    一个 RTF 内容控件随即添加到最后一个段落中。

  8. 保存文档。

    按钮随即从文档中删除。

后续步骤

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

  • 有关演示如何在运行时向文档添加许多其他类型的控件并在重新打开文档时重新创建控件的示例，请参阅办公室开发示例和演练中的 Word 外接程序动态控件示例。

  • 有关演示如何使用适用于 Excel 的 VSTO 外接程序将控件添加到工作表的演练，请参阅 演练：在 VSTO 外接程序项目中的运行时向工作表添加控件。

相关内容