UserControl 类
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
表示一个 .ascx 文件（也称为用户控件），该文件是从托管 ASP.NET Web 应用程序的服务器请求。 文件必须从 Web 窗体页进行调用，否则将出现分析程序错误。
public ref class UserControl : System::Web::UI::TemplateControl, System::Web::UI::IAttributeAccessor, System::Web::UI::IUserControlDesignerAccessorpublic class UserControl : System.Web.UI.TemplateControl, System.Web.UI.IAttributeAccessor, System.Web.UI.IUserControlDesignerAccessortype UserControl = class
inherit TemplateControl
interface IAttributeAccessor
interface IUserControlDesignerAccessortype UserControl = class
inherit TemplateControl
interface IAttributeAccessor
interface INamingContainer
interface IUserControlDesignerAccessorPublic Class UserControl
Inherits TemplateControl
Implements IAttributeAccessor, IUserControlDesignerAccessor- 继承
- 派生
- 实现
示例
以下示例 SimpleControl中定义的类 继承 UserControl 类，并可用作 ASP.NET 代码隐藏类。 它使用 、 和 Web 服务器控件，并定义一个myButton_Click方法，该方法将TextBox.Text属性值以及两个字符串分配给 属性Label.Text。ButtonLabelTextBox
重要
此示例具有一个接受用户输入的文本框，这是一个潜在的安全威胁。 默认情况下，ASP.NET 网页验证用户输入是否不包含脚本或 HTML 元素。 有关详细信息，请参阅脚本侵入概述。
using System;
using System.Web.UI;
using System.Web.UI.WebControls;
public class SimpleControl:UserControl
{
public TextBox name;
public Label output;
public Button myButton;
public void myButton_Click(object sender, EventArgs e)
{
output.Text = "Hello, " + name.Text + ".";
}
}
Imports System.Web.UI
Imports System.Web.UI.WebControls
Public Class SimpleControl
Inherits UserControl
Public name As TextBox
Public output As Label
Public myButton As Button
Public Sub myButton_Click(sender As Object, e As EventArgs)
output.Text = "Hello, " + name.Text + "."
End Sub
End Class
以下示例是 .ascx 文件中包含的标记。 可以使用上一 SimpleControl 示例中定义的 类作为此 .ascx 文件中标记的代码隐藏类。
<%@ control inherits = "SimpleControl" src = "SimpleControl.cs" %>
<table style="background-color:yellow;font: 10pt verdana;border-width:1;border-style:solid;border-color:black;" cellspacing="15">
<tr>
<td><b>Enter your name here: </b></td>
<td><ASP:TextBox id="name" runat="server"/></td>
</tr>
<tr>
<td><b><ASP:Label id="output" runat="server"/></b></td>
</tr>
<tr>
<td></td>
<td><asp:button id="myButton" text="Submit" OnClick="myButton_Click" runat="server" /></td>
</tr>
</table>
<%@ control inherits = "SimpleControl" src = "SimpleControl.vb" %>
<table style="background-color: yellow; font: 10pt verdana;border-width:1;border-style:solid;border-color:black;" cellspacing="15">
<tr>
<td><b>Enter your name here: </b></td>
<td><ASP:TextBox id="name" runat="server"/></td>
</tr>
<tr>
<td><b><ASP:Label id="output" runat="server"/></b></td>
</tr>
<tr>
<td></td>
<td><asp:button text="Submit" OnClick="myButton_Click" runat="server" /></td>
</tr>
</table>
注解
类 UserControl 与扩展名为 .ascx 的文件相关联。 这些文件在运行时编译为 UserControl 对象，并缓存在服务器内存中。
可以通过在另一个 .ascx 文件中声明一个 .ascx 文件（包括Web Forms页中的后者）来嵌套用户控件。
用户控件包含在 ASP.NET Web Forms页中，为 Web 开发人员提供了一种捕获常用 Web UI 的简单方法。 它们的实例化和缓存方式类似于 Page 对象。 但是，与页面不同，用户控件不能单独调用。 只能从包含它们的页面或其他用户控件调用它们。
如果要使用代码隐藏技术创建用户控件，请从此类派生。 如果要使用此技术开发Web Forms页面，建议使用此方法。
有关以声明方式创建用户控件的信息，请参阅 ASP.NET 用户控件。
构造函数
| UserControl() |
初始化 UserControl 类的新实例。 |
属性
| Adapter |
获取控件的浏览器特定适配器。 (继承自 Control) |
| Application |
为当前 Web 请求获取 Application 对象。 |
| AppRelativeTemplateSourceDirectory |
获取或设置包含该控件的 Page 或 UserControl 对象的应用程序相对虚拟目录。 (继承自 Control) |
| AppRelativeVirtualPath |
获取或设置从中解析和编译控件的文件的相对于应用程序的虚拟目录路径。 (继承自 TemplateControl) |
| Attributes |
获取在 .aspx 文件中的用户控件标记中声明的所有特性名和值对的集合。 |
| AutoHandlers |
已过时.
ASP.NET 2.0 中已弃用 AutoHandlers 属性。 它是由生成的类使用的，不应在代码中使用。 (继承自 TemplateControl) |
| BindingContainer |
获取包含该控件的数据绑定的控件。 (继承自 Control) |
| Cache |
获取与包含用户控件的应用程序关联的 Cache 对象。 |
| CachePolicy |
获取对该用户控件的缓存参数集合的引用。 |
| ChildControlsCreated |
获取一个值，该值指示是否已创建服务器控件的子控件。 (继承自 Control) |
| ClientID |
获取由 ASP.NET 生成的 HTML 标记的控件 ID。 (继承自 Control) |
| ClientIDMode |
获取或设置用于生成 ClientID 属性值的算法。 (继承自 Control) |
| ClientIDSeparator |
获取一个字符值，该值表示 ClientID 属性中使用的分隔符字符。 (继承自 Control) |
| Context |
为当前 Web 请求获取与服务器控件关联的 HttpContext 对象。 (继承自 Control) |
| Controls |
获取 ControlCollection 对象，该对象表示 UI 层次结构中的指定服务器控件的子控件。 (继承自 Control) |
| DataItemContainer |
如果命名容器实现 IDataItemContainer，则获取对命名容器的引用。 (继承自 Control) |
| DataKeysContainer |
如果命名容器实现 IDataKeysControl，则获取对命名容器的引用。 (继承自 Control) |
| DesignMode |
获取一个值，该值指示是否正在使用设计图面上的一个控件。 (继承自 Control) |
| EnableTheming |
获取或设置一个布尔值，该值指示主题是否应用于派生自 TemplateControl 类的控件。 (继承自 TemplateControl) |
| EnableViewState |
获取或设置一个值，该值指示服务器控件是否向发出请求的客户端保持自己的视图状态以及它所包含的任何子控件的视图状态。 (继承自 Control) |
| Events |
获取控件的事件处理程序委托列表。 此属性为只读。 (继承自 Control) |
| HasChildViewState |
获取一个值，该值指示当前服务器控件的子控件是否具有任何已保存的视图状态设置。 (继承自 Control) |
| ID |
获取或设置分配给服务器控件的编程标识符。 (继承自 Control) |
| IdSeparator |
获取用于分隔控件标识符的字符。 (继承自 Control) |
| IsChildControlStateCleared |
获取一个值，该值指示该控件中包含的控件是否具有控件状态。 (继承自 Control) |
| IsPostBack |
获取一个值，该值指示是正为响应客户端回发而加载用户控件，还是正第一次加载和访问用户控件。 |
| IsTrackingViewState |
获取一个值，用于指示服务器控件是否会将更改保存到其视图状态中。 (继承自 Control) |
| IsViewStateEnabled |
获取一个值，该值指示是否为该控件启用了视图状态。 (继承自 Control) |
| LoadViewStateByID |
获取一个值，该值指示控件是否通过 ID 而不是索引参与加载其视图状态。 (继承自 Control) |
| NamingContainer |
获取对服务器控件的命名容器的引用，此引用创建唯一的命名空间，以区分具有相同 ID 属性值的服务器控件。 (继承自 Control) |
| Page |
获取对包含服务器控件的 Page 实例的引用。 (继承自 Control) |
| Parent |
获取对页 UI 层次结构中服务器控件的父控件的引用。 (继承自 Control) |
| RenderingCompatibility |
获取一个值，该值指定呈现的 HTML 将与之兼容的 ASP.NET 版本。 (继承自 Control) |
| Request |
为当前 Web 请求获取 HttpRequest 对象。 |
| Response |
为当前 Web 请求获取 HttpResponse 对象。 |
| Server |
为当前 Web 请求获取 HttpServerUtility 对象。 |
| Session |
为当前 Web 请求获取 HttpSessionState 对象。 |
| Site |
获取容器信息，该容器在呈现于设计图面上时承载当前控件。 (继承自 Control) |
| SkinID |
获取或设置要应用于控件的外观。 (继承自 Control) |
| SupportAutoEvents |
获取一个值，该值指示 TemplateControl 控件是否支持自动事件。 (继承自 TemplateControl) |
| TemplateControl |
获取或设置对包含该控件的模板的引用。 (继承自 Control) |
| TemplateSourceDirectory |
获取包含当前服务器控件的 Page 或 UserControl 的虚拟目录。 (继承自 Control) |
| Trace |
为当前 Web 请求获取 TraceContext 对象。 |
| UniqueID |
获取服务器控件的唯一的、以分层形式限定的标识符。 (继承自 Control) |
| ValidateRequestMode |
获取或设置指示控件是否检查来自浏览器的客户端输入是否具有潜在危险值的值。 (继承自 Control) |
| ViewState |
获取状态信息的字典，这些信息使您可以在同一页的多个请求间保存和还原服务器控件的视图状态。 (继承自 Control) |
| ViewStateIgnoresCase |
获取一个值，该值指示 StateBag 对象是否不区分大小写。 (继承自 Control) |
| ViewStateMode |
获取或设置此控件的视图状态模式。 (继承自 Control) |
| Visible |
获取或设置一个值，该值指示服务器控件是否作为 UI 呈现在页上。 (继承自 Control) |
方法
事件
| AbortTransaction |
当用户结束交易时发生。 (继承自 TemplateControl) |
| CommitTransaction |
当事务完成时发生。 (继承自 TemplateControl) |
| DataBinding |
当服务器控件绑定到数据源时发生。 (继承自 Control) |
| Disposed |
当从内存释放服务器控件时发生，这是请求 ASP.NET 页时服务器控件生存期的最后阶段。 (继承自 Control) |
| Error |
当引发未经处理的异常时发生。 (继承自 TemplateControl) |
| Init |
当服务器控件初始化时发生；初始化是控件生存期的第一步。 (继承自 Control) |
| Load |
当服务器控件加载到 Page 对象中时发生。 (继承自 Control) |
| PreRender |
在加载 Control 对象之后、呈现之前发生。 (继承自 Control) |
| Unload |
当服务器控件从内存中卸载时发生。 (继承自 Control) |
显式接口实现
扩展方法
| FindDataSourceControl(Control) |
返回与指定控件的数据控件关联的数据源。 |
| FindFieldTemplate(Control, String) |
返回指定控件的命名容器中指定列的字段模板。 |
| FindMetaTable(Control) |
返回包含数据控件的元表对象。 |
| GetDefaultValues(INamingContainer) |
为指定数据控件获取默认值的集合。 |
| GetMetaTable(INamingContainer) |
为指定数据控件获取表元数据。 |
| SetMetaTable(INamingContainer, MetaTable) |
为指定数据控件设置表元数据。 |
| SetMetaTable(INamingContainer, MetaTable, IDictionary<String,Object>) |
为指定数据控件设置表元数据和默认值映射。 |
| SetMetaTable(INamingContainer, MetaTable, Object) |
为指定数据控件设置表元数据和默认值映射。 |
| TryGetMetaTable(INamingContainer, MetaTable) |
确定表元数据是否可用。 |
| EnableDynamicData(INamingContainer, Type) |
为指定数据控件启用动态数据行为。 |
| EnableDynamicData(INamingContainer, Type, IDictionary<String,Object>) |
为指定数据控件启用动态数据行为。 |
| EnableDynamicData(INamingContainer, Type, Object) |
为指定数据控件启用动态数据行为。 |
适用于
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈