ASP.NET 用户控件概述

项目
10/22/2014

更新：2007 年 11 月

有时可能需要控件中具有内置 ASP.NET Web 服务器控件未提供的功能。在这种情况下，您可以创建自己的控件。有两个选择。您可以创建：

用户控件。用户控件是能够在其中放置标记和 Web 服务器控件的容器。然后，可以将用户控件作为一个单元对待，为其定义属性和方法。
自定义控件。自定义控件是编写的一个类，此类从 Control 或 WebControl 派生。

创建用户控件要比创建自定义控件方便很多，因为可以重用现有的控件。用户控件使创建具有复杂用户界面元素的控件极为方便。

本主题提供了使用 ASP.NET 用户控件的概述。

用户控件结构

ASP.NET Web 用户控件与完整的 ASP.NET 网页（.aspx 文件）相似，同时具有用户界面页和代码。可以采取与创建 ASP.NET 页相似的方式创建用户控件，然后向其中添加所需的标记和子控件。用户控件可以像页面一样包含对其内容进行操作（包括执行数据绑定等任务）的代码。

用户控件与 ASP.NET 网页有以下区别：

用户控件的文件扩展名为 .ascx。
用户控件中没有 @ Page 指令，而是包含 @ Control 指令，该指令对配置及其他属性进行定义。
用户控件不能作为独立文件运行。而必须像处理任何控件一样，将它们添加到 ASP.NET 页中。
用户控件中没有 html、body 或 form 元素。这些元素必须位于宿主页中。

可以在用户控件上使用与在 ASP.NET 网页上所用相同的 HTML 元素（html、body 或 form 元素除外）和 Web 控件。例如，如果您要创建一个将用作工具栏的用户控件，则可以将一系列 Button Web 服务器控件放在该控件上，并创建这些按钮的事件处理程序。

下面的示例演示一个实现微调控件的用户控件，在此微调控件中，用户可单击向上和向下按钮以滚动文本框中的一系列选择。

安全说明：
该示例具有一个文本框，用于接受用户输入，这是一个潜在的安全威胁。默认情况下，ASP.NET 网页验证用户输入是否不包括脚本或 HTML 元素。有关更多信息，请参见脚本侵入概述。

<%@ Control Language="VB" ClassName="UserControl1" %>
<script runat="server">
    Protected colors As String() = {"Red", "Green", "Blue", "Yellow"}
    Protected currentColorIndex As Integer = 0
    Protected Sub Page_Load(ByVal sender As Object, _
            ByVal e As System.EventArgs)
        If IsPostBack Then
            currentColorIndex = CInt(ViewState("currentColorIndex"))
        Else
            currentColorIndex = 0
            DisplayColor()
        End If
    End Sub
    
    Protected Sub DisplayColor()
        textColor.Text = colors(currentColorIndex)
        ViewState("currentColorIndex") = currentColorIndex.ToString()
    End Sub

    Protected Sub buttonUp_Click(ByVal sender As Object, _
            ByVal e As System.EventArgs)
        If currentColorIndex = 0 Then
            currentColorIndex = colors.Length - 1
        Else
            currentColorIndex -= 1
        End If
        DisplayColor()
    End Sub
    
    Protected Sub buttonDown_Click(ByVal sender As Object, _
            ByVal e As System.EventArgs)
        If currentColorIndex = colors.Length - 1 Then
            currentColorIndex = 0
        Else
            currentColorIndex += 1
        End If
        DisplayColor()
    End Sub
</script>
<asp:TextBox ID="textColor" runat="server" 
    ReadOnly="True" />
<asp:Button Font-Bold="True" ID="buttonUp" runat="server"  
    Text="^" OnClick="buttonUp_Click" />
<asp:Button Font-Bold="True" ID="buttonDown" runat="server" 
    Text="v" OnClick="buttonDown_Click" />

<% @ Control Language="C#" ClassName="UserControl1" %>
<script runat="server">
    protected int currentColorIndex;
    protected String[] colors = {"Red", "Blue", "Green", "Yellow"};
    protected void Page_Load(object sender, EventArgs e)
    {
        if (IsPostBack)
        {
            currentColorIndex = 
                Int16.Parse(ViewState["currentColorIndex"].ToString());
        }
        else
        {
            currentColorIndex = 0;
            DisplayColor();
        }
    }
    
    protected void DisplayColor()
    {
        textColor.Text = colors[currentColorIndex];
        ViewState["currentColorIndex"] = currentColorIndex.ToString();
    }
    
    protected void buttonUp_Click(object sender, EventArgs e)
    {
        if(currentColorIndex == 0)
        {
            currentColorIndex = colors.Length - 1;
        }
        else
        {
            currentColorIndex -= 1;
        }
        DisplayColor();
    }

    protected void buttonDown_Click(object sender, EventArgs e)
    {
        if(currentColorIndex == (colors.Length - 1))
        {
            currentColorIndex = 0;
        }    
        else
        {
            currentColorIndex += 1;
        }
        DisplayColor();
    }
</script>
<asp:TextBox ID="textColor" runat="server" 
    ReadOnly="True" />
<asp:Button Font-Bold="True" ID="buttonUp" runat="server" 
    Text="^" OnClick="buttonUp_Click" />
<asp:Button Font-Bold="True" ID="buttonDown" runat="server" 
    Text="v" OnClick="buttonDown_Click" />

注意，用户控件与 ASP.NET 页十分相像，它包含若干控件（一个 TextBox 控件和两个 Button 控件）以及处理按钮的 Click 事件和页面的 Load 事件的代码。但是，用户控件除了控件以外不包含标记，没有 @ Page 指令，但包含一个 @ Control 指令。

向页面添加用户控件

通过在宿主页上进行注册，可以将用户控件添加到页面中。注册用户控件时，要指定包含用户控件的 .ascx 文件、标记前缀以及将用于在页面上声明用户控件的标记名称。有关详细信息，请参见如何：在 ASP.NET 网页中包括用户控件。

定义用户控件的属性和方法

可以采用定义页面的属性和方法时所用的方式定义用户控件的属性和方法。通过定义用户控件的属性，就能以声明方式及利用代码设置其属性。

用户控件中的事件

用户控件包含 Web 服务器控件时，可以在用户控件中编写代码来处理其子控件引发的事件。例如，如果用户控件包含一个 Button 控件，则可以在用户控件中为该按钮的 Click 事件创建处理程序。

默认情况下，用户控件中的子控件引发的事件对于宿主页不可用。但是，可以为用户控件定义事件并引发这些事件，以便将子控件引发的事件通知宿主页。进行此操作的方式与定义任何类的事件一样。有关更多信息，请参见引发事件。

引用外部资源

用户控件运行时，会将该用户控件的 URL 作为基 URL，以解析对外部资源（如图像或其他页面的定位点）的引用。例如，如果用户控件包含一个 Image 控件，而此控件的 ImageUrl 属性设置为 Images/Button1.gif，则会将图像的 URL 添加到用户控件的 URL 以解析该图像的完整路径。如果用户控件引用的资源不在用户控件本身的子文件夹中，则必须提供在运行时解析为正确文件夹的路径。有关指定 ASP.NET 服务器控件的路径的更多信息，请参见 ASP.NET 网站路径。

缓存与用户控件

用户控件支持独立于宿主页的缓存指令。因此，可以向页面添加用户控件，并对页面的某些部分进行缓存。有关详细信息，请参见缓存 ASP.NET 页的某些部分。

请参见

其他资源

ASP.NET 用户控件