HTML5Validators 技术文档

HTML5Validators 是一个用于 Rails 3+ 的 gem/插件，它能够通过 ActiveModel 和 HTML5 实现自动的客户端表单验证。本文将详细介绍如何安装、使用以及配置 HTML5Validators，帮助开发者更好地理解和使用该项目。

1. 安装指南

1.1 安装步骤

要在你的 Rails 项目中使用 HTML5Validators，首先需要在 Gemfile 中添加以下内容：

gem 'html5_validators'

然后运行以下命令来安装 gem：

bundle install

安装完成后，HTML5Validators 将自动集成到你的 Rails 应用中，并开始为表单提供客户端验证功能。

2. 项目的使用说明

2.1 自动客户端验证

HTML5Validators 会自动将你的模型验证代码转换为 HTML5 验证属性，并在每次调用 form_for 时应用这些属性。以下是一些常见的验证示例：

2.1.1 必填字段验证（PresenceValidator）

在模型中定义必填字段：

class User
  include ActiveModel::Validations
  validates_presence_of :name
end

在视图中使用 text_field 或其他类似的表单助手：

<%= f.text_field :name %>

生成的 HTML 将包含 required 属性：

<input id="user_name" name="user[name]" required="required" type="text" />

2.1.2 长度验证（LengthValidator）

在模型中定义字段的最大长度：

class User
  include ActiveModel::Validations
  validates_length_of :name, maximum: 10
end

在视图中使用 text_field 或 text_area：

<%= f.text_field :name %>

生成的 HTML 将包含 maxlength 属性：

<input id="user_name" maxlength="10" name="user[name]" size="10" type="text" />

2.1.3 数值验证（NumericalityValidator）

在模型中定义数值范围：

class User
  include ActiveModel::Validations
  validates_numericality_of :age, greater_than_or_equal_to: 20
end

在视图中使用 number_field：

<%= f.number_field :age %>

生成的 HTML 将包含 min 属性：

<input id="user_age" min="20" name="user[age]" size="30" type="number" />

2.2 禁用自动客户端验证

在某些情况下，你可能希望禁用自动的客户端验证。HTML5Validators 提供了四种方式来取消自动验证：

2.2.1 针对单个表单禁用

在 form_for 中设置 auto_html5_validation: false：

<%= form_for @user, auto_html5_validation: false do |f| %>
  ...
<% end %>

2.2.2 针对单个模型实例禁用

在控制器中设置 auto_html5_validation = false：

@user = User.new auto_html5_validation: false

2.2.3 针对整个模型类禁用

在模型中设置 auto_html5_validation = false：

class User < ActiveRecord::Base
  self.auto_html5_validation = false
end

2.2.4 全局禁用

在 Html5Validators 模块中设置 config.enabled = false：

Html5Validators.enabled = false

3. 项目 API 使用文档

HTML5Validators 的主要功能是通过 ActiveModel 的验证规则自动生成 HTML5 验证属性。以下是一些常用的 API 示例：

3.1 validates_presence_of

用于验证字段是否为空：

validates_presence_of :name

生成的 HTML 属性为 required="required"。

3.2 validates_length_of

用于验证字段的长度：

validates_length_of :name, maximum: 10

生成的 HTML 属性为 maxlength="10"。

3.3 validates_numericality_of

用于验证字段的数值范围：

validates_numericality_of :age, greater_than_or_equal_to: 20

生成的 HTML 属性为 min="20"。

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Gemfile 中添加以下内容：

gem 'html5_validators'

然后运行 bundle install 完成安装。

4.2 支持的版本

HTML5Validators 支持以下 Ruby 和 Rails 版本：

• Ruby: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3
• Rails: 3.2.x, 4.0.x, 4.1, 4.2, 5.0, 5.1, 5.2, 6.0, 6.1, 7.0, 7.1

4.3 注意事项

当使用不支持 HTML5 的旧版浏览器时，这些额外的验证属性将被忽略。

总结

HTML5Validators 是一个强大的工具，能够帮助开发者轻松实现客户端表单验证。通过本文的指南，你应该能够顺利安装、配置和使用该 gem，并在你的 Rails 项目中应用 HTML5 表单验证功能。