Bootstrap-select 多功能表单 Select 下拉菜单美化插件 - 文章教程

Bootstrap-select 多功能表单 Select 下拉菜单美化插件

发布于 2020-03-26 字数 20895 浏览 2153 评论 0

jQuery 插件通过直观的 Select,搜索等功能将 select 元素带入 21 世纪。现在支持 Bootstrap 4。

Bootstrap-select 多功能表单 Select 下拉菜单美化插件

快速开始

Bootstrap-select需要jQuery v1.9.1 +,Bootstrap的dropdown.js组件和Bootstrap的CSS。如果您尚未在项目中使用Bootstrap,则可以在此处下载Bootstrap v3.3.7最低要求的预编译版本。如果在Bootstrap v4 +中使用bootstrap-select,你还需要Popper.js。有关Bootstrap v4的所有要求,请参阅入门。预期版本的需求将在即将发布的bootstrap-select版本中提供。

有几种快速启动选项:

  • 下载最新版本。
  • 克隆回购: git clone https://github.com/snapappointments/bootstrap-select.git
  • 使用npm安装: npm install bootstrap-select
  • 使用yarn安装: yarn add bootstrap-select
  • 使用Composer安装: composer require snapappointments/bootstrap-select
  • 使用NuGet安装: Install-Package bootstrap-select
  • 使用Bower安装: bower install bootstrap-select
  • 通过CDN安装(cdnjsjsDelivr):
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" target="_blank" class="external-link" href="https://cdn.jsdelivr.net/npm/bootstrap-select@1.13.9/dist/css/bootstrap-select.min.css">

<!-- Latest compiled and minified JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap-select@1.13.9/dist/js/bootstrap-select.min.js"></script>

<!-- (Optional) Latest compiled and minified JavaScript translation files -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap-select@1.13.9/dist/js/i18n/defaults-*.min.js"></script>

发布后,CDN 会更新,这意味着发布版本及其在 CDN 上的可用性之间存在延迟。

用法

Bootstrap 4 仅适用于 bootstrap-select v1.13.0 +。默认情况下,bootstrap-select 会自动检测正在使用的 Bootstrap 版本。但是在某些情况下,版本检测将不起作用。有关更多信息,请参阅下面的文档。

通过 selectpicker

selectpicker 类添加到 select 元素以自动初始化 bootstrap-select。

<select class="selectpicker">
  <option>Mustard</option>
  <option>Ketchup</option>
  <option>Barbecue</option>
</select>

通过 JavaScript

// To style only selects with the my-select class
$('.my-select').selectpicker();

// To style all selects
$('select').selectpicker();

如果通过 JavaScript 调用 bootstrap-select,则需要将代码包装在一个 .ready() 块中或将其放在页面的底部(在 bootstrap-select 的最后一个实例之后)。

$(function () {
  $('select').selectpicker();
});

Bootstrap 版本


由于 Bootstrap 3 和 Bootstrap 4之间的类名和布局有一些变化,bootstrap-select 需要知道您正在使用的 Bootstrap的版本。 默认情况下,bootstrap-select 会自动检测 Bootstrap 的版本。 但是,在某些情况下,版本检测无法正常工作(例如,异步加载 Bootstrap 或存在命名空间冲突)。 目前,如果版本检测失败,bootstrap-select 默认使用 Bootstrap 3 格式化。 这将在下一个主要版本中更改。

您可以通过 bootstrap-select 手动指定 Bootstrap 的版本 Constructor.BootstrapVersion

$.fn.selectpicker.Constructor.BootstrapVersion = '4';

核心选项


选项可以通过数据属性或 JavaScript 传递。 对于数据属性,将选项名称附加到 data-,如 data-style =""data-selected-text-format = "count"

注意:出于安全原因,无法使用数据属性提供 sanitizesanitizeFnwhiteList 选项。

名称 类型 默认值 描述
actionsBox boolean false 设置为true时,在下拉菜单的顶部添加两个按钮(全选取消全选)。
container string | false false 设置为字符串时,将select附加到特定元素或选择器,例如container: 'body' | '.main-body'
countSelectedText string | function function 设置selectedTextFormat为count或count>#时显示的文本格式。 {0}是选定的金额。 {1}总数可供选择。

设置为函数时,第一个参数是所选选项的数量,第二个参数是总数 选项。 该函数必须返回一个字符串。

deselectAllText string 'Deselect All' 启用actionsBox时取消选择所有选项的按钮上的文本。
dropdownAlignRight boolean | 'auto' false 将菜单对齐而不是左对齐。 如果设置为“auto”,如果在向左对齐时菜单的全宽度没有空间,菜单将自动对齐。
dropupAuto boolean true 检查哪个有更多的空间,高于或低于。 如果dropup有足够的空间可以正常完全打开,但是上面有更多空间,则dropup仍会正常打开。 否则,它变成了一个下降。 如果dropupAuto设置为false,则必须手动调用dropup。
header string false 在页面顶部添加一个标题; 默认包括关闭按钮
hideDisabled boolean false 从菜单中删除已禁用的选项和optgroups data-hide-disabled: true
iconBase string 'glyphicon' 将基数设置为使用不同的图标字体而不是Glyphicons。 如果更改iconBase,您可能还想更改tickIcon,以防新图标字体使用不同的命名方案。
liveSearch boolean false 设置为true时,会在selectpicker下拉列表的顶部添加一个搜索框。
liveSearchNormalize boolean false 将liveSearchNormalize设置为true允许对重音不敏感的搜索。
liveSearchPlaceholder string null 设置为字符串时,将将等于字符串的占位符属性添加到liveSearch输入。
liveSearchStyle string 'contains' 设置为“contains”时,搜索将显示包含搜索文本的选项。 例如,搜索pl,同时返回Apple,Plum和Plantain。 当设置为'startsWith'时,搜索pl将仅返回Plum和Plantain。
maxOptions integer | false false 设置为整数并在多选中时,所选选项的数量不能超过给定值。

此选项也可以作为<optgroup>的数据属性存在,在这种情况下,它仅适用于<optgroup>

maxOptionsText string | array | function function 启用maxOptions时显示的文本以及已选择给定方案的最大选项数。

如果使用函数,则必须返回一个数组。 array [0]是maxOptions应用于整个select元素时使用的文本。 array [1]是在optgroup上使用maxOptions时使用的文本。 如果使用字符串,则元素和optgroup使用相同的文本。

mobile boolean false 设置为true时,启用设备的选择菜单的本机菜单。
multipleSeparator string ', ' 设置分隔选定选项的按钮中显示的字符。
noneSelectedText string 'Nothing selected' 多重选择没有选定选项时显示的文本。
noneResultsText string 'No results matched {0}' 搜索未返回任何结果时显示的文本。
selectAllText string 'Select All' 启用actionsBox时选择所有选项的按钮上的文本。
selectedTextFormat 'values' | 'static' | 'count' | 'count > x' (where x is an integer) 'values' 指定如何使用多重选择显示选择。

'values'显示所选选项的列表(由multipleSeparator分隔.'static'只显示select元素的标题.'count'显示所选选项的总数.'count> x'的行为类似于'values',直到数量为 选定的选项大于x;之后,它的行为类似于'count'

selectOnTab boolean false 设置为true时,将制表符视为selectpicker下拉列表中的输入或空格字符。
showContent boolean true 设置为true时,显示与按钮中所选选项关联的自定义HTML。 设置为false时,将显示选项值。
showIcon boolean true 设置为true时,显示与按钮中所选选项关联的图标。
showSubtext boolean false 设置为true时,显示与按钮中所选选项关联的子文本。
showTick boolean false 在所选选项上显示复选标记(对于没有多个属性的项目)。
size 'auto' | integer | false 'auto' 设置为“auto”时,菜单始终打开以显示窗口允许的项目数量,而不会被切断。

设置为整数时,菜单将显示给定的项目数,即使下拉列表已被切断。

设置为false时,菜单将始终显示所有项目。

style string | null Bootstrap 4: 'btn-light'Bootstrap 3: 'btn-default' 设置为字符串时,将值添加到按钮的样式。
styleBase string | null 'btn' 应用于按钮的默认类。 使用setStyle方法时,此类将始终保留。

提示:如果要将元素设置为表单控件,请将style设置为'',将styleBase设置为'form-control'

tickIcon string 'glyphicon-ok' 设置要用于显示为所选选项旁边的“tick”的图标。
title string | null null selectpicker的默认标题。
virtualScroll boolean | integer 600 如果启用,下拉列表中的项目将使用虚拟化呈现(即,仅渲染视口内的项目)。 这大大提高了具有大量选项的选择的性能。 如果select具有至少该数量的选项,则设置为仅使用虚拟化的整数。
width 'auto' | 'fit' | css-width | false (where css-width is a CSS width with units, e.g. 100px) false 设置为auto时,会自动调整选择器的宽度以适应最宽的选项。

设置为css-width时,selectpicker的宽度将强制内联到给定值。

设置为false时,将删除所有宽度信息。

windowPadding integer | array 0 这在窗口具有下拉菜单不应覆盖的区域(例如固定标题)的情况下非常有用。 设置为整数时,将向所有边添加相同的填充。 或者,可以以[top,right,bottom,left]格式使用整数数组。
sanitize boolean true 启用或禁用清理。 如果激活,将对各个选项的'data-content'进行清理。
whiteList object Default value 包含允许的属性和标记的对象
sanitizeFn null | function null 在这里,您可以提供自己的清洁功能。 如果您更喜欢使用专用库来执行清理,这可能很有用。

默认设置


您可以通过修改其 Constructor.DEFAULTS 对象来更改 bootstrap-select 的默认设置:

$.fn.selectpicker.Constructor.DEFAULTS.multipleSeparator = '|';

事件


Bootstrap-select 公开了一些事件以挂钩到 select 功能。

hide.bs.selecthidden.bs.selectshow.bs.selectshown.bs.select 都有一个 relatedTarget 属性,其值是切换的锚元素。

事件类型 描述
show.bs.select 调用show实例方法时会立即触发此事件。
shown.bs.select 当下拉菜单对用户可见时(将等待CSS转换完成),将触发此事件。
hide.bs.select 调用hide实例方法时会立即触发此事件。
hidden.bs.select 下拉菜单已完成对用户隐藏时将触发此事件(将等待CSS转换完成)。
loaded.bs.select select初始化后会触发此事件。
rendered.bs.select 调用渲染实例后将触发此事件。
refreshed.bs.select 调用刷新实例后将触发此事件。
changed.bs.select 更改选择的值后将触发此事件。 它经过event, clickedIndex, isSelected, previousValue.

previousValue是更改前的select值。 如果通过.selectpicker('val')selectpicker('selectAll').selectpicker('deselectAll')方法更改了select的值,则clickedIndexisSelected将为null

$('#mySelect').on('changed.bs.select', function (e, clickedIndex, isSelected, previousValue) {
  // do something...
});

Sanitizer


通过各个选项的 data-content 属性添加的HTML将使用我们的内置清洁程序进行清理。

默认的 whiteList 值如下:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i;
var DefaultWhitelist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', 'tabindex', 'style', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

如果要向此默认whiteList添加新值,可以执行以下操作:

var myDefaultWhiteList = $.fn.selectpicker.Constructor.DEFAULTS.whiteList;

// To allow table elements
myDefaultWhiteList.table = [];

// To allow td elements and data-option attributes on td elements
myDefaultWhiteList.td = ['data-option'];

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
var myCustomRegex = /^data-my-app-[\w-]+/;
myDefaultWhiteList['*'].push(myCustomRegex);

如果您想绕过我们的sanitizer,因为您更喜欢使用专用库,则应执行以下操作:

$('#yourSelect').selectpicker({
  sanitizeFn: function (domNodes) {
return DOMPurify.sanitize(domNodes)
  }
});

出于性能原因,我们的内置清理程序接受一组DOM节点作为其第一个参数,而不是HTML字符串。 如果决定使用自己的sanitizeFn,请记住这一点。

方法

与 bootstrap-select 的接口。


.selectpicker('val')

您可以通过调用元素上的val方法来设置所选值。

$('.selectpicker').selectpicker('val', 'Mustard');
$('.selectpicker').selectpicker('val', ['Mustard','Relish']);

这与直接在select元素上调用val()不同。 如果直接在元素上调用val(),则 bootstrap-select ui将不会刷新(因为更改事件仅从用户交互中触发)。 您必须自己调用ui refresh方法。

$('.selectpicker').val('Mustard');
$('.selectpicker').selectpicker('render');

// 这相当于上述内容
$('.selectpicker').selectpicker('val', 'Mustard');

.selectpicker('selectAll')

这将选择多选中的所有项目。

$('.selectpicker').selectpicker('selectAll');

.selectpicker('deselectAll')

这将取消选择多选中的所有项目。

$('.selectpicker').selectpicker('deselectAll');

.selectpicker('render')

您可以使用render方法强制重新呈现bootstrap-select ui。 如果以编程方式更改影响元素布局的任何基础值,则此选项非常有用。

$('.selectpicker').selectpicker('render');

.selectpicker('mobile')

通过调用移动滚动$('.selectpicker').selectpicker('mobile')这将启用设备的选择菜单的本机菜单

用于检测浏览器的方法由用户决定。

if( /Android|webOS|iPhone|iPad|iPod|BlackBerry/i.test(navigator.userAgent) ) {
  $('.selectpicker').selectpicker('mobile');
}

.selectpicker('setStyle')

修改与按钮本身或其容器关联的类。

如果更改容器上的类:

$('.selectpicker').addClass('col-lg-12').selectpicker('setStyle');

如果更改按钮上的类(更改数据样式):

// Replace Class
$('.selectpicker').selectpicker('setStyle', 'btn-danger');

// Add Class
$('.selectpicker').selectpicker('setStyle', 'btn-large', 'add');

// Remove Class
$('.selectpicker').selectpicker('setStyle', 'btn-large', 'remove');

.selectpicker('refresh')

要以编程方式使用JavaScript更新选择,请先操作select,然后使用refresh方法更新UI以匹配新状态。 在删除或添加选项时,或通过JavaScript禁用/启用选择时,这是必需的。

$('.selectpicker').selectpicker('refresh');
<select class="selectpicker remove-example">
  <option value="Mustard">Mustard</option>
  <option value="Ketchup">Ketchup</option>
  <option value="Relish">Relish</option>
</select>

<button class="btn btn-warning rm-mustard">Remove Mustard</button>
<button class="btn btn-danger rm-ketchup">Remove Ketchup</button>
<button class="btn btn-success rm-relish">Remove Relish</button>
$('.rm-mustard').click(function () {
  $('.remove-example').find('[value=Mustard]').remove();
  $('.remove-example').selectpicker('refresh');
});
$('.ex-disable').click(function () {
  $('.disable-example').prop('disabled', true);
  $('.disable-example').selectpicker('refresh');
});

$('.ex-enable').click(function () {
  $('.disable-example').prop('disabled', false);
  $('.disable-example').selectpicker('refresh');
});

.selectpicker('toggle')

以编程方式切换bootstrap-select菜单打开/关闭。

$('.selectpicker').selectpicker('toggle');

.selectpicker('hide')

要以编程方式隐藏bootstrap-select,请使用hide方法(这只会影响bootstrap-select本身的可见性)。

$('.selectpicker').selectpicker('hide');

.selectpicker('show')

要以编程方式显示bootstrap-select,请使用show方法(这仅影响bootstrap-select本身的可见性)。

$('.selectpicker').selectpicker('show');

.selectpicker('destroy')

要以编程方式销毁bootstrap-select,请使用destroy方法。

$('.selectpicker').selectpicker('destroy');

相关链接

如果你对这篇文章有疑问,欢迎到本站 社区 发帖提问或使用手Q扫描下方二维码加群参与讨论,获取更多帮助。

扫码加入群聊

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

目前还没有任何评论,快来抢沙发吧!

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

2891 文章
评论
84935 人气
更多

推荐作者

伊面

文章 0 评论

白况

文章 0 评论

七禾

文章 0 评论

亢潮

文章 0 评论

悲念泪

文章 0 评论