# @cocreate/filter 中文文档

规范地址：https://npmcn.com/package/%40cocreate/filter/

版本：2\.0\.2
npm 元数据更新时间：2026-11-07T02:46:24.893Z
中文译文更新时间：2026-11-10T08:46:51.586Z
软件包许可：AGPL-3\.0

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

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

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

- 包体积（解压后）：218 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：5 个
- 首次发布：2021-03-26T01:42:08.634Z
- 最新版本发布：2026-11-07T02:46:24.684Z
- 近 30 天下载量：2040（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：296（近 12 个月 12 个）

## 中文简介

一个 JavaScript api 定义了过滤颜色,描述,文本,价格或任何存储于db的文档列表的属性. 用于创建自定义组件, 如抓取、 计分器、 数据表等 .

## 安装

```sh
npm install @cocreate/filter
```

也可以使用：`pnpm add @cocreate/filter`、`yarn add @cocreate/filter`、`bun add @cocreate/filter`

## README

# 创建过滤器

`@cocreate/filter` 将 HTML 属性变成可重复使用的数据过滤器。 它是Coreate应用程序中由列表,表格,搜索,页码,无限滚动,自定义数据传输组件使用的过滤层.

模块本身不获取或提供记录。 它从一个或多个元素中收集过滤状态,使该状态暴露于拥有结果集的元素或数据模块.

[文档和演示](https://cocreatejs.com/docs/filter) | [更改日志](https://github.com/CoCreateJS/filter/blob/master/CHANGELOG.md) | [问题](https://github.com/CoCreateJS/filter/issues)

![minified](https://img.badgesize.io/https://cdn.CoCreateJS.com/filter/latest/CoCreate-filter.min.js?style=flat-square&label=minified&color=orange) ![gzip](https://img.badgesize.io/https://cdn.CoCreateJS.com/filter/latest/CoCreate-filter.min.js?compression=gzip&style=flat-square&label=gzip&color=yellow) ![brotli](https://img.badgesize.io/https://cdn.CoCreateJS.com/filter/latest/CoCreate-filter.min.js?compression=brotli&style=flat-square&label=brotli) ![GitHub latest release](https://img.shields.io/github/v/release/CoCreateJS/filter?style=flat-square) ![License](https://img.shields.io/github/license/CoCreateJS/filter?style=flat-square)

![CoCreate-filter](https://cdn.cocreatejs.com/docs/CoCreate-filter.gif)

## 安装

### 光盘N

```html
<script src="https://cdn.CoCreateJS.com/filter/latest/CoCreate-filter.min.js"></script>
```

### 无

```bash
npm install @cocreate/filter
```

```javascript
import "@cocreate/filter";
```

### 线条

```bash
yarn add @cocreate/filter
```

## 如何运作

模块监视带有一个或多个元素的元素 `filter-*` 属性。 它读取其当前值,创建过滤对象,并通过其 `setFilter` 一体化.

有两个共同的安排:

1.  将过滤属性直接放入结果元素上.
2.  将输入、选择和按钮等控件放在结果元素内或相邻处,并与之连接 `filter-query`。 。 。 .

当一个控制器改变时,模块在发送更新后过滤器前等待一秒钟. 普通更新重排结果索引和组合 `overwrite`;加载更新保留了现有结果.

## 最小示例

```html
<input
    type="search"
    filter-query-key="name.$regex"
    placeholder="Search names"
>

<div
    id="users"
    filter-query
    database="app"
    collection="users"
    filter-limit="20"
></div>
```

输入提供了查询键并从输入值中获取其值. 结果元素是过滤目标. 拥有的数据或渲染模块 `#users` 消耗产生的过滤器.

## 过滤属性

| 属性 | 目的 | 示例 |
| --- | --- | --- |
| `filter-query` | 将元素标为过滤目标并解决相关控制. | `filter-query` |
| `filter-query-key` | 添加来自元素的查询字段. | `filter-query-key="user_id"` |
| `filter-query-value` | 从属性直接提供查询值. | `filter-query-value="active"` |
| `filter-query-options` | 为正则表达式查询添加选项字段. | `filter-query-options="i"` |
| `filter-key` | 设置消耗数据模块使用的密钥或索引值. | `filter-key="page"` |
| `filter-value` | 用品价值 `filter-key`。 。 。 . | `filter-value="2"` |
| `filter-search` | 启用使用元素当前值的文本搜索. | `filter-search` |
| `filter-operator` | 选择搜索操作员。 默认是 `or`。 。 。 . | `filter-operator="and"` |
| `filter-case-sensitive` | 用于搜索的大小写敏感度控制 . | `filter-case-sensitive="true"` |
| `filter-sort-key` | 选择要排序的字段. | `filter-sort-key="createdAt"` |
| `filter-sort-direction` | 选择排序方向. | `filter-sort-direction="desc"` |
| `filter-limit` | 每页设置记录。 默认是 `20`。 。 。 . | `filter-limit="50"` |
| `filter-index` | 设置起始结果索引. | `filter-index="0"` |
| `filter-on` | 添加加载多或计数触发 : `click`, (中文(简体) ), `scroll`,或 `fetched`。 。 。 . | `filter-on="scroll"` |

该模块目前使用连字符 `filter-*` 属性名称。 它们是与点指派语法分开的 `@cocreate/events`。 。 。 .

## 查询过滤

使用 `filter-query` 结果要素和 `filter-query-key` 控制系统 控制权 `getValue()` 结果成为查询值.

```html
<input
    filter-query-key="email.$regex"
    filter-query-options="i"
    type="search"
>
<section id="results" filter-query></section>
```

由此产生的查询概念如下:

```javascript
{
    email: {
        $regex: "value",
        $options: "i"
    }
}
```

被嵌入的密钥会通过CoCreate的点注释工具进行转换. 空数组值去掉相应的查询密钥 。 缺少密钥、 空值或被拒绝的值 `checkValue` 禁用贡献.

使用 `filter-query-value` 以加价方式提供的值:

```html
<button filter-query-key="status" filter-query-value="published">
    Published
</button>
```

明确管制 `filter-query-value` 未从输入事件更新。 值变化时更改属性或调用过滤器更新集成.

## 密钥和搜索过滤

`filter-key` 为过滤器提供值 `key` 对象。 数字值转换为数字;无效的数字值返回到 `1` 在目前执行过程中.

```html
<button filter-key="page" filter-value="2">Next page</button>
<div filter-query filter-limit="20"></div>
```

添加 `filter-search` 用于输入或具有共生成的其他元素 `getValue()` 方法 :

```html
<input
    filter-search
    filter-operator="or"
    filter-case-sensitive="false"
    placeholder="Search all fields"
>
<div filter-query></div>
```

过滤器包含有当前值、操作符和大小写敏感性设置的搜索条目。 消耗数据模块决定适用哪些字段和搜索执行.

## 排序

排序表示为 `{ key, direction }` 条目。 在一个 `INPUT`, (中文(简体) ), `TEXTAREA`,或 `SELECT` 的排序属性触发过滤器更新.

```html
<select filter-sort-key="createdAt" filter-sort-direction="desc">
    <option value="desc">Newest</option>
    <option value="asc">Oldest</option>
</select>
<div filter-query></div>
```

多类控件可以贡献出不同的字段. 如果两个控件使用相同的排序密钥,后置值将取代更早的方向.

## 再加载多加载

结果元素的 `filter-limit` 默认为 `20`。 。 。 . `filter-index` 默认为 `0`。 。 。 .

```html
<div id="results" filter-query filter-limit="25"></div>
<button filter-on="click">Load more</button>
```

`filter-on="scroll"` 用途 `IntersectionObserver` 当触发器完全可见时请求更多数据. `filter-on="fetched"` 将获取的计数写入触发器 `setValue` 之后 `fetchedData` 活动.

装入更多更新集 `loadMore` 并保存现有结果集。 普通查询、搜索、排序或密钥更改重置 `index` 设置 `overwrite` 所以旧纪录被替换了.

## 过滤对象形状

运行时间维护一个类似于以下的过滤对象:

```javascript
{
    query: { status: "published" },
    key: { page: 1 },
    search: [
        { value: "co", operator: "or", caseSensitive: false }
    ],
    sort: [
        { key: "createdAt", direction: "desc" }
    ],
    index: 0,
    limit: 20,
    overwrite: true
}
```

只有人口密集的部分。 准确解释 `query`, (中文(简体) ), `key`,以及 `search` 属于消耗过滤器的数据模块.

## Java 脚本 API

包导出一个默认对象, 包含以下成员:

```javascript
import CoCreateFilter from "@cocreate/filter";

await CoCreateFilter.init(document.querySelector("#results"));
const filter = await CoCreateFilter.getFilter(
    document.querySelector("#results")
);
```

### `init(element)`

初始化一个元素, a `HTMLCollection`页:1 `NodeList`,或一系列元素。 元素在匹配模块的过滤选择器时进行处理.

### `getFilter(element)`

构建并返回一个元素的有效过滤器,包括从相关控制中解析的贡献。 该模块还暴露了其内部 `elements` 财务报告和审定财务报表 `filters` 用于检查运行时状态的集成图.

### 数据助手

默认导出也会被曝光 `queryData`, (中文(简体) ), `searchData`,以及 `sortData` 从 `@cocreate/utils`。这些帮助器可供定制的消费者使用,将相同的语义应用到一个内语数组中.

## 生命周期和时间

-   匹配元素在启动和添加到文档时初始化.
-   支助 `filter-*` 属性变化触发过滤器更新.
-   输入更改为 `1000ms`。 。 。 .
-   `filter-on="scroll"` 用途 `IntersectionObserver` 阈值为 `1`。 。 。 .
-   删除的节点从模块的元素注册被删除 .

因为过滤器是同步组装的,在CoCreate装入后初始化所依赖的数据/发送模块,或者使用它们的生命周期钩,而不是假设在HTML解析时可以同步使用过滤器.

## 目前的限制和执行说明

-   过滤器更新延迟一秒钟 。 这影响到方案更新和文本输入.
-   空值在多条路径中被视为无效贡献 。 使用删除过滤器属性或一个空数组, 其中消耗性集成需要清除查询 .
-   `filter-on="fetched"` 取决于 `fetchedData` 事件和a `setValue` 由周围数据部分提供的方法.
-   来源重复 `value === "true"` 键转换中的分支。 计划转换 `"false"` 改为 `0` 未执行;无效的数字值返回到 `1`。 。 。 .
-   此包协调过滤状态 。 它没有定义数据库权限,传输,记录渲染,或页码UI.

## 解决问题

### 过滤器永远不会改变

检查控件是否支持 `filter-*` 属性,解决 a `filter-query` 结果元素,并曝光 `getValue()` 当没有明确 `filter-query-value` 提供。 记住,更新延迟了1秒钟.

### 查询缺少一个字段

检查 `filter-query-key` 和返回的值 `getValue()`空值和被 `checkValue` 被跳过。 对于巢地,使用点名,例如: `profile.name` 或者说 `profile.name.$regex`。 。 。 .

### 装入更多替换列表

确定更新来自一个元素 `filter-on="click"` 或者说 `filter-on="scroll"`。一个普通输入、查询、排序或密钥故意更新集 `overwrite` 并重置索引.

### 排序无效

排序控件只附加他们的自动更改收听器 `INPUT`, (中文(简体) ), `TEXTAREA`,以及 `SELECT` 要素。 确认两者 `filter-sort-key` 财务报告和审定财务报表 `filter-sort-direction` 是现相而非空相.

## 捐款

请读一下 [贡献指南](https://github.com/CoCreateJS/filter/blob/master/CONTRIBUTING.md)打开 [问题](https://github.com/CoCreateJS/filter/issues),或者提交拉动请求。 属性名称的改变,过滤形状,解跳行为,和生命周期事件都是相容性的,应该包括文档和实例.

## 许可证

该软件在GNU Affero通用公共许可证版本3(AGPLv3)和商业许可证下获得双许可证.

-   **开源使用 :** 对于开源项目和非商业用途,该软件可在AGPLv3下提供. 见 [自由文件](https://github.com/CoCreateJS/filter/blob/master/LICENSE)。 。 。 .
-   **商业用途:** 营利性用途需要从 [创造](https://cocreatejs.com/)。 。 。 .

## 常见问题

### @cocreate/filter 是什么？

一个 JavaScript api 定义了过滤颜色,描述,文本,价格或任何存储于db的文档列表的属性\. 用于创建自定义组件, 如抓取、 计分器、 数据表等 \.

### 如何安装 @cocreate/filter？

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

### @cocreate/filter 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cocreate\_\_filter 是否存在。

### @cocreate/filter 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cocreate/filter 可以商用吗？

@cocreate/filter 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @cocreate/filter 的下载量有多少？

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

### @cocreate/filter 还在维护吗？

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