# @checkly/elements 中文文档

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

版本：0\.1\.0-beta\.2
npm 元数据更新时间：2026-10-20T10:44:09.412Z
中文译文更新时间：2026-11-09T13:08:42.193Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：633 kB，75 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- peer 依赖：@types/react \>=19
- 首次发布：2026-10-09T08:05:03.620Z
- 最新版本发布：2026-10-16T10:20:25.777Z
- 近 30 天下载量：2641（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

作为框架不可知自定义元素对用户界面进行严格监测

## 安装

```sh
npm install @checkly/elements
```

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

## README

# @ checkly/ 要点

以框架不可知自定义元素——状态, 上调时间、统计数据和事件,无论何时 围绕它的框架.

仅浏览器和仅使用ES: 由 a 装入 `<script type="module">` 在你的页面上, 没有共同JS的构建. `lit` 财务报告和审定财务报表 `@lit/context` 只有运行时间 依赖性,一个测试可以阻止列表的增长.

## 安装

预释放在npm下 `pre` 标签; 尚未稳定释放.

```sh
pnpm add @checkly/elements@pre
```

每一次释放都是从承诺开始命名的 所以把准确的 在一个必须复制其建筑的项目中。 在双方工作 一次,构建此取出( t)`pnpm install` 还建造 `dist/`和 `pnpm link /absolute/path/to/checkly-elements` 从消费者.

[从另一个寄存器中收存](https://npmcn.com/package/%40checkly/elements/docs/consuming.md) 涵盖其他 线路进入.

每个元件都是从自己的入境点进口的,而进口是 注册标签 :

```html
<script type="module">
  import '@checkly/elements/status-dot'
</script>

<checkly-status-dot status="failing" label="Checkout API"></checkly-status-dot>
<checkly-status-dot status="success" size="small"></checkly-status-dot>
```

## 这是什么

该目录包含15个显示元素,加上可选的API适配器,一个HTTP 客户和两个公共资源来源。 从平原显示元素渲染 视图模型属性,所以一个主机可以从自己的商店来作一个板.

| 路径 | 目的 |
| --- | --- |
| `src/core` | 基类 每一个元素都建立在:符号表,四个数据状态,阴影/光-DOM机械,源道. |
| `src/client` | HTTP运输、传呼和能见度 -- -- 源元素和服务器侧消费者使用的民调. |
| `src/adapters` | 从仪表板和状态页的电线回放中 纯绘图到视图模型中. |
| `src/sources` | 可选的自定义元素可以获取公共仪表板或状态页并输入其下方的渲染目录. |
| `src/elements` | 目录. 这里的文件自动是一个切入点,大小预算,以及每个相容套件的主题. |
| `themes/` | `checkly.css`,生成:用一个 `.dark` 和Checkly的应用程序一样 产品本身是元素的默认值. |
| `demo/` | 反应灵敏的国家、主题和现场公共资源采集的审查中心. |
| `scripts/` | 该建筑的辅助铸造:生成样式docs,大小预算,自文档检查. |

## 正在获取检查数据

渲染目录和取取客户端是独立的出入口. 页面 因此没有下载HTTP或投票码:

```js
import { ChecklyClient } from '@checkly/elements/client'

const client = ChecklyClient.forDashboard({ dashboardId: 'my-dashboard' })
const statuses = await client.listCheckStatuses()
```

`forDashboard` 财务报告和审定财务报表 `forStatusPage` 使用相应的出版资源 APIs (英语). `forApi` 用于服务器侧码,需要账户 API 键加其 账户编号.

已经执行自己要求的消费者可以导入相同的映射 函数而不使用客户端或任何元素:

```js
import { adaptChecks } from '@checkly/elements/adapters'
```

对于无框架的公共仪表板,请导入其来源并包入元素 应接收其数据:

```html
<script type="module">
  import '@checkly/elements/dashboard-source'
  import '@checkly/elements/check-list'
</script>

<checkly-dashboard-source dashboard-id="my-dashboard">
  <checkly-check-list></checkly-check-list>
</checkly-dashboard-source>
```

使用状况文件 `@checkly/elements/status-page-source` 和要求 `version="v2"` 或者说 `version="v3"`。这些源元素有意支持 仅限公共资源;保护资源需要单独设计 认证桥.

状态页源输入了嵌入式服务上行时间、事件横幅/列表以及 维护清单。 选择升起时间 `service-id`,并使用 `history` 一个 事件列表显示其存档. 您的页面拥有版式, 服务标题 和品牌;来源拥有请求和API特定映射.

### 范围账户数据试点

作者组成的页面也可以使用实验 `/v1/embed-tokens` 财务报告和审定财务报表 `/v1/elements-data` 终点,后面 `ELEMENTS_EMBED` 账户旗。 A 类 服务器持有的 API 证书薄荷,用于明确检查ID 浏览器获取一次并传递快照 `adaptElementsSnapshot` 纯净的元素。 不需要投票、仪表板或对状况页面的依赖.

这个 [显示仓库](https://github.com/checkly/checkly-elements-demo) 以工作为例: 保存密钥、握手的本地服务器, 和能证明它失效的探测器.

### API 密钥仅为服务器侧

一个账户API密钥可以读取该账户,不属于浏览器代码. `ChecklyClient.forApi()` 拒绝 `cu_` 财务报告和审定财务报表 `sv_` 浏览器中的密钥,除非 呼叫器明确设置 `unsafeAllowBrowserApiKey`逃生舱仍然 记录风险。 偏好公布的仪表板或状态页,或代理 通过保留密钥的后端进行特定账户数据.

## 开发

```sh
pnpm install         # also builds, via prepare
pnpm demo            # the demo pages on :5173
pnpm test            # build, unit specs, hygiene
pnpm test:browser    # real Chromium, via Playwright
```

浏览器运行器第一次需要二进制 :

```sh
pnpm exec playwright install chromium
```

每一个命令,每个命令的目的,都在 [文件/开发](https://npmcn.com/package/%40checkly/elements/docs/development.md)。 。 。 .

## 文档

|  |  |
| --- | --- |
| [使用元素](https://npmcn.com/package/%40checkly/elements/docs/usage.md) | 元素本身:它们拿什么,四个州每个州都有,一个源头如何供养它们. |
| [休养](https://npmcn.com/package/%40checkly/elements/docs/styling.md) | 使这些看起来像你的产品: 代币,零件,插槽,以及抛出阴影边界。 包括每个令牌的生成表, 部分和时间档目录声明 . |
| [从另一个寄存器中收存](https://npmcn.com/package/%40checkly/elements/docs/consuming.md) | 三种方式——发表在npm上,被束缚在一种承诺上,或与当地联系起来——以及达到的目的. |
| [发展](https://npmcn.com/package/%40checkly/elements/docs/development.md) | 命令,两个试跑者,截图套件,演示页,出入口,大小预算. |
| [出版](https://npmcn.com/package/%40checkly/elements/docs/publishing.md) | 预放和放出是如何运行的,注册标记的意思是什么,在第一个稳定版本之前必须真实的是什么. |
| [一般事务人员(其他职等)](https://npmcn.com/package/%40checkly/elements/AGENTS.md) | 针对在此寄存器中工作的编码代理的指令 . |

## 许可证

麻省理工学院.

## 常见问题

### @checkly/elements 是什么？

作为框架不可知自定义元素对用户界面进行严格监测

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

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

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

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

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

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

### @checkly/elements 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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