# 下拉选择 - 页面: https://jiguang132.com/zh/resources/chakra-ui/docs/select - 资源: Chakra UI (https://jiguang132.com/zh/resources/chakra-ui.md) - 全部指南: https://jiguang132.com/zh/resources/chakra-ui/docs.md 从已知集合中选择一个或多个值，值数组与显示文本分开。原生表单关联、异步空集合和嵌套弹层规则见专属实用指南。 ## 随附图标许可 源码查看器包含 ICON_ATTRIBUTION.md，以及本组示例实际使用的图标集合原始许可。再分发示例时请保留；react-icons 封装包的许可证不能替代各图标集合自身的条款。 - Remix Icon: Apache License Version 2.0 用于从已知选项中选择一项或多项。如果需要输入关键词检索选项，使用 Combobox；普通原生表单可考虑 Native Select。此页针对 Chakra UI 3.37.0，不适用于 Chakra v2、Base UI 或 Radix 的同名组件。 ## 安装与组成 先完成 setup.zh.md 的 Provider 与 Emotion 初始化。基础示例从 `@chakra-ui/react` 导入 `Select`、`Portal` 和 `createListCollection`，没有独立的 Select npm 包。 固定上游源码 `vendor/apps/compositions/src/examples/select-basic.tsx` 是最小完整示例。用 `createListCollection({ items })` 建立集合，将集合传给 `Select.Root` 的 `collection`。`Select.HiddenSelect` 保留原生表单关联；`Select.Label` 提供可访问名称。触发器内使用 `Select.ValueText`，弹层由 `Portal`、`Select.Positioner`、`Select.Content`、`Select.Item` 组成。 ## 受控值与状态 - `value` 是选中值数组，单选也不要改为字符串；`onValueChange` 从事件的 `value` 读取新数组。不要传入另一个库的 `onValueChange(value)` 回调写法。 - `multiple` 启用多选；集合的值应稳定且唯一。对象数据配置 `itemToValue` 和 `itemToString`，不要依赖数组下标作为业务标识。 - `disabled` 和 `invalid` 在 Root 控制交互或错误外观；错误文案和业务校验仍由应用负责。 - 尺寸、变体、颜色、分组、清除、溢出、头像、国家选项、表单集成和嵌套弹层均有独立原生示例。本地清单保留 20 个示例，不只展示一个基础样式。 ## 异步数据不是静态选项 `select-async-loading` 额外依赖 `react-use@17.6.1`，原始代码请求公开 Pokémon 接口。其加载结束但请求失败时，原生示例的集合为空，并不代表没有匹配结果。JGuang 的 CSP 禁止该请求，因此预览明确标记网络受限，不能用空列表冒充成功。 用于自己的项目时，替换为经授权的数据源，检查 HTTP 状态，分别显示加载中、无结果和错误，提供可重试动作，并防止过期响应覆盖较新的选项。网站不提供业务后端。`重置示例` 不会解除 JGuang 的请求限制。 ## 弹层、主题与验收 普通页面可使用 Portal；在 Dialog 或 Popover 内使用时，参考 `select-open-from-dialog`、`select-open-from-popover` 的原生组合，避免把弹层错误移动到模态焦点范围之外。保持 Chakra 语义令牌和 Provider，不注入官网颜色覆盖组件。 检查方向键、Enter、Escape、Tab、焦点返回、禁用选项、清除、多选和表单提交。确认深浅色与窄屏弹层位置。独立消费项目已验证方向键打开并选中 Vue.js；这不是所有示例或所有框架均已验收的声明。 ## 来源 上游提交 `2e7517745cff2fcde0b8012f136cf99611ff262a` 的 Select MDX 与原始示例保存在 vendor；本页为 JGuang 中文实用指南。原始许可与依赖差异见 PROVENANCE.md 和 LOCAL_CHANGES.md。 ## 安装与初始化 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` 渲染前配置 ChakraProvider、defaultSystem 和 Emotion。保留宿主项目的 React 版本并检查 peer 兼容。官方 npm 安装提供组件包，不会复制以下示例源码。locale、next-themes 和框架专属 SSR 配置见资源安装指南；npm 安装之外还需单独复制所选示例源码。 ## 完整原生使用示例 这是固定版本的真实示例，不是通用 API 伪代码。复制完整源码依赖并保留命名导出；附加依赖逐例列在下方。 ```tsx "use client" import { Portal, Select, createListCollection } from "@chakra-ui/react" export const SelectBasic = () => { return ( Select framework {frameworks.items.map((framework) => ( {framework.label} ))} ) } const frameworks = createListCollection({ items: [ { label: "React.js", value: "react" }, { label: "Vue.js", value: "vue" }, { label: "Angular", value: "angular" }, { label: "Svelte", value: "svelte" }, ], }) ``` ## 全部示例与复现要求 示例名称用于选择演示，不是组件通用 variant 属性。复制所选示例全部 sourceFiles；compositions 别名表示本地文件，不是 npm 包。保留相对导入或映射到宿主真实目录。React peer 单独检查；编辑器示例保留一致的固定 Tiptap 扩展版本。 ### 基础用法 `select-basic` · 命名导出 `SelectBasic` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-basic.tsx` ### 不同尺寸 `select-with-sizes` · 命名导出 `SelectWithSizes` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-sizes.tsx` ### 不同变体 `select-with-variants` · 命名导出 `SelectWithVariants` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-variants.tsx` ### 颜色色板 `select-with-color-palette` · 命名导出 `SelectWithColorPalette` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-color-palette.tsx` ### 选项分组 `select-with-option-group` · 命名导出 `SelectWithOptionGroup` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 es-toolkit@1.47.0 ``` - `vendor/apps/compositions/src/examples/select-with-option-group.tsx` ### 受控状态 `select-controlled` · 命名导出 `SelectControlled` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-controlled.tsx` ### 异步加载 `select-async-loading` · 命名导出 `SelectAsyncLoading` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-use@17.6.1 ``` - `vendor/apps/compositions/src/examples/select-async-loading.tsx` ### React Hook Form 集成 `select-with-hook-form` · 命名导出 `SelectWithHookForm` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 @hookform/resolvers@5.4.0 react-hook-form@7.77.0 zod@4.4.3 ``` - `vendor/apps/compositions/src/examples/select-with-hook-form.tsx` ### 禁用状态 `select-with-disabled` · 命名导出 `SelectWithDisabled` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-disabled.tsx` ### 无效状态 `select-with-invalid` · 命名导出 `SelectWithInvalid` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-invalid.tsx` ### 多项选择 `select-with-multiple` · 命名导出 `SelectWithMultiple` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-multiple.tsx` ### 定位 `select-with-positioning` · 命名导出 `SelectWithPositioning` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-positioning.tsx` ### 清除 `select-with-clear` · 命名导出 `SelectWithClear` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-clear.tsx` ### 溢出 `select-with-overflow` · 命名导出 `SelectWithOverflow` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-overflow.tsx` ### 项目说明 `select-with-item-description` · 命名导出 `SelectWithItemDescription` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-item-description.tsx` ### 打开来源弹出层 `select-open-from-popover` · 命名导出 `SelectOpenFromPopover` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-open-from-popover.tsx` ### 打开来源对话框 `select-open-from-dialog` · 命名导出 `SelectOpenFromDialog` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-open-from-dialog.tsx` ### 头像 `select-with-avatar` · 命名导出 `SelectWithAvatar` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 ``` - `vendor/apps/compositions/src/examples/select-with-avatar.tsx` ### 国家 `select-with-country` · 命名导出 `SelectWithCountry` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 es-toolkit@1.47.0 ``` - `vendor/apps/compositions/src/examples/select-with-country.tsx` ### 图标按钮 `select-with-icon-button` · 命名导出 `SelectWithIconButton` · 上游原始示例 ```bash npm install @chakra-ui/react@3.37.0 @emotion/react@11.14.0 react-icons@5.6.0 ``` - `vendor/apps/compositions/src/examples/select-with-icon-button.tsx` ## 原生 API 与源码参考 源码查看器保留原始声明、import 与继承关系。Ark UI 事件契约、Chakra 样式属性和 recipe 类型仍以原生包为准；本指南不平铺或编造默认值。代码注释保留原文，不冒充正文翻译。 - `npm/@chakra-ui/react@3.37.0/dist/types/components/select/index.d.ts` - `npm/@chakra-ui/react@3.37.0/dist/types/components/select/namespace.d.ts` - `npm/@chakra-ui/react@3.37.0/dist/types/components/select/select.d.ts` ## 状态与安装后检查 执行严格类型检查、目标项目生产构建和实际操作。检查名称／焦点／键盘、深浅色、窄屏、原生支持的空／加载／错误状态以及卸载清理。预览限制远程接口、上传与下载，业务服务需自行配置。复制命令或预览就绪不代表安装完成或后端成功。 ## 来源与许可边界 https://github.com/chakra-ui/chakra-ui/tree/2e7517745cff2fcde0b8012f136cf99611ff262a 本页是 JGuang 双语实用说明，不声称全文翻译上游 MDX。原始文档与示例字节保留在 vendor。保留仓库 MIT、compositions 的 ISC 元数据和独立依赖声明；原始许可元数据差异与缺失完整声明仍作为显式审查事项，不包含 Chakra Pro 付费内容。 --- JGuang 全部资源索引: https://jiguang132.com/llms.txt