Ext.NET Button 控件深度解析：客戶端/服務端事件、參數傳遞與自定義屬性

Ext.NET Button 事件機制總覽

Ext.NET（原 Coolite）是 Ext JS 的 ASP.NET 伺服器端封裝。Button 控件支援三種互動模式：純客戶端、服務端 DirectEvent、服務端帶參數 DirectEvent，以及自定義屬性注入客戶端。

1. 純客戶端事件（零往返）

<ext:Button ID="Button1" runat="server" Text="客戶端點擊">
    <Listeners>
        <Click Handler="Greet()" />
    </Listeners>
</ext:Button>

<script>
    function Greet() { alert("Hello World!"); }
</script>

特點： 無 Postback，無伺服器負擔，適合 UI 交互、驗證、彈窗等純前端邏輯。

2. 服務端 DirectEvent（AJAX 往返）

<ext:Button ID="Button1" runat="server" Text="服務端點擊">
    <DirectEvents>
        <Click OnEvent="MyButtonClickHandler" />
    </DirectEvents>
</ext:Button>

protected void MyButtonClickHandler(object sender, DirectEventArgs e) {
    X.Msg.Alert("標題", "Hello World!").Show();
}

關鍵點：

• DirectEventArgs 提供 ExtraParams、EventArguments 等豐富上下文
• 若改用 EventArgs 將失去 ExtraParams 存取能力
• 作者註：調試時後台斷點命中但前台無 Alert，可能因 X.Msg.Alert 需 .Show() 顯式渲染，或 JS 錯誤中斷

3. 服務端事件帶參數

<ext:Button ID="Button1" runat="server" Text="帶參點擊">
    <DirectEvents>
        <Click OnEvent="MyButtonClickHandler">
            <ExtraParams>
                <ext:Parameter Name="param1" Value="value1" Mode="Raw" />
                <ext:Parameter Name="userId" Value="App.currentUser.id" Mode="Raw" />
            </ExtraParams>
        </Click>
    </DirectEvents>
</ext:Button>

protected void MyButtonClickHandler(object sender, DirectEventArgs e) {
    string p1 = e.ExtraParams["param1"]; // "value1"
    string uid = e.ExtraParams["userId"]; // 客戶端 JS 變數值
    X.Msg.Alert("收到", $"{p1}, {uid}").Show();
}

Mode="Raw" 表示 Value 視為 JS 表達式（如變數、函數調用）；預設 Mode="Value" 視為字面字串。

4. 自定義屬性注入客戶端

<ext:Button ID="Button1" runat="server" Text="自定義屬性">
    <Listeners>
        <Click Handler="CusProperty(this);" />
    </Listeners>
    <CustomConfig>
        <ext:ConfigItem Name="cusProperty1" Value="theValue" Mode="Value" />
        <ext:ConfigItem Name="dynamicVal" Value="Date.now()" Mode="Raw" />
    </CustomConfig>
</ext:Button>

<script>
    function CusProperty(btn) {
        alert("靜態值：" + btn.cusProperty1); // "theValue"
        alert("動態值：" + btn.dynamicVal);   // 當前時間戳
    }
</script>

原理： CustomConfig 將屬性序列化到客戶端組件實例，this 即該 Button 的 JS 物件。

實戰建議與最佳實踐

常見問題排查

1. DirectEvent 不觸發：檢查 runat="server"、ID 唯一、頁面有 <ext:ResourceManager>
2. ExtraParams 取不到值：確認 Mode 正確、JS 表達式無語法錯誤（F12 Network 觀察 Request Payload）
3. X.Msg.Alert 不顯示：必須鏈式調用 .Show()，或使用 X.Msg.Show(new MessageBoxConfig { ... })