# @asphalt-react/selection 中文文档

规范地址：https://npmcn.com/package/%40asphalt-react/selection/

版本：2\.19\.0
npm 元数据更新时间：2026-10-29T07:10:44.622Z
中文译文更新时间：2026-11-08T10:09:10.908Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40asphalt-react/selection
原文对照：https://npmcn.com/package/%40asphalt-react/selection/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：117 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：react \>= 16\.8\.2
- 首次发布：2024-06-21T12:52:14.225Z
- 最新版本发布：2026-10-29T07:10:44.414Z
- 近 30 天下载量：1805（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 14 个）

## 中文简介

选择组件是一组组件,允许用户从项目列表中选择选项.

## 安装

```sh
npm install @asphalt-react/selection
```

也可以使用：`pnpm add @asphalt-react/selection`、`yarn add @asphalt-react/selection`、`bun add @asphalt-react/selection`

## README

# 选择

![npm](https://img.shields.io/npm/dt/@asphalt-react/selection?style=flat-square) [![npm version](https://badge.fury.io/js/@asphalt-react%2Fselection.svg)](https://badge.fury.io/js/@asphalt-react%2Fselection)

选择是一个由可获取的本地选择选项组成的家庭,这使得从列表中选择一个或多个选项变得容易. 选择导出**下坠**" 构成部分.

## 使用量

Dropdown 接受一系列选项,其中每个选项是包含至少2个属性的对象, `id` 打开 `key`。 。 。 .

```jsx
import { Dropdown } from "@asphalt-react/selection"

function App() {
  let items = [
    { id: "1", key: "Apple" },
    { id: "2", key: "Banana" },
  ]

  return <Dropdown items={items} />
}
```

# 下坠

Dropdown 显示一个 popover 中的选项列表, 供用户选择 。 您可以在列表中过滤选项并设置初始选择的选项,同时选择所有选项. Dropdown 支持自定义选定选项的顺序,将其重置到初始状态并设定在初始渲染时打开.

降水主要由3个部分组成.

-   选择框 - 持有所选值
-   ListBox - 持有选项
-   列表项目 - 选项本身

## 项目

这个 `id` 属性是 Dropdown 如何识别项目( K) 。 自然,它应该是独一无二的。 这个 `key` 属性的值将显示为列表项,因此用户可以轻松识别他们想要选择的选项.

## 多选择和过滤选项

应用 `multiSelect` 当您想要您的用户选择多个选项时, prop . 为在选项中进行过滤,请使用 `typeahead` 道具 (英语).

## 已控制

应用 `controlled` 管理应用程序中项目状态的道具。 当你启用时 `controlled` 道具,确保:

-   包含 `selected` 键 `items` 道具来.
-   使用 `onControlledChange` 改为 `onChange` 以获取关于当前所选项目和动作类型(选择或取消选择)的信息.
-   更新 `items` 使用返回的值从 `onControlledChange` 活动.
-   请注意: `initialSelected` 内 `items` 道具不会生效.

## 组

应用 `group` 可启用分组显示和管理分组基项结构的道具 。 当你启用时 `group` 道具,确保:

-   表格中的每个项目 `items` 道具必须包含 `subitems` 包含子选项的阵列.

```jsx
import { Dropdown } from "@asphalt-react/selection"

function App() {
  let items = [
  {
      id: "fruits_1",
      key: "Fruits",
      selectable: false,
      subitems: [
        { id: "1", key: "Apple" },
        { id: "2", key: "Banana" },
      ],
    },
    {
      id: "vegetables_1",
      key: "Vegetables",
      selectable: false,
      subitems: [
        { id: "1", key: "Carrot" },
        { id: "2", key: "Broccoli" },
      ],
    },
    {
      id: "grain_1",
      key: "Grain",
      selectable: false,
      subitems: [
        { id: "1", key: "Bread" },
        { id: "2", key: "Flavor" },
      ],
    },
  ]

  return <Dropdown group items={items} />
}
```

## 增强选项

为增强选项的字幕,您可以添加自定义元素,如"Avatar",同时添加字幕. 例如,显示一个用户列表的外观/首字母. 使用 `getAddonStart` 财务报告和审定财务报表 `getAddonEnd` 以启动行为。 您可以使用 `inactive`。当将其应用到一个组时,它也会禁用其所有子项.

## i18n (英语)

国际化是设计和准备您的应用软件可以使用不同语言的过程. 选择框文本支持 l10n , 可以使用 `translate`。它只对 `multiselect` 启用了 Dropdown .

## 键盘交互

Dropdown组件完全对键盘友好. 它被设计成这样,用户如果愿意,就不需要将手移到鼠标上.

-   使用 标签 专注 Dropdown.
-   使用任意 ↓ , (中文(简体) ), ↑ , (中文(简体) ), 输入 打开列表框.
-   使用 ↓ 以导航列表.
-   使用 ↑ 导航列表.
-   使用 换行+qq 以导航5次列表.
-   使用 换行+qq 导航5倍于名单.
-   使用 输入 从列表中选择一个选项.
-   使用 英格兰 关闭列表.

## 数据属性

滴滴允许通过 [`data-*` 属性](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) 到 Drop down 的顶级元素. `data-*` 被 Dropdown 用于识别每个实例并测试其行为。 Dropdown的内部元素有一个 `data-testid` 用于测试目的的属性.

## 道具

### 项目

滴出物体组.

示例

```js
const items = [{ id: "1", key: "Jakarta", ... }];
```

如果想要将项目作为一个组处理,请为每个组项目提供分项目. 示例

```js
{
  id: "add-unique-string-id",
  key: "DisplayValue",
  initialSelected: false,
  selectionOrder: 0,
  selectable: true,
  selected: true,
  inactive: true,
  subitems: [
    {
      id: "add-unique-child-string-id",
      key: "Child display value",
      initialSelected: false,
      inactive: true,
      selectionOrder: 0
    }
  ]
}
```

仅以上 `id` 需要时间。 通常至少提供 `id` 财务报告和审定财务报表 `key`。 。 。 . 使用 `selected` 仅在控制模式下对外部选择进行管理. 使用 `selectable` 指定组件是否允许选择组标签。 只在多选择和组合中使用. 使用 `inactive` 以禁用项目。 设定在组级别时, 它也会禁用其所有子项 .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 数组 | 真实 | 不详 |

### 变化

回调处理项目选择事件 。 Ivokes on user 交互或 Dropdown 重置. 其签名如下:

-   项目 - 用户交互选择的项目
-   选项 - 有以下属性的选项桶
    -   参考: Dropdown 的回放
    -   选中的项目: 万一 `multiselect` 启用下拉
    -   全部选中: 如果选中所有项目, 则显示布尔值

```js
 (item, { ref, selectedItems }) => {}
```

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 控制

滴滴让你控制了内部状态 使用此道具来管理项目的选择 .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 不详 |

### 关于控制下的变化

回调处理项目选择/取消选择 `controlled` 放下来 启动用户交互或标签删除. 其签名如下:

```js
(item, { ref, selection, changedItems }) => {}
```

-   项 - 用户互动的项目。 如果用户选择“全部选择”选项,则 `item` 无效.
-   选项 - 具有以下属性的选项桶:
    -   参考: Dropdown 的回放
    -   选择: 表示项目选择/取消选择的布尔值( 真/假)
    -   更改项目:仅在用户选择时显示 `select all`。该修改状态的所有项目。 使用 `selection` 键来确定是否 `changedItems` 被选中或取消.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 多选择

启用多个项选择

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 类型头

允许根据打出的关键字过滤匹配的项目. 这个 [匹配算法](https://github.com/kentcdodds/match-sorter) 使用过的 给予最终用户尽可能最好的用户体验.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 输入

回调处理用户输入 `typeahead` 启用了 Dropdown 。 它接收回声合成事件作为论据.

```js
(event) => {}
```

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 布莱尔

回调处理模糊事件 `typeahead` 启用了 Dropdown 。 它接收回声合成事件作为论据.

```js
(event) => {}
```

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 大小

使组件具有所提供的大小。 接受"s","m","l"表示中小和大.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 语句 | 虚假 | "m" (英语) |

### 缩放

扩展组件宽度以匹配其容器.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 默认突出显示 指数

这是在 Droppdown 初始化或重置时突出显示的项目的索引值

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 编号 | 虚假 | 0 个 |

### 首选项

初始化时下拉

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 已禁用

禁用下坠.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 占位符

提示未选中项目时显示的文本 .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 字符串 | 虚假 | "选择" |

### 无效

对 Dropdown 应用无效的样式.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 不详 |

### 显示键

Dropdown 使用此道具来渲染列表项的标题而不是“ 关键” 属性 .

```jsx
const item = [
{
 id: 1,
 label: "Bali",
},
{
 id: 2,
 label: "Jakarta"
}]

function App () {
 return <Dropdown items={items} displayKey="label" />
}
```

在分组模式中,确保分组 `key` 匹配其分项目 `key`。 。 。 .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 字符串 | 虚假 | "钥匙" |

### 翻转

如果没有空间来制造弹出器,则会按照取景口边界进行俯冲.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 真实 |

### 过滤器

下放显示在 a 中过滤的项目 `typeahead` 默认启用了 Drop down 。 设置此道具的值 改为 `false` 来显示所有项目.

相匹配的项目列在清单的首位,然后是其余项目.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 真实 |

### 翻译

在选中框中显示自定义文本的函数 `multiSelect` 启用了 Dropdown .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 编号

DOM DOM DOD DOD (英语:DOM id of the Dropdown)). DOM ID of the DOD DOD (英语).

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 字符串 | 虚假 | 不详 |

### 标签编号

Dropdown使用的标签的编号 。 用于aria属性.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 字符串 | 虚假 | 不详 |

### 空文本

未找到结果时显示自定义文本 .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 字符串 | 虚假 | "没有结果" |

### 标记

将选中的项目显示为上方的标签 `multiselect` 放下枪.

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 真实 |

### 获取AddonStart

3⁄4 ̄ ̧漯B 它接收的项目作为 参数以唯一地识别列表项目.

```jsx
const itemAvatar = (item) => {
 const caption = item.key.substring(0,2)

 return <Avatar uppercase>{caption}</Avatar>
}

function App () {
 return <Dropdown getAddonStart={itemAvatar} />
}
```

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 获取后端

3⁄4 ̄ ̧漯B 它接收的项目作为 参数以唯一地识别列表项目.

```jsx
const itemAvatar = (item) => {
 const caption = item.key.substring(0,2)

 return <Avatar uppercase>{caption}</Avatar>
}

function App () {
 return <Dropdown getAddonEnd={itemAvatar} />
}
```

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 乐趣c | 虚假 | 不详 |

### 全部选择

在列表中渲染一个特殊项目,允许用户在 Dropdown 中选择或取消所有选项. 它接受布尔值或节点.

可接受值 :

-   `true`:允许选择所有特性,并使用“选择全部”作为项目的标题.
-   `false`: 跳过选中的全部功能.
-   节点:允许选择所有特性,并使用元素作为项目的标题.

```jsx
import {Text} from "@asphalt-react/typography"

<Dropdown selectAll={<Text>Pilih Semua</Text>} />
```

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 工会 | 虚假 | 虚假 |

### 组

启用分组项目选择 .

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

# 列表项目

## 道具

### 儿童

列出项目包的节点

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 节点 | 真实 | 不详 |

### 已禁用

项目的已禁用状态

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 突出显示

突出项目状态

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 选中

选定项目状态

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 大小

项目大小。 接受一个"s","m"和"l"

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 语句 | 虚假 | "m" (英语) |

### 缩进

项目缩进状态

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

# 列表项目关联

## 道具

### 儿童

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 节点 | 虚假 | 不详 |

### 折叠文字

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 真实 |

### 大小

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 语句 | 虚假 | "m" (英语) |

### 检查

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 已禁用

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 添加开始

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 节点 | 虚假 | 不详 |

### 添加结束

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 节点 | 虚假 | 不详 |

### 复选框

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 不确定

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 缩进

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 不详 |

### 强调

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

### 可选择

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 不详 |

### 匹配

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 字符串 | 虚假 | "" "" (英语) |

### 不活动

| 类型 | 所需经费 | 默认 |
| --- | --- | --- |
| 嘘 | 虚假 | 虚假 |

## 常见问题

### @asphalt-react/selection 是什么？

选择组件是一组组件,允许用户从项目列表中选择选项\.

### 如何安装 @asphalt-react/selection？

在项目目录运行 npm install @asphalt-react/selection，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>= 16\.8\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @asphalt-react/selection 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @asphalt-react/selection 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @asphalt-react/selection 可以商用吗？

@asphalt-react/selection 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @asphalt-react/selection 的下载量有多少？

根据 npm 官方下载统计，@asphalt-react/selection 在 2026/10/07 – 2026/11/05 这 30 天内被下载 1,805 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @asphalt-react/selection 还在维护吗？

最新版本 2\.19\.0 发布于 2026/10/29（10 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 14 个；首次发布于 2024/06/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。