asp.net自定义控件教程-建站教程-锦华智联科技

ASP.NET 自定义控件终极教程

第一部分：为什么需要自定义控件？
（图片来源网络，侵删）
- 什么是自定义控件？
- 使用自定义控件的优势
第二部分：自定义控件的类型
- 复合控件
- 派生控件
- 模板化控件
第三部分：创建你的第一个自定义控件（复合控件）
- 实例1：创建一个带验证的邮箱输入框
  - 步骤1：创建类库项目
  - 步骤2：继承 CompositeControl
  - 步骤3：创建子控件
  - 步骤4：创建子控件模板
  - 步骤5：处理回发和事件
  - 步骤6：添加属性
  - 步骤7：使用控件
  - 步骤8：添加设计时支持
第四部分：创建一个功能更强大的自定义控件（派生控件）
- 实例2：创建一个带样式的 Bootstrap 风格按钮
  - 步骤1：继承 WebControl
  - 步骤2：重写 RenderContents 方法
  - 步骤3：添加自定义属性
  - 步骤4：使用控件
第五部分：高级主题与最佳实践
（图片来源网络，侵删）
- 状态管理
- 事件处理
- 设计时支持
- 资源文件
- 发布与部署

第一部分：为什么需要自定义控件？

什么是自定义控件？

ASP.NET 自定义控件是开发者创建的、可重用的服务器端控件，它封装了 HTML、CSS、JavaScript 和 C# (或 VB.NET) 代码，让你可以在多个页面甚至多个项目中像使用 TextBox 或 Button 一样轻松地使用它。

使用自定义控件的优势

代码重用：将复杂的 UI 逻辑封装成一个控件,避免在多个页面中重复编写相同的代码。
逻辑封装：将业务逻辑和表现层分离，一个复杂的搜索控件，其内部的数据获取和过滤逻辑对页面是不可见的，页面只需调用控件的 Search() 方法即可。
易于维护：如果需要修改 UI 或逻辑，只需修改自定义控件的代码,所有使用该控件的页面都会自动更新。
一致性：确保整个应用程序中相同功能的控件具有一致的外观和行为。
扩展性：你可以继承并扩展现有的 ASP.NET 控件,为其添加新功能或修改默认行为。

第二部分：自定义控件的类型

ASP.NET 主要提供三种类型的自定义控件：

复合控件
- 特点：通过组合一个或多个现有的 ASP.NET 服务器控件（如 TextBox, Label, RequiredFieldValidator）来创建一个新的控件。
- 适用场景：当你需要将几个标准控件组合成一个具有特定功能的逻辑单元时，一个“用户名输入框 + 标签 + 必填验证器”的组合。
- 基类：通常继承自 System.Web.UI.WebControls.CompositeControl。
派生控件
（图片来源网络，侵删）
- 特点：从现有的 ASP.NET 控件（如 WebControl, Label, Button）直接继承，并重写其核心方法（如 Render）来改变其呈现的 HTML。
- 适用场景：当你需要修改一个现有控件的默认行为或外观，但又不想完全从头开始创建时，创建一个总是带有特定 CSS 类的 Button。
- 基类：继承自 System.Web.UI.WebControls.WebControl 或更具体的控件如 System.Web.UI.WebControls.Button。
模板化控件
- 特点：最复杂、最灵活的类型，它允许开发者使用自定义模板来定义控件的布局，数据列表控件如 FormView 和 Repeater 就是模板化控件的经典例子。
- 适用场景：当你需要创建一个可以显示重复数据,并且希望最终用户可以自由定义其显示方式的控件时。
- 基类：继承自 System.Web.UI.WebControls.DataBoundControl 或 System.Web.UI.WebControls.CompositeDataBoundControl。

本教程将重点讲解前两种类型,因为它们是最常用且最容易上手的。

第三部分：创建你的第一个自定义控件（复合控件）

我们将创建一个名为 EmailInput 的复合控件，它包含一个 Label、一个 TextBox 和一个 RequiredFieldValidator。

步骤1：创建类库项目

打开 Visual Studio。
选择 "创建新项目"。
搜索并选择 "类库" 模板（确保选择的是 C# 或 VB.NET 的 Web 相关类库）。
将项目命名为 MyCustomControls。
点击 "创建"。

步骤2：继承 CompositeControl

在项目中，删除默认的 Class1.cs 文件，添加一个新类，命名为 EmailInput.cs。

using System.Web.UI;
using System.Web.UI.WebControls;
namespace MyCustomControls
{
    // 1. 继承 CompositeControl
    [ToolboxData("<{0}:EmailInput runat=server></{0}:EmailInput>")]
    public class EmailInput : CompositeControl
    {
        // 控件的核心逻辑将在这里实现
    }
}

[ToolboxData] 特性指定了当您将此控件拖放到设计器时,默认生成的标记。

步骤3：创建子控件

我们需要声明我们将要使用的子控件。

private Label _label;
private TextBox _textBox;
private RequiredFieldValidator _validator;
protected override void CreateChildControls()
{
    // 确保只在必要时创建子控件
    if (Controls.Count == 0)
    {
        // 创建 Label
        _label = new Label();
        _label.AssociatedControlID = "txtEmail"; // 关联到 TextBox，提高可访问性
        _label.Text = "电子邮箱：";
        this.Controls.Add(_label);
        // 创建 TextBox
        _textBox = new TextBox();
        _textBox.ID = "txtEmail";
        this.Controls.Add(_textBox);
        // 创建验证器
        _validator = new RequiredFieldValidator();
        _validator.ControlToValidate = _textBox.ID;
        _validator.ErrorMessage = "请输入电子邮箱！";
        _validator.Text = "*"; // 显示一个星号
        this.Controls.Add(_validator);
    }
    base.CreateChildControls();
}

CreateChildControls 是复合控件的核心方法,它负责创建和初始化所有子控件。

步骤4：创建子控件模板

为了让子控件能正确呈现，我们需要重写 EnsureChildControls 方法，并在 RenderContents 方法中渲染它们。

protected override void EnsureChildControls()
{
    base.EnsureChildControls();
}
protected override void RenderContents(HtmlTextWriter writer)
{
    // 渲染 Label
    _label.RenderControl(writer);
    writer.Write(" "); // 添加一个空格
    // 渲染 TextBox
    _textBox.RenderControl(writer);
    writer.Write(" "); // 添加一个空格
    // 渲染 Validator
    _validator.RenderControl(writer);
}

步骤5：处理回发和事件

复合控件会自动处理其子控件的回发数据，你不需要做太多事情，只要确保 CreateChildControls 在每次回发时都被正确调用即可（ASP.NET 生命周期会自动处理）。

步骤6：添加属性

让我们为 EmailInput 控件添加一些有用的属性，如 LabelText 和 Text。

[Bindable(true)]
[Category("Appearance")]
[DefaultValue("")]
[Localizable(true)]
public string LabelText
{
    get
    {
        EnsureChildControls();
        return _label.Text;
    }
    set
    {
        EnsureChildControls();
        _label.Text = value;
    }
}
[Bindable(true)]
[Category("Behavior")]
[DefaultValue("")]
public string Text
{
    get
    {
        EnsureChildControls();
        return _textBox.Text;
    }
    set
    {
        EnsureChildControls();
        _textBox.Text = value;
    }
}

[Bindable]：允许属性在数据绑定时使用。
[Category]：在属性窗口中将属性分组。
[DefaultValue]：设置属性的默认值。
[Localizable]：标记属性是否需要本地化。
重要：在属性的 get 和 set 访问器中调用 EnsureChildControls(),以确保在访问属性时子控件已经被创建。

步骤7：使用控件

编译项目：右键点击 MyCustomControls 项目，选择 "生成"。
创建一个 ASP.NET Web 应用程序：在同一个解决方案中新建一个 ASP.NET Web 应用程序项目（WebAppDemo）。
添加引用：在 WebAppDemo 项目中，右键 "引用" -> "添加引用"，选择 "项目"，然后勾选 MyCustomControls。

注册控件：在 WebAppDemo 的 Web.config 文件中，添加 pages 节点下的 controls 节点：

<configuration>
  <system.web>
    <pages>
      <controls>
        <!-- 
          add namespace="你的控件命名空间"
          tagPrefix="你想要的标签前缀，如 cc"
          assembly="你的控件项目名称"
        -->
        <add namespace="MyCustomControls" tagPrefix="cc" assembly="MyCustomControls" />
      </controls>
    </pages>
  </system.web>
</configuration>

在页面中使用：打开一个 ASPX 页面（如 Default.aspx）,在源视图中直接使用你的控件：

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" Inherits="WebAppDemo.Default" %>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>EmailInput 控件演示</title>
</head>
<body>
    <form id="form1" runat="server">
        <div>
            <cc:EmailInput ID="emailInput1" runat="server" LabelText="请输入您的邮箱：" />
            <br />
            <asp:Button ID="btnSubmit" runat="server" Text="提交" OnClick="btnSubmit_Click" />
            <br />
            <asp:Label ID="lblResult" runat="server" Text=""></asp:Label>
        </div>
    </form>
</body>
</html>

在代码后端获取值：

protected void btnSubmit_Click(object sender, EventArgs e)
{
    // 直接通过 Text 属性获取控件的值
    string email = emailInput1.Text;
    lblResult.Text = "您输入的邮箱是：" + email;
}

现在运行项目,你就能看到一个功能完整的邮箱输入控件了！

步骤8：添加设计时支持（可选但推荐）

为了让控件在设计器中更好看、更易用，可以创建一个 Designer 类。

在 MyCustomControls 项目中添加一个新类，命名为 EmailInputDesigner。

让它继承自 CompositeControlDesigner。

using System.Web.UI.Design;
using System.Web.UI.WebControls;
namespace MyCustomControls
{
    public class EmailInputDesigner : CompositeControlDesigner
    {
        // 可以在这里重写方法来改变设计时的行为
        // 可以返回一个预览的 HTML
        public override string GetDesignTimeHtml()
        {
            EmailInput ctrl = (EmailInput)Component;
            // 在设计时显示一个友好的提示
            return $"<div style='border:1px solid #ccc; padding:5px; background-color:#f9f9f9;'>[设计时预览: {ctrl.LabelText ?? "邮箱输入"}]</div>";
        }
    }
}

在 EmailInput.cs 控件类上添加 Designer 特性：
```
[ToolboxData("<{0}:EmailInput runat=server></{0}:EmailInput>")]
[Designer(typeof(MyCustomControls.EmailInputDesigner))]
public class EmailInput : CompositeControl
{
    // ...
}
```
重新编译后，在设计视图中，你的控件将显示为 [设计时预览: 请输入您的邮箱：],而不是一个空白框。

第四部分：创建一个功能更强大的自定义控件（派生控件）

我们创建一个继承自 WebControl 的按钮，它默认应用 Bootstrap 样式。

步骤1：继承 WebControl

在 MyCustomControls 项目中添加一个新类 BootstrapButton.cs。

using System.Web.UI;
using System.Web.UI.WebControls;
namespace MyCustomControls
{
    [ToolboxData("<{0}:BootstrapButton runat=server Text='Button'></{0}:BootstrapButton>")]
    public class BootstrapButton : WebControl
    {
        // ...
    }
}

步骤2：重写 RenderContents 方法

派生控件的核心在于重写 Render 或 RenderContents 方法来生成 HTML。

Render：渲染整个控件，包括开始标签（如 <div>）和结束标签（如 </div>）。
RenderContents：只渲染控件内部的内容，假设它已经被一个容器（如 span）包裹，对于 Button，我们通常使用 RenderContents。

protected override void RenderContents(HtmlTextWriter writer)
{
    // 1. 获取控件的 Text 属性
    string text = this.Text;
    // 2. 构造 HTML
    // 使用 writer.Write 写入 HTML
    writer.Write(" <button type='submit' class='btn ");
    // 3. 根据 ButtonType 添加不同的 Bootstrap 样式
    switch (this.ButtonType)
    {
        case ButtonType.Primary:
            writer.Write("btn-primary");
            break;
        case ButtonType.Success:
            writer.Write("btn-success");
            break;
        case ButtonType.Danger:
            writer.Write("btn-danger");
            break;
        default:
            writer.Write("btn-default"); // 默认样式
            break;
    }
    writer.Write("'>");
    writer.WriteEncodedText(text); // 使用 WriteEncodedText 来防止 XSS 攻击
    writer.Write("</button> ");
}

步骤3：添加自定义属性

我们需要添加 Text 和 ButtonType 属性。

// Text 属性
[Bindable(true)]
[Category("Appearance")]
[DefaultValue("")]
public virtual string Text
{
    get
    {
        string s = (string)ViewState["Text"];
        return ((s == null) ? string.Empty : s);
    }
    set
    {
        ViewState["Text"] = value;
    }
}
// ButtonType 枚举属性
public enum ButtonType
{
    Primary,
    Success,
    Danger,
    Default
}
[Bindable(true)]
[Category("Appearance")]
[DefaultValue(ButtonType.Default)]
public virtual ButtonType ButtonType
{
    get
    {
        object obj = ViewState["ButtonType"];
        return (obj == null) ? ButtonType.Default : (ButtonType)obj;
    }
    set
    {
        ViewState["ButtonType"] = value;
    }
}

对于简单属性，我们使用 ViewState 来存储其值,这对于派生控件是标准做法。
ButtonType 是一个自定义枚举,提供了类型安全。

步骤4：使用控件

编译项目。
确保你的 Web 应用程序项目已经引用了 MyCustomControls 并在 Web.config 中注册了它（tagPrefix 可以继续用 cc）。

在 ASPX 页面中使用：

<%@ Register assembly="MyCustomControls" namespace="MyCustomControls" tagprefix="cc" %>
<form id="form1" runat="server">
    <div>
        <cc:BootstrapButton ID="btnPrimary" runat="server" Text="主要按钮" ButtonType="Primary" />
        <cc:BootstrapButton ID="btnSuccess" runat="server" Text="成功按钮" ButtonType="Success" />
        <cc:BootstrapButton ID="btnDanger" runat="server" Text="危险按钮" ButtonType="Danger" />
    </div>
</form>

注意：为了让 Bootstrap 样式生效，你必须在页面中引入 Bootstrap 的 CSS 文件。

运行后，你将看到三个不同样式的按钮，其 HTML 结构完全符合 Bootstrap 的规范。

第五部分：高级主题与最佳实践

状态管理
- ViewState：默认开启，用于在回发之间保存控件的属性值，对于简单的、非大量数据的属性，使用 ViewState 是最方便的，但对于大型控件或列表数据，ViewState 会导致页面体积增大，影响性能，此时可以考虑禁用 ViewState 并使用其他方式（如 Session, Cache）或实现 IPostBackDataHandler 接口来手动处理回发数据。
- ControlState：与 ViewState 类似，但即使 EnableViewState="false"，它也会被保留,适用于控件的核心功能所必需的数据。
事件处理
- 自定义控件可以通过 BubbleEvent 或实现 INamingContainer 接口来将子控件的事件“冒泡”到父控件或页面，也可以直接定义自己的事件，如 public event EventHandler Click;。
设计时支持
- 如 EmailInput 示例所示，创建一个 Designer 类可以极大地提升开发体验，你可以使用 System.Web.UI.Design 命名空间中的类来操作设计器表面、提供数据源、编辑模板等。
资源文件
- 为了实现国际化，不要将硬编码的字符串（如 ErrorMessage）写在代码里，应该使用 .resx 资源文件，在控件中，可以通过 HttpContext.GetGlobalResourceObject 或 HttpContext.GetLocalResourceObject 来读取资源文件中的字符串。
发布与部署
- 将编译后的 MyCustomControls.dll 文件复制到你的 Web 应用程序的 bin 文件夹中。
- 确保 Web.config 中的 pages/controls 配置正确。
- 如果控件被多个项目共享，可以考虑将其部署到 GAC（全局程序集缓存）中，但这在现代开发中已不常见，通常直接部署到 bin 目录更简单。

通过本教程，你已经学习了 ASP.NET 自定义控件的两种主要类型：复合控件和派生控件。

复合控件适合“搭积木”,将现有控件组合成新功能。
派生控件适合“定制化”,从零开始或修改现有控件的呈现方式。

自定义控件是构建大型、可维护、可扩展的 ASP.NET 应用程序的强大工具，掌握它，将让你从一个页面开发者向真正的组件开发者迈进，从今天开始，尝试将你项目中重复的 UI 逻辑封装成自定义控件吧！

asp.net自定义控件教程