bh的16个标准字段方法完整清单:从email_field到datetime_field逐个讲透

原创2026-10-25 15:44:161,999 阅读
文章标签:UI库/组件

bh的16个标准字段方法完整清单:从email_field到datetime_field逐个讲透

bh(Bootstrap Helpers)是一个为 Rails 应用"预先写好 Bootstrap 6 标记"的表单构建器,提供一套开箱即用的标准字段方法——从 email_field 到 datetime_field 共 16 个。视图里只需写清楚"要什么字段",Bootstrap 类名、尺寸、aria 无障碍属性、浏览器自动填充行为全部由它代劳,一行 CSS 都不用手动写。

bh 项目主页:Bootstrap 表单字段方法与组件一览

先认识 bh:谁替你写 Bootstrap HTML

Bootstrap 是个好框架,但代价是再简单的组件也要手写一大段 HTML:弹窗要写开关按钮、Esc 关闭、给读屏器的提示……bh 的思路是把这一切收进一个表单构建器 lib/bh/form_builder.rb:

  • 统一尺寸:每个字段自动穿上 form-control form-control-lg 两个类,手指一摸就够大(见 lib/bh/form_builder.rb 的 CONTROL 常量)
  • 自带无障碍:没有标签的字段会补上 aria-label,页面上自带的 aria 选项优先(dressed 方法,lib/bh/form_builder.rb)
  • 不覆盖你的定制:视图传入的 class 会与构建器的类合并、data 按键合并,其余选项以页面为准

所以视图代码可以干净到只表达意图:

<%= form.email_field :email %>
<%= form.datetime_field :moment %>

30 秒启用步骤

在 Gemfile 中加入:

gem 'bh', '~> 6.9.0'

然后在应用控制器里指定默认构建器,所有表单立即生效:

class ApplicationController < ActionController::Base
  default_form_builder Bh::FormBuilder
end

16 个标准字段方法完整清单

# 方法 画出的控件 源码位置
1 text_field 文本框 form_builder.rb
2 email_field 邮箱字段,autocomplete="email" controls.rb
3 number_field 数字字段,唤起数字键盘 controls.rb
4 password_field 密码框 controls.rb
5 search_field 搜索框 controls.rb
6 url_field 网址字段,autocomplete="url" controls.rb
7 date_field 日期选择 controls.rb
8 time_field 时间选择 controls.rb
9 datetime_field 日期+时间组合 controls.rb
10 text_area 多行文本域 controls.rb
11 file_field 文件上传 form_builder.rb
12 select 下拉菜单 controls.rb
13 check_box 复选框 controls.rb
14 radio_button 单选按钮 controls.rb
15 check 复选框+文案(可带说明行) controls.rb
16 phone_field 电话号码,边输边格式化 form_builder.rb

逐个讲透 📋

基础输入五件套:text_field 到 search_field

这一组是最常用的单行输入,行为上各带一点"浏览器懂"的增强:

  • text_field:普通的文本框,画成大号控件(form-control-lg),是所有字段的基准样式
  • email_field:邮箱字段。除统一类名外,自动补 autocomplete: 'email'——浏览器会主动提供用户保存过的那个邮箱,填表体验直接起飞(controls.rb)
  • url_field:网址字段,同样的 autocomplete: 'url' 待遇,浏览器会把存过的地址递给你
  • password_field:密码框。注释写得很直白——"没有任何一列的列名值得天生是密码框",必须显式调用
  • search_field:搜索词输入框,类型上就是给搜索用的
  • number_field:数字字段,移动端会唤起数字键盘

日期时间三兄弟 📅:date_field、time_field、datetime_field

  • date_field:一个日期
  • time_field:一个时刻
  • datetime_field:日期加时刻的组合框,对应"下单时间""预约时刻"这类最常见的场景

三者都按同一尺寸画出,与表单里其他字段视觉上完全对齐。

多行与文件:text_area、file_field

  • text_area:多行文字,同样穿上大号控件的类名
  • file_field:文件上传。Rails 原生给这个控件是"素颜"的,bh 把它也拉进统一尺寸,避免上传框和旁边字段大小不一(form_builder.rb)

选择与勾选:select、check_box、radio_button、check

  • select:下拉菜单,aria-label 和类名齐活
  • check_box:单个复选框,穿上 check 类由 Bootstrap 绘制
  • radio_button:单选按钮,穿上 radio 类
  • check:bh 自己造的组合件——"复选框 + 旁边的文案"。这是唯一文字写在控件右侧而不是上边的场景,所以它不是普通 label。还支持 description: 选项,在文案下方加一行小字说明(controls.rb):
<%= form.check :insured, 'Insured', description: 'A gumball is not a hat.' %>

特殊项:phone_field 📱

phone_field 是 16 个标准方法里唯一带交互的:它挂上了包内的 phone Stimulus 控制器,北美号码在输入过程中就自动成形为 555-555-5555,placeholder 也从 config/locales/bh.en.yml 的词条读取,跟着读者的语言走(form_builder.rb)。

加分项:4 个"标准之外"的字段

这 16 个是"Rails 本来就有、bh 重新打扮"的字段;而下面 4 个是 Rails 没有、bh 额外补上的,值得顺带认识:

方法 效果 源码
price_field 金额:$ 和单位画在边框内部 adornments.rb
percentage_field 百分比:% 跟在数字后面 adornments.rb
pin_field 6 位验证码:一个真实字段画成 6 个槽位 pins.rb
combobox 可搜索的下拉菜单,提交的仍是一个 <select> comboboxes.rb

去示例页看看全部效果 👀

gem 自带一个 dummy 应用,把每个助手在一个页面上各画了一次,见 test/dummy/app/views/pages/show.html.erb。在仓库根目录执行 bin/setup 后 rails s,打开 localhost:3000 就能同时看到 email_field 到 pin_field 的全部成品。

bh Bootstrap 表单字段方法:九大配色主题与组件社交横幅

小结

  • 16 个标准字段方法覆盖了绝大多数表单场景,核心收益就三条:统一尺寸、自带无障碍、浏览器自动填充
  • 页面只说"要什么字段",Bootstrap 类名全部由构建器代写
  • 想更进一步,price_field、pin_field、combobox 这些"标准之外"的字段能解决金额、验证码、搜索下拉三个高频痛点
  • 行为细节都可以对照 test/test_bh_forms.rb 里的断言,每个字段输出的 HTML 都有测试背书
登录后查看全文
bh