BOOTSTRA.386 5.3.1 组件配置指南:data-bs- 数据属性与 data-bs-config 合并优先级详解
BOOTSTRA.386 5.3.1 组件配置指南:data-bs- 数据属性与 data-bs-config 合并优先级详解
本文以 BOOTSTRA.386 仓库所承载的 Bootstrap 5.3.1 文档片段 js-data-attributes.md 为核心,系统讲解通过 data-bs-* 数据属性配置 Bootstrap 组件的完整规则:camelCase 到 kebab-case 的命名转换、属性值类型自动规范化、实验性 data-bs-config 批量配置,以及"默认值 / data-bs-config / 单独数据属性 / JS 对象"四层配置的合并优先级。读完本文,你将能仅凭 HTML 属性完成 Tooltip、Popover、Modal 等组件的精细配置,并理解其底层解析与合并的实现原理。
该文档片段并非孤立存在,而是被 10 个官方文档页面以 {{< partial "js-data-attributes.md" >}} 的方式内嵌引用,包括 getting-started/javascript.md 以及 Carousel、Collapse、Dropdown、Modal、Offcanvas、Popover、Scrollspy、Toast、Tooltip 等组件文档页,因此它实际上是"如何用 HTML 配置所有 JS 组件"的通用规范。
一、核心规则:选项经 data-bs- 前缀传入,camelCase 转 kebab-case
Bootstrap 的所有 JS 插件都可以通过数据属性直接启用与配置,文档明确指出:
由于选项既可以通过数据属性传入,也可以通过 JavaScript 传入,因此可以将选项名追加到
data-bs-之后,例如data-bs-animation="{value}"。当通过数据属性传参时,务必把选项名的大小写从_camelCase_改为_kebab-case_。例如,应该使用data-bs-custom-class="beautifier",而不是data-bs-customClass="beautifier"。
这条命名规则在源码中有直接对应实现。查看 dom/manipulator.js 中的 normalizeDataKey:
function normalizeDataKey(key) {
return key.replace(/[A-Z]/g, chr => `-${chr.toLowerCase()}`)
}
当代码内部以 camelCase 形式(如 customClass、fallbackPlacements)读写选项时,会通过该函数把大写字母转成 -小写 的 kebab-case 形态,从而与 HTML 属性名对齐。同时,反向的 getDataAttributes 在读取 DOM 时会做一次"去 bs 前缀 + 首字母小写"的还原(见 manipulator.js),例如 data-bs-custom-class 会被还原为配置键 customClass。
常见映射示例
| 组件配置项(camelCase) | HTML 数据属性(kebab-case) |
|---|---|
animation |
data-bs-animation |
customClass |
data-bs-custom-class |
fallbackPlacements |
data-bs-fallback-placements |
popperConfig |
data-bs-popper-config |
show(Modal 触发) |
data-bs-show |
toggle / target |
data-bs-toggle / data-bs-target |
其中 data-bs-toggle、data-bs-target、data-bs-dismiss、data-bs-slide 等属于"启用型"属性,在各组件源码中以选择器常量形式被直接查询,例如 carousel.js 中的 SELECTOR_DATA_SLIDE 与 SELECTOR_DATA_RIDE、collapse.js 中的 SELECTOR_DATA_TOGGLE,以及 util/component-functions.js 中对 [data-bs-dismiss="${name}"] 的全局事件委托。
二、属性值类型自动规范化:布尔、数字、null 与 JSON
除命名转换外,getDataAttributes 读取的每个值都会经过 manipulator.js 中的 normalizeData 处理。由于 HTML 属性本质上都是字符串,该函数负责把字符串还原为真正的 JS 类型:
function normalizeData(value) {
if (value === 'true') return true
if (value === 'false') return false
if (value === Number(value).toString()) return Number(value)
if (value === '' || value === 'null') return null
if (typeof value !== 'string') return value
try {
return JSON.parse(decodeURIComponent(value))
} catch {
return value
}
}
"true"/"false"→ 布尔值true/false;"0"、"150"等纯数字字符串 → 数字类型;- 空字符串或
"null"→null; - 无法直接匹配以上规则的字符串,会尝试
JSON.parse(decodeURIComponent(value))——这正是文档中"现有数据属性能够承载 JSON 值"(如data-bs-delay='{"show":0,"hide":150}')的底层来源;解析失败则原样保留字符串。
因此,当你写下 data-bs-delay='{"show":0,"hide":150}' 时,Tooltip/Popover 最终拿到的 config.delay 是一个 { show: 0, hide: 150 } 对象,而不再需要手工 JSON.parse。同理,data-bs-trigger="hover focus" 会保留为原始字符串,由组件内部再拆分为触发方式集合。
三、data-bs-config:Bootstrap 5.2.0 引入的实验性批量配置
文档指出,自 Bootstrap 5.2.0 起,所有组件支持一个**实验性(experimental)**的保留数据属性 data-bs-config,用于以 JSON 字符串承载一份"小型组件配置"。官方示例:
<div
data-bs-config='{"delay":0, "title":123}'
data-bs-title="456">
</div>
按照合并规则,最终 title 的值为 456——单独的数据属性会覆盖 data-bs-config 中给出的同名键值。与此同时,单独的属性也可以直接承载 JSON 值:
<div data-bs-delay='{"show":0,"hide":150}'></div>
关于 data-bs-config 的解析,有两点实现细节值得注意:
- 解析失败的非对象值会被整体忽略。util/config.js 的
_mergeConfigObj先尝试读取data-bs-config,只有当解析结果为对象时才参与合并;单测 util/config.spec.js 用data-bs-config="foo"(非 JSON)验证了这一点——此时配置退化为仅由默认值、单独数据属性和 JS 对象构成。 data-bs-config不会被当作普通选项误读。manipulator.js 中getDataAttributes在收集属性时显式过滤掉以bsConfig开头的 dataset 键(!key.startsWith('bsConfig')),对应的单测见 dom/manipulator.spec.js,确保它只作为配置容器、而不会以config选项混入最终配置对象。
四、合并优先级:默认值 < data-bs-config < 单独数据属性 < JS 对象
文档给出了合并结果的定义:
最终配置对象是
data-bs-config、data-bs-与 JS 对象三者合并的结果,其中后给出的键值会覆盖先给出的键值。
结合源码可以进一步还原出完整的四层优先级。_mergeConfigObj(config, element) 的实现(util/config.js)本质是一个逐层展开的对象展开(spread):
_mergeConfigObj(config, element) {
const jsonConfig = isElement(element)
? Manipulator.getDataAttribute(element, 'config')
: {} // 解析 data-bs-config
return {
...this.constructor.Default, // ① 组件内置默认值(最低优先级)
...(typeof jsonConfig === 'object' ? jsonConfig : {}), // ② data-bs-config
...(isElement(element) ? Manipulator.getDataAttributes(element) : {}), // ③ 单独 data-bs-* 属性
...(typeof config === 'object' ? config : {}) // ④ 编程方式传入的 JS 配置对象(最高优先级)
}
}
即完整的覆盖链为:组件默认值 → data-bs-config → 单独 data-bs-* 数据属性 → JS 配置对象,后一层对同名键一律覆盖前一层。单测 util/config.spec.js 用一个混合元素精确验证了这一行为:
<div id="test"
data-bs-config='{"testBool":false,"testInt":50,"testInt2":100}'
data-bs-test-int="8"
data-bs-test-string-1="bar"></div>
再配合 JS 传入 { testString1: 'test' },最终断言为:testBool: false(来自 data-bs-config)、testInt: 8(单独属性覆盖 config 的 50)、testInt2: 100(config 覆盖默认值 600)、testString1: 'test'(JS 对象最高优先级)。这一测试与文档描述完全一致,可直接作为排查配置不生效问题时的"参考答案"。
五、从源码看完整解析链路:Manipulator 与 Config 的分工
把上面的机制串起来,一个元素从 HTML 到最终生效配置,走的是这样一条调用链:
- 组件实例化(如
new bootstrap.Tooltip(el))触发 base-component.js 的_getConfig(config),它把元素与编程配置一并交给_mergeConfigObj(config, this._element); _mergeConfigObj依次读取默认值、data-bs-config(经Manipulator.getDataAttribute(element, 'config'))、全部data-bs-*属性(经Manipulator.getDataAttributes)与 JS 对象,完成四层合并;- 合并结果再经
_configAfterMerge做组件级后处理(如延迟、容器归一化),最后由_typeCheckConfig依据组件的DefaultType做类型校验,类型不符会抛出TypeError(见 util/config.js)。
Tooltip 是一个很好的观察样本。tooltip.js 重写了 _getConfig:它先读取数据属性,并删除 sanitize、allowList、sanitizeFn 三个禁止通过数据属性注入的键(DISALLOWED_ATTRIBUTES),再走通用合并流程;随后在 _configAfterMerge(tooltip.js)中把数字类型的 delay 归一化为 { show, hide },把数字类型的 title/content 转为字符串——这正解释了文档示例中 data-bs-config='{"delay":0, "title":123}' 为何能正常工作:数字 123 会被安全转换为字符串 "123" 作为标题。
六、实战:仅用 HTML 完成 Tooltip 的精细配置
综合以上规则,可以在一个按钮上仅用数据属性完成 Tooltip 的延迟、标题与自定义样式配置:
<button
type="button"
class="btn btn-secondary"
data-bs-toggle="tooltip"
data-bs-title="示例提示"
data-bs-custom-class="beautifier"
data-bs-delay='{"show":200,"hide":100}'
data-bs-placement="bottom">
悬停查看提示
</button>
data-bs-toggle="tooltip"负责启用组件;data-bs-custom-class="beautifier"对应选项customClass(kebab-case 命名),可用于为 Tooltip 追加自定义类以覆盖样式,Popover 文档 popovers.md 中即用data-bs-custom-class="custom-popover"配合 CSS 变量实现外观定制;data-bs-delay='{"show":200,"hide":100}'演示了属性承载 JSON 值的能力;- 更复杂的场景可改用
data-bs-config='{"delay":{"show":200,"hide":100},"placement":"bottom"}'将多项配置聚合成一份 JSON,再由单独的data-bs-title覆盖其中某项——这正是data-bs-config与单独属性协同的典型用法。
七、注意事项与适用前提
- 同一元素只能使用一组数据属性:官方文档明确"不要在一个元素上使用多组数据属性"(例如不能从同一个按钮同时触发 Tooltip 和 Modal)。源码侧 dom/data.js 也做了硬性约束:每个元素只允许绑定一个组件实例,重复绑定会在控制台报错。
data-bs-config是实验性能力:自 Bootstrap 5.2.0 起支持,本文所述规则以仓库内的 v5.3.1 版本(package.json中version: "5.3.1")为准,后续主版本可能调整,生产环境使用前请关注版本变更说明。- HTML 属性名与 JSON 键的大小写差异:HTML 属性名一律小写并用连字符(
data-bs-custom-class),而data-bs-config内部的 JSON 键必须使用与组件选项一致的 camelCase(如"customClass"、"fallbackPlacements"),二者不要混淆。 - 合并方向要记牢:单独
data-bs-*属性 >data-bs-config,JS 对象 > 一切数据属性。当某个属性"看起来没生效"时,优先检查是否为高优先级来源(JS 对象、单独属性)覆盖了低优先级来源,或 JSON 键名大小写不匹配。 - 类型校验失败会直接抛错:若
data-bs-*提供的值与组件DefaultType声明的类型不符,_typeCheckConfig会抛出形如TOOLTIP: Option "placement" provided type "string" but expected type ...的TypeError,这类报错通常是排查配置问题的最直接线索。
整体而言,这套 data-bs-* + data-bs-config 机制让 BOOTSTRA.386 所基于的 Bootstrap 5.3.1 组件在"纯 HTML 即配置"的方向上保持了完整能力:命名转换保证了选项名的一致映射,normalizeData 保证了类型正确,四层合并优先级则提供了从默认值、批量 JSON 到单属性覆盖、再到 JS 精确控制的渐进式定制路径。