# @colinaut/alpinejs-plugin-simple-validate 中文文档

规范地址：https://npmcn.com/package/%40colinaut/alpinejs-plugin-simple-validate/

版本：1\.8\.2
npm 元数据更新时间：2024-04-01T19:27:01.791Z
中文译文更新时间：2026-11-10T13:22:07.001Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：202 kB，33 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2022-07-14T03:52:23.003Z
- 最新版本发布：2024-04-01T19:27:01.609Z
- 近 30 天下载量：2448（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 0 个）

## 中文简介

简单的 Alpine 窗体验证插件

## 安装

```sh
npm install @colinaut/alpinejs-plugin-simple-validate
```

也可以使用：`pnpm add @colinaut/alpinejs-plugin-simple-validate`、`yarn add @colinaut/alpinejs-plugin-simple-validate`、`bun add @colinaut/alpinejs-plugin-simple-validate`

## README

# AlpineJS 插件 — 简单形式验证

![](https://img.shields.io/bundlephobia/min/@colinaut/alpinejs-plugin-simple-validate) ![](https://img.shields.io/npm/v/@colinaut/alpinejs-plugin-simple-validate)

非常简单的窗体验证插件 [阿尔卑斯山](https://alpinejs.dev/)。这个插件的设计与AlpineJS本身一样,可以根据需要被喷入。 此插件没有为您的窗体数据或功能强制设置一个有意见的结构 。 它可以使用或没有x-model.

X-validate指令允许简单的验证和出错显示. 它还以活性形式Data来捕捉所有的形式数据. $validate 魔法函数允许访问验证函数,formData,以及简单的提交验证检查.

## 最新情况1.8

-   用于 $validate 魔法函数的嵌入式字段工作, 如 Complete ()、 data () 或 value () .
-   禁用现在是窗体Data对象的字段属性 。 当一个字段被禁用时,无论是通过设置禁用字段本身还是母字段集,禁用的财产都会被设定为真实的. _已禁用字段默认有效, 不返回值 ._ 被一个变异观察者监视残疾,所以AlpineJS绑定 `:disabled` 将工作.
-   隐藏属性不再需要 x- validate , 以便在设定时更新 `:value` 或其它 javascript 以动态更新值。 变异观察者会自动发现变化和更新.
-   **破坏变化** x 需要删除。 使用 AlpineJS 绑定 `:required` 而不是按需要动态设置.

## 简单使用

添加一个 `x-data`,以及 `x-validate` 给您的 `<form>` 元素(您不需要x-data上的任何变量;它只需要作为高山元件启动). 此自动 :

-   将所有数据抓取到被动形式 Data\[form\] 数组,该数组在模糊或点击时更新(取决于字段类型).
-   使用基本浏览器检查Validity( ) 校验 blur `required` 属性和输入类型.
-   由于浏览器版本有限,因此对所需、电子邮件、电话和url类型字段使用内置改进的regex验证.
-   自动添加隐藏 `span.error-msg` 与字段相邻的错误消息相邻.
    -   你需要自己来设计这个_见下文示例_(中文(简体) )
-   当有效性检查失败时,它...
    -   添加数 `aria-invalid="true"` 财务报告和审定财务报表 `aria-errormessage` 属性到字段元素.
    -   删除错误消息 `hidden` 属性.
    -   还添加了多余的 `data-error="{error message}"` 字段的父元素,用于您想要的任何额外样式(搜索最接近的样式) `field-parent` 类母元素或未使用 `.parentNode`) (中文(简体) ).
    -   模糊触发无效后, 它会添加“ 输入” 事件倾听器用于验证以及“ blur ”
-   如果触发有效, 则会反转所有上述内容
-   使用 `:disabled="$validate.isComplete('formId')"` 以禁用提交按钮和/或使用 `@submit="$validate.submit"` 在提交前自动检查所有字段的有效性.

## 自定义使用

-   使用 `x-validate` 指令与直接针对窗体字段的修改符一起添加额外的验证,例如 `x-validate.wholenumber`
-   写自定义错误消息 :
    -   添加 `data-error-msg='custom error message'` 字段本身
    -   添加兄弟元素为 `error-msg` 类并在此写入您自己的错误消息。 该插件将搜索所有相邻的兄弟姐妹, 并为您添加连接的 aria- errormessage 标识 。 如果您想要在错误消息之前添加一些描述性文字或其他元素, 或者如果您想要对特定错误消息使用特殊的样式, 这也是有用的 .
    -   在页面的任意位置添加一个带有正确 id 属性的元素( id 是) `error-msg-${id of matching field}`它会用它.
-   使用 `x-validate.group` 在复选框或收音机按钮组上验证选中至少一个.
-   向类似字段添加特定测试 `x-validate='$el.value === 'bunny'` (见下文使用表达式验证).
-   使用 `$validate.isComplete(el)` 以检测形态, `<fieldset>` 组或任何字段完成
-   你可以跳过 `x-validate` 编辑 `<form>` 再加一点 `x-validate` 如果您想要验证几个字段,则直接输入字段。 仍然需要x数据 `<form>`。 。 。 .
-   Git repo 中的实例文件夹显示您可以使用此插件的一些 .

## 指令 x- 验证

### 窗体元素指令和 UI 修改器

UI 修改器主要用于设置全局默认值 `<form>` 但也可以用于单个形式字段元素上进行更具体的控制.

-   `x-validate` 触发验证并抓取整个窗体的表格Data
-   `x-validate.bluronly` —— 修改默认内容, 绝不在可填表字段中使用“ 输入” 事件倾听器
-   `x-validate.input` 设置字段以同时使用“ blur” 和“ 输入” 事件倾听器来进行所有验证
-   `x-validate.refocus` 在无效时设置要强制关注窗体元素的字段
-   `x-validate.use-browser` 使用在验证中构建的浏览器以及 x 验证
-   `x-validate.validate-on-submit` 提交时自动触发验证

### 字段元素指令

这些是用于regex验证的奖金指令。 您也可以忽略这些并使用 `pattern` 属性.

使用过 `<input>`, (中文(简体) ), `<select>`, (中文(简体) ), `<textarea>`

-   `x-validate` ——只抓取数据;如果不抓取数据,则自有用处 `<form>`。同样有用的是配对特定的字段验证表达式,例如 `x-validate='$el.value === 'bunny'`。 。 。 . _请注意,在许多情况下,情况是正常的 [模式属性](https://www.w3schools.com/TAGS/att_input_pattern.asp) 也许是你需要的._
-   `x-validate.required` - 替换 `required` 属性\*
-   `x-validate.tel` 使用改进的正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正正则正则正则正正
-   `x-validate.email` - 使用改进后的正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正正则正则正则正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正正
-   `x-validate.website` ——如果站点域名有效,无论是否http://或https://
-   `x-validate.url` 使用改进的正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正则正正正则正则正正则正则正则正则正
-   `x-validate.number` − 如果数字有效(正或负;整数或小数)
-   `x-validate.integer` − 如果整数有效(正数或负数)
-   `x-validate.wholenumber` − 如果整数有效(正整数)
-   日期验证: 允许在单位之间 / 或 - 或
    -   `x-validate.date` 默认为"yyyy-mm-dd"格式,因为这就是 `type='date'` 输入字段将日期保存为
    -   `x-validate.date.mmddyyyy` —'mm-dd-yyyy'格式
    -   `x-validate.date.ddmmyyyy` —'dd-mm-yyy'格式
    -   `x-validate.date.yyyymmdd` ——"yyyy-mm-dd"格式
    -   _如果你想更复杂的验证 我建议 [日数](https://github.com/iamkun/dayjs)_

\* 允许您使用 `x-validate.required` 改为 `required` 属性或 `x-validate.tel` 打开 `type='text'` 改为 `type='tel'`

#### 使用表达式验证

您可以在字段中添加一个特定的测试 `x-validate='$el.value === 'bunny'`;这可以与其他验证对齐. 例如: `x-validate.website='$el.includes('bunny')` 只有网站有兔子的名字. _请注意,在许多情况下,情况是正常的 [模式属性](https://www.w3schools.com/TAGS/att_input_pattern.asp) 也许是你需要的._

### 复选框和无线电按钮组

共享同名属性的复选框和收音机按钮更新同名表格Data字段数据对象. 电台按钮用当前选中的按钮更新值 。 复选框同时保存一个逗号分隔的字符串值和一个数组.

您可以通过添加验证选中至少一个 `x-validate.group` 到指定组中的每个复选框或收音机按钮。 如果您想要用户选择多个复选框, 请使用添加的最小数字表达式 `x-validate.group="2"`。 。 。 .

_**说明:** 复选框和收音机按钮组在组的包装后添加出错消息. 这要么是最近的 `field-parent` 类父元素或它使用 `.parentNode.parentNode` 默认。 据推测,每个复选框/收音机被一个标签或列表项所包裹,然后在组周围有包装._

## 魔法函数

-   `$formData` 返回当前窗体Data对象
-   `$validate` 是具有一组函数的对象(见下文函数)

### 校验函数

您可以添加任何特定的验证, 如 _电子邮件_ 或者说 _电话_。魔法功能与指令的主要区别在于假设需要的功能.

-   两者 `$validate.email('')` 财务报告和审定财务报表 `$validate.email('hi')` 返回虚假
-   `$validate.email('hi@hello.com')` 返回正则
-   `val === '' || $validate.email(val)` 如果 val 是空字符串或是一个有效的电子邮件地址, 返回 true
-   验证日期允许这样的格式 `$validate.date.mmddyyyy(str)`

### 其他职能

使用时 `<form>`,则 `x-validate` 每个字段被添加到被动式Data\[formId\]阵列中. 如果只用于单个字段, `x-validate` 只将这些字段添加到窗体Data\[formId\]阵列中.

-   `@submit="$validate.submit"` 用于窗体元素。 验证当前窗体; 如果显示验证失败错误并阻止提交事件 .
-   `$validate.isComplete(el)` 返回窗体、字段或字段的真伪有效性
-   `$validate.data(el)` 返回窗体或字段设置字段的数组,或单个字段数据对象 \*
-   `$validate.formData(form)` 返回带有按键字段名的原始窗体Data对象 \*
-   `$validate.value(el,value)` 返回带有字段名键的简单对象及其窗体和字段的值,或仅仅是字段的原始值。 值参数是可选的,只针对字段;如果它会更新字段值并更新x-validate formData. \*

\* 'el' 参数变量可以使用 $refs 或名称/id 的字符串来获取窗体、字段集和字段的数据.

### 高级函数

这些允许访问一些后端的功能——您自己冒险使用.

-   `$validate.updateData(field,data,triggerErrorMsg)` 允许您直接为字段添加/更新窗体Data数组。 当只用字段名称被调用时,它会抓住字段的新值. 如果您正在通过其他 javascript 函数动态更新字段, 这一点将会有所帮助 .
-   `$validate.toggleError(field,valid)` 允许您切换任意字段中的错误信息.

## 示例窗体数据

```
{
    'field-name': {
        name: 'field-name', node: [field HTMLElement], value: 'field value', valid: true, required: true, mods: [array of directive modifiers], set: [parent fieldset HTMLElement], parentNode: [parent HTMLElement], array: [array of checked selections (only used groups of checkboxes or radio buttons)], exp: [expression on x-validate]
    }
}
```

_**说明:** 名称 = 名称属性 || id 属性_

## 示例

实例文件夹中更为复杂的例子 。 运行 `npm run serve` 来观看.

```
<form id="form" x-data x-validate @submit="$validate.submit">
        <p><em>* required</em></p>
        <div>
            <label for="name">Your Name *</label>
            <input type="text" id="name" name="name" required />
        </div>
        <div>
            <label for="email">Your Email *</label>
            <input type="email" id="email" name="email" required />
        </div>
        <div>
            <label for="wholenumber">Whole Number</label>
            <input type="wholenumber" id="wholenumber" name="wholenumber" x-validate.wholenumber data-error-msg="positive whole number required" />
        </div>
        <div id="animals" data-error-msg="you must pick at least one animal">
            <h4>Favorite Animals *</h4>
            <label><input type="checkbox" x-validate.group name="animal" id="cat" value="cat" /> 
                Cat</label>
            <label><input type="checkbox" x-validate.group name="animal" id="dog" value="dog" /> 
                Dog</label>
            <label><input type="checkbox" x-validate.group name="animal" id="bunny" value="bunny" /> 
                Bunny</label>
        </div>
        <div>
            <input type="submit" value="submit">
        </div>
    </form>
<style type="text/css">
    /* style to display the error message */
    .error-msg {
        color: red;
    }
</style>

```

### 更详细错误信息样式示例

```
.error-msg[hidden] {
    opacity: 0;
    height: 0px;
    transform: scale(0);
}
.error-msg {
    font-size: 0.8rem;
    font-weight: 700;
    color: darkred;
    transform-origin: left;
    transition: all 200ms;
    display: block;
}
```

## 安装

### 光盘N

```
<script defer src="https://unpkg.com/@colinaut/alpinejs-plugin-simple-validate@1/dist/alpine.validate.min.js"></script>
<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
```

### 国家预防机制/PNPM/YARN

```
npm i @colinaut/alpinejs-plugin-simple-validate

pnpm i @colinaut/alpinejs-plugin-simple-validate

yarn add @colinaut/alpinejs-plugin-simple-validate
```

### 捆绑和初始化

如果您正在捆绑您的 Javascript, 那么您可以初始化插件 :

```
import Alpine from "alpinejs";
import validate from "@colinaut/alpinejs-plugin-simple-validate";

Alpine.plugin(validate);

window.Alpine = Alpine;

Alpine.start();
```

### 11个静态站点

使用时 [十一号](https://www.11ty.dev/),并且想要在当地安装,而不是依赖CDN,您可以通过国家防范机制/PNPM/YARN安装,然后通过js文件,从而将其包含在输出中. 那你只需要把它加到头上.

```
eleventyConfig.addPassthroughCopy({
    "node_modules/alpinejs/dist/cdn.min.js" : "js/alpine.min.js",
    "node_modules/@colinaut/alpinejs-plugin-simple-validate/dist/alpine.validate.min.js": "js/alpine.validate.min.js",
})
```

```
<script src="/js/alpine.validate.min.js" defer></script>
<script src="/js/alpine.min.js" defer></script>
```

## 路线图

-   把密码清理干净.
-   解决字段获得新增错误消息的问题, 即使不需要这些错误消息 .
-   也许添加x-值, 以便能更方便地动态更新值 ?

在github上添加任何增强请求.

## 鸣谢

使用 [AlpineJS 插件蓝图](https://github.com/img.shields.io/github/v/release/victoryoalli/alpinejs-plugin-blueprint)

## 常见问题

### @colinaut/alpinejs-plugin-simple-validate 是什么？

简单的 Alpine 窗体验证插件

### 如何安装 @colinaut/alpinejs-plugin-simple-validate？

在项目目录运行 npm install @colinaut/alpinejs-plugin-simple-validate，或使用 pnpm add / yarn add / bun add。

### @colinaut/alpinejs-plugin-simple-validate 支持 TypeScript 吗？

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

### @colinaut/alpinejs-plugin-simple-validate 支持 ESM 还是 CommonJS？

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

### @colinaut/alpinejs-plugin-simple-validate 可以商用吗？

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

### @colinaut/alpinejs-plugin-simple-validate 的下载量有多少？

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

### @colinaut/alpinejs-plugin-simple-validate 还在维护吗？

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