# @github/filter-input-element 中文文档

规范地址：https://npmcn.com/package/%40github/filter-input-element/

版本：0\.1\.1
npm 元数据更新时间：2026-10-15T16:20:44.695Z
中文译文更新时间：2026-11-16T12:42:28.346Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40github/filter-input-element
原文对照：https://npmcn.com/package/%40github/filter-input-element/?lang=original
项目主页：https://github.com/github/filter-input-element#readme
源码仓库：https://github.com/github/filter-input-element

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

- 包体积（解压后）：18.6 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2019-11-27T21:13:15.248Z
- 最新版本发布：2019-12-10T20:41:18.137Z
- 近 30 天下载量：2489（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

在匹配过滤器输入文本的子树上显示元素 .

## 安装

```sh
npm install @github/filter-input-element
```

也可以使用：`pnpm add @github/filter-input-element`、`yarn add @github/filter-input-element`、`bun add @github/filter-input-element`

## README

# < filter- input > 元素 ![](https://github.com/github/filter-input-element/workflows/Node%20CI/badge.svg)

在匹配过滤器输入文本的子树上显示元素 .

## 安装

```
$ npm install @github/filter-input-element
```

## 使用量

```html
<filter-input aria-owns="robots">
  <label>
    Filter robots
    <input type="text" autofocus autocomplete="off">
  </label>
</filter-input>
<div id="robots">
  <ul data-filter-list>
    <li>Bender</li>
    <li>Hubot</li>
    <li>Wall-E</li>
    <li>BB-8</li>
    <li>R2-D2</li>
  </ul>
  <p data-filter-empty-state hidden>0 robots found.</p>
</div>
```

## 要素和属性

### 需求

-   `filter-input[aria-owns]` 应该指向包罗全部的容器ID `<filter-input>` 相关要素.
-   `filter-input` 应该有一个 `input` 用于过滤的儿童元素.
-   `[id]` 应设置在包含或有下列内容的容器上: `[data-filter-list]` 属性.
-   `[data-filter-list]` 应设定为: **直接儿童因素** 将被过滤.

### 可选

#### 指定过滤文本

使用 `[data-filter-item-text]` 以指定一个其文本应用于过滤的元素。 在以下例子中,案文 `(current)` 将不匹配.

```html
<div data-filter-list>
  <a href="/bender">Bender</a>
  <a href="/hubot">
    <span data-filter-item-text>Hubot</span>
    (current)
  </a>
</div>
```

#### 空盘

使用 `[data-filter-empty-state]` 以指定未找到结果时要显示的元素。 此元素必须在容器内 `aria-owns` 指点.

```html
<div id="filter-list">
  <div data-filter-list>
    <a href="/bender">Bender</a>
    <a href="/hubot">Hubot</a>
  </div>
  <div data-filter-empty-state hidden>No results found.</div>
</div>
```

#### 创建新项目

使用 `[data-filter-new-item]` 以包含一个项目,在找不到精确匹配时创建新实例。 元素为 `[data-filter-new-text]`文本内容将设定为输入值。 您还可以使用 `[data-filter-new-value]` 为查询参数设置输入值.

```html
<div id="filter-list">
  <div data-filter-list>
    <a href="/bender">Bender</a>
    <a href="/hubot">Hubot</a>
  </div>
  <form action="/new" data-filter-new-item hidden>
    <button name="robot" data-filter-new-item-value>
      Create robot "<span data-filter-new-item-text></span>"
    </button>
  </form>
</div>
```

## 方法

`filterInputElement.filter` 可选择设置以提供替代过滤逻辑。 默认为下弦 .

```js
const fuzzyFilterInput = document.querySelector('.js-fuzzy-filter-input')
fuzzyFilterInput.filter = (element, elementText, query) => {
  // fuzzy filtering logic
  return {match: boolean, hideNew: boolean}
}
```

`match`(所需)表示是否应当显示该项目. `hideNew` (可选)将确定是否应当隐藏“创建新项目”元素。 例如,当找到精确匹配时,"创建新项目"选项应该被隐藏.

## 活动

-   `filter-input-start` (泡泡) - 开火 `<filter-input>` 当过滤动作即将启动时.
-   `filter-input-updated` (泡泡) - 开火 `<filter-input>` 当过滤器完成时. `event.detail.count` 找到匹配次数,以及 `event.detail.total` 是元素的总数.

为确保客户端更新以辅助技术传播, `filter-input-updated` 事件可以用来更新过滤结果来筛选阅读器。 例如:

```js
const ariaLiveContainer = document.querySelector('[aria-live="assertive"]')
document.addEventListener('filter-input-updated', event => {
  ariaLiveContainer.textContent = `${event.detail.count} results found.`
})
```

有关此技术的详情,请查看 [改善GOV.UK搜索的无障碍环境](https://technology.blog.gov.uk/2014/08/14/improving-accessibility-on-gov-uk-search/)。 。 。 .

## 浏览器支持

浏览器, 不本地 [自定义元素支持](https://caniuse.com/#feat=custom-elementsv1) 需要一个 [多边填充](https://github.com/webcomponents/custom-elements)。 。 。 .

-   颜色
-   火花
-   萨法里
-   微软边缘

## 发展

```
npm install
npm test
```

## 许可证

以麻省理工学院许可证分发。 详情见LICENSE.

## 常见问题

### @github/filter-input-element 是什么？

在匹配过滤器输入文本的子树上显示元素 \.

### 如何安装 @github/filter-input-element？

在项目目录运行 npm install @github/filter-input-element，或使用 pnpm add / yarn add / bun add。

### @github/filter-input-element 支持 TypeScript 吗？

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

### @github/filter-input-element 支持 ESM 还是 CommonJS？

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

### @github/filter-input-element 可以商用吗？

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

### @github/filter-input-element 的下载量有多少？

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

### @github/filter-input-element 还在维护吗？

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

