在运行时向办公室文档添加控件

  • 项目

可以在运行时向 Microsoft Office Word 文档和 Microsoft Office Excel 工作簿中添加控件。 还可以在运行时删除这些控件。 在运行时添加或删除的控件称为 动态控件。

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

本主题将介绍以下内容：

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

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

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

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

  • 在 Word 文档级项目中，使用 Controls 类的 ThisDocument 属性。 有关此类的详细信息，请参阅 文档主机项。

  • 在 Excel 或 Word 的 VSTO 外接程序项目中，使用Controls运行时生成的或Document属性Worksheet。 有关在运行时生成这些对象的详细信息，请参阅 在运行时在 VSTO 外接程序中扩展 Word 文档和 Excel 工作簿。

添加控件

ControlCollection 和 ControlCollection 类型包含可用于将宿主控件和公共 Windows 窗体控件添加到文档和工作表中的帮助器方法。 Each method name has the format Addcontrol class, where control class is the class name of the control that you want to 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 文档级项目中从 NamedRange 中删除 Sheet1 。

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

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

注意

请不要以编程方式在文档的 Shutdown 事件处理程序中删除控件。 发生 Shutdown 事件时，文档的 UI 元素将不再可用。 如果要在关闭文档之前删除控件，请将你的代码添加到另一个事件的事件处理程序中，对于 Word 为 BeforeClose 或 BeforeSave ，对于 Excel 为 BeforeClose或 BeforeSave 。

向文档添加主机控件

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

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

保存并关闭文档后，动态创建的宿主控件会断开与其事件的连接，并丧失其数据绑定功能。 可以向解决方案中添加代码，以在重新打开文档时重新创建这些宿主控件。 有关详细信息，请参阅在办公室文档中保留动态控件。

注意

以下宿主控件不具备帮助器方法，因为不能以编程方式将这些控件添加到 XmlMappedRange、 XMLNode和 XMLNodes文档中。

向文档添加Windows 窗体控件

当以编程方式向文档中添加 Windows 窗体控件时，必须提供控件的位置和一个可唯一标识该控件的名称。 用于办公室运行时的 Visual Studio 工具为每个控件提供帮助程序方法。 这些方法将重载，以便可以传递控件位置的范围或具体坐标。

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

注意

不能以编程方式向受保护的文档添加 Windows 窗体控件。 如果通过以编程方式取消 Word 文档或 Excel 工作表保护来添加控件，则必须编写额外的代码在关闭文档时删除该控件的 ActiveX 包装。 该控件的 ActiveX 包装不会从受保护的文档中自动删除。

添加自定义控件

如果想要添加可用帮助器方法不支持的 Control （如自定义用户控件），请使用以下方法：

  • 对于 Excel，使用 AddControl 对象的 ControlCollection 方法。

  • 对于 Word，使用 AddControl 对象的 ControlCollection 方法。

    若要添加控件，请将 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、OLEObject 或 OLEControl 对象。

    如果访问 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;

相关内容