官方 API 链接: 链接标题 https://select2.org/
select2 4.0.3
1. select2 api 参数的文档
属性 | 类型 | 默认 | 描述 |
---|---|---|---|
width | string | resolve | 支持对容器宽度的定制 |
ajax | object | null | 提供对 ajax 数据源的支持 |
allowClear | boolean | false | 提供对可清除选择的支持 |
closeOnSelect | boolean | true | 控制下拉菜单是否在选择后关闭 |
data | array of objects | null | 允许从数组中呈现下拉菜单选项 |
dataAdapter | SelectAdapter | 用于覆盖内置 DataAdapter | |
debug | boolean | false | 用于覆盖内置 DataAdapter |
disabled | boolean | false | 当设置为 true 时,select 控件将被禁用 |
dropdownAdapter | DropdownAdapter | 用于覆盖内置的 DropdownAdapter | |
dropdownParent | jQuery 选择器或 DOM 节点 | $(document.body) | 允许您定制下拉菜单的位置 |
escapeMarkup | callback | Utils.escapeMarkup | 处理由自定义模板提供的内容的自动转义 |
initSelection | callback | 该选项在 Select2 v4.0 中被弃用,并将在 v4.1 中删除 | |
language | string or object | EnglishTranslation | 指定用于 Select2 消息的语言 |
matcher | 一个回调,获取搜索 params 和数据对象 | 处理自定义搜索匹配 | |
maximumInputLength | int | 0 | 可能为搜索词提供的最大字符数 |
maximumSelectionLength | int | 0 | 可在多选择控件中选择的最大项数。如果该选项的值小于 1,则所选项的数量将不受限制 |
minimumInputLength | int | 0 | 开始搜索所需的最小字符数 |
minimumResultsForSearch | int | 0 | 显示搜索框所需的最小结果数 |
placeholder | string or object | null | 指定控件的占位符 |
query | 一个函数参数 (including a callback) | Query | 该选项在 Select2 v4.0 中被弃用,并将在 v4.1 中删除 |
resultsAdapter | ResultsAdapter | 用于覆盖内置的 ResultsAdapter | |
selectionAdapter | 用于覆盖内置 SelectionAdapter | ||
selectOnClose | boolean | false | 当下拉关闭时,实现自动选择 |
sorter | callback | ||
tags | boolean / array of objects | false | 用于支持自由文本响应 |
templateResult | callback | 定制搜索结果的方式 | |
templateSelection | callback | 定制选择的方式 | |
theme | string | default | 允许你设置主题 |
tokenizer | callback | 一个回调,它处理自由文本条目的自动标记化 | |
tokenSeparators | array | [] | 应该用作令牌分隔符的字符列表 |
2. 外观
2.1. 禁用 select2
- $(".js-example-disabled").select2();
- $(".js-example-disabled-multi").select2();
- $(".js-programmatic-enable").on("click", function () {
- $(".js-example-disabled").prop("disabled", false);
- $(".js-example-disabled-multi").prop("disabled", false);
- });
- $(".js-programmatic-disable").on("click", function () {
- $(".js-example-disabled").prop("disabled", true);
- $(".js-example-disabled-multi").prop("disabled", true);
- });
2.2. 禁用 select2 的选项(disabled: true)
<select class="js-example-disabled-results">
<option value="one">First</option>
<option value="two" disabled="disabled">Second (disabled)</option>
<option value="three">Third</option>
</select>
2.3. 宽度
Select2 将尽可能地匹配原始元素的宽度. 有时这并不完美, 在这种情况下, 您可以手动设置宽度配置选项:
值 | 描述 |
---|---|
'element' | 使用来自任何适用的 CSS 规则的计算元素宽度。 |
'style' | 宽度由 select 元素的 style 属性决定。如果没有找到样式属性,则返回 null 作为宽度。 |
'resolve' | 使用样式属性值 (如果可用),根据需要返回到计算元素宽度。 |
'<value>' | 有效的 CSS 值可以作为字符串传递(例如宽度:'80%')。 |
- <select class="js-example-responsive" style="width: 50%"></select>
- <select class="js-example-responsive" multiple="multiple" style="width: 75%"></select>
- $(".js-example-responsive").select2({
- width: 'resolve' // need to override the changed default
- });
3. Select2 数据格式
Select2 可以作为下拉选项呈现从数组或远程数据源 (AJAX) 以编程方式提供的数据. 为了实现这一点, Select2 需要一个非常特定的数据格式. 这种格式由一个 JSON 对象组成, 该对象包含由结果键键入的对象数组.
- {
- "results": [
- {
- "id": 1,
- "text": "Option 1"
- },
- {
- "id": 2,
- "text": "Option 2"
- }
- ],
- "pagination": {
- "more": true
- }
- }
每个对象至少应该包含一个 id 和一个 text 属性. 与数据对象一起传递的任何附加参数都将包含在 Select2 公开的数据对象中.
如果您想要使用 "无限滚动" 功能, 那么响应对象也可以包含分页数据. 这应该在分页键下指定.
3.1. 选择和禁用的选项
您还可以为该数据结构中的选项提供已选择和禁用的属性. 例如:
- {
- "results": [
- {
- "id": 1,
- "text": "Option 1"
- },
- {
- "id": 2,
- "text": "Option 2",
- "selected": true// 已选择
- },
- {
- "id": 3,
- "text": "Option 3",
- "disabled": true// 禁用属性
- }
- ]
- }
在这种情况下, 将预先选择选项 2, 并禁用选项 3.
3.2. 将数据转换为所需的格式
3.2.1. 生成 id 属性
Select2 要求使用 id 属性惟一地标识结果列表中显示的选项. 如果您使用 id(如 pk)以外的属性来惟一地标识一个选项, 那么您需要将您的旧属性映射到 id, 然后再将其传递给 Select2.
如果您无法在服务器上执行此操作, 或者您处于无法更改 API 的情况, 您可以在将 API 传递给 Select2 之前使用 JavaScript 执行此操作
- var data = $.map(yourArrayData, function (obj) {
- obj.id = obj.id || obj.pk; // replace pk with your identifier
- return obj;
- });
3.2.2. 生成 text 属性
就像使用 id 属性一样, Select2 要求为选项显示的文本存储在 text 属性中. 您可以使用以下 JavaScript 从任何现有属性映射此属性.
- var data = $.map(yourArrayData, function (obj) {
- obj.text = obj.text || obj.name; // replace name with the property used for the text
- return obj;
- });
- 4. Ajax(远程数据)
Select2 内置了 AJAX 支持, 使用 jQuery 的 AJAX 方法.
- HTML:
- <select class="js-data-example-ajax"></select>
- Javascript:
- $('.js-data-example-ajax').select2({
- ajax: {
- url: 'https://api.github.com/search/repositories',
- dataType: 'json'
- // 额外的 AJAX 参数在这里; 请参阅本章末尾, 以获得本示例的完整代码
- }
- });
您可以使用 ajax 选项配置 Select2 如何搜索远程数据. Select2 将把 ajax 对象中的任何选项传递给 jQuery 的 $.ajax 函数, 或您指定的传输函数.
仅对于远程数据源, Select2 不会创建一个新的 < option > 元素, 直到项目第一次被选中. 这是出于性能原因. 一旦创建了一个<选项>, 它将保留在 DOM 中, 即使之后更改了选择.
4.1. 请求参数(Request parameters)
Select2 将在用户打开控件时向指定的 URL 发出请求(除非有一个 minimumInputLength 设置), 并且每次用户在搜索框中输入时都会发出请求. 默认情况下, 它将作为查询字符串参数发送如下内容
term: 搜索框中的当前搜索词.
q: 包含与 term 相同的内容.
_type: 一个 "request type". 通常是查询, 但对分页请求更改为 query_append.
page: 请求的当前页码. 只发送分页 (无限滚动) 搜索.
例如, Select2 可能会发出类似的请求: https://api.github.com/search/repositories?term=sel&_type=query&q=sel
有时, 您可能需要向请求添加额外的查询参数. 可以通过覆盖 ajax 修改随请求发送的参数.
- $('#mySelect2').select2({
- ajax: {
- url: 'https://api.github.com/orgs/select2/repos',
- data: function (params) {
- var query = {
- search: params.term,
- type: 'public'
- }
- // 查询参数将是? search=[term]&type=public
- return query;
- }
- }
- });
4.2. 转换响应数据
您可以使用 ajax.processResults 选项将 API 返回的数据转换为 Select2 所期望的格式:
- $('#mySelect2').select2({
- ajax: {
- url: '/example/api',
- processResults: function (data) {
- // 将响应对象的顶级键从 "items" 转换为 "results"
- return {
- results: data.items
- };
- }
- }
- });
4.3. 默认选中值
您可能希望为 Select2 控件设置一个预先选择的默认值, 该控件接收来自 AJAX 请求的数据.
要提供默认选择, 您可以为每个包含应该显示的值和文本的选择包含一个 < option>.
<select class="js-example-data-ajax form-control">
<option value="3620194" selected="selected">select2/select2</option>
</select>
要以编程方式实现这一点, 您将需要创建并附加一个新 < option>.
4.4. Pagination(分页)
Select2 支持对远程数据源的分页("无限滚动"). 要使用此特性, 您的远程数据源必须能够响应分页请求(Laravel 和 UserFrosting 等服务器端框架具有此内置).
要使用分页, 必须告诉 Select2 通过覆盖 ajax 向请求添加任何必要的分页参数. 数据设置. 要检索的当前页存储在 params.page 属性中.
- $('#mySelect2').select2({
- ajax: {
- url: 'https://api.github.com/search/repositories',
- data: function (params) {
- var query = {
- search: params.term,
- page: params.page || 1
- }
- // 查询参数将是? search=[term]&page=
- return query;
- }
- }
- });
Select2 将期望响应中有一个 pagination.more 值. more 的值应该是 true 或 false, 这将告诉 Select2 是否有更多页面的结果可供检索.
- {
- "results": [
- {
- "id": 1,
- "text": "Option 1"
- },
- {
- "id": 2,
- "text": "Option 2"
- }
- ],
- "pagination": {
- "more": true
- }
- }
如果服务器端代码没有在响应中生成 pagination.more 属性, 那么可以使用 processResults 从其他可用信息中生成这个值.
例如, 假设你的 API 返回一个 count_filtered 值告诉你总共有多少 (unpaginated) 结果中可用数据集. 如果你知道你的分页的 API 返回一次 10 个结果, 您可以使用此连同 count_filtered 的价值来计算 pagination.more 的值.
- processResults: function (data, params) {
- params.page = params.page || 1;
- return {
- results: data.results,
- pagination: {
- more: (params.page * 10) <data.count_filtered
- }
- };
- }
4.5. Rate-limiting 请求
您可以告诉 Select2 在触发 AJAX 请求之前等待用户输入完搜索词. 只需使用 ajax.delay 配置选项告诉 Select2, 在发送请求之前, 用户停止输入后要等待多长时间:
- $('#mySelect2').select2({
- ajax: {
- delay: 250 // 在触发请求之前等待 250 毫秒
- }
- });
4.6. 简化动态网址
如果搜索结果没有一个 url, 或者需要调用一个函数来确定要使用的 url, 可以为 ajax.url 选项指定一个回调来生成 url. 当前搜索查询将通过 params 选项传入:
- $('#mySelect2').select2({
- ajax: {
- url: function (params) {
- return '/some/url/' + params.term;
- }
- }
- });
4.7. 选择运输方法(Alternative transport methods)
Select2 使用 ajax.transport 中定义的传输方法向 API 发送请求. 默认情况下, 这种传输方法是 jQuery.ajax, 但是它可以很容易被覆盖:
- $('#mySelect2').select2({
- ajax: {
- transport: function (params, success, failure) {
- var request = new AjaxRequest(params.url, params);
- request.on('success', success);
- request.on('failure', failure);
- }
- }
- });
4.8. jQuery $.ajax 选项
传递给 ajax 的所有选项将直接传递给执行 ajax 请求的 $.ajax 函数.
Select2 将拦截一些自定义选项, 允许您在发出请求时进行自定义:
- ajax: {
- // 在发出 ajax 请求之前, 等待用户停止输入的毫秒数.
- delay: 250,
- // 您可以根据传递到请求中的参数创建自定义 url.
- // 如果您正在使用一个具有 X 函数的框架来生成要请求的 url, 这将非常有用.
- //
- // @param params 包含用于生成请求的参数的对象.
- // @returns 请求应该被处理的 URL.
- url: function (params) {
- return UrlGenerator.Random();
- },
- // 您可以根据用于请求的参数将自定义数据传递到请求中.
- // 对于默认方法 "GET" 请求, 这些是附加到 url 的查询参数.
- // 对于 "POST" 请求, 这是将传递到请求中的表单数据.
- // 对于其他请求, 从这里返回的数据应该根据 jQuery 和服务器的期望进行定制.
- //
- // @param params The object containing the parameters used to generate the
- // request.
- // @returns Data to be directly passed into the request.
- data: function (params) {
- var queryParameters = {
- q: params.term
- }
- return queryParameters;
- },
- // 您可以修改从服务器返回的结果, 允许您在最后时刻更改数据, 或者找到传递到 Select2 的响应的正确部分.
- // 请记住, 结果应该作为对象数组传递.
- //
- // @param data 由 jQuery 直接返回的数据.
- // @returns 包含结果数据以及插件使用的任何必需的元数据的对象. 对象应该包含一个数据对象数组, 作为 `results` 键.
- processResults: function (data) {
- return {
- results: data
- };
- },
- // 如果不想使用 jQuery 提供的默认 AJAX 传输函数, 可以使用定制的 AJAX 传输函数.
- //
- // @param params 包含用于生成请求的参数的对象.
- // @param success 一个回调函数, 接收来自请求的结果 "data".
- // @param failure 一个回调函数, 指示请求无法完成.
- // @returns 具有 "abort" 函数的对象, 如果需要可以调用该函数来中止请求.
- transport: function (params, success, failure) {
- var $request = $.ajax(params);
- $request.then(success);
- $request.fail(failure);
- return $request;
- }
- }
4.9. 例子
- $(".js-example-data-ajax").select2({
- ajax: {
- url: "https://api.github.com/search/repositories",
- dataType: 'json',
- delay: 250,
- data: function (params) {
- return {
- q: params.term, // search term
- page: params.page
- };
- },
- processResults: function (data, params) {
- // 将结果解析为 Select2 所期望的格式, 因为我们使用的是自定义格式函数,
- // 不需要修改远程 JSON 数据, 除了表示可以使用无限滚动
- return {
- results: data.items,
- pagination: {
- more: (params.page * 30) < data.total_count
- }
- };
- },
- cache: true
- },
- placeholder: 'Search for a repository',
- escapeMarkup: function (markup) { return markup; }, // 让我们自定义格式化工作
- minimumInputLength: 1,
- templateResult: formatRepo,
- templateSelection: formatRepoSelection
- });
- function formatRepo (repo) {
- if (repo.loading) {
- return repo.text;
- }
- var markup = "<div class='select2-result-repository clearfix'>" +
- "<div class='select2-result-repository__avatar'><img src='" + repo.owner.avatar_url + "'/></div>" +
- "<div class='select2-result-repository__meta'>" +
- "<div class='select2-result-repository__title'>" + repo.full_name + "</div>";
- if (repo.description) {
- markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
- }
- markup += "<div class='select2-result-repository__statistics'>" +
- "<div class='select2-result-repository__forks'><i class='fa fa-flash'></i>" + repo.forks_count + "Forks</div>" +
- "<div class='select2-result-repository__stargazers'><i class='fa fa-star'></i>" + repo.stargazers_count + "Stars</div>" +
- "<div class='select2-result-repository__watchers'><i class='fa fa-eye'></i>" + repo.watchers_count + "Watchers</div>" +
- "</div>" +
- "</div></div>";
- return markup;
- }
- function formatRepoSelection (repo) {
- return repo.full_name || repo.text;
- }
- 5. Arrays(数组)
5.1. 加载数组数据
可以使用 data configuration 选项从本地数组加载下拉选项.
通过为所选值提供选项标记, 可以为数组数据提供初始选择, 类似于为标准选择提供选项标记.
- var data = [
- {
- id: 0,
- text: 'enhancement'
- },
- {
- id: 1,
- text: 'bug'
- },
- {
- id: 2,
- text: 'duplicate'
- },
- {
- id: 3,
- text: 'invalid'
- },
- {
- id: 4,
- text: 'wontfix'
- }
- ];
- $(".js-example-data-array").select2({
- data: data
- })
- $(".js-example-data-array-selected").select2({
- data: data
- })
与 AJAX 数据源提供的项目不同, 以数组形式提供的项目将立即呈现为目标 < select > 控件中的 < option > 元素.
5.2. 与 tags 选项的向后兼容性
在 Select2 v3.5 中, 这个选项被称为 tags. 但是在 4.0 版本中, tags 现在处理标签特性.
对于向后兼容性, tags 选项仍然可以接受对象数组, 在这种情况下, 它们将按照与 data 选项相同的方式处理.
6. Dropdown(下拉)
6.1. 模板
默认情况下, Select2 将在结果列表中显示每个数据对象的文本属性. 下拉菜单中的搜索结果的外观可以使用 templateResult 选项进行定制:
- function formatState (state) {
- if (!state.id) {
- return state.text;
- }
- var baseUrl = "/user/pages/images/flags";
- var $state = $(
- '<span><img src="' + baseUrl + '/' + state.element.value.toLowerCase() + '.png" class="img-flag" /> '+ state.text +'</span>'
- );
- return $state;
- };
- $(".js-example-templating").select2({
- templateResult: formatState
- });
templateResult 函数应该返回包含要显示的文本的字符串, 或者返回包含应该显示的数据的对象(例如 jQuery 对象). 它还可以返回 null, 这将阻止该选项在结果列表中显示.
6.2. Built-in escaping
默认情况下, 假设 templateResult 返回的字符串仅包含文本, 并将通过 escapeMarkup 函数传递, 该函数将剥离任何 HTML 标记.
如果需要用结果模板呈现 HTML, 则必须将呈现的结果封装到 jQuery 对象中. 在本例中, 结果将直接传递给 jQuery.fn.append, 并由 jQuery 直接处理. 任何标记, 如 HTML, 都不会被逃脱, 而是由你来逃避用户提供的任何恶意输入.
6.3. 自动选择
Select2 可以配置为使用 selectOnClose 选项在下拉菜单关闭时自动选择当前突出显示的结果
- $('#mySelect2').select2({
- selectOnClose: true
- });
6.4. 在选择后强制下拉菜单保持打开
选择一个元素时, Select2 将自动关闭下拉菜单, 类似于普通的选择框. 您可以使用 closeOnSelect 选项, 以防止在选择结果时下拉菜单关闭:
- $('#mySelect2').select2({
- closeOnSelect: false
- });
== 注意, 此选项仅适用于多选择控件.==
6.5. 下拉的位置 (Dropdown placement)
默认情况下, Select2 将把下拉菜单附加到主体的末端, 并将它绝对地放置在选择容器的上方或下方.
如果容器下面没有足够的空间, 但是容器上面有足够的空间, Select2 将显示容器上方的下拉菜单.
dropdownParent 选项允许您为要追加的下拉选择一个替代元素:
- $('#mySelect2').select2({
- dropdownParent: $('#myModal')
- });
当试图正确地在模态和其他小容器内渲染 Select2 时, 这是有用的. 如果在 Bootstrap 模式中使用搜索框有困难, 例如, 尝试将 dropdownParent 选项设置为模态元素.
7. 选择
当从下拉菜单中选择一个选项时, Select2 将在容器框中显示所选的值. 默认情况下, 它将显示 Select2 对所选选项的内部表示的文本属性.
7.1. 模板
可以通过使用 templateSelection 配置选项来定制所选结果的外观. 这需要一个回调, 将选择数据对象转换为字符串表示或 jQuery 对象.
- function formatState (state) {
- if (!state.id) {
- return state.text;
- }
- var baseUrl = "/user/pages/images/flags";
- var $state = $(
- '<span><img src="' + baseUrl + '/' + state.element.value.toLowerCase() + '.png" class="img-flag" /> '+ state.text +'</span>'
- );
- return $state;
- };
- $(".js-example-templating").select2({
- templateSelection: formatState
- });
- 7.2. Built-in escaping(内置逃离)
默认情况下, templateSelection 返回的字符串被假定为只包含文本, 并将通过 "escapeMarkup" 函数传递, 该函数将删除任何 HTML 标记.
如果需要使用选择模板呈现 HTML, 则必须将呈现的选择包装在 jQuery 对象中. 在本例中, 选择将直接传递给 jQuery.fn.append, 并由 jQuery 直接处理. 任何标记, 如 HTML, 都不会被转义, 它由您来避免用户提供的任何恶意输入.
7.3. 限制选择的数量
Select2 多值选择框可以设置可以选择的最大选项数量的限制. 下面的 select 用 select2 选项中的 multiple 属性和 maximumSelectionLength 声明.
- $(".js-example-basic-multiple-limit").select2({
- maximumSelectionLength: 2
- });
7.4. 可清除的选择
当设置为 true 时, 当选择一个值时, 将在选择框中显示一个 clear 按钮("x" 图标). 单击 clear 按钮将清除选中的值, 有效地将 select 框重新设置为其占位符值.
- $('select').select2({
- placeholder: 'This is my placeholder',
- allowClear: true
- });
7.5. 动态选择创建
除了预先填充的选项菜单之外, Select2 还可以从用户在搜索框中输入的文本中动态创建新的选项. 这个特性叫做 "tagging". 要启用标记, 请将 tags 选项设置为 true:
- <select class="form-control">
- <option selected="selected">orange</option>
- <option>white</option>
- <option>purple</option>
- </select>
- $(".js-example-tags").select2({
- tags: true
- });
注意, 当标签启用时, 用户可以从已存在的选项中进行选择, 或者通过选择第一个选项来创建一个新选项, 这是用户到目前为止输入到搜索框中的内容.
7.6. 使用多值选择框进行标记
标签也可以在多值选择框中使用. 在下面的示例中, 我们在 Select2 控件上设置 multiple="multiple" 属性, 该控件也启用了 tags: true
<select class="form-control" multiple="multiple">
<option selected="selected">orange</option>
<option>white</option>
<option selected="selected">purple</option>
</select>
尝试输入一个在下拉菜单中没有列出的值 -- 你可以将它作为一个新选项添加进来!
7.7. 标签自动标记
Select2 支持在用户键入搜索字段时自动添加选项的能力. 尝试在下面的搜索字段中键入并输入一个空间或逗号.
可以使用 tokenSeparators 选项指定标记时应该使用的分隔符.
- $(".js-example-tokenizer").select2({
- tags: true,
- tokenSeparators: [',', ' ']
- })
7.8. 创建自定义标签
7.8.1. 标签属性
通过定义一个 createTag 回调, 您可以向新创建的标记添加额外的属性:
- $('select').select2({
- createTag: function (params) {
- var term = $.trim(params.term);
- if (term === '') {
- return null;
- }
- return {
- id: term,
- text: term,
- newTag: true // add additional parameters
- }
- }
- });
7.8.2. 约束标签创建
您可以控制 Sealt2 何时允许用户创建新的标签, 如果添加无效的值, 则通过添加一些逻辑来创建 createTag 返回空值.
- $('select').select2({
- createTag: function (params) {
- // Don't offset to create a tag if there is no @ symbol
- if (params.term.indexOf('@') === -1) {
- // Return null to disable tag creation
- return null;
- }
- return {
- id: params.term,
- text: params.term
- }
- }
- });
7.8.3. 自定义下拉中的标签放置
您可以通过定义一个 insertTag 回调来控制新创建的选项的位置:
- $('select').select2({
- insertTag: function (data, tag) {
- // Insert the tag at the end of the results
- data.push(tag);
- }
- });
- 8. Placeholders
Select2 支持使用占位符配置选项显示 placeholder 值. 占位符值将显示出来, 直到作出选择.
8.1. Text placeholders
最常见的情况是使用文本字符串作为占位符值.
- 8.2. Single select placeholders(单选择占位符)
- HTML:
- <select class="js-example-placeholder-single js-states form-control">
- <option></option>
- </select>
- JS:
- $(".js-example-placeholder-single").select2({
- placeholder: "Select a state",
- allowClear: true
- });
对于单选择, 为了让占位符值出现, 您必须在 < select > 控件中为第一个选项设置一个空白的 < option>. 这是因为浏览器试图在默认情况下选择第一个选项. 如果您的第一个选项是非空的, 浏览器将显示这个而不是占位符.
8.3. Multi-select placeholders(多选择占位符)
对于 multi-selects, 您必须没有空 < option > 元素
- HTML:
- <select class="js-example-placeholder-multiple js-states form-control" multiple="multiple"></select>
- JS:
- $(".js-example-placeholder-multiple").select2({
- placeholder: "Select a state"
- });
Select2 使用多个选择框上的 placeholder 属性, 这需要 IE 10 +. 您可以用 Placeholders.js polyfill 支持旧版本.
8.4. 默认选择占位符
或者, placeholder 选项的值可以是表示默认选择的数据对象(<option>). 在这种情况下, 数据对象的 id 应该与相应的默认选择的 value 相匹配.
- $('select').select2({
- placeholder: {
- id: '-1', // the value of the option
- text: 'Select an option'
- }
- });
当您使用创建自己的 placeholder 选项的框架时, 这是很有用的.
8.5. 使用 AJAX 使用 placeholder
Select2 支持所有配置的占位符, 包括 AJAX. 如果您使用的是单个 select, 那么您仍然需要在空 < option > 中添加.
8.6. 自定义占位符的外表
当在单选择模式中使用 Select2 时, 如果指定占位符选项, 则通过 templateSelection 回调传递占位符选项. 您可以在这个回调中使用一些附加逻辑来检查 id 属性, 并对占位符选项应用另一种转换:
- $('select').select2({
- templateSelection: function (data) {
- if (data.id === '') { // adjust for custom placeholder values
- return 'Custom styled placeholder text';
- }
- return data.text;
- }
- });
8.7. 旧的 Internet Explorer 版本中的占位符
Select2 在多个 select 的输入框上使用本机 X 属性, 旧版本的 Internet Explorer 不支持该属性. 您需要在页面上包含 Placeholders.js, 或者使用完整的构建, 以便将 placeholder 属性支持添加到输入框中.
9. Search
下拉菜单的顶部会自动添加一个搜索框, 用于选择框只允许选择一个选项的情况. 可以使用 Select2 轻松定制搜索框的行为和外观.
9.1. 定制结果如何匹配
当用户通过在搜索框中输入搜索词来过滤结果时, Select2 使用一个内部的 "matcher" 来匹配搜索词与结果. 您可以通过为 matcher 配置选项指定回调来定制 Select2 匹配搜索项的方式.
Select2 将把它内部表示的每个选项传递到这个回调中, 以确定是否应该显示它.
- function matchCustom(params, data) {
- // 如果没有搜索项, 则返回所有数据.
- if ($.trim(params.term) === '') {
- return data;
- }
- // 如果没有 "text" 属性, 不要显示该项
- if (typeof data.text === 'undefined') {
- return null;
- }
- //`params.term` 应该是用于搜索 `data.text` 的术语, 而 Y 应该是显示数据对象的文本
- if (data.text.indexOf(params.term)> -1) {
- var modifiedData = $.extend({}, data, true);
- modifiedData.text += '(matched)';
- // 您可以从这里返回修改后的对象
- // 这包括匹配嵌套数据集中的 "子数据"
- return modifiedData;
- }
- // 如果不应该显示术语, 则返回'null'
- return null;
- }
- $(".js-example-matcher").select2({
- matcher: matchCustom
- });
matcher 只处理本地提供的数据. 例如, 通过一个数组! 当使用远程数据集时, Select2 期望返回的结果已经在服务器端进行了过滤.
9.2. 匹配分组选项
只有一级对象将被传递到 matcher 回调. 如果使用嵌套数据, 则必须遍历 children 数组并分别匹配它们. 这允许在处理嵌套对象时进行更高级的匹配, 允许您随心所欲地处理它们.
此示例仅在字符串开头出现术语时匹配结果:
- function matchStart(params, data) {
- // 如果没有搜索词, 则返回所有数据
- if ($.trim(params.term) === '') {
- return data;
- }
- // 如果没有 "children" 属性, 请跳过.
- if (typeof data.children === 'undefined') {
- return null;
- }
- // `data.children` 包含我们要匹配的实际选项.
- var filteredChildren = [];
- $.each(data.children, function (idx, child) {
- if (child.text.toUpperCase().indexOf(params.term.toUpperCase()) == 0) {
- filteredChildren.push(child);
- }
- });
- // 如果我们匹配时区组的任何子元素, 那么设置组上的匹配子元素并返回 group 对象
- if (filteredChildren.length) {
- var modifiedData = $.extend({}, data, true);
- modifiedData.children = filteredChildren;
- // 您可以从这里返回修改后的对象
- // 这包括在嵌套数据集中匹配 "children"
- return modifiedData;
- }
- // 如果不应该显示术语, 则返回'null'
- return null;
- }
- $(".js-example-matcher-start").select2({
- matcher: matchStart
- });
9.3. 最小搜索词长度
有时, 当处理大型数据集时, 只有当搜索项的长度是一定的时, 才开始过滤结果会更有效. 这在处理远程数据集时非常常见, 因为它只允许使用重要的搜索术语.
您可以使用 X 选项设置最小的搜索项长度:
- $('select').select2({
- minimumInputLength: 3 // 只有当用户输入 3 个或更多字符时才开始搜索
- });
9.4. 最大搜索词长度
在某些情况下, 搜索术语需要限制在一定范围内. Select2 允许限制搜索项的长度, 使其不超过一定的长度.
您可以使用 maximumInputLength 选项限制搜索词的最大长度:
- $('select').select2({
- maximumInputLength: 20 // 只允许最多 20 个字符的术语
- });
9.5. 将搜索框的显示限制为较大的结果集
minimumResultsForSearch 选项确定下拉菜单中显示搜索框所需的初始搜索结果的最小数量.
这个选项对于使用小结果集的本地数据的情况非常有用, 搜索框只会浪费屏幕空间. 将此值设置为 - 1 以永久隐藏搜索框.
- $('select').select2({
- minimumResultsForSearch: 20 // 必须显示至少 20 个结果
- });
9.6. 隐藏搜索框
9.6.1. 单项选择
对于单个选择, Select2 允许使用 minimumResultsForSearch 配置选项隐藏搜索框. 在本例中, 我们使用值 Infinity 告诉 Select2 永远不要显示搜索框.
- $("#js-example-basic-hide-search").select2({
- minimumResultsForSearch: Infinity
- });
9.6.2. 多项选择
对于多选择框, 没有单独的搜索控件. 因此, 要禁用对多选择框的搜索, 需要在打开或关闭下拉菜单时将 disabled 属性设置为 true:
- $('#js-example-basic-hide-search-multi').select2();
- $('#js-example-basic-hide-search-multi').on('select2:opening select2:closing', function( event ) {
- var $searchfield = $(this).parent().find('.select2-search__field');
- $searchfield.prop('disabled', true);
- });
10. 可编程控制
10.1. 添加, 选择或清除项目(Add, select, or clear items)
10.1.1. 在下拉菜单中创建新的选项
可以通过编程方式向 Select2 控件添加新选项, 方法是创建一个新的 Javascript Option 对象并将其附加到控件中:
- var data = {
- id: 1,
- text: 'Barn owl'
- };
- var newOption = new Option(data.text, data.id, false, false);
- $('#mySelect2').append(newOption).trigger('change');
new Option(...)的第三个参数确定项目是否为 "默认选择"; 也就是说, 它为新选项设置 selected 属性. 第四个参数设置选项的实际选择状态 -- 如果设置为 true, 则默认选择新选项.
10.1.2. 如果不存在则创建
如果它已经存在, 您可以使用. find 来选择选项, 否则创建它.
- // 设置值, 必要时创建一个新选项
- if ($('#mySelect2').find("option[value='" + data.id + "']").length) {
- $('#mySelect2').val(data.id).trigger('change');
- } else {
- // 创建 DOM 选项并在默认情况下进行预选择
- var newOption = new Option(data.text, data.id, true, true);
- // 将其附加到 select
- $('#mySelect2').append(newOption).trigger('change');
- }
10.1.3. 选择选项
要以编程方式为 Select2 控件选择选项 / 项, 请使用 jQuery .val()方法:
- $('#mySelect2').val('1'); // 选择值为 "1" 的选项
- $('#mySelect2').trigger('change'); // 通知任何 JS 组件该值已更改
还可以将数组传递给 val 以进行多个选择:
- $('#mySelect2').val(['1', '2']);
- $('#mySelect2').trigger('change'); // 通知任何 JS 组件该值已更改
Select2 将侦听其附加到的 < select > 元素上的更改事件. 当您进行任何需要在 Select2 中反映的外部更改 (例如更改值) 时, 您应该触发此事件.
10.1.4. 在远程(AJAX) Select2 中预先选择选项
对于从 AJAX 源接收数据的 Select2 控件, 使用. val()将不起作用. 选项将不存在, 因为 AJAX 请求在启动控制和 / 或用户开始搜索之前不会被激发. 服务器端过滤和分页会使这一过程更加复杂 -- 不能保证在什么时候将特定的项加载到 Select2 控件中!
因此, 处理此问题的最佳方法是将预先选择的项添加为新选项. 对于远程数据源数据, 这可能涉及在服务器端应用程序中创建一个新的 API 端点, 该端点可以检索单个项:
- // 设置 Select2 控件
- $('#mySelect2').select2({
- ajax: {
- url: '/api/students'
- }
- });
- // 获取预先选择的项, 并添加到控件
- var studentSelect = $('#mySelect2');
- $.ajax({
- type: 'GET',
- url: '/api/students/s/' + studentId
- }).then(function (data) {
- // 创建选项并附加到 Select2
- var option = new Option(data.full_name, data.id, true, true);
- studentSelect.append(option).trigger('change');
- // 手动触发 "select2:select" 事件
- studentSelect.trigger({
- type: 'select2:select',
- params: {
- data: data
- }
- });
- });
注意, 我们手动触发 select2:select 事件并传递整个 data 对象. 这允许其他处理程序访问所选项的其他属性.
10.1.5. 清除选择
您可以通过将控件的值设置为 null 来清除 Select2 控件中的所有当前选择:
$('#mySelect2').val(null).trigger('change');
10.2. 检索选择
有两种方法可以以编程方式访问当前的选择数据: 使用. select2("data")或使用 jQuery 选择器.
10.2.1. 使用数据方法
调用 select2('data')将返回表示当前选择的对象的 JavaScript 数组. 每个对象将包含通过 processResults 和 templateResult 回调传递的源数据对象中的所有属性 / 值.
$('#mySelect2').select2('data');
10.2.2. 使用 jQuery 选择器
还可以通过: selected jQuery 选择器访问选定的项
$('#mySelect2').find(':selected');
可以使用 HTML data-* 属性扩展表示当前选择的 < option > 元素, 以包含来自源数据对象的任意数据:
- $('#mySelect2').select2({
- // ...
- templateSelection: function (data, container) {
- // 为所选选项向 < option > 标记添加自定义属性
- $(data.element).attr('data-custom-attribute', data.customValue);
- return data.text;
- }
- });
- // 检索第一个选定元素的自定义属性值
- $('#mySelect2').find(':selected').data('custom-attribute');
不要依赖于选择的 < option > 元素属性来确定当前选择的项. 当从远程资源选项创建元素时, Select2 不添加 selected 属性.
10.3. Methods
Select2 有几个内置的方法, 允许对组件进行编程控制.
10.3.1. 打开下拉
通过将方法名称传递给. select2(...), 可以调用 Select2 直接处理的方法.
open 方法将导致下拉菜单打开, 显示可选择的选项.
$('#mySelect2').select2('open');
10.3.2. 关闭下拉
close 方法将导致下拉菜单关闭, 隐藏可选选项:
$('#mySelect2').select2('close');
10.3.3. 检查插件是否初始化
要测试 Select2 是否在特定的 DOM 元素上初始化, 可以检查 select2-hidden-accessible 类:
- if ($('#mySelect2').hasClass("select2-hidden-accessible")) {
- // Select2 已经初始化
- }
10.3.4. 销毁 Select2 控制
destroy 方法将从目标元素中删除 Select2 小部件. 它将恢复到标准 select 控件:
$('#mySelect2').select2('destroy');
10.3.5. 事件解脱(Event unbinding)
当您销毁 Select2 控件时, Select2 将只解绑定插件自动绑定的事件. 您在自己的代码中绑定的任何事件, 包括显式绑定的 Select2 事件, 都需要使用. off jQuery 方法手动解除绑定:
- // 设置一个 Select2 控件
- $('#example').select2();
- // 绑定事件
- $('#example').on('select2:select', function (e) {
- console.log('select event');
- });
- // 摧毁 Select2
- $('#example').select2('destroy');
- // 解开事件
- $('#example').off('select2:select');
- 10.4. Events
当使用组件执行不同的操作时, Select2 将触发一些不同的事件, 允许您添加自定义钩子并执行操作. 您还可以使用. trigger 在 Select2 控件上手动触发这些事件.
Event | 描述 |
---|---|
change | 在选择或删除选项时触发。 |
change.select2 | change 的作用域版本。 |
select2:closing | 在下拉菜单关闭之前触发。这个事件是可以避免的。 |
select2:close | 当下拉关闭时触发。select2:closing 在此之前被触发,可以被阻止。 |
select2:opening | 在下拉菜单打开之前触发。这个事件是可以避免的。 |
select2:open | 当下拉菜单打开时触发。select2:opening 在此之前被触发,可以被阻止。 |
select2:selecting | 在选择结果之前触发。这个事件是可以避免的。 |
select2:select | 当选择结果时触发。select2:selecting 在此之前被触发,可以被阻止。 |
select2:unselecting | 在删除选择之前触发。这个事件是可以避免的。 |
select2:unselect | 当选择移除时触发。select2:unselecting 在此之前被触发,可以被阻止。 |
10.4.1. 监听事件
所有公共事件都使用 jQuery 事件系统进行转发, 并在 Select2 所附的 < select > 元素上触发. 您可以使用 jQuery 提供的. on 方法附加到它们:
- $('#mySelect2').on('select2:select', function (e) {
- // Do something
- });
- 10.4.2. Event data
当 select2:select 被触发时, 可以通过 params.data 属性访问选择的数据:
- $('#mySelect2').on('select2:select', function (e) {
- var data = e.params.data;
- console.log(data);
- });
e.params.data 将返回一个包含选择属性的对象. 数据源中提供的选择的任何额外数据也将包含在这个对象中. 例如:
- {
- "id": 1,
- "text": "Tyto alba",
- "genus": "Tyto",
- "species": "alba"
- }
- 10.4.3. Triggering events(触发事件)
您可以使用 jQuery trigger 方法在 Select2 控件上手动触发事件. 但是, 如果您想为事件传递一些数据给任何处理程序, 您需要构造一个新的 jQuery Event 对象并对此进行触发器:
- var data = {
- "id": 1,
- "text": "Tyto alba",
- "genus": "Tyto",
- "species": "alba"
- };
- $('#mySelect2').trigger({
- type: 'select2:select',
- params: {
- data: data
- }
- });
10.4.4. 限制 change 事件的范围
其他组件监听 change 事件或附加具有副作用的自定义事件处理程序是很常见的. 要将范围限制为仅通知 Select2 更改, 请使用. select2 事件名称空间:
- $('#mySelect2').val('US'); // 更改值或对内部状态做一些更改
- $('#mySelect2').trigger('change.select2'); // 只通知 Select2 的更改
11. 国际化
11.1. 消息翻译
必要时, Select2 将向用户显示某些消息. 例如, 当没有找到搜索结果或需要输入更多字符以进行搜索时, 将出现一条消息. 这些消息已经被 Select2 的贡献者翻译成多种语言, 但是您也可以提供自己的翻译.
11.2. 语言文件
Select2 可以从语言文件中加载不同语言的消息翻译. 在使用 Select2 提供的翻译时, 必须确保在 Select2 之后将翻译文件包含在页面中.
当字符串作为语言传入时, Select2 将尝试将其解析为语言文件. 这允许您指定自己的语言文件, 这些文件必须定义为 AMD 模块. 如果找不到语言文件, Select2 将假定它是 Select2 的内置语言之一, 它将尝试为该语言加载翻译.
- $(".js-example-language").select2({
- language: "es"
- });
在初始化 Select2 时, 不需要定义这种语言, 而是可以在任何父元素的 [lang] 属性中定义为[lang="es"].
11.3. 翻译的对象
您也可以通过提供类似于下面的对象来提供您自己的自定义消息:
- language: {
- // 您可以在构建中提供的语言文件中找到所有选项. 它们都必须是返回应该显示的字符串的函数.
- inputTooShort: function () {
- return "You must enter more characters...";
- }
- }
翻译由 select2/translation 模块处理.
11.4. RTL 支持
如果 dir 属性设置在 < select > 或它的任何父属性上, Select2 将在 RTL 网站上工作. 您还可以使用 dir:"rtl" 配置选项初始化 Select2.
- $(".js-example-rtl").select2({
- dir: "rtl"
- });
11.5. 音译支持(变音符号) (Transliteration support (diacritics))
Select2 的默认 matcher 会将修改后的字母转换成 ASCII 码, 这样用户就更容易在国际选择中过滤结果. 在下面的选择中输入 "aero".
- $(".js-example-diacritics").select2();
- 12. Advanced(高级)
- 12.1.Adapters and Decorators(适配器和修饰符)
从 4.0 版本开始, Select2 使用适配器模式作为扩展其特性和行为的强大手段.
大多数内置特性 (如前面章节中描述的) 都是通过内置适配器实现的. 您可以通过实现您自己的适配器来进一步扩展 Select2 的功能.
12.1.1. 适配器接口
所有自定义适配器必须实现 Adapter 接口描述的方法.
此外, 覆盖默认 selectionAdapter 和 dataAdapter 行为的适配器必须实现相应的 SelectionAdapter 和 DataAdapter 接口所描述的其他方法.
12.1.2. Adapter
所有适配器都必须实现 Adapter 接口, Select2 使用该接口为适配器呈现 DOM 元素并绑定任何内部事件:
- // 应该由 Select2 呈现的基本 HTML. 应该返回一个 jQuery 或 DOM 元素, 该元素将被 Select2 自动放置在 DOM 中.
- //
- // @returns jQuery 或 DOM 元素, 包含必须由 Select2 呈现的任何元素
- Adapter.render = function () {
- return $jq;
- };
- // 绑定到任何 Select2 或 DOM 事件.
- //
- // @param container 与 jQuery 元素绑定的 Select2 对象. 您可以使用 "on" 来侦听 Select2 事件, 并使用 "trigger" 方法触发 Select2 事件.
- // @param $container 将在 jQuery DOM 节点中呈现所有默认适配器.
- Adapter.bind = function (container, $container) { };
- // 将 DOM 元素放在 Select2 DOM 容器中, 或者放在另一个位置. 这允许适配器位于 Select2 DOM 之外, 例如在文档末尾或 Select2 DOM 节点中的特定位置.
- //
- // 注意: 在数据适配器上不调用此方法.
- //
- // @param $rendered 从调用 "render" 返回的呈现的 DOM 元素. Select2 可能对它进行了修改, 但是根元素总是相同的.
- // @param $defaultContainer Select2 的默认容器通常将呈现的 DOM 元素放在其中. 对于大多数适配器, 这是 Select2 DOM 元素.
- Adapter.position = function ($rendered, $defaultContainer) { };
- // 销毁已创建的任何事件或 DOM 元素.
- // 在元素上调用 select2("destroy")时调用这个函数.
- Adapter.destroy = function () { };
- 12.1.3. SelectionAdapter
选择是显示给用户的, 以替换标准 < select > 框. 它控制选择选项的显示, 以及任何需要嵌入容器中的其他内容, 例如搜索框.
用于覆盖默认 selectionAdapter 的适配器也必须实现 update 方法:
- // 更新选中的数据.
- //
- // @param data 数据适配器生成的数据对象数组. 如果不应选择对象, 则将传递一个空数组.
- //
- // 注意: 即使 Select2 附加到只接受单个选择的源上, 也始终会向该方法传递数组.
- SelectionAdapter.update = function (data) { };
- 12.1.4. DataAdapter
Select2 使用数据集生成可以选择的可能结果, 以及当前选择的结果.
用于覆盖默认 dataAdapter 的适配器必须实现 current 和 query 方法:
- // 获取当前选择的选项. 当尝试获取 Select2 的初始选择时, 以及当 Select2 需要确定在结果中选择了哪些选项时, 将调用这个函数.
- //
- // @param callback 在检索当前选择时应该调用的函数. 函数的第一个参数应该是一个数据对象数组.
- DataAdapter.current = function (callback) {
- callback(currentData);
- }
- // 获取一组基于传入的参数进行筛选的选项.
- //
- // @param params 包含查询可能受到影响的任何数量的参数的对象. 只有核心参数将被文档化.
- // @param params.term 一个用户提供的术语. 这通常是搜索框的值(如果存在的话), 但也可以是空字符串或空值.
- // @param params.page 应该加载的特定页面. 这通常是在处理远程数据集时提供的, 远程数据集依赖于分页来确定应该显示什么对象.
- // @param callback 应该使用查询结果调用的函数.
- DataAdapter.query = function (params, callback) {
- callback(queryiedData);
- }
- 12.1.5. Decorators
Select2 使用 decorator 通过其配置选项公开适配器的功能.
您可以使用 Select2 提供的 Utils.Decorate 方法向适配器应用 decorator:
- $.fn.select2.amd.require(
- ["select2/utils", "select2/selection/single", "select2/selection/placeholder"],
- function (Utils, SingleSelection, Placeholder) {
- var CustomSelectionAdapter = Utils.Decorate(SingleSelection, Placeholder);
- });
使用 Decorator 或适配器的所有核心选项都将在文档的 "Decorator" 或 "Adapter" 部分明确地声明它. decorator 通常只与特定类型的适配器兼容, 所以请务必注意所提供的适配器.
12.1.6. AMD 的兼容性
您可以在这里找到关于如何将 Select2 与现有的基于 amd 的项目集成的更多信息. 当适配器被自动构造时, Select2 将自动加载一些模块, 因此使用 Select2 并使用自定义 AMD 构建的用户可能需要指定生成到 Select2 模块的路径.
12.2. Built-in adapters(内置的适配器 )
本节描述 Select2 的内置适配器, 以及它们用来公开其功能的 decorator.
12.2.1. Selection
Select2 分别将 SingleSelection 和 MultipleSelection 适配器作为单一和多选择控件的 SelectionAdapter 的默认实现. SingleSelection 和 MultipleSelection 都扩展了基础 BaseSelection 适配器.
来源: http://www.qdfuns.com/article/30225/1117f26e7aa6adbccca5d51d1c5b7196.html