# ColorPicker 使用文档
本文档介绍 AtomUI ColorPicker 控件的各种使用方式，示例代码摘自 Gallery 演示程序。
> 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/ColorPickerShowCase.axaml`
---
## 前置准备
在 AXAML 中使用 ColorPicker，需要引入以下命名空间：
```xml
xmlns:atom="https://atomui.net"
```
在 C# 代码中引入：
```csharp
using AtomUI.Desktop.Controls; // ColorPicker、GradientColorPicker
using AtomUI.Controls; // SizeType 等共享类型
```
---
## 1. 基本用法
最简单的颜色选择器，点击触发器即可弹出颜色面板：
```xml
```
- `DefaultValue` 设置初始颜色值
- 点击触发器弹出 Flyout 面板，面板中包含色谱、色相滑块、输入框等
---
## 2. 触发器尺寸
通过 `SizeType` 属性设置触发器尺寸，支持 `Small`、`Middle`（默认）、`Large` 三种：
```xml
```
**提示**：尺寸影响触发器色块的大小和内间距，不影响 Flyout 面板的大小。
---
## 3. 受控模式
通过 `ValueSyncStrategy` 属性控制颜色值的同步时机：
| 模式 | 说明 |
|---|---|
| `Immediate`（默认） | 拖动滑块时实时更新 `Value`，触发 `ValueChanged` 事件 |
| `OnCompleted` | 仅在关闭 Flyout 面板时更新 `Value`，触发 `ValueSelected` 事件 |
```xml
```
**使用场景**：
- `Immediate`：需要实时预览颜色效果的场景（如实时修改背景色）
- `OnCompleted`：只在用户确认选择后才生效的场景（如提交表单）
---
## 4. 渐变色选择
使用 `GradientColorPicker` 选取线性渐变色，支持多色标（GradientStop）编辑：
```xml
```
**渐变色选择器面板功能**：
- 渐变预览条：显示当前渐变效果
- 色标指示器：可拖动调整位置，点击选中编辑颜色
- 添加/删除色标
- 色谱和滑块：编辑选中色标的颜色
> 📖 与 Ant Design 的区别：Ant Design 通过 `mode` 属性切换纯色/渐变模式，AtomUI 将其拆分为两个独立控件（`ColorPicker` 和 `GradientColorPicker`），更符合 Avalonia 的类型系统。
---
## 5. 触发器文本
通过 `IsShowText="True"` 在触发器上显示颜色文本值：
```xml
```
### 自定义文本格式化
通过 `ColorTextFormatter` 附加属性自定义触发器文本渲染：
```xml
```
```csharp
// 在 Code-behind 或 ViewModel 中设置
var colorPicker = this.FindControl("CustomRenderText");
ColorPicker.SetColorTextFormatter(colorPicker, (color, format) =>
{
var hex = ColorToHexConverter.ToHexString(color, AlphaComponentPosition.Leading, false, true);
return $"🎨 {hex}";
});
```
**文本内容随 `Format` 属性变化**：
- `Hex`：显示 `#1677ff`
- `Hsva`：显示 `hsva(217, 100%, 100%, 1.00)`
- `Rgba`：显示 `rgba(22, 119, 255, 1.00)`
---
## 6. 禁用状态
通过 `IsEnabled="False"` 禁用颜色选择器：
```xml
```
禁用时触发器变灰，不可点击，Flyout 不会弹出。
---
## 7. 禁用 Alpha 通道
通过 `IsAlphaEnabled="False"` 隐藏透明度滑块，仅允许选取不透明色：
```xml
```
禁用 Alpha 通道后：
- Flyout 面板中不显示透明度滑块
- 输入区域中不显示 Alpha 输入框
- 颜色值的 Alpha 分量始终为 1.0
---
## 8. 清除颜色
通过 `IsClearEnabled="True"` 允许用户清除已选颜色：
```xml
```
清除颜色后：
- 触发器色块显示透明棋盘格背景（表示无颜色）
- `Value` 变为 `null`
- 可通过 `EmptyColorText` 属性自定义空状态文本
---
## 9. 触发方式
通过 `TriggerType` 属性设置 Flyout 的触发方式：
| 触发方式 | 说明 |
|---|---|
| `Click`（默认） | 点击触发器弹出面板 |
| `Hover` | 鼠标悬浮触发器弹出面板 |
```xml
```
---
## 10. 颜色格式
通过 `Format` 属性设置颜色编码格式，支持 `Hex`（默认）、`Hsva`、`Rgba`：
```xml
```
**格式影响范围**：
- 触发器文本显示（当 `IsShowText=True`）
- Flyout 面板中输入框的显示格式
当 `IsFormatEnabled="True"`（默认）时，用户可在面板中点击格式切换按钮自由切换格式。
---
## 11. 预设色板
通过 `IsPaletteGroupEnabled="True"` 启用预设色板，面板底部会显示 Ant Design 标准色板：
```xml
```
### 自定义预设色板
通过 `PaletteGroup` 属性设置自定义预设色组：
```csharp
var customPalettes = new List
{
new("品牌色", new List
{
Color.FromRgb(0x16, 0x77, 0xff),
Color.FromRgb(0x09, 0x58, 0xf9),
Color.FromRgb(0x3c, 0x86, 0xff),
}),
new("主题色", new List
{
Color.FromRgb(0x52, 0xc4, 0x1a),
Color.FromRgb(0xfa, 0xad, 0x14),
Color.FromRgb(0xff, 0x4d, 0x4f),
}),
};
colorPicker.PaletteGroup = customPalettes;
```
---
## 12. 样式变体
通过 `StyleVariant` 属性设置触发器的样式变体，与 Input 控件的样式系统对齐：
```xml
```
---
## 13. 输入状态
通过 `Status` 属性设置输入控件状态，用于表单验证反馈：
```xml
```
**使用场景**：通常由 FormItem 自动管理，无需手动设置。当表单验证失败时，FormItem 会自动将 ColorPicker 的 `Status` 设为 `Error`。
---
## 14. MVVM 数据绑定
ColorPicker 支持标准的 Avalonia 数据绑定模式：
### 绑定颜色值
```xml
```
```csharp
// ViewModel（使用 ReactiveUI）
[Reactive]
public Color? ThemeColor { get; set; } = Color.FromRgb(0x16, 0x77, 0xff);
[Reactive]
public LinearGradientBrush? GradientBackground { get; set; }
```
### 监听颜色变化
```xml
```
```csharp
// Code-behind
public void HandleColorChanged(object? sender, ColorChangedEventArgs e)
{
// 实时响应颜色变化（Immediate 模式下拖动时持续触发）
var newColor = e.NewColor;
PreviewBorder.Background = new SolidColorBrush(newColor ?? Colors.Transparent);
}
public void HandleColorSelected(object? sender, ColorSelectedEventArgs e)
{
// 用户确认选择（Flyout 关闭时触发）
var selectedColor = e.SelectedColor;
ApplyColor(selectedColor);
}
```
### 命令绑定
```xml
```
---
## 15. Flyout 弹出位置
通过 `Placement` 属性控制 Flyout 的弹出位置：
```xml
```
---
## 16. 控制动画行为
```xml
```
---
## 常见组合模式
### 表单集成
ColorPicker 实现了 `IFormItemAware` 接口，可直接在 Form 中使用：
```xml
```
### 紧凑空间
ColorPicker 实现了 `ICompactSpaceAware` 接口，可在 `Space.Compact` 中使用：
```xml
Apply
```
### 实时预览
结合 `ValueSyncStrategy="Immediate"` 和 `ValueChanged` 事件实现实时预览：
```xml
```
```csharp
public void HandleColorChanged(object? sender, ColorChangedEventArgs e)
{
PreviewBorder.Background = new SolidColorBrush(e.NewColor ?? Colors.Transparent);
}