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

Question

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

快速开始

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安装(cdnjs 或 jsDelivr):

<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" 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"。

注意：出于安全原因，无法使用数据属性提供 sanitize，sanitizeFn 和 whiteList 选项。

名称	类型	默认值	描述
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.select，hidden.bs.select，show.bs.select 和 shown.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的值，则clickedIndex和isSelected将为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');

相关链接

• 中文官网：https://www.bootstrapselect.cn