syncfusion-blazor-popups
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion Blazor Popups
实现Syncfusion Blazor弹窗
Dialog
对话框
The Syncfusion Blazor Dialog component provides a flexible, feature-rich solution for creating modal and modeless dialogs in Blazor applications. Dialogs are essential UI elements for displaying alerts, confirmations, forms, and interactive content overlaid on the main application.
Syncfusion Blazor Dialog组件为Blazor应用创建模态和非模态对话框提供了灵活且功能丰富的解决方案。对话框是在主应用上层显示警报、确认信息、表单和交互式内容的重要UI元素。
Component Overview
组件概述
The Dialog component supports:
- Template-based layouts (header, content, footer with custom HTML/components)
- Multiple interaction modes (modal and modeless)
- Rich event system (lifecycle, drag, resize, overlay interactions)
- Advanced positioning (fixed, absolute, relative, centered)
- Interactive features (draggable, resizable, minimize/maximize buttons, fullscreen mode)
- Accessibility support (WCAG compliance, keyboard navigation, ARIA attributes)
- Animations (open/close transitions)
- State management (visible binding, state persistence)
Dialog组件支持:
- 基于模板的布局(页眉、内容页、页脚可自定义HTML/组件)
- 多种交互模式(模态和非模态)
- 丰富的事件系统(生命周期、拖拽、调整大小、覆盖层交互)
- 高级定位(固定、绝对、相对、居中)
- 交互式功能(可拖拽、可调整大小、最小化/最大化按钮、全屏模式)
- 无障碍访问支持(符合WCAG标准、键盘导航、ARIA属性)
- 动画效果(打开/关闭过渡动画)
- 状态管理(可见性绑定、状态持久化)
Documentation and Navigation Guide
文档与导航指南
Getting Started
快速入门
📄 Read: references/getting-started.md
- Installation and NuGet package setup
- Blazor WebAssembly and Server project configuration
- Adding namespaces and Syncfusion services
- Basic dialog implementation
- CSS imports and theme configuration
- Displaying header, content, and setting visibility
📄 阅读: references/getting-started.md
- 安装与NuGet包配置
- Blazor WebAssembly和Server项目配置
- 添加命名空间和Syncfusion服务
- 基础对话框实现
- CSS导入和主题配置
- 显示页眉、内容并设置可见性
Templates and Content Customization
模板与内容自定义
📄 Read: references/templates.md
- Header template with custom HTML and icons
- Content template with forms and Blazor components
- Footer template and custom buttons
- DialogTemplates structure
- Embedding complex UI elements in dialogs
📄 阅读: references/templates.md
- 包含自定义HTML和图标的页眉模板
- 包含表单和Blazor组件的内容模板
- 页脚模板和自定义按钮
- DialogTemplates结构
- 在对话框中嵌入复杂UI元素
Dialog Buttons
对话框按钮
📄 Read: references/dialog-buttons.md
- DialogButton component configuration
- Button placement and click handlers
- Using DialogButtons vs FooterTemplate
- Standard button patterns and common use cases
📄 阅读: references/dialog-buttons.md
- DialogButton组件配置
- 按钮布局和点击处理程序
- DialogButtons与FooterTemplate的对比使用
- 标准按钮模式和常见用例
Events and Interactions
事件与交互
📄 Read: references/events.md
- Lifecycle events (Created, Destroyed)
- Opening and closing events (OnOpen, Opened, OnClose, Closed)
- Drag events (OnDragStart, OnDrag, OnDragStop)
- Resize events (OnResizeStart, Resizing, OnResizeStop)
- Modal overlay interactions (OnOverlayModalClick)
📄 阅读: references/events.md
- 生命周期事件(Created、Destroyed)
- 打开和关闭事件(OnOpen、Opened、OnClose、Closed)
- 拖拽事件(OnDragStart、OnDrag、OnDragStop)
- 调整大小事件(OnResizeStart、Resizing、OnResizeStop)
- 模态覆盖层交互(OnOverlayModalClick)
Positioning and Visibility
定位与可见性
📄 Read: references/positioning-visibility.md
- Position property (fixed, absolute, relative)
- Visible binding for show/hide control
- Target element configuration
- Dialog centering on page
- Width and height configuration
- Z-index management
📄 阅读: references/positioning-visibility.md
- Position属性(fixed、absolute、relative)
- 用于显示/隐藏控制的可见性绑定
- 目标元素配置
- 对话框页面居中
- 宽度和高度配置
- Z-index管理
Dialog Behavior and Features
对话框行为与功能
📄 Read: references/dialog-behavior.md
- Modal vs modeless dialogs
- AllowDragging and EnableResize properties
- AllowPrerender for performance optimization
- ShowCloseIcon configuration
- Creating nested dialogs
- Animation support
- IsModal and overlay behavior
📄 阅读: references/dialog-behavior.md
- 模态与非模态对话框
- AllowDragging和EnableResize属性
- 用于性能优化的AllowPrerender
- ShowCloseIcon配置
- 创建嵌套对话框
- 动画支持
- IsModal和覆盖层行为
Methods and Programmatic Control
方法与程序化控制
📄 Read: references/methods.md
- ShowAsync() to open dialogs programmatically
- ShowAsync(true) to open dialogs in fullscreen mode
- HideAsync() to close dialogs programmatically
- GetDimension() to retrieve dialog size
- GetButton(index) and GetButtonItems() for button access
- RefreshPositionAsync() for position recalculation
- Complete control examples
📄 阅读: references/methods.md
- ShowAsync():以编程方式打开对话框
- ShowAsync(true):以全屏模式打开对话框
- HideAsync():以编程方式关闭对话框
- GetDimension():获取对话框尺寸
- GetButton(index)和GetButtonItems():访问按钮
- RefreshPositionAsync():重新计算位置
- 完整控制示例
Advanced Customization and Styling
高级自定义与样式
📄 Read: references/advanced-customization.md
- CSS class customization and styling
- Appearance customization
- Accessibility features (WCAG compliance, keyboard navigation)
- Animation configurations
- State persistence strategies with EnablePersistence
- Minimize/Maximize button implementation
- Localization support
- Responsive dialog design
📄 阅读: references/advanced-customization.md
- CSS类自定义和样式设置
- 外观自定义
- 无障碍功能(WCAG合规、键盘导航)
- 动画配置
- 启用EnablePersistence的状态持久化策略
- 最小化/最大化按钮实现
- 本地化支持
- 响应式对话框设计
Quick Start
快速入门
Basic Dialog
基础对话框
csharp
@using Syncfusion.Blazor.Popups
<SfDialog Width="300px" Header="Welcome">
<DialogTemplates>
<Content>This is a basic dialog with content.</Content>
</DialogTemplates>
</SfDialog>csharp
@using Syncfusion.Blazor.Popups
<SfDialog Width="300px" Header="Welcome">
<DialogTemplates>
<Content>This is a basic dialog with content.</Content>
</DialogTemplates>
</SfDialog>Dialog with Show/Hide Control
带显示/隐藏控制的对话框
csharp
@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;
}
}csharp
@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;
}
}Common Patterns
常见模式
Alert Dialog
警报对话框
csharp
<SfDialog Width="350px" IsModal="true" Header="Alert">
<DialogTemplates>
<Content>This action cannot be undone.</Content>
</DialogTemplates>
</SfDialog>csharp
<SfDialog Width="350px" IsModal="true" Header="Alert">
<DialogTemplates>
<Content>This action cannot be undone.</Content>
</DialogTemplates>
</SfDialog>Form Dialog
表单对话框
csharp
<SfDialog Width="400px" Header="User Information">
<DialogTemplates>
<Content>
<div class="form-group">
<input type="text" placeholder="Enter name" />
</div>
</Content>
</DialogTemplates>
</SfDialog>csharp
<SfDialog Width="400px" Header="User Information">
<DialogTemplates>
<Content>
<div class="form-group">
<input type="text" placeholder="Enter name" />
</div>
</Content>
</DialogTemplates>
</SfDialog>Draggable and Resizable Dialog
可拖拽和调整大小的对话框
csharp
<SfDialog Width="400px" Header="Features" AllowDragging="true" EnableResize="true">
<DialogTemplates>
<Content>You can drag and resize this dialog.</Content>
</DialogTemplates>
</SfDialog>csharp
<SfDialog Width="400px" Header="Features" AllowDragging="true" EnableResize="true">
<DialogTemplates>
<Content>You can drag and resize this dialog.</Content>
</DialogTemplates>
</SfDialog>Fullscreen Dialog
全屏对话框
csharp
@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();
}
}csharp
@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();
}
}Key Properties
关键属性
| Property | Type | Purpose |
|---|---|---|
| string | Sets dialog width (e.g., "400px", "50%"). Default: "100%" |
| string | Sets dialog height (e.g., "300px", "70%"). Default: "auto" |
| string | Sets dialog header text |
| string | Sets dialog content text |
| bool | Controls dialog visibility. Supports @bind-Visible. Default: true |
| bool | Makes dialog modal (overlay blocking interaction). Default: false |
| bool | Shows close button in header. Default: false |
| bool | Enables dialog dragging by header. Default: false |
| bool | Enables dialog resizing. Default: false |
| bool | Closes dialog when Escape key is pressed. Default: true |
| DialogAnimationSettings | Configures open/close animations (effect, duration, delay). Default: Fade effect, 400ms |
| string | Positioning mode: "fixed" (stays on screen), "absolute" (relative to target), or "relative" (document flow). Default: "fixed" |
| string | X-coordinate position (e.g., "100px", "20%"). Works with Position property. Default: "auto" |
| string | Y-coordinate position (e.g., "50px", "10%"). Works with Position property. Default: "auto" |
| string | Unique identifier for the dialog. Required when EnablePersistence="true" |
| string | Sets minimum height constraint for resize (e.g., "150px"). Default: null |
| string | Sets maximum height constraint for resize (e.g., "600px"). Default: null |
| ResizeDirection[] | Array of resize directions (e.g., SouthEast, NorthEast). Default: [SouthEast] |
| List<DialogButtonModel> | Programmatic button configuration (alternative to DialogButtons component) |
| string | Custom CSS class(es) for styling |
| bool | Enables right-to-left layout support. Default: false |
| bool | Persists position, width, height to browser local storage. Default: false. Requires ID property |
| string | CSS selector for dialog target/container element (e.g., "#container", ".target-div") |
| RenderFragment | Custom footer content (alternative to DialogButtons component) |
| bool | Keeps DOM elements when hidden for faster re-display. Default: false |
| double | Sets stacking order relative to other elements. Default: 1000 |
| 属性 | 类型 | 用途 |
|---|---|---|
| string | 设置对话框宽度(例如:"400px"、"50%")。默认值:"100%" |
| string | 设置对话框高度(例如:"300px"、"70%")。默认值:"auto" |
| string | 设置对话框页眉文本 |
| string | 设置对话框内容文本 |
| bool | 控制对话框可见性,支持@bind-Visible。默认值:true |
| bool | 将对话框设置为模态(覆盖层阻止交互)。默认值:false |
| bool | 在页眉显示关闭按钮。默认值:false |
| bool | 允许通过页眉拖拽对话框。默认值:false |
| bool | 允许调整对话框大小。默认值:false |
| bool | 按下Escape键时关闭对话框。默认值:true |
| DialogAnimationSettings | 配置打开/关闭动画(效果、时长、延迟)。默认值:淡入淡出效果,400ms |
| string | 定位模式:"fixed"(固定在屏幕)、"absolute"(相对于目标)或"relative"(文档流)。默认值:"fixed" |
| string | X坐标位置(例如:"100px"、"20%"),需配合Position属性使用。默认值:"auto" |
| string | Y坐标位置(例如:"50px"、"10%"),需配合Position属性使用。默认值:"auto" |
| string | 对话框的唯一标识符,当EnablePersistence="true"时必填 |
| string | 设置调整大小时的最小高度限制(例如:"150px")。默认值:null |
| string | 设置调整大小时的最大高度限制(例如:"600px")。默认值:null |
| ResizeDirection[] | 调整大小的方向数组(例如:SouthEast、NorthEast)。默认值:[SouthEast] |
| List<DialogButtonModel> | 程序化按钮配置(DialogButtons组件的替代方案) |
| string | 用于样式设置的自定义CSS类 |
| bool | 启用从右到左布局支持。默认值:false |
| bool | 将位置、宽度、高度持久化到浏览器本地存储。默认值:false,需设置ID属性 |
| string | 对话框目标/容器元素的CSS选择器(例如:"#container"、".target-div") |
| RenderFragment | 自定义页脚内容(DialogButtons组件的替代方案) |
| bool | 隐藏时保留DOM元素以加快重新显示速度。默认值:false |
| double | 设置相对于其他元素的堆叠顺序。默认值:1000 |
Key Enums and Types
关键枚举与类型
DialogEffect Enum
DialogEffect枚举
Animation effects for dialog open/close transitions:
| Value | Description |
|---|---|
| No animation |
| Fade in/out effect (default) |
| Zoom in/out from center |
| Slide from/to left |
| Slide from/to right |
| Slide from/to top |
| Slide from/to bottom |
| Horizontal flip effect |
| Vertical flip effect |
对话框打开/关闭过渡的动画效果:
| 值 | 描述 |
|---|---|
| 无动画 |
| 淡入淡出效果(默认) |
| 从中心缩放 |
| 从左侧滑入/滑出 |
| 从右侧滑入/滑出 |
| 从顶部滑入/滑出 |
| 从底部滑入/滑出 |
| 水平翻转效果 |
| 垂直翻转效果 |
ResizeDirection Enum
ResizeDirection枚举
Directions from which the dialog can be resized:
| Value | Description |
|---|---|
| Bottom edge |
| Top edge |
| Right edge |
| Left edge |
| Bottom-right corner (default) |
| Bottom-left corner |
| Top-right corner |
| Top-left corner |
| All directions |
对话框可调整大小的方向:
| 值 | 描述 |
|---|---|
| 底部边缘 |
| 顶部边缘 |
| 右侧边缘 |
| 左侧边缘 |
| 右下角(默认) |
| 左下角 |
| 右上角 |
| 左上角 |
| 所有方向 |
ButtonType Enum
ButtonType枚举
HTML button type attribute for dialog buttons:
| Value | Description |
|---|---|
| Standard button (default) |
| Form submission button |
| Form reset button |
对话框按钮的HTML button类型属性:
| 值 | 描述 |
|---|---|
| 标准按钮(默认) |
| 表单提交按钮 |
| 表单重置按钮 |
DialogAnimationSettings Class
DialogAnimationSettings类
Configuration for dialog animations:
| Property | Type | Description | Default |
|---|---|---|---|
| DialogEffect | Animation effect | DialogEffect.Fade |
| int | Animation duration (milliseconds) | 400 |
| int | Animation delay (milliseconds) | 0 |
- Use for fullscreen dialogs when you need maximum focus and screen real estate
ShowAsync(true) - Set initially when using programmatic control with ShowAsync() Example:
Visible="false"
csharp
var animSettings = new DialogAnimationOptions
{
Effect = DialogEffect.Zoom,
Duration = 300,
Delay = 0
};对话框动画配置:
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| DialogEffect | 动画效果 | DialogEffect.Fade |
| int | 动画时长(毫秒) | 400 |
| int | 动画延迟(毫秒) | 0 |
- 当需要最大焦点和屏幕空间时,使用打开全屏对话框
ShowAsync(true) - 当使用ShowAsync()进行程序化控制时,初始设置示例:
Visible="false"
csharp
var animSettings = new DialogAnimationOptions
{
Effect = DialogEffect.Zoom,
Duration = 300,
Delay = 0
};DialogDimension Class
DialogDimension类
Returned by method:
GetDimension()| Property | Type | Description |
|---|---|---|
| string | Current dialog width |
| string | Current dialog height |
GetDimension()| 属性 | 类型 | 描述 |
|---|---|---|
| string | 当前对话框宽度 |
| string | 当前对话框高度 |
Important Constraints and Notes
重要约束与注意事项
⚠️ Critical Requirements:
- ID Property: Must be set when using . The ID serves as the localStorage key.
EnablePersistence="true" - Mutual Exclusivity: and
FooterTemplatecannot be used together. Choose one approach.DialogButtons - Target Selector: The property must reference a valid CSS selector for existing DOM elements.
Target - Resize Dependency: only works when
ResizeHandles.EnableResize="true" - Position Context: The property affects how
PositionandLeftcoordinates are interpreted.Top
📋 Best Practices:
- Use for critical actions requiring user attention
IsModal="true" - Set for frequently toggled dialogs to improve performance
AllowPrerender="true" - Always provide a close mechanism (button, close icon, or Escape key)
- Use values in increments (1000, 1001, 1002) for nested dialogs
ZIndex - Test responsive behavior with percentage-based Width/Height values
⚠️ 关键要求:
- ID属性:当使用时必须设置,ID作为localStorage的键。
EnablePersistence="true" - 互斥性:和
FooterTemplate不能同时使用,需选择其中一种方式。DialogButtons - 目标选择器:属性必须引用现有DOM元素的有效CSS选择器。
Target - 调整大小依赖:仅在
ResizeHandles时生效。EnableResize="true" - 定位上下文:属性会影响
Position和Left坐标的解释方式。Top
📋 最佳实践:
- 对于需要用户关注的关键操作,使用
IsModal="true" - 对于频繁切换的对话框,设置以提升性能
AllowPrerender="true" - 始终提供关闭机制(按钮、关闭图标或Escape键)
- 嵌套对话框使用递增的ZIndex值(1000、1001、1002)
- 使用百分比宽度/高度测试响应式行为
Related Skills
相关技能
- implementing-buttons - For dialog button styling and behavior
- implementing-dropdown-list - For select controls within dialogs
- implementing-text-inputs - For form fields in dialogs
- implementing-buttons - 用于对话框按钮样式和行为
- implementing-dropdown-list - 用于对话框内的选择控件
- implementing-text-inputs - 用于对话框内的表单字段
See Also
另请参阅
Tooltips
提示框
The Syncfusion Blazor Tooltip component provides contextual information by displaying messages when users interact with target elements through hovering, clicking, or focusing. It supports rich content, flexible positioning, multiple trigger modes, and comprehensive customization options.
Syncfusion Blazor Tooltip组件通过悬停、点击或聚焦交互,为目标元素显示上下文信息。它支持丰富的内容、灵活的定位、多种触发模式以及全面的自定义选项。
Component Overview
组件概述
The Blazor Tooltip component offers:
- Multiple content types: Simple text, HTML title attributes, templates, RenderFragment, and MarkupString
- Flexible positioning: 12 static positions (TopLeft, TopCenter, TopRight, BottomLeft, etc.), mouse trailing, and custom offsets
- Open mode options: Hover, Click, Focus, Auto, Custom, and combinations
- Sticky mode: Keep tooltips open with a close button
- Customization: Full CSS control over wrapper, content, and tip pointer
- Dynamic targets: Support for elements added after component initialization
- Accessibility: WCAG 2.2 compliance with ARIA attributes and keyboard support
- Collision handling: Automatic repositioning when tooltips hit viewport boundaries
Blazor Tooltip组件提供:
- 多种内容类型:纯文本、HTML标题属性、模板、RenderFragment和MarkupString
- 灵活的定位:12种静态位置(TopLeft、TopCenter、TopRight、BottomLeft等)、鼠标跟随和自定义偏移
- 打开模式选项:悬停、点击、聚焦、自动、自定义及组合模式
- 粘性模式:通过关闭按钮保持提示框打开
- 自定义:对包装器、内容和提示指针的完整CSS控制
- 动态目标:支持组件初始化后添加的元素
- 无障碍访问:符合WCAG 2.2标准,支持ARIA属性和键盘操作
- 碰撞处理:当提示框触及视口边界时自动重新定位
Documentation and Navigation Guide
文档与导航指南
Getting Started
快速入门
📄 Read: references/getting-started.md
- Prerequisites and system requirements
- Package installation (Syncfusion.Blazor.Popups and Themes)
- Namespace imports and service registration
- Stylesheet and script resource setup
- Basic Tooltip implementation with Button
- WebAssembly App configuration
- Web App setup (Server, Client, Auto render modes)
- Interactive render mode configuration
- First Tooltip example
📄 阅读: references/getting-started.md
- 先决条件和系统要求
- 包安装(Syncfusion.Blazor.Popups和Themes)
- 命名空间导入和服务注册
- 样式表和脚本资源设置
- 带Button的基础Tooltip实现
- WebAssembly应用配置
- Web应用设置(Server、Client、Auto渲染模式)
- 交互式渲染模式配置
- 第一个Tooltip示例
Content Management
内容管理
📄 Read: references/content.md
- Simple text content using Content property
- Using HTML title attribute as tooltip content
- ContentTemplate for custom HTML layouts
- Dynamic content with RenderFragment
- Rendering HTML strings with MarkupString
- Interactive elements inside tooltips
- Images, formatted text, and links in tooltip content
- Complex tooltip layouts with multiple sections
📄 阅读: references/content.md
- 使用Content属性设置纯文本内容
- 使用HTML标题属性作为提示框内容
- 使用ContentTemplate自定义HTML布局
- 使用RenderFragment实现动态内容
- 使用MarkupString渲染HTML字符串
- 提示框内的交互式元素
- 提示框内容中的图片、格式化文本和链接
- 包含多个部分的复杂提示框布局
Positioning and Placement
定位与布局
📄 Read: references/positioning.md
- Position property with 12 static options (TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, BottomRight, LeftTop, LeftCenter, LeftBottom, RightTop, RightCenter, RightBottom)
- Mouse trailing behavior (MouseTrail property)
- Offset configuration (OffsetX and OffsetY)
- Collision detection and automatic repositioning
- WindowCollision for viewport boundary handling
- Combining positions with offsets
- Best practices for position selection
📄 阅读: references/positioning.md
- Position属性包含12种静态选项(TopLeft、TopCenter、TopRight、BottomLeft、BottomCenter、BottomRight、LeftTop、LeftCenter、LeftBottom、RightTop、RightCenter、RightBottom)
- 鼠标跟随行为(MouseTrail属性)
- 偏移配置(OffsetX和OffsetY)
- 碰撞检测和自动重新定位
- WindowCollision用于视口边界处理
- 位置与偏移的组合使用
- 位置选择的最佳实践
Open Modes and Triggers
打开模式与触发
📄 Read: references/open-modes.md
- OpensOn property values (Auto, Hover, Click, Focus, Custom)
- Desktop vs mobile behavior differences
- Multiple trigger combinations (e.g., "Hover Click")
- Sticky mode (IsSticky) with close button
- Open and close delays (OpenDelay, CloseDelay)
- Custom trigger implementation with public methods
- Mobile tap and hold behavior
- Best practices for trigger selection
📄 阅读: references/open-modes.md
- OpensOn属性值(Auto、Hover、Click、Focus、Custom)
- 桌面与移动端行为差异
- 多种触发组合(例如:"Hover Click")
- 带关闭按钮的粘性模式(IsSticky)
- 打开和关闭延迟(OpenDelay、CloseDelay)
- 使用公共方法实现自定义触发
- 移动端点击并按住的行为
- 触发选择的最佳实践
Customization and Styling
自定义与样式
📄 Read: references/customization-and-styling.md
- CssClass property for custom styles
- Tip pointer customization (size, colors, shape)
- Tooltip wrapper and popup styling
- Content styling (font, color, padding)
- Arrow tip styling for all 4 directions
- Inner and outer tip CSS structure
- Complete CSS class reference
- Theme integration examples
📄 阅读: references/customization-and-styling.md
- 使用CssClass属性设置自定义样式
- 提示指针自定义(大小、颜色、形状)
- 提示框包装器和弹窗样式
- 内容样式(字体、颜色、内边距)
- 四个方向的箭头提示样式
- 内部和外部提示的CSS结构
- 完整CSS类参考
- 主题集成示例
Dimensions and Sizing
尺寸与大小
📄 Read: references/dimensions.md
- Width and Height properties
- Auto vs fixed sizing strategies
- Scroll mode for content overflow
- Combining Height with IsSticky for scrollable tooltips
- Responsive sizing considerations
- Content overflow handling
📄 阅读: references/dimensions.md
- Width和Height属性
- 自动与固定大小策略
- 内容溢出的滚动模式
- Height与IsSticky结合实现可滚动提示框
- 响应式大小注意事项
- 内容溢出处理
Target Configuration
目标配置
📄 Read: references/target-configuration.md
- Target property with CSS selectors
- Single vs multiple target elements
- Dynamic target elements added after render
- TargetContainer for automatic registration
- GUID ID limitations (cannot start with digit)
- Best practices for target selection
- Examples with buttons, links, inputs, and custom elements
📄 阅读: references/target-configuration.md
- 使用CSS选择器的Target属性
- 单个与多个目标元素
- 渲染后添加的动态目标元素
- 用于自动注册的TargetContainer
- GUID ID限制(不能以数字开头)
- 目标选择的最佳实践
- 按钮、链接、输入框和自定义元素的示例
Accessibility
无障碍访问
📄 Read: references/accessibility.md
- WCAG 2.2 and Section 508 compliance
- ARIA attributes (role="tooltip", aria-describedby, aria-hidden)
- Keyboard navigation (Tab for focus, Escape to close)
- Screen reader support
- Right-to-Left (RTL) language support
- Color contrast requirements
- Mobile device accessibility
- Axe-core validation
- Best practices for accessible tooltips
📄 阅读: references/accessibility.md
- 符合WCAG 2.2和Section 508标准
- ARIA属性(role="tooltip"、aria-describedby、aria-hidden)
- 键盘导航(Tab聚焦、Escape关闭)
- 屏幕阅读器支持
- 从右到左(RTL)语言支持
- 颜色对比度要求
- 移动设备无障碍访问
- Axe-core验证
- 无障碍提示框的最佳实践
Quick Start Example
快速入门示例
Basic Tooltip with Button
带Button的基础提示框
razor
@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!";
}razor
@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!";
}Tooltip with Custom Position
自定义位置的提示框
razor
@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons
<SfTooltip Target="#saveBtn" Content="Save changes" Position="Position.RightCenter">
<SfButton ID="saveBtn" Content="Save"></SfButton>
</SfTooltip>razor
@using Syncfusion.Blazor.Popups
@using Syncfusion.Blazor.Buttons
<SfTooltip Target="#saveBtn" Content="Save changes" Position="Position.RightCenter">
<SfButton ID="saveBtn" Content="Save"></SfButton>
</SfTooltip>Multiple Tooltips Using Class Selector
使用类选择器的多个提示框
razor
@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>razor
@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>Common Patterns
常见模式
Sticky Tooltip with Click Trigger
点击触发的粘性提示框
razor
<SfTooltip Target="#helpBtn" Content="Need help? Contact support at help@example.com"
OpensOn="Click" IsSticky="true">
<SfButton ID="helpBtn" Content="Help" IconCss="e-icons e-help"></SfButton>
</SfTooltip>razor
<SfTooltip Target="#helpBtn" Content="Need help? Contact support at help@example.com"
OpensOn="Click" IsSticky="true">
<SfButton ID="helpBtn" Content="Help" IconCss="e-icons e-help"></SfButton>
</SfTooltip>Tooltip with HTML Template
带HTML模板的提示框
razor
<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> john@example.com</p>
<p><strong>Status:</strong> Active</p>
</div>
</ContentTemplate>
<ChildContent>
<SfButton ID="infoBtn" Content="Info" IsPrimary="true"></SfButton>
</ChildContent>
</SfTooltip>razor
<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> john@example.com</p>
<p><strong>Status:</strong> Active</p>
</div>
</ContentTemplate>
<ChildContent>
<SfButton ID="infoBtn" Content="Info" IsPrimary="true"></SfButton>
</ChildContent>
</SfTooltip>Tooltip with Mouse Trailing
鼠标跟随的提示框
razor
<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>razor
<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>Custom Styled Tooltip
自定义样式的提示框
razor
<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>razor
<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>Dynamic Targets with TargetContainer
使用TargetContainer的动态目标
razor
<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;
}razor
<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;
}Key Properties
关键属性
Essential Properties
核心属性
| Property | Type | Default | Description |
|---|---|---|---|
| Content | string | null | Text content to display in tooltip |
| Target | string | null | CSS selector for target elements |
| Position | Position | TopCenter | Tooltip placement position |
| OpensOn | string | "Auto" | Trigger mode (Auto, Hover, Click, Focus, Custom) |
| IsSticky | bool | false | Keep tooltip open with close button |
| Animation | AnimationModel | null | Animation settings for open/close transitions |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| Content | string | null | 提示框中显示的文本内容 |
| Target | string | null | 目标元素的CSS选择器 |
| Position | Position | TopCenter | 提示框的布局位置 |
| OpensOn | string | "Auto" | 触发模式(Auto、Hover、Click、Focus、Custom) |
| IsSticky | bool | false | 通过关闭按钮保持提示框打开 |
| Animation | AnimationModel | null | 打开/关闭过渡的动画设置 |
Content Properties
内容属性
| Property | Type | Description |
|---|---|---|
| ContentTemplate | RenderFragment | Custom HTML content template. Default: null |
| Content | string | Simple text or HTML string content. Default: null |
| ChildContent | RenderFragment | Wraps the target element(s) within the tooltip component. Default: null |
| 属性 | 类型 | 描述 |
|---|---|---|
| ContentTemplate | RenderFragment | 自定义HTML内容模板。默认值:null |
| Content | string | 纯文本或HTML字符串内容。默认值:null |
| ChildContent | RenderFragment | 将目标元素包裹在提示框组件内。默认值:null |
Positioning Properties
定位属性
| Property | Type | Default | Description |
|---|---|---|---|
| Position | Position | TopCenter | Static position around target |
| MouseTrail | bool | false | Follow mouse pointer |
| OffsetX | double | 0 | Horizontal offset in pixels |
| OffsetY | double | 0 | Vertical offset in pixels |
| WindowCollision | bool | false | Use viewport for collision detection instead of parent element |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| Position | Position | TopCenter | 目标元素周围的静态位置 |
| MouseTrail | bool | false | 跟随鼠标指针 |
| OffsetX | double | 0 | 水平偏移(像素) |
| OffsetY | double | 0 | 垂直偏移(像素) |
| WindowCollision | bool | false | 使用视口而非父元素进行碰撞检测 |
Timing Properties
时序属性
| Property | Type | Default | Description |
|---|---|---|---|
| OpenDelay | double | 0 | Delay before opening (milliseconds) |
| CloseDelay | double | 0 | Delay before closing (milliseconds) |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| OpenDelay | double | 0 | 打开前的延迟(毫秒) |
| CloseDelay | double | 0 | 关闭前的延迟(毫秒) |
Event Callbacks
事件回调
| Event | Type | Description |
|---|---|---|
| Created | EventCallback<object> | Raised after tooltip component is created |
| Destroyed | EventCallback<object> | Raised when tooltip component is destroyed |
| OnOpen | EventCallback<TooltipEventArgs> | Raised before tooltip is displayed (cancelable) |
| Opened | EventCallback<TooltipEventArgs> | Raised after tooltip is opened |
| OnClose | EventCallback<TooltipEventArgs> | Raised before tooltip hides (cancelable) |
| Closed | EventCallback<TooltipEventArgs> | Raised after tooltip is closed |
| OnRender | EventCallback<TooltipEventArgs> | Raised before tooltip is added to DOM (cancelable) |
| OnCollision | EventCallback<TooltipEventArgs> | Raised during collision detection calculations |
| 事件 | 类型 | 描述 |
|---|---|---|
| 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> | 碰撞检测计算期间触发 |
Public Methods
公共方法
| Method | Return Type | Description |
|---|---|---|
| OpenAsync(ElementReference?, TooltipAnimationSettings) | Task | Opens tooltip programmatically with optional target and animation settings |
| CloseAsync(TooltipAnimationSettings) | Task | Closes tooltip programmatically with optional animation settings |
| RefreshAsync() | Task | Refreshes tooltip to sync with dynamic DOM changes and target updates |
| RefreshPositionAsync(ElementReference?) | Task | Recalculates and updates tooltip position based on current target location |
| 方法 | 返回类型 | 描述 |
|---|---|---|
| OpenAsync(ElementReference?, TooltipAnimationSettings) | Task | 以编程方式打开提示框,可指定目标和动画设置 |
| CloseAsync(TooltipAnimationSettings) | Task | 以编程方式关闭提示框,可指定动画设置 |
| RefreshAsync() | Task | 刷新提示框以同步动态DOM变化和目标更新 |
| RefreshPositionAsync(ElementReference?) | Task | 根据当前目标位置重新计算并更新提示框位置 |
Appearance Properties
外观属性
| Property | Type | Description |
|---|---|---|
| CssClass | string | Custom CSS class for styling. Default: null |
| Width | string | Tooltip width (auto or pixels). Default: "auto" |
| Height | string | Tooltip height (auto or pixels). Default: "auto" |
| ShowTipPointer | bool | Show/hide arrow pointer. Default: true |
| TipPointerPosition | TipPointerPosition | Position of tip pointer (Auto, Start, Middle, End). Default: Auto |
| EnableRtl | bool | Enable right-to-left direction. Default: false |
| HtmlAttributes | Dictionary<string, object> | Additional HTML attributes for tooltip element. Default: null |
| ID | string | Unique identifier for the tooltip component. Default: auto-generated |
| 属性 | 类型 | 描述 |
|---|---|---|
| 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 Properties
目标属性
| Property | Type | Description |
|---|---|---|
| Target | string | CSS selector for target elements. Default: null |
| Container | string | Container element where tooltip popup is appended. Default: "body" |
| TargetContainer | string | Container selector for dynamic target registration. Default: null |
| 属性 | 类型 | 描述 |
|---|---|---|
| Target | string | 目标元素的CSS选择器。默认值:null |
| Container | string | 提示框弹窗附加到的容器元素。默认值:"body" |
| TargetContainer | string | 用于动态目标注册的容器选择器。默认值:null |
Key Types and Classes
关键类型与类
AnimationModel Class
AnimationModel类
Configuration for tooltip open and close animations:
| Property | Type | Description |
|---|---|---|
| Open | TooltipAnimationSettings | Animation settings for opening tooltip |
| Close | TooltipAnimationSettings | Animation settings for closing tooltip |
提示框打开和关闭动画的配置:
| 属性 | 类型 | 描述 |
|---|---|---|
| Open | TooltipAnimationSettings | 提示框打开的动画设置 |
| Close | TooltipAnimationSettings | 提示框关闭的动画设置 |
TooltipAnimationSettings Class
TooltipAnimationSettings类
Detailed animation configuration:
| Property | Type | Default | Description |
|---|---|---|---|
| Effect | Effect | Fade | Animation effect (FadeIn, FadeOut, ZoomIn, ZoomOut, None) |
| Duration | int | 150 | Animation duration in milliseconds |
| Delay | int | 0 | Animation delay in milliseconds |
详细的动画配置:
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| Effect | Effect | Fade | 动画效果(FadeIn、FadeOut、ZoomIn、ZoomOut、None) |
| Duration | int | 150 | 动画时长(毫秒) |
| Delay | int | 0 | 动画延迟(毫秒) |
Effect Enum
Effect枚举
Animation effects for tooltip transitions:
| Value | Description |
|---|---|
| None | No animation |
| FadeIn | Fade in effect for opening |
| FadeOut | Fade out effect for closing |
| ZoomIn | Zoom in effect for opening |
| ZoomOut | Zoom out effect for closing |
提示框过渡的动画效果:
| 值 | 描述 |
|---|---|
| None | 无动画 |
| FadeIn | 打开时淡入效果 |
| FadeOut | 关闭时淡出效果 |
| ZoomIn | 打开时放大效果 |
| ZoomOut | 关闭时缩小效果 |
Position Enum
Position枚举
Tooltip placement positions:
| Value | Description |
|---|---|
| TopLeft | Above target, aligned to left edge |
| TopCenter | Above target, centered (default) |
| TopRight | Above target, aligned to right edge |
| BottomLeft | Below target, aligned to left edge |
| BottomCenter | Below target, centered |
| BottomRight | Below target, aligned to right edge |
| LeftTop | Left of target, aligned to top edge |
| LeftCenter | Left of target, centered vertically |
| LeftBottom | Left of target, aligned to bottom edge |
| RightTop | Right of target, aligned to top edge |
| RightCenter | Right of target, centered vertically |
| RightBottom | Right of target, aligned to bottom edge |
提示框的布局位置:
| 值 | 描述 |
|---|---|
| TopLeft | 目标上方,左对齐 |
| TopCenter | 目标上方,居中(默认) |
| TopRight | 目标上方,右对齐 |
| BottomLeft | 目标下方,左对齐 |
| BottomCenter | 目标下方,居中 |
| BottomRight | 目标下方,右对齐 |
| LeftTop | 目标左侧,顶部对齐 |
| LeftCenter | 目标左侧,垂直居中 |
| LeftBottom | 目标左侧,底部对齐 |
| RightTop | 目标右侧,顶部对齐 |
| RightCenter | 目标右侧,垂直居中 |
| RightBottom | 目标右侧,底部对齐 |
TipPointerPosition Enum
TipPointerPosition枚举
Arrow pointer placement on tooltip:
| Value | Description |
|---|---|
| Auto | Automatically adjusts pointer position (default) |
| Start | Pointer at start of tooltip edge |
| Middle | Pointer at middle of tooltip edge |
| End | Pointer at end of tooltip edge |
提示框箭头指针的位置:
| 值 | 描述 |
|---|---|
| Auto | 自动调整指针位置(默认) |
| Start | 指针位于提示框边缘的起始处 |
| Middle | 指针位于提示框边缘的中间 |
| End | 指针位于提示框边缘的末端 |
Common Use Cases
常见用例
Form Field Help Text
表单字段帮助文本
Provide contextual help for form inputs:
- Read references/getting-started.md for basic setup
- Read references/open-modes.md for Focus trigger
- Use to show tooltip when input receives focus
OpensOn="Focus" - Position tooltip to avoid covering the input field
为表单输入提供上下文帮助:
- 阅读references/getting-started.md了解基础设置
- 阅读references/open-modes.md了解Focus触发模式
- 使用在输入框获得焦点时显示提示框
OpensOn="Focus" - 调整提示框位置以避免遮挡输入字段
Icon Button Descriptions
图标按钮说明
Add descriptive text to icon-only buttons:
- Use simple property for short descriptions
Content - Set for immediate feedback
OpensOn="Hover" - Consider or
Position.TopCenterfor consistencyPosition.BottomCenter
为纯图标按钮添加描述性文本:
- 使用简单的属性设置简短描述
Content - 设置以获得即时反馈
OpensOn="Hover" - 考虑使用或
Position.TopCenter保持一致性Position.BottomCenter
Rich Content Cards
富内容卡片
Display detailed information on hover:
- Read references/content.md for template options
- Use with formatted HTML
ContentTemplate - Include images, links, and formatted text
- Consider and
OpensOn="Click"for complex contentIsSticky="true"
悬停时显示详细信息:
- 阅读references/content.md了解模板选项
- 使用添加格式化HTML
ContentTemplate - 包含图片、链接和格式化文本
- 对于复杂内容,考虑使用和
OpensOn="Click"IsSticky="true"
Status Indicators
状态指示器
Show status details on hover:
- Use color-coded tooltips with
CssClass - Read references/customization-and-styling.md for styling
- Keep content concise and scannable
悬停时显示状态详情:
- 使用设置颜色编码的提示框
CssClass - 阅读references/customization-and-styling.md了解样式设置
- 保持内容简洁易读
Dynamic Dashboard Elements
动态仪表板元素
Add tooltips to dynamically added widgets:
- Read references/target-configuration.md for dynamic setup
- Use to handle elements added after initialization
TargetContainer - Use data attributes for tooltip content
为动态添加的小部件添加提示框:
- 阅读references/target-configuration.md了解动态设置
- 使用处理初始化后添加的元素
TargetContainer - 使用数据属性设置提示框内容
Accessibility Enhancements
无障碍访问增强
Ensure tooltips are accessible:
- Read references/accessibility.md for compliance
- Use semantic HTML in templates
- Ensure keyboard navigation works
- Test with screen readers
- Maintain color contrast ratios
确保提示框可访问:
- 阅读references/accessibility.md了解合规要求
- 在模板中使用语义化HTML
- 确保键盘导航正常工作
- 使用屏幕阅读器测试
- 保持颜色对比度比例
Predefined Dialog
预定义对话框
Component Overview
组件概述
The Syncfusion Blazor Predefined Dialogs use a service-based architecture with two key components:
- SfDialogService - Registered service for opening dialogs programmatically
- SfDialogProvider - Component added to layout to enable dialog rendering
Key Features:
- Three dialog types: Alert, Confirm, Prompt
- Service-based invocation from anywhere in the app
- Customizable positioning, dimensions, and animations
- Draggable dialog support
- Button customization with icons
- Custom content rendering
- Built-in accessibility support
Package:
Namespace:
Syncfusion.Blazor.PopupsNamespace:
Syncfusion.Blazor.PopupsSyncfusion Blazor预定义对话框采用基于服务的架构,包含两个核心组件:
- SfDialogService - 用于以编程方式打开对话框的注册服务
- SfDialogProvider - 添加到布局中以启用对话框渲染的组件
核心功能:
- 三种对话框类型:Alert、Confirm、Prompt
- 可从应用任意位置通过服务调用
- 可自定义定位、尺寸和动画
- 支持可拖拽对话框
- 带图标的按钮自定义
- 自定义内容渲染
- 内置无障碍访问支持
包:
命名空间:
Syncfusion.Blazor.Popups命名空间:
Syncfusion.Blazor.PopupsDocumentation and Navigation Guide
文档与导航指南
Getting Started (Setup & Basic Usage)
快速入门(设置与基础用法)
📄 Read: references/getting-started.md
- Prerequisites and system requirements
- Installation for Blazor WebAssembly, Server App, and Web App
- NuGet package installation (Syncfusion.Blazor.Popups)
- Import namespaces (_Imports.razor)
- Service registration (SfDialogService, AddSyncfusionBlazor)
- Adding SfDialogProvider to MainLayout
- Stylesheet and script references
- Alert dialog basics (AlertAsync method)
- Confirm dialog basics (ConfirmAsync method)
- Prompt dialog basics (PromptAsync method)
- Basic code examples for all three dialog types
📄 阅读: references/getting-started.md
- 先决条件和系统要求
- Blazor WebAssembly、Server App和Web App的安装步骤
- NuGet包安装(Syncfusion.Blazor.Popups)
- 导入命名空间(_Imports.razor)
- 服务注册(SfDialogService、AddSyncfusionBlazor)
- 在MainLayout中添加SfDialogProvider
- 样式表和脚本引用
- Alert对话框基础(AlertAsync方法)
- Confirm对话框基础(ConfirmAsync方法)
- Prompt对话框基础(PromptAsync方法)
- 三种对话框类型的基础代码示例
Positioning Dialogs
对话框定位
📄 Read: references/positioning.md
- DialogOptions.Position property
- PositionDataModel configuration (X and Y)
- Position values: left, center, right, top, bottom, offset
- Customizing dialog position for alert, confirm, prompt
- Examples with top-center positioning
📄 阅读: references/positioning.md
- DialogOptions.Position属性
- PositionDataModel配置(X和Y)
- 位置值:left、center、right、top、bottom、offset
- 自定义Alert、Confirm、Prompt对话框的位置
- 顶部居中定位的示例
Draggable Dialogs
可拖拽对话框
📄 Read: references/dragging.md
- DialogOptions.AllowDragging property
- Enabling drag behavior by dialog header
- Header visibility requirement
- Examples for draggable alert, confirm, prompt dialogs
📄 阅读: references/dragging.md
- DialogOptions.AllowDragging属性
- 启用通过对话框页眉拖拽的行为
- 页眉可见性要求
- 可拖拽Alert、Confirm、Prompt对话框的示例
Dialog Dimensions
对话框尺寸
📄 Read: references/dimensions.md
- DialogOptions.Width and Height properties
- Default auto-sizing behavior
- Setting dimensions in pixels or percentages
- Max-width and max-height using CssClass
- Min-width and min-height using CssClass
- Responsive sizing strategies
- Examples with custom dimensions
📄 阅读: references/dimensions.md
- DialogOptions.Width和Height属性
- 默认自动调整大小行为
- 设置像素或百分比单位的尺寸
- 使用CssClass设置最大宽度和最大高度
- 使用CssClass设置最小宽度和最小高度
- 响应式大小策略
- 自定义尺寸的示例
Customization Options
自定义选项
📄 Read: references/customization.md
- DialogOptions.PrimaryButtonOptions (OK button)
- DialogOptions.CancelButtonOptions (Cancel button)
- DialogButtonOptions.Content (button text)
- DialogButtonOptions.IconCss (button icons)
- DialogOptions.ShowCloseIcon property
- DialogOptions.ChildContent for custom content rendering
- Customizing alert, confirm, prompt dialogs
- Advanced content customization examples
📄 阅读: references/customization.md
- DialogOptions.PrimaryButtonOptions(OK按钮)
- DialogOptions.CancelButtonOptions(Cancel按钮)
- DialogButtonOptions.Content(按钮文本)
- DialogButtonOptions.IconCss(按钮图标)
- DialogOptions.ShowCloseIcon属性
- DialogOptions.ChildContent用于自定义内容渲染
- 自定义Alert、Confirm、Prompt对话框
- 高级内容自定义示例
Animation Effects
动画效果
📄 Read: references/animation.md
- DialogOptions.AnimationSettings property
- DialogAnimationOptions configuration
- Animation Delay, Duration, and Effect
- DialogEffect enumeration values
- Zoom, fade, slide effects
- Examples with zoom animation
📄 阅读: references/animation.md
- DialogOptions.AnimationSettings属性
- DialogAnimationOptions配置
- 动画延迟、时长和效果
- DialogEffect枚举值
- 缩放、淡入淡出、滑动效果
- 缩放动画的示例
Quick Start Example
快速入门示例
Basic Alert Dialog
基础Alert对话框
razor
@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!");
}
}razor
@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!");
}
}Basic Confirm Dialog
基础Confirm对话框
razor
@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";
}
}razor
@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";
}
}Basic Prompt Dialog
基础Prompt对话框
razor
@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";
}
}razor
@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";
}
}Common Patterns
常见模式
Pattern 1: Confirmation Before Delete
模式1:删除前确认
razor
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
}
}razor
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
}
}Pattern 2: Positioned Dialog
模式2:定位对话框
razor
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
);
}razor
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
);
}Pattern 3: Custom Content Prompt
模式3:自定义内容Prompt
razor
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);
}razor
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);
}Pattern 4: Animated Draggable Dialog
模式4:带动画的可拖拽对话框
razor
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
);
}razor
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
);
}Key Properties
关键属性
SfDialogService Methods
SfDialogService方法
| Method | Parameters | Returns | Description |
|---|---|---|---|
| title, content, options | | Shows alert dialog with OK button |
| title, content, options | | Shows confirm dialog, returns true/false |
| title, defaultValue, options | | Shows prompt dialog, returns input or null |
| 方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| title, content, options | | 显示带OK按钮的Alert对话框 |
| title, content, options | | 显示Confirm对话框,返回true/false |
| title, defaultValue, options | | 显示Prompt对话框,返回输入内容或null |
DialogOptions Properties
DialogOptions属性
| Property | Type | Default | Description |
|---|---|---|---|
| PositionDataModel | center/center | Dialog position (X, Y coordinates) |
| string | "auto" | Dialog width (px, %, em) |
| string | "auto" | Dialog height (px, %, em) |
| bool | false | Enable dragging by header |
| bool | false | Show close icon button |
| DialogAnimationOptions | default | Animation configuration |
| DialogButtonOptions | null | Primary (OK) button customization |
| DialogButtonOptions | null | Cancel button customization |
| RenderFragment | null | Custom content for dialog body |
| string | null | Custom CSS class |
| bool | true | Close on Escape key |
| int | 1000 | Dialog z-index |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| PositionDataModel | center/center | 对话框位置(X、Y坐标) |
| string | "auto" | 对话框宽度(px、%、em) |
| string | "auto" | 对话框高度(px、%、em) |
| bool | false | 允许通过页眉拖拽 |
| bool | false | 显示关闭图标按钮 |
| DialogAnimationOptions | default | 动画配置 |
| DialogButtonOptions | null | 主按钮(OK)自定义 |
| DialogButtonOptions | null | Cancel按钮自定义 |
| RenderFragment | null | 对话框主体的自定义内容 |
| string | null | 自定义CSS类 |
| bool | true | 按下Escape键关闭 |
| int | 1000 | 对话框Z-index |
PositionDataModel Properties
PositionDataModel属性
| Property | Type | Values | Description |
|---|---|---|---|
| string | left, center, right, offset | Horizontal position |
| string | top, center, bottom, offset | Vertical position |
| 属性 | 类型 | 值 | 描述 |
|---|---|---|---|
| string | left, center, right, offset | 水平位置 |
| string | top, center, bottom, offset | 垂直位置 |
DialogButtonOptions Properties
DialogButtonOptions属性
| Property | Type | Description |
|---|---|---|
| string | Button text content |
| string | CSS class for button icon |
| bool | Primary button styling |
| 属性 | 类型 | 描述 |
|---|---|---|
| string | 按钮文本内容 |
| string | 按钮图标的CSS类 |
| bool | 主按钮样式 |
DialogAnimationSettings Properties
DialogAnimationSettings属性
| Property | Type | Description |
|---|---|---|
| DialogEffect | Animation effect (Zoom, Fade, etc.) |
| int | Animation duration in milliseconds |
| int | Animation delay in milliseconds |
| 属性 | 类型 | 描述 |
|---|---|---|
| DialogEffect | 动画效果(Zoom、Fade等) |
| int | 动画时长(毫秒) |
| int | 动画延迟(毫秒) |
Common Use Cases
常见用例
Use Case 1: Error/Warning/Info Messages
用例1:错误/警告/信息消息
Display system messages, errors, warnings, or information requiring user acknowledgment using Alert dialogs.
使用Alert对话框显示系统消息、错误、警告或需要用户确认的信息。
Use Case 2: Critical Action Confirmation
用例2:关键操作确认
Get user confirmation before destructive actions like delete, logout, or data loss operations using Confirm dialogs.
在执行删除、注销或数据丢失等破坏性操作前,使用Confirm对话框获取用户确认。
Use Case 3: User Input Collection
用例3:用户输入收集
Collect simple text input like usernames, search queries, or configuration values using Prompt dialogs.
使用Prompt对话框收集简单文本输入,如用户名、搜索查询或配置值。
Use Case 4: Form Validation Feedback
用例4:表单验证反馈
Show validation errors or success messages with positioned dialogs that don't obstruct form fields.
使用定位对话框显示验证错误或成功消息,避免遮挡表单字段。
Use Case 5: Custom Interactive Dialogs
用例5:自定义交互式对话框
Create complex interactive dialogs with custom content, multiple inputs, and customized buttons.
创建包含自定义内容、多个输入框和自定义按钮的复杂交互式对话框。
Use Case 6: Notification System
用例6:通知系统
Build notification systems with animated, positioned dialogs that appear in specific screen areas.
使用带动画的定位对话框构建通知系统,在屏幕特定区域显示通知。
Setup Requirements
设置要求
Prerequisites:
- Blazor WebAssembly, Server, or Web App project
- .NET SDK installed
- Visual Studio, VS Code, or .NET CLI
Required Packages:
Syncfusion.Blazor.PopupsSyncfusion.Blazor.Themes
Required Setup:
- Register in Program.cs
SfDialogService - Register service
AddSyncfusionBlazor() - Add in MainLayout.razor
SfDialogProvider - Include Syncfusion theme stylesheet in head
- Include Syncfusion script reference in body
- Import namespace in _Imports.razor
Syncfusion.Blazor.Popups
Refer to references/getting-started.md for complete setup instructions for all Blazor app types.
先决条件:
- Blazor WebAssembly、Server或Web App项目
- 已安装.NET SDK
- Visual Studio、VS Code或.NET CLI
所需包:
Syncfusion.Blazor.PopupsSyncfusion.Blazor.Themes
所需设置:
- 在Program.cs中注册
SfDialogService - 注册服务
AddSyncfusionBlazor() - 在MainLayout.razor中添加
SfDialogProvider - 在head中包含Syncfusion主题样式表
- 在body中包含Syncfusion脚本引用
- 在_Imports.razor中导入命名空间
Syncfusion.Blazor.Popups
有关所有Blazor应用类型的完整设置说明,请参阅references/getting-started.md。