# @emmgeede/gridselect 中文文档

规范地址：https://npmcn.com/package/%40emmgeede/gridselect/

版本：1\.2\.0
npm 元数据更新时间：2026-11-08T11:18:33.495Z
中文译文更新时间：2026-11-13T15:52:54.859Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40emmgeede/gridselect
原文对照：https://npmcn.com/package/%40emmgeede/gridselect/?lang=original
项目主页：https://gridselect.im/
源码仓库：https://github.com/emmgeede/gridselect

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

- 包体积（解压后）：230 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue \>=3\.3，react \>=18
- 首次发布：2026-11-01T12:48:05.421Z
- 最新版本发布：2026-11-08T11:18:33.171Z
- 近 30 天下载量：3789（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

无依赖选择组件:短列表可见项目,长列表可搜索网格.

## 安装

```sh
npm install @emmgeede/gridselect
```

也可以使用：`pnpm add @emmgeede/gridselect`、`yarn add @emmgeede/gridselect`、`bun add @emmgeede/gridselect`

## README

[![GridSelect logo: four rounded squares in shades of sky blue](https://raw.githubusercontent.com/emmgeede/gridselect/main/assets/logo.svg?v=3)](https://gridselect.im/demo/)

# 选择网格

[![npm version](https://img.shields.io/npm/v/@emmgeede/gridselect)](https://www.npmjs.com/package/@emmgeede/gridselect) [![CI](https://github.com/emmgeede/gridselect/actions/workflows/ci.yml/badge.svg)](https://github.com/emmgeede/gridselect/actions/workflows/ci.yml) [![Accessibility](https://github.com/emmgeede/gridselect/actions/workflows/accessibility.yml/badge.svg)](https://github.com/emmgeede/gridselect/actions/workflows/accessibility.yml) [![Bundle size](https://img.shields.io/bundlejs/size/@emmgeede/gridselect)](https://bundlejs.com/?q=@emmgeede/gridselect) [![License: MIT](https://img.shields.io/github/license/emmgeede/gridselect)](https://npmcn.com/package/%40emmgeede/gridselect/LICENSE)

从选择列表中选择的无依赖 JavaScript 组件 . 您写一个普通的无线电组、 复选框组或 `<select>`把它包起来 其余部分由网格选择。 短列表作为项目保持可见. 更长的清单 切换到打开带有搜索输入和一个的面板的紧凑字段 多柱网格,完全键盘可访问. 打入过滤项目,或 突出显示匹配的位置,数字直接选择一个条目.

您的标记保持原生, 所以表格提交, 重置和验证像往常一样 没有JavaScript,一切仍然有效.

**[尝试演示](https://gridselect.im/demo/)**

[![A currency field with its panel open. The search input contains 'dollar' and six matching currencies are shown as numbered items in a three-column grid, the first one outlined as the cursor.](https://raw.githubusercontent.com/emmgeede/gridselect/main/assets/filter-light.png?v=5)](https://gridselect.im/demo/)

**长列表, 过滤模式( 默认) .** 球场开设了一个有40个货币的面板. 键入 "美元"隐藏了其他一切,并重新编号了6个匹配的1比6. 概述的项目是 光标:输入、点击或数字选择.

[![A short list of four shipping options shown as rounded items with digit badges 1 to 4, the first one selected.](https://raw.githubusercontent.com/emmgeede/gridselect/main/assets/short-light.png?v=5)](https://gridselect.im/demo/)

**短名单.** 最多10个条目作为项目保持可见。 他们是本地的无线电按钮 下面;箭头键在它们之间移动,而数字 1 至 4 直接选择一个.

[![Highlight mode: all currencies stay in place, the two krone entries are shown in blue, the others dimmed, the cursor is on Norwegian krone, digit badges switch to S1, S2 for the second tier.](https://raw.githubusercontent.com/emmgeede/gridselect/main/assets/highlight-light.png?v=5)](https://gridselect.im/demo/)

**长列表, 突出显示模式** (单位:千美元)`data-search="highlight"`) (中文(简体) ). 搜索的同一列表 "克龙". 没有什么是故意隐藏的:每个条目都有它的位置,所以使用列表的人 每天可以依靠位置。 火柴(丹麦克龙和挪威克龙)以蓝色标出 光标跳转到第一个匹配时,所有其他条目都会被暗化. 条目11至20被选中 相向并有位数(S1至S0).

**状态 :** 1.2.0版本,稳定。 npm上公布为 `@emmgeede/gridselect`,因为 npm 处理平话名 `gridselect` 也一样 类似旧的软件包。 版本数 跟着 [语义版本](https://semver.org/)。见 [特征](https://npmcn.com/package/%40emmgeede/gridselect/#readme-features) 对于今天的工作 [变动情况](https://npmcn.com/package/%40emmgeede/gridselect/CHANGELOG.md) 改变什么.

## 目录

-   [安装](https://npmcn.com/package/%40emmgeede/gridselect/#readme-installation)
-   [使用量](https://npmcn.com/package/%40emmgeede/gridselect/#readme-usage)
    -   [对变化的反应](https://npmcn.com/package/%40emmgeede/gridselect/#readme-reacting-to-changes)
    -   [一次几个](https://npmcn.com/package/%40emmgeede/gridselect/#readme-several-at-once)
-   [文档](https://npmcn.com/package/%40emmgeede/gridselect/#readme-documentation)
-   [特征](https://npmcn.com/package/%40emmgeede/gridselect/#readme-features)
-   [浏览器支持](https://npmcn.com/package/%40emmgeede/gridselect/#readme-browser-support)
-   [发展](https://npmcn.com/package/%40emmgeede/gridselect/#readme-development)
-   [许可证](https://npmcn.com/package/%40emmgeede/gridselect/#readme-license)

## 安装

```sh
npm install @emmgeede/gridselect
```

```js
import { gridselect } from "@emmgeede/gridselect";
import "@emmgeede/gridselect/gridselect.css"; // optional
```

没有捆绑机,从CDN(`window.gridselect`:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@emmgeede/gridselect@1/src/gridselect.css">
<script src="https://cdn.jsdelivr.net/npm/@emmgeede/gridselect@1/dist/gridselect.min.js"></script>
<script>
  document.querySelectorAll("[data-gridselect]").forEach((el) => gridselect(el));
</script>
```

只偏爱HTML吗? 使用自定义元素,参见 [`<grid-select>`](https://gridselect.im/docs/guide/frameworks.html)数字 :

```html
<script src="https://cdn.jsdelivr.net/npm/@emmgeede/gridselect@1/dist/gridselect-element.min.js"></script>
```

## 使用量

```html
<fieldset data-gridselect>
  <legend>Currency</legend>
  <label><input type="radio" name="cur" value="EUR" checked> Euro</label>
  <label><input type="radio" name="cur" value="CHF"> Swiss franc</label>
</fieldset>
```

```js
import { gridselect } from "@emmgeede/gridselect";

const gs = gridselect(document.querySelector("[data-gridselect]"));
gs.value; // "EUR"
gs.value = "CHF"; // checks the CHF radio, fires no event
```

### 对变化的反应

GridSelect 保留您的输入作为真理的来源 。 每当用户选择 某物,点击输入,使用键盘或选择其中的项目 面板, 网格选择集 `checked` 在本地输入和浏览器上 拥有 `input` 财务报告和审定财务报表 `change` 事件点燃了它。 两个泡泡,一个听 包装包覆盖整个组:

```js
const wrapper = document.querySelector("[data-gridselect]");
const gs = gridselect(wrapper);

wrapper.addEventListener("change", (event) => {
  console.log(event.target.value); // the input that changed, e.g. "CHF"
  // the whole selection: "CHF", or ["a", "c"] for checkboxes
  console.log(gs.value);
});
```

没有要学习的自定义事件: 听的代码 `change` 或者说 `input` 与 `addEventListener` 保持工作不变。 反应是例外 在面板内取出,因为反应 `onChange` 在收音机上收听 点击,不显示为 `change`。在“反应”中,在包装上附加一个本地听众 (通过参考)直到计划的框架包装存在. 设置 `gs.value` 从 代码点火没有事件, 就像设置 `checked` 自己,还有一种形式 提交总是发送当前选择.

### 一次几个

```js
document.querySelectorAll("[data-gridselect]").forEach((el) => gridselect(el));
```

使用 `forEach((el) => gridselect(el))`没有 `forEach(gridselect)`: 第二个 窗体通过索引作为第二个参数,该参数将作为选项在 后来的版本.

A 类 `<fieldset>` 带有 `<legend>` 是推荐的包装, 它会显示屏幕 阅读组名。 任何元素都会起作用, `data-gridselect` 仅是一个 用于选择包装和样式表的常规.

## 文档

所有文件,每页都有一个现场实例,在 **[网格选择.im/docs](https://gridselect.im/docs/)**。 。 。 .

-   **指南 :** [来源](https://gridselect.im/docs/guide/sources.html) (无线电、复选箱、, `<select>`, (中文(简体) ), `items`, (中文(简体) ), [服务器上的条目](https://gridselect.im/docs/guide/server.html), (中文(简体) ), [面板](https://gridselect.im/docs/guide/panel.html), (中文(简体) ), [搜索](https://gridselect.im/docs/guide/search.html), (中文(简体) ), [键盘和数字](https://gridselect.im/docs/guide/keyboard.html), (中文(简体) ), [组](https://gridselect.im/docs/guide/groups.html), (中文(简体) ), [被绑住和最近输入](https://gridselect.im/docs/guide/pinned.html), (中文(简体) ), [说明](https://gridselect.im/docs/guide/descriptions.html), (中文(简体) ), [多重选择](https://gridselect.im/docs/guide/multiple.html), (中文(简体) ), [表单](https://gridselect.im/docs/guide/forms.html), (中文(简体) ), [样式和主题](https://gridselect.im/docs/guide/styling.html), (中文(简体) ), [无障碍](https://gridselect.im/docs/guide/accessibility.html), (中文(简体) ), [`<grid-select>`,反应, Vue 等](https://gridselect.im/docs/guide/frameworks.html)。 。 。 .
-   **参考:** [选项](https://gridselect.im/docs/reference/), (中文(简体) ), [属性和钩](https://gridselect.im/docs/reference/attributes.html), (中文(简体) ), [实例和事件](https://gridselect.im/docs/reference/instance.html), (中文(简体) ), [CSS 变量](https://gridselect.im/docs/reference/css.html)。 。 。 .

## 特征

| 特性 | 状态 |
| --- | --- |
| 电台和复选箱组, `value`, (中文(简体) ), `destroy()`类型 | 可用 |
| 网格面板高于可配置阈值( 默认 10), 网格或列表布局 | 可用 |
| 搜索模式 `filter` (违约)和 `highlight` | 可用 |
| 带有可配置的修改分级的数字快捷键 | 可用 |
| `<select>` 作为源 | 可用 |
| 带有 CSS 变量、 光和暗的可选样式表 | 可用 |
| npm 发布并演示页面 | 可用 |
| 网格面板的多重选择, `<select multiple>` | 可用 |
| JS阵列的条目, `setItems()` | 可用 |
| `<grid-select>` 自定义元素 | 可用 |
| 模糊匹配 | 可用 |
| 自动列宽和流量布局 | 可用 |
| 分组标题`<optgroup>`组合 `items`(中文(简体) ) | 可用 |
| 固定和最近条目 | 可用 |
| 多重选择的上限( E)`max`(中文(简体) ) | 可用 |
| 说明(每个条目第二行) | 可用 |
| 在有空间的地方打开面板, 直至窗口边缘 | 可用 |
| 全窗口宽度的面板 | 可用 |
| `<grid-select>` 作为一种形式控制(有效性,重置, `FormData`(中文(简体) ) | 可用 |
| 服务器的条目( E)`load`(中文(简体) ) | 可用 |
| 主题:展示、高对比、紧凑、开放供稿 | 可用 |
| 反应和 Vue 包装 | 可用 |

## 浏览器支持

当前常绿浏览器(Chrome, Edge, Firefox, Safari).

## 发展

```sh
npm install
npm test             # unit tests (Vitest + jsdom), type check, package contents
npm run test:e2e     # browser tests (Playwright, Chromium) incl. axe-core checks
npm run build        # dist/gridselect.d.ts and dist/gridselect.min.js
npm run screenshots  # README images and animations in assets/, from the demo page (needs ImageMagick)
npm run playground   # http://localhost:5173/playground/ (tests) and /demo/
node scripts/pr-check.js  # the contribution rules CI checks on pull requests
```

贡献: 已读 [一般事务人员(其他职等)](https://npmcn.com/package/%40emmgeede/gridselect/AGENTS.md) (对人和AI特工的规则, 带有 `contributing` claude Code)和关于主题, [捐款额](https://npmcn.com/package/%40emmgeede/gridselect/CONTRIBUTING.md)。 。 。 .

发布: 推动版本标签( E)`vX.Y.Z`匹配 `package.json`运行 发布工作流程,该工作流程将测试,构建并发布到 npm 并带有出处.

游乐场载荷 `src/gridselect.js` 直接显示每个变体 : 短而长的收音机组,复选框,两种搜索模式,列表布局, 带有 `required`, (中文(简体) ), `disabled`中,提交并重置,并重置 `change` 事件。 它的造型是临时的,直到样式表船.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40emmgeede/gridselect/LICENSE)

## 常见问题

### @emmgeede/gridselect 是什么？

无依赖选择组件:短列表可见项目,长列表可搜索网格\.

### 如何安装 @emmgeede/gridselect？

在项目目录运行 npm install @emmgeede/gridselect，或使用 pnpm add / yarn add / bun add。

### @emmgeede/gridselect 支持 TypeScript 吗？

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

### @emmgeede/gridselect 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @emmgeede/gridselect 可以商用吗？

@emmgeede/gridselect 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @emmgeede/gridselect 的下载量有多少？

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

### @emmgeede/gridselect 还在维护吗？

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