Ajax (远程数据)

Select2使用jQuery的AJAX方法内置了AJAX支持。在此示例中,我们可以使用GitHub的API搜索存储库:

在您的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 功能或 transport 您指定的功能。

仅对于远程数据源,Select2不会创建新的<option> 元素,直到第一次选择该项目。这样做是出于性能原因。一次 <option> 已创建,即使以后更改选择,它也将保留在DOM中。

请求参数

当用户打开控件时,Select2将向指定的URL发出请求(除非有一个minimumInputLength设置为Select2选项),并在每次用户在搜索框中键入内容时再次输入。默认情况下,它将发送以下查询字符串参数:

  • term : 搜索框中的当前搜索词。
  • q : 包含与相同的内容term.
  • _type: “请求类型”。通常为 query,但更改为query_append 分页请求。
  • page : 要请求的当前页码。仅发送用于分页(无限滚动)搜索。

例如,Select2可能发出如下请求: https://api.github.com/search/repositories?term=sel&_type=query&q=sel.

有时,您可能需要向请求中添加其他查询参数。您可以通过覆盖请求来修改随请求发送的参数 ajax.data 选项:

$('#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;
    }
  }
});

转换响应数据

您可以使用 ajax.processResults 选项,将API返回的数据转换为Select2期望的格式:

$('#mySelect2').select2({
  ajax: {
    url: '/example/api',
    processResults: function (data) {
      // 将响应对象的顶级键从“items”转换为“results”
      return {
        results: data.items
      };
    }
  }
});

Select2期望在服务器端过滤来自远程端点的结果。请参阅此注释,以了解为何选择此实现。如果无法进行服务器端筛选,那么您可能会对使用Select2对数据数组的支持感兴趣。

默认(预选)值

您可能希望为从AJAX请求接收其数据的Select2控件设置预选的默认值。

要提供默认选择,您可以添加一个<option> 对于包含应显示的值和文本的每个选择:

<select class="js-example-data-ajax form-control">
  <option value="3620194" selected="selected">select2/select2</option>
</select>

要以编程方式实现这一目标,您将需要 创建并添加一个新的 Option.

分页

Select2支持开箱即用的远程数据源分页(“无限滚动”)。要使用此功能,您的远程数据源必须能够响应分页的请求(服务器端框架(如Laravel和UserFrosting)具有此内置功能)。

要使用分页,您必须告诉Select2通过覆盖以下内容向请求添加任何必要的分页参数: ajax.data 设置。当前要检索的页面存储在 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=[page]
      return query;
    }
  }
});

Select2将期望 pagination.more 响应中的值。more 应该为 truefalse告诉Select2是否有更多页面可用于检索结果:

{
  "results": [
    {
      "id": 1,
      "text": "Option 1"
    },
    {
      "id": 2,
      "text": "Option 2"
    }
  ],
  "pagination": {
    "more": true
  }
}

如果您的服务器端代码未生成 pagination.more 属性,您可以使用 processResults 从其他可用信息中生成此值。例如,假设您的API返回一个 count_filtered 值,它告诉您数据集中有多少个总计(未分页)结果。如果您知道分页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
        }
    };
}

限速请求

您可以让Select2等待,直到用户输入完搜索字词后才触发AJAX请求。只需使用ajax.delay 配置选项,用于告诉Select2用户停止输入后发送请求之前要等待多长时间:

$('#mySelect2').select2({
  ajax: {
    delay: 250 // 在触发请求之前等待250毫秒
  }
});

动态网址

如果您的搜索结果没有单个网址,或者您需要调用一个函数来确定要使用的网址,则可以为ajax.url 用于生成网址的选项。当前的搜索查询将通过 params 选项:

$('#mySelect2').select2({
  ajax: {
    url: function (params) {
      return '/some/url/' + params.term;
    }
  }
});

替代运输方式

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);
    }
  }
});

jQuery $.ajax 选项

传递给的所有选项ajax 将直接传递给 $.ajax 执行AJAX请求的函数。

Select2将拦截一些自定义选项,使您可以在请求进行时自定义:

ajax: {
  // 在发出ajax请求之前等待用户停止键入的毫秒数。
  delay: 250,
  // 您可以根据传递到请求中的参数来定制url。如果您使用的框架具有基于JavaScript的函数来生成要向其发出请求的url,那么这很有用。
  //
  // @param params包含用于生成请求。
  // @returns 请求应发送到的url。
  url: function (params) {
    return UrlGenerator.Random();
  },
  // 您可以根据用于发出请求的参数将自定义数据传递到请求中。对于默认方法“GET”请求,这些是附加到url的查询参数。对于“POST”请求,这是将传递到请求中的表单数据。对于其他请求,从这里返回的数据应该根据jQuery和您的服务器的期望进行定制。
  //
  // @param params包含用于生成请求
  // @returns 直接传递到请求中的数据。
  data: function (params) {
    var queryParameters = {
      q: params.term
    }

    return queryParameters;
  },
  // 您可以修改从服务器返回的结果,允许您在最后一分钟对数据进行更改,或者找到要传递给Select2的响应的正确部分。请记住,结果应该作为对象数组传递。
  //
  // @param 数据jQuery直接返回的数据。
  // @returns 一个包含结果数据以及任何必需的对象
  //   插件使用的元数据。对象应包含一个数据对象数组作为“results”键。
  processResults: function (data) {
    return {
      results: data
    };
  },
  //如果不想使用jQuery提供的默认传输函数,可以使用自定义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;
  }
}

其他例子

该代码为本章开头提供的Github示例提供了动力: