AtomUI/docs/controls/desktop/data-entry/toggle-switch/implementation.md

# ToggleSwitch 桌面版实现原理

本文档描述 ToggleSwitch 桌面版的内部布局、状态流转、模板接入、加载动画、内容绑定、Form 和 Token 使用。公共设计与 API 契约见 [ToggleSwitch 桌面版架构设计](overview.md)，Token 语义见 [ToggleSwitch Token 设计](token.md)，变化记录见 [ToggleSwitch Changelog](changelog.md)。

## 1. 实现定位

ToggleSwitch 的 public 桌面类型位于 `AtomUI.Desktop.Controls`，实际交互和布局实现位于 `AtomUI.Controls.AbstractToggleSwitch`。桌面层通过 `ToggleSwitchToken` 和主题文件提供 参考设计体系 风格视觉。本文档聚焦 AtomUI 增强层，不重新说明 Avalonia `ToggleButton` 的基础点击和键盘切换算法。

## 2. 源码文件结构

主要源码：

- `src/AtomUI.Desktop.Controls/Switch/ToggleSwitch.cs`：public 桌面控件，注册 `ToggleSwitchToken` resource scope。
- `src/AtomUI.Controls/Switch/AbstractToggleSwitch.cs`：公共 API、测量、布局、内容绑定、loading、hit test、Form 和渲染主逻辑。
- `src/AtomUI.Controls/Switch/SwitchKnob.cs`：把手绘制、加载指示绘制、把手宽度动画和加载动画生命周期。
- `src/AtomUI.Desktop.Controls/Switch/ToggleSwitchToken.cs`：ToggleSwitch 控件级 Token。
- `src/AtomUI.Desktop.Controls/Switch/Themes/ToggleSwitchTheme.axaml`：主模板、状态 selector、SizeType 分支和 Token 引用。
- `src/AtomUI.Desktop.Controls/Switch/Themes/SwitchKnobTheme.axaml`：把手主题、加载动画周期和动效。

## 3. 核心类职责

`ToggleSwitch` 是桌面包对外入口。它不新增 API，也不重写布局和交互，只把实例接入 `ToggleSwitchToken` scope。

`AbstractToggleSwitch` 是状态和布局核心。它负责读取 `IsChecked`、`IsLoading`、`SizeType`、`OnContent`、`OffContent` 等状态，计算轨道尺寸、把手位置、内容偏移和 Form value。

`SwitchKnob` 是内部把手。它根据 `KnobSize` 和 `KnobRenderWidth` 绘制圆形或胶囊把手，在 loading 状态下绘制旋转 loading arc。

`WaveSpiritDecorator` 是视觉效果边界，只在 checked 状态变化且 `IsWaveSpiritEnabled=true` 时播放，不参与值状态计算。

## 4. 状态与数据流

基础状态流：

```text
IsChecked / IsPressed / SizeType / content / token
      ↓
MeasureOverride
      ↓
Track size + content desired size
      ↓
CalculateElementsOffset
      ↓
KnobRect + KnobMovingRect + OnContentOffset + OffContentOffset
      ↓
ArrangeOverride + Render
```

checked 变化时，如果启用 motion，控件先基于当前 groove size 重新计算元素位置，再由 `RectTransition` 和 `PointTransition` 执行动画。`_isCheckedChanged` 用于让 arrange 阶段在 checked 切换后使用 `KnobMovingRect`，保持过渡位置一致。

loading 状态流：

```text
IsLoading changed
  → HandleLoadingState
  → set cursor local value / dispose cursor local value
  → SwitchKnob.NotifyStartLoading / NotifyStopLoading
```

Form 状态流：

```text
Form.SetValue(bool?) → IsChecked
IsChecked changed    → Form ValueChanged
Form.GetValue()      → IsChecked
Form.ClearValue()    → IsChecked = null
```

## 5. 生命周期与模板接入

`OnApplyTemplate` 获取以下稳定 part：

- `PART_SwitchKnob`
- `PART_OnContentPresenter`
- `PART_OffContentPresenter`
- `PART_WaveSpirit`
- `PART_MainContainer`

模板接入后，控件把当前 `KnobSize` 写入 `SwitchKnob`，再根据当前 `IsLoading` 同步把手 loading 状态。模板 part 没有全局事件订阅，主要生命周期风险来自内容图标 relay binding 和 loading animation。

内容变化时，`SetupContent` 会释放旧 on/off 内容对应的 `CompositeDisposable`，再为新的 `PathIcon` / `Icon` 建立尺寸和前景色绑定。维护时必须保持内容替换和 disposable 释放成对出现。

`SwitchKnob` 在 `OnAttachedToVisualTree` 中根据 `_isLoading` 启动加载动画，在 `OnDetachedFromVisualTree` 中取消并释放 `CancellationTokenSource`。加载旋转使用共享无限动画 helper，并显式采用 `PlaybackBehavior.OnlyIfVisible`；ToggleSwitch 自身或 Visual 祖先不可见时 animation clock 暂停，重新可见后继续。

## 6. 交互与事件处理

Pointer press 流程：

```text
OnPointerPressed
  → if !IsLoading then base.OnPointerPressed
  → if knob not mid-animation
  → _isCheckedChanged=false
  → AdjustOffsetOnPressed
```

Pointer release 流程：

```text
OnPointerReleased
  → if !IsLoading then base.OnPointerReleased
  → AdjustOffsetOnReleased
  → InvalidateArrange
```

loading 状态下 pointer press/release 不进入基类逻辑，因此不会切换 `IsChecked`。键盘切换仍来自 `ToggleButton` 基类，维护 loading 行为时必须确认键盘路径也不产生业务不一致。

`HitTest(Point)` 只在控件 enabled 且非 loading 时返回 groove rect 命中结果。该接口用于自定义命中测试，不应把内容 presenter 或 wave 外扩区域作为可点击范围。

## 7. 内部算法与关键流程

### 7.1 测量与宽度计算

测量阶段分别测量 on/off content presenter，取二者最大宽度作为内容宽度，再叠加 `InnerMinMargin` 和 `InnerMaxMargin`。最终宽度取该值与 `TrackMinWidth` 的较大值，高度使用 `TrackHeight`。

### 7.2 把手位置

`HandleRect(bool isChecked, Size controlSize)` 根据 checked 状态计算把手左上角。unchecked 时把手位于左侧 `TrackPadding`，checked 时位于 `controlSize.Width - TrackPadding - handleSize`。按下时把手宽度乘以 `STRETCH_FACTOR`。

### 7.3 内容偏移

`ExtraInfoRect` 根据当前状态和内部边距计算内容区域。checked 时 on content 进入可见区域，off content 移到右侧不可见区域；unchecked 时反向处理。内容偏移使用 `PointTransition` 过渡。

### 7.4 轨道绘制

`AbstractToggleSwitch.Render` 使用 `DrawPilledRect` 绘制轨道，并通过 `SwitchOpacity` 控制 disabled/loading 透明度。轨道背景来自 `GrooveBackground`，通常由主题 selector 设置。

### 7.5 把手与 loading 绘制

`SwitchKnob.Render` 根据 `KnobRenderWidth` 和高度判断绘制圆形或胶囊把手。loading 状态下，按当前 `Rotation` 绘制 90 度 arc。`GetLoadIndicatorPen` 缓存 pen，并在 brush 引用变化时重建。

## 8. 资源、性能与 AOT 边界

ToggleSwitch 不通过反射访问模板结构。模板结构由稳定 part 和 AXAML `TemplateBinding` 表达。

资源与生命周期边界：

- on/off 图标内容的 relay binding 必须在内容替换时释放。
- `IsLoading` 设置的 cursor local value 必须在退出 loading 时 dispose。
- `SwitchKnob` 的 loading `CancellationTokenSource` 必须在停止 loading 和 detach 时释放。
- 隐藏祖先下的 loading animation 不得继续推进 animation clock。
- Token 只表达尺寸、颜色、阴影、字体和加载动画周期，不承载 `IsChecked`、`IsLoading` 或内容实例状态。

当前图标内容绑定使用 C# relay binding，因为目标对象来自用户提供的 runtime content，不是稳定模板 part。模板内部固定关系应继续优先使用 AXAML binding 和 selector。

AOT 边界：

- Token 类型通过 generator 显式注册。
- API 与 Token 契约由控件文档、源码 public surface、Token 类型或生成数据维护。
- 文档中列出的 part 名称必须与 AXAML 和 C# 查找代码一致。

## 9. 维护不变量

内部重构必须保持以下不变量：

- `ToggleSwitch` public 类型保持轻量桌面入口，不把共享实现复制到 Desktop 包。
- `AbstractToggleSwitch` 继续作为 API 和状态核心。
- loading 不触发新切换，并释放 cursor local value 和 animation token。
- 内容图标 relay binding 在内容替换时释放。
- `MeasureOverride` 必须同时考虑 on/off content 的最大宽度。
- `SwitchKnob` loading animation detach 时必须取消。
- `SizeType=Custom` 默认与 Middle 视觉一致。
- `SwitchOpacity` 只表达 disabled/loading 视觉透明度，不改变 enabled 状态。
- WaveSpirit 只作为视觉反馈，不影响 `IsChecked`。

## 10. 测试与验证

验证范围：

- checked、unchecked、null 绑定和 Form 读写清空。
- loading 状态下 pointer 和命中测试不触发切换。
- loading attach/detach 不泄漏动画 token。
- `OnContent` / `OffContent` 为文本和图标时的测量、偏移、前景色和尺寸同步。
- Large / Middle / Small / Custom 下的高度、最小宽度、内容边距和图标尺寸。
- disabled、pointerover、pressed、checked 和 unchecked 主题 selector。
- WaveSpirit 开关不改变值状态。
- Gallery ToggleSwitch 示例、源码片段。
- 文档改动运行 `git diff --check`，并检查相对链接存在。