5分钟上手bh：Rails应用中打造Bootstrap 6表单的快速开始教程

bh（Bootstrap Helpers）是一个专为 Ruby on Rails 打造的 Bootstrap 6 辅助工具库：它用一个表单构建器自动"穿好"所有字段的 Bootstrap 样式，再附带下拉搜索框（combobox）、6位验证码输入、对话框、Toast 提示、聊天气泡等现成组件。装上 bh，你基本不用再手写 Bootstrap 的 HTML 标记。本文带你用5分钟完成安装、接入和常用组件速览。

一键安装：只需3行代码

bh 支持 Ruby 3.2+ 和较新的 Rails 版本。在项目根目录打开 Gemfile，加入：

gem 'bh', '~> 6.9.0'

然后在终端执行 bundle install 即可。官方提示当前大版本仍在快速演进，建议用 ~> 锁住次版本号，而不是直接写 ~> 6。

装好后，Rails Engine 会自动托管静态文件：浏览器请求 /bh/css/bh.css 和 /bh/js/bh.js 时，gem 自己就会把样式和脚本端出来（前缀定义见 engine.rb）。

最快接入布局：在 Layout 里引入样式与脚本

打开你的布局文件，把这两行放进 <head>：

<link rel='stylesheet' href='<%= Bh::Engine::PREFIX %>css/bh.css'>
<script type='module' src='<%= Bh::Engine::PREFIX %>js/bh.js'></script>

一行样式 + 一个脚本，Bootstrap 6 的全部组件（内含 22 个 Stimulus 控制器）都打包在这对文件里，无需 CDN。

核心一步：把 Bh::FormBuilder 设为默认表单构建器

这是 bh 的灵魂。打开 application_controller.rb，加上：

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

从此视图里写的 email_field、number_field 等都会自动穿上 form-control form-control-lg 的"大衣"，视图只说"要哪种字段"，不必关心样式细节。实现见 form_builder.rb。

常用字段速览：一行 Ruby 对应一个 Bootstrap 控件

下面这段代码来自官方演示页 show.html.erb，几乎展示了 builder 的全部本事：

<%= form_with url: '/verify', scope: :contact do |form| %>
  <%= form.pin_field :pin_confirmation, required: true %>
  <%= form.label :email, 'Email' do %><%= form.email_field :email %><% end %>
  <%= form.number_field :size %>
  <%= form.password_field :secret %>
  <%= form.text_area :notes %>
  <%= form.price_field :fee %>
  <%= form.percentage_field :rate %>
  <%= form.select :state, %w[California Oregon] %>
  <%= form.combobox :county, %w[Alameda Marin], { prompt: 'Pick a county' }, multiple: true %>
  <%= form.check :agreed, 'I agree to the terms' %>
  <%= form.phone_field :phone %>
  <%= form.submit 'Confirm' %>
<% end %>

几个亮点：

• fieldset / label / submit：表单骨架全部自动排版，label 还能包住控件变成单一元素；
• phone_field：边打字边把号码塑造成 555-555-5555 的格式；
• price_field / percentage_field：金额和百分比自带 Bootstrap 装饰控件，货币符号直接"长"在边框里（见 adornments.rb）；
• check 可带 description:：复选框下方多一行解释文字。

两个 Rails 没有的字段：combobox 与 pin_field

combobox 把一个 <select> 画成可搜索的下拉菜单，但提交时仍是表单里唯一的下拉框，兼容性和无障碍都保留得很好（源码见 comboboxes.rb）。菜单里的"搜索""清空""无结果"等文案来自 bh.en.yml，可本地化。

pin_field 则用一个真实输入框渲染出6格 OTP 验证码输入，校验失败时格子自动标红，移动端弹出数字键盘（源码见 pins.rb）。

彩蛋：9套配色主题一键切换

bh 还内置9套调色板，分别托管在 /bh/theme/<name>.css：bootstrap、dawn、dracula、gruvbox、monokai、nord、one_dark、solarized、tokyo_night。文件都在 app/stylesheets/bh/theme/ 下，每次只引入一套。配合 scheme 控制器写一个"换一套配色"按钮，用户点一下就能换肤，且偏好会记住。

下一步：去哪里看全部组件

• 本地试跑：仓库自带一个演示应用，克隆后执行 bin/setup 再 rails s，打开 localhost:3000 即可一页看到全部组件，加 ?flash=1 还能看到 Toast 效果；
• 更多助手：dialog 对话框、toasts 把 flash 变成 Toast、chat_with 聊天气泡、confirm_button_to 先确认再提交的按钮，源码集中在 lib/bh/helpers/；
• 更新日志：CHANGELOG.md 记录每个版本的变化；
• 相关测试：可以翻翻 test/dummy/app/ 下的演示控制器与视图，每个助手都有一行真实用法。

5分钟到了——安装、布局、builder 三步走完，你的 Rails 应用里所有表单都已经是 Bootstrap 6 的正规军了。🎉