jQuery 替换选择框插件 Select2 自定义配置 API


如果在初始化 Select2 时配置自定义选项,只需将对象传递给 .select2()

$('.js-example-basic-single').select2({
  placeholder: 'Select an option'
});

配置 API

Option Type Default Description
adaptContainerCssClass
adaptDropdownCssClass
ajax object null Provides support for ajax data sources.
allowClear boolean false Provides support for clearable selections.
amdBase string ./ See Using Select2 with AMD or CommonJS loaders.
amdLanguageBase string ./i18n/ See Using Select2 with AMD or CommonJS loaders.
closeOnSelect boolean true Controls whether the dropdown is closed after a selection is made.
containerCss
containerCssClass string ''
data array of objects null Allows rendering dropdown options from an array.
dataAdapter SelectAdapter Used to override the built-in DataAdapter.
debug boolean false Enable debugging messages in the browser console.
dir
disabled boolean false When set to true, the select control will be disabled.
dropdownAdapter DropdownAdapter Used to override the built-in DropdownAdapter
dropdownAutoWidth boolean false
dropdownCss
dropdownCssClass string ''
dropdownParent jQuery selector or DOM node $(document.body) Allows you to customize placement of the dropdown.
escapeMarkup callback Utils.escapeMarkup Handles automatic escaping of content rendered by custom templates.
initSelection callback See initSelection. This option was deprecated in Select2 v4.0, and will be removed in v4.1.
language string or object EnglishTranslation Specify the language used for Select2 messages.
matcher A callback taking search params and the data object. Handles custom search matching.
maximumInputLength integer 0 Maximum number of characters that may be provided for a search term.
maximumSelectionLength integer 0 The maximum number of items that may be selected in a multi-select control. If the value of this option is less than 1, the number of selected items will not be limited.
minimumInputLength integer 0 Minimum number of characters required to start a search.
minimumResultsForSearch integer 0 The minimum number of results required to display the search box.
multiple boolean false This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the multiple HTML attribute to this option during initialization.
placeholder string or object null Specifies the placeholder for the control.
query A function taking params (including a callback) Query This option was deprecated in Select2 v4.0, and will be removed in v4.1.
resultsAdapter ResultsAdapter Used to override the built-in ResultsAdapter.
selectionAdapter SingleSelection or MultipleSelection, depending on the value of multiple. Used to override the built-in SelectionAdapter.
selectOnClose boolean false Implements automatic selection when the dropdown is closed.
sorter callback
tags boolean / array of objects false Used to enable free text responses.
templateResult callback Customizes the way that search results are rendered.
templateSelection callback Customizes the way that selections are rendered.
theme string default Allows you to set the theme.
tokenizer callback A callback that handles automatic tokenization of free-text entry.
tokenSeparators array [] The list of characters that should be used as token separators.
width string resolve Supports customization of the container width.

全局默认值

在某些情况下,您需要在 Web 应用程序中为 Select2 的所有实例设置默认选项。当您从过去的 Select2 版本迁移,或者使用非标准选项(如自定义 AMD 构建)时,这尤其有用。Select2 公开了默认选项 $.fn.select2.defaults,允许您全局设置它们。
当设置全局默认值时,将覆盖已设置的任何默认值。默认选项仅在请求未初始化前设置的选项使用。
您可以通过调用设置默认选项 $.fn.select2.defaults.set("key", "value")。例如:

$.fn.select2.defaults.set("theme", "classic");

嵌套选项

要为缓存设置默认值,请使用与 HTML 相同的表示法 data-* attributes。两个破折号(–)将被嵌套级别替换,单个破折号(-)将密钥转换为 camelCase 字符串:

$.fn.select2.defaults.set("ajax--cache", false);

重置默认选项

通过调用将默认选项重置为其初始值:

$.fn.select2.defaults.reset();

data-* attributes

建议您在初始化 Select2 时传入对象来声明配置选项。但是,您也可以使用 HTML5 定义配置选项 data-* attributes,它将覆盖初始化 Select2 和任何默认值时设置的任何选项。

camelCase 选项

HTML 数据属性不区分大小写,因此任何包含大写字母的选项都将被解析为好像它们都是小写的。因为 Select2 有很多选项是 camelCase,其中单词用大写字母分隔,所以你必须用破折号写出这些选项。所以通常会调用一个选项 allowClear 应改为定义为 allow-clear


    ...

相当于在 js 中这样表达:

$("select").select2({
  tags: "true",
  placeholder: "Select an option",
  allowClear: true
});

<< jQuery 替换选择框插件 Select2 基本用法