ASP.NET WebForms 中,`.aspx` 頁面與 `.ascx` 使用者控制項之間傳值,核心在於 **公開屬性 (Properties)**、**公開方法 (Methods)**、**事件** 三種模式。本文提供 C# 完整範例,涵蓋宣告、設定、取得、事件回傳。
ParentPage.aspx
├─ 設定 UserControl 屬性
├─ 訂閱 UserControl 事件
└─ 呼叫 UserControl 方法
UserControl.ascx
├─ 公開屬性 (供父頁面設定/讀取)
├─ 公開方法 (供父頁面呼叫)
└─ 觸發事件 (通知父頁面)
<%@ Control Language="C#" ClassName="WebUserControl" %>
<script runat="server">
public partial class WebUserControl : System.Web.UI.UserControl
{
//--- 公開屬性:父頁面設定書名 ---
private string _bookTitle = "";
public string BookTitle
{
get { return _bookTitle; }
set { _bookTitle = value; lblTitle.Text = value; } // 同步更新 UI
}
//--- 公開屬性:父頁面讀取使用者輸入 ---
public string SearchKeyword
{
get { return txtKeyword.Text.Trim(); }
}
//--- 公開方法:父頁面呼叫重置 ---
public void ResetForm()
{
txtKeyword.Text = "";
lblTitle.Text = _bookTitle;
}
//--- 事件:使用者點擊搜尋,通知父頁面 ---
public event EventHandler SearchClicked;
protected void btnSearch_Click(object sender, EventArgs e)
{
SearchClicked?.Invoke(this, new SearchEventArgs(txtKeyword.Text.Trim()));
}
}
// 事件參數類別
public class SearchEventArgs : EventArgs
{
public string Keyword { get; private set; }
public SearchEventArgs(string keyword) { Keyword = keyword; }
}
</script>
<asp:Label ID="lblTitle" runat="server" /><br />
<asp:TextBox ID="txtKeyword" runat="server" />
<asp:Button ID="btnSearch" runat="server" Text="搜尋" OnClick="btnSearch_Click" />
<%@ Page Language="C#" %>
<%@ Register Src="WebUserControl.ascx" TagPrefix="uc" TagName="BookSearch" %>
<script runat="server">
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack)
{
// 1. 設定屬性 (初始化)
BookSearch1.BookTitle = "ASP.NET 進階開發";
}
}
// 2. 訂閱事件 (在 Init 或 Load 階段)
protected void Page_Init(object sender, EventArgs e)
{
BookSearch1.SearchClicked += BookSearch1_SearchClicked;
}
void BookSearch1_SearchClicked(object sender, WebUserControl.SearchEventArgs e)
{
// 父頁面接收到使用者輸入的關鍵字
lblResult.Text = "搜尋關鍵字: " + Server.HtmlEncode(e.Keyword);
// 可進一步呼叫資料庫、繞繫 GridView 等
}
// 3. 呼叫控制項公開方法
protected void btnReset_Click(object sender, EventArgs e)
{
BookSearch1.ResetForm();
}
</script>
<html><body>
<form id="form1" runat="server">
<uc:BookSearch ID="BookSearch1" runat="server" />
<hr />
<asp:Label ID="lblResult" runat="server" /><br />
<asp:Button ID="btnReset" runat="server" Text="重置控制項" OnClick="btnReset_Click" />
</form>
</body></html>
protected void Page_Init(object sender, EventArgs e)
{
var ctrl = (WebUserControl)LoadControl("WebUserControl.ascx");
ctrl.ID = "DynamicBookSearch";
ctrl.BookTitle = "動態載入標題";
ctrl.SearchClicked += Ctrl_SearchClicked;
phContainer.Controls.Add(ctrl); // PlaceHolder 控制項
}
' 在 UserControl 內部
var parentPage = this.Page as ParentPage;
if (parentPage != null)
{
var masterValue = parentPage.SomePublicProperty;
parentPage.SomePublicMethod();
}
' 注意:造成強耦合,建議改用「介面」或「事件」解耦
| 場景 | 推薦方式 | 關鍵點 |
|---|---|---|
| 父→子 單向資料 | 公開屬性 (Property) | `Page_Init` 或 `Page_Load` (非 PostBack) 設定 |
| 子→父 通知/資料回傳 | 自訂事件 + EventArgs | 鬆耦合、型別安全、支援多播 |
| 父呼叫子功能 | 公開方法 (Method) | 命名語意化 (如 `ResetForm`、`BindData`) |
| 子需父資源 | 介面 (Interface) + 依賴注入 | 避免強轉 `this.Page`,利於單元測試 |
| 跨控制項通訊 | 父頁面協調 / 事件總線 | 不要讓控制項直接互相引用 |
遷移提示:ASP.NET Core / Blazor / Razor Pages 已無 UserControl 概念,改用 **ViewComponent**、**Partial View**、**Blazor Component**,資料流為單向 (Parameter/EventCallback),架構更清晰。