使用者控制項 (.ascx) 是 ASP.NET Web Forms 封裝可重用 UI 片段的核心機制。掌握「如何向控制項傳參數」、「頁面如何存取控制項內部成員」、「控制項如何對外公開事件」三大核心技巧,是構建模組化、可維護頁面的關鍵。
在 .ascx.cs 定義公共屬性,頁面透過宣告式標記或程式碼後置賦值。
public partial class UC_UserClass : System.Web.UI.UserControl
{
private int _classID = 0;
public int ClassID
{
get { return _classID; }
set { _classID = value; }
}
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack)
{
// 使用 ClassID 執行資料繫結等初始化邏輯
BindData(_classID);
}
}
}
<%@ Register Src="~/Controls/UC_UserClass.ascx" TagPrefix="uc1" TagName="UC_UserClass" %>
<uc1:UC_UserClass ID="UC_UserClass1" runat="server" ClassID="100" />
// 必須在頁面類別宣告對應欄位,VS2005+ 自動生成,VS2003 需手動加入
protected UC_UserClass UC_UserClass1;
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack)
{
UC_UserClass1.ClassID = 123456789; // 動態計算值
}
}
注意:控制項 ID 必須與頁面類別欄位名稱完全一致,否則找不到強型別參考。
使用 FindControl 穿透命名容器邊界,或直接公開強型別屬性/方法。
DropDownList ddl = UC_UserClass1.FindControl("ddlCategory") as DropDownList;
if (ddl != null) ddl.SelectedValue = "5";
// 在 UC_UserClass.ascx.cs 中
public string SelectedCategory
{
get { return ddlCategory.SelectedValue; }
set { ddlCategory.SelectedValue = value; }
}
// 頁面直接使用
string cat = UC_UserClass1.SelectedCategory;
UC_UserClass1.SelectedCategory = "8";
// 控制項
public void RefreshData(int newClassID) { ClassID = newClassID; BindData(newClassID); }
// 頁面
UC_UserClass1.RefreshData(999);
控制項定義事件,頁面訂閱處理,實現雙向通訊而不產生循環參考。
public event EventHandler CategorySelected;
public class CategorySelectedEventArgs : EventArgs
{
public int CategoryID { get; set; }
public string CategoryName { get; set; }
}
protected void ddlCategory_SelectedIndexChanged(object sender, EventArgs e)
{
var handler = CategorySelected;
if (handler != null)
handler(this, new CategorySelectedEventArgs
{
CategoryID = int.Parse(ddlCategory.SelectedValue),
CategoryName = ddlCategory.SelectedItem.Text
});
}
<uc1:UC_UserClass ID="UC_UserClass1" runat="server" OnCategorySelected="UC_UserClass1_CategorySelected" />
// 或程式碼後置
UC_UserClass1.CategorySelected += UC_UserClass1_CategorySelected;
void UC_UserClass1_CategorySelected(object sender, CategorySelectedEventArgs e)
{
lblInfo.Text = $"使用者選擇: {e.CategoryName} (ID={e.CategoryID})";
}
Control ctrl = LoadControl("~/Controls/UC_UserClass.ascx");
var uc = ctrl as UC_UserClass;
if (uc != null)
{
uc.ClassID = 888;
uc.CategorySelected += UC_CategorySelected;
phContainer.Controls.Add(ctrl); // PlaceHolder 或 Panel 作為容器
}
關鍵點:動態載入必須在 Page_Init 或更早階段執行,並確保每次 PostBack 都以相同 ID 重建控制項樹,以維持 ViewState 與事件連線。
| 問題 | 原因 | 解決方案 |
|---|---|---|
| 屬性值在 PostBack 後歸零 | 屬性未存入 ViewState | 屬性 getter/setter 讀寫 ViewState["Key"] 或使用 ControlState |
| FindControl 回傳 null | 命名容器隔離 / 控制項尚未建立 / ID 錯誤 | 確認命名容器層級、在 PreRender 後查找、使用唯一 ID |
| 動態載入控制項事件不觸發 | PostBack 時未以相同 ID 重建 | 在 Page_Init 重建,ID 固定,ViewState 自動還原 |
| VS2003 頁面類別缺少控制項欄位 | 舊版設計師不自動生成 | 手動加入 protected UC_UserClass UC_UserClass1; 欄位 |
使用者控制項參數傳遞的核心是 屬性注入,跨邊界存取的核心是 FindControl 或強型別包裝,雙向通訊的核心是 事件模式。遵循「高內聚、低耦合、封裝內部結構」原則,將控制項打造成真正可重用、可測試、可維護的 UI 元件。