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

项目
08/12/2011

可以在运行时向 Microsoft Office Word 文档和 Microsoft Office Excel 工作簿添加控件，也可从中移除控件。在运行时向文档添加的控件称为“动态控件”。

**适用于：**本主题中的信息适用于以下应用程序的文档级项目和应用程序级项目：Excel 2007 和 Excel 2010；Word 2007 和 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 方法。有关完整的帮助器方法列表，请参见宿主控件的帮助器方法和 Windows 窗体控件的帮助器方法。

下面的代码示例在 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 事件。

将宿主控件添加到文档中

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

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

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

提示

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

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

以编程方式向文档添加 Windows 窗体控件时，必须提供控件的位置以及唯一标识该控件的名称。 Visual Studio Tools for Office Runtime为每个控件都提供了帮助器方法。这些方法将被重载，以便您可以传递控件位置的范围或特定坐标。有关具体说明，请参见如何：为 Office 文档添加 Windows 窗体控件。

保存并关闭文档后，将从文档中移除所有动态创建的 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 方法返回的对象定义了控件与工作表或文档交互的方式。所返回对象的类型取决于项目：

对于面向 .NET Framework 4 的项目，此方法返回 Microsoft.Office.Tools.Excel.ControlSite（对于 Excel）或 Microsoft.Office.Tools.Word.ControlSite（对于 Word）对象。
对于面向 .NET Framework 3.5 的项目，此方法返回 Microsoft.Office.Tools.Excel.OLEObject（对于 Excel）或 Microsoft.Office.Tools.Word.OLEControl（对于 Word）对象。

下面的代码示例演示如何使用 AddControl(Control, Range, String) 方法动态地向面向 .NET Framework 4 的文档级 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;

请参见

通过