Select

Select 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 Select 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Select 通过 prop 构成简单结构：

1import { Select, SelectItem } from "@lenso/ui";2
3export default function App() {4  return (5    <Select label="Select animal" placeholder="Choose one">6      <SelectItem key="cat">Cat</SelectItem>7      <SelectItem key="dog">Dog</SelectItem>8    </Select>9  );10}

在 v3 中，Select 需要使用复合组件，并通过 ListBox 渲染菜单项：

1import { Select, Label, ListBox } from "@lenso/ui";2
3export default function App() {4  return (5    <Select placeholder="Choose one">6      <Label>Select animal</Label>7      <Select.Trigger>8        <Select.Value />9        <Select.Indicator />10      </Select.Trigger>11      <Select.Popover>12        <ListBox>13          <ListBox.Item id="cat" textValue="Cat">14            Cat15            <ListBox.ItemIndicator />16          </ListBox.Item>17          <ListBox.Item id="dog" textValue="Dog">18            Dog19            <ListBox.ItemIndicator />20          </ListBox.Item>21        </ListBox>22      </Select.Popover>23    </Select>24  );25}

关键变化

1. 组件结构

v2： 简单的 Select，子节点为 SelectItem
v3： 复合组件（Select.Trigger、Select.Value、Select.ClearButton、Select.Indicator、Select.Popover）与用于菜单项的 ListBox

2. 菜单项组件

v2： SelectItem、SelectSection
v3： ListBox.Item、ListBox.Section（分组标题使用 Header，分组之间使用 Separator）

3. Prop 变更

v2 prop	v3 位置	说明
`selectedKeys`	`value`	从 Set / 数组改为单个值或数组
`onSelectionChange`	`onChange`	已重命名的事件处理函数
`defaultSelectedKeys`	`defaultValue`	已重命名的 prop
`label`	—	使用 `Label` 组件
`description`	—	使用 `Description` 组件
`errorMessage`	—	使用 `FieldError` 组件
`variant`	`variant`	仅保留 `primary` \| `secondary`
`color`	—	已移除（请使用 Tailwind CSS）
`size`	—	已移除（请使用 Tailwind CSS）
`radius`	—	已移除（请使用 Tailwind CSS）
`classNames`	—	在各子组件上使用 `className` prop
`startContent`	—	直接自定义 `Select.Trigger`
`endContent`	—	直接自定义 `Select.Trigger`
`selectorIcon`	—	自定义 `Select.Indicator` 的 children
`isClearable`	`Select.ClearButton`	内置子组件；不要在 `Select.Trigger` 内嵌套 `<button>`
`renderValue`	—	使用 `Select.Value` 的渲染 prop
`labelPlacement`	—	标签始终在外部
`isRequired`	`isRequired`	仍然可用
`disabledKeys`	`disabledKeys`	仍然可用
`isOpen`	`isOpen`	新增：受控地控制 Popover 的打开状态
`defaultOpen`	`defaultOpen`	新增：非受控的默认打开状态
`onOpenChange`	`onOpenChange`	新增：打开状态变化时触发
`selectionMode`	`selectionMode`	仍然可用
`disableAnimation`	—	已移除（动画机制已不同）
`popoverProps`、`listboxProps`、`scrollShadowProps`	—	直接在 `Select.Popover`、`ListBox` 等组件上传入 prop

迁移示例

选择

1import { useState } from "react";2
3{/* Single selection */}4const [singleValue, setSingleValue] = useState(new Set([]));5<Select6  selectedKeys={singleValue}7  onSelectionChange={setSingleValue}8  label="Select animal"9>10  <SelectItem key="cat">Cat</SelectItem>11  <SelectItem key="dog">Dog</SelectItem>12</Select>13
14{/* Multiple selection */}15const [multiValue, setMultiValue] = useState(new Set([]));16<Select17  selectionMode="multiple"18  selectedKeys={multiValue}19  onSelectionChange={setMultiValue}20  label="Select animals"21>22  <SelectItem key="cat">Cat</SelectItem>23  <SelectItem key="dog">Dog</SelectItem>24</Select>

表单校验

1{/* With description */}2<Select3  label="Select animal"4  description="Choose your favorite"5  placeholder="Choose one"6>7  <SelectItem key="cat">Cat</SelectItem>8</Select>9
10{/* With validation */}11<Select12  isInvalid13  errorMessage="Please select an option"14  label="Select animal"15>16  <SelectItem key="cat">Cat</SelectItem>17</Select>

带分组

1import { Select, SelectItem, SelectSection } from "@lenso/ui";2
3<Select label="Select animal">4  <SelectSection title="Mammals">5    <SelectItem key="cat">Cat</SelectItem>6    <SelectItem key="dog">Dog</SelectItem>7  </SelectSection>8  <SelectSection title="Birds">9    <SelectItem key="eagle">Eagle</SelectItem>10    <SelectItem key="parrot">Parrot</SelectItem>11  </SelectSection>12</Select>

受控的打开状态

1{/* v2 不支持受控的打开状态 */}2<Select label="Select animal">3  <SelectItem key="cat">Cat</SelectItem>4  <SelectItem key="dog">Dog</SelectItem>5</Select>

禁用选项

1import { Select, SelectItem } from "@lenso/ui";2
3<Select label="Select animal" disabledKeys={["dog"]}>4  <SelectItem key="cat">Cat</SelectItem>5  <SelectItem key="dog">Dog</SelectItem>6  <SelectItem key="parrot">Parrot</SelectItem>7</Select>

必填

1import { Select, SelectItem } from "@lenso/ui";2
3<Select isRequired label="Select animal">4  <SelectItem key="cat">Cat</SelectItem>5  <SelectItem key="dog">Dog</SelectItem>6</Select>

自定义指示器

1<Select selectorIcon={<CustomIcon />} label="Select animal">2  <SelectItem key="cat">Cat</SelectItem>3</Select>

组件剖析

v3 Select 的结构如下：

1Select (Root)2  ├── Label (optional)3  ├── Select.Trigger4  │   ├── Select.Value5  │   ├── Select.ClearButton（可选）6  │   └── Select.Indicator7  ├── Description (optional)8  ├── Select.Popover9  │   └── ListBox10  │       ├── ListBox.Item11  │       │   ├── Label (optional)12  │       │   ├── Description (optional)13  │       │   └── ListBox.ItemIndicator14  │       ├── ListBox.Section (optional)15  │       │   ├── Header (section title)16  │       │   └── ListBox.Item17  │       └── Separator (optional, between sections)18  └── FieldError (optional)

重要说明

菜单项标识

v2： React 的 key 同时用于列表协调与选择时的项标识。
v3： 在 ListBox.Item 上使用 id（状态 / 焦点）与 textValue（无障碍）；列表协调仍使用 React 的 key。

选择值的类型

v2： selectedKeys 为 Set<Key> 或数组
v3： 单选时 value 为 Key | null，多选时为 Key[]

清除按钮

isClearable prop 已移除。请在 Select.Trigger 内使用 Select.ClearButton。不要在触发器内嵌套 <button> — Select.Trigger 本身已经是 button。

清除控件面向指针操作；触发器同时支持按 Backspace 或 Delete 清除，以便键盘与屏幕阅读器用户使用。

1<Select value={value} onChange={setValue}>2  <Select.Trigger>3    <Select.Value />4    <Select.ClearButton />5    <Select.Indicator />6  </Select.Trigger>7  {/* ... */}8</Select>

总结

组件结构：必须使用复合组件（Select.Trigger、Select.Value、Select.ClearButton、Select.Indicator、Select.Popover）。
菜单项组件：SelectItem → ListBox.Item，SelectSection → ListBox.Section（分组标题用 Header，分组之间用 Separator）。
标签 / 描述 / 错误：使用独立组件，而不是对应 prop。
选择相关 prop：selectedKeys / onSelectionChange → value / onChange。
受控的打开状态：新增 isOpen、defaultOpen、onOpenChange 用于控制 Popover 的打开状态。
禁用选项：仍支持 disabledKeys 以禁用指定菜单项。
必填：仍支持 isRequired 标记字段为必填。
样式：variant 仅保留 primary | secondary；color、size、radius 已移除，请用 Tailwind CSS 扩展。
classNames 已移除：在各子组件上使用 className prop。
内容类 prop 已移除：startContent、endContent 需通过自定义触发器实现。
清除按钮：isClearable 已移除，请在 Select.Trigger 内使用 Select.ClearButton（不要嵌套 <button>）。
自定义值：用 Select.Value 的渲染 prop 替代 renderValue。