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

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

网上找了很多类似的插件，主要有下面种：

第一个组件是写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
第二个组件也是在github上面找的——bootstrap-multiselect。这个组件风格和第一个非常相似，文档也挺全面。

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

bootstrap-multiselect文档以及Demo：http://davidstutz.github.io/bootstrap-multiselect
Jquery的Autocomplete插件：https://github.com/agarzola/jQueryAutocompletePlugin
一个不怎么为人所知的Jquery插件：marcopolo.js https://github.com/jstayton/jquery-marcopolo

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

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

这个插件的环境要求：

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格式的搜索结果：

到这一步，功能上就都是先了，但是其丑无比，你还需要加入下面的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">

  Your search could not be completed at this time.

</li>
```
Setting this option to null or returning false suppresses the message from being displayed.

Default:
```
return 'Your search could not be completed at this time.';
```
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">

  Your search must be at least 3 characters.

</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 'Your search must be at least ' + minChars + 'characters.';
```
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">

  No results for something.

</li>
```
Setting this option to null or returning false suppresses the message from being displayed.

Default:
```
return 'No results for ' + q + '.';
```
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');
```

原文地址：bootstrap风格的multiselect插件——类似邮箱收件人样式