syncfusion-blazor-popups

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing 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

关键属性

PropertyTypePurpose
Width
stringSets dialog width (e.g., "400px", "50%"). Default: "100%"
Height
stringSets dialog height (e.g., "300px", "70%"). Default: "auto"
Header
stringSets dialog header text
Content
stringSets dialog content text
Visible
boolControls dialog visibility. Supports @bind-Visible. Default: true
IsModal
boolMakes dialog modal (overlay blocking interaction). Default: false
ShowCloseIcon
boolShows close button in header. Default: false
AllowDragging
boolEnables dialog dragging by header. Default: false
EnableResize
boolEnables dialog resizing. Default: false
CloseOnEscape
boolCloses dialog when Escape key is pressed. Default: true
AnimationSettings
DialogAnimationSettingsConfigures open/close animations (effect, duration, delay). Default: Fade effect, 400ms
Position
stringPositioning mode: "fixed" (stays on screen), "absolute" (relative to target), or "relative" (document flow). Default: "fixed"
Left
stringX-coordinate position (e.g., "100px", "20%"). Works with Position property. Default: "auto"
Top
stringY-coordinate position (e.g., "50px", "10%"). Works with Position property. Default: "auto"
ID
stringUnique identifier for the dialog. Required when EnablePersistence="true"
MinHeight
stringSets minimum height constraint for resize (e.g., "150px"). Default: null
MaxHeight
stringSets maximum height constraint for resize (e.g., "600px"). Default: null
ResizeHandles
ResizeDirection[]Array of resize directions (e.g., SouthEast, NorthEast). Default: [SouthEast]
Buttons
List<DialogButtonModel>Programmatic button configuration (alternative to DialogButtons component)
CssClass
stringCustom CSS class(es) for styling
EnableRtl
boolEnables right-to-left layout support. Default: false
EnablePersistence
boolPersists position, width, height to browser local storage. Default: false. Requires ID property
Target
stringCSS selector for dialog target/container element (e.g., "#container", ".target-div")
FooterTemplate
RenderFragmentCustom footer content (alternative to DialogButtons component)
AllowPrerender
boolKeeps DOM elements when hidden for faster re-display. Default: false
ZIndex
doubleSets stacking order relative to other elements. Default: 1000
属性类型用途
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
stringX坐标位置(例如:"100px"、"20%"),需配合Position属性使用。默认值:"auto"
Top
stringY坐标位置(例如:"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

Key Enums and Types

关键枚举与类型

DialogEffect Enum

DialogEffect枚举

Animation effects for dialog open/close transitions:
ValueDescription
None
No animation
Fade
Fade in/out effect (default)
Zoom
Zoom in/out from center
SlideLeft
Slide from/to left
SlideRight
Slide from/to right
SlideTop
Slide from/to top
SlideBottom
Slide from/to bottom
FlipX
Horizontal flip effect
FlipY
Vertical flip effect
对话框打开/关闭过渡的动画效果:
描述
None
无动画
Fade
淡入淡出效果(默认)
Zoom
从中心缩放
SlideLeft
从左侧滑入/滑出
SlideRight
从右侧滑入/滑出
SlideTop
从顶部滑入/滑出
SlideBottom
从底部滑入/滑出
FlipX
水平翻转效果
FlipY
垂直翻转效果

ResizeDirection Enum

ResizeDirection枚举

Directions from which the dialog can be resized:
ValueDescription
South
Bottom edge
North
Top edge
East
Right edge
West
Left edge
SouthEast
Bottom-right corner (default)
SouthWest
Bottom-left corner
NorthEast
Top-right corner
NorthWest
Top-left corner
All
All directions
对话框可调整大小的方向:
描述
South
底部边缘
North
顶部边缘
East
右侧边缘
West
左侧边缘
SouthEast
右下角(默认)
SouthWest
左下角
NorthEast
右上角
NorthWest
左上角
All
所有方向

ButtonType Enum

ButtonType枚举

HTML button type attribute for dialog buttons:
ValueDescription
Button
Standard button (default)
Submit
Form submission button
Reset
Form reset button
对话框按钮的HTML button类型属性:
描述
Button
标准按钮(默认)
Submit
表单提交按钮
Reset
表单重置按钮

DialogAnimationSettings Class

DialogAnimationSettings类

Configuration for dialog animations:
PropertyTypeDescriptionDefault
Effect
DialogEffectAnimation effectDialogEffect.Fade
Duration
intAnimation duration (milliseconds)400
Delay
intAnimation delay (milliseconds)0
  • Use
    ShowAsync(true)
    for fullscreen dialogs when you need maximum focus and screen real estate
  • Set
    Visible="false"
    initially when using programmatic control with ShowAsync() Example:
csharp
var animSettings = new DialogAnimationOptions 
{ 
    Effect = DialogEffect.Zoom, 
    Duration = 300, 
    Delay = 0 
};
对话框动画配置:
属性类型描述默认值
Effect
DialogEffect动画效果DialogEffect.Fade
Duration
int动画时长(毫秒)400
Delay
int动画延迟(毫秒)0
  • 当需要最大焦点和屏幕空间时,使用
    ShowAsync(true)
    打开全屏对话框
  • 当使用ShowAsync()进行程序化控制时,初始设置
    Visible="false"
    示例:
csharp
var animSettings = new DialogAnimationOptions 
{ 
    Effect = DialogEffect.Zoom, 
    Duration = 300, 
    Delay = 0 
};

DialogDimension Class

DialogDimension类

Returned by
GetDimension()
method:
PropertyTypeDescription
Width
stringCurrent dialog width
Height
stringCurrent dialog height
GetDimension()
方法返回的类型:
属性类型描述
Width
string当前对话框宽度
Height
string当前对话框高度

Important Constraints and Notes

重要约束与注意事项

⚠️ Critical Requirements:
  • ID Property: Must be set when using
    EnablePersistence="true"
    . The ID serves as the localStorage key.
  • Mutual Exclusivity:
    FooterTemplate
    and
    DialogButtons
    cannot be used together. Choose one approach.
  • Target Selector: The
    Target
    property must reference a valid CSS selector for existing DOM elements.
  • Resize Dependency:
    ResizeHandles
    only works when
    EnableResize="true"
    .
  • Position Context: The
    Position
    property affects how
    Left
    and
    Top
    coordinates are interpreted.
📋 Best Practices:
  • Use
    IsModal="true"
    for critical actions requiring user attention
  • Set
    AllowPrerender="true"
    for frequently toggled dialogs to improve performance
  • Always provide a close mechanism (button, close icon, or Escape key)
  • Use
    ZIndex
    values in increments (1000, 1001, 1002) for nested dialogs
  • Test responsive behavior with percentage-based Width/Height values
⚠️ 关键要求:
  • ID属性:当使用
    EnablePersistence="true"
    时必须设置,ID作为localStorage的键。
  • 互斥性
    FooterTemplate
    DialogButtons
    不能同时使用,需选择其中一种方式。
  • 目标选择器
    Target
    属性必须引用现有DOM元素的有效CSS选择器。
  • 调整大小依赖
    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

核心属性

PropertyTypeDefaultDescription
ContentstringnullText content to display in tooltip
TargetstringnullCSS selector for target elements
PositionPositionTopCenterTooltip placement position
OpensOnstring"Auto"Trigger mode (Auto, Hover, Click, Focus, Custom)
IsStickyboolfalseKeep tooltip open with close button
AnimationAnimationModelnullAnimation settings for open/close transitions
属性类型默认值描述
Contentstringnull提示框中显示的文本内容
Targetstringnull目标元素的CSS选择器
PositionPositionTopCenter提示框的布局位置
OpensOnstring"Auto"触发模式(Auto、Hover、Click、Focus、Custom)
IsStickyboolfalse通过关闭按钮保持提示框打开
AnimationAnimationModelnull打开/关闭过渡的动画设置

Content Properties

内容属性

PropertyTypeDescription
ContentTemplateRenderFragmentCustom HTML content template. Default: null
ContentstringSimple text or HTML string content. Default: null
ChildContentRenderFragmentWraps the target element(s) within the tooltip component. Default: null
属性类型描述
ContentTemplateRenderFragment自定义HTML内容模板。默认值:null
Contentstring纯文本或HTML字符串内容。默认值:null
ChildContentRenderFragment将目标元素包裹在提示框组件内。默认值:null

Positioning Properties

定位属性

PropertyTypeDefaultDescription
PositionPositionTopCenterStatic position around target
MouseTrailboolfalseFollow mouse pointer
OffsetXdouble0Horizontal offset in pixels
OffsetYdouble0Vertical offset in pixels
WindowCollisionboolfalseUse viewport for collision detection instead of parent element
属性类型默认值描述
PositionPositionTopCenter目标元素周围的静态位置
MouseTrailboolfalse跟随鼠标指针
OffsetXdouble0水平偏移(像素)
OffsetYdouble0垂直偏移(像素)
WindowCollisionboolfalse使用视口而非父元素进行碰撞检测

Timing Properties

时序属性

PropertyTypeDefaultDescription
OpenDelaydouble0Delay before opening (milliseconds)
CloseDelaydouble0Delay before closing (milliseconds)
属性类型默认值描述
OpenDelaydouble0打开前的延迟(毫秒)
CloseDelaydouble0关闭前的延迟(毫秒)

Event Callbacks

事件回调

EventTypeDescription
CreatedEventCallback<object>Raised after tooltip component is created
DestroyedEventCallback<object>Raised when tooltip component is destroyed
OnOpenEventCallback<TooltipEventArgs>Raised before tooltip is displayed (cancelable)
OpenedEventCallback<TooltipEventArgs>Raised after tooltip is opened
OnCloseEventCallback<TooltipEventArgs>Raised before tooltip hides (cancelable)
ClosedEventCallback<TooltipEventArgs>Raised after tooltip is closed
OnRenderEventCallback<TooltipEventArgs>Raised before tooltip is added to DOM (cancelable)
OnCollisionEventCallback<TooltipEventArgs>Raised during collision detection calculations
事件类型描述
CreatedEventCallback<object>提示框组件创建后触发
DestroyedEventCallback<object>提示框组件销毁时触发
OnOpenEventCallback<TooltipEventArgs>提示框显示前触发(可取消)
OpenedEventCallback<TooltipEventArgs>提示框打开后触发
OnCloseEventCallback<TooltipEventArgs>提示框隐藏前触发(可取消)
ClosedEventCallback<TooltipEventArgs>提示框关闭后触发
OnRenderEventCallback<TooltipEventArgs>提示框添加到DOM前触发(可取消)
OnCollisionEventCallback<TooltipEventArgs>碰撞检测计算期间触发

Public Methods

公共方法

MethodReturn TypeDescription
OpenAsync(ElementReference?, TooltipAnimationSettings)TaskOpens tooltip programmatically with optional target and animation settings
CloseAsync(TooltipAnimationSettings)TaskCloses tooltip programmatically with optional animation settings
RefreshAsync()TaskRefreshes tooltip to sync with dynamic DOM changes and target updates
RefreshPositionAsync(ElementReference?)TaskRecalculates and updates tooltip position based on current target location
方法返回类型描述
OpenAsync(ElementReference?, TooltipAnimationSettings)Task以编程方式打开提示框,可指定目标和动画设置
CloseAsync(TooltipAnimationSettings)Task以编程方式关闭提示框,可指定动画设置
RefreshAsync()Task刷新提示框以同步动态DOM变化和目标更新
RefreshPositionAsync(ElementReference?)Task根据当前目标位置重新计算并更新提示框位置

Appearance Properties

外观属性

PropertyTypeDescription
CssClassstringCustom CSS class for styling. Default: null
WidthstringTooltip width (auto or pixels). Default: "auto"
HeightstringTooltip height (auto or pixels). Default: "auto"
ShowTipPointerboolShow/hide arrow pointer. Default: true
TipPointerPositionTipPointerPositionPosition of tip pointer (Auto, Start, Middle, End). Default: Auto
EnableRtlboolEnable right-to-left direction. Default: false
HtmlAttributesDictionary<string, object>Additional HTML attributes for tooltip element. Default: null
IDstringUnique identifier for the tooltip component. Default: auto-generated
属性类型描述
CssClassstring用于样式设置的自定义CSS类。默认值:null
Widthstring提示框宽度(auto或像素)。默认值:"auto"
Heightstring提示框高度(auto或像素)。默认值:"auto"
ShowTipPointerbool显示/隐藏箭头指针。默认值:true
TipPointerPositionTipPointerPosition提示指针的位置(Auto、Start、Middle、End)。默认值:Auto
EnableRtlbool启用从右到左方向。默认值:false
HtmlAttributesDictionary<string, object>提示框元素的额外HTML属性。默认值:null
IDstring提示框组件的唯一标识符。默认值:自动生成

Target Properties

目标属性

PropertyTypeDescription
TargetstringCSS selector for target elements. Default: null
ContainerstringContainer element where tooltip popup is appended. Default: "body"
TargetContainerstringContainer selector for dynamic target registration. Default: null
属性类型描述
Targetstring目标元素的CSS选择器。默认值:null
Containerstring提示框弹窗附加到的容器元素。默认值:"body"
TargetContainerstring用于动态目标注册的容器选择器。默认值:null

Key Types and Classes

关键类型与类

AnimationModel Class

AnimationModel类

Configuration for tooltip open and close animations:
PropertyTypeDescription
OpenTooltipAnimationSettingsAnimation settings for opening tooltip
CloseTooltipAnimationSettingsAnimation settings for closing tooltip
提示框打开和关闭动画的配置:
属性类型描述
OpenTooltipAnimationSettings提示框打开的动画设置
CloseTooltipAnimationSettings提示框关闭的动画设置

TooltipAnimationSettings Class

TooltipAnimationSettings类

Detailed animation configuration:
PropertyTypeDefaultDescription
EffectEffectFadeAnimation effect (FadeIn, FadeOut, ZoomIn, ZoomOut, None)
Durationint150Animation duration in milliseconds
Delayint0Animation delay in milliseconds
详细的动画配置:
属性类型默认值描述
EffectEffectFade动画效果(FadeIn、FadeOut、ZoomIn、ZoomOut、None)
Durationint150动画时长(毫秒)
Delayint0动画延迟(毫秒)

Effect Enum

Effect枚举

Animation effects for tooltip transitions:
ValueDescription
NoneNo animation
FadeInFade in effect for opening
FadeOutFade out effect for closing
ZoomInZoom in effect for opening
ZoomOutZoom out effect for closing
提示框过渡的动画效果:
描述
None无动画
FadeIn打开时淡入效果
FadeOut关闭时淡出效果
ZoomIn打开时放大效果
ZoomOut关闭时缩小效果

Position Enum

Position枚举

Tooltip placement positions:
ValueDescription
TopLeftAbove target, aligned to left edge
TopCenterAbove target, centered (default)
TopRightAbove target, aligned to right edge
BottomLeftBelow target, aligned to left edge
BottomCenterBelow target, centered
BottomRightBelow target, aligned to right edge
LeftTopLeft of target, aligned to top edge
LeftCenterLeft of target, centered vertically
LeftBottomLeft of target, aligned to bottom edge
RightTopRight of target, aligned to top edge
RightCenterRight of target, centered vertically
RightBottomRight 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:
ValueDescription
AutoAutomatically adjusts pointer position (default)
StartPointer at start of tooltip edge
MiddlePointer at middle of tooltip edge
EndPointer 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
    OpensOn="Focus"
    to show tooltip when input receives 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
    Content
    property for short descriptions
  • Set
    OpensOn="Hover"
    for immediate feedback
  • Consider
    Position.TopCenter
    or
    Position.BottomCenter
    for consistency
为纯图标按钮添加描述性文本:
  • 使用简单的
    Content
    属性设置简短描述
  • 设置
    OpensOn="Hover"
    以获得即时反馈
  • 考虑使用
    Position.TopCenter
    Position.BottomCenter
    保持一致性

Rich Content Cards

富内容卡片

Display detailed information on hover:
  • Read references/content.md for template options
  • Use
    ContentTemplate
    with formatted HTML
  • Include images, links, and formatted text
  • Consider
    OpensOn="Click"
    and
    IsSticky="true"
    for complex content
悬停时显示详细信息:
  • 阅读references/content.md了解模板选项
  • 使用
    ContentTemplate
    添加格式化HTML
  • 包含图片、链接和格式化文本
  • 对于复杂内容,考虑使用
    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
    TargetContainer
    to handle elements added after initialization
  • 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:
Syncfusion.Blazor.Popups

Namespace:
Syncfusion.Blazor.Popups

Syncfusion Blazor预定义对话框采用基于服务的架构,包含两个核心组件:
  • SfDialogService - 用于以编程方式打开对话框的注册服务
  • SfDialogProvider - 添加到布局中以启用对话框渲染的组件
核心功能:
  • 三种对话框类型:Alert、Confirm、Prompt
  • 可从应用任意位置通过服务调用
  • 可自定义定位、尺寸和动画
  • 支持可拖拽对话框
  • 带图标的按钮自定义
  • 自定义内容渲染
  • 内置无障碍访问支持
包:
Syncfusion.Blazor.Popups

命名空间:
Syncfusion.Blazor.Popups

Documentation 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方法

MethodParametersReturnsDescription
AlertAsync
title, content, options
Task
Shows alert dialog with OK button
ConfirmAsync
title, content, options
Task<bool>
Shows confirm dialog, returns true/false
PromptAsync
title, defaultValue, options
Task<string>
Shows prompt dialog, returns input or null
方法参数返回值描述
AlertAsync
title, content, options
Task
显示带OK按钮的Alert对话框
ConfirmAsync
title, content, options
Task<bool>
显示Confirm对话框,返回true/false
PromptAsync
title, defaultValue, options
Task<string>
显示Prompt对话框,返回输入内容或null

DialogOptions Properties

DialogOptions属性

PropertyTypeDefaultDescription
Position
PositionDataModelcenter/centerDialog position (X, Y coordinates)
Width
string"auto"Dialog width (px, %, em)
Height
string"auto"Dialog height (px, %, em)
AllowDragging
boolfalseEnable dragging by header
ShowCloseIcon
boolfalseShow close icon button
AnimationSettings
DialogAnimationOptionsdefaultAnimation configuration
PrimaryButtonOptions
DialogButtonOptionsnullPrimary (OK) button customization
CancelButtonOptions
DialogButtonOptionsnullCancel button customization
ChildContent
RenderFragmentnullCustom content for dialog body
CssClass
stringnullCustom CSS class
CloseOnEscape
booltrueClose on Escape key
ZIndex
int1000Dialog z-index
属性类型默认值描述
Position
PositionDataModelcenter/center对话框位置(X、Y坐标)
Width
string"auto"对话框宽度(px、%、em)
Height
string"auto"对话框高度(px、%、em)
AllowDragging
boolfalse允许通过页眉拖拽
ShowCloseIcon
boolfalse显示关闭图标按钮
AnimationSettings
DialogAnimationOptionsdefault动画配置
PrimaryButtonOptions
DialogButtonOptionsnull主按钮(OK)自定义
CancelButtonOptions
DialogButtonOptionsnullCancel按钮自定义
ChildContent
RenderFragmentnull对话框主体的自定义内容
CssClass
stringnull自定义CSS类
CloseOnEscape
booltrue按下Escape键关闭
ZIndex
int1000对话框Z-index

PositionDataModel Properties

PositionDataModel属性

PropertyTypeValuesDescription
X
stringleft, center, right, offsetHorizontal position
Y
stringtop, center, bottom, offsetVertical position
属性类型描述
X
stringleft, center, right, offset水平位置
Y
stringtop, center, bottom, offset垂直位置

DialogButtonOptions Properties

DialogButtonOptions属性

PropertyTypeDescription
Content
stringButton text content
IconCss
stringCSS class for button icon
IsPrimary
boolPrimary button styling
属性类型描述
Content
string按钮文本内容
IconCss
string按钮图标的CSS类
IsPrimary
bool主按钮样式

DialogAnimationSettings Properties

DialogAnimationSettings属性

PropertyTypeDescription
Effect
DialogEffectAnimation effect (Zoom, Fade, etc.)
Duration
intAnimation duration in milliseconds
Delay
intAnimation delay in milliseconds

属性类型描述
Effect
DialogEffect动画效果(Zoom、Fade等)
Duration
int动画时长(毫秒)
Delay
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:
  1. Blazor WebAssembly, Server, or Web App project
  2. .NET SDK installed
  3. Visual Studio, VS Code, or .NET CLI
Required Packages:
  • Syncfusion.Blazor.Popups
  • Syncfusion.Blazor.Themes
Required Setup:
  1. Register
    SfDialogService
    in Program.cs
  2. Register
    AddSyncfusionBlazor()
    service
  3. Add
    SfDialogProvider
    in MainLayout.razor
  4. Include Syncfusion theme stylesheet in head
  5. Include Syncfusion script reference in body
  6. Import
    Syncfusion.Blazor.Popups
    namespace in _Imports.razor
Refer to references/getting-started.md for complete setup instructions for all Blazor app types.
先决条件:
  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