Semi Design Select 选择器完全指南:从基本用法到高级定制与源码级原理解析
Semi Design Select 选择器完全指南:从基本用法到高级定制与源码级原理解析
Semi Design(@douyinfe/semi-ui)的 Select 选择器支持单选、多选、分组、搜索、远程加载、虚拟列表、自定义触发器与自定义选项渲染等一整套能力,是表单与筛选场景的核心输入组件。本文以 Select 官方文档 为主线,逐一拆解每个配置项的用法与源码实现依据,读完即可在业务中正确选型、灵活定制并规避常见踩坑点。
如何引入 Select
Select 组件及其子组件 Option、OptGroup 统一从 @douyinfe/semi-ui 引入:
import { Select } from '@douyinfe/semi-ui';
const Option = Select.Option;
需要注意的是,Select 的直接子元素必须为 Option 或 OptGroup,不允许出现 Fragment、DIV 等其他元素阻隔。这一点在源码中由 Select 的静态成员挂载方式体现(见 index.tsx 中 static Option = Option; static OptGroup = OptionGroup;),收集子节点时依赖 Option 上的 isSelectOption 标记(见 option.tsx)。
基本使用:Option 声明 value
每个 Option 标签都必须声明 value 属性,children 内容会被渲染进下拉列表;选中后回填到选择框的则是 label(未显式声明时取 children):
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<>
<Select defaultValue="douyin" style={{ width: 120 }}>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
</Select>
<br />
<br />
<Select placeholder="Select line of business" style={{ width: 120 }}>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
</Select>
</>
);
Option 还支持 disabled、showTick、className、style 等属性(完整见下文 API 表格)。当某选项被禁用时,其点击事件会被内部拦截——见 option.tsx 的 onClick 实现。
以数组形式传入 Option
当选项较多或来自接口数据时,可以直接通过 optionList 传入一个对象数组,每个对象必须包含 value / label 属性,其他自定义属性(如 disabled、业务字段)也可以一并携带:
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
const list = [
{ value: 'douyin', label: 'Douyin' },
{ value: 'capcut', label: 'Capcut' },
{ value: 'coze', label: 'Coze' },
{ value: 'toutiao', label: 'TooBuzz' },
];
return <Select placeholder="Business line" style={{ width: 180 }} optionList={list}></Select>;
};
从源码看,optionList 与 JSX children 两条声明路径最终都会归一为统一的 OptionProps<a href="https://link.gitcode.com/i/0d828e5d7e4814af6ea4d087af1c30aa" target="_blank">] 结构:SelectFoundation._collectOptions 通过 adapter 的 getOptionsFromChildren() 收集后统一交给 updateOptions 处理(见 [foundation.ts)。不同 Option 的 label 必须唯一,value 允许重复——因为内部 SelectState.selections 是一个以 label 为 key 的 Map(见 index.tsx 的注释说明)。
多选:multiple 与已选项展示策略
配置 multiple 属性即可开启多选。自 v2.28 起,选择器自带 maxHeight: 270,内容超出后可通过垂直滚动查看(该默认值定义在 constants.ts 的 numbers.LIST_HEIGHT)。
围绕多选场景,Semi 提供了一组控制“已选项标签”展示的配置:
| 配置项 | 版本 | 说明 |
|---|---|---|
maxTagCount |
— | 限制已选项展示数量,超出部分以 +N 形式展示 |
ellipsisTrigger |
>= v2.28.0 | 对溢出部分 tag 做自适应处理,宽度不足时截断最后一个 tag 内容;有性能损耗,不推荐大表单场景使用 |
expandRestTagsOnClick |
>= v2.28.0 | 设置了 maxTagCount 时,点击可展开显示全部剩余 tag |
showRestTagsPopover |
>= v2.22.0 | 超出 maxTagCount 后,hover +N 是否通过 Popover 展示剩余项,默认 false |
restTagsPopoverProps |
>= v2.22.0 | 上述 Popover 的配置属性(如 position) |
max |
— | 限制最大可选数量,超出后无法选中并触发 onExceed 回调 |
max 上限校验在源码中有明确实现:多选处理分支 _handleMultipleSelect 中,若 selections.size >= maxLimit 则直接 notifyMaxLimit 并 return,不再加入选择集(见 foundation.ts)。
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<>
<Select multiple style={{ width: '320px' }} defaultValue={['douyin', 'coze']}>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
<br />
<br />
<Select
multiple
maxTagCount={2}
showRestTagsPopover={true}
restTagsPopoverProps={{ position: 'top' }}
style={{ width: '320px' }}
defaultValue={['douyin', 'coze', 'capcut']}
>
<Select.Option value="douyin">Semi</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
<br />
<br />
<Select
multiple
style={{ width: '320px' }}
defaultValue={['douyin']}
max={2}
onExceed={() => Toast.warning('Only two options are allowed')}
>
<Select.Option value="douyin">Semi</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
<br />
<br />
<Select
multiple
maxTagCount={2}
showRestTagsPopover={true}
restTagsPopoverProps={{ position: 'top' }}
style={{ width: '220px' }}
defaultValue={['xigua', 'coze', 'capcut', 'douyin']}
ellipsisTrigger
expandRestTagsOnClick
>
<Select.Option value="douyin">Semi</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
</>
);
分组:OptGroup
使用 Select.OptGroup 进行分组。分组功能仅支持通过 JSX 声明 children 使用,不支持通过 optionList 传入。同时注意:OptGroup 必须为 Select 的直接子元素;若 children 需要动态更新,OptGroup 上的 key 也必须更新,否则 Select 无法识别。
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<Select placeholder="" style={{ width: 180 }} filter>
<Select.OptGroup label="Asia">
<Select.Option value="a-1">China</Select.Option>
<Select.Option value="a-2">Korea</Select.Option>
</Select.OptGroup>
<Select.OptGroup label="Europe">
<Select.Option value="b-1">Germany</Select.Option>
<Select.Option value="b-2">France</Select.Option>
</Select.OptGroup>
<Select.OptGroup label="South America">
<Select.Option value="c-1">Peru</Select.Option>
</Select.OptGroup>
</Select>
);
也可以用数组数据配合 map 动态渲染分组结构,此时建议给每个 OptGroup 一个稳定的复合 key:
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
const data = [
{ label: 'Asia', children: [{ value: 'a-1', label: 'China' }, { value: 'a-2', label: 'Korea' }] },
{ label: 'Europe', children: [{ value: 'b-1', label: 'Germany' }, { value: 'b-2', label: 'France' }] },
{ label: 'South America', children: [{ value: 'c-1', label: 'Peru' }] },
];
return (
<Select placeholder="" style={{ width: 180 }} filter>
{data.map((group, index) => (
<Select.OptGroup label={group.label} key={`${index}-${group.label}`}>
{group.children.map((option, index2) => (
<Select.Option value={option.value} key={`${index2}-${group.label}`}>
{option.label}
</Select.Option>
))}
</Select.OptGroup>
))}
</Select>
);
};
尺寸与校验状态
通过 size 控制选择器尺寸,可选 small / default / large(合法取值定义在 constants.ts 的 SIZE_SET):
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<>
<Select placeholder="Business line" style={{ width: '200px' }} size="small">
<Select.Option value="douyin">Douyin</Select.Option>
</Select>
<br />
<br />
<Select placeholder="Business line" style={{ width: '200px' }}>
<Select.Option value="douyin">Douyin</Select.Option>
</Select>
<br />
<br />
<Select placeholder="Business line" style={{ width: '200px' }} size="large">
<Select.Option value="douyin">Douyin</Select.Option>
</Select>
</>
);
通过 validateStatus 设置校验状态样式:default / warning / error,仅影响背景颜色等样式表现:
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<>
<Select style={{ width: '180px' }} defaultValue='Capcut'>
<Select.Option value="Capcut">Capcut</Select.Option>
</Select>
<br />
<br />
<Select style={{ width: '180px' }} validateStatus="warning" defaultValue='Capcut'>
<Select.Option value="Capcut">Capcut</Select.Option>
</Select>
<br />
<br />
<Select style={{ width: '180px' }} validateStatus="error" defaultValue='Capcut'>
<Select.Option value="Capcut">Capcut</Select.Option>
</Select>
</>
);
配置前缀、后缀、清除按钮与下拉箭头
- 通过
prefix传入选择框前缀、suffix传入后缀,可以为文本或 ReactNode;当传入内容为文本或 Icon 时自动带上左右间隔,若为自定义 ReactNode,左右间隔为 0; - 通过
showClear控制清除按钮是否展示(onClear为点击清除回调); - 通过
showArrow控制右侧下拉箭头是否展示;arrowIcon可自定义箭头 Icon(开启showClear且有选中值时,hover 时优先展示清除图标)。
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
import { IconVigoLogo, IconGift } from '@douyinfe/semi-icons';
() => (
<>
<Select style={{ width: '320px' }} defaultValue={'douyin'} prefix={<IconVigoLogo />} showClear={true}>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
<br />
<br />
<Select
style={{ width: '320px' }}
defaultValue={'capcut'}
prefix={<IconVigoLogo />}
suffix={<IconGift />}
showArrow={false}
>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
</>
);
弹出层插槽:inner / outer 四向扩展
弹出层顶部、底部分别预留了插槽,用于添加自定义节点:
innerTopSlot/innerBottomSlot:渲染在 optionList 内部,随 optionList 一起滚动;outerTopSlot/outerBottomSlot:渲染为与 optionList 平级,无论是否滚动始终展现。
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
import { IconClock } from '@douyinfe/semi-icons';
() => {
let selectStyle = { width: 180, margin: 20 };
let innerSlotStyle = {
backgroundColor: '#FFF', height: '40px', color: '#0077FA',
display: 'flex', justifyContent: 'center', alignItems: 'center', cursor: 'pointer',
};
let innerSlotNode = <div style={innerSlotStyle}>No suitable product?</div>;
let outSlotStyle = {
backgroundColor: 'whitesmoke', height: '29px',
display: 'flex', justifyContent: 'center', alignItems: 'center', cursor: 'pointer',
};
let outSlotNode = (
<div style={outSlotStyle}>
<IconClock></IconClock>
<span style={{ color: 'rgba(28, 31, 35, 0.55)' }}>More recently viewed pages</span>
</div>
);
return (
<div>
<p>outerBottomSlot:</p>
<Select
style={selectStyle}
dropdownStyle={{ width: 180 }}
maxHeight={213}
defaultOpen
autoAdjustOverflow={false}
position="bottom"
outerBottomSlot={outSlotNode}
>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
<p>innerBottomSlot:</p>
<Select style={selectStyle} dropdownStyle={{ width: 180 }} innerBottomSlot={innerSlotNode} >
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
</div>
);
};
插槽常被用于构建“搜索型导航菜单”:例如在 outerTopSlot 中插入一组 Tab,点击 Tab 切换 optionList 数据源,实现一个带分类的搜索选择器。此时通常配合 onChangeWithObject、受控 value 使用(参考原文档中的 Tab 切换示例)。注意在带自定义交互元素的插槽场景下,键盘可访问性要求 Tab 键可在插槽与选择框之间切换,详见下文 Accessibility 章节。
受控组件
传入 value 时 Select 即受控组件,所选值完全由 value 决定,配合 onChange 更新:
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
let [value, setValue] = useState('xigua');
return (
<>
<Select value={value} style={{ width: '300px' }} onChange={setValue} placeholder="Controlled Component">
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
</>
);
};
源码对受控与非受控走不同分支:受控模式下选中后直接 notifyChange,由外部更新 value 再回流更新选中态;非受控模式则先内部 updateSelection 再通知(见 foundation.ts)。
联动 Select
通过受控 value 与 onChange 可以实现两个 Select 之间的级联联动(如省份 → 城市)。如果是带层级关系的复杂联动,官方建议直接使用 Cascader 组件:
import React, { useState } from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
const continents = ['Asia', 'Europe'];
const maps = {
Asia: ['China', 'Korea'],
Europe: ['United Kingdom', 'France', 'Germany'],
};
const [continent, setContinent] = useState(continents[0]);
const countrys = maps[continent];
const [country, setCountry] = useState(countrys[0]);
const continentsChange = newContinent => {
setContinent(newContinent);
setCountry(maps[newContinent][0]);
};
const countryChange = newCountry => setCountry(newCountry);
return (
<>
<Select style={{ width: '150px', margin: '10px' }} onChange={continentsChange} value={continent}>
{continents.map(c => (
<Select.Option value={c} key={c}>{c}</Select.Option>
))}
</Select>
<Select style={{ width: '150px', margin: '10px' }} value={country} onChange={countryChange}>
{countrys.map(c => (
<Select.Option value={c} key={c}>{c}</Select.Option>
))}
</Select>
</>
);
};
开启搜索:filter 与 autoClearSearchValue
将 filter 置为 true 开启搜索能力,默认搜索策略为 input 输入值与 option 的 label 做字符串 include 对比。默认情况下多选选中后会自动清空搜索关键字,若想保留,将 autoClearSearchValue 设为 false(v2.3 后提供):
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<>
<Select filter style={{ width: 180 }} placeholder="Searchable Select">
<Select.Option value="app1">Douyin</Select.Option>
<Select.Option value="app2">Coze</Select.Option>
<Select.Option value="app3">Capcut</Select.Option>
<Select.Option value="app4">BuzzVideo</Select.Option>
</Select>
<br />
<br />
<Select
filter
multiple
style={{ width: 350 }}
placeholder="Searchable Multiple Select"
autoClearSearchValue={false}
>
<Select.Option value="semi-0">Semi-0</Select.Option>
<Select.Option value="semi-1">Semi-1</Select.Option>
<Select.Option value="semi-2">Semi-2</Select.Option>
<Select.Option value="semi-3">Semi-3</Select.Option>
<Select.Option value="semi-4">Semi-4</Select.Option>
</Select>
</>
);
autoClearSearchValue 的语义在源码中有分支处理:多选时若开启,选中后会 clearInput 并同时清空筛选条件以展示全部候选(见 foundation.ts)。搜索命中时,Option 中匹配关键字还会通过 Highlight 组件高亮(见 option.tsx)。
搜索框位置:searchPosition
默认搜索框展示于 Select 的 Trigger 上。通过 searchPosition 可指定为 dropdown(放在弹出列表顶部)或 trigger(v2.61.0 后提供);通过 searchPlaceholder 可定制 dropdown 中搜索框的 placeholder。
需要注意 showClear 与两种位置的联动差异:
searchPosition='trigger'时,点击 Trigger 区域清空按钮会同时清空已选项与搜索框文本;searchPosition='dropdown'时,点击 Trigger 清空按钮仅清空已选项,点击下拉内搜索框的清空按钮仅清空搜索文本。
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<>
<Select
filter
searchPosition='dropdown'
style={{ width: 200 }}
defaultValue={'ulikecam'}
>
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="ulikecam">UlikeCam</Select.Option>
<Select.Option value="jianying">Capcut</Select.Option>
<Select.Option value="xigua">XiguaVideo</Select.Option>
</Select>
<br />
<br />
<Select
filter
searchPosition='dropdown'
multiple
style={{ width: 300 }}
defaultValue={['semi-1']}
autoClearSearchValue={false}
>
<Select.Option value="semi-0">Semi-0</Select.Option>
<Select.Option value="semi-1">Semi-1</Select.Option>
<Select.Option value="semi-2">Semi-2</Select.Option>
<Select.Option value="semi-3">Semi-3</Select.Option>
<Select.Option value="semi-4">Semi-4</Select.Option>
</Select>
</>
);
合法的 searchPosition 取值常量(trigger / dropdown)同样定义在 constants.ts。
远程搜索:remote + loading + onSearch
远程搜索适合选项数据来自接口的场景,核心组合是:
filter开启搜索能力;remote关闭本地过滤(输入内容不会与当前optionList匹配筛选);onSearch回调触发接口请求(可用lodash-es的debounce防抖);- 动态更新
optionList; - 请求期间通过
loading展示加载状态; - 使用受控
value。
import React from 'react';
import { debounce } from 'lodash-es';
import { Select } from '@douyinfe/semi-ui';
() => {
const [loading, setLoading] = useState(false);
const optionList = [
{ value: 'dsm', label: 'Semi DSM', type: 1 },
{ value: 'd2c', label: 'Semi DesignToCode', type: 2 },
{ value: 'c2d', label: 'Semi CodeToDesign', type: 3 },
{ value: 'plugin', label: 'Semi Plugin', type: 4 },
];
const [list, setList] = useState(optionList);
const [value, setValue] = useState('');
const handleMultipleChange = newValue => {
setValue(newValue);
};
const handleSearch = inputValue => {
setLoading(true);
let result = [];
if (inputValue) {
let length = Math.ceil(Math.random() * 100);
result = Array.from({ length }, (v, i) => {
return { value: inputValue + i, label: `Relative: ${inputValue}${i}`, type: i + 1 };
});
setTimeout(() => {
setLoading(false);
setList(result);
}, 1000);
} else {
setLoading(false);
}
};
return (
<Select
style={{ width: 300 }}
filter
remote
onChangeWithObject
multiple
value={value}
onSearch={debounce(handleSearch, 1000)}
optionList={list}
loading={loading}
onChange={handleMultipleChange}
emptyContent={null}
></Select>
);
};
remote 的关键作用可从 FAQ 印证:若不设置 remote,输入值会先与当前 optionList 做本地匹配,异步请求完成前可能因无匹配项而显示无数据;设置 remote={true} 可关闭对当前本地数据的匹配过滤。加载动画由内部集成 Spin 实现。
自定义搜索策略:filter 作为函数
当默认的 label include 策略不满足需求时,可以把 filter 置为自定义函数:入参为 (searchInput, option),满足过滤条件时返回 true。例如同时匹配 label 与 value、或忽略大小写:
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
function search(sugInput, option) {
// Search for both label and value
let label = option.label.toUpperCase();
let value = option.value.toUpperCase();
let sug = sugInput.toUpperCase();
return label.includes(sug) || value.includes(sug);
}
return (
<Select filter={search} style={{ width: '180px' }} placeholder="try hello or douyin">
<Select.Option value="hello">Douyin</Select.Option>
<Select.Option value="bytedance">UlikeCam</Select.Option>
<Select.Option value="semi">BuzzVideo</Select.Option>
</Select>
);
};
源码中 filter 的类型为 boolean | ((inputValue: string, option: OptionProps) => boolean)(见 index.tsx),_isFilterable() 用 Boolean(filter) 判断是否开启搜索(见 foundation.ts),函数形态则直接作为过滤谓词使用。
自定义已选项标签渲染:renderSelectedItem
默认选中后会把 option.label 或 option.children 回填到选择框。通过 renderSelectedItem 可完全自定义选择框内已选项的渲染:
- 单选:
renderSelectedItem(optionNode: object) => content: ReactNode - 多选:
renderSelectedItem(optionNode: object, { index: number, onClose: function }) => { isRenderInTag: boolean, content: ReactNode }isRenderInTag为true时,content 自动包裹在Tag中渲染(带背景色与关闭按钮);- 为
false时直接渲染返回的 content。
典型场景是“头像 + 邮箱”型选项:自定义 Option 结构(通过 Select.Option 展开 {...item} 附带头像、邮箱等字段),再用 renderSelectedItem 组合 Avatar 渲染:
import React from 'react';
import { Select, Avatar, Tag } from '@douyinfe/semi-ui';
() => {
const list = [
{ name: 'Keman Xia', email: 'xiakeman@example.com', avatar: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/bag.jpeg' },
{ name: 'Yue Shen', email: 'shenyue@example.com', avatar: 'https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/bf8647bffab13c38772c9ff94bf91a9d.jpg' },
];
const renderSelectedItem = optionNode => (
<div key={optionNode.email} style={{ display: 'flex', alignItems: 'center' }}>
<Avatar src={optionNode.avatar} size="small">{optionNode.abbr}</Avatar>
<span style={{ marginLeft: 8 }}>{optionNode.email}</span>
</div>
);
const renderMultipleWithCustomTag = (optionNode, { onClose }) => {
const content = (
<Tag avatarSrc={optionNode.avatar} avatarShape="circle" closable={true} onClose={onClose} size="large" key={optionNode.name}>
{optionNode.name}
</Tag>
);
return { isRenderInTag: false, content };
};
const renderCustomOption = (item, index) => {
const optionStyle = { display: 'flex', paddingLeft: 24, paddingTop: 10, paddingBottom: 10 };
return (
<Select.Option value={item.name} style={optionStyle} showTick={true} {...item} key={item.email}>
<Avatar size="small" src={item.avatar} />
<div style={{ marginLeft: 8 }}>
<div style={{ fontSize: 14 }}>{item.name}</div>
<div style={{ color: 'var(--color-text-2)', fontSize: 12, lineHeight: '16px', fontWeight: 'normal' }}>{item.email}</div>
</div>
</Select.Option>
);
};
return (
<>
<Select
placeholder="Please select..." style={{ width: 280, height: 40 }}
onChange={v => console.log(v)} defaultValue={'Keman Xia'}
renderSelectedItem={renderSelectedItem}
>
{list.map((item, index) => renderCustomOption(item, index))}
</Select>
<Select
placeholder="Please select..." maxTagCount={2} style={{ width: 280, marginTop: 20 }}
onChange={v => console.log(v)} defaultValue={['Keman Xia', 'Yue Shen']}
multiple renderSelectedItem={renderMultipleWithCustomTag}
>
{list.map((item, index) => renderCustomOption(item, index))}
</Select>
</>
);
};
Tag 支持 avatarSrc / avatarShape 属性(circle / square),可在多选标签内直接嵌入头像。renderSelectedItem 的函数签名定义见 index.tsx。
自定义弹出层样式
通过 dropdownClassName、dropdownStyle 控制弹出层样式,例如自定义弹出层宽度时用 dropdownStyle 传 width(FAQ 也说明:弹出层 MinWidth 会被给定,但 width 不会写死,需要时通过 dropdownStyle 自行补充):
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => (
<Select style={{ width: 180 }} dropdownStyle={{ width: 250 }} dropdownClassName="test">
<Select.Option value="douyin">Douyin</Select.Option>
<Select.Option value="coze">Coze</Select.Option>
<Select.Option value="capcut">Capcut</Select.Option>
<Select.Option value="xigua">BuzzVideo</Select.Option>
</Select>
);
其他弹出层相关配置还包括:position(弹出位置,默认 'bottomLeft',可选值参考 Popover 的 position)、autoAdjustOverflow(被遮挡时自动调整方向,默认 true)、dropdownMatchSelectWidth(下拉菜单最小宽度是否等于 Select,默认 true)、spacing(弹出层与触发器的间距,默认 4)、zIndex(默认 1030)、getPopupContainer(指定弹出层挂载父级 DOM)、rePosKey(手动触发重新定位)、dropdownMargin(溢出安全区计算,v2.25.0)、preventScroll、stopPropagation 等。
动态修改 Options
如果需要在运行时动态更新 Options,应使用受控 value,否则已选项与新增选项列表可能无法正确对齐:
import React from 'react';
import { Select, Button } from '@douyinfe/semi-ui';
() => {
let [options, setOptions] = useState([1, 2, 3, 4]);
function add() {
let length = Math.ceil(Math.random() * 10);
let newOptions = Array.from({ length }, (v, i) => i + 1);
setOptions(newOptions);
}
return (
<>
<Select style={{ width: '180px' }} value={4}>
{options.map(option => (
<Select.Option value={option} key={option}>{option}</Select.Option>
))}
</Select>
<br />
<br />
<Button onClick={add}>ChangeOptions Dynamic</Button>
</>
);
};
获取选中选项的其他属性:onChangeWithObject
默认 onChange 只能拿到 value;如需拿到选中节点的其他属性,使用 onChangeWithObject。此时 onChange 入参变为对象,包含 option 的各种属性,例如 onChange({ value, label, ...rest })。
注意:当 onChangeWithObject 置为 true 时,defaultValue / value 也应为 object,且须带有 value、label key——源码在 _updateSingle / _updateMultiple 中正是通过取 propValue.value 做选中比对(见 foundation.ts):
import React from 'react';
import { Select, TextArea } from '@douyinfe/semi-ui';
() => {
const list = [
{ value: 'douyin', label: 'Douyin', type: 1 },
{ value: 'capcut', label: 'Capcut', type: 2 },
{ value: 'xigua', label: 'BuzzVideo', type: 3 },
];
const [cbValue, setCbValue] = useState();
const [multipleCbValue, setMultipleCbValue] = useState();
return (
<div>
<Select
style={{ width: 150 }}
onChangeWithObject
optionList={list}
defaultValue={list[0]}
onChange={v => { setCbValue(v); console.log(v); }}
></Select>
<h4>onChange callback:</h4>
<TextArea style={{ width: 320, marginBottom: 48 }} autosize value={JSON.stringify(cbValue)} rows={2} />
<Select
style={{ width: 320 }}
onChangeWithObject
multiple
optionList={list}
onChange={v => { setMultipleCbValue(v); console.log(v); }}
placeholder="Multiple Select"
></Select>
<h4>onChange callback:</h4>
<TextArea style={{ width: 320 }} autosize value={JSON.stringify(multipleCbValue)} />
</div>
);
};
创建条目:allowCreate
设置 allowCreate={true}(需与 filter 配合),用户可以创建并选中选项中不存在的条目:
- 通过
renderCreateItem自定义创建标签时的内容显示,默认值为(inputValue, isFocus, style) => 'Create' + inputValue; - 可配合
defaultActiveFirstOption使用,自动选中第一项,输入完内容直接回车即可立即创建; - 创建成功后触发
onCreate回调。
注意:开启 allowCreate 后,不再响应对 Children 或 optionList 的更新——组件会强制接管这两类数据源,避免本地创建的条目与外部更新的合并策略歧义。
import React from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
const optionList = [
{ value: 'douyin', label: 'Douyin' },
{ value: 'capcut', label: 'Capcut' },
{ value: 'xigua', label: 'BuzzVideo' },
];
return (
<>
<Select
style={{ width: 400 }}
optionList={optionList}
allowCreate={true}
multiple={true}
filter={true}
onChange={v => console.log(v)}
defaultActiveFirstOption
></Select>
<br />
<br />
<Select
style={{ width: 400 }}
optionList={optionList}
allowCreate={true}
multiple={true}
filter={true}
renderCreateItem={input => <div style={{ padding: 10 }}>Create Item:{input}</div>}
onChange={v => console.log(v)}
defaultActiveFirstOption
></Select>
</>
);
};
从源码看,动态创建的选项带有 _inputCreateOnly 标记,被选中时会先触发 notifyCreate 再进入选择流程(见 foundation.ts)。
虚拟列表:virtualize
当 Option 数量很大(如数千条)时,传入 virtualize 开启列表虚拟化以优化性能。它是一个对象:
height:选项列表高度,默认 270(v2.20.8 之前为 300);width:选项列表宽度,默认 100%;itemSize:每一行 Option 的高度,必须传入。
注意:当 virtualize.height 大于默认 270px 时,为避免出现双滚动条,需将 maxHeight 设为与 virtualize.height 相同的值。例如设置 virtualize.height 为 400 时,应同时设置 maxHeight={400}。
import React, { useMemo } from 'react';
import { Select } from '@douyinfe/semi-ui';
() => {
const optionList = useMemo(() => {
return Array.from({ length: 3000 }, (v, i) => ({ label: `option-${i}`, value: i }));
}, []);
const virtualize = {
height: 270,
width: '100%',
itemSize: 36, // px
};
return (
<Select
placeholder="3000 options"
style={{ width: 260 }}
filter
virtualize={virtualize}
optionList={optionList}
></Select>
);
};
虚拟化底层由 react-window 的 FixedSizeList 与自定义 VirtualRow 实现(见 index.tsx 的引入),因此使用 renderOptionItem 自定义选项时,务必把 props 中的 style 应用到最外层 wrapper DOM,否则虚拟滚动下布局会异常。
自定义 Trigger:triggerRender
如果默认选择框布局不满足需求,可通过 triggerRender 完全自定义触发器显示。其回调参数类型 TriggerRenderProps 定义见 index.tsx:
interface TriggerRenderProps {
value: array<object>; // 当前所有已选中的选项
inputValue: string; // 当前输入框的值
onSearch: (inputValue: string) => void; // 更新输入框值的函数,自定义 Input 值变化时应调用它同步状态到 Select 内部(需 filter=true,v2.32 后支持)
onClear: () => void; // 清空值的函数
onRemove: (option: object) => void; // 移除单个选项(v2.32 后支持)
disabled: boolean; // Select 是否禁用
placeholder: string; // Select 占位符
componentProps: ...; // 用户传给 Select 的全部 props
}
示例:自定义一个“品牌色触发器”,将多个已选项的 label 拼接展示:
import React, { useState } from 'react';
import { Select, Tag } from '@douyinfe/semi-ui';
import { IconAppCenter, IconChevronDown } from '@douyinfe/semi-icons';
() => {
const [valList, setValList] = useState(['douyin', 'ulikecam']);
const list = [
{ value: 'douyin', label: 'Douyin' },
{ value: 'ulikecam', label: 'UlikeCam' },
{ value: 'jianying', label: 'Capcut' },
{ value: 'doubao', label: 'Cici' },
];
const triggerRender = ({ value }) => {
return (
<div style={{
minWidth: '112', backgroundColor: 'var(--semi-color-primary-light-default)',
height: 32, display: 'flex', alignItems: 'center', paddingLeft: 12,
borderRadius: 3, color: 'var(--semi-color-primary)',
}}>
<div style={{ fontWeight: 600, flexShrink: 0, fontSize: 14 }}>AppName</div>
<div style={{ margin: 4, whiteSpace: 'nowrap', textOverflow: 'ellipsis', flexGrow: 1, overflow: 'hidden' }}>
{value.map(item => item.label).join(' , ')}
</div>
<IconAppCenter style={{ marginRight: 8, flexShrink: 0 }} />
</div>
);
};
const triggerRender2 = ({ value }) => {
return (
<div style={{ margin: 4, whiteSpace: 'nowrap', textOverflow: 'ellipsis', flexGrow: 1, overflow: 'hidden', display: 'flex', alignItems: 'center' }}>
<Tag size='large' color='cyan' shape='circle' suffixIcon={<IconChevronDown />}>
{value.map(item => item.label).join(' / ')}
</Tag>
</div>
);
};
return (
<div>
<h4>Different Background Trigger</h4>
<Select
value={valList}
triggerRender={triggerRender}
optionList={list}
onChange={value => setValList(value)}
multiple
filter
searchPosition='dropdown'
style={{ width: 240 }}
></Select>
<br />
<br />
<h4>Use circle Tag as trigger</h4>
<Select
value={valList}
onChange={value => setValList(value)}
triggerRender={triggerRender2}
optionList={list}
filter
multiple
searchPosition='dropdown'
style={{ width: 240, marginTop: 20, outline: 0 }}
></Select>
</div>
);
};
triggerRender 更复杂的用法是复用 TagInput 的拖拽排序能力:在 triggerRender 内嵌 TagInput,通过 onSearch / onClear 与 Select 内部状态同步,再在 TagInput.onChange 中按 label 反查 value 重排已选项,即可实现“可拖拽排序的多选 Select”。这是原文档给出的高阶实践示例,可直接参考其中的 handleSort 实现思路。
自定义 Option 渲染:renderOptionItem
候选列表的定制有两种层次:
- 简单定制:将 Option 的
label或 children 传为 ReactNode,内容自动带上 padding、背景色等样式; - 完全定制:通过
renderOptionItem完全接管列表中候选的渲染,从回调入参中获取状态值,实现更高自由度的结构渲染。
使用 renderOptionItem 时有四条硬性注意:
- props 传入的
style必须消费在 wrapper dom 上,否则虚拟化场景下无法正常使用; selected、focused、disabled等状态的样式需要自行添加(可从 props 获取对应布尔值);onMouseEnter、className必须绑定在 wrapper dom 上,否则上下键盘操作时展示会出问题;- 如果自定义项是
Select.Option,需要把renderProps.onClick透明传给 Option 的onSelect。
import React from 'react';
import { Select, Checkbox } from '@douyinfe/semi-ui';
() => {
const renderOptionItem = renderProps => {
const {
disabled, selected, label, value, focused,
className, style, onMouseEnter, onClick, empty, emptyContent, ...rest
} = renderProps;
const optionCls = classNames({
['custom-option-render']: true,
['custom-option-render-focused']: focused,
['custom-option-render-disabled']: disabled,
['custom-option-render-selected']: selected,
className,
});
return (
<div style={style} className={optionCls} onClick={() => onClick()} onMouseEnter={e => onMouseEnter()}>
<Checkbox checked={selected} />
<div className="option-right">{label}</div>
</div>
);
};
const optionList = [
{ value: 'douyin', label: 'Semi', otherKey: 0 },
{ value: 'capcut', label: 'Capcut', disabled: true, otherKey: 1 },
{ value: 'cam', label: 'UlikeCam', otherKey: 2 },
{ value: 'buzz', label: 'Buzz', otherKey: 3 },
];
return (
<>
<Select
filter defaultOpen defaultValue="douyin"
dropdownClassName="components-select-demo-renderOptionItem"
optionList={optionList} style={{ width: 180 }}
renderOptionItem={renderOptionItem}
/>
<br />
<br />
<Select
filter placeholder="multiple" multiple
dropdownClassName="components-select-demo-renderOptionItem"
optionList={optionList} style={{ width: 320, marginTop: 180 }}
renderOptionItem={renderOptionItem}
/>
</>
);
};
配套 SCSS 中需要为 focused / disabled / selected 等状态类提供样式,例如 custom-option-render-focused 使用 var(--semi-color-fill-0) 背景、custom-option-render-disabled 使用 var(--semi-color-disabled-text) 与 not-allowed 光标等(完整示例样式见原文档)。renderOptionItem 的入参结构 optionRenderProps 定义见 index.tsx。
API 参考
Select Props(关键项)
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| allowCreate | 是否允许用户创建新条目,需与 filter 配合;开启后不再响应 children / optionList 更新 |
boolean | false | |
| arrowIcon | 自定义右侧下拉箭头 Icon | ReactNode | ||
| autoAdjustOverflow | 弹出层被遮挡时是否自动调整方向 | boolean | true | |
| autoClearSearchValue | 选中后是否自动清空搜索关键字(multiple + filter 时生效) | boolean | true | 2.3.0 |
| autoFocus | 挂载时是否自动聚焦 | boolean | false | |
| borderless | 无边框模式 | boolean | >= 2.33.0 | |
| clearIcon | 自定义清除按钮(showClear 为 true 时生效) | ReactNode | 2.25.0 | |
| clickToHide | 展开时点击选择框自动收起下拉 | boolean | false | |
| defaultValue | 挂载时初始选中值 | string | number | array | ||
| defaultOpen | 挂载时是否展示下拉 | boolean | false | |
| defaultActiveFirstOption | 是否默认高亮第一项(回车直接选中) | boolean | true | |
| disabled | 是否禁用 | boolean | false | |
| dropdownClassName / dropdownStyle | 弹出层类名 / 内联样式 | string / object | ||
| dropdownMatchSelectWidth | 下拉最小宽度是否等于 Select | boolean | true | |
| dropdownMargin | 弹出层溢出安全区计算(fixed 元素遮挡场景) | object | number | 2.25.0 | |
| emptyContent | 无结果时展示内容;设为 null 时不展示下拉列表 | string | ReactNode | ||
| ellipsisTrigger | maxTagCount 多选时对溢出 tag 做截断自适应(有性能损耗) | boolean | false | 2.28.0 |
| expandRestTagsOnClick | maxTagCount 多选时,面板展开后是否展开冗余 Tags | boolean | false | 2.28.0 |
| filter | 是否可搜索;为 true 启用默认 label 匹配,为函数时自定义过滤策略 | boolean | function | false | |
| getPopupContainer | 指定弹出层挂载父级 DOM(需设 position: relative) | function(): HTMLElement | () => document.body | |
| inputProps | filter 开启时输入框的附加配置(勿传 value/ref/onChange/onFocus) | object | 2.2.0 | |
| innerTopSlot / innerBottomSlot | 弹出层内部(optionList 内)顶部 / 底部插槽 | ReactNode | ||
| loading | 下拉是否展示加载动画 | boolean | false | |
| max | 最大可选数量(仅多选生效),超出触发 onExceed | number | ||
| maxTagCount | 多选时最多展示的 tag 数,超出以 +N 展示 | number | ||
| maxHeight | optionList 最大高度;虚拟化 height > 270 时需与 virtualize.height 相同 | string | number | 270 | |
| multiple | 是否多选 | boolean | false | |
| outerTopSlot / outerBottomSlot | 弹出层外部(与 optionList 平级)顶部 / 底部插槽 | ReactNode | ||
| optionList | 以数组传入 Option,每项需含 label / value | Array({value, label}) | ||
| placeholder | 占位符 | ReactNode | ||
| position | 弹出层位置 | string | 'bottomLeft' | |
| prefix / suffix | 选择框前 / 后缀 | ReactNode | ||
| rePosKey | 更新该值手动触发弹出层重新定位 | string | number | ||
| remote | 是否开启远程搜索(不本地过滤) | boolean | false | |
| renderCreateItem | allowCreate 时自定义创建标签渲染 | function(inputValue) | InputValue => 'Create' + InputValue | |
| renderSelectedItem | 自定义选择框内已选项渲染 | function(option) | ||
| restTagsPopoverProps | +N Popover 的配置属性 | PopoverProps | {} | 2.22.0 |
| searchPosition | 搜索框位置:trigger / dropdown | string | 'trigger' | 2.61.0 |
| searchPlaceholder | dropdown 内搜索框占位符 | string | ||
| showArrow | 是否展示下拉箭头 | boolean | true | |
| showClear | 是否展示清除按钮 | boolean | false | |
| showRestTagsPopover | 超出 maxTagCount 后 hover +N 是否展示 Popover | boolean | false | 2.22.0 |
| size | 尺寸:default / small / large | string | ||
| spacing | 弹出层与触发器间距 | number | 4 | |
| stopPropagation | 是否阻止弹出层点击冒泡 | boolean | true | |
| triggerRender | 自定义触发器 DOM | function | ||
| validateStatus | 校验状态:warning / error / default | string | 'default' | |
| value | 受控值,配合 onChange | string | number | array | ||
| virtualize | 列表虚拟化配置 {height, width, itemSize} | object | ||
| zIndex | 弹出层 z-index | number | 1030 | |
| onBlur / onFocus | 失焦 / 聚焦回调 | function(event) | ||
| onChange | 选中变化回调 | function(value) | ||
| onChangeWithObject | 是否以对象形式返回选中选项全部属性 | boolean | false | |
| onClear | 点击清除图标回调 | function | ||
| onCreate | allowCreate 创建候选后回调 | function | ||
| onDeselect | 取消选中回调 | function(value, option) | ||
| onDropdownVisibleChange | 下拉展开 / 收起回调 | function(visible) | ||
| onExceed | 超过 max 上限回调(多选有效) | function | ||
| onSearch | 输入框内容变化回调(第二参数 v2.31 后提供) | function(sugInput, e) | ||
| onSelect | 选中回调 | function(value, option) |
说明:完整字段(含
aria-*、insetLabel、onListScroll、onMouseEnter/onMouseLeave、preventScroll、motion、mouseEnterDelay、mouseLeaveDelay等)可查阅 index.tsx 中的SelectProps类型定义。
Option Props
不同 Option 的
label必须唯一,value允许重复。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| className | 外层类名 | string | |
| disabled | 禁用 | boolean | false |
| label | 展示文本;渲染时优先取 label,其次取 children,再退化为 value | string | ReactNode | |
| showTick | 选中时是否展示勾选 Icon | boolean | true |
| style | 内联样式 | object | |
| value | 属性值 | string | number |
OptGroup Props
| 属性 | 说明 | 类型 |
|---|---|---|
| className | CSS 类名 | string |
| label | 展示文本 | ReactNode |
| style | 内联样式 | object |
Methods:通过 ref 调用
Select 通过 ref 暴露以下内部方法:
| 方法 | 说明 | 版本 |
|---|---|---|
| close | 手动关闭下拉列表 | |
| clearInput | 手动清空输入框值 | |
| deselectAll | 手动清空已选项 | |
| focus | 手动聚焦 Select | |
| open | 手动打开下拉列表 | |
| selectAll | 手动选中全部选项 | |
| search(value: string, event: event) | 通过 ref 触发搜索,搜索值会写入 Input | v2.35.0 |
| rePosition | 手动触发下拉层重新定位 |
无障碍(Accessibility)
ARIA
- Select 触发器 role 为
combobox,弹出层 role 为listbox,选项 role 为option; - 触发器带有
aria-haspopup、aria-expanded、aria-controls,表示触发器与弹出层的关联关系; - 多选时 listbox 的
aria-multiselectable为true; - Option 选中时
aria-selected为true,禁用时aria-disabled为true; aria-activedescendant保证屏幕朗读时能识别当前选中的选项。
键盘与焦点
无 filter 的 Select:
- 聚焦后,可用
Up Arrow/Down Arrow/Enter打开下拉,并自动聚焦到第一项(defaultActiveFirstOption默认 true); - 下拉打开时:
Esc或Tab关闭菜单;Up Arrow/Down Arrow切换选项;Enter选中并收起面板; - 焦点在自定义插槽交互元素上时,
Tab可在插槽元素间切换,Shift + Tab可回到 Select 选择框。
带 filter 的 Select:
- 聚焦后同样可用方向键 / Enter 打开下拉,焦点仍在选择框上,可输入内容同时用方向键切换选项;
- 下拉打开后键盘交互与无 filter 一致;
- 焦点在选择框上时,插槽内交互元素的 Tab / Shift+Tab 行为同上。
内容规范(Content Guidelines)
- 触发器文案:用 1~3 个词描述用户需要做的输入;使用陈述式书写规范(首字母大写,其余小写);避免标点与冠词(the / an / a);标签需是独立语句,不要让标签与选项拼成一句话;使用描述性而非指示性语句,如需更多解释可在选择框下方提供帮助文本。
- 选项文案:无默认选项时用 "Select" 作为占位文案;选项按字母序或其他逻辑顺序排列;同样遵循陈述式书写规范,避免句尾逗号分号;清晰表达该选项所代表的含义。
TypeScript 泛型支持
Select 组件支持通过泛型参数约束 value 类型,获得更精确的类型推断(无需手动类型转换):
import { Select } from '@douyinfe/semi-ui';
// 指定 value 为 string 类型
<Select<string>
value={selectedValue}
onChange={(value) => {
// value 类型为 string | string[] | undefined
setSelectedValue(value);
}}
>
<Select.Option value="option1">Option 1</Select.Option>
<Select.Option value="option2">Option 2</Select.Option>
</Select>
// 多选模式下 value 类型为 string[]
<Select<string>
multiple
value={selectedValues}
onChange={(value) => {
// 由于 multiple 为 true,实际为 string[]
setSelectedValues(value as string[]);
}}
>
<Select.Option value="option1">Option 1</Select.Option>
<Select.Option value="option2">Option 2</Select.Option>
</Select>
源码层面,SelectValue<T> 的推导逻辑是:未提供泛型时保持向后兼容的 string | number | any<a href="https://link.gitcode.com/i/797fd9428a1226ded935ab1fcb054ae2" target="_blank">] | Record | undefined;提供泛型 T 时推导为 T | T[] | undefined(见 [index.tsx)。
常见问题 FAQ
-
可搜索 Select 用远程数据动态更新
optionList,为何异步请求完成前有时没数据? 检查是否设置了remote={true}。未设置时,输入值默认与当前 optionList 做本地匹配,无匹配项即无数据展示;remote可关闭对当前本地数据的匹配过滤。 -
用 JSX 声明 Option、label 为 i18n 后内容,切换 locale 后无法重新渲染? 以 JSX children 声明 Option 时,内容为 ReactNode,无法用 deepEqual 对比是否更新(性能开销过大),组件通过收集 children 的
key判断;key 不变即认为 Options 未变化,不会重新收集数据。可将 locale 作为 Option key 的一部分,或改用optionList传入(对象形式 key 相对有限,内部用 isEqual 判断变化)。 -
用 JSX 声明 Option,动态切换 disabled 属性后不生效? 原因同上。可重新设置不同的 key 值,或改用
optionList声明候选。 -
Select 会自动限制下拉菜单宽度吗? 会给定 MinWidth,但不会写死 width;如需固定宽度可自行通过
dropdownStyle添加。 -
设置 allowCreate 后,动态更新 optionList 或 children 不生效?
allowCreate主要用于本地创建场景,开启后相当于强制接管 optionList/children,不再响应外部更新——否则本地已创建条目如何与最新 props 合并(覆盖还是融合)高度依赖业务逻辑,组件层不适合强制定制。 -
为什么 Semi 的 Select 要求 label 唯一而非 value 唯一? 首先必须有唯一标识做选中判断;几乎所有 UI 库用 Select.Option 时只要求 label 和 value 两个值。选择用 label 是因为 label 是用户感知的内容:若两个选项展示完全一致,用户视角无法区分但选中效果不同(如一个 value 为 0、一个为 1),交互上不合理。而“label 唯一、value 重复”在日常场景中很常见,例如按 App 名选择公司 id:value 是对应公司 id,label 是 App 名。若确实需要重复 label,可传入 ReactNode 类型的 label 绕过该限制。
-
单选选中后为何不触发 blur 事件? v2.17.0 之前单选选中会触发 Select 的 blur;v2.17.0 起增加 A11y 支持后不再触发。单选选中后面板关闭,焦点仍在触发器上(此时按 Enter 可再次打开)。无论单选多选,按 Esc 仅关闭浮动层,触发器保持焦点(按 Enter 可再次打开)。