通过

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

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

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

本主题介绍以下内容：

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

若要在运行时添加、获取或删除控件，请使用帮助程序方法和ControlCollectionControlCollection对象。

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

添加控件

ControlCollection和ControlCollection类型包含可用于向文档和工作表添加宿主控件和常见 Windows 窗体控件的辅助方法。 每个方法名称都有格式 Add控件类，其中 控件类 是要添加的控件的类名。 例如，若要向 NamedRange 文档添加控件，请使用 AddNamedRange 该方法。

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

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

访问和删除控件

可以使用Worksheet或Document的Controls属性来遍历文档中的所有控件，包括在设计时添加的控件。 在设计时添加的 控件也称为静态控件。

可以通过调用 Delete 控件的方法或调用 Remove 每个 Controls 集合的方法来删除动态控件。 下面的代码示例使用Remove方法，从 Excel 的文档级项目中删除NamedRangeSheet1。

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

不能在运行时删除静态控件。 如果尝试使用 Delete 或 Remove 方法删除静态控件，将引发一个 CannotRemoveControlException 。

注释

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

向文档添加主机控件

以编程方式向文档添加主机控件时，必须提供唯一标识控件的名称，并且必须指定在文档中添加控件的位置。 请查看以下主题以获取特定的操作指南：

有关主机控件的详细信息，请参阅 主机项和主机控件概述。

保存并关闭文档后，所有动态创建的主机控件都会与其事件断开连接，并且会丢失其数据绑定功能。 可以将代码添加到解决方案，以在重新打开文档时重新创建主机控件。 有关详细信息，请参阅 在 Office 文档中持久保存动态控件。

注释

以下主机控件不提供帮助程序方法，因为这些控件不能以编程方式添加到文档：XmlMappedRange和XMLNodeXMLNodes。

向文档添加 Windows 窗体控件

以编程方式向文档添加 Windows 窗体控件时，必须提供控件的位置以及唯一标识控件的名称。 Visual Studio Tools for Office 运行时为每个控件提供辅助方法。 这些方法被重载，以便你可以传递控件位置的范围或具体坐标。

保存并关闭文档后，将从文档中删除所有动态创建的 Windows 窗体控件。 可以将代码添加到解决方案，以在重新打开文档时重新创建控件。 如果使用 VSTO 外接程序创建动态 Windows 窗体控件，则控件的 ActiveX 包装器将保留在文档中。 有关详细信息，请参阅 在 Office 文档中持久保存动态控件。

注释

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

添加自定义控件

如果您想添加可用帮助程序方法不支持的元素，例如自定义用户控件 Control，请使用以下方法：

  • 对于 Excel，请使用 AddControlControlCollection 对象的一个方法。

  • 对于 Word，请使用某个ControlCollection对象的AddControl方法之一。

    若要添加控件，请将 Control、控件的位置以及唯一标识控件的名称传递给 AddControl 方法。 该方法 AddControl 返回一个对象，该对象定义控件与工作表或文档的交互方式。 该方法 AddControl 返回一个 ControlSite （for Excel）或一个 ControlSite 对象（对于 Word）。

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

    UserControl1 customControl = new UserControl1();

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

使用自定义控件的成员

使用其中 AddControl 一种方法将控件添加到工作表或文档后，现在有两个不同的控件对象：

  • 用于表示自定义控件的 Control。

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

    这些控件之间共享许多属性和方法。 请务必通过适当的控件访问这些成员：

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

  • 若要访问由控件共享的成员，请使用ControlSite或OLEObjectOLEControl对象。

    如果从Control进行共享成员访问，可能会无提示或通知地失败，或产生无效结果。 始终使用ControlSite、OLEObject或OLEControl对象的方法或属性，除非所需的方法或属性不可用；仅在这种情况下，才应参考Control。

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

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

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

相关内容