syncfusion-maui-step-progressbar

实现 .NET MAUI StepProgressBar

全面介绍如何实现和自定义 Syncfusion® .NET MAUI StepProgressBar（SfStepProgressBar）控件。本指南涵盖步骤进度可视化、多步骤流程跟踪、按顺序指示步骤进度、自定义步骤外观和内容、处理步骤状态（已完成/进行中/未开始）、方向选项、工具提示、事件、无障碍支持、RTL 支持以及液态玻璃效果。

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 在 .NET MAUI 应用中实现分步进度指示器
• 显示多步骤流程可视化（订单跟踪、用户注册、结账流程）
• 通过一系列阶段显示进度并提供视觉反馈
• 自定义步骤外观（形状、颜色、内容类型、动画）
• 处理步骤状态：已完成、进行中或未开始
• 为步骤显示配置水平或垂直方向
• 为步骤添加交互式工具提示，以提供更多上下文
• 实现步骤点击事件和状态更改处理
• 支持从右到左（RTL）布局，以适应国际化需求
• 为步骤进度条应用现代液态玻璃效果
• 创建无障碍的步骤进度体验

组件概述

.NET MAUI StepProgressBar（SfStepProgressBar） 是一种可视化控件，用于显示顺序流程中的多个步骤进度。它提供：

• 多步骤可视化：清晰显示 3 到 10 个以上的步骤及其进度
• 三种进度状态：已完成、进行中和未开始
• 灵活的方向：水平或垂直布局
• 丰富的自定义选项：形状（圆形/正方形）、内容类型（勾号/叉号/圆点/编号/图像）、颜色、尺寸
• 文本描述：支持格式化文本的主文本和次文本
• 交互功能：工具提示、点击事件、状态更改事件
• 无障碍支持：支持屏幕阅读器和包容性设计
• 高级效果：液态玻璃效果，营造现代 UI 视觉风格
• RTL 支持：支持从右到左渲染，以适应国际化需求

常见用例包括订单跟踪系统、多页注册表单、结账流程、入门教程、调查进度和安装向导。

文档和导航指南

入门

📄 阅读： references/getting-started.md

阅读时机：用户首次设置 StepProgressBar、需要安装步骤或想要基本的可运行示例时。

涵盖主题：

• 安装 Syncfusion.Maui.ProgressBar NuGet 包
• 使用 ConfigureSyncfusionCore() 注册处理程序
• 将 SfStepProgressBar 添加到 XAML 或 C#
• 使用 ItemsSource 和 ObservableCollection 填充项目
• 设置 ActiveStepIndex 和 ActiveStepProgressValue
• 使用 StepProgressBarItem 集合创建 ViewModel
• 基本水平进度条示例

描述和标签

📄 阅读： references/descriptions-and-labels.md

阅读时机：用户需要添加文本标签、自定义标签位置、为步骤添加图像或使用格式化文本时。

涵盖主题：

• PrimaryText 和 SecondaryText 属性
• 用于富文本的 PrimaryFormattedText 和 SecondaryFormattedText
• 用于控制步骤与文本之间间距的 LabelSpacing
• LabelPosition 选项（Start、End、Top、Bottom）
• 用于向步骤内容添加图像的 ImageSource
• 使用 FontImageSource 的字体图标
• 水平/垂直模式下特定于位置的标签行为

方向

📄 阅读： references/orientation.md

阅读时机：用户想要从水平布局切换为垂直布局，或需要方向选项方面的指导时。

涵盖主题：

• 水平方向（默认）
• 垂直方向
• 设置 Orientation 属性
• 不同方向的视觉差异
• 各方向的适用场景

自定义

📄 阅读： references/customization.md

适用场景：用户需要自定义步骤形状、颜色、内容类型、动画、模板或单个步骤的样式。

涵盖主题：

• 步骤形状类型（Circle、Square）及 ShapeType 属性
• 内容类型（Numbering、Tick、Cross、Dot）及 ContentType 属性
• 使用 ProgressAnimationDuration 设置动画时长
• 自定义进度条背景颜色
• 使用 ProgressTrackSize 为每个步骤自定义进度轨道大小
• 用于已完成、进行中和未开始状态的 StepSettings
• Background、ContentFillColor、ProgressColor 和 Stroke 属性
• TextStyle 自定义（颜色、字体、属性）
• 使用 DataTemplate 定义自定义步骤视觉效果的 StepTemplate
• 用于条件式步骤模板的 DataTemplateSelector
• 用于自定义标签的 PrimaryTextTemplate 和 SecondaryTextTemplate
• 完整的自定义示例

事件

📄 阅读： references/events.md

适用场景：用户需要处理步骤点击交互，或响应步骤状态变化。

涵盖主题：

• 用于处理步骤点击交互的 StepTapped 事件
• StepTappedEventArgs 属性
• 用于跟踪状态变化的 StepStatusChanged 事件
• StepStatusChangedEventArgs 属性
• 事件处理程序实现示例

工具提示

📄 阅读： references/tooltips.md

适用场景：用户希望为步骤添加工具提示、自定义工具提示外观或使用自定义工具提示模板。

涵盖主题：

• 使用 ShowToolTip 属性启用工具提示
• 在 StepProgressBarItem 上设置 ToolTipText
• 用于自定义外观的 ToolTipSettings
• Background、Stroke、Duration 和 TextStyle 属性
• 使用 DataTemplate 定义自定义工具提示设计的 ToolTipTemplate
• 控制工具提示的显示时长
• 自定义工具提示布局和内容

无障碍

📄 阅读： references/accessibility.md

适用场景：用户需要确保符合无障碍要求，或了解屏幕阅读器支持情况。

涵盖主题：

• 无障碍功能概述
• 屏幕阅读器播报格式
• 步骤编号、文本和状态播报
• 包容性设计注意事项

从右到左支持

📄 阅读： references/right-to-left.md

适用场景：用户需要支持 RTL 语言（阿拉伯语、希伯来语等）或镜像布局。

涵盖主题：

• 将 FlowDirection 属性设为 RightToLeft
• RTL 渲染行为
• 用于国际化的布局镜像

液态玻璃效果

📄 阅读： references/liquid-glass-effect.md

适用场景：用户希望应用现代液态玻璃视觉效果（.NET 10+、macOS 26+、iOS 26+）。

涵盖主题：

• 集成 SfGlassEffectView
• 在玻璃效果视图中封装 StepProgressBar
• 为玻璃效果设置透明背景
• 平台和版本要求
• 使用渐变背景的完整实现