AtomUI/docs/Desktop.Controls/Segmented/Segmented.md

Segmented 分段控制器

概述

分段控制器（Segmented）用于在少量互斥选项之间进行快速切换。它在视觉上提供比 RadioButton 更强的操作感和辨识度，类似于 iOS/macOS 的 SegmentedControl。用户通过点击不同的分段来切换当前选中项，被选中的分段通过一个带有投影的**滑动色块（Thumb）**来标识，选中态切换时色块会平滑动画滑动到目标位置。

AtomUI 的 Segmented 控件完整复刻了 Ant Design 5.0 Segmented 的设计规范，在 .NET / Avalonia 平台上提供与 Ant Design React 版一致的视觉体验和交互行为。

---

设计原理

Ant Design 的分段控制器设计哲学

Ant Design 对 Segmented 的定位是：「分段控制器。当用户需要在几个互斥的选项之间进行选择时使用，相比 Radio 按钮有更强的视觉感知」。典型应用场景包括：

• 视图模式切换（列表视图 / 卡片视图 / 网格视图）
• 时间维度切换（日 / 周 / 月 / 季 / 年）
• 数据分类筛选（全部 / 待处理 / 已完成）
• 简单的标签页导航

核心设计特征：

特征	说明
🔘 互斥单选	始终有且仅有一个选项被选中，首次渲染默认选中第一项
🎯 滑动色块	选中项通过一个独立的色块（Thumb）标识，切换时色块平滑滑动到新位置
📏 三种尺寸	Large / Middle / Small，与全局尺寸体系一致
🔲 Block 模式	可撑满父容器，选项均分宽度
🖼️ 图标支持	每个选项可包含图标，或仅显示图标
🚫 逐项禁用	可单独禁用某些选项

Avalonia 基础能力

AtomUI 的 Segmented 控件基于 Avalonia 的 SelectingItemsControl。理解 Avalonia 提供的基础能力有助于理解 AtomUI 在其之上做了哪些扩展。

Avalonia SelectingItemsControl 的核心职责：

SelectingItemsControl 继承自 ItemsControl，增加了选择管理能力。它维护 SelectedItem / SelectedIndex 等选择状态，并通过 SelectionChanged 事件通知外部。其继承链为：

Control → TemplatedControl → ItemsControl → SelectingItemsControl

Avalonia SelectingItemsControl 提供的基础属性：

属性	说明
Items	数据项集合（ItemsControl 基础能力）
ItemTemplate	数据项的 DataTemplate
SelectedIndex	当前选中项的索引
SelectedItem	当前选中的数据对象
SelectionMode	选择模式（Segmented 固定为 Single）
SelectionChanged	选中项变化事件
AutoScrollToSelectedItem	选中时是否自动滚动到选中项（Segmented 默认 false）

AtomUI 的扩展设计

AtomUI Segmented 在 Avalonia SelectingItemsControl 的基础上，遵循 Ant Design 5.0 规范做了以下扩展：

扩展能力	实现方式	设计动机
滑动色块（Thumb）	自定义 Render 方法绘制带圆角和阴影的矩形	复刻 Ant Design 的选中滑块动画效果
色块滑动动画	SelectedThumbPos / SelectedThumbSize + PointTransition / SizeTransition	选中项切换时色块平滑过渡
三种尺寸	ISizeTypeAware 接口 + SizeType 共享属性	全局统一的 Large / Middle / Small 尺寸系统
Block 模式	IsExpanding 属性 + SegmentedStackPanel 自定义布局	选项均分父容器宽度
图标支持	SegmentedItem.Icon 属性 + IconPresenter	每个选项可包含 Ant Design 图标
逐项禁用	各 SegmentedItem 独立的 IsEnabled 属性	灵活控制可用性
默认选中首项	OnApplyTemplate 中检查并设置 SelectedIndex = 0	对齐 Ant Design 默认行为
表单集成	IFormItemAware 接口	可参与 FormItem 验证流程
Design Token	SegmentedToken + RegisterTokenResourceScope	所有视觉值从全局/组件级 Token 派生
过渡动画	IMotionAwareControl + IsMotionEnabled	色块滑动、选项背景色过渡动画可全局开关

---

功能详解

滑动色块（Selected Thumb）

Segmented 最具标志性的视觉特征是滑动色块——一个在选中项后方渲染的带圆角、带阴影的矩形色块。它的行为如下：

• 位置追踪：通过 SelectedThumbPos 和 SelectedThumbSize 记录当前选中项的位置和尺寸
• 平滑动画：当选中项变化时，SelectedThumbPos 通过 PointTransition 动画过渡到新位置，SelectedThumbSize 通过 SizeTransition 动画过渡到新尺寸
• 自定义渲染：在 Render 方法中使用 DrawRectangle 直接绘制色块和容器背景，无需额外的视觉层
• 阴影效果：色块带有 BoxShadowsTertiary 投影，增加立体感

Block 模式（IsExpanding）

当 IsExpanding = true 时：

• Segmented 容器撑满父元素宽度（HorizontalAlignment = Stretch）
• 所有选项均分容器宽度
• 使用 SegmentedStackPanel（自定义 Panel）计算等宽布局

三种尺寸（SizeType）

尺寸通过 SizeType 属性设置，影响容器圆角、选项高度、字体大小和内间距：

尺寸	容器圆角	色块圆角	选项最小高度	字体大小	选项内间距
Large	BorderRadiusLG	BorderRadius	ControlHeightLG - TrackPadding * 2	FontSizeLG	SegmentedItemPadding
Middle	BorderRadius	BorderRadiusSM	ControlHeight - TrackPadding * 2	FontSize	SegmentedItemPadding
Small	BorderRadiusSM	BorderRadiusXS	ControlHeightSM - TrackPadding * 2	FontSize	SegmentedItemPaddingSM

图标支持

每个 SegmentedItem 支持 Icon 属性（PathIcon 类型），可以：

• 仅图标（不设 Content）
• 图标 + 文字（同时设置 Icon 和 Content）

当 Icon 不为 null 时，:has-icon 伪类被激活，文字内容会增加左边距以与图标保持间距。

过渡动画

控件	动画属性	说明
Segmented	SelectedThumbPos、SelectedThumbSize	色块位置和尺寸的平滑过渡
SegmentedItem	Background	选项背景色的平滑过渡（悬浮/按下态变化）

---

与 Ant Design 规范的对齐程度

特性	Ant Design (React)	AtomUI (Avalonia)	对齐情况
基本选项 options	✅ string[] | SegmentedOption[]	✅ SegmentedItem 子项	✅ 完全对齐
选中项 value	✅ 受控属性	✅ SelectedItem / SelectedIndex	✅ 完全对齐
默认选中 defaultValue	✅ 默认值	✅ 默认选中首项	✅ 完全对齐
Block 模式 block	✅ 布尔属性	✅ IsExpanding 属性	✅ 完全对齐
三种尺寸 size	✅ large / middle / small	✅ SizeType 属性	✅ 完全对齐
禁用选项 disabled	✅ 逐项 / 整体禁用	✅ SegmentedItem.IsEnabled	✅ 完全对齐
图标 icon	✅ ReactNode	✅ PathIcon 属性	✅ 对齐（类型不同，语义一致）
选中滑块动画	✅ CSS transition	✅ PointTransition + SizeTransition	✅ 完全对齐
自定义渲染 label	✅ ReactNode	⚠️ 通过 ContentTemplate 部分支持	⚠️ 部分对齐
选项变化回调 onChange	✅ 回调函数	✅ SelectionChanged 事件	✅ 完全对齐

---

继承关系

Segmented

Avalonia.Controls.Primitives.TemplatedControl
  └── Avalonia.Controls.ItemsControl
        └── Avalonia.Controls.SelectingItemsControl
              └── AtomUI.Controls.Commons.AbstractSegmented
                    ├── implements ISizeTypeAware
                    ├── implements IMotionAwareControl
                    ├── implements IFormItemAware
                    └── AtomUI.Desktop.Controls.Segmented

SegmentedItem

Avalonia.Controls.Primitives.TemplatedControl
  └── Avalonia.Controls.ContentControl
        └── AtomUI.Controls.Commons.AbstractSegmentedItem (ISelectable)
              └── AtomUI.Desktop.Controls.SegmentedItem

各层级职责划分：

层级	提供的能力
SelectingItemsControl (Avalonia)	数据项管理、选择状态（SelectedItem / SelectedIndex）、SelectionChanged 事件、容器化（Container Virtualization）
AbstractSegmented (AtomUI.Controls)	滑动色块渲染与动画、SizeType / IsExpanding / IsMotionEnabled 属性、默认选中首项、SegmentedItem 容器准备（传递 SizeType/IsMotionEnabled）、表单集成（IFormItemAware）
Segmented (AtomUI.Desktop.Controls)	Token 作用域注册、创建桌面端 SegmentedItem 容器
ContentControl (Avalonia)	任意内容容纳、Content / ContentTemplate
AbstractSegmentedItem (AtomUI.Controls)	IsSelected / Icon 属性、:pressed / :selected / :has-icon 伪类、鼠标选择交互、背景色过渡动画
SegmentedItem (AtomUI.Desktop.Controls)	Token 作用域注册

实现的共享接口：

接口	定义位置	作用
ISizeTypeAware	AtomUI.Controls.Shared	支持 SizeType（Small / Middle / Large）三种尺寸切换
IMotionAwareControl	AtomUI.Controls	支持 IsMotionEnabled 属性，全局动画开关
IFormItemAware	AtomUI.Controls.Shared	可作为 FormItem 的子控件参与表单验证
ISelectable	Avalonia	支持 IsSelected 属性，参与 SelectingItemsControl 选择逻辑

---

源码位置

基类层（AtomUI.Controls）—— 设备无关

文件路径	说明
src/AtomUI.Controls/Segmented/AbstractSegmented.cs	分段控制器抽象基类：滑块渲染/动画、选择逻辑、尺寸/扩展属性、表单集成
src/AtomUI.Controls/Segmented/AbstractSegmentedItem.cs	分段选项抽象基类：选择状态、图标、伪类管理、背景色过渡
src/AtomUI.Controls/Segmented/SegmentedPseudoClass.cs	共享伪类常量定义（:has-icon）
src/AtomUI.Controls/Segmented/SegmentedStackPanel.cs	自定义布局面板：支持普通水平排列和 Block 等宽排列

平台层（AtomUI.Desktop.Controls）—— 桌面端具体实现

文件路径	说明
src/AtomUI.Desktop.Controls/Segmented/Segmented.cs	桌面端 Segmented：Token 注册、创建 SegmentedItem 容器
src/AtomUI.Desktop.Controls/Segmented/SegmentedItem.cs	桌面端 SegmentedItem：Token 注册
src/AtomUI.Desktop.Controls/Segmented/SegmentedToken.cs	组件级 Design Token
src/AtomUI.Desktop.Controls/Segmented/Themes/SegmentedTheme.axaml	Segmented ControlTheme
src/AtomUI.Desktop.Controls/Segmented/Themes/SegmentedItemTheme.axaml	SegmentedItem ControlTheme
src/AtomUI.Desktop.Controls/Segmented/Themes/SegmentedThemes.axaml	主题资源字典汇总注册
Gallery 示例	controlgallery/AtomUIGallery/ShowCases/Views/DataDisplay/SegmentedShowCase.axaml

---

模板结构

Segmented 模板

Border#Frame (CornerRadius, Padding, ClipToBounds)
└── ItemsPresenter (PART_ItemsPresenter)
    └── SegmentedStackPanel                    ← 自定义布局面板
        ├── SegmentedItem [0]
        ├── SegmentedItem [1]
        ├── SegmentedItem [2]
        └── ...

注意：Segmented 的容器背景和选中色块均通过 Render 方法直接绘制（DrawRectangle），而非通过模板元素。这是因为色块需要在所有选项的"下方"但在容器背景的"上方"渲染，且需要动画支持。

SegmentedItem 模板

Border#Frame (Background, CornerRadius, Padding)
└── DockPanel (LastChildFill=True)
    ├── IconPresenter#IconPresenter            ← 图标展示器（可选，Icon 不为 null 时显示）
    └── ContentPresenter#Content               ← 文字/自定义内容