Listbox

在浮层中展示可选择的选项，支持搜索过滤与键盘操作，可作为 Select 的选择面板。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于有选项、键盘导航和选择语义的列表面板，通常由 Select 承载。通知、联系人、活动流是内容列表，不使用 Listbox。

items 的 value 必须唯一，label 用于显示和搜索；children 存在时替换 items。
显式选项使用 MenuItem as="item"；显式搜索使用 Input as="search" 并关闭内置 search，避免重复输入框。
默认内置搜索占位通过 listbox.search 随 LocaleProvider 切换；parts.Input.placeholder（含空字符串）与原生 aria-label 保持优先，显式 Input 子项由调用方配置，查询和选项内容不翻译。

导入

import { Listbox } from '@snowui-design-system/components';

用法

自定义类别

页面状态

长列表

位置

宽度与对齐

悬停反馈

选中标记

API 参考

属性	类型	默认值	示例	描述
`children`	`Snippet`	`—`	`<Select><Listbox search={false}><MenuItem as="item" value="guides">Guides</MenuItem></Listbox></Select>`	无参数的显式选项内容；传入后不生成 `items`。选项使用 `MenuItem as="item"` 并提供唯一 `value`；外置搜索使用 `Input as="search"`，同时设置 `search={false}` 避免重复内置搜索框。
`items`	`ListboxItem[]`	`[]`	`items={[{ value: "guides", label: "Guides" }, { value: "archive", label: "Archive", disabled: true }]}`	默认内置选项数组；每项包含必填且唯一的字符串 `value`、显示及搜索使用的 `label`、可选 `disabled`。有 children 时忽略；运行时自定义项由宿主另行管理。
`parts`	`ComponentPartsOf<{ Input: typeof Input; MenuItem: typeof MenuItem; Text: typeof Text; }>`	`—`	`parts={{ Input: { placeholder: "Find a component…" } }}`	配置默认内置 Input、MenuItem 与字符串标签 Text 的公开 Props，例如搜索 placeholder、allowCustomValue、选项 showCheck 或标签排版；parts.Text 只作用于实际生成的 items／自定义选项标签，显式子项自行配置。parts.MenuItem.showCheck 优先于 Listbox 的 showCheck。
`search`	`boolean`	`—`	`search`	是否生成固定在面板顶部的 Input；依次读取显式值、宿主配置并回退 true。Select 默认向 Listbox 提供 false；需要搜索时显式开启。
`maxHeight`	`number \| string`	`—`	`maxHeight={200}`	面板最大高度，数字为 px，字符串为 CSS 长度；受可用视口约束。未设置时最多完整显示 10 项，空间不足时至少保留实际选项中的前 2 项。
`minWidth`	`number \| string`	`—`	`minWidth={120}`	面板最小宽度，数字为 px，字符串为 CSS 长度；未设置时搜索开启取 160px，否则取 0。内容与视口约束仍参与最终宽度计算。
`scrollbar`	`boolean`	`true`	`scrollbar`	溢出时显示浮层滚动条；false 仅隐藏轨道，仍可通过滚轮和键盘滚动。
`matchTriggerWidth`	`boolean`	`true`	`matchTriggerWidth`	true 时以锚点实测宽度加固定 2px 为宽度基准，左右各覆盖 1px，内容需要更宽时允许扩展；false 时按选项内容 Hug，不添加补偿，仍受 minWidth 与视口约束。
`placementMode`	`"selected" \| "bottom"`	`"selected"`	`placementMode="selected"`	selected 将选中项中心对齐触发器；bottom 从触发器下方展开。最终定位与高度受可用视口约束。
`align`	`"start" \| "end"`	`"start"`	`align="start"`	面板相对锚点左边缘或右边缘对齐；Hug 面板与锚点宽度不同时差异明显，最终位置受视口约束。
`showCheck`	`boolean`	`false`	`showCheck`	为选中项预留并显示 trailing 勾选；Select 默认提供 true。显式 MenuItem 可用自身 showCheck 覆盖，自定义 trailing 替换默认勾选。
`continuousHover`	`boolean`	`true`	`continuousHover`	在直接 MenuItem 之间移动同一个高亮背景，键盘 active 共用该背景；false 恢复逐项即时背景，禁用和过滤项不作为目标。