您现在的位置：程式碼之家 >> 編程語言 > >> .NET 網頁程式設計 >> ASP.NET 基礎 >> ASP.NET 基礎

Ajax Control Toolkit BalloonPopupExtender 完整使用教學：從基礎到自訂樣式

編輯：ASP.NET 基礎

BalloonPopupExtender 是 Ajax Control Toolkit 中極實用的提示元件，能在使用者滑鼠移入/點擊目標控制項時，顯示豐富的彈出面板（支援 HTML、圖片、表單）。本文從套件安裝、基本屬性、三種內建樣式、自訂 CSS、完整範例到常見坑點一次說明。

快速開始：安裝與註冊

NuGet 安裝：Install-Package AjaxControlToolkit

頁面註冊 TagPrefix（或在 web.config 全域註冊）：

<%@ Register Assembly="AjaxControlToolkit" Namespace="AjaxControlToolkit" TagPrefix="ajaxToolkit" %>

頁面放入 ToolkitScriptManager（必須，負責腳本合併與載入）：

<ajaxToolkit:ToolkitScriptManager ID="ToolkitScriptManager1" runat="server" />

核心屬性速查表

屬性	說明	預設/範例
`TargetControlID`	觸發彈出的目標控制項 ID	"txtSearch"
`BalloonPopupControlID`	作為彈出內容容器的 Panel ID	"pnlHelp"
`Position`	彈出位置相對目標	TopLeft, TopRight, BottomLeft, BottomRight, Left, Right, Auto
`BalloonStyle`	內建樣式	Balloon(氣球), Rectangle(矩形), Cloud(雲朵), Custom(自訂)
`BalloonSize`	尺寸等級	Small, Medium, Large
`DisplayOnMouseOver`	true=滑鼠移入顯示，false=點擊顯示	true
`CustomCssUrl`	BalloonStyle=Custom 時的 CSS 檔案路徑	"~/Css/MyBalloon.css"
`UseShadow`	是否顯示陰影	true
`ShowArrow`	是否顯示箭頭指向目標	true

完整範例：滑鼠移入文字框顯示說明面板

<%@ Page Language="C#" %>
<%@ Register Assembly="AjaxControlToolkit" Namespace="AjaxControlToolkit" TagPrefix="ajaxToolkit" %>
<!DOCTYPE html>
<html>
<head runat="server">
    <title>BalloonPopup Demo</title>
    <style>
        .help-panel { padding: 10px; font-family: 'Microsoft JhengHei', sans-serif; background: #fffbea; border: 1px solid #f0e68c; border-radius: 6px; width: 260px; }
        .help-title { font-weight: bold; color: #b8860b; margin-bottom: 6px; }
    </style>
</head>
<body>
    <form id="form1" runat="server">
        <ajaxToolkit:ToolkitScriptManager ID="ScriptManager1" runat="server" />

        <div style="margin: 50px;">
            <label>帳號：</label>
            <asp:TextBox ID="txtAccount" runat="server" Width="200px" />
        </div>

        <!-- 彈出內容面板（預設隱藏） -->
        <asp:Panel ID="pnlAccountHelp" runat="server" CssClass="help-panel" Style="display: none;">
            <div class="help-title">💡 帳號輸入說明</div>
            <ul style="margin: 0; padding-left: 20px;">
                <li>長度 6~20 字元</li>
                <li>僅限英數字、底線</li>
                <li>不可使用中文或特殊符號</li>
            </ul>
            <img src="~/Images/keyboard.png" alt="鍵盤圖示" style="margin-top: 8px; max-width: 100%;" />
        </asp:Panel>

        <ajaxToolkit:BalloonPopupExtender ID="bpeAccount" runat="server"
            TargetControlID="txtAccount"
            BalloonPopupControlID="pnlAccountHelp"
            Position="Right"
            BalloonStyle="Cloud"
            BalloonSize="Medium"
            DisplayOnMouseOver="true"
            UseShadow="true"
            ShowArrow="true" />
    </form>
</body>
</html>

自訂樣式

設定 BalloonStyle="Custom" 並指定 CustomCssUrl。CSS 需定義以下類別（Toolkit 會自動套用）：

.ajax__balloon_popup { /* 外層容器 */ }
.ajax__balloon_popup .ajax__balloon_content { /* 內容區 */ }
.ajax__balloon_popup .ajax__balloon_arrow { /* 箭頭 */ }

範例 CSS 可參考 Toolkit 原始碼 BalloonPopup.css 修改顏色、圓角、陰影。

常見問題與解決

面板不顯示/位置錯誤：確認 BalloonPopupControlID 對應的 Panel 已設 Style="display: none;"，且在同一個 NamingContainer 內。
UpdatePanel 內失效：BalloonPopupExtender 必須與 TargetControl 在同一個 UpdatePanel，或設 ChildrenAsTriggers="true"。
IE 相容模式異常：頁面加入 <meta http-equiv="X-UA-Compatible" content="IE=Edge" />。
行動裝置觸控：DisplayOnMouseOver 在觸控裝置表現不一，建議改用點擊觸發（DisplayOnMouseOver="false"）並搭配 PopupOnClick="true"（Toolkit 更新版支援）。