ASP.NET 使用者控件開發與應用完整指南

使用者控件特性

• 副檔名 .ascx，無 @Page 指令，改為 @Control。
• 不可直接瀏覽，必須註冊後嵌入 .aspx 頁面。
• 可包含 HTML 標記、Web 控件、程式碼後置、事件處理。
• 支援公開屬性/方法，實現父頁面與控件雙向通訊。

建立搜尋控件範例

1. 標記

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="SearchBox.ascx.cs" Inherits="SearchBox" %>
<asp:TextBox ID="txtKeyword" runat="server" />
<asp:Button ID="btnSearch" runat="server" Text="搜尋" OnClick="btnSearch_Click" />

2. 程式碼後置

public partial class SearchBox : System.Web.UI.UserControl
{
    // 公開屬性：按鈕文字
    public string ButtonText
    {
        get => btnSearch.Text;
        set => btnSearch.Text = value;
    }

    // 公開事件：搜尋動作
    public event EventHandler SearchClicked;

    protected void btnSearch_Click(object sender, EventArgs e)
    {
        txtKeyword.Text = "搜尋完成：" + txtKeyword.Text;
        SearchClicked?.Invoke(this, new SearchEventArgs(txtKeyword.Text));
    }

    protected void Page_Load(object sender, EventArgs e)
    {
        if (!IsPostBack) btnSearch.Text = ButtonText;
    }
}

public class SearchEventArgs : EventArgs
{
    public string Keyword { get; }
    public SearchEventArgs(string keyword) => Keyword = keyword;
}

在 .aspx 頁面使用

1. 註冊指令

<%@ Register Src="~/Controls/SearchBox.ascx" TagPrefix="uc" TagName="SearchBox" %>

2. 拖曳或手寫標記

<uc:SearchBox ID="ucSearch1" runat="server" ButtonText="開始查詢" OnSearchClicked="ucSearch1_SearchClicked" />
<asp:Label ID="lblResult" runat="server" />

3. 父頁面處理事件

protected void ucSearch1_SearchClicked(object sender, SearchEventArgs e)
{
    lblResult.Text = "父頁面收到關鍵字：" + e.Keyword;
}

進階技巧

• 動態載入：var ctrl = LoadControl("~/Controls/SearchBox.ascx"); phContainer.Controls.Add(ctrl); 需在 Page_Init 執行以保持 ViewState。
• 巢狀控件存取：var txt = ucSearch1.FindControl("txtKeyword") as TextBox;。
• 樣式隔離：控件內部使用 CssClass，父頁面引用同名 CSS 即可統一風格。
• 快取輸出：@Control OutputCache Duration="60" VaryByParam="none" 針對靜態化片段。

適用場景

• 全站共用頁首/頁尾/導覽列/登入區塊。
• 重複業務區塊：商品卡片、新聞列表項、分頁器、搜尋框。
• 需在多個專案間共用的 UI 元件（編譯成 .dll 部署）。