# @github/auto-check-element 中文文档

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

版本：6\.0\.0
npm 元数据更新时间：2026-10-15T16:20:17.451Z
中文译文更新时间：2026-11-16T10:57:31.108Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：35.3 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2019-05-23T11:47:45.489Z
- 最新版本发布：2025-03-25T18:58:42.242Z
- 近 30 天下载量：130673（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

用服务器端点验证其值的输入元素 .

## 安装

```sh
npm install @github/auto-check-element
```

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

## README

# < 自动检查> 元素

以服务器端点验证其值的输入元素 .

## 安装

```
$ npm install --save @github/auto-check-element
```

## 使用量

### 脚本

作为模块导入 :

```js
import '@github/auto-check-element'
```

带有脚本标签 :

```html
<script type="module" src="./node_modules/@github/auto-check-element/dist/index.js">
```

### 标记

```erb
<auto-check src="/signup-check/username" csrf="<%= authenticity_token_for("/signup-check/username") %>">
  <input>
</auto-check>
```

请注意,在以下例子中,CSRF要素被标记为: `data-csrf` 属性而不是 `name` 这样,当元素被放入一个形式时,值就不会被放入后端.

```erb
<auto-check src="/signup-check/username">
  <input>
  <input hidden data-csrf value="<%= authenticity_token_for("/signup-check/username") %>">
</auto-check>
```

## 属性

-   `src` 是接收 POST 请求的服务器端点 。 张贴的表格中包含 `value` 包含要验证的文本输入的参数。 回答 200 个“ 确定” 状态时, 显示所提供的值是有效的 。 任何其他错误状态响应显示提供的值无效 .
-   `csrf` 这是 [中国证监会](https://en.wikipedia.org/wiki/Cross-site_request_forgery) 张贴表格的符号。 请求中可以使用它作为 `authenticity_token` 格式参数.
    -   您也可通过儿童元素提供CSRF标志。 见 [使用量](https://npmcn.com/package/%40github/auto-check-element/#readme-Usage) 实例.
-   `required` 是一个布尔属性,需要验证成功后才能提交周围的表格.
-   `http-method` 默认为 `POST` 以表格数据提交数据。 你可以设置 `GET` 而所使用的 HTTP 方法将是使用 url 编码的参数获取.

## 活动

### 网络请求生命周期事件

请求的生命周期活动于 `<auto-check>` 键。 这些事件不会发泡.

-   `loadstart` - 服务器抓取开始 .
-   `load` - 网络请求成功完成.
-   `error` - 网络请求失败 .
-   `loadend` - 网络请求已完成.

网络事件对显示飞行中请求时的进展状态很有用.

```js
const check = document.querySelector('auto-check')
const container = check.parentElement
check.addEventListener('loadstart', () => container.classList.add('is-loading'))
check.addEventListener('loadend', () => container.classList.remove('is-loading'))
check.addEventListener('load', () => container.classList.add('is-success'))
check.addEventListener('error', () => container.classList.add('is-error'))
```

### 自动检查事件

**`auto-check-start`** 当元素中输入时,即发出。 单位 `event.detail` 您可以找到:

-   `setValidity`:一个在输入上提供自定义失败消息的函数. 默认是"验证...".

```js
const input = check.querySelector('input')

input.addEventListener('auto-check-start', function(event) {
  const {setValidity} = event.detail
  setValidity('Loading validation')
})
```

**`auto-check-send`** 在网络请求开始前发送。 单位 `event.detail` 您可以找到:

-   `body`: FormData 请求机构在请求发送前修改.

```js
const input = check.querySelector('input')

input.addEventListener('auto-check-send', function(event) {
  const {body} = event.detail
  body.append('custom_form_data', 'value')
})
```

**`auto-check-success`** 当服务器响应 200 时发送 。 单位 `event.detail` 您可以找到:

-   `response`: 成功的服务器 [回应](https://developer.mozilla.org/en-US/docs/Web/API/Response)。其正文可用于显示服务器提供的信息.

```js
input.addEventListener('auto-check-success', async function(event) {
  const message = await event.detail.response.text()
  console.log('Validation passed', message)
})
```

**`auto-check-error`** 当服务器以400或500范围错误状态响应时,即发出。 单位 `event.detail` 您可以找到:

-   `response`: 失败的服务器 [回应](https://developer.mozilla.org/en-US/docs/Web/API/Response)。其正文可用于显示服务器提供的信息.
-   `setValidity`:一个在输入上提供自定义失败消息的函数. 默认是“ 校正失败 ” .

```js
input.addEventListener('auto-check-error', async function(event) {
  const {response, setValidity} = event.detail

  setValidity('Validation failed')

  const message = await response.text()
  console.log('Validation failed', message)
})
```

**`auto-check-complete`** 在成功或出错事件后发出,以指示自动检查生命周期的结束.

```js
input.addEventListener('auto-check-complete', function(event) {
  console.log('Validation complete', event)
})
```

## 手动触发验证

这个 `triggerValidation()` 函数可用于手动触发 `<auto-check>` 键.

```js
document.getElementById('input-element').closest('auto-check').triggerValidation()
```

## 浏览器支持

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

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

## 发展

```
npm install
npm test
```

对于本地开发,请解析下行 `examples/index` 并使用 `npx serve`。 。 。 .

## 许可证

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

## 常见问题

### @github/auto-check-element 是什么？

用服务器端点验证其值的输入元素 \.

### 如何安装 @github/auto-check-element？

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

### @github/auto-check-element 支持 TypeScript 吗？

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

### @github/auto-check-element 支持 ESM 还是 CommonJS？

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

### @github/auto-check-element 可以商用吗？

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

### @github/auto-check-element 的下载量有多少？

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

### @github/auto-check-element 还在维护吗？

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

