syncfusion-blazor-popups

实现 Syncfusion Blazor 弹出窗口

对话框

Syncfusion Blazor Dialog 组件为在 Blazor 应用程序中创建模态和非模态对话框提供了灵活且功能丰富的解决方案。对话框是重要的 UI 元素，可在主应用程序上方显示警报、确认信息、表单和交互式内容。

组件概述

Dialog 组件支持：

• 基于模板的布局（标头、内容、页脚，可包含自定义 HTML/组件）
• 多种交互模式（模态和非模态）
• 丰富的事件系统（生命周期、拖动、调整大小、遮罩层交互）
• 高级定位（固定、绝对、相对、居中）
• 交互功能（可拖动、可调整大小、最小化/最大化按钮、全屏模式）
• 无障碍支持（符合 WCAG 标准、键盘导航、ARIA 属性）
• 动画（打开/关闭过渡效果）
• 状态管理（可见性绑定、状态持久化）

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• Blazor WebAssembly 和 Server 项目配置
• 添加命名空间和 Syncfusion 服务
• 基本对话框实现
• CSS 导入和主题配置
• 显示标头和内容，以及设置可见性

模板与内容自定义

📄 阅读： references/templates.md

• 使用自定义 HTML 和图标的标头模板
• 使用表单和 Blazor 组件的内容模板
• 页脚模板和自定义按钮
• DialogTemplates 结构
• 在对话框中嵌入复杂 UI 元素

对话框按钮

📄 阅读： references/dialog-buttons.md

• DialogButton 组件配置
• 按钮位置和点击处理程序
• 使用 DialogButtons 与 FooterTemplate
• 标准按钮模式和常见用例

事件与交互

📄 阅读： references/events.md

• 生命周期事件（Created、Destroyed）
• 打开和关闭事件（OnOpen、Opened、OnClose、Closed）
• 拖动事件（OnDragStart、OnDrag、OnDragStop）
• 调整大小事件（OnResizeStart、Resizing、OnResizeStop）
• 模态遮罩层交互（OnOverlayModalClick）

定位与可见性

📄 阅读： references/positioning-visibility.md

• Position 属性（固定、绝对、相对）
• 用于控制显示/隐藏的 Visible 绑定
• 目标元素配置
• 在页面上居中对话框
• 宽度和高度配置
• Z-index 管理

对话框行为与功能

📄 阅读： references/dialog-behavior.md

• 模态与非模态对话框
• AllowDragging 和 EnableResize 属性
• 用于性能优化的 AllowPrerender
• ShowCloseIcon 配置
• 创建嵌套对话框
• 动画支持
• IsModal 和遮罩层行为

方法与程序化控制

📄 阅读： references/methods.md

• 使用 ShowAsync() 以程序化方式打开对话框
• 使用 ShowAsync(true) 以全屏模式打开对话框
• 使用 HideAsync() 以程序化方式关闭对话框
• 使用 GetDimension() 获取对话框尺寸
• 使用 GetButton(index) 和 GetButtonItems() 访问按钮
• 使用 RefreshPositionAsync() 重新计算位置
• 完整控制示例

高级自定义与样式

📄 阅读： references/advanced-customization.md

• CSS 类自定义和样式设置
• 外观自定义
• 无障碍功能（符合 WCAG 标准、键盘导航）
• 动画配置
• 使用 EnablePersistence 的状态持久化策略
• 最小化/最大化按钮实现
• 本地化支持
• 响应式对话框设计

快速入门

基本对话框

@using Syncfusion.Blazor.Popups

<SfDialog Width="300px" Header="Welcome">
    <DialogTemplates>
        <Content>This is a basic dialog with content.</Content>
    </DialogTemplates>
</SfDialog>

带显示/隐藏控制的对话框

@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons

<div id="target">
    <SfButton OnClick="@OpenDialog">Open Dialog</SfButton>
    
    <SfDialog Target="#target" Width="400px" Header="Confirmation" 
              ShowCloseIcon="true" @bind-Visible="IsVisible">
        <DialogTemplates>
            <Content>Are you sure you want to proceed?</Content>
        </DialogTemplates>
        <DialogButtons>
            <DialogButton Content="OK" IconCss="e-icons e-ok-icon" IsPrimary="true" OnClick="@OnOkClick" />
            <DialogButton Content="Cancel" IconCss="e-icons e-close-icon" OnClick="@OnCancelClick" />
        </DialogButtons>
    </SfDialog>
</div>

@code {
    private bool IsVisible { get; set; } = false;
    
    private void OpenDialog() => IsVisible = true;
    
    private void OnOkClick()
    {
        // Handle OK action
        IsVisible = false;
    }
    
    private void OnCancelClick()
    {
        // Handle Cancel action
        IsVisible = false;
    }
}

常见模式

警告对话框

<SfDialog Width="350px" IsModal="true" Header="Alert">
    <DialogTemplates>
        <Content>This action cannot be undone.</Content>
    </DialogTemplates>
</SfDialog>

表单对话框

<SfDialog Width="400px" Header="User Information">
    <DialogTemplates>
        <Content>
            <div class="form-group">
                <input type="text" placeholder="Enter name" />
            </div>
        </Content>
    </DialogTemplates>
</SfDialog>

可拖动和调整大小的对话框

<SfDialog Width="400px" Header="Features" AllowDragging="true" EnableResize="true">
    <DialogTemplates>
        <Content>You can drag and resize this dialog.</Content>
    </DialogTemplates>
</SfDialog>

全屏对话框

@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons

<SfButton OnClick="@OpenFullScreenDialog">Open Fullscreen Dialog</SfButton>

<SfDialog @ref="DialogRef" Width="250px" ShowCloseIcon="true" Visible="false">
    <DialogTemplates>
        <Header>Dialog</Header>
        <Content>This is a fullscreen dialog</Content>
    </DialogTemplates>
    <DialogButtons>
        <DialogButton Content="OK" IsPrimary="true" OnClick="@CloseDialog" />
        <DialogButton Content="Cancel" OnClick="@CloseDialog" />
    </DialogButtons>
</SfDialog>

@code {
    SfDialog DialogRef;

    private async Task OpenFullScreenDialog()
    {
        await this.DialogRef.ShowAsync(true);
    }

    private async Task CloseDialog()
    {
        await this.DialogRef.HideAsync();
    }
}

关键属性

属性	类型	用途
Width	string	设置对话框宽度（例如，"400px"、"50%"）。默认值："100%"
Height	string	设置对话框高度（例如，"300px"、"70%"）。默认值："auto"
Header	string	设置对话框标题文本
Content	string	设置对话框内容文本
Visible	bool	控制对话框的可见性。支持 @bind-Visible。默认值：true
IsModal	bool	将对话框设为模态（覆盖层会阻止交互）。默认值：false
ShowCloseIcon	bool	在标题栏中显示关闭按钮。默认值：false
AllowDragging	bool	启用通过标题栏拖动对话框。默认值：false
EnableResize	bool	启用调整对话框大小。默认值：false
CloseOnEscape	bool	按下 Escape 键时关闭对话框。默认值：true
AnimationSettings	DialogAnimationSettings	配置打开/关闭动画（效果、时长、延迟）。默认值：淡入淡出效果，400ms
Position	string	定位模式："fixed"（保持在屏幕上）、"absolute"（相对于目标定位）或 "relative"（文档流）。默认值："fixed"
Left	string	X 坐标位置（例如，"100px"、"20%"）。与 Position 属性配合使用。默认值："auto"
Top	string	Y 坐标位置（例如，"50px"、"10%"）。与 Position 属性配合使用。默认值："auto"
ID	string	对话框的唯一标识符。EnablePersistence="true" 时必需
MinHeight	string	设置调整大小时的最小高度限制（例如，"150px"）。默认值：null
MaxHeight	string	设置调整大小时的最大高度限制（例如，"600px"）。默认值：null
ResizeHandles	ResizeDirection[]	调整大小的方向数组（例如，SouthEast、NorthEast）。默认值：[SouthEast]
Buttons	List<DialogButtonModel>	以编程方式配置按钮（可替代 DialogButtons 组件）
CssClass	string	用于设置样式的自定义 CSS 类
EnableRtl	bool	启用从右到左布局支持。默认值：false
EnablePersistence	bool	将位置、宽度和高度保存到浏览器本地存储。默认值：false。需要 ID 属性
Target	string	对话框目标/容器元素的 CSS 选择器（例如，"#container"、".target-div"）
FooterTemplate	RenderFragment	自定义页脚内容（可替代 DialogButtons 组件）
AllowPrerender	bool	隐藏时保留 DOM 元素，以便更快地重新显示。默认值：false
ZIndex	double	设置相对于其他元素的堆叠顺序。默认值：1000

关键枚举和类型

DialogEffect 枚举

对话框打开/关闭过渡动画的效果：

值	描述
None	无动画
Fade	淡入/淡出效果（默认）
Zoom	从中心放大/缩小
SlideLeft	从左侧滑入/滑出
SlideRight	从右侧滑入/滑出
SlideTop	从顶部滑入/滑出
SlideBottom	从底部滑入/滑出
FlipX	水平翻转效果
FlipY	垂直翻转效果

ResizeDirection 枚举

可用于调整对话框大小的方向：

值	描述
South	底边
North	顶边
East	右边
West	左边
SouthEast	右下角（默认）
SouthWest	左下角
NorthEast	右上角
NorthWest	左上角
All	所有方向

ButtonType 枚举

对话框按钮的 HTML button 类型属性：

值	描述
Button	标准按钮（默认）
Submit	表单提交按钮
Reset	表单重置按钮

DialogAnimationSettings 类

对话框动画的配置：

属性	类型	描述	默认值
Effect	DialogEffect	动画效果	DialogEffect.Fade
Duration	int	动画时长（毫秒）	400
Delay	int	动画延迟（毫秒）	0

• 需要最大限度地集中注意力并充分利用屏幕空间时，对全屏对话框使用 ShowAsync(true)
• 使用 ShowAsync() 进行编程控制时，初始设置 Visible="false" 示例：

var animSettings = new DialogAnimationOptions 
{ 
    Effect = DialogEffect.Zoom, 
    Duration = 300, 
    Delay = 0 
};

DialogDimension 类

由 GetDimension() 方法返回：

属性	类型	描述
Width	string	当前对话框宽度
Height	string	当前对话框高度

重要限制和注意事项

⚠️ 关键要求：

• ID 属性：使用 EnablePersistence="true" 时必须设置。ID 用作 localStorage 键。
• 互斥性：FooterTemplate 和 DialogButtons 不能同时使用。请选择其中一种方式。
• 目标选择器：Target 属性必须引用有效的 CSS 选择器，且对应的 DOM 元素必须已存在。
• 调整大小依赖项：只有在 EnableResize="true" 时，ResizeHandles 才会生效。
• 位置上下文：Position 属性会影响对 Left 和 Top 坐标的解释方式。

📋 最佳实践：

• 对需要用户关注的关键操作，使用 IsModal="true"
• 对频繁切换的对话框设置 AllowPrerender="true"，以提升性能
• 始终提供关闭方式（按钮、关闭图标或 Escape 键）
• 对嵌套对话框使用递增的 ZIndex 值（1000、1001、1002）
• 使用基于百分比的 Width/Height 值测试响应式行为

相关技能

• implementing-buttons - 用于设置对话框按钮的样式和行为
• implementing-dropdown-list - 用于设置对话框中的选择控件
• implementing-text-inputs - 用于设置对话框中的表单字段

---

另请参阅

• Syncfusion Blazor 对话框文档
• 对话框事件参考
• Blazor 主题

工具提示

Syncfusion Blazor Tooltip 组件可在用户通过悬停、单击或聚焦与目标元素交互时显示消息，从而提供上下文信息。它支持丰富的内容、灵活的定位、多种触发模式和全面的自定义选项。

组件概述

Blazor Tooltip 组件提供：

• 多种内容类型：简单文本、HTML title 属性、模板、RenderFragment 和 MarkupString
• 灵活定位：12 种静态位置（TopLeft、TopCenter、TopRight、BottomLeft 等）、鼠标跟随和自定义偏移
• 打开模式选项：Hover、Click、Focus、Auto、Custom 及其组合
• 粘滞模式：通过关闭按钮保持工具提示打开
• 自定义：可通过 CSS 全面控制包装器、内容和提示指针
• 动态目标：支持在组件初始化后添加的元素
• 无障碍访问：符合 WCAG 2.2 标准，支持 ARIA 属性和键盘操作
• 碰撞处理：工具提示触及视口边界时自动重新定位

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 先决条件和系统要求
• 软件包安装（Syncfusion.Blazor.Popups 和 Themes）
• 命名空间导入和服务注册
• 样式表和脚本资源设置
• 使用 Button 实现基本 Tooltip
• WebAssembly App 配置
• Web App 设置（Server、Client、Auto 渲染模式）
• 交互式渲染模式配置
• 第一个 Tooltip 示例

内容管理

📄 阅读： references/content.md

• 使用 Content 属性设置简单文本内容
• 使用 HTML title 属性作为工具提示内容
• 使用 ContentTemplate 创建自定义 HTML 布局
• 使用 RenderFragment 设置动态内容
• 使用 MarkupString 渲染 HTML 字符串
• 在工具提示中放置交互元素
• 在工具提示内容中添加图片、格式化文本和链接
• 使用多个分区创建复杂的工具提示布局

定位和放置

📄 阅读： references/positioning.md

• 使用 Position 属性设置 12 种静态位置（TopLeft、TopCenter、TopRight、BottomLeft、BottomCenter、BottomRight、LeftTop、LeftCenter、LeftBottom、RightTop、RightCenter、RightBottom）
• 鼠标跟随行为（MouseTrail 属性）
• 偏移量配置（OffsetX 和 OffsetY）
• 碰撞检测和自动重新定位
• 使用 WindowCollision 处理视口边界
• 组合使用位置和偏移量
• 选择位置的最佳实践

打开模式和触发方式

📄 阅读： references/open-modes.md

• OpensOn 属性的取值（Auto、Hover、Click、Focus、Custom）
• 桌面设备与移动设备的行为差异
• 多种触发方式组合（例如，“Hover Click”）
• 粘滞模式（IsSticky）及关闭按钮
• 打开和关闭延迟（OpenDelay、CloseDelay）
• 使用公共方法实现自定义触发方式
• 移动设备上的轻触和长按行为
• 选择触发方式的最佳实践

自定义和样式

📄 阅读： references/customization-and-styling.md

• 使用 CssClass 属性设置自定义样式
• 自定义指示箭头（尺寸、颜色、形状）
• 工具提示容器和弹出层样式
• 内容样式（字体、颜色、内边距）
• 为所有 4 个方向设置箭头样式
• 内部和外部指示箭头的 CSS 结构
• 完整的 CSS 类参考
• 主题集成示例

尺寸

📄 阅读： references/dimensions.md

• Width 和 Height 属性
• 自动尺寸与固定尺寸策略
• 内容溢出时的滚动模式
• 组合使用 Height 和 IsSticky，创建可滚动的工具提示
• 响应式尺寸注意事项
• 处理内容溢出

目标配置

📄 阅读： references/target-configuration.md

• 使用 CSS 选择器设置 Target 属性
• 单个与多个目标元素
• 渲染后动态添加的目标元素
• 使用 TargetContainer 自动注册
• GUID ID 的限制（不能以数字开头）
• 选择目标的最佳实践
• 按钮、链接、输入框和自定义元素示例

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• ARIA 属性（role="tooltip"、aria-describedby、aria-hidden）
• 键盘导航（Tab 键聚焦，Escape 键关闭）
• 屏幕阅读器支持
• 从右到左（RTL）语言支持
• 颜色对比度要求
• 移动设备无障碍支持
• Axe-core 验证
• 创建无障碍工具提示的最佳实践

快速入门示例

带按钮的基本工具提示

@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons

<SfTooltip ID="Tooltip" Target="#btn" Content="@Content">
    <SfButton ID="btn" Content="Show Tooltip"></SfButton>
</SfTooltip>

@code
{
    string Content = "Click to save your changes!";
}

自定义位置的工具提示

@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons

<SfTooltip Target="#saveBtn" Content="Save changes" Position="Position.RightCenter">
    <SfButton ID="saveBtn" Content="Save"></SfButton>
</SfTooltip>

使用类选择器创建多个工具提示

@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons

<SfTooltip ID="Tooltip" Target=".action-btn" Content="Click to perform action">
    <div id="container">
        <SfButton ID="btn1" CssClass="action-btn" Content="Save" title="Save your work"></SfButton>
        <SfButton ID="btn2" CssClass="action-btn" Content="Cancel" title="Discard changes"></SfButton>
        <SfButton ID="btn3" CssClass="action-btn" Content="Delete" title="Remove item permanently"></SfButton>
    </div>
</SfTooltip>

常见模式

使用点击触发的粘滞工具提示

<SfTooltip Target="#helpBtn" Content="Need help? Contact support at [email protected]" 
           OpensOn="Click" IsSticky="true">
    <SfButton ID="helpBtn" Content="Help" IconCss="e-icons e-help"></SfButton>
</SfTooltip>

带 HTML 模板的工具提示

<SfTooltip Target="#infoBtn" OpensOn="Click">
    <ContentTemplate>
        <div style="padding: 10px;">
            <h4 style="margin: 0 0 10px 0;">User Information</h4>
            <p><strong>Name:</strong> John Doe</p>
            <p><strong>Email:</strong> [email protected]</p>
            <p><strong>Status:</strong> Active</p>
        </div>
    </ContentTemplate>
    <ChildContent>
        <SfButton ID="infoBtn" Content="Info" IsPrimary="true"></SfButton>
    </ChildContent>
</SfTooltip>

鼠标跟随工具提示

<SfTooltip MouseTrail="true" Content="Follow the cursor" Target="#trackArea">
    <div id="trackArea" style="width: 300px; height: 200px; border: 2px dashed #ccc; padding: 20px;">
        Hover over this area - the tooltip follows your mouse!
    </div>
</SfTooltip>

自定义样式的工具提示

<SfTooltip Target="#customBtn" Content="Custom styled tooltip" CssClass="custom-tooltip">
    <SfButton ID="customBtn" Content="Hover Me"></SfButton>
</SfTooltip>

<style>
    .custom-tooltip.e-tooltip-wrap {
        background-color: #2196F3;
        border-radius: 8px;
    }
    
    .custom-tooltip.e-tooltip-wrap .e-tip-content {
        color: white;
        font-weight: 600;
        padding: 8px 12px;
    }
    
    .custom-tooltip.e-tooltip-wrap .e-arrow-tip-outer.e-tip-top {
        border-bottom: 10px solid #2196F3;
    }
</style>

使用 TargetContainer 设置动态目标

<SfTooltip ID="dynamicTooltip" Target=".dynamic-item" TargetContainer="#app-container" Content="Dynamic content item">
</SfTooltip>

<div id="app-container">
    <button class="dynamic-item" title="Static button">Static</button>
    @if (showDynamic)
    {
        <button class="dynamic-item" title="Dynamically added button">Dynamic</button>
    }
</div>

@code {
    private bool showDynamic = false;
}

关键属性

基本属性

属性	类型	默认值	描述
Content	string	null	在工具提示中显示的文本内容
Target	string	null	目标元素的 CSS 选择器
Position	Position	TopCenter	工具提示的位置
OpensOn	string	"Auto"	触发模式（Auto、Hover、Click、Focus、Custom）
IsSticky	bool	false	保持工具提示打开，并显示关闭按钮
Animation	AnimationModel	null	打开/关闭过渡的动画设置

内容属性

属性	类型	描述
ContentTemplate	RenderFragment	自定义 HTML 内容模板。默认值：null
Content	string	简单文本或 HTML 字符串内容。默认值：null
ChildContent	RenderFragment	将目标元素包装在工具提示组件内。默认值：null

定位属性

属性	类型	默认值	描述
Position	Position	TopCenter	目标周围的固定位置
MouseTrail	bool	false	跟随鼠标指针
OffsetX	double	0	水平偏移量，单位为像素
OffsetY	double	0	垂直偏移量，单位为像素
WindowCollision	bool	false	使用视口而非父元素进行碰撞检测

计时属性

属性	类型	默认值	描述
OpenDelay	double	0	打开前的延迟时间（毫秒）
CloseDelay	double	0	关闭前的延迟时间（毫秒）

事件回调

事件	类型	描述
Created	EventCallback<object>	工具提示组件创建后触发
Destroyed	EventCallback<object>	工具提示组件销毁时触发
OnOpen	EventCallback<TooltipEventArgs>	工具提示显示前触发（可取消）
Opened	EventCallback<TooltipEventArgs>	工具提示打开后触发
OnClose	EventCallback<TooltipEventArgs>	工具提示隐藏前触发（可取消）
Closed	EventCallback<TooltipEventArgs>	工具提示关闭后触发
OnRender	EventCallback<TooltipEventArgs>	工具提示添加到 DOM 前触发（可取消）
OnCollision	EventCallback<TooltipEventArgs>	碰撞检测计算期间触发

公共方法

方法	返回类型	描述
OpenAsync(ElementReference?, TooltipAnimationSettings)	Task	以编程方式打开工具提示，可选指定目标和动画设置
CloseAsync(TooltipAnimationSettings)	Task	以编程方式关闭工具提示，可选指定动画设置
RefreshAsync()	Task	刷新工具提示，使其与动态 DOM 变更和目标更新同步
RefreshPositionAsync(ElementReference?)	Task	根据当前目标位置重新计算并更新工具提示位置

外观属性

属性	类型	描述
CssClass	string	用于设置样式的自定义 CSS 类。默认值：null
Width	string	工具提示宽度（auto 或像素值）。默认值："auto"
Height	string	工具提示高度（auto 或像素值）。默认值："auto"
ShowTipPointer	bool	显示/隐藏箭头指针。默认值：true
TipPointerPosition	TipPointerPosition	箭头指针的位置（Auto、Start、Middle、End）。默认值：Auto
EnableRtl	bool	启用从右到左的方向。默认值：false
HtmlAttributes	Dictionary<string, object>	工具提示元素的其他 HTML 属性。默认值：null
ID	string	工具提示组件的唯一标识符。默认值：自动生成

目标属性

属性	类型	描述
Target	string	目标元素的 CSS 选择器。默认值：null
Container	string	用于追加工具提示弹窗的容器元素。默认值："body"
TargetContainer	string	用于动态注册目标的容器选择器。默认值：null

关键类型和类

AnimationModel 类

工具提示打开和关闭动画的配置：

属性	类型	描述
Open	TooltipAnimationSettings	打开工具提示的动画设置
Close	TooltipAnimationSettings	关闭工具提示的动画设置

TooltipAnimationSettings 类

详细的动画配置：

属性	类型	默认值	描述
Effect	Effect	Fade	动画效果（FadeIn、FadeOut、ZoomIn、ZoomOut、None）
Duration	int	150	动画时长，单位为毫秒
Delay	int	0	动画延迟，单位为毫秒

Effect 枚举

工具提示过渡效果：

值	描述
None	无动画
FadeIn	打开时的淡入效果
FadeOut	关闭时的淡出效果
ZoomIn	打开时的缩放进入效果
ZoomOut	关闭时的缩放退出效果

Position 枚举

工具提示的放置位置：

值	描述
TopLeft	位于目标上方，与左边缘对齐
TopCenter	位于目标上方，居中（默认）
TopRight	位于目标上方，与右边缘对齐
BottomLeft	位于目标下方，与左边缘对齐
BottomCenter	位于目标下方，居中
BottomRight	位于目标下方，与右边缘对齐
LeftTop	位于目标左侧，与顶部边缘对齐
LeftCenter	位于目标左侧，垂直居中
LeftBottom	位于目标左侧，与底部边缘对齐
RightTop	位于目标右侧，与顶部边缘对齐
RightCenter	位于目标右侧，垂直居中
RightBottom	位于目标右侧，与底部边缘对齐

TipPointerPosition 枚举

工具提示上箭头指针的位置：

值	描述
Auto	自动调整指针位置（默认）
Start	指针位于工具提示边缘的起始处
Middle	指针位于工具提示边缘的中间
End	指针位于工具提示边缘的末尾

常见用例

表单字段帮助文本

为表单输入提供上下文帮助：

• 阅读 references/getting-started.md 了解基本设置
• 阅读 references/open-modes.md 了解 Focus 触发方式
• 使用 OpensOn="Focus"，在输入框获得焦点时显示工具提示
• 调整工具提示位置，避免遮挡输入框

图标按钮描述

为仅含图标的按钮添加描述文本：

• 对简短描述使用简单的 Content 属性
• 设置 OpensOn="Hover"，以便立即显示反馈
• 考虑使用 Position.TopCenter 或 Position.BottomCenter，保持一致性

富内容卡片

悬停时显示详细信息：

• 阅读 references/content.md 了解模板选项
• 将 ContentTemplate 与格式化的 HTML 配合使用
• 包含图片、链接和格式化文本
• 对于复杂内容，可考虑设置 OpensOn="Click" 和 IsSticky="true"

状态指示器

悬停时显示状态详情：

• 使用 CssClass 设置颜色编码的工具提示
• 阅读 references/customization-and-styling.md 了解样式设置
• 保持内容简洁易读

动态仪表板元素

为动态添加的小组件添加工具提示：

• 阅读 references/target-configuration.md 了解动态设置
• 使用 TargetContainer 处理初始化后添加的元素
• 使用数据属性设置工具提示内容

无障碍增强

确保工具提示易于访问：

• 阅读 references/accessibility.md 了解合规要求
• 在模板中使用语义化 HTML
• 确保键盘导航正常工作
• 使用屏幕阅读器进行测试
• 保持颜色对比度符合要求

预定义对话框

组件概述

Syncfusion Blazor 预定义对话框采用基于服务的架构，包含两个关键组件：

• SfDialogService - 用于以编程方式打开对话框的已注册服务
• SfDialogProvider - 添加到布局中以启用对话框渲染的组件

主要功能：

• 三种对话框类型：警告、确认、提示
• 可从应用中的任意位置通过服务调用
• 可自定义位置、尺寸和动画
• 支持可拖动对话框
• 可使用图标自定义按钮
• 自定义内容渲染
• 内置无障碍支持

包： Syncfusion.Blazor.Popups
命名空间： Syncfusion.Blazor.Popups

---

文档与导航指南

入门（设置与基本用法）

📄 阅读： references/getting-started.md

• 先决条件和系统要求
• 为 Blazor WebAssembly、Server App 和 Web App 安装
• 安装 NuGet 包（Syncfusion.Blazor.Popups）
• 导入命名空间（_Imports.razor）
• 注册服务（SfDialogService、AddSyncfusionBlazor）
• 将 SfDialogProvider 添加到 MainLayout
• 样式表和脚本引用
• 警告对话框基础知识（AlertAsync 方法）
• 确认对话框基础知识（ConfirmAsync 方法）
• 提示对话框基础知识（PromptAsync 方法）
• 三种对话框类型的基本代码示例

对话框定位

📄 阅读： references/positioning.md

• DialogOptions.Position 属性
• PositionDataModel 配置（X 和 Y）
• 位置值：left、center、right、top、bottom、offset
• 自定义警告、确认和提示对话框的位置
• 顶部居中定位示例

可拖动对话框

📄 阅读： references/dragging.md

• DialogOptions.AllowDragging 属性
• 通过对话框标题栏启用拖动行为
• 标题栏必须可见
• 可拖动的警告、确认和提示对话框示例

对话框尺寸

📄 阅读： references/dimensions.md

• DialogOptions.Width 和 Height 属性
• 默认自动调整尺寸行为
• 以像素或百分比设置尺寸
• 使用 CssClass 设置最大宽度和最大高度
• 使用 CssClass 设置最小宽度和最小高度
• 响应式尺寸策略
• 自定义尺寸示例

自定义选项

📄 阅读： references/customization.md

• DialogOptions.PrimaryButtonOptions（确定按钮）
• DialogOptions.CancelButtonOptions（取消按钮）
• DialogButtonOptions.Content（按钮文本）
• DialogButtonOptions.IconCss（按钮图标）
• DialogOptions.ShowCloseIcon 属性
• DialogOptions.ChildContent 用于自定义内容渲染
• 自定义警告、确认和提示对话框
• 高级内容自定义示例

动画效果

📄 阅读： references/animation.md

• DialogOptions.AnimationSettings 属性
• DialogAnimationOptions 配置
• 动画延迟、时长和效果
• DialogEffect 枚举值
• 缩放、淡入淡出、滑动效果
• 缩放动画示例

---

快速入门示例

基本警告对话框

@page "/alert-example"
@inject SfDialogService DialogService

<SfButton @onclick="ShowAlert">Show Alert</SfButton>

@code {
    private async Task ShowAlert()
    {
        await DialogService.AlertAsync("This is an alert message!");
    }
}

基本确认对话框

@page "/confirm-example"
@inject SfDialogService DialogService

<SfButton @onclick="ShowConfirm">Show Confirm</SfButton>
<p>@result</p>

@code {
    private string result = "";
    
    private async Task ShowConfirm()
    {
        bool isConfirmed = await DialogService.ConfirmAsync("Do you want to proceed?");
        result = isConfirmed ? "User clicked OK" : "User clicked Cancel";
    }
}

基本提示对话框

@page "/prompt-example"
@inject SfDialogService DialogService

<SfButton @onclick="ShowPrompt">Show Prompt</SfButton>
<p>@userInput</p>

@code {
    private string userInput = "";
    
    private async Task ShowPrompt()
    {
        string input = await DialogService.PromptAsync("Enter your name:");
        userInput = input ?? "User cancelled";
    }
}

---

常见模式

模式 1：删除前确认

private async Task DeleteItem(int itemId)
{
    var options = new DialogOptions()
    {
        PrimaryButtonOptions = new DialogButtonOptions()
        {
            Content = "Delete",
            IconCss = "e-icons e-delete"
        },
        CancelButtonOptions = new DialogButtonOptions()
        {
            Content = "Cancel"
        }
    };
    
    bool confirmed = await DialogService.ConfirmAsync(
        "Are you sure you want to delete this item?", 
        "Confirm Delete", 
        options
    );
    
    if (confirmed)
    {
        // Perform delete operation
    }
}

模式 2：定位对话框

private async Task ShowPositionedAlert()
{
    var options = new DialogOptions()
    {
        Position = new PositionDataModel()
        {
            X = "center",
            Y = "top"
        },
        Width = "400px",
        Height = "200px"
    };
    
    await DialogService.AlertAsync(
        "This dialog appears at the top center!",
        "Alert",
        options
    );
}

模式 3：自定义内容提示

private async Task ShowCustomPrompt()
{
    string username = "";
    
    var options = new DialogOptions()
    {
        ChildContent = @<div>
            <label>Username:</label>
            <input type="text" @bind="username" class="e-input" />
        </div>,
        PrimaryButtonOptions = new DialogButtonOptions() { Content = "Connect" },
        CancelButtonOptions = new DialogButtonOptions() { Content = "Close" }
    };
    
    await DialogService.PromptAsync("Enter your credentials:", "Login", options);
}

模式 4：带动画的可拖动对话框

private async Task ShowAnimatedDialog()
{
    var options = new DialogOptions()
    {
        AllowDragging = true,
        ShowCloseIcon = true,
        AnimationSettings = new DialogAnimationOptions()
        {
            Effect = DialogEffect.Zoom,
            Duration = 300,
            Delay = 0
        },
        Width = "500px"
    };
    
    await DialogService.AlertAsync(
        "Drag me around! I have zoom animation too!",
        "Draggable Dialog",
        options
    );
}

---

关键属性

SfDialogService 方法

方法	参数	返回值	描述
AlertAsync	title, content, options	Task	显示带有“确定”按钮的警告对话框
ConfirmAsync	title, content, options	Task<bool>	显示确认对话框，并返回 true/false
PromptAsync	title, defaultValue, options	Task<string>	显示提示对话框，并返回输入内容或 null

DialogOptions 属性

属性	类型	默认值	描述
Position	PositionDataModel	center/center	对话框位置（X、Y 坐标）
Width	string	"auto"	对话框宽度（px、%、em）
Height	string	"auto"	对话框高度（px、%、em）
AllowDragging	bool	false	启用通过标题栏拖动
ShowCloseIcon	bool	false	显示关闭图标按钮
AnimationSettings	DialogAnimationOptions	default	动画配置
PrimaryButtonOptions	DialogButtonOptions	null	主按钮（确定）的自定义设置
CancelButtonOptions	DialogButtonOptions	null	取消按钮的自定义设置
ChildContent	RenderFragment	null	对话框主体的自定义内容
CssClass	string	null	自定义 CSS 类
CloseOnEscape	bool	true	按 Escape 键时关闭
ZIndex	int	1000	对话框的 z-index

PositionDataModel 属性

属性	类型	值	描述
X	string	left, center, right, offset	水平位置
Y	string	top, center, bottom, offset	垂直位置

DialogButtonOptions 属性

属性	类型	描述
Content	string	按钮文本内容
IconCss	string	按钮图标的 CSS 类
IsPrimary	bool	主按钮样式

DialogAnimationSettings 属性

属性	类型	描述
Effect	DialogEffect	动画效果（Zoom、Fade 等）
Duration	int	动画时长（毫秒）
Delay	int	动画延迟（毫秒）

---

常见用例

用例 1：错误/警告/信息消息

使用警告对话框显示需要用户确认的系统消息、错误、警告或信息。

用例 2：关键操作确认

使用确认对话框，在执行删除、注销或可能导致数据丢失等破坏性操作前获取用户确认。

用例 3：收集用户输入

使用提示对话框收集简单的文本输入，例如用户名、搜索查询或配置值。

用例 4：表单验证反馈

使用定位对话框显示验证错误或成功消息，避免遮挡表单字段。

用例 5：自定义交互式对话框

创建包含自定义内容、多个输入项和自定义按钮的复杂交互式对话框。

用例 6：通知系统

构建带有动画效果和位置设置的通知系统，让对话框显示在屏幕的特定区域。

---

设置要求

先决条件：

1. Blazor WebAssembly、Server 或 Web App 项目
2. 已安装 .NET SDK
3. Visual Studio、VS Code 或 .NET CLI

所需软件包：

• Syncfusion.Blazor.Popups
• Syncfusion.Blazor.Themes

所需设置：

1. 在 Program.cs 中注册 SfDialogService
2. 注册 AddSyncfusionBlazor() 服务
3. 在 MainLayout.razor 中添加 SfDialogProvider
4. 在 head 中引入 Syncfusion 主题样式表
5. 在 body 中引入 Syncfusion 脚本引用
6. 在 _Imports.razor 中导入 Syncfusion.Blazor.Popups 命名空间

有关所有 Blazor 应用类型的完整设置说明，请参阅 references/getting-started.md。