--- localeCode: zh-CN order: 46 category: 输入类 title: Select 选择器 icon: doc-select width: 60% brief: 用户可以通过 Select 选择器从一个选项集合中去选中一个或多个选项，并呈现最终选择结果 --- ## 代码演示 ### 如何引入 ```jsx import import { Select } from '@douyinfe/semi-ui'; const Option = Select.Option; ``` Select的直接子元素必须为 Option 或者 OptGroup，不允许为其他Element ### 基本使用 每个 Option 标签都必须声明 value 属性，Option 的 children 或 label 将会被渲染至下拉列表中 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( <>



); ``` ### 以数组形式传入 Option 可以直接通过`optionList`传入一个对象数组，每个对象必须包含 value/label 属性（当然其他属性也可以通过此方式传入） ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => { const list = [ { value: 'douyin', label: '抖音', otherKey: 0 }, { value: 'ulikecam', label: '轻颜相机', disabled: true, otherKey: 1 }, { value: 'jianying', label: '剪映', otherKey: 2 }, { value: 'toutiao', label: '今日头条', otherKey: 3 }, ]; return ; }; ``` ### 多选 自 v2.28后，select 的选择器会自带 maxHeight 270，内容超出后可以通过垂直滚动查看。 配置`multiple`属性，可以支持多选 配置 `maxTagCount` 可以限制已选项展示的数量，超出部分将以+N 的方式展示 配置 `ellipsisTrigger` (>= v2.28.0) 对溢出部分的 tag 做自适应处理，当宽度不足时，最后一个tag内容作截断处理。开启该功能后会有一定性能损耗，不推荐在大表单场景下使用 配置 `expandRestTagsOnClick` (>= v2.28.0) 可以在设置 `maxTagCount` 情况下通过点击展示全剩余的tag 使用 `showRestTagsPopover` (>= v2.22.0) 可以设置在超出 `maxTagCount` 后，hover +N 是否显示 Popover，默认为 `false`。并且，还可以在 `restTagsPopoverProps` 属性中配置 Popover。 配置 `max` 属性可限制最大可选的数量，超出最大限制数量后无法选中，同时会触发`onExceed`回调 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( <>





); ``` ### 分组 用 OptGroup 进行分组（分组功能仅支持通过 jsx 方式声明 children 使用，不支持 optionList 方式传入） 1. OptGroup 必须为 Select 的直接子元素，不允许有 Fragment 或 DIV 等其他元素阻隔 2. 若 Select 的 children 需要动态更新，OptGroup 上的 key 也需要进行更新，否则 Select 无法识别 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( ); ``` ```jsx live=true 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 ( ); }; ``` ### 不同尺寸 通过 Size 控制选择器的大小尺寸: `small` / `default` / `large` ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( <>



); ``` ### 不同校验状态样式 validateStatus: default / warning / error 仅影响背景颜色等样式表现 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( <>



); ``` ### 配置前缀、后缀、清除按钮 - 可以通过`prefix`传入选择框前缀，通过`suffix`传入选择框后缀，可以为文本或者 ReactNode 当 prefix、suffix 传入的内容为文本或者 Icon 时，会自动带上左右间隔，若为自定义 ReactNode，则左右间隔为 0 - 通过`showClear`控制清除按钮是否展示 - 通过`showArrow`控制右侧下拉箭头是否展示 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; import { IconVigoLogo, IconGift } from '@douyinfe/semi-icons'; () => ( <>

); ``` ### 在顶部/底部渲染附加项 我们在弹出层顶部、底部分别预留了插槽，当你需要在弹出层中添加自定义 node 时 可以通过`innerBottomSlot`或者`outerBottomSlot`传入，自定义 node 将会被渲染在弹出层底部；可以通过`innerTopSlot`或者`outerTopSlot`传入，自定义 node 将会被渲染在弹出层顶部。 - `innerTopSlot` 和 `innerBottomSlot`将会被渲染在 optionList 内部，当滚动到 optionList 顶部/底部时展现 - `outerTopSlot` 和 `outerBottomSlot`将会被渲染为与 optionList 平级，无论 optionList 是否滚动，都会始终展现 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => { let innerSlotStyle = { backgroundColor: 'var(--color-white)', height: '36px', display: 'flex', alignItems: 'center', cursor: 'pointer', paddingLeft: 32, borderTop: '1px solid var(--semi-color-border)', borderRadius: '0 0 6px 6px', color: 'var(--semi-color-link)', }; let innerSlotNode =
点击加载更多
; let outSlotStyle = { backgroundColor: 'var(--semi-color-fill-0)', height: '36px', display: 'flex', paddingLeft: 32, color: 'var(--semi-color-link)', alignItems: 'center', cursor: 'pointer', borderTop: '1px solid var(--semi-color-border)', borderRadius: '0 0 6px 6px', }; let outSlotNode = (
未找到应用?
); return (

outerBottomSlot:

innerBottomSlot:

); }; ``` 通过 outerTopSlot 将内容插入顶部插槽 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => { const list = { component: [ { value: 'select', label: '选择器' }, { value: 'tabs', label: '标签' }, { value: 'avatar', label: '头像' }, { value: 'button', label: '按钮' }, ], design: [ { value: 'color', label: '颜色' }, { value: 'dark', label: '暗色模式' }, { value: 'icon', label: '图标' }, { value: 'font', label: '字体' }, ], feedback: [ { value: 'faq', label: '常见问题' }, { value: 'join', label: '加入用户群' }, { value: 'hornbill', label: '犀鸟反馈问题' }, ], }; const [key, setKey] = useState('component'); const [value, setValue] = useState({ value: 'faq', label: '常见问题' }); const handleTdouyinlick = itemKey => { setKey(itemKey); }; const tabStyle = { cursor: 'pointer', marginRight: 12, paddingBottom: 4, }; const tabActiveStyle = { ...tabStyle, borderBottom: '1px solid var(--semi-color-primary)', fontWeight: 700, }; const tabWrapper = { display: 'flex', paddingTop: 8, paddingLeft: 32, borderBottom: '0.5px solid var(--semi-color-border)', }; const tabOptions = [ { itemKey: 'component', label: '组件' }, { itemKey: 'design', label: '设计' }, { itemKey: 'feedback', label: '反馈' }, ]; const outerTopSlotNode = (
{tabOptions.map((item, index) => { style = item.itemKey === key ? tabActiveStyle : tabStyle; return (
handleTdouyinlick(item.itemKey)}> {item.label}
); })}
); return ( 抖音 轻颜相机 剪映 西瓜视频 ); }; ``` ### 动态修改 Options 如果需要动态更新 Options，应该使用受控的 value ```jsx live=true hideInDSM import React, { useState } 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 ( <>

); }; ``` ### 联动 使用受控 value，实现不同 Select 之间的联动。如果是带有层级关系的复杂联动建议直接使用`Cascader`组件 ```jsx live=true hideInDSM import React, { useState } from 'react'; import { Select } from '@douyinfe/semi-ui'; () => { const provinces = ['四川', '广东']; const maps = { 四川: ['成都', '都江堰'], 广东: ['广州', '深圳', '东莞'], }; const [province, setProvince] = useState(provinces[0]); const citys = maps[province]; const [city, setCity] = useState(citys[0]); const provinceChange = newProvince => { setProvince(newProvince); setCity(maps[newProvince][0]); }; const cityChange = newCity => setCity(newCity); return ( <> ); }; ``` ### 开启搜索 将 `filter` 置为 true，开启搜索能力。默认搜索策略将为 input 输入值与 option 的 label 值进行 include 对比 默认情况下，多选选中后会自动清空搜索关键字。若你希望保留，可以通过 autoClearSearchValue 设为 false 关闭默认行为（v2.3 后提供） ```jsx live=true hideInDSM import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( <>

); ``` ### 搜索框位置 默认搜索框展示于 Select 的 Trigger 触发器上。通过 `searchPosition` 可以指定不同的位置，可选 `dropdown`、`trigger`。 在 v2.61.0后提供 若希望定制位于 dropdown 中的 Input 搜索框的 placeholder，可以通过 `searchPlaceholder` 控制 若 `searchPosition` 值为 `trigger`，当showClear=true 时，点击Trigger区域的清空按钮，将同时清空已选项以及搜索框中的文本 若 `searchPosition` 值为 `dropdown`，当showClear=true 时，点击Trigger区域清空按钮，仅清空已选项。点击搜索框中的清空按钮，仅清空搜索文本 ```jsx live=true import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( <>

); ``` ### 远程搜索 带有远程搜索，防抖请求，加载状态的多选示例 通过`filter`开启搜索能力 将`remote`设置为 true 关闭对当前数据的筛选过滤 通过动态更新`optionList`更新下拉菜单中的备选项 使用受控的 value 属性 ```jsx live=true import React from 'react'; import { debounce } from 'lodash-es'; import { Select } from '@douyinfe/semi-ui'; () => { const [loading, setLoading] = useState(false); const optionList = [ { value: 'douyin', label: '抖音', type: 1 }, { value: 'xingtu', label: '醒图', type: 2 }, { value: 'jianying', label: '剪映', type: 3 }, { value: 'toutiao', label: '今日头条', 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: `相近业务 ${inputValue}${i}`, type: i + 1 }; }); setTimeout(() => { setLoading(false); setList(result); }, 1000); } else { setLoading(false); } }; return ( ); }; ``` ### 自定义搜索逻辑 可以将 `filter` 置为自定义函数，定制你想要的搜索策略 如下例子，选项 label 值都是大写，默认的检索策略是字符串 include 对比，会区分大小写。 通过传入自定义 `filter` 函数，检索时输入小写字母也能搜到相应内容。 ```jsx live=true hideInDSM import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => { function searchLabel(sugInput, option) { let label = option.label.toUpperCase(); let sug = sugInput.toUpperCase(); return label.includes(sug); } return ( ); }; ``` ### 自定义已选项标签渲染 默认情况下，选中选项后会将 option.label 或 option.children 的内容回填到选择框中 但你可以通过 `renderSelectedItem` 自定义选择框中已选项标签的渲染结构 - 单选时 `renderSelectedItem(optionNode:object) => content:ReactNode` - 多选时 `renderSelectedItem(optionNode:object, { index:number, onClose:function }) => { isRenderInTag:bool, content:ReactNode }` - isRenderInTag 为 true 时，会自动将 content 包裹在 Tag 中渲染（带有背景色以及关闭按钮） - isRenderInTag 为 false 时，将直接渲染返回的 content ```jsx live=true import React from 'react'; import { Select, Avatar, Tag } from '@douyinfe/semi-ui'; () => { const list = [ { name: '夏可漫', email: 'xiakeman@example.com', avatar: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png', }, { name: '申悦', email: 'shenyue@example.com', avatar: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/bag.jpeg', }, { name: '曲晨一', email: 'quchenyi@example.com', avatar: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/Viamaker.png', }, { name: '文嘉茂', email: 'wenjiamao@example.com', avatar: 'https://sf6-cdn-tos.douyinstatic.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/6fbafc2d-e3e6-4cff-a1e2-17709c680624.png', }, ]; const renderSelectedItem = optionNode => (
{optionNode.abbr} {optionNode.email}
); // avatarSrc & avatarShape are supported const renderMultipleWithCustomTag = (optionNode, { onClose }) => { const content = ( {optionNode.name} ); return { isRenderInTag: false, content, }; }; const renderMultipleWithCustomTag2 = (optionNode, { onClose }) => { const content = ( {optionNode.name} ); return { isRenderInTag: false, content, }; }; const renderCustomOption = (item, index) => { const optionStyle = { display: 'flex', paddingLeft: 24, paddingTop: 10, paddingBottom: 10, }; return (
{item.name}
{item.email}
); }; return ( <> ); }; ``` ### 自定义弹出层样式 你可以通过 dropdownClassName、dropdownStyle 控制弹出层的样式 例如当自定义弹出层的宽度时，可以通过 dropdownStyle 传入 width ```jsx live=true hideInDSM import React from 'react'; import { Select } from '@douyinfe/semi-ui'; () => ( ); ``` ### 获取选项的其他属性 默认情况下`onChange`只能拿到 value，如果需要拿选中节点的其他属性，可以使用`onChangeWithObject`属性 此时`onChange`函数的入参将会是 object，包含 option 的各种属性，例如 `onChange({ value, label, ...rest })` 当 onChangeWithObject 置为 true 时，`defaultValue` / `Value` 也应为 object，且须带有 `value`、`label` key ```jsx live=true hideInDSM import React from 'react'; import { Select, TextArea } from '@douyinfe/semi-ui'; () => { const list = [ { value: 'douyin', label: '抖音', type: 1 }, { value: 'ulikecam', label: '轻颜相机', type: 2 }, { value: 'jianying', label: '剪映', type: 3 }, { value: 'toutiao', label: '今日头条', type: 4 }, ]; const [cbValue, setCbValue] = useState(); const [multipleCbValue, setMultipleCbValue] = useState(); const onChange = value => { setCbValue(value); console.log(value); }; const onMultipleChange = value => { setMultipleCbValue(value); console.log(value); }; return (

onChange回调: