Listbox

listbox

可选列表 · WAI-ARIA roving tabindex + 单/多/纯动作 + typeahead(零依赖)

用法

单选

selectionMode="single"，点选/方向键漫游，选中项打勾。

tsx

<Listbox
  items={items}
  selectionMode="single"
  defaultSelectedKeys={["profile"]}
  onSelectionChange={setKeys}
/>

多选

selectionMode="multiple"，可多选，aria-multiselectable 自动开启。

tsx

<Listbox
  items={items}
  selectionMode="multiple"
  defaultSelectedKeys={["profile", "settings"]}
  onSelectionChange={setKeys}
/>

纯动作列表

selectionMode="none" 不持有选中态，仅靠 onAction 触发命令。

tsx

<Listbox
  items={items}
  selectionMode="none"
  onAction={(key) => console.log(key)}
  aria-label="动作列表"
/>

插槽与描述

startContent 图标、description 次级文案、endContent 快捷键、disabled 停用。

tsx

const items = [
  { key: "profile", label: "个人资料", description: "查看与编辑账户", startContent: <User className="size-4" /> },
  { key: "shortcut", label: "快捷键", endContent: <kbd className="font-mono text-xs">⌘K</kbd> },
  { key: "disabled", label: "停用项", disabled: true },
];

<Listbox items={items} selectionMode="single" />

何时用

需要一段「就地可见、键盘可达」的选项列表（菜单项、设置项、命令列表）时用。要单/多选受控选中态走 selectionMode="single"/"multiple"；只想点了就触发动作（不持有选中态）走 selectionMode="none" + onAction。和 Combobox 的区别：Combobox 带输入框与浮层、适合海量可搜索选项；Listbox 是常驻的扁平列表，无输入、无弹层。

导入

import { Listbox } from "@hulianui/ui"

Props

名称	类型	默认	说明
items*	`ListboxItemData[]`	—	列表项；每项含 `key`/`label`，可带 `description`/`startContent`/`endContent`/`disabled`
selectionMode	`"none" \| "single" \| "multiple"`	`"single"`	none=纯动作列表（不持有选中态）；single/multiple=可选
selectedKeys	`string[]`	—	受控选中键
defaultSelectedKeys	`string[]`	—	非受控初始选中键
disabledKeys	`string[]`	—	额外禁用键（与 `item.disabled` 合并）
className	`string`	—	容器类名
aria-label	`string`	—	无可见标题时的无障碍标签

Events

事件	类型	说明
onSelectionChange	`(keys: string[]) => void`	选中变化回调
onAction	`(key: string) => void`	任意项激活都触发（含 none 模式），用于命令式动作

禁忌 / 坑

selectionMode="none" 时组件不持有选中态，要响应点击必须接 onAction；onSelectionChange 在该模式下不会有意义的输出。
无可见标题时务必传 aria-label，否则屏幕阅读器读不出列表用途。
暂无其它已知坑。

Playground

selectionMode

<Listbox
  items={items}
  selectionMode="single"
  selectedKeys={keys}
  onSelectionChange={setKeys}
/>

用法

单选

selectionMode="single"，点选/方向键漫游，选中项打勾。

tsx

<Listbox
  items={items}
  selectionMode="single"
  defaultSelectedKeys={["profile"]}
  onSelectionChange={setKeys}
/>

多选

selectionMode="multiple"，可多选，aria-multiselectable 自动开启。

tsx

<Listbox
  items={items}
  selectionMode="multiple"
  defaultSelectedKeys={["profile", "settings"]}
  onSelectionChange={setKeys}
/>

纯动作列表

selectionMode="none" 不持有选中态，仅靠 onAction 触发命令。

tsx

<Listbox
  items={items}
  selectionMode="none"
  onAction={(key) => console.log(key)}
  aria-label="动作列表"
/>

插槽与描述

startContent 图标、description 次级文案、endContent 快捷键、disabled 停用。

tsx

const items = [
  { key: "profile", label: "个人资料", description: "查看与编辑账户", startContent: <User className="size-4" /> },
  { key: "shortcut", label: "快捷键", endContent: <kbd className="font-mono text-xs">⌘K</kbd> },
  { key: "disabled", label: "停用项", disabled: true },
];

<Listbox items={items} selectionMode="single" />

何时用

Props

名称	类型	默认	说明
items*	`ListboxItemData[]`	—	列表项；每项含 `key`/`label`，可带 `description`/`startContent`/`endContent`/`disabled`
selectionMode	`"none" \| "single" \| "multiple"`	`"single"`	none=纯动作列表（不持有选中态）；single/multiple=可选
selectedKeys	`string[]`	—	受控选中键
defaultSelectedKeys	`string[]`	—	非受控初始选中键
disabledKeys	`string[]`	—	额外禁用键（与 `item.disabled` 合并）
className	`string`	—	容器类名
aria-label	`string`	—	无可见标题时的无障碍标签

事件

类型

说明

onSelectionChange

(keys: string[]) => void

选中变化回调

onAction

(key: string) => void

任意项激活都触发（含 none 模式），用于命令式动作

Listbox

用法

单选

多选

纯动作列表

插槽与描述

何时用

导入

Props

Events

禁忌 / 坑

相关

Playground

Listbox

用法

单选

多选

纯动作列表

插槽与描述

何时用

导入

Props

Events

禁忌 / 坑

相关

Playground