syncfusion-winui-segmented-control

实现 WinUI 分段控件

何时使用此技能

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

• 创建分段控件或分段选择器 UI
• 实现互斥选项选择
• 构建类似选项卡的导航，但不使用完整的 TabControl
• 创建筛选栏或视图模式切换器
• 显示 2 个或更多线性选项，且只能选择其中一个
• 添加动画选择过渡效果（滑动效果）
• 创建自定义分段样式（椭圆形、圆形、顶部指示器）
• 实现分段选择的键盘导航
• 根据条件禁用特定分段
• 同时支持浅色和深色主题

用户提及以下内容时，务必应用此技能： 分段控件、分段选择器、选项选择器、筛选栏、视图切换器、选项卡选择器、互斥按钮或 WinUI 应用中的基于分段的导航。

组件概述

SfSegmentedControl 是 Syncfusion WinUI 控件，提供了一种简单方式，可从两个或更多线性排列的分段中进行选择，每个分段都作为互斥选项。它是单选按钮或选项卡的简洁替代方案，内置滑动动画、自定义样式和主题支持。

命名空间： Syncfusion.UI.Xaml.Editors
NuGet 包： Syncfusion.Editors.WinUI
平台： WinUI 3 Desktop（.NET 5+、Windows App SDK 1.0+）

主要优势： 提供现代化的 iOS 风格分段选择器，具备滑动动画、阴影效果和丰富的自定义选项，非常适合在不使用复杂 UI 的情况下紧凑地选择选项。

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置（Syncfusion.Editors.WinUI）
• 命名空间导入（Syncfusion.UI.Xaml.Editors）
• SfSegmentedControl 基本初始化
• 使用字符串集合填充（内联 x:String 项）
• 使用业务对象填充（ItemsSource、DisplayMemberPath）
• 用于自定义 UI 的 ItemTemplate（图标、图像、文本）
• 首个包含 ViewModel 的完整示例
• 许可证注册

选择功能

📄 阅读： references/selection.md

• 用于程序化选择的 SelectedIndex 属性
• SelectedItem 属性和双向绑定
• 带有 NewValue 和 OldValue 的 SelectionChanged 事件
• 以编程方式处理选择（按索引、按项、循环选择）

📄 阅读： references/selection-styling.md

• 自定义 SelectedSegmentStyle
• 对选中项应用阴影效果（HasShadow、ShadowColor）
• 选择动画（Slide 或 None）和 SelectionAnimationType 属性
• 键盘导航（方向键、Tab、Enter）
• 选择最佳实践

禁用项

📄 阅读： references/disable-items.md

• 使用 SetItemEnabled 方法按条件禁用
• 按索引禁用分段
• 禁用项的视觉效果
• 阻止用户与特定分段交互
• 常见模式（表单验证、条件可用性）

UI 自定义

📄 阅读： references/ui-customization.md

• BorderThickness 和 ItemBorderThickness
• 自定义控件和项的 CornerRadius
• 自定义 BorderBrush 颜色
• 使用 ItemContainerStyle 为每个项设置样式
• 使用 ItemTemplateSelector 选择条件模板
• 使用 ItemContainerStyleSelector 选择条件样式
• UI 样式最佳实践

📄 阅读： references/custom-templates.md

• 椭圆形（胶囊）样式模板
• 圆形颜色样本样式模板
• 图像与文本垂直堆叠布局模板
• 顶部指示器（选项卡栏）样式模板
• 渐变背景模板

主题支持

📄 阅读： references/themes.md

• 在 App.xaml 中设置 RequestedTheme（Dark/Light）
• 使用键进行主题自适应自定义
• 12 个主题资源键，支持完整控制
• SyncfusionSegmentedControl* 主题键
• 浅色和深色主题示例
• ResourceDictionary.ThemeDictionaries 结构

快速入门示例

使用字符串的基本分段控件

<Window xmlns:syncfusion="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <syncfusion:SfSegmentedControl 
            x:Name="segmentedControl"
            HorizontalAlignment="Center"
            VerticalAlignment="Center"
            SelectedIndex="0">
            <x:String>Day</x:String>
            <x:String>Week</x:String>
            <x:String>Month</x:String>
            <x:String>Year</x:String>
        </syncfusion:SfSegmentedControl>
    </Grid>
</Window>

使用业务对象和 ViewModel

// ViewModel
public class SegmentedViewModel
{
    public ObservableCollection<PeriodModel> Periods { get; set; }
    
    public SegmentedViewModel()
    {
        Periods = new ObservableCollection<PeriodModel>
        {
            new PeriodModel { Name = "Day" },
            new PeriodModel { Name = "Week" },
            new PeriodModel { Name = "Month" },
            new PeriodModel { Name = "Year" }
        };
    }
}

public class PeriodModel
{
    public string Name { get; set; }
}

<syncfusion:SfSegmentedControl 
    ItemsSource="{Binding Periods}"
    DisplayMemberPath="Name"
    SelectedIndex="2"/>

常见模式

1. 视图模式切换器

<syncfusion:SfSegmentedControl SelectedIndex="0" SelectionChanged="ViewMode_Changed">
    <x:String>List</x:String>
    <x:String>Grid</x:String>
    <x:String>Timeline</x:String>
</syncfusion:SfSegmentedControl>

private void ViewMode_Changed(object sender, SegmentSelectionChangedEventArgs e)
{
    string selectedMode = e.NewValue as string;
    UpdateViewMode(selectedMode);
}

适用场景： 在不同的显示模式或布局之间切换。

2. 带选中状态的筛选栏

<syncfusion:SfSegmentedControl 
    ItemsSource="{Binding FilterOptions}"
    DisplayMemberPath="Label"
    SelectedIndex="{Binding SelectedFilterIndex, Mode=TwoWay}"/>

适用场景： 按类别筛选数据，并显示选中状态。

3. 使用 ItemTemplate 的自定义图标分段

<syncfusion:SfSegmentedControl ItemsSource="{Binding Items}">
    <syncfusion:SfSegmentedControl.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <Path Data="{Binding Icon}" Fill="{Binding IconColor}" Width="16" Height="16"/>
                <TextBlock Text="{Binding Name}" Margin="6,0,0,0"/>
            </StackPanel>
        </DataTemplate>
    </syncfusion:SfSegmentedControl.ItemTemplate>
</syncfusion:SfSegmentedControl>

适用场景： 使用图标或图像的分段，以提升视觉识别度。

4. 禁用不可用选项的分段

segmentedControl.SetItemEnabled(2, false); // Disable "Premium" option
segmentedControl.SetItemEnabled(3, false); // Disable "Enterprise" option

适用场景： 根据用户权限或应用状态，有条件地禁用选项。

5. 带阴影的自定义选中样式

<syncfusion:SfSegmentedControl SelectedIndex="1">
    <syncfusion:SfSegmentedControl.SelectedSegmentStyle>
        <Style TargetType="syncfusion:SelectedSegmentBorder">
            <Setter Property="Background" Value="#6C58EA"/>
            <Setter Property="HasShadow" Value="True"/>
            <Setter Property="ShadowColor" Value="#6C58EA"/>
            <Setter Property="CornerRadius" Value="8"/>
        </Style>
    </syncfusion:SfSegmentedControl.SelectedSegmentStyle>
</syncfusion:SfSegmentedControl>

适用场景： 为选中的分段增添层次感和现代外观。

6. 关闭动画以实现即时选择

<syncfusion:SfSegmentedControl 
    SelectionAnimationType="None"
    SelectedIndex="0">
    <x:String>Option 1</x:String>
    <x:String>Option 2</x:String>
    <x:String>Option 3</x:String>
</syncfusion:SfSegmentedControl>

适用场景： 滑动动画对于快速选择来说太慢或容易分散注意力时。

关键属性

属性	类型	默认值	描述
ItemsSource	IEnumerable	null	用作分段显示的项目集合。
DisplayMemberPath	string	null	要从业务对象中显示的属性路径。
ItemTemplate	DataTemplate	null	用于呈现每个分段项目的自定义模板。
SelectedIndex	int	0	当前选中分段的索引（从 0 开始）。
SelectedItem	object	null	ItemsSource 中当前选中的项目。
SelectionAnimationType	SegmentSelectionAnimationType	Slide	选中状态转换的动画类型（Slide 或 None）。
SelectedSegmentStyle	Style	Default	选中分段边框的样式（SelectedSegmentBorder 目标）。
ItemContainerStyle	Style	Default	每个 SfSegmentedItem 容器的样式。
ItemTemplateSelector	DataTemplateSelector	null	用于条件选择项目模板的选择器。
ItemContainerStyleSelector	StyleSelector	null	用于条件选择项目样式的选择器。
BorderThickness	Thickness	1	控件的边框粗细。
ItemBorderThickness	Thickness	0,0,1,0	分段项目之间的边框粗细。
CornerRadius	CornerRadius	0	控件的圆角半径。
BorderBrush	Brush	Default	控件的边框颜色。

关键事件

事件	描述
SelectionChanged	选中项更改时触发。通过 SegmentSelectionChangedEventArgs 提供 NewValue 和 OldValue。

关键方法

方法	描述
SetItemEnabled(int index, bool isEnabled)	启用或禁用指定索引处的分段项目。

常见用例

视图切换器

• 列表／网格／时间线视图切换
• 日历视图模式（日／周／月／年）
• 地图视图类型（标准／卫星／混合）
• 图表类型（折线／条形／饼图）

最佳方式： 使用字符串项目，或将 DisplayMemberPath 与 SelectionChanged 事件处理程序配合使用。

筛选栏

• 状态筛选（全部／进行中／已完成／已归档）
• 优先级筛选（低／中／高／紧急）
• 类别筛选（文档／图像／视频／音频）
• 时间段筛选（今天／周／月／年）

最佳方式： 绑定到 ObservableCollection，并通过双向绑定使用 SelectedIndex。

设置切换器

• 隐私级别（公开／好友／私密）
• 通知偏好设置（全部／重要／无）
• 语言选择（英语／西班牙语／法语）
• 主题选择（自动／浅色／深色）

最佳方式： 使用 SelectionChanged 立即更新应用设置。

类标签页导航

• 紧凑的分区导航（信息／详情／评价）
• 表单步骤指示器（个人信息／地址／付款）
• 个人资料标签页（帖子／简介／照片）

最佳方式： 配合自定义 ItemTemplate 显示图标，并禁用动画以实现即时切换。

仪表板控件

• 日期范围选择器（1D/1W/1M/3M/1Y）
• 数据源切换项（本地/云端/全部）
• 报告类型选择器
• 比较模式切换项

最佳做法： 启用阴影效果，并使用与仪表板主题相匹配的自定义颜色。

实现技巧

1. 项目数量： 最适合包含 2-7 个分段。项目更多时，可能需要滚动或使用其他控件。

2. 选择处理： 使用 SelectionChanged 事件立即响应。使用 SelectedIndex 进行 MVVM 绑定。

3. 禁用项目： 设置 ItemsSource 后，使用 SetItemEnabled()。如果绑定到 ViewModel，请在 Loaded 事件中调用。

4. 自定义样式： 设置 ItemContainerStyle 以保持间距统一。使用 SelectedSegmentStyle 设置选中状态的外观。

5. 动画： 滑动动画（默认）可实现平滑过渡。在表单中选择时，可使用 None 实现即时切换。

6. 键盘支持： 使用方向键导航，按 Enter 选择。确保设置 TabIndex，以实现正确的焦点移动顺序。

7. 主题支持： 在 Resources 中使用主题键，确保浅色/深色主题的外观一致。

8. ItemTemplate： 可用于图标、图像或复杂布局。模板应保持简单，以确保性能。

9. 边框自定义： 设置 ItemBorderThickness="0" 可实现无缝分段。使用 BorderThickness 设置外边框。

10. CornerRadius： 使控件和项目的 CornerRadius 保持一致，以实现统一的圆角外观。

相关文档

• 入门指南： 请参阅 references/getting-started.md，了解设置和基本用法
• 选择属性和事件： 请参阅 references/selection.md，了解 SelectedIndex、SelectedItem、SelectionChanged 和以编程方式进行选择
• 选择样式和键盘操作： 请参阅 references/selection-styling.md，了解 SelectedSegmentStyle、阴影、动画、键盘导航和最佳做法
• 禁用项目： 请参阅 references/disable-items.md，了解如何有条件地禁用分段
• UI 自定义： 请参阅 references/ui-customization.md，了解边框、圆角、选择器和最佳做法
• 自定义模板： 请参阅 references/custom-templates.md，了解椭圆、圆形、图像+文本、顶部指示器和渐变模板
• 主题： 请参阅 references/themes.md，了解主题支持和自定义键