客户端参数
ClientSideValidations 方便你的铁路7.2和8.x应用!
项目目标
- 遵循客户端验证的最佳做法 卢克·沃布列斯基
- 自动提取并应用定义的验证规则 服务器到客户端.
- 如果服务器侧验证规则无法执行 客户端( 即有条件的回调, 如: if, : 除非) 然后不 尝试客户端验证。 倒回服务器侧 审定.
- 客户端验证错误渲染应为 无法与服务器侧验证错误渲染区分 .
- 宽浏览器兼容性.
- 使用任何活动模式:基于参数的模式
- 验证嵌入地
- 支持自定义验证
- 客户端验证回调
- 支持额外窗体构建器, ORMS 等的插件系统...
安装
在您的 Gemfile 中添加以下行 :
gem 'client_side_validations'
然后运行 bundle install
请跑 spring stop 如果您正在使用 春节
您接下来需要运行生成器 :
rails g client_side_validations:install
这将安装初始化 :
config/initializers/client_side_validations.rb
Java 脚本文件
指令取决于您的技术堆栈 .
客户端测试不再依赖于jQuery.
如果您以前安装过 jquery-rails, (中文(简体) ), jquery_ujs,或只为客户端SideValidations自定义 jQuery 启动代码,在升级到24.x时可以去除该集成.
使用 Web 包装器时
添加以下软件包:
yarn add @client-side-validations/client-side-validations
然后在您的 app/javascript/packs/application.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')
涡轮和涡轮链接用户的提醒
使用时 涡轮,使用
import 语法和确保 @client-side-validations/client-side-validations
导入 之后 @hotwired/turbo-rails,因此,客户端参数可以正确检测
window.Turbo 并附上它的事务处理者.
使用时 涡轮链接 5.2, (韩语),
使用该 require 语法和确保 @client-side-validations/client-side-validations
需要时间 之后 Turbolinks.start(),因此客户端参数可以正确
检测 window.Turbolinks 并附上它的事务处理者.
使用螺旋桨时
在您的 app/assets/javascripts/application.js 文件 :
//= require rails.validations
使用时 涡轮链接, (中文(简体) ),
确保 rails.validations 需要时间 之后 turbolinks这样
客户端SideValidation可以适当附加其事件处理器.
如果您需要将资产文件从宝石复制到您的项目中, 请运行 :
rails g client_side_validations:copy_assets
注:如果运行 copy_assets,您每次更新此项目时都需要再次运行.
移徙指南
24.x 打破变化
如果您正在升级到24x,请更新您的集成代码以使用 ClientSideValidations 对象直接.
已删除旧的 j 查询插件方法 。 使用 DOM- 第一公开 API 代替 :
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。如果您在自定义选择器、召回器或验证器中读取或写入这些属性,则将其更新到范围名称:
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 风格的命名间隔来收听或解封事件, 您必须更新这些调用 .
在此之前:
$(form).on('form:validate:before.ClientSideValidations', handler)
$(input).off('.ClientSideValidations')
之后:
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请参看 插件维基页面
(自由加入你自己)
使用量
在你身边 FormBuilder 您只需要启用验证 :
<%= form_for @user, validate: true do |f| %>
...
这应该足够让你走.
从14.0版本开始,客户端参数也支持 form_with。 。 。 .
语法与 form_for数字 :
<%= form_with model: @user, validate: true do |f| %>
...
说明: 客户端参数要求 id 窗体字段的属性
工作,所以它会强迫 form_with 生成 id.
验证器命令
默认情况下, ClientSideValidations 会按相同的顺序进行验证 在模型中指定。 换句话说, 如果您想要验证格式 在电子邮件字段存在前,您可以使用以下内容:
class User < ApplicationRecord
validates :email, format: { with: /\A[^@\s]+@[^@\s]+\z/ }, presence: true
end
有条件验证器
默认情况下,有条件的验证者不进行评估并传递给客户端. 我们这样做是因为 制表时的状态模型 不一定是状态 ,用于验证服务器侧的模型。 但是,如果你想推翻这种行为,你可以这样做 在形式。 鉴于以下模式:
class Person < ActiveRecord::Base
validates :name, presence: true, length: { maximum: 10 }, if: :can_validate?
def can_validate?
true
end
end
您可以强制形式:
<%= f.text_field :name, validate: true %>
通过 validate: true 将强制所有验证者执行此属性。 如果有条件
在制作表格时,将按模型的状态对其进行评估。 你也可以强迫
单个验证符 :
<%= f.text_field :name, validate: { presence: true } %>
在上述情况下 presence 验证器将传递给客户端.
情况也是如此 其他支持的有条件验证 (如普罗克,阵列或弦等).
注: 何时 :if 条件包括符号或字符串
changed? 在其中或开始 will_save_change_to,验证器将自动强制.
class Person < ActiveRecord::Base
validates :name, presence: true, if: :name_changed?
end
在上述例子中出现名称将被验证 没有明确的强迫.
之所以这样做,是因为人们总是认为值会改变 形式.
条件定义 :unless 键没有此优化.
关闭验证器
如果您想要跳过给定属性上的验证, 它会强制到 false数字 :
<%= f.text_field :name, validate: false %>
如果您想要对关闭的校验更具有选择性, 您只需做:
<%= f.text_field :name, validate: { presence: false } %>
你甚至可以关闭每个字段集:
<%= 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数字 :
<%= 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 对象,并且输入必须启用以进行客户端验证.
您可以添加给定对象的所有属性 没有任何传递 :
<%= f.validate %>
您也可以像输入语法一样强制验证器:
<%= f.validate :email, presence: false %>
使用这种方法要小心. 嵌入式验证器是 依据下达的命令进行覆盖。 所以,如果你这样做 比如说:
<%= 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 包含下列内容:
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
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
# config/locales/en.yml
en:
errors:
messages:
email: "Not an email address"
最后我们需要添加客户端验证器. 这可以通过钩入 ClientSideValidations.validator 对象。 创建新文件 app/assets/javascripts/rails.validations.customValidators.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
}
}
就这样! 现在您可以使用自定义验证器, 就像您模式中任何其他验证器一样
# app/models/person.rb
class Person < ActiveRecord::Base
validates_email :email
end
客户端验证将应用新的验证符,并根据需要验证您的表格 .
对客户端进行启用、禁用和重置
您可能想要启用、 禁用甚至完全重置客户端上绑定的验证事件, 原因很多 . ClientSideValidations 提供简单的API.
启用
如果您已经通过 AJAX 将新的表格输入您的页面, 您需要启用该表格进行校验 :
ClientSideValidations.enable(newForm)
您应该将此附加到新 HTML 生成时被发射的事件中 .
如果对现有窗体引入新输入, 您可以使用相同的函数 :
ClientSideValidations.enable(newInput)
残疾
如果您想要完全用表格关闭验证:
ClientSideValidations.disable(form)
重设
您可以重置当前验证状态, 清除所有错误消息, 并重接干净事件处理器 :
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形式元素作为第一个参数,而原生事件对象作为第二个参数.
以下是在验证失败时给错误消息做动画的回调示例 :
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()
}
.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数字 :
# Example: disable the presence validator
ClientSideValidations::Config.disabled_validators = [:presence]
注意 FormBuilder 将自动跳过已禁用的构建验证符.
手动验证
默认情况下,客户端SideValidations会自动验证表格.
如果您出于某种原因想要手动验证表格(例如您正在用多步形式工作),可以使用以下方法:
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)
要手动验证一个字段, 您也可能触发一个聚焦事件 :
input.dispatchEvent(new Event('focusout', { bubbles: true }))
作者数
版本
这颗宝石紧随其后 语义版本
想帮忙吗?
请吧! 我们一直想改进这颗宝石 请看我们的 贡献准则 关于如何妥善提交问题和处理请求.
法律
码头2012-2024年,专卖局长