AtomUI/docs/Desktop.Controls/Transfer/TransferUsage.md

Transfer 使用文档

本文档介绍 AtomUI Transfer 控件的使用方式与常见场景。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/TransferShowCase.axaml

---

前置准备

AXAML 命名空间

xmlns:atom="https://atomui.net"

C# 命名空间

using AtomUI.Desktop.Controls;

---

基本用法

最基本的穿梭框，提供数据源和目标键，即可完成双栏穿梭操作：

<atom:ListTransfer Name="BasicListTransfer"
                   SourceTitle="Source"
                   TargetTitle="Target" />

在代码后置中设置数据源：

var items = new List<ListItemData>();
for (var i = 0; i < 20; i++)
{
    items.Add(new ListItemData
    {
        ItemKey = new EntityKey(i),
        Content = $"content{i + 1}"
    });
}
BasicListTransfer.ItemsSource = items;
BasicListTransfer.TargetKeys = new List<EntityKey>
{
    new(1), new(3), new(5)
};

---

单向穿梭

设置 IsOneWay="True" 后，只有"转移到目标"按钮可见，目标面板以删除按钮替代选择框：

<atom:ListTransfer Name="OneWayTransferList"
                   SourceTitle="Source"
                   TargetTitle="Target"
                   IsOneWay="True"
                   IsEnabled="{Binding OneWayTransferEnabled}" />
<atom:ToggleSwitch IsChecked="{Binding OneWayTransferEnabled, Mode=TwoWay}"
                   OnContent="disable"
                   OffContent="enable" />

---

带搜索的穿梭框

启用 IsFilterEnabled 后在面板头部下方显示搜索框。可通过 FilterValueSelector 指定搜索匹配的数据字段：

<atom:ListTransfer Name="SearchTransferList"
                   IsFilterEnabled="True"
                   FilterPlaceholderText="Search here"
                   FilterValueSelector="{Binding TransferFilterValueSelector}" />

---

高级用法

自定义穿梭按钮文本、列表宽度、页脚内容和列表项模板：

<atom:ListTransfer ToTargetButtonText="to right"
                   ToSourceButtonText="to left"
                   ListWidth="300"
                   Name="AdvanceTransfer">
    <atom:ListTransfer.SourceViewFooter>
        <atom:Button SizeType="Small" Click="ReloadAdvancedTransferItems">
            Left button reload
        </atom:Button>
    </atom:ListTransfer.SourceViewFooter>
    <atom:ListTransfer.TargetViewFooter>
        <atom:Button SizeType="Small" Click="ReloadAdvancedTransferItems">
            Right button reload
        </atom:Button>
    </atom:ListTransfer.TargetViewFooter>
    <atom:ListTransfer.ItemTemplate>
        <DataTemplate x:DataType="viewModels:SearchCaseItemData">
            <TextBlock TextTrimming="CharacterEllipsis">
                <Run Text="{Binding Content}" />
                <Run Text="-" />
                <Run Text="{Binding Description}" />
            </TextBlock>
        </DataTemplate>
    </atom:ListTransfer.ItemTemplate>
</atom:ListTransfer>

---

分页穿梭框

当数据量很大时，设置 PageSize 启用分页显示：

<atom:ListTransfer Name="PaginationTransferList"
                   IsOneWay="{Binding PaginationIsOneWay}"
                   PageSize="10"
                   ListHeight="370" />
<atom:ToggleSwitch IsChecked="{Binding PaginationIsOneWay, Mode=TwoWay}"
                   OnContent="one way"
                   OffContent="one way" />

启用分页后列表宽度自动使用 ListWidthLG（250px），选择操作下拉菜单会增加"选择当页"、"反选当页"等选项。

---

树形穿梭框

使用 TreeTransfer 在源面板展示树形结构数据：

<atom:TreeTransfer Name="TreeTransfer"
                   IsStretchView="True"
                   IsOneWay="{Binding TreeTransferIsOneWay}">
    <atom:TreeTransfer.SourceView>
        <atom:TransferTreeView IsDefaultExpandAll="True" />
    </atom:TreeTransfer.SourceView>
</atom:TreeTransfer>
<atom:ToggleSwitch IsChecked="{Binding TreeTransferIsOneWay, Mode=TwoWay}"
                   OnContent="one way"
                   OffContent="one way" />

树形穿梭的数据项需实现 ITreeItemNode 接口（含 Children 属性和 Header 属性），穿梭后目标面板以扁平列表展示已选节点。

---

验证状态

Transfer 支持 Status 属性显示验证状态边框：

<!-- Error 状态 —— 红色边框 -->
<atom:ListTransfer Status="Error" />

<!-- Warning 状态 —— 黄色边框 -->
<atom:ListTransfer Status="Warning" />

---

事件处理

SelectionChanged 事件

穿梭操作完成后触发，可获取源面板和目标面板的键集合：

transfer.SelectionChanged += (sender, args) =>
{
    var sourceKeys = args.SourceSelectedKeys;
    var targetKeys = args.TargetSelectedKeys;
    // 处理穿梭后的逻辑
};

---

数据模型

列表穿梭数据项

列表穿梭的数据项需实现 IItemKey 接口。最简单的方式是使用内置的 ListItemData：

var item = new ListItemData
{
    ItemKey = new EntityKey(1),
    Content = "Item 1"
};

自定义数据模型

也可以自定义数据模型，只要实现 IItemKey 接口即可：

public class MyTransferItem : IItemKey
{
    public EntityKey? ItemKey { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
}

树形穿梭数据项

树形穿梭需实现 ITreeItemNode 接口，包含 Children 子节点集合和 Header 展示文本。

---

常见问题

Q: 如何控制面板宽度？

通过 ListWidth 属性设置固定宽度，或设置 IsStretchView="True" 让面板填满可用空间。

Q: 分页模式下列表变宽了？

这是设计行为——启用分页后自动使用 ListWidthLG（250px）以容纳分页控件。

Q: 如何自定义过滤逻辑？

实现 IValueFilter 接口并赋值给 Filter 属性即可替换默认的 Contains 过滤器。

Q: TreeTransfer 的目标面板为什么是扁平列表？

与 Ant Design 的行为一致——树形穿梭的目标面板扁平化展示已选叶节点，源面板通过遮罩（灰显）表示已转移的节点。