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

可以将控件添加到 Microsoft Office Word 文档和 Microsoft Office Excel 工作簿在运行时。还可以移除它们在运行时。您添加或移除在运行时的控件称为 动态控件。

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

本主题讲述：

• 在运行时的托管使用控件集合。

• 将宿主控件添加到文档。

• 添加 Windows 窗体控件添加到文档。

有关相关的视频演示，请参见 How Do I: Add Controls to a Document Surface at Runtime?（如何实现：在运行时向文档图面添加控件？）。

使用控件集合在运行时管理控件

若要在运行时添加、获取或移除控件，请使用 Microsoft.Office.Tools.Excel.ControlCollection 和 Microsoft.Office.Tools.Word.ControlCollection 对象的帮助器方法。

访问这些对象的方式取决于要开发的项目的类型：

• 在 Excel 的文档级项目中，请使用 Sheet1、Sheet2 和 Sheet3 类的 Worksheet.Controls 属性。有关这些类的更多信息，请参见工作表宿主项。

• 在 Word 的文档级项目中，请使用 ThisDocument 类的 Document.Controls 属性。有关此类的更多信息，请参见文档宿主项。

• 在 Excel 或 Word 的应用程序级项目中，请使用您在运行时生成的 Microsoft.Office.Tools.Excel.Worksheet 或 Microsoft.Office.Tools.Word.Document 的 Controls 属性。有关在运行时生成这些对象的更多信息，请参见在运行时在应用程序级外接程序中扩展 Word 文档和 Excel 工作簿。

添加控件

Microsoft.Office.Tools.Excel.ControlCollection 和 Microsoft.Office.Tools.Word.ControlCollection 类型包含可用于添加宿主控件，和常用 Windows 窗体控件添加到文档或工作表的帮助器方法。每个方法名称具有格式 Add控件选件类，其中 控件选件类 是要添加控件的类名。例如，若要向文档中添加 NamedRange 控件，可以使用 AddNamedRange 方法。

下面的代码示例在 Excel 的文档级项目中向 Sheet1 添加了一个 NamedRange。

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

访问和删除控件

您可以使用 Microsoft.Office.Tools.Excel.Worksheet 或 Microsoft.Office.Tools.Word.Document 的 Controls 属性来循环访问文档中的所有控件，包括您在设计时添加的控件。在设计时添加的控件也称为“静态控件”。

可以通过如下方法移除动态控件：调用相应控件的 Delete 方法，或调用每个 Controls 集合的 Remove 方法。下面的代码示例使用 Remove 方法在 Excel 的文档级项目中从 Sheet1 移除一个 NamedRange。

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

无法在运行时移除静态控件。如果您尝试使用 Delete 或 Remove 方法来移除静态控件，将会引发 CannotRemoveControlException。

说明
请勿在文档的 Shutdown 事件处理程序中以编程方式移除控件。引发 Shutdown 事件时，文档的 UI 元素不再可用。如果要在文档关闭前移除控件，请将代码添加到其他事件的事件处理程序中，例如 Word 的 Document.BeforeClose 或 Document.BeforeSave 事件，或者 Excel 的 Workbook.BeforeClose 或 Workbook.BeforeSave 事件。

将宿主控件添加到文档中

以编程方式向文档添加宿主控件时，必须提供一个唯一标识该控件的名称，并且必须指定要在文档的什么位置添加该控件。有关具体说明，请参见以下主题：

• 如何：向工作表添加 ListObject 控件

• 如何：向工作表添加 NamedRange 控件

• 如何：向工作表添加 Chart 控件

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

• 如何：向 Word 文档添加书签控件

有关宿主控件的更多信息，请参见 宿主项和宿主控件概述。

保存并关闭文档后，所有动态创建的宿主控件都将与其事件断开连接并失去其数据绑定功能。您可以向解决方案添加代码，以便在文档重新打开时重新创建这些宿主控件。有关更多信息，请参见在 Office 文档中保存动态控件。

说明
没有为以下宿主控件提供帮助器方法，因为无法以编程方式将这些控件添加到文档中：XmlMappedRange、XMLNode 和 XMLNodes。

将 Windows 窗体控件添加到文档中

以编程方式向文档添加 Windows 窗体控件时，必须提供控件的位置以及唯一标识该控件的名称。Visual Studio Tools for Office Runtime为每个控件都提供了帮助器方法。这些方法将被重载，以便可以通过一个范围或特定坐标控件的位置。

保存并关闭文档后，将从文档中移除所有动态创建的 Windows 窗体控件。您可以向解决方案添加代码，以便在文档重新打开时重新创建这些控件。如果您创建动态 Windows 窗体控件时使用的是应用程序级外接程序，则这些控件的 ActiveX 包装将留在文档中。有关更多信息，请参见在 Office 文档中保存动态控件。

说明
无法以编程方式将 Windows 窗体控件添加到受保护的文档中。如果以编程方式取消对 Word 文档或 Excel 工作表的保护以添加控件，则必须编写附加代码以在关闭文档时移除控件的 ActiveX 包装。控件的 ActiveX 包装不会自动从受保护的文档删除。

添加自定义控件

如果可用的帮助器方法不支持，如自定义用户控件的要添加 System.Windows.Forms.Control，请使用下列方法：

• 对于 Excel，请使用 Microsoft.Office.Tools.Excel.ControlCollection 对象的 AddControl() 方法之一。

• 对于 Word，请使用 Microsoft.Office.Tools.Word.ControlCollection 对象的 AddControl() 方法之一。

若要添加这种控件，请将 System.Windows.Forms.Control、相应控件的位置和唯一标识相应控件的名称传递给 AddControl 方法。AddControl 方法返回的对象定义了控件与工作表或文档交互的方式。AddControl 方法返回 Microsoft.Office.Tools.Excel.ControlSite (对于 Excel) 或 Microsoft.Office.Tools.Word.ControlSite 对象 (对于 Word)。

下面的代码示例演示如何使用 AddControl(Control, Range, String) 方法动态添加自定义用户控件到文档级 Excel 项目中的工作表。在此示例中，用户控件名为 UserControl1，并且，Range 名为 range1。若要使用此示例，请运行它从在项目的 Sheetn 选件类。

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

使用自定义控件的成员

在使用 AddControl 方法之一向工作表或文档添加控件后，您现在就有了两个不同的控件对象：

• 表示自定义控件的 System.Windows.Forms.Control。

• 在控件添加到工作表或文档中后表示该控件的 ControlSite、OLEObject 或 OLEControl 对象。

这两个控件之间共享许多属性和方法。一定要通过适当的控件访问这些成员，这一点非常重要：

• 若要访问仅属于自定义控件的成员，请使用 System.Windows.Forms.Control。

• 若要访问这两个控件共享的成员，请使用 ControlSite、OLEObject 或 OLEControl 对象。

如果从 System.Windows.Forms.Control 访问共享的成员，访问可能失败并且不会显示警告或通知，或者可能产生无效的结果。除非所需的方法或属性不可用，否则请始终使用 ControlSite、OLEObject 或 OLEControl 对象的方法或属性；只有当所需的方法或属性不可用时才应引用 System.Windows.Forms.Control。

例如，ControlSite 类和 System.Windows.Forms.Control 类都有 Top 属性。若要获取或设置控件顶部与文档顶部之间的距离，请使用 ControlSite 的 Top 属性，不要使用 System.Windows.Forms.Control 的 Top 属性。

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

请参见

任务

如何：向工作表添加 ListObject 控件

如何：向工作表添加 NamedRange 控件

如何：向工作表添加 Chart 控件

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

如何：向 Word 文档添加书签控件

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

概念

在 Office 文档中保存动态控件

Office 文档上的 Windows 窗体控件概述

其他资源

Office 文档上的控件