Bootstrap Switch 2.0.1 使用指南：选项、方法与事件详解

Bootstrap Switch 2.0.1 使用指南：选项、方法与事件详解

bootstrap-switch 项目地址: https://gitcode.com/gh_mirrors/boo/bootstrap-switch

什么是 Bootstrap Switch

Bootstrap Switch 是一个基于 Bootstrap 框架的 jQuery 插件，它能够将普通的复选框（checkbox）和单选按钮（radio button）转换为美观的开关式切换控件。这个插件不仅提供了视觉上的提升，还增加了丰富的交互功能和自定义选项。

核心特性

1. 多种尺寸选择：支持 mini、small、normal、large 等多种尺寸
2. 丰富的颜色主题：提供 primary、info、success、warning、danger 等多种颜色
3. 高度可定制：可以自定义开关两侧的文本、颜色和中间手柄的图标
4. 动画效果：默认带有平滑的切换动画
5. 状态控制：支持禁用、只读等多种状态

选项配置

Bootstrap Switch 的所有选项都通过 data-* 属性在 HTML 元素上设置。只有 checked、disabled 和 readonly 这三个选项例外，它们使用标准的 HTML 输入属性。

主要选项说明

| 选项名称 | 类型 | 描述 | 可选值 | 默认值 | |---------|------|------|--------|--------| | state | Boolean | 开关状态 | true, false | 'checked' 属性或 true | | size | String | 开关尺寸 | '', 'mini', 'small', 'normal', 'large' | '' | | animate | Boolean | 是否启用动画 | true, false | true | | disabled | Boolean | 是否禁用 | true, false | 'disabled' 属性或 false | | readonly | Boolean | 是否只读 | true, false | 'readonly' 属性或 false | | on | String | 左侧颜色 | 'primary', 'info', 'success', 'warning', 'danger', 'default' | null | | off | String | 右侧颜色 | 'primary', 'info', 'success', 'warning', 'danger', 'default' | null | | on-label | String | 左侧文本 | 任意字符串 | 'ON' | | off-label | String | 右侧文本 | 任意字符串 | 'OFF' | | label-text | String | 中间手柄文本 | 任意字符串 | ' ' | | label-icon | String | 中间手柄图标 | 任意字符串 | null |

使用示例：

<input type="checkbox" 
       data-size="small" 
       data-on-text="启用" 
       data-off-text="禁用" 
       data-on-color="success" 
       data-off-color="danger">

方法调用

Bootstrap Switch 提供了一系列方法用于动态控制开关的状态和行为。所有方法都返回 jQuery 对象（输入元素本身），支持链式调用。

常用方法详解

1. 状态控制

   • state(): 获取当前开关状态（true/false）
   • setState(value[, skip]): 设置开关状态
   • toggleState([skip]): 切换开关状态

2. 尺寸与动画

   • setSizeClass(size): 设置开关尺寸
   • setAnimated(animate): 设置是否启用动画

3. 禁用与只读

   • isDisabled(): 检查是否禁用
   • setDisabled(disabled): 设置禁用状态
   • toggleDisabled(): 切换禁用状态

4. 外观定制

   • setOnClass(class): 设置左侧颜色
   • setOffClass(class): 设置右侧颜色
   • setOnLabel(text): 设置左侧文本
   • setOffLabel(text): 设置右侧文本

5. 其他

   • destroy(): 销毁 Bootstrap Switch 实例，恢复原始输入元素

方法调用示例：

// 获取开关状态
var isChecked = $('[name="my-checkbox"]').bootstrapSwitch('state');

// 设置开关为开启状态
$('[name="my-checkbox"]').bootstrapSwitch('setState', true);

// 切换开关状态
$('[name="my-checkbox"]').bootstrapSwitch('toggleState');

// 设置小尺寸
$('[name="my-checkbox"]').bootstrapSwitch('setSizeClass', 'small');

事件处理

Bootstrap Switch 触发一个主要事件 switch-change，当开关状态改变时触发。这个事件提供两个参数：

1. event: 标准的事件对象
2. data: 包含以下属性的对象
   • el: 原始输入元素的 DOM 对象
   • value: 新的开关状态（true/false）

事件监听示例：

$('[name="my-checkbox"]').on('switch-change', function(e, data) {
    console.log('开关状态已改变:', data.value);
    // 可以根据新状态执行相应操作
});

最佳实践

1. 初始化时机：确保在 DOM 完全加载后再初始化 Bootstrap Switch
2. 性能优化：对大量开关控件使用事件委托而非单独绑定
3. 响应式设计：考虑在不同屏幕尺寸下使用不同大小的开关
4. 无障碍访问：确保开关控件有适当的标签和 ARIA 属性

常见问题

Q: 如何在初始化后动态修改开关选项？ A: 使用相应的方法，如 setOnClass、setOffLabel 等。

Q: 为什么我的开关没有动画效果？ A: 检查是否设置了 data-animate="false" 或调用了 setAnimated(false)。

Q: 如何完全移除 Bootstrap Switch？ A: 使用 destroy() 方法可以恢复原始输入元素。

Bootstrap Switch 2.0.1 是一个功能强大且易于使用的插件，通过合理利用其提供的选项、方法和事件，可以创建出既美观又功能丰富的开关控件，大大提升用户界面的交互体验。

bootstrap-switch 项目地址: https://gitcode.com/gh_mirrors/boo/bootstrap-switch