bh的16个标准字段方法完整清单:从email_field到datetime_field逐个讲透
bh的16个标准字段方法完整清单:从email_field到datetime_field逐个讲透
bh(Bootstrap Helpers)是一个为 Rails 应用"预先写好 Bootstrap 6 标记"的表单构建器,提供一套开箱即用的标准字段方法——从 email_field 到 datetime_field 共 16 个。视图里只需写清楚"要什么字段",Bootstrap 类名、尺寸、aria 无障碍属性、浏览器自动填充行为全部由它代劳,一行 CSS 都不用手动写。
先认识 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 的全部成品。
小结
- 16 个标准字段方法覆盖了绝大多数表单场景,核心收益就三条:统一尺寸、自带无障碍、浏览器自动填充
- 页面只说"要什么字段",Bootstrap 类名全部由构建器代写
- 想更进一步,
price_field、pin_field、combobox这些"标准之外"的字段能解决金额、验证码、搜索下拉三个高频痛点 - 行为细节都可以对照 test/test_bh_forms.rb 里的断言,每个字段输出的 HTML 都有测试背书

