# @cocreate/elements 中文文档

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

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

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

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

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

- 包体积（解压后）：349 kB，43 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：8 个
- 首次发布：2021-10-18T21:46:42.760Z
- 最新版本发布：2026-11-07T02:43:57.915Z
- 近 30 天下载量：1958（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：269（近 12 个月 15 个）

## 中文简介

通过使用html5属性来查询存储在CoCreate无头 CMS中的数据,将内容获取到任意html元素中. 如果数据被更改, 它会立即在 html 标签中反映出来, 因为更改会实时播放

## 安装

```sh
npm install @cocreate/elements
```

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

## README

# @ cocreate/ 要素

使用 HTML5 属性将 HTML 元素直接绑入您的数据。 元素声明 _价值存在的地方_ ——一个存储,数据库,阵列,文档,和密钥——模块处理其余内容:读取内值,回写更改,并与其他客户端和服务器广播更新时保持实时同步. 没有查询代码,没有取取层,也没有取景模式. 标记为数据绑定.

* * *

## 文档

完整的指南和工作演示请参见 [文档](https://cocreatejs.com/docs/elements)。 。 。 .

## 目录

-   [特征](https://npmcn.com/package/%40cocreate/elements/#readme-features)
-   [安装](https://npmcn.com/package/%40cocreate/elements/#readme-installation)
-   [使用量](https://npmcn.com/package/%40cocreate/elements/#readme-usage)
-   [如何运作](https://npmcn.com/package/%40cocreate/elements/#readme-how-it-works)
-   [数据范围](https://npmcn.com/package/%40cocreate/elements/#readme-the-data-scope)
-   [核心属性](https://npmcn.com/package/%40cocreate/elements/#readme-core-attributes)
-   [行为属性](https://npmcn.com/package/%40cocreate/elements/#readme-behavior-attributes)
-   [密钥表达式](https://npmcn.com/package/%40cocreate/elements/#readme-key-expressions)
-   [值管道](https://npmcn.com/package/%40cocreate/elements/#readme-value-pipeline)
-   [表单](https://npmcn.com/package/%40cocreate/elements/#readme-forms)
-   [过滤和列表](https://npmcn.com/package/%40cocreate/elements/#readme-filtering-and-lists)
-   [实时同步](https://npmcn.com/package/%40cocreate/elements/#readme-realtime-synchronization)
-   [行动](https://npmcn.com/package/%40cocreate/elements/#readme-actions)
-   [方法](https://npmcn.com/package/%40cocreate/elements/#readme-element-methods)
-   [Java 脚本 API](https://npmcn.com/package/%40cocreate/elements/#readme-javascript-api)
-   [行为说明](https://npmcn.com/package/%40cocreate/elements/#readme-behavior-notes)
-   [通知](https://npmcn.com/package/%40cocreate/elements/#readme-announcements)
-   [路线图](https://npmcn.com/package/%40cocreate/elements/#readme-roadmap)
-   [如何贡献](https://npmcn.com/package/%40cocreate/elements/#readme-how-to-contribute)
-   [关于](https://npmcn.com/package/%40cocreate/elements/#readme-about)
-   [许可证](https://npmcn.com/package/%40cocreate/elements/#readme-license)

* * *

## 特征

-   **声明数据绑定 :** 将一个元素指向一个文档字段,并读取、制作和坚持该字段,而没有任何应用代码.
-   **自动 CRUD 分辨率 :** 操作是从现在的属性推断出来的,所以同样的标记在它没有ID时创造了一个记录,并在它有的时候更新.
-   **实时双向同步 :** 元素订阅自己的数据范围,并在系统任何地方的基本记录发生变化时立即更新.
-   **已删除 :** 共享范围的要素被收集到一个单一的查询中,因此一个包含在20个字段的文档可以完成一个读取.
-   **文档窗体:** 一种形式将战地组合成一个有效载荷,向儿童宣传其范围,并将儿童作为单一行动加以保存.
-   **值转换管道 :** 入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出.
-   **过滤器集成 :** 与 `@cocreate/filter` 以驱动查询、排序、页码和无限卷轴.
-   **行动整合:** 登记册 `save`, (中文(简体) ), `delete`,以及 `reset` 坚韧不拔地形成行动链.
-   **自动绑定 :** 后来插入的内容,包括提供的模板,将自动初始化并订阅.

* * *

## 安装

```bash
npm install @cocreate/elements
```

```bash
yarn add @cocreate/elements
```

### 光盘N

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

* * *

## 使用量

### 显示值

```html
<span array="users" object="64b9a32e18f21bc56789abcd" key="name"></span>
```

元素读取 `name` 字段。 如果文档在系统的任何位置发生变化,则元素会更新.

### 编辑一个值

```html
<input
    array="users"
    object="64b9a32e18f21bc56789abcd"
    key="email"
    realtime="true" />
```

与 `realtime`每一个键盘都坚持着球场。 没有它,值在 `save` 动作运行.

### 组合字段输入文档

```html
<form array="users" object="64b9a32e18f21bc56789abcd">
    <input key="name" />
    <input key="email" />
    <textarea key="bio"></textarea>

    <button actions="save">Save</button>
</form>
```

表格向每个字段宣传其范围,因此,每个输入只声明其 `key`保存发送一个包含所有三个字段的有效载荷.

### 创建记录

```html
<form array="users" object>
    <input key="name" />
    <input key="email" />

    <button actions="save, reset">Create</button>
</form>
```

一个空的 `object` 属性表示“还没有文档”。 在保存模块发布一个创建时,然后将新的id写回窗体及其字段,因此之后会保存同一记录的更新.

### 创建列表

```html
<div
    array="users"
    object
    filter-query-key="status"
    filter-query-value="active"
    filter-limit="20"
    filter-sort-key="name"
    render-query="[template]">
    <div template>
        <span>{{object.name}}</span>
        <span>{{object.email}}</span>
    </div>
</div>
```

### 删除记录

```html
<button
    array="users"
    object="64b9a32e18f21bc56789abcd"
    actions="delete">
    Delete
</button>
```

可以通过 `delete-query`。每个目标宣布 拥有 CRUD 范围; 共享相同存储、 数据库和数组的对象 在一个删除请求中发送.

```html
<button
    actions="delete"
    delete-query="$document [data-delete]:checked[]">
    Delete selected
</button>

<input
    type="checkbox"
    data-delete
    array="users"
    object="64b9a32e18f21bc56789abcd" />
```

* * *

## 如何运作

1.  装入模块扫描宣布的元素时 `storage`, (中文(简体) ), `database`, (中文(简体) ), `array`,或 `render-json`。 。 。 .
2.  每个元件的属性被分析成一个正常的 CRUD 有效载荷,及其 **类型** 被推断为存在属性.
3.  A 类 **数据键** 由范围产生,每个共享关键要素被组合在一起。 外地一级 `key` 被故意从文档范围密钥中排除,因此一个文档的所有字段都具有同一个范围.
4.  在套接字上标出范围,从而将未来的修改推向每个约束要素.
5.  读取被解析分批,因此一个查询服务于范围中的每一个元素.
6.  反应被分配到每个元素中,这些元素取出自己的活地,并通过价值管道使其形成.
7.  可编辑元素聆听输入 。 何时 `realtime` 启用后,更改会自动持续.
8.  写入一个创建或更新的解析度,取决于是否存在一个id,而生成的id被传播回标记.

* * *

## 数据范围

属性描述一个层次,从存储提供者下到单个字段.

| 职等 | 属性 | 说明 |
| --- | --- | --- |
| 存储 | `storage` | 储存供应商或别名 |
| 数据库 | `database` | 数据库名称 |
| 阵列 | `array` | 收集、表格或数据集 |
| 指数 | `index` | 数组内的索引 |
| 对象 | `object` | 文档 ID, 新文档为空 |
| 密钥 | `key` | 文档中的字段 |

这个 **类型** 从目前的最深层推断出:

| 属性显示 | 推导类型 |
| --- | --- |
| `object` 或者说 `key` (与 `array`(中文(简体) ) | `object` |
| `index` (与 `array`(中文(简体) ) | `index` |
| `array` | `array` |
| `database` | `database` |
| `storage` | `storage` |

其中任何一个都可能同时持有一个逗号分离列表,以瞄准多个瞄准镜.

```html
<div array="users, admins" key="name"></div>
```

* * *

## 核心属性

| 属性 | 说明 |
| --- | --- |
| `storage` | 业务所针对的储存供应商 |
| `database` | 数据库名称,组织默认值 |
| `array` | 收藏或表格名称 |
| `index` | 数组内的索引范围 |
| `object` | 文件编号。 空创建新文档 , `ObjectId()` 生成一个, `pending` 标记飞行中的创建 |
| `key` | 文档中的字段路径 |
| `updateName` | 更新命名范围时重命名目标 |
| `organization_id` | 租户身份标识 |
| `host` | 主机上下文 |
| `apikey` | 用于操作的 API 密钥 |
| `room` | 实时房间范围 |
| `reference` | 何时 `false`,从返回对象中去除存储元数据 |

* * *

## 行为属性

每个都接受 `"false"` 选择退出,而大多数默认启用.

| 属性 | 说明 |
| --- | --- |
| `crud="false"` | 将元素完全排除在约束之外 |
| `read="false"` | 元素不读,只写 |
| `save="false"` | 元素从不写,只读 |
| `update="false"` | 元素忽略其首次读取后收到的更新 |
| `listen="false"` | 元素忽略了广播,但仍接受自己的读取 |
| `delete` | 将元素标为删除目标 |
| `upsert` | 如果文档在更新时不存在, 则创建此文档 |
| `realtime="true"` | 坚持每个输入事件 |
| `crdt="true"` | 通过协作合并而不是覆盖编辑文字 |
| `broadcast="false"` | 向其他客户端播放更改 |
| `broadcast-sender="false"` | 向发送者反馈变化 |
| `broadcast-client="false"` | 禁止传播到其他标签 |
| `form-attributes="false"` | 防止元素继承其形式范围 |
| `reset` | 控制重置行为,见 [表单](https://npmcn.com/package/%40cocreate/elements/#readme-forms) |
| `splice`, (中文(简体) ), `slice`, (中文(简体) ), `update` | 当密钥瞄准索引时的矩阵突变模式 |

* * *

## 密钥表达式

`key` 支持不止一个平方字段名称.

| 表达式 | 决定: |
| --- | --- |
| `name` | 一个顶级字段 |
| `profile.address.city` | 通过点标记的嵌入地 |
| `tags[0]` | 按索引排列的数组成员 |
| `{}` | 用于读取或写入整个对象的整个文档 |
| `tags.$length` | 数组字段的长度 |
| `$data` | 完整的应答有效载荷 |
| `$object` 编号 : `$array` | 当前类型的全部结果收集 |

```html
<span array="posts" object="64b9a32e18f21bc56789abcd" key="comments.$length"></span>
```

* * *

## 值管道

价值观在进出途中被改变 `@cocreate/element-prototype`。这些属性适用于任何约束元素.

| 属性 | 说明 |
| --- | --- |
| `value-type` | 强制值, 例如 `json`, (中文(简体) ), `html`, (中文(简体) ), `text`, (中文(简体) ), `array`, (中文(简体) ), `number` |
| `value-prefix` | 预留字符串 |
| `value-suffix` | 附加字符串 |
| `value-replace` | 替换模式的第一个匹配 |
| `value-replaceall` | 替换图案的所有匹配 |
| `value-replacement` | 上面使用的替换字符串 |
| `value-lowercase` | 小写值 |
| `value-uppercase` | 大写值 |
| `value-encode` | 编码该值, 例如 base64 或 URI |
| `value-decode` | 解码值 |
| `value-remove-query` | 在读取 HTML 值前删除匹配的节点 |
| `value-dispatch` | 当查询返回无结果时清除值 |
| `value-bubbles` | 泡泡合成输入事件 |
| `value-query` | 由其他元素构成此元素的值 |
| `value-attribute` | 将构成值写入属性而不是值 |

```html
<textarea
    array="files"
    object="64b9a32e18f21bc56789abcd"
    key="src"
    value-type="text"
    value-replaceall="/```html\n|\n```/g"></textarea>
```

* * *

## 表单

### 范围 继承

宣传表格 `organization_id`, (中文(简体) ), `host`, (中文(简体) ), `storage`, (中文(简体) ), `database`, (中文(简体) ), `array`, (中文(简体) ), `index`, (中文(简体) ), `object`,以及 `key` 对参与约束的后裔要素。 添加 `form-attributes="false"` 对必须保持自身范围的因素.

### 生成的编码

`object="ObjectId()"` 创建初始化时的客户端标识,让相关记录在持续前相互参考.

### 保存

保存一个表格将每个捆绑场收集成每个类型的一个有效载荷,并发布一次操作. 在表格中保存个人元素代表到表格,因此一个字段从不偶然写出部分文档.

### 重设

这个 `reset` 属性控制重置保存的内容.

| 数值 | 文件编号 | 数值 |
| --- | --- | --- |
| 删除 | 清除 | 清除 |
| `object` | 清除 | 保留 |
| `value` | 保留 | 清除 |
| `false` | 保留 | 保留 |

```html
<input key="organization_id" value="$organization_id" reset="false" hidden />
```

* * *

## 过滤和列表

过滤属性 `@cocreate/filter` 直接用绑定的范畴来驱动查询,排序,限制,和页码.

```html
<div
    array="posts"
    object
    filter-query-key="status"
    filter-query-value="published"
    filter-sort-key="created.on"
    filter-sort-direction="desc"
    filter-limit="10"
    render-query="[template]">
    <div filter-on="scroll" filter-query="$parent"></div>
    <article template>{{object.title}}</article>
</div>
```

一个过滤器元素可能针对另一个元素 `filter-query`,因此页面其它位置的输入可以驱动列表的查询。 更改过滤器重新读取范围并重新发回.

* * *

## 实时同步

每个瞄准镜通过两个频道的套接字订阅:一个用于特定文档,另一个用于它所属的收藏. 因此,修改既涉及与该记录相连的要件,也涉及任何收集该记录的清单.

订阅数为参考数。 当从 DOM 中去除最后一个绑定到某个范围的元素时,模块会自动不订阅,因此提供列表和模式不会泄露通道.

* * *

## 行动

| 行动 | 完成事件 | 行为 |
| --- | --- | --- |
| `save` | `saved` | 坚持元素,或者它属于某个元素时的形态 |
| `delete` | `deleted` | 删除绑定文档, 尊重 `delete-query` 多个目标 |
| `reset` | `reset` | 根据每个字段恢复窗体 `reset` 属性 |

```html
<button actions="save, reset">Save and clear</button>
```

* * *

## 方法

将方法直接附在元素上,因此必须的代码和行动链共享一个执行.

| 方法 | 打开可用 | 说明 |
| --- | --- | --- |
| `getValue()` | 任何绑定元素 | 通过值行读取值 |
| `setValue(value)` | 任何绑定元素 | 写入值并发送输入和更改 |
| `read()` | 任何绑定元素 | 重读元素的范围 |
| `save()` | 任何约束要素或形式 | 坚持元素或整个形式 |
| `getData()` | 表单 | 返回组装的有效载荷而不保存 |
| `getFilter()` 编号 : `setFilter()` | 过滤元素 | 读取或替换活动过滤器,重新读取范围 |

```javascript
const form = document.querySelector("#profile");
const payload = await form.getData();
await form.save();
```

* * *

## Java 脚本 API

```javascript
import elements from "@cocreate/elements";

elements.init();
elements.init(document.querySelector("#profile"));
```

| 方法 | 说明 |
| --- | --- |
| `init(element)` | 初始化元素、集合或整个文档 |
| `read(element, data, dataKey)` | 读取范围并分发结果 |
| `save(element, action)` | 坚持元素或形式 |
| `getData(element)` | 将有效载荷组合成一个元素或形式 |
| `getDataObject(element)` | 将元素的属性规范化为 CRUD 有效载荷 |
| `reset(action)` | 运行窗体重置逻辑 |
| `setDataType(element, data, action)` | 将已创建的记录的 ID 应用到标记中 |
| `elements`, (中文(简体) ), `keys`, (中文(简体) ), `forms` | 约束要素和范围的内部登记册 |

* * *

## 行为说明

-   元素必须声明 `storage`, (中文(简体) ), `database`,或 `array` 待初始化。 孤独 `object` 或者说 `key` 因此,表格中的字段依赖继承范围.
-   读取为500ms被去除并被每个范围去去重复,所以许多内容绑定一个文档产生一个单一的查询.
-   一个元素每个范围读取一次。 更改过滤器或调用 `read()` 恢复状态.
-   文档 ID 必须是 24 个十六进制字符值, 或占位符 `pending` 财务报告和审定财务报表 `ObjectId()`。 。 。 .
-   服务器上显示的元素 `rendered` 标记并跳过他们的第一个客户端渲染,保存服务器输出.
-   需要保存输入 `realtime`,从不适用于 `_id` 字段.
-   何时 `crdt` 并启用了文档 id,文本编辑会协同进行合并,而不是覆盖.

* * *

## 通知

图书馆的所有更新都记录在我们 [变化](https://github.com/CoCreateJS/elements/blob/master/CHANGELOG.md) 财务报告和审定财务报表 [释放](https://github.com/CoCreateJS/elements/releases)。您也可以订阅电子邮件以发布和中断更改.

* * *

## 路线图

即将作出的改进包括:

-   扩展数组突变操作符
-   失败时优化回滚
-   Schema-aware 价值胁迫
-   开发模式诊断无约束和配置错误的范围
-   Devtools 检查元素的范围和订阅

如果你对这个项目的未来方向有兴趣, 请看看我们的开放 [问题](https://github.com/CoCreateJS/elements/issues) 财务报告和审定财务报表 [拖动请求](https://github.com/CoCreateJS/elements/pulls)我们想听听你的反馈.

* * *

## 如何贡献

我们鼓励为我们的图书馆捐款(你甚至可能得分) [捐款](https://github.com/CoCreateJS/elements/blob/master/CONTRIBUTING.md) 详细指南.

我们希望这个图书馆由社区驱动, Coreate 领导。 我们需要你的帮助来实现这一目标。 为了帮助确保我们按正确的顺序建造正确的东西,我们请你们创造 [问题](https://github.com/CoCreateJS/elements/issues) 财务报告和审定财务报表 [拖动请求](https://github.com/CoCreateJS/elements/pulls) 或只是对现有问题进行投票或发表意见或提出请求.

我们感谢你的继续支持,谢谢!

* * *

## 关于

CoCreate-elements 由 CoCreate 开发者体验团队指导和支持.

请发电子邮件给开发者体验团队 [这里](mailto:develop@CoCreateJS.com) 如果有任何疑问.

创造要素由创造要素公司维护和资助. CoCreate的名称和标志是CoCreate,LLC的商标.

* * *

## 许可证

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

-   **开源使用**:用于开源项目和非商业用途,此软件可在AGPLv3下提供. AGPLv3允许您自由使用,修改并分发此软件,前提是所有修改和衍生作品也根据AGPLv3获得许可. 营业执照全文见 [自由文件](https://github.com/CoCreateJS/elements/blob/master/LICENSE)。 。 。 .
    
-   **商业用途**: 意图将这一软件用于商业目的的营利性公司和个人必须获得商业许可证。 商业执照,当你签到 API 密钥我们 [网站](https://cocreatejs.com/)。该许可证允许对软件进行专有使用和修改,而不需要AGPLv3的左取要求。 将这一软件融入专有商业产品和应用是理想的.
    

如果您没有购买商业许可证,并打算将这个软件用于商业目的,请到我们的网站上注册API密钥.

### 输入动作按钮的快捷键

设定 `submit-query` 在窗体或内部区域明确选择动作 元素 Enter 应从单行输入中单击:

```html
<form>
    <section submit-query="#next-step">
        <input name="name" />
        <button id="next-step" type="button" actions="disabled, validate, save, disabled">Next</button>
    </section>
</form>
```

离这里最近的 `submit-query` 在形式中获胜。 它的值使用 Coreate 查询 选择器,从带有属性的元素中解析出。 决心 目标必须 `actions`,属于同一种形式,并可见和启用. 当属性缺失时,不推断任何动作目标. 空或未解决 查询、多个返回的目标以及已禁用的目标不会通过 土生土长。 Hold Enter 不反复激活按钮 .

文本区域、 选择、 可编辑的内容、 输入部件、 组成、 修改 按键键, 已经由另一个听众处理的事件保持正常 键盘行为。 此快捷键调用 `.click()`; 它不提交表格 自己来 现有 `action`编号 :`method` 处理仍然分开,并提交按钮 与 `actions` 还可以通过链条对外部提交进行预处理.

## 常见问题

### @cocreate/elements 是什么？

通过使用html5属性来查询存储在CoCreate无头 CMS中的数据,将内容获取到任意html元素中\. 如果数据被更改, 它会立即在 html 标签中反映出来, 因为更改会实时播放

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

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

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

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

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

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

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

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

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

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

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

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