# ButtonSpinner 使用文档
本文档介绍 AtomUI ButtonSpinner 控件的各种使用方式，示例代码摘自 Gallery 演示程序。
> 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/Navigation/ButtonSpinnerShowCase.axaml`
---
## 前置准备
在 AXAML 中使用 ButtonSpinner，需要引入以下命名空间：
```xml
xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"
```
在 C# 代码中引入：
```csharp
using AtomUI.Desktop.Controls; // ButtonSpinner, ButtonSpinnerLocation
using AtomUI.Controls; // SizeType, InputControlStyleVariant, InputControlStatus
using Avalonia.Controls.Primitives; // SpinEventArgs, SpinDirection
```
---
## 1. 基本用法
最简单的 ButtonSpinner 包裹一段文本内容，右侧自带上下操作按钮：
```xml
```
---
## 2. 三种尺寸
通过 `SizeType` 属性设置控件尺寸，支持 `Large`（40px）、`Middle`（32px，默认）、`Small`（24px）三种。
```xml
```
---
## 3. 样式变体
通过 `StyleVariant` 属性设置样式变体，支持 `Outline`（线框，默认）、`Filled`（填充）、`Borderless`（无边框）三种。
```xml
```
---
## 4. 禁用状态
通过 `IsEnabled="False"` 禁用控件，三种样式变体均支持：
```xml
```
---
## 5. 前后附加组件（AddOn）
通过 `LeftAddOn` 和 `RightAddOn` 在输入框外部添加文字或图标附加组件：
```xml
```
---
## 6. 前后缀（Prefix / Suffix）
通过 `InnerLeftContent` 和 `InnerRightContent` 在输入区域内部添加前缀和后缀：
```xml
```
---
## 7. 验证状态
通过 `Status` 属性设置 Error 或 Warning 状态，搭配三种样式变体使用：
```xml
```
---
## 8. Spin 事件处理
ButtonSpinner 自身不管理数值，通过 `Spin` 事件将增减意图传递给外部：
```xml
```
```csharp
// Code-behind
private int _currentValue = 0;
private void HandleSpin(object? sender, SpinEventArgs e)
{
if (e.Direction == SpinDirection.Increase)
{
_currentValue++;
}
else
{
_currentValue--;
}
// 更新 UI...
}
```
### 使用 ValidSpinDirection 限制方向
```xml
```
---
## 9. 控制操作按钮
### 隐藏操作按钮
```xml
```
### 禁止 Spin
```xml
```
### 操作按钮放在左侧
```xml
```
### 浮动操作按钮
```xml
```
---
## 10. 控制动画
```xml
```
---
## 常见组合模式
### 自定义数值输入器
```xml
```
### 带单位的数值调整
```xml
```
### 紧凑布局组合
```xml
```