bh的三个特色字段：phone_field实时格式化、price与percentage输入组详解

• UI库/组件

bh（Bootstrap Helpers）是面向 Rails 的 Bootstrap 6 表单助手 gem，它替你写好全部 HTML，视图里只剩一行 Ruby。本文带你一次看懂它的三个特色字段：phone_field的实时格式化，以及price_field、percentage_field这类把单位写进边框的输入组 📞💰📊

一分钟接入 bh 表单助手

先说结论：装好 gem、在布局里挂上样式表和脚本、给控制器指定构建器，三个字段立刻可用。

# 控制器里指定默认表单构建器 class ApplicationController < ActionController::Base default_form_builder Bh::FormBuilder end

布局中通过Bh::Engine::PREFIX引入/bh/css/bh.css和/bh/js/bh.js即可，样式与脚本都由引擎自己分发，详见 lib/engine.rb。

phone_field 电话字段：边输入边格式化

phone_field处理北美电话（NANP）：用户敲入5555555555，页面里立刻变成555-555-5555。

<%= form.phone_field :phone, class: 'text-center' %>

它的工作原理是「服务器只交数字，形状交给浏览器」：

• 服务器渲染出的输入框只带 10 位裸数字和data-controller="phone"，所有格式规则集中在 app/javascript/bh/phone_controller.js 这一个 Stimulus 控制器里，想换成(555) 555-5555只需改 JS，不碰 Ruby。
• 控制器写死了合法形状pattern="[2-9]\d{2}-[2-9]\d{2}-\d{4}"（区号和交换码不能以 0/1 开头，见 phone_controller.js#L10-L11），并顺手补上inputmode="numeric"，移动端直接弹出数字键盘。
• 只进数字：keydown会直接拒绝非数字键；满 10 位后第 11 位按键被当场拦下，保证旁观的校验器永远先看到合法形态。
• 粘贴、自动填充也重排：整串进入的值会被重新整形，并再发一次input事件。
• 带 +1 的国家码也能收：11 位且以 1 开头时，自动剥掉前导 1，只留 10 位号码。
• 校验失败重绘页面后照样带分隔符：connect时会对已有值再格式化一遍，表单不会因为服务端退回裸数字而露馅。

placeholder 里的555-555-5555取自语言文件 config/locales/bh.en.yml#L12——号码怎么写是读者语言的事，不硬编码进 gem。字段默认携带autocomplete="tel"与aria-label，视图显式传入的class、autocomplete、data都会原样保留，见 lib/bh/form_builder.rb#L62-L66。

price_field 金额输入组：货币符号写进边框

price_field渲染的是 Bootstrap 的 adorned（附饰）控件：货币符号是一个span，和数字输入框共处同一个边框内——边框和内边距属于外层包裹，内部输入框戴form-ghost类，自己不描边不占位。

<%= form.price_field :fee %> # 渲染出：<div class="form-control form-adorn d-flex"> # <span class="form-adorn-text">$</span> # <input class="form-ghost" type="number" min="0" step="0.01" ...> # </div>

默认规则很克制：min: 0、step: 0.01（美分级），调用方知道列的精度时可以传step:覆盖。货币符号读 I18n 的number.currency.format.unit，缺省$；把语言文件的 unit 设成¥，字段就跟着变 ¥，逻辑见 lib/bh/form_builder/adornments.rb#L16-L35。

percentage_field 百分比输入组：百分号跟随数字

percentage_field与金额字段共用同一套附饰结构，只有一处不同：%是后缀而不是前缀。外层多一个form-adorn-end类，CSS 里让数字输入框排在符号前面，所以视觉上永远是「数字 + %」，符合人读百分数的习惯。

<%= form.percentage_field :rate %> # 渲染出：<div class="form-control form-adorn d-flex form-adorn-end"> # <span class="form-adorn-text">%</span> # <input class="form-ghost" type="number" ...> # </div>

它没有预设min/step，默认就是普通数字输入框，调用方按需补充。完整渲染断言可以参考 test/test_bh_forms.rb#L32-L39。

三个字段一页跑起来：本地演示步骤

gem 自带一个「每个组件只画一次」的演示应用，三个字段全部在同一个表单里（fee、rate、phone，见 test/dummy/app/views/pages/show.html.erb#L22-L29）。克隆仓库后即可启动：

git clone https://gitcode.com/gh_mirrors/bh/bh cd bh && bin/setup && rails s

打开localhost:3000，就能看到全部组件同屏渲染，?flash=1还能追加 toast 提示。

小结：什么时候用哪个字段

• 收电话号码 →phone_field，格式化、键盘、校验提示一站配齐，改形状只动 JS；
• 收金额 →price_field，货币符号来自 I18n，换语言文件就换币种；
• 收百分比 →percentage_field，%恒在数字之后。

三者都由 lib/bh/form_builder.rb 统一「着装」：视图只声明字段种类，外观、无障碍标签、浏览器提示全部由构建器负责，这正是 bh「一行 Ruby，零 markup」的核心理念 ✨

• UI库/组件