syncfusion-winui-segmented-control

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing WinUI Segmented Control

实现WinUI分段控件

When to Use This Skill

何时使用本指南

Use this skill when the user needs to:

Create a segmented control or segment picker UI
Implement mutually exclusive option selection
Build tab-like navigation without full TabControl
Create filter bars or view mode switchers
Display 2+ linear options where only one can be selected
Add animated selection transitions (slide effect)
Create custom segment styles (ellipse, circle, top indicator)
Implement keyboard navigation for segment selection
Disable specific segments conditionally
Support both light and dark themes

Always apply this skill when the user mentions: segmented control, segment picker, option selector, filter bar, view switcher, tab selector, mutually exclusive buttons, or segment-based navigation in WinUI applications.

当用户有以下需求时可使用本指南：

创建分段控件或分段选择器UI
实现互斥选项选择功能
构建无需完整TabControl的类标签导航
创建过滤栏或视图模式切换器
展示2个及以上线性排列的单选选项
添加选择动画过渡（滑动效果）
自定义分段样式（椭圆、圆形、顶部指示器）
实现分段选择的键盘导航
按条件禁用特定分段
同时支持明暗主题

当用户提到WinUI应用中的分段控件、分段选择器、选项选择器、过滤栏、视图切换器、标签选择器、互斥按钮或分段式导航时，务必使用本指南。

Component Overview

组件概述

SfSegmentedControl is a Syncfusion WinUI control that provides a simple way to choose from a linear set of two or more segments, each functioning as a mutually exclusive option. It offers a clean alternative to radio buttons or tabs with built-in slide animation, custom styling, and theme support.

Namespace:

Syncfusion.UI.Xaml.Editors

NuGet Package:

Syncfusion.Editors.WinUI

Platform: WinUI 3 Desktop (.NET 5+, Windows App SDK 1.0+)

Key Advantage: Provides a modern, iOS-style segmented picker with slide animation, shadow effects, and extensive customization—ideal for compact option selection without complex UI.

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

命名空间：

Syncfusion.UI.Xaml.Editors

NuGet包：

Syncfusion.Editors.WinUI

支持平台： WinUI 3 桌面端（.NET 5+，Windows App SDK 1.0+）

核心优势： 提供现代化的iOS风格分段选择器，支持滑动动画、阴影效果和高度自定义，非常适合无需复杂UI的紧凑型选项选择场景。

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and NuGet package setup (Syncfusion.Editors.WinUI)
Namespace imports (Syncfusion.UI.Xaml.Editors)
Basic SfSegmentedControl initialization
Populating with string collections (inline x:String items)
Populating with business objects (ItemsSource, DisplayMemberPath)
ItemTemplate for custom UI (icons, images, text)
First complete example with ViewModel
License registration

📄 阅读： references/getting-started.md

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

Selection Features

选择功能

📄 Read: references/selection.md

SelectedIndex property for programmatic selection
SelectedSegmentStyle customization
Shadow effects on selected items (HasShadow, ShadowColor)
Selection animations (Slide vs None)
SelectionAnimationType property
Keyboard navigation (Arrow keys, Tab, Enter)
SelectionChanged event with NewValue and OldValue
Handling selection programmatically

📄 阅读： references/selection.md

用于编程式选择的SelectedIndex属性
SelectedSegmentStyle自定义
选中项的阴影效果（HasShadow、ShadowColor）
选择动画（滑动/无动画）
SelectionAnimationType属性
键盘导航（方向键、Tab、Enter）
携带NewValue和OldValue的SelectionChanged事件
编程式处理选择逻辑

Disabling Items

禁用项功能

📄 Read: references/disable-items.md

SetItemEnabled method for conditional disabling
Disabling segments by index
Visual appearance of disabled items
Preventing user interaction with specific segments
Common patterns (form validation, conditional availability)

📄 阅读： references/disable-items.md

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

UI Customization

UI自定义

📄 Read: references/ui-customization.md

BorderThickness and ItemBorderThickness
CornerRadius customization for control and items
BorderBrush color customization
ItemContainerStyle for per-item styling
ItemTemplateSelector for conditional templates
ItemContainerStyleSelector for conditional styles
Custom templates (ellipse, circle, image+text, top indicator)
Advanced styling patterns

📄 阅读： references/ui-customization.md

BorderThickness和ItemBorderThickness
控件与项的CornerRadius自定义
BorderBrush颜色自定义
针对单项样式的ItemContainerStyle
用于条件模板的ItemTemplateSelector
用于条件样式的ItemContainerStyleSelector
自定义模板（椭圆、圆形、图文、顶部指示器）
高级样式设计模式

Theme Support

主题支持

📄 Read: references/themes.md

RequestedTheme in App.xaml (Dark/Light)
Theme-aware customization using keys
12 theme resource keys for complete control
SyncfusionSegmentedControl* theme keys
Light and Dark theme examples
ResourceDictionary.ThemeDictionaries structure

📄 阅读： references/themes.md

App.xaml中的RequestedTheme（暗/亮）
使用键实现主题感知自定义
12个主题资源键实现完全控制
SyncfusionSegmentedControl*系列主题键
明暗主题示例
ResourceDictionary.ThemeDictionaries结构

Quick Start Example

快速入门示例

Basic Segmented Control with Strings

基础字符串分段控件

xaml

<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>

xaml

<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>

With Business Objects and ViewModel

结合业务对象与ViewModel

csharp

// 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; }
}

xaml

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

csharp

// 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; }
}

xaml

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

Common Patterns

常见使用模式

1. View Mode Switcher

1. 视图模式切换器

xaml

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

csharp

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

When to use: Switching between different display modes or layouts.

xaml

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

csharp

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

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

2. Filter Bar with Selection

2. 带选择功能的过滤栏

xaml

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

When to use: Filtering data by category with visible selection state.

xaml

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

适用场景： 按类别过滤数据，同时展示可见的选择状态。

3. Custom Icon Segments with ItemTemplate

3. 带ItemTemplate的自定义图标分段

xaml

<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>

When to use: Segments with icons or images for better visual recognition.

xaml

<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. Disabled Segments for Unavailable Options

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

csharp

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

When to use: Conditionally disabling options based on user permissions or app state.

csharp

segmentedControl.SetItemEnabled(2, false); // 禁用「高级」选项
segmentedControl.SetItemEnabled(3, false); // 禁用「企业版」选项

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

5. Custom Selection Style with Shadow

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

xaml

<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>

When to use: Adding visual depth and modern appearance to selected segments.

xaml

<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. No Animation for Instant Selection

6. 无动画的即时选择

xaml

<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>

When to use: When slide animation feels too slow or distracting for rapid selections.

xaml

<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>

适用场景： 滑动动画对于快速选择场景显得过慢或容易造成干扰的情况。

Key Properties

关键属性

Property	Type	Default	Description
`ItemsSource`	IEnumerable	null	Collection of items to display as segments.
`DisplayMemberPath`	string	null	Property path to display from business objects.
`ItemTemplate`	DataTemplate	null	Custom template for rendering each segment item.
`SelectedIndex`	int	0	Index of the currently selected segment (0-based).
`SelectedItem`	object	null	Currently selected item from ItemsSource.
`SelectionAnimationType`	SegmentSelectionAnimationType	Slide	Animation type (Slide or None) for selection transitions.
`SelectedSegmentStyle`	Style	Default	Style for the selected segment border (SelectedSegmentBorder target).
`ItemContainerStyle`	Style	Default	Style for each SfSegmentedItem container.
`ItemTemplateSelector`	DataTemplateSelector	null	Selector for conditional item templates.
`ItemContainerStyleSelector`	StyleSelector	null	Selector for conditional item styles.
`BorderThickness`	Thickness	1	Border thickness of the control.
`ItemBorderThickness`	Thickness	0,0,1,0	Border thickness between segment items.
`CornerRadius`	CornerRadius	0	Corner radius of the control.
`BorderBrush`	Brush	Default	Border color of the control.

属性	类型	默认值	说明
`ItemsSource`	IEnumerable	null	要展示为分段的项集合。
`DisplayMemberPath`	string	null	业务对象中需要展示的属性路径。
`ItemTemplate`	DataTemplate	null	用于渲染每个分段项的自定义模板。
`SelectedIndex`	int	0	当前选中分段的索引（从0开始）。
`SelectedItem`	object	null	ItemsSource中当前选中的项。
`SelectionAnimationType`	SegmentSelectionAnimationType	Slide	选择过渡的动画类型（滑动/无动画）。
`SelectedSegmentStyle`	Style	默认	选中分段边框的样式（目标类型为SelectedSegmentBorder）。
`ItemContainerStyle`	Style	默认	每个SfSegmentedItem容器的样式。
`ItemTemplateSelector`	DataTemplateSelector	null	用于条件选择项模板的选择器。
`ItemContainerStyleSelector`	StyleSelector	null	用于条件选择项样式的选择器。
`BorderThickness`	Thickness	1	控件的边框厚度。
`ItemBorderThickness`	Thickness	0,0,1,0	分段项之间的边框厚度。
`CornerRadius`	CornerRadius	0	控件的圆角半径。
`BorderBrush`	Brush	默认	控件的边框颜色。

Key Events

关键事件

Event	Description
`SelectionChanged`	Fired when selection changes. Provides NewValue and OldValue in SegmentSelectionChangedEventArgs.

事件	说明
`SelectionChanged`	选择发生变化时触发。SegmentSelectionChangedEventArgs中包含NewValue和OldValue参数。

Key Methods

关键方法

Method	Description
`SetItemEnabled(int index, bool isEnabled)`	Enables or disables a segment item at the specified index.

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

Common Use Cases

常见用例

View Switchers

视图切换器

List/Grid/Timeline view toggles
Calendar view modes (Day/Week/Month/Year)
Map view types (Standard/Satellite/Hybrid)
Chart types (Line/Bar/Pie)

Best Approach: Use string items or DisplayMemberPath with SelectionChanged event handler.

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

最佳实现： 使用字符串项或DisplayMemberPath搭配SelectionChanged事件处理函数。

Filter Bars

过滤栏

Status filters (All/Active/Completed/Archived)
Priority filters (Low/Medium/High/Critical)
Category filters (Documents/Images/Videos/Audio)
Time period filters (Today/Week/Month/Year)

Best Approach: Bind to ObservableCollection, use SelectedIndex with two-way binding.

状态过滤（全部/活跃/已完成/已归档）
优先级过滤（低/中/高/紧急）
类别过滤（文档/图片/视频/音频）
时间段过滤（今日/本周/本月/本年）

最佳实现： 绑定到ObservableCollection，使用双向绑定的SelectedIndex。

Settings Toggles

设置项切换

Privacy levels (Public/Friends/Private)
Notification preferences (All/Important/None)
Language selection (English/Spanish/French)
Theme selection (Auto/Light/Dark)

Best Approach: Use SelectionChanged to update app settings immediately.

隐私等级（公开/好友可见/私密）
通知偏好（全部/重要/关闭）
语言选择（英语/西班牙语/法语）
主题选择（自动/亮色/暗色）

最佳实现： 使用SelectionChanged事件即时更新应用设置。

Tab-like Navigation

类标签导航

Compact section navigation (Info/Details/Reviews)
Form step indicators (Personal/Address/Payment)
Profile tabs (Posts/About/Photos)

Best Approach: Use with custom ItemTemplate for icons, disable animation for instant switching.

紧凑型分区导航（信息/详情/评论）
表单步骤指示器（个人信息/地址/支付）
个人主页标签（动态/关于/照片）

最佳实现： 搭配自定义ItemTemplate实现图标展示，关闭动画实现即时切换。

Dashboard Controls

仪表盘控件

Date range selectors (1D/1W/1M/3M/1Y)
Data source toggles (Local/Cloud/All)
Report type selectors
Comparison mode toggles

Best Approach: Enable shadow effects, use custom colors matching dashboard theme.

日期范围选择器（1天/1周/1月/3月/1年）
数据源切换（本地/云端/全部）
报表类型选择器
对比模式切换

最佳实现： 开启阴影效果，使用匹配仪表盘主题的自定义颜色。

Implementation Tips

实现提示

Item Count: Best for 2-7 segments. More items may require scrolling or alternative control.
Selection Handling: Use SelectionChanged event for immediate reactions. Bind SelectedIndex for MVVM.
Disabled Items: Use SetItemEnabled() after ItemsSource is set. Call in Loaded event if binding to ViewModel.
Custom Styling: Set ItemContainerStyle for uniform spacing. Use SelectedSegmentStyle for selection appearance.
Animation: Slide animation (default) provides smooth transitions. Use None for instant selection in forms.
Keyboard Support: Arrow keys navigate, Enter selects. Ensure TabIndex is set for proper focus flow.
Theme Support: Use theme keys in Resources for consistent Light/Dark theme appearance.
ItemTemplate: Use for icons, images, or complex layouts. Keep templates simple for performance.
Border Customization: Set ItemBorderThickness="0" for seamless segments. Use BorderThickness for outer border.
CornerRadius: Match control and item CornerRadius for consistent rounded appearance.

项数量： 最适合2-7个分段的场景。项过多时可能需要滚动功能或更换其他控件。
选择处理： 需要即时响应时使用SelectionChanged事件，MVVM模式下绑定SelectedIndex即可。
禁用项： 要在ItemsSource设置完成后调用SetItemEnabled()。如果绑定到ViewModel，请在Loaded事件中调用。
自定义样式： 如需统一间距可设置ItemContainerStyle，如需调整选中态外观可使用SelectedSegmentStyle。
动画： 默认的滑动动画可提供流畅的过渡效果。表单场景下如需即时选择可设置为无动画。
键盘支持： 方向键可导航，Enter键可选择。请正确设置TabIndex以保证焦点流转符合预期。
主题支持： 在资源中使用主题键可保证明暗主题下的外观一致性。
ItemTemplate： 可用于实现图标、图片或复杂布局，为保证性能请尽量保持模板简洁。
边框自定义： 如需无缝分段可设置ItemBorderThickness="0"，如需外边框可设置BorderThickness。
CornerRadius： 请保持控件和项的CornerRadius一致，以获得统一的圆角外观。

syncfusion-winui-segmented-control

Original

Translation

Implementing WinUI Segmented Control

实现WinUI分段控件

When to Use This Skill

何时使用本指南

Component Overview

组件概述

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

Selection Features

选择功能

Disabling Items

禁用项功能

UI Customization

UI自定义

Theme Support

主题支持

Quick Start Example

快速入门示例

Basic Segmented Control with Strings

基础字符串分段控件

With Business Objects and ViewModel

结合业务对象与ViewModel

Common Patterns

常见使用模式

1. View Mode Switcher

1. 视图模式切换器

2. Filter Bar with Selection

2. 带选择功能的过滤栏

3. Custom Icon Segments with ItemTemplate

3. 带ItemTemplate的自定义图标分段

4. Disabled Segments for Unavailable Options

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

5. Custom Selection Style with Shadow

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

6. No Animation for Instant Selection

6. 无动画的即时选择

Key Properties

关键属性

Key Events

关键事件

Key Methods

关键方法

Common Use Cases

常见用例

View Switchers

视图切换器

Filter Bars

过滤栏

Settings Toggles

设置项切换

Tab-like Navigation

类标签导航

Dashboard Controls

仪表盘控件

Implementation Tips

实现提示

Related Documentation

相关文档