bootstrap风格的multiselect插件——类似邮箱收件人样式

时间：2023-03-08 20:41:47

在开发颗粒云邮箱的过程中，遇到了一个前端的问题，就是邮箱收件人的那个multiselect的input输入框。不仅能够多选，还要能够支持ajax搜索，把联系人搜索出来。就是类似下面的这个东西：

bootstrap风格的multiselect插件——类似邮箱收件人样式网上找了很多类似的插件，主要有下面种：

  1. 第一个组件是写bootstrap table的主人公wenzhixin封装的一个组件——multiple-select。这个组件风格简单、文档全、功能强大。但是觉得它选中的效果不太好。关于它的效果展示，我们放在后面。还是给出对应的文档API。

    Multiple-Select源码主页：https://github.com/wenzhixin/multiple-select

    Multiple-Select文档以及Demo：http://wenzhixin.net.cn/p/multiple-select/docs/index.html?locale=zh_CN

  2. 第二个组件也是在github上面找的——bootstrap-multiselect。这个组件风格和第一个非常相似，文档也挺全面。

    bootstrap-multiselect源码主页：https://github.com/davidstutz/bootstrap-multiselect

    bootstrap-multiselect文档以及Demo：http://davidstutz.github.io/bootstrap-multiselect

  3. Jquery的Autocomplete插件：https://github.com/agarzola/jQueryAutocompletePlugin

  4. 一个不怎么为人所知的Jquery插件：marcopolo.js  https://github.com/jstayton/jquery-marcopolo

颗粒云邮箱采用的是上面提到的第四种marcopolo.js来实现多选输入框的。先看看效果图，做得比较丑：

bootstrap风格的multiselect插件——类似邮箱收件人样式

bootstrap风格的multiselect插件——类似邮箱收件人样式

你觉得丑不是因为人家插件的问题，纯属本人的问题……

这个插件的环境要求：

  • jQuery >= 1.4.3

  • jQuery UI Widget >= 1.8.21 (included in minified build)

  • All modern browsers, including IE >= 6

使用该插件你只需要在页面引入如下文件（资源文件自己去github下载，上面给出了地址）

<script src="jquery.min.js"></script>

<script src="jquery.marcopolo.min.js"></script>

然后在HTML代码中添加一个input输入框：

<input type="text" name="userSearch" id="userSearch">

然后加入下面这段JS：

$('#userSearch').marcoPolo({

  url: '/users/search',

  formatItem: function (data, $item) { 

      return data.first_name + ' ' + data.last_name;

  },

  onSelect: function (data, $item) {

      window.location = data.profile_url;

  }

});

上面的url就是你ajax搜索的时候，服务器的响应地址。服务端应该返回json格式的搜索结果：

bootstrap风格的multiselect插件——类似邮箱收件人样式

到这一步，功能上就都是先了，但是其丑无比，你还需要加入下面的CSS来美化一下：

/* Ordered list for displaying selected items. */

div.mf_container ol.mf_list {

    display: inline;

}

/* Selected item, regardless of state (highlighted, selected). */

div.mf_container ol.mf_list li.mf_item {

    border: 1px solid #C0C0C0;

    cursor: pointer;

    display: inline-block;

    margin: 2px;

    padding: 4px 4px 5px;

}

/* Selected item that's highlighted by mouseover. */

div.mf_container ol.mf_list li.mf_item.mf_highlighted {

    background-color: #E0E0E0;

}

/* Selected item that's selected by click or keyboard. */

div.mf_container ol.mf_list li.mf_item.mf_selected {

    background-color: #C0C0C0;

}

/* Remove link. */

div.mf_container ol.mf_list li.mf_item a.mf_remove {

    color: #E0E0E0;

    margin-left: 10px;

    text-decoration: none;

}

/* Remove link that's highlighted. */

div.mf_container ol.mf_list li.mf_item.mf_highlighted a.mf_remove {

    color: #FFFFFF;

}

/* Remove link that's selected. */

div.mf_container ol.mf_list li.mf_item.mf_selected a.mf_remove {

    color: #FFFFFF;

}

/* Actual input, styled to be invisible within the container. */

div.mf_container input.mf_input {

    border: 0;

    font: inherit;

    font-size: 100%;

    margin: 2px;

    outline: none;

    padding: 4px;

}

下面附上github上的英文文档，英文好的同学可以完善更多的功能配置：

Options

All options are optional, although url is usually specified unless the input field is in a form by itself (in which case the form'saction attribute can be used).

  • cache boolean

    Whether to cache query results. The cache is shared by all instances, which is a big advantage when many of the same field type appear on the same page. For example, a tags field that's repeated for every record on a page.

    Default: true

  • compare boolean, string

    Whether to compare the selected item against items displayed in the results list. The selected item is highlighted if a match is found, instead of the first item in the list (highlight option must be enabled). Set this option to true if the data is a string; otherwise, specify the data object attribute name to compare on.

    Default: false

  • data object, string, function

    Additional data to be sent in the request query string. (Note: The query string parameter that is set with the input value (param option) will overwrite the value in the data object if an attribute with the same name exists.)

    Default: {}

    When a function is used, it's called for every request, allowing the data to be dynamic. An object must be returned.

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Return: object of additional data.

    • q string Requested input value.

  • delay integer

    The number of milliseconds to delay before firing a request after a change is made to the input value. This helps prevent an ajax request on every keystroke from overwhelming the server and slowing down the page.

    Default: 250

  • hideOnSelect boolean

    Whether to hide the results list when an item is selected. Interesting things can be done when this is set to false, such as hiding and showing certain items when other items are selected. The results list is still hidden when the input is blurred for any other reason.

    Default: true

  • highlight boolean

    Whether to automatically highlight an item when the results list is displayed. Usually it's the first item, but it could be the previously selected item if compare is specified.

    Default: true

  • label selector, jQuery object, DOM element, null

    Positioning a label over an input is a common design pattern (sometimes referred to as overlabel) that unfortunately doesn't work so well with all of the input focus/blur events that occur with autocomplete. With this option, however, the hiding/showing of the label is handled internally to provide a built-in solution to the problem. The label receives the classmp_label.

    Default: null

  • minChars integer

    The minimum number of characters required before a request is fired. See the formatMinChars callback to format the (optional) message displayed when this value is not reached.

    Default: 1

  • param string

    The name of the query string parameter that is set with the input value.

    Default: q

  • required boolean

    Whether to clear the input value when no selection is made from the results list. This happens when the input is blurred, usually by clicking or tabbing out of the field.

    Default: false

  • selectable selector

    The list items to make selectable. For example, say you add the class header to a number of list items (in the formatItemcallback) that you want to act as non-selectable headers. They can be excluded with the selector :not(.header). Selectable items receive the class mp_selectable.

    Default: *

  • selected object, null

    Prime the input with a selected item. onSelect is called just as if the item were selected from the results list.

    Default: null

  • submitOnEnter boolean

    Whether to allow the browser's default behavior of submitting the form on ENTER.

    Default: false

  • url string, null

    The URL to GET request for the results, which must be an array of strings or JSON. If no URL is set, the parent form'saction attribute value is used if one exists. q is added to the query string with the input value, along with any additionaldata.

    Default: null

Callbacks

Formatting

  • formatData (data) function, null

    Format the raw data that's returned from the ajax request. Useful for further filtering the data or returning the array of results that's embedded deeper in the object.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Return: array of objects to use as the data.

    • data array, object Data returned from the request.

  • formatError ($item, jqXHR, textStatus, errorThrown) function, null

    Format the text that's displayed when the ajax request fails. The message is displayed in a list item with the classmp_error:

    <li class="mp_error">
    
  <em>Your search could not be completed at this time.</em>
    
</li>

    Setting this option to null or returning false suppresses the message from being displayed.

    Default:

    return '<em>Your search could not be completed at this time.</em>';

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Return: string, DOM element, or jQuery object to use as the message.

    • $item jQuery object List item to display the message.

    • jqXHR object or XMLHTTPRequest in jQuery 1.4.x.

    • textStatus string Error status of the request.

    • errorThrown string HTTP error status.

  • formatItem (data, $item) function

    Format the display of each item in the results list. By default, the title or name value of the data object is displayed. The returned value is added to a list item with the class mp_item:

    <li class="mp_item">The Title of Something</li>

    Default:

    return data.title || data.name;

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Return: string, DOM element, or jQuery object to use as the display.

    • data string, object Data returned from the request.

    • $item jQuery object List item to display the result.

  • formatMinChars (minChars, $item) function, null

    Format the text that's displayed when the minimum number of characters (specified with the minChars option) hasn't been reached. The message is displayed in a list item with the class mp_min_chars:

    <li class="mp_min_chars">
    
  <em>Your search must be at least <strong>3</strong> characters.</em>
    
</li>

    Setting this option to null or returning false suppresses the message from being displayed. It is also not displayed when there is no input value.

    Default:

    return '<em>Your search must be at least <strong>' + minChars + '</strong>characters.</em>';

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Return: string, DOM element, or jQuery object to use as the message.

    • minChars integer Minimum number of characters required.

    • $item jQuery object List item to display the message.

  • formatNoResults (q, $item) function, null

    Format the text that's displayed when there are no results returned for the requested input value. The message is displayed in a list item with the class mp_no_results:

    <li class="mp_no_results">
    
  <em>No results for <strong>something</strong>.</em>
    
</li>

    Setting this option to null or returning false suppresses the message from being displayed.

    Default:

    return '<em>No results for <strong>' + q + '</strong>.</em>';

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Return: string, DOM element, or jQuery object to use as the message.

    • q string Requested input value.

    • $item jQuery object List item to display the message.

Events

  • onBlur () function, null

    Called when the user is finished interacting with the autocomplete interface, not just the text input, which loses and gains focus on a results list mouse click.

    Default: null

    Parameters: none

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopoloblur event:

    $(selector).on('marcopoloblur', function (event) { … });

  • onChange (q) function, null

    Called when the input value changes.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopolochange event:

    $(selector).on('marcopolochange', function (event, q) { … });

    • q string Changed input value.

  • onError ($item, jqXHR, textStatus, errorThrown) function, null

    Called when the ajax request fails.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopoloerror event:

    $(selector).on('marcopoloerror', function (event, $item, jqXHR, textStatus, errorThrown) { … });

    • $item jQuery object List item to display the message.

    • jqXHR object or XMLHTTPRequest in jQuery 1.4.x.

    • textStatus string Error status of the request.

    • errorThrown string HTTP error status.

  • onFocus () function, null

    Called when the text input receives focus. This is different than the standard focus event on the text input, however, as this callback does not fire when a results list item is selected via mouse click, which causes the text input to blur and immediately gain focus again.

    Default: null

    Parameters: none

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopolofocus event:

    $(selector).on('marcopolofocus', function (event) { … });

  • onMinChars (minChars, $item) function, null

    Called when the minimum number of characters (specified with the minChars option) hasn't been reached by the end of the delay.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopolominchars event:

    $(selector).on('marcopolominchars', function (event, minChars, $item) { … });

    • minChars integer Minimum number of characters required.

    • $item jQuery object List item to display the message.

  • onNoResults (q, $item) function, null

    Called when there are no results returned for the request.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopolonoresults event:

    $(selector).on('marcopolonoresults', function (event, q, $item) { … });

    • q string Requested input value.

    • $item jQuery object List item to display the message.

  • onRequestBefore () function, null

    Called before the ajax request is made. Useful for showing a loading spinner if the request is going to take some time.

    Default: null

    Parameters: none

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopolorequestbefore event:

    $(selector).on('marcopolorequestbefore', function (event) { … });

  • onRequestAfter (jqXHR, textStatus) function, null

    Called after the ajax request completes (success or error). Useful for hiding a loading spinner that's shown inonRequestBefore.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopolorequestafter event:

    $(selector).on('marcopolorequestafter', function (event, jqXHR, textStatus) { … });

    • jqXHR object or XMLHTTPRequest in jQuery 1.4.x.

    • textStatus string Status of the request.

  • onResults (data) function, null

    Called when there are results to be displayed.

    Default: null

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopoloresults event:

    $(selector).on('marcopoloresults', function (event, data) { … });

    • data array Data returned from the request.

  • onSelect (data, $item, initial) function, null

    Called when an item is selected from the results list or an initial value (see Setting an Initial Value). By default, the title orname value of the data object is used to populate the input value.

    Default:

    this.val(data.title || data.name);

    Parameters:

    this: jQuery object Text input (no need to wrap like $(this)).

    Event: You can also bind to the marcopoloselect event:

    $(selector).on('marcopoloselect', function (event, data, $item, initial) { … });

    • data string, object Data returned from the request.

    • $item jQuery object, null Selected results list item. null if selected option used.

    • initial boolean Whether this is an initial value.

Methods

  • change

    Programmatically change the input value without triggering a search request (use the search method for that). If the value is different than the current input value, the onChange callback is fired.

    Example:

    $('#userSearch').marcoPolo('change', 'Wilson');

    Parameters:

    • q string New input value.

  • destroy

    Remove the autocomplete functionality and return the selected input fields to their original state.

    Example:

    $('#userSearch').marcoPolo('destroy');

  • list

    Get the results list element.

    Example:

    $('#userSearch').marcoPolo('list');

  • option

    Get or set one or more options.

    Example:

    Get a specific option:

    $('#userSearch').marcoPolo('option', 'url');

    Get the entire options object:

    $('#userSearch').marcoPolo('option');

    Set a specific option:

    $('#userSearch').marcoPolo('option', 'url', '/new/url');

    Set multiple options:

    $('#userSearch').marcoPolo('option', {
    
  url: '/new/url',  onSelect: function (data, $item) { … }
    
});

    Parameters:

    • nameOrValues string, object Optional options to get or set.

    • value mixed Optional option value to set.

  • search

    Programmatically trigger a search request using the existing input value or a new one. The input receives focus to allow for keyboard navigation.

    Example:

    Trigger a search on the existing input value:

    $('#userSearch').marcoPolo('search');

    Trigger a search on a new value:

    $('#userSearch').marcoPolo('search', 'Wilson');

    Parameters:

    • q string Optional new input value to search on.

  • select

    Set the currently selected data, just as if the user clicked or keyboard selected an item from the results list. The onSelectcallback is fired.

    Example:

    $('#userSearch').marcoPolo('select', { first_name: 'Lindsay', … });

    Parameters:

    • data string, object Data of the selected item.

  • selected

    Get the currently selected data (string, object, or null if not set).

    Example:

    $('#userSearch').marcoPolo('selected');