syncfusion-winforms-popup

实现弹出控件（PopupControlContainer）

何时使用此技能

在以下情况下使用此技能：

• 需要在 Windows Forms 应用程序中创建自定义弹出面板
• 希望将弹出窗口附加到父控件（按钮、文本框、标签等）
• 正在使用自定义控件实现类似下拉列表的行为
• 需要为弹出窗口配置自动关闭、自动滚动或键盘导航
• 希望处理弹出窗口的生命周期事件（显示前、显示后、关闭时）
• 正在构建上下文菜单、下拉面板或自定义选择器控件
• 需要用子控件（按钮、网格、日历等）填充弹出窗口
• 需要透明或可调整大小的弹出窗口
• 正在弹出窗口中托管 ComboBoxBase 或其他复杂控件
• 遇到弹出窗口关闭行为或焦点管理方面的问题

组件概述

PopupControlContainer 是一个派生自面板的控件，可用于填充子控件并将其关联到父控件。默认情况下，弹出窗口处于隐藏状态，可通过父控件上的鼠标单击、按钮按下或键盘操作等事件以编程方式显示。

主要功能：

• 托管任意子控件（按钮、文本框、网格、自定义控件）
• 关联任意父控件
• 单击弹出窗口外部时自动关闭
• 内容超出弹出窗口大小时自动滚动
• 使用对话框按键进行键盘导航（Enter、Esc、Tab、F4、F2）
• 事件驱动的生命周期（BeforePopup、Popup、CloseUp）
• 以编程方式显示/隐藏并控制位置
• 可调整大小且透明的弹出窗口
• 支持嵌套弹出窗口（托管 ComboBoxBase）

常见用例：

• 用于文本框或按钮的自定义下拉面板
• 颜色选择器、日期选择器或自定义选择器
• 上下文相关的工具栏或选项面板
• 带有交互式控件的工具提示式窗口
• 自定义组合框实现

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 包
• 通过设计器和代码添加控件
• 基本的父控件关联
• ShowPopup 和 HidePopup 方法
• 完整的可运行示例

配置弹出行为

自动关闭行为
📄 阅读： references/auto-close-behavior.md

• 单击外部时默认自动关闭
• IgnoreMouseMessages 属性
• PopupCloseType 模式（Done、Canceled、Deactivated）
• 条件关闭场景

自动滚动
📄 阅读： references/autoscroll.md

• 启用自动滚动条
• AutoScrollMargin 和 AutoScrollMinSize
• 处理内容溢出

键盘导航
📄 阅读： references/keyboard-navigation.md

• 默认对话框按键行为
• IgnoreDialogKey 属性
• 自定义键盘处理

事件与生命周期

📄 阅读： references/events.md

• BeforePopup 事件（显示前、调整大小时）
• Popup 事件（显示后、焦点管理）
• CloseUp 事件（关闭时、数据传递）
• 助记键支持和焦点处理
• 完整的事件处理程序示例

高级场景

📄 阅读： references/advanced-scenarios.md

• 托管 ComboBoxBase 控件
• 创建透明弹出窗口
• 使用 IsShowing() 检查弹出窗口状态
• BeforeCloseUp 变通方法
• 边缘情况和故障排除

快速入门示例

基本弹出窗口设置

using Syncfusion.Windows.Forms;

public partial class Form1 : Form
{
    private PopupControlContainer popupControlContainer1;
    private Button button1;
    private RichTextBox richTextBox1;
    
    public Form1()
    {
        InitializeComponent();
        
        // Initialize popup container
        this.popupControlContainer1 = new PopupControlContainer();
        
        // Add child control (button in this example)
        this.button1 = new Button();
        this.button1.Text = "Click Me";
        this.button1.Location = new Point(10, 10);
        this.popupControlContainer1.Controls.Add(this.button1);
        
        // Configure popup
        this.popupControlContainer1.Size = new Size(200, 100);
        
        // Create parent control
        this.richTextBox1 = new RichTextBox();
        this.richTextBox1.Size = new Size(150, 50);
        this.richTextBox1.Location = new Point(20, 20);
        this.richTextBox1.Click += RichTextBox1_Click;
        
        // Associate popup with parent
        this.popupControlContainer1.ParentControl = this.richTextBox1;
        
        // Add controls to form
        this.Controls.Add(this.richTextBox1);
    }
    
    private void RichTextBox1_Click(object sender, EventArgs e)
    {
        // Show popup at default position
        this.popupControlContainer1.ShowPopup(Point.Empty);
    }
}

在特定位置显示弹出窗口

// Show at specific screen coordinates
this.popupControlContainer1.ShowPopup(new Point(100, 200));

// Show below parent control
Point location = this.richTextBox1.PointToScreen(
    new Point(0, this.richTextBox1.Height));
this.popupControlContainer1.ShowPopup(location);

以编程方式隐藏弹出窗口

// Simple hide
this.popupControlContainer1.HidePopup();

// Hide with close type
this.popupControlContainer1.HidePopup(PopupCloseType.Done);
this.popupControlContainer1.HidePopup(PopupCloseType.Canceled);

常见模式

模式 1：条件自动关闭

// Prevent auto-close on outside clicks
this.popupControlContainer1.IgnoreMouseMessages = true;

// Close only when condition is met
private void ValidateButton_Click(object sender, EventArgs e)
{
    if (ValidateInput())
    {
        this.popupControlContainer1.HidePopup(PopupCloseType.Done);
    }
}

模式 2：关闭时传递数据

private void PopupControlContainer1_CloseUp(object sender, PopupClosedEventArgs e)
{
    if (e.PopupCloseType == PopupCloseType.Done)
    {
        // Transfer data from popup to parent form
        this.textBox1.Text = this.popupTextBox.Text;
    }
    else if (e.PopupCloseType == PopupCloseType.Canceled)
    {
        // Discard changes
    }
}

模式 3：可调整大小的弹出窗口

private void PopupControlContainer1_BeforePopup(object sender, CancelEventArgs e)
{
    // Make popup resizable
    this.popupControlContainer1.PopupHost.FormBorderStyle = FormBorderStyle.SizableToolWindow;
    this.popupControlContainer1.Dock = DockStyle.Fill;
    
    // Set minimum size
    if (this.popupControlContainer1.PopupHost.Size.Width < 200)
    {
        this.popupControlContainer1.PopupHost.Size = new Size(200, 150);
    }
}

模式 4：透明弹出窗口

private void PopupControlContainer1_BeforePopup(object sender, CancelEventArgs e)
{
    // Set opacity for transparency
    this.popupControlContainer1.PopupHost.Opacity = 0.75;
}

关键属性和方法

属性

属性	类型	说明
ParentControl	Control	与弹出窗口关联的控件
IgnoreMouseMessages	bool	为 true 时，阻止在外部单击时自动关闭
IgnoreDialogKey	bool	为 true 时，禁用默认的键盘关闭行为
AutoScroll	bool	内容溢出时启用自动滚动条
AutoScrollMargin	Size	滚动区域周围的边距
AutoScrollMinSize	Size	滚动区域的最小尺寸
PopupHost	Form	包含弹出窗口的宿主窗体（可在事件中访问）

方法

方法	说明
ShowPopup(Point)	在指定的屏幕坐标处显示弹出窗口
HidePopup()	隐藏弹出窗口
HidePopup(PopupCloseType)	使用指定的关闭类型隐藏弹出窗口
IsShowing()	如果弹出窗口当前可见，则返回 true

事件

事件	触发时机	主要用途
BeforePopup	显示弹出窗口之前	调整弹出窗口大小、自定义外观、取消显示
Popup	显示弹出窗口之后	设置焦点、启用助记键
CloseUp	关闭弹出窗口时	传递数据、恢复焦点、处理关闭类型

常见用例

用例 1：自定义日期选择器

创建一个包含日历控件并附加到文本框的弹出窗口。

用例 2：颜色选择器弹出窗口

构建一个颜色选择器面板，单击按钮时弹出，并带有“确定”/“取消”按钮。

用例 3：上下文相关工具栏

在 RichTextBox 中选中文本时，显示包含格式选项的弹出式工具栏。

用例 4：多选下拉菜单

创建一个带复选框的弹出窗口以支持多选，仅在单击“完成”时关闭。

用例 5：级联弹出窗口

在弹出窗口中承载 ComboBoxBase，保持正确的焦点并防止过早关闭。

故障排除提示

弹出窗口立即关闭：

• 设置 IgnoreMouseMessages = true，以阻止自动关闭
• 检查是否需要启用 IgnoreDialogKey
• 确认事件处理程序没有意外调用 HidePopup()

子控件无法响应助记键：

• 处理 Popup 事件并调用 this.popupControlContainer1.Focus()

弹出窗口位置不正确：

• 使用 PointToScreen() 将父控件坐标转换为屏幕坐标
• 考虑父控件的大小和屏幕边界

内容被截断：

• 启用 AutoScroll = true
• 设置适当的 AutoScrollMinSize
• 在 BeforePopup 事件中调整弹出窗口的大小

ComboBoxBase 下拉菜单关闭弹出窗口：

• 实现并重写 OnPopup() 的自定义 PopupControlContainer
• 在 ComboBoxBase 的 DropDown 事件中设置父子关系
• 有关完整实现，请参阅 references/advanced-scenarios.md

---

有关详细的实现指南、代码示例和边缘情况处理，请使用上文的 Documentation and Navigation Guide 导航至相应的参考文件。