Gravity UI – UIKit

import {Select} from '@gravity-ui/uikit';

Select 是一个控件，提供用户可以选择的选项列表。

选项

可供选择的选项。

定义选项

您可以将选项定义为对象数组或组件的子组件。第一种方法对于选项需要复杂准备以及可能需要记忆的情况很有用。当选项很少并且它们的配置不需要复杂的计算时，第二个很方便。

平面清单

Array of objects

Child nodes

<Select
  placeholder="value"
  options={[
    {value: 'val_1', content: 'Value 1'},
    {value: 'val_2', content: 'Value 2'},
    {value: 'val_3', content: 'Value 3'},
    {value: 'val_4', content: 'Value 4'},
  ]}
/>
<Select placeholder="value">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

分组清单

Array of objects

Child nodes

<Select
  placeholder="value"
  options={[
    {
      label: 'Group 1',
      options: [
        {value: 'val_1', content: 'Value 1'},
        {value: 'val_2', content: 'Value 2'},
      ],
    },
    {
      label: 'Group 2',
      options: [
        {value: 'val_3', content: 'Value 3'},
        {value: 'val_4', content: 'Value 4'},
      ],
    },
  ]}
/>
<Select placeholder="value">
  <Select.OptionGroup label="Group 1">
    <Select.Option value="val_1" content="Value 1" />
    <Select.Option value="val_2" content="Value 2" />
  </Select.OptionGroup>
  <Select.OptionGroup label="Group 2">
    <Select.Option value="val_3" content="Value 3" />
    <Select.Option value="val_4" content="Value 4" />
  </Select.OptionGroup>
</Select>

将数据存储在选项中

您可以使用该 option.data 属性在每个选项中定义和存储唯一数据。当您在使用 onUpdate 回调时需要丰富数据时，或者例如，在使用绘制选项时，这可能很有用 renderOption。

选择多个选项

要启用多项选择，请使用该 multiple 属性。它的默认值是 false。

<Select multiple={true} placeholder="values">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

计数器

您可以使用该 hasCounter 属性将所选项目的计数器添加到组件中。

<Select multiple={true} hasCounter={true} placeholder="values">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

筛选选项

要启用筛选分区，请使用该 filterable 属性。它的默认值是 false。

<Select filterable={true} placeholder="Filterable">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

大小

要管理默认控件和选项大小，请使用该 size 属性。它的默认大小是 m。

<Select size="s" placeholder="S Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>
<Select size="m" placeholder="M Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>
<Select size="l" placeholder="L Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>
<Select size="xl" placeholder="XL Size">
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>

控制宽度

默认情况下，控件宽度会拉伸以匹配所选选项内容的宽度。您可以使用以下 width 属性对其进行管理：

'max':拉伸到父项的全宽。

number:应用以像素为单位的宽度。

Default

Max

In pixels

<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select width="max">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select width={150}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

弹出窗口宽度

您可以使用该 popupWidth 属性管理弹出窗口的宽度。可用值为：

'fit':应用控制宽度。

number:应用以像素为单位的宽度。

关于默认行为的注意事项：

弹出窗口的宽度等于最宽选项的宽度，但不超过 90vw。这不适用于您使用虚拟化的情况。
缩小选项会被拉伸以适应控件的宽度。

Non-virtualized list

A regular list when all the elements are in the dom tree at once.

Default

Fit

In pixels

<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>

虚拟化列表

为了以最佳方式显示大量选项， Select 内置列表虚拟化工具。在超过选项数量的阈值（50 默认情况下）后，将启用虚拟化。您可以使用该 virtualizationThreshold 属性管理此值。

使用虚拟化时，一些限制适用于弹出式元素：

弹出窗口的宽度不再调整为最长选项的长度。
弹出窗口的最小宽度等于控件的宽度，或者 100px 如果控件较短。

Default

In pixels

<Select>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth="fit">
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select popupWidth={80}>
  <Select.Option value="val_1">Loooooooooooooooooooong Value 1</Select.Option>
  <Select.Option value="val_2">Loooooooooooooooooooong Value 2</Select.Option>
  <Select.Option value="val_3">Loooooooooooooooooooong Value 3</Select.Option>
  <Select.Option value="val_4">Loooooooooooooooooooong Value 4</Select.Option>
</Select>

高级用法

有很多方法可以自定义 Select.

渲染自定义控件

要呈现自定义控件，请使用该 renderControl 属性。注意：你应该将所有参数转发到你的节点，以启用一致的行为，就像使用默认控件时一样。

<Select
  renderControl={({onClick, onKeyDown, ref}) => {
    return <button ref={ref} onClick={onClick} extraProps={{onKeyDown}}>Custom control</button>
  }}
>
  <Select.Option value="val_1">Value 1</Select.Option>
  <Select.Option value="val_2">Value 2</Select.Option>
  <Select.Option value="val_3">Value 3</Select.Option>
  <Select.Option value="val_4">Value 4</Select.Option>
</Select>

渲染自定义过滤器分区

要呈现自定义滤镜部分，请使用该 renderFilter 属性并将该 filterable 属性设置为 true。注意：您需要将所有参数转发到您的节点才能启用正常运行的过滤器，就像使用默认配置一样。

<Select
  placeholder="Custom filter"
  filterable={true}
  renderFilter={({onChange, onKeyDown, ref, value}) => {
    return (
      <div style={{display: 'flex', flexDirection: 'column'}}>
        <input
          ref={ref}
          value={value}
          size="1"
          onKeyDown={onKeyDown}
          onChange={(e) => onChange(e.target.value)}
        />
        <button>Do smth</button>
      </div>
    );
  }}
>
  <Select.Option value="val_1">Value 1</Select.Option>
</Select>

呈现自定义选项

要呈现自定义选项，请使用以下 renderOption 属性：

<Select
  renderOption={(option) => {
    return (
      <div style={{color: option.data.color}}>
        {option.children}
      </div>
    );
  }}
>
  <Select.Option value="val_1" data={{color: '#8FE1A1'}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{color: '#38C0A8'}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{color: '#3A7AC3'}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{color: '#534581'}}>Value 4</Select.Option>
</Select>

呈现自定义选定选项

要呈现自定义选定选项，请使用以下 renderSelectedOption 属性：

<Select
  renderSelectedOption={(option) => {
    return (
      <div style={{color: option.data.color}}>
        {option.children}
      </div>
    );
  }}
>
  <Select.Option value="val_1" data={{color: '#8FE1A1'}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{color: '#38C0A8'}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{color: '#3A7AC3'}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{color: '#534581'}}>Value 4</Select.Option>
</Select>

不同高度的渲染选项

根据 size 属性，期权的高度是固定的。如果需要渲染不同高度的选项，则可以使用该 option.data 属性。它将存储有关您需要为选项设置的高度以及设置此值的 getOptionHeight 属性的信息。

<Select
  getOptionHeight={(option) => option.data.height}
>
  <Select.Option value="val_1" data={{height: 20}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{height: 40}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{height: 60}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{height: 80}}>Value 4</Select.Option>
</Select>

呈现自定义弹出窗口

要呈现自定义弹出窗口，请使用该 renderPopup 属性。

<Select
  filterable
  placeholder="Custom popup"
  renderPopup={({renderList, renderFilter}) => {
    return (
      <React.Fragment>
        {renderFilter()}
        <div style={{width: "100%", height: "20px", backgroundColor: "tomato"}} />
        {renderList()}
      </React.Fragment>
    );
  }}
>
  <Select.Option value="val_1" data={{color: '#8FE1A1'}}>Value 1</Select.Option>
  <Select.Option value="val_2" data={{color: '#38C0A8'}}>Value 2</Select.Option>
  <Select.Option value="val_3" data={{color: '#3A7AC3'}}>Value 3</Select.Option>
  <Select.Option value="val_4" data={{color: '#534581'}}>Value 4</Select.Option>
</Select>

错误

此 Select 状态适用于不正确的用户输入。要更改外 Select 观，请使用带有 "invalid" 值的 validationState 属性。或者，您可以通过该 errorMessage 属性提供错误消息。默认情况下，消息文本在组件外部呈现。您可以使用该 errorPlacement 属性对其进行更改。

Error message

<Select
    placeholder="Placeholder"
    errorMessage="Error message"
    validationState="invalid"
>
    <Select.Option value="val_1">Value 1</Select.Option>
    <Select.Option value="val_2">Value 2</Select.Option>
    <Select.Option value="val_3">Value 3</Select.Option>
    <Select.Option value="val_4">Value 4</Select.Option>
</Select>
<Select
    placeholder="Placeholder"
    errorPlacement="inside"
    errorMessage="Error message"
    validationState="invalid"
>
    <Select.Option value="val_1">Value 1</Select.Option>
    <Select.Option value="val_2">Value 2</Select.Option>
    <Select.Option value="val_3">Value 3</Select.Option>
    <Select.Option value="val_4">Value 4</Select.Option>
</Select>

属性

姓名	描述	类型	默认
className	控制类名	`string`
defaultValue	在使用不受控制状态时代表所选选项的默认值	`string[]`
残疾的	表明用户无法使用该控件	`boolean`	`false`
可过滤	显示选择弹出窗口有过滤器部分	`boolean`	`false`
filterOption	用于比较选项和过滤器	`function`
filterPlaceholder	默认过滤器输入占位符文本	`string`
getOptionHeight	用于设置自定义用户选项的高度	`function`
getOptionGroupHeight	用于设置自定义用户选项组的高度	`function`
hasClear	启用显示用于清除所选选项的图标	`boolean`	`false`
id	`id` HTML 属性	`string`
标签	控制标签	`string`
加载中	将加载项添加到选项列表的末尾。选项列表为空时，其工作原理类似于永久加载指示器。	`boolean`
多个	显示是否可以在列表中选择多个选项	`boolean`	`false`
名称	控件的名称	`string`
onBlur	元素失去焦点时调用的处理程序。	`function`
过滤	受控的过滤器值	`string`	`''`
onFilterChange	每次更换过滤器后都会触发	`function`
onFocus	元素获得焦点时调用的处理程序	`function`
onLoadMore	加载指示器可见时触发	`function`
onOpenChange	每次更改弹出窗口可见性后都会触发	`function`
onUpdate	当用户提交对 `Select` 值的更改时触发	`function`
选项	可供选择的选项	`（选择选项\| [选择选项组)]`
大头针	控制边框视图	`string`	`'round-round'`
占位符	占位符文本	`string`
popupClassName	带有选项列表的弹出窗口 `className`	`string`
popupPlacement	弹出窗口放置	`PopupPlacement` `数组<PopupPlacement>`	`['bottom-start', 'bottom-end', 'top-start', 'top-end']`
popupWidth	弹出窗口宽度	`数字\| '适合'\| '服装'`	`'outfit'`
qa	测试 ID 属性 (`data-qa`)	`string`
renderControl	用于呈现用户控件	`function`
renderEmptyOptions	用于为空选项列表渲染节点	`function`
renderFilter	用于渲染用户筛选器部分	`function`
renderOption	用于呈现用户选项	`function`
renderOptionGroup	用于呈现用户选项组	`function`
renderSelectedOption	用于呈现用户选择的选项	`function`
renderPopup	用于呈现用户弹出内容	`function`
大小	控件/选项大小	`string`	`'m'`
价值	代表所选选项的值	`string[]`
观点	控制视图	`string`	`'normal'`
virtualizationThreshold	选项数阈值，超过该阈值后将启用虚拟化	`number`	`50`
宽度	控制宽度	`字符串\| 数字`	`undefined`
errorMessage	错误文本	`string`
errorPlacement	错误位置	`outside` `inside`	`outside`
validationState	验证状态	`"invalid"`
hasCounter	显示所选选项数。仅当启用多选时，计数器才会出现。	`boolean`

CSS API

姓名	描述
`--g-select-focus-outline-color`	聚焦时的轮廓颜色（默认情况下缺失）

Select

§选项

§定义选项

§平面清单

§分组清单

§将数据存储在选项中

§选择多个选项

§计数器

§筛选选项

§大小

§控制宽度

Default

Max

In pixels

§弹出窗口宽度

§Non-virtualized list

Default

Fit

In pixels

§虚拟化列表

Default

In pixels

§高级用法

§渲染自定义控件

§渲染自定义过滤器分区

§呈现自定义选项

§呈现自定义选定选项

§不同高度的渲染选项

§呈现自定义弹出窗口

§错误

§属性

§CSS API

选项

定义选项

平面清单

分组清单

将数据存储在选项中

选择多个选项

计数器

筛选选项

大小

控制宽度

弹出窗口宽度

Non-virtualized list

虚拟化列表

高级用法

渲染自定义控件

渲染自定义过滤器分区

呈现自定义选项

呈现自定义选定选项

不同高度的渲染选项

呈现自定义弹出窗口

错误

属性

CSS API