Semi Design 中的 Transfer 穿梭框组件深度解析

Semi Design 中的 Transfer 穿梭框组件深度解析

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design

什么是 Transfer 穿梭框

Transfer 穿梭框是一种高效的多选选择器组件，它通过左右两个面板直观地展示待选和已选项，用户可以方便地在两个面板之间转移数据项。相比传统的多选下拉框，Transfer 组件能够展示更多选项信息，支持搜索功能，特别适合处理大量选项的场景。

基本使用

要使用 Transfer 组件，首先需要准备符合要求的数据源：

import { Transfer } from '@douyinfe/semi-ui';

const data = Array.from({ length: 100 }, (v, i) => ({
    label: `选项名称 ${i}`,
    value: i,
    disabled: false,
    key: `key-${i}`,
}));

function Demo() {
    return (
        <Transfer
            style={{ width: 568, height: 416 }}
            dataSource={data}
            onChange={(values, items) => console.log(values, items)}
        />
    );
}

每个数据项必须包含以下属性：

• label: 显示文本
• value: 选项值
• key: 唯一标识
• disabled: 是否禁用(可选)

分组展示

对于需要分类展示的场景，Transfer 支持分组显示：

const dataWithGroup = [
    {
        title: '类别A',
        children: [
            { label: 'A-1', value: 1, key: 1 },
            { label: 'A-2', value: 2, key: 2 }
        ]
    },
    {
        title: '类别B',
        children: [
            { label: 'B-1', value: 3, key: 3 },
            { label: 'B-2', value: 4, key: 4 }
        ]
    }
];

<Transfer type="groupList" dataSource={dataWithGroup} />

注意：

1. 分组数据需要设置 type="groupList"
2. 每个分组必须有 title 和 children 属性
3. 目前不支持多层嵌套分组

高级功能

自定义搜索逻辑

Transfer 默认支持搜索功能，但你可以通过 filter 属性自定义搜索逻辑：

const customFilter = (searchText, item) => {
    return item.value.includes(searchText) || item.label.includes(searchText);
};

<Transfer filter={customFilter} />

自定义渲染选项

Transfer 提供了多种自定义渲染的 API：

1. renderSourceItem: 自定义左侧待选项渲染
2. renderSelectedItem: 自定义右侧已选项渲染
3. renderSourceHeader: 自定义左侧面板头部
4. renderSelectedHeader: 自定义右侧面板头部

const renderItem = (item) => (
    <div>
        <Avatar>{item.abbr}</Avatar>
        <div>
            <div>{item.label}</div>
            <div>{item.value}</div>
        </div>
    </div>
);

<Transfer 
    renderSourceItem={renderItem}
    renderSelectedItem={renderItem}
/>

拖拽排序

从 v1.11.0 开始，Transfer 支持拖拽排序功能：

<Transfer draggable dataSource={data} />

对于自定义渲染的场景，可以使用 sortableHandle 包裹拖拽触发器：

const renderSelectedItem = (item) => {
    const { sortableHandle } = item;
    const DragHandle = sortableHandle(() => <IconHandle />);
    
    return (
        <div>
            <DragHandle />
            {/* 其他内容 */}
        </div>
    );
};

性能优化

当处理大量数据时，可以考虑以下优化策略：

1. 使用虚拟滚动（Transfer 内置支持）
2. 避免在 renderSourceItem 和 renderSelectedItem 中做复杂计算
3. 对于静态数据，可以考虑使用 memo 优化自定义渲染组件

最佳实践

1. 明确标识：确保每个选项都有唯一的 key 值
2. 合理分组：对于超过50项的列表，考虑使用分组提升用户体验
3. 提供搜索：当选项超过20个时，建议开启搜索功能
4. 禁用状态：对于不可选项，明确设置 disabled: true
5. 响应式设计：根据容器大小调整 Transfer 的尺寸

总结

Semi Design 的 Transfer 组件提供了丰富的功能和灵活的 API，能够满足各种复杂场景下的多选需求。通过合理使用分组、搜索、自定义渲染等功能，可以构建出既美观又高效的用户界面。对于需要处理大量数据的场景，记得关注性能优化，确保用户体验流畅。

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design