通过

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

更新： 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 专业版 和 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

    添加多格式文本控件

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

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

  11. 返回到功能区设计器，并双击“添加多格式文本控件”。

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

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

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

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

保存文档后移除 Button 控件

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

保存文档后移除 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. 在“添加控件”组中，单击“添加多格式文本控件”。

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

  8. 保存文档。

    按钮随即从文档中移除。

后续步骤

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

请参见

任务

如何：为 Office 文档添加 Windows 窗体控件

如何：向 Word 文档添加内容控件

Word 外接程序动态控件示例

概念

Word 应用程序级外接程序开发

在运行时向 Office 文档添加控件

在 Office 文档中保存动态控件

在运行时在应用程序级外接程序中扩展 Word 文档和 Excel 工作簿

修订记录

日期

修订历史记录

原因

2008 年 7 月

新增主题。

SP1 功能更改。