# @gridui/select 中文文档 规范地址：https://npmcn.com/package/%40gridui/select/ 版本：1\.0\.2 npm 元数据更新时间：2026-11-01T02:48:59.630Z 中文译文更新时间：2026-11-01T07:54:13.264Z 软件包许可：UNLICENSED 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40gridui/select 原文对照：https://npmcn.com/package/%40gridui/select/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：158 kB，23 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：10 个 - peer 依赖：react ^19\.2\.0，react-dom ^19\.2\.0 - 首次发布：2026-10-31T02:43:15.621Z - 最新版本发布：2026-11-01T02:48:59.464Z - 已发布版本数：4（近 12 个月 4 个） ## 中文简介 GridUI React select ## 安装 ```sh npm install @gridui/select ``` 也可以使用：`pnpm add @gridui/select`、`yarn add @gridui/select`、`bun add @gridui/select` ## README # @gridui /选择 核心家庭。公共API: `Combobox`， `ComboboxProps`， `MultiSelect`， `MultiSelectProps`， `Select`， `SelectAction`， `SelectGroup`， `SelectOption`， `SelectProps`. 从 `@gridui/select` 和负载 `@gridui/select/styles.css` 后的主题。 此家族使用的任何组合依赖项的加载样式。应用程序拥有自己的路由、标签、状态持久化和品牌。 看到 [组件所有权](https://npmcn.com/package/docs/component-ownership.md) 和 [版本历史](https://npmcn.com/package/%40gridui/select/.changeset/history/). ## 选择和组合框 `Select` 和 `Combobox` 共享期权、操作、选择状态、表单集成、 以及下拉界面、高亮、指示器、排版和运动。 基数选择拥有选项导航；组合框将基数弹出窗口与 本地可编辑输入和活动-后代列表框。 每个弹出框包含一个选项列表框和一个单独的操作页脚；按钮和 链接永远不会伪装成选项。选择默认值为 `position="popper"`,打开 在触发器下方并在视口边缘翻转。 `position="item-aligned"` 的地方 当空间允许时，将选中的项目置于触发器之上，并使用viewport安全 回退。两种模式都匹配触发器的外部宽度和限制高度 空间。选项列表独立于操作滚动。标准小巧 触发器保留2.75雷姆和2.25雷姆的最小高度。选项标签和描述包装； 可编辑输入显示一行。 `portalContainer` 可以保持弹出框在一个 封闭覆盖层的所有权和焦点边界。在模态或抽屉中， 使用 `portalContainer` 当弹出窗口必须继承本地主题或自定义门户时 的位置。基数层协调嵌套焦点和Escape处理。附加一个 自定义容器到面板，而不是其滚动体，以避免剪切菜单。 `options` 接受 `SelectOption` 条目或 `SelectGroup` 条目 `label` 和 `options`。选项值在组之间必须是唯一的；组标签必须为 独一无二的。每个选项都有一个字符串 `label`，可选字符串 `description`、装饰 `icon` React节点，以及 `disabled`。说明在标签下面换行。Select在其触发器中显示标签和图标； 组合框在其输入中显示标签。不要将交互式内容放在图标中。 使用 `value` / `onValueChange` 对于受控状态或 `defaultValue` 为当地 状态。默认值为空；没有隐式选择任何选项。所选 缺少的价值 `options` 显示其原始值并保持原生形式 提交，直到匹配的选项到达。一个显式的 “All status”等过滤器支持空值选项。否则, `placeholder` 提供空状态文本。通过提供标签 `Label.htmlFor` 和 `id`，或触发器上的可访问名称。选择转发按钮道具和 参考文献;组合框转发输入道具和裁判。 对于这两个分量， `name`， `form`， `required`, `disabled` 配置本机隐藏 选择用于表单提交和约束。无效控件聚焦于 可见触发器。原生表单重置恢复初始值；控制电话 通过接收复位 `onValueChange`，包括残疾期间。取消复位 没有效果。设置 `disabled` 在打开的控件上关闭其弹出窗口； 重新启用它会使弹出框关闭。组合框也关闭并清除其 当它变为只读时搜索；再次使其可编辑不会重新打开它。选择和操作也检查继承 激活时的字段集可用性，拒绝过时的门户交互。 提供本地化的 `clearLabel` 添加一个单独的清除按钮。它发出 空字符串并将焦点返回给触发器。对于需要的清除是禁用的， 已禁用或已空的控件。 组合框也禁用清除while `readOnly`;外部控制更新和 原生形式重置保留其正常行为。 ### 行动 两个组件都接受 `actions: readonly SelectAction[]`。每个动作都有一个 独特的 `id`， `label`，可选装饰 `icon`，可选 `disabled`. 提供 `href` (可选 `target` 和 `rel`)获取本地链接或 `onAction` 用于按钮回调。动作从不更新所选值或发出 `onValueChange`。它们在那里仍然可用 没有匹配的选项。不会创建隐式选项。 默认情况下，Actions关闭弹出窗口； `closeOnAction: false` 保持打开状态。 关闭在回调运行之前恢复触发器焦点，从而允许回调 打开一个对话框或对另一个控件进行聚焦，而不会稍后窃取焦点。联系保持 原生导航和修改点击行为。禁用的操作被跳过 Tab序列。操作位于选项列表框之外，无法到达 或者用选项导航键选择。 ### 搜索和键盘交互 `Combobox` 直接在其可编辑触发器中搜索。供应本地化 `searchLabel` 和 `emptyLabel` 字符串。可见 `Label` 通过相关 `id` 或者显式可访问名称优先于搜索标签回退。 搜索使用不区分大小写、nfkc标准化的方式过滤标签和描述 子串匹配。空组消失；禁用的匹配仍然可见。 键入不会提交选择。选择将标签提交到输入； 逃避、外部解除或关闭操作将恢复所选标签。 保持弹出窗口打开的操作保留当前查询。 选择用回车键、空格键或方向键打开，并聚焦所选选项。 向上/向下导航启用选项；Home/结束和定时字符前缀导航 也支持。输入或空格提交。组合框保留本地编辑 和IME成分；输入或其箭头键打开列表，向上/向下移动 活动选项，Enter提交启用选项。GridUI允许高亮显示 禁用了发现的组合框选项；激活它们永远不会提交。 它的输入保留DOM焦点并公开 主动选项直通 `aria-activedescendant`。如果在搜索过程中选项改变， 当高亮显示在当前结果上时，高亮显示将停留在当前结果上，否则将回落 到第一个当前结果。Enter总是使用当前结果集合。逃避逃避而不付诸行动 并将焦点返回给触发器，使封闭所有者打开。标签/ Shift + Tab 达到独立行动；禁用的操作将被跳过。教鞭解雇假 关注外部目标。 ### 服务器呈现 过程中显式呈现选定的标签、图标和原生表单值 SSR，包括分组选项和 `defaultValue`。可编辑触发器呈现 其选择标签前水合作用；关闭的弹出窗口不会显示选项或 执行操作。客户端在弹出式交互前进行补水； 保持服务器和客户端初始值/选项相同。浏览器验证 将真正的节点渲染的HTML和练习选择，重置，过滤， 独立的动作，焦点切换，以及整个视口矩阵的空结果。 不包括远程搜索和隐式选项创建。使用MultiSelect进行多次选择。 ## 实现和生命周期 Select使用基数Select；Combobox使用原生输入组合基数弹出窗口，共享GridUI 表面、排版、间距和高光。选择默认值为 `position="popper"`； `position="item-aligned"` 当空间允许时，将选定项与触发器对齐。 两种模式都使用触发器宽度，包括边框和填充。 `src/select/select.tsx` 和 `src/combobox/combobox.tsx` 拥有自己的触发器和弹出框 成分; `src/shared/` 拥有共享的选择、表单、动作和搜索合作者。它们的选项呈现器是分开的，因为Select拥有item-text 而组合框拥有一个过滤集合。基数拥有定位和 解雇。选择委托选项导航到基数；Combobox拥有自己的 可编辑输入和活动后代键盘模型。 `use-selection-value.ts` 拥有控制/本地选择和初始值重置。 `use-selection-popup.ts` 拥有可用性、打开/关闭转换和焦点切换。组合框和 多选共享查询，当前结果高亮显示，键盘移动通过 `use-search-options.ts`;选项替换永远不会留下无效的活动项。 `selection-form.tsx` 拥有本地表单关联、验证和可取消 重置观察。 `selection-actions.tsx` 呈现独立的链接和按钮。 `types.ts` 拥有共享期权、诉讼和选择合同； `options.ts` 拥有 纯滤波和平坦化； `style.ts` 拥有特定选择的表示并组成覆盖表面 样式，而不需要将变量转换为下拉菜单名称。DropdownMenu仍然 拥有公共选项行样式。 `selection-popup.tsx` 股票组合框/多选 传送门几何、明确的锚容器和焦点/逃逸事件管道； 呼叫者选择初始焦点和解雇策略。多选使用表单 带有useListField的ListFieldControl用于本地多值桥接。内部零件 不是包装出口。参见选择合同 对于键盘、表单、服务器呈现和受浏览器测试保护的焦点保证。 地表运动用途 `@gridui/overlay`;负载 `@gridui/overlay/styles.css` 在主题之后，在这个家庭之前。 ## 常见问题 ### @gridui/select 是什么？ GridUI React select ### 如何安装 @gridui/select？ 在项目目录运行 npm install @gridui/select，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2\.0）、react-dom（^19\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @gridui/select 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @gridui/select 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @gridui/select 可以商用吗？ @gridui/select 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。 ### @gridui/select 还在维护吗？ 最新版本 1\.0\.2 发布于 2026/11/01（2 天前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。