# AtomUI 6.0.8 API 变更示例

本文档补充 `6.0.8` 相比 `6.0.7` 的主要 API 变更和迁移写法。正式版本条目见仓库根目录 `CHANGELOG.md` 和 `CHANGELOG.zh-CN.md`。

## ImagePreviewer 图片源迁移

`6.0.8` 将 ImagePreviewer 的图片源统一到 `IImagePreviewSource`：

- `SourceUri` -> `Source`
- `SourceUris` -> `Sources`
- `FallbackSourceUri` -> `FallbackSource`
- URI、本地文件、Avalonia resource 使用 `UriImagePreviewSource`
- 数据库、鉴权网络、加密文件、内存数据等按需流使用 `StreamImagePreviewSource`

### 6.0.7 写法

```xml
<atom:ImagePreviewer
    SourceUri="https://example.com/photo.jpg"
    FallbackSourceUri="avares://Demo/Assets/fallback.png" />
```

### 6.0.8 写法

```csharp
using AtomUI.Desktop.Controls;

public IImagePreviewSource PreviewSource { get; } =
    new UriImagePreviewSource("https://example.com/photo.jpg");

public IImagePreviewSource PreviewFallbackSource { get; } =
    new UriImagePreviewSource("avares://Demo/Assets/fallback.png");
```

```xml
<atom:ImagePreviewer
    Source="{Binding PreviewSource}"
    FallbackSource="{Binding PreviewFallbackSource}" />
```

### 多图、封面和预加载

`CoverIndex` 只决定关闭态封面显示哪一张，不会改变 `CurrentIndex`。

```csharp
public IList<IImagePreviewSource> PreviewImages { get; } =
[
    new UriImagePreviewSource("https://example.com/photo-1.jpg"),
    new UriImagePreviewSource("https://example.com/photo-2.jpg"),
    new UriImagePreviewSource("https://example.com/photo-3.jpg")
];

public int CurrentPreviewIndex { get; set; }
```

```xml
<atom:ImageGroupPreviewer
    Sources="{Binding PreviewImages}"
    CoverIndex="1"
    CurrentIndex="{Binding CurrentPreviewIndex}"
    MaxConcurrentLoads="4"
    PreloadCount="1" />
```

### 懒加载数据流

`OpenReadAsync` 每次调用都应返回新的可读流，返回流由 ImagePreviewer 负责释放。

```csharp
public IImagePreviewSource SecurePreviewSource { get; } =
    new StreamImagePreviewSource(
        openReadAsync: cancellationToken =>
        {
            Stream stream = File.OpenRead("/secure/photos/invoice.png");
            return new ValueTask<Stream>(stream);
        },
        displayName: "invoice.png",
        contentType: "image/png",
        identity: "/secure/photos/invoice.png");
```

## Upload 组合式触发器迁移

`6.0.8` 中 Upload 根控件只负责文件状态、队列、Form 值和生命周期；选择文件、选择目录、拖拽区由可组合控件承担。

### 6.0.7 写法

```xml
<atom:Upload
    IsUploadDirectoryEnabled="True"
    IsShowUploadTrigger="True"
    DefaultTaskList="{Binding DefaultTaskList}"
    UploadTransport="{Binding UploadTransport}" />
```

### 6.0.8 写法

```csharp
using AtomUI.Desktop.Controls;
using System.Collections.ObjectModel;

public ObservableCollection<UploadFileItem> Attachments { get; } = [];

public IFileUploadTransport UploadTransport { get; } = new MyUploadTransport();
```

```xml
<atom:Upload
    Files="{Binding Attachments}"
    UploadTransport="{Binding UploadTransport}"
    AutoUpload="True"
    ListMaxHeight="180"
    ListScrollBarVisibility="Auto"
    SuccessAutoRemoveDelay="0:0:3">
    <atom:Space>
        <atom:UploadTrigger SourceKind="Files">
            <atom:Button Content="Select files" />
        </atom:UploadTrigger>
        <atom:UploadTrigger SourceKind="Directories">
            <atom:Button Content="Select directory" />
        </atom:UploadTrigger>
    </atom:Space>
</atom:Upload>
```

### 拖拽上传

```xml
<atom:Upload
    Files="{Binding Attachments}"
    UploadTransport="{Binding UploadTransport}">
    <atom:UploadDropZone>
        <TextBlock Text="Drop files here" />
    </atom:UploadDropZone>
</atom:Upload>
```

### Form 值投影

`FileValueMode` 控制 Upload 写入 Form 的值：

```xml
<atom:Upload
    Files="{Binding Attachments}"
    FileValueMode="Results"
    UploadTransport="{Binding UploadTransport}" />
```

## OtpLineEdit 新增控件

`OtpLineEdit` 用单一 `Text` 表达完整验证码；cell、separator 和 mask 只影响视觉。

```xml
<atom:OtpLineEdit
    Text="{Binding Code}"
    Length="6"
    InputMode="Numeric"
    Separator="-"
    SeparatorInterval="3"
    StyleVariant="Outlined" />
```

```xml
<atom:OtpLineEdit
    Text="{Binding RecoveryCode}"
    Length="8"
    InputMode="AlphaNumeric"
    IsMasked="True"
    PlaceholderText="•" />
```

```csharp
public string? Code { get; set; }
```

## Form 和 DataValidationErrors

`6.0.8` 中 Form validator 产生的错误会写入 Avalonia `DataValidationErrors`。如果已有 ViewModel 校验、binding 校验或业务层原生 validation error，AtomUI 控件会以原生 error 为最高优先级展示。

默认触发方式为 `OnChanged`；需要失焦后再验证时显式配置：

```xml
<atom:Form ValidateTrigger="OnBlur">
    <atom:FormItem Name="UserName" IsRequired="True">
        <atom:LineEdit Text="{Binding UserName}" />
    </atom:FormItem>
</atom:Form>
```

## 默认双向绑定

多个选择和值语义属性现在默认使用 `BindingMode.TwoWay`。不再需要在常规场景中显式写 `Mode=TwoWay`：

```xml
<atom:Select
    OptionsSource="{Binding CityOptions}"
    SelectedOption="{Binding SelectedCity}" />

<atom:TreeSelect
    ItemsSource="{Binding TreeNodes}"
    SelectedItems="{Binding SelectedTreeNodes}" />

<atom:DatePicker SelectedDateTime="{Binding SelectedDate}" />

<atom:TimePicker SelectedTime="{Binding SelectedTime}" />

<atom:Rate Value="{Binding Rating}" />

<atom:Dialog IsOpen="{Binding IsSettingsOpen}" />
```

如果业务确实需要只读投影，仍可在绑定上显式设置 `Mode=OneWay`。

## DataGrid 过滤模型

列过滤现在直接挂在列 API 上，过滤项来源和选中值可绑定：

```xml
<atom:DataGridTextColumn
    Header="Name"
    Binding="{Binding Name}"
    Filters="{Binding NameFilters}"
    SelectedFilterValues="{Binding SelectedNames}"
    FilterTextMemberPath="Text"
    FilterValueMemberPath="Value"
    FilterPresenterMode="Menu"
    FilterSelectionMode="Multiple"
    FilterApplyMode="SelectionChanged" />
```

树形过滤使用 `FilterChildrenMemberPath`：

```xml
<atom:DataGridTextColumn
    Header="Department"
    Binding="{Binding Department}"
    Filters="{Binding DepartmentFilters}"
    SelectedFilterValues="{Binding SelectedDepartments}"
    FilterTextMemberPath="Name"
    FilterValueMemberPath="Id"
    FilterChildrenMemberPath="Children"
    FilterPresenterMode="Tree" />
```

## Select、ComboBox 和 Cascader 溢出提示

选中内容无法完整显示时，可以开启溢出 tooltip：

```xml
<atom:Select
    IsShowOverflowTip="True"
    OverflowTipDelay="800"
    OverflowTipPlacement="TopEdgeAlignedLeft"
    OptionsSource="{Binding Options}"
    SelectedOptions="{Binding SelectedOptions}" />

<atom:ComboBox
    IsShowOverflowTip="True"
    OverflowTipDelay="800"
    OverflowTipPlacement="TopEdgeAlignedLeft"
    ItemsSource="{Binding Items}" />
```

## TabControl 和 TabStrip 拖动排序

```xml
<atom:TabControl
    IsTabReorderEnabled="True"
    TabActivationTrigger="PointerReleased"
    TabReordering="HandleTabReordering"
    TabReordered="HandleTabReordered">
    <atom:TabItem Header="Tab 1">Content 1</atom:TabItem>
    <atom:TabItem Header="Tab 2">Content 2</atom:TabItem>
    <atom:TabItem Header="Tab 3">Content 3</atom:TabItem>
</atom:TabControl>
```

`TabActivationTrigger="PointerReleased"` 是默认值，适合拖动排序场景；如果需要鼠标按下立即激活，可改为 `PointerPressed`。

## Dialog 异步关闭校验

```csharp
await Dialog.ShowDialogAsync(
    new TextBlock { Text = "Close without saving?" },
    options: new DialogOptions
    {
        Title = "Unsaved changes",
        BeforeCloseAsync = async context =>
        {
            if (context.Reason == DialogCloseReason.Rejected)
            {
                return true;
            }

            return await ConfirmSaveAsync();
        }
    });
```