# @client-side-validations/client-side-validations 中文文档

规范地址：https://npmcn.com/package/%40client-side-validations/client-side-validations/

版本：25\.0\.0
npm 元数据更新时间：2026-07-05T13:00:34.286Z
中文译文更新时间：2026-11-10T01:38:46.220Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40client-side-validations/client-side-validations
原文对照：https://npmcn.com/package/%40client-side-validations/client-side-validations/?lang=original
项目主页：https://github.com/DavyJonesLocker/client_side_validations
源码仓库：https://github.com/DavyJonesLocker/client_side_validations

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

- 包体积（解压后）：103 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- Node.js 要求：\>= 18\.12
- 运行依赖：0 个
- 首次发布：2019-07-26T13:33:45.010Z
- 最新版本发布：2026-07-05T13:00:34.174Z
- 近 30 天下载量：27514（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 4 个）

## 中文简介

客户端验证方便您的铁路 7.2 和 8.x 应用程序

## 安装

```sh
npm install @client-side-validations/client-side-validations
```

也可以使用：`pnpm add @client-side-validations/client-side-validations`、`yarn add @client-side-validations/client-side-validations`、`bun add @client-side-validations/client-side-validations`

## README

# 客户端参数

[![Gem Version](https://badge.fury.io/rb/client_side_validations.svg)](https://badge.fury.io/rb/client_side_validations) [![npm version](https://badge.fury.io/js/%40client-side-validations%2Fclient-side-validations.svg)](https://badge.fury.io/js/%40client-side-validations%2Fclient-side-validations) [![Ruby Build Status](https://github.com/DavyJonesLocker/client_side_validations/actions/workflows/ruby.yml/badge.svg)](https://github.com/DavyJonesLocker/client_side_validations/actions) [![JavaScript Build Status](https://github.com/DavyJonesLocker/client_side_validations/actions/workflows/javascript.yml/badge.svg)](https://github.com/DavyJonesLocker/client_side_validations/actions) [![Maintainability](https://qlty.sh/gh/DavyJonesLocker/projects/client_side_validations/maintainability.svg)](https://qlty.sh/gh/DavyJonesLocker/projects/client_side_validations) [![Coverage Status](https://coveralls.io/repos/github/DavyJonesLocker/client_side_validations/badge.svg?branch=main)](https://coveralls.io/github/DavyJonesLocker/client_side_validations?branch=main)

`ClientSideValidations` 方便你的铁路7.2和8.x应用!

## 项目目标

1.  遵循客户端验证的最佳做法 [卢克·沃布列斯基](https://alistapart.com/article/inline-validation-in-web-forms/)
2.  自动提取并应用定义的验证规则 服务器到客户端.
3.  如果服务器侧验证规则无法执行 客户端( 即有条件的回调, 如: if, : 除非) 然后不 尝试客户端验证。 倒回服务器侧 审定.
4.  客户端验证错误渲染应为 无法与服务器侧验证错误渲染区分 .
5.  宽浏览器兼容性.
6.  使用任何活动模式:基于参数的模式
7.  验证嵌入地
8.  支持自定义验证
9.  客户端验证回调
10.  支持额外窗体构建器, ORMS 等的插件系统...

## 安装

在您的 Gemfile 中添加以下行 :

```ruby
gem 'client_side_validations'
```

然后运行 `bundle install`

请跑 `spring stop` 如果您正在使用 [春节](https://github.com/rails/spring)

您接下来需要运行生成器 :

```
rails g client_side_validations:install
```

这将安装初始化 :

```
config/initializers/client_side_validations.rb
```

### Java 脚本文件

指令取决于您的技术堆栈 .

客户端测试不再依赖于jQuery. 如果您以前安装过 `jquery-rails`, (中文(简体) ), `jquery_ujs`,或只为客户端SideValidations自定义 jQuery 启动代码,在升级到24.x时可以去除该集成.

#### 使用 Web 包装器时

添加以下软件包:

```sh
yarn add @client-side-validations/client-side-validations
```

然后在您的 `app/javascript/packs/application.js` 组合 :

```js
// If you are using `import` syntax
import '@client-side-validations/client-side-validations'

// If you are using `require` syntax
require('@client-side-validations/client-side-validations')
```

##### 涡轮和涡轮链接用户的提醒

使用时 [涡轮](https://github.com/hotwired/turbo-rails),使用 `import` 语法和确保 `@client-side-validations/client-side-validations` 导入 **之后** `@hotwired/turbo-rails`,因此,客户端参数可以正确检测 `window.Turbo` 并附上它的事务处理者.

使用时 [涡轮链接](https://github.com/turbolinks/turbolinks) 5.2, (韩语), 使用该 `require` 语法和确保 `@client-side-validations/client-side-validations` 需要时间 **之后** `Turbolinks.start()`,因此客户端参数可以正确 检测 `window.Turbolinks` 并附上它的事务处理者.

#### 使用螺旋桨时

在您的 `app/assets/javascripts/application.js` 文件 :

```js
//= require rails.validations
```

使用时 [涡轮链接](https://github.com/turbolinks/turbolinks), (中文(简体) ), 确保 `rails.validations` 需要时间 **之后** `turbolinks`这样 客户端SideValidation可以适当附加其事件处理器.

如果您需要将资产文件从宝石复制到您的项目中, 请运行 :

```
rails g client_side_validations:copy_assets
```

注:如果运行 `copy_assets`,您每次更新此项目时都需要再次运行.

## 移徙指南

### 24.x 打破变化

如果您正在升级到24x,请更新您的集成代码以使用 `ClientSideValidations` 对象直接.

已删除旧的 j 查询插件方法 。 使用 DOM- 第一公开 API 代替 :

```js
ClientSideValidations.enable(form)
ClientSideValidations.validate(form)
ClientSideValidations.isValid(form, validators)
ClientSideValidations.disable(form)
ClientSideValidations.reset(form)
```

这些方法接受本地的DOM元素和DOM集合. 他们不接受 jQuery 对象或 CSS 选择字符串 .

自定义验证器、 窗体构建器和回调器现在接收本地的 DOM 节点, 而不是 jQuery 包装器 。 更新任何使用 DOM API 的自定义代码, 如 `.value`, (中文(简体) ), `.form`, (中文(简体) ), `.closest()`,以及 `querySelector()`。 。 。 . 本地验证器称为 `(element, options)`。收到的回调表格 `(form, eventData)`,元素召回则收到 `(element, message, callback)` 或者说 `(element, callback)` 取决于事件.

所有运行时拥有的验证状态属性现在被命名为空格 `csv`。如果您在自定义选择器、召回器或验证器中读取或写入这些属性,则将其更新到范围名称:

```text
data-changed => data-csv-changed
data-valid => data-csv-valid
data-validate => data-csv-validate
data-not-locally-unique => data-csv-not-locally-unique
```

匹配数据集属性为 `element.dataset.csvChanged`, (中文(简体) ), `element.dataset.csvValid`, (中文(简体) ), `element.dataset.csvValidate`,以及 `element.dataset.csvNotLocallyUnique`。 。 。 . `csvChanged` 作为字符串值存储 `'true'` 财务报告和审定财务报表 `'false'`。 。 。 .

**j 查询指定名称的事件被删除.** 事件现在是普通本地的DOM自定义事件. 如果您的应用程序使用 jQuery 风格的命名间隔来收听或解封事件, 您必须更新这些调用 .

在此之前:

```js
$(form).on('form:validate:before.ClientSideValidations', handler)
$(input).off('.ClientSideValidations')
```

之后:

```js
form.addEventListener('form:validate:before', handler)
// store and pass the handler reference to removeEventListener when unbinding
```

客户端SideValidations发送的本地事件完整列表: `form:validate:before`, (中文(简体) ), `form:validate:after`, (中文(简体) ), `form:validate:pass`, (中文(简体) ), `form:validate:fail`, (中文(简体) ), `element:validate:before`, (中文(简体) ), `element:validate:after`, (中文(简体) ), `element:validate:pass`, (中文(简体) ), `element:validate:fail`。 。 。 .

如果您正在从23.0.0版本升级,则 `data-csv-*` 上面的更名对于任何仍然读取或写入旧属性名的自定义代码都是必要的. 如果您已经在23.x上,新的24.x升级步骤是更新任何仍然参考的本地独有性集成 `data-not-locally-unique` 或者说 `element.dataset.notLocallyUnique`。 。 。 .

如果您的应用程序销售了已编译的资产 `rails g client_side_validations:copy_assets`,在升级后再次运行该生成器,所以您复制的资产匹配当前 jQuery-free 捆绑 .

## 初始化器

初写者包括一个评论 `ActionView::Base.field_error_proc`。 。 。 . 解析此选项, 使您错误消息与输入字段连接 .

我建议你别用类似 `error_messages_for`客户端 Side 校验不支持这种类型的错误渲染 。 如果你想的话 保持客户端的一致性 而服务器侧提供了验证错误消息, 请使用其中的 `config/initializers/client_side_validations.rb`

## 插件

其他 `ActiveModel` 以其他资源和其他 铁路 `FormBuilders`请参看 [插件维基页面](https://github.com/DavyJonesLocker/client_side_validations/wiki/Plugins) (自由加入你自己)

-   [简单格式](https://github.com/DavyJonesLocker/client_side_validations-simple_form)
-   [蒙古语](https://github.com/DavyJonesLocker/client_side_validations-mongoid)

## 使用量

在你身边 `FormBuilder` 您只需要启用验证 :

```erb
<%= form_for @user, validate: true do |f| %>
  ...
```

这应该足够让你走.

从14.0版本开始,客户端参数也支持 `form_with`。 。 。 . 语法与 `form_for`数字 :

```erb
<%= form_with model: @user, validate: true do |f| %>
  ...
```

**说明:** 客户端参数要求 `id` 窗体字段的属性 工作,所以它会强迫 `form_with` 生成 id.

## 验证器命令

默认情况下, ClientSideValidations 会按相同的顺序进行验证 在模型中指定。 换句话说, 如果您想要验证格式 在电子邮件字段存在前,您可以使用以下内容:

```rb
class User < ApplicationRecord
  validates :email, format: { with: /\A[^@\s]+@[^@\s]+\z/ }, presence: true
end
```

## 有条件验证器

默认情况下,有条件的验证者不进行评估并传递给客户端. 我们这样做是因为 制表时的状态模型 不一定是状态 ,用于验证服务器侧的模型。 但是,如果你想推翻这种行为,你可以这样做 在形式。 鉴于以下模式:

```ruby
class Person < ActiveRecord::Base
  validates :name, presence: true, length: { maximum: 10 }, if: :can_validate?

  def can_validate?
    true
  end
end
```

您可以强制形式:

```erb
<%= f.text_field :name, validate: true %>
```

通过 `validate: true` 将强制所有验证者执行此属性。 如果有条件 在制作表格时,将按模型的状态对其进行评估。 你也可以强迫 单个验证符 :

```erb
<%= f.text_field :name, validate: { presence: true } %>
```

在上述情况下 `presence` 验证器将传递给客户端.

情况也是如此 [其他支持的有条件验证](https://guides.rubyonrails.org/v5.2.3/active_record_validations.html#conditional-validation) (如普罗克,阵列或弦等).

**注:** 何时 `:if` 条件包括符号或字符串 `changed?` 在其中或开始 `will_save_change_to`,验证器将自动强制.

```ruby
class Person < ActiveRecord::Base
  validates :name, presence: true, if: :name_changed?
end
```

在上述例子中出现名称将被验证 没有明确的强迫.

之所以这样做,是因为人们总是认为值会改变 形式.

条件定义 `:unless` 键没有此优化.

### 关闭验证器

如果您想要跳过给定属性上的验证, 它会强制到 `false`数字 :

```erb
<%= f.text_field :name, validate: false %>
```

如果您想要对关闭的校验更具有选择性, 您只需做:

```erb
<%= f.text_field :name, validate: { presence: false } %>
```

你甚至可以关闭每个字段集:

```erb
<%= f.fields_for :profile, validate: false do |p| %>
  ...
```

请注意: `pass` 也会在跳过验证的字段上进行回调 .

## 了解客户端验证数据属性

附有验证的制成形式将永远具有 `data-client-side-validations` 属性.

其包含的对象将视 `FormBuilder` 正在使用中。 不过, `html_settings` 财务报告和审定财务报表 `validators` 永远在场.

### `html_settings`

这将总是包含类型 到类 `FormBuilder` 做了渲染。 该类型将被 JavaScript 用于决定如何 `add` 财务报告和审定财务报表 `remove` 错误消息。 如果你创造了一个新的 `FormBuilder`,您需要写自己的处理器来添加和删除.

### `validators`

此对象包含每个输入的验证符 `FormBuilder`键入 `name` 属性和每个包含验证器的特性可以简单地包含错误消息本身,也可以包含关于该验证器应如何运行的具体选项.

### 添加非输入的验证符

如果您需要添加更多的验证器,但不要在表格上立即渲染,您可以给这些验证器注入 `FormBuilder#validate`数字 :

```erb
<%= form_for @user, validate: true do |f| %>
  <p>
    <%= f.label :name %>
    <%= f.text_field :name %>
  </p>
  <%= f.validate :age, :bio %>
...
```

在上述例子中 `age` 财务报告和审定财务报表 `bio` 格式上不会输入,但其验证器将适当添加到表格中 `validators` 以后使用的对象。 如果您真的想在以后动态提供这些输入 `name` 输入时的属性必须与 `validators` 对象,并且输入必须启用以进行客户端验证.

您可以添加给定对象的所有属性 没有任何传递 :

```erb
<%= f.validate %>
```

您也可以像输入语法一样强制验证器:

```erb
<%= f.validate :email, presence: false %>
```

使用这种方法要小心. 嵌入式验证器是 依据下达的命令进行覆盖。 所以,如果你这样做 比如说:

```erb
<%= f.text_field :email, validate: { presence: false } %>
<%= f.validate %>
```

这个 `presence` 校验符不会因为选项而关闭 被电话所覆盖 `FormBuilder#validate`

## 自定义出错渲染

`ClientSideValidations` 将使用 `ActiveRecord::Base.field_error_proc` 生成错误消息。 其它 `FormBuilders` 将使用自己的设置.

如果您需要更改错误的标记, 您可以在 `config/initializers/client_side_validations.rb`

_请注意_ 如果您修改了标记, 您还需要修改 `ClientSideValidations.formBuilders['ActionView::Helpers::FormBuilder']`是因为 `add` 财务报告和审定财务报表 `remove` 函数。 您可以创建名为 JavaScript 的新文件, 以覆盖行为 `rails.validations.actionView.js` 包含下列内容:

```js
window.ClientSideValidations.formBuilders['ActionView::Helpers::FormBuilder'] = {
  add: function(element, settings, message) {
    // custom add code here
  },

  remove: function(element, settings) {
    // custom remove code here
  }
}
```

请查看密码 `rails.validations.js` 以查看现有 `add` 财务报告和审定财务报表 `remove` 函数工作,以及如何最好地覆盖特定使用大小写.

## 自定义验证器

### 本地验证器

客户端验证支持使用自定义验证器. 以下为创建验证电子邮件地址格式的自定义验证符的示例 .

假设你们有多个模型,所有模型都有电子邮件字段,你们正在验证每个模型上那个电子邮件地址的格式。 这是一种常见的验证,可能从定制验证器中受益. 我们要把验证器放进去 `config/initializers/email_validator.rb`

```ruby
class EmailValidator < ActiveModel::EachValidator
  def validate_each(record, attr_name, value)
    unless value =~ /^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
      record.errors.add(attr_name, :email, options.merge(value: value))
    end
  end
end

# This allows us to assign the validator in the model
module ActiveModel::Validations::HelperMethods
  def validates_email(*attr_names)
    validates_with EmailValidator, _merge_attributes(attr_names)
  end
end
```

注意! 准备! 安装自定义的初始化器 `config/initializers`,以其他方式命名的验证器助手不会 移民不会成功.

接下来我们需要将错误消息添加到 Rails i18n 文件 `config/locales/en.yml`

```yaml
# config/locales/en.yml
en:
  errors:
    messages:
      email: "Not an email address"
```

最后我们需要添加客户端验证器. 这可以通过钩入 `ClientSideValidations.validator` 对象。 创建新文件 `app/assets/javascripts/rails.validations.customValidators.js`

```js
// The options variable is a JSON Object
// The element variable is a DOM element
window.ClientSideValidations.validators.local.email = function (element, options) {
  // Your validator code goes in here
  if (!/^([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i.test(element.value)) {
    // When the value fails to pass validation you need to return the error message.
    // It can be derived from validator.message
    return options.message
  }
}
```

就这样! 现在您可以使用自定义验证器, 就像您模式中任何其他验证器一样

```ruby
# app/models/person.rb
class Person < ActiveRecord::Base
  validates_email :email
end
```

客户端验证将应用新的验证符,并根据需要验证您的表格 .

## 对客户端进行启用、禁用和重置

您可能想要启用、 禁用甚至完全重置客户端上绑定的验证事件, 原因很多 . `ClientSideValidations` 提供简单的API.

### 启用

如果您已经通过 AJAX 将新的表格输入您的页面, 您需要启用该表格进行校验 :

```js
ClientSideValidations.enable(newForm)
```

您应该将此附加到新 HTML 生成时被发射的事件中 .

如果对现有窗体引入新输入, 您可以使用相同的函数 :

```js
ClientSideValidations.enable(newInput)
```

### 残疾

如果您想要完全用表格关闭验证:

```js
ClientSideValidations.disable(form)
```

### 重设

您可以重置当前验证状态, 清除所有错误消息, 并重接干净事件处理器 :

```js
ClientSideValidations.reset(form)
```

## 回电

`ClientSideValidations` 将根据元素或窗体的状态运行回调。 支持下列回调:

-   `ClientSideValidations.callbacks.element.after(element, eventData)`
-   `ClientSideValidations.callbacks.element.before(element, eventData)`
-   `ClientSideValidations.callbacks.element.fail(element, message, callback, eventData)`
-   `ClientSideValidations.callbacks.element.pass(element, callback, eventData)`
-   `ClientSideValidations.callbacks.form.after(form, eventData)`
-   `ClientSideValidations.callbacks.form.before(form, eventData)`
-   `ClientSideValidations.callbacks.form.fail(form, eventData)`
-   `ClientSideValidations.callbacks.form.pass(form, eventData)`

召回的名字应该很直接 譬如说, `ClientSideValidations.callbacks.form.fail` 如果一个表单无法验证,则将调用。 还有 `ClientSideValidations.callbacks.element.before` 将在该特定元素的验证运行前调用.

所有元素回调都接收了DOM元素作为第一个参数,本地事件对象作为第二个参数. `ClientSideValidations.callbacks.element.fail()` 接收失败消息作为第二个参数,将错误字段添加为第三个参数的回调,将事件Data对象添加为第四个参数. `ClientSideValidations.callbacks.element.pass()` 接收去除错误字段的回调,作为第二个参数。 错误字段回调仍然必须被您的自定义回调引用 .

所有形式回调都会收到DOM形式元素作为第一个参数,而原生事件对象作为第二个参数.

以下是在验证失败时给错误消息做动画的回调示例 :

```javascript
window.ClientSideValidations.callbacks.element.fail = function (element, message, callback) {
  callback()

  var messageElement = element.parentElement.querySelector('.message')

  if (messageElement) {
    if (typeof messageElement.animate === 'function') {
      messageElement.animate(
        [
          { opacity: 0, transform: 'translateX(-8px)' },
          { opacity: 1, transform: 'translateX(0)' }
        ],
        { duration: 250, easing: 'ease-out', fill: 'both' }
      )
    } else {
      messageElement.style.opacity = '1'
      messageElement.style.transform = 'translateX(0)'
    }
  }
}

window.ClientSideValidations.callbacks.element.pass = function (element, callback) {
  callback()
}
```

```css
.message {
  background-color: red;
  border-bottom-right-radius: 5px 5px;
  border-top-right-radius: 5px 5px;
  display: inline-block;
  padding: 2px 5px;
}
```

最后,没有评论 `ActionView::Base.field_error_proc` 覆盖于 `config/initializers/client_side_validations.rb`

## 禁用验证符

如果您想要禁用一些验证器, 请设置 `disabled_validators` 配置变量在 `config/initializers/client_side_validations.rb`数字 :

```ruby
# Example: disable the presence validator
ClientSideValidations::Config.disabled_validators = [:presence]
```

注意 `FormBuilder` 将自动跳过已禁用的构建验证符.

## 手动验证

默认情况下,客户端SideValidations会自动验证表格.

如果您出于某种原因想要手动验证表格(例如您正在用多步形式工作),可以使用以下方法:

```js
const input = document.getElementById('myInputField')
const form = input.form
const validators = form.ClientSideValidations.settings.validators

// Validate a single field
ClientSideValidations.isValid(input, validators)

// Validate the whole form
ClientSideValidations.isValid(form, validators)
```

要手动验证一个字段, 您也可能触发一个聚焦事件 :

```js
input.dispatchEvent(new Event('focusout', { bubbles: true }))
```

## 作者数

[布莱恩·卡达雷拉](https://twitter.com/bcardarella)

[格列米亚·塔利亚拉特拉](https://twitter.com/gtagliala)

[我们非常感谢许多捐助者](https://github.com/DavyJonesLocker/client_side_validations/graphs/contributors)

## 版本

这颗宝石紧随其后 [语义版本](https://semver.org/)

## 想帮忙吗?

请吧! 我们一直想改进这颗宝石 请看我们的 [贡献准则](https://github.com/DavyJonesLocker/client_side_validations/blob/main/CONTRIBUTING.md) 关于如何妥善提交问题和处理请求.

## 法律

[码头](https://dockyard.com/)2012-2024年,专卖局长

[@dockyard (英语)](https://twitter.com/dockyard)

[获得麻省理工学院许可证](https://opensource.org/licenses/mit)

## 常见问题

### @client-side-validations/client-side-validations 是什么？

客户端验证方便您的铁路 7\.2 和 8\.x 应用程序

### 如何安装 @client-side-validations/client-side-validations？

在项目目录运行 npm install @client-side-validations/client-side-validations，或使用 pnpm add / yarn add / bun add。

### @client-side-validations/client-side-validations 支持 TypeScript 吗？

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

### @client-side-validations/client-side-validations 支持 ESM 还是 CommonJS？

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

### @client-side-validations/client-side-validations 需要什么版本的 Node\.js？

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

### @client-side-validations/client-side-validations 可以商用吗？

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

### @client-side-validations/client-side-validations 的下载量有多少？

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

### @client-side-validations/client-side-validations 还在维护吗？

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