select2 4.0 中文API (基于翻译软件翻译,如有问题欢迎指出修正)

原创 Shawe 译文 select2 400阅读 2018-07-26 15:11:59 举报

官方API链接:链接标题

select2 4.0.3

1. select2 api参数的文档

属性类型默认描述
widthstringresolve支持对容器宽度的定制
ajaxobjectnull提供对ajax数据源的支持
allowClearbooleanfalse提供对可清除选择的支持
closeOnSelectbooleantrue控制下拉菜单是否在选择后关闭
dataarray of objectsnull允许从数组中呈现下拉菜单选项
dataAdapterSelectAdapter用于覆盖内置DataAdapter
debugbooleanfalse用于覆盖内置DataAdapter
disabledbooleanfalse当设置为true时,select控件将被禁用
dropdownAdapterDropdownAdapter用于覆盖内置的DropdownAdapter
dropdownParentjQuery选择器或DOM节点$(document.body)允许您定制下拉菜单的位置
escapeMarkupcallbackUtils.escapeMarkup处理由自定义模板提供的内容的自动转义
initSelectioncallback该选项在Select2 v4.0中被弃用,并将在v4.1中删除
languagestring or objectEnglishTranslation指定用于Select2消息的语言
matcher一个回调,获取搜索params和数据对象处理自定义搜索匹配
maximumInputLengthint0可能为搜索词提供的最大字符数
maximumSelectionLengthint0可在多选择控件中选择的最大项数。如果该选项的值小于1,则所选项的数量将不受限制
minimumInputLengthint0开始搜索所需的最小字符数
minimumResultsForSearchint0显示搜索框所需的最小结果数
placeholderstring or objectnull指定控件的占位符
query一个函数参数(including a callback)Query该选项在Select2 v4.0中被弃用,并将在v4.1中删除
resultsAdapterResultsAdapter用于覆盖内置的ResultsAdapter
selectionAdapter用于覆盖内置SelectionAdapter
selectOnClosebooleanfalse当下拉关闭时,实现自动选择
sortercallback
tagsboolean / array of objectsfalse用于支持自由文本响应
templateResultcallback定制搜索结果的方式
templateSelectioncallback定制选择的方式
themestringdefault允许你设置主题
tokenizercallback一个回调,它处理自由文本条目的自动标记化
tokenSeparatorsarray[]应该用作令牌分隔符的字符列表

2. 外观

2.1. 禁用select2

2.2. 禁用select2的选项(disabled: true)

2.3. 宽度

Select2将尽可能地匹配原始元素的宽度。有时这并不完美,在这种情况下,您可以手动设置宽度配置选项:

描述
'element'使用来自任何适用的CSS规则的计算元素宽度。
'style'宽度由select元素的style属性决定。如果没有找到样式属性,则返回null作为宽度。
'resolve'使用样式属性值(如果可用),根据需要返回到计算元素宽度。
'<value>'有效的CSS值可以作为字符串传递(例如宽度:'80%')。

3. Select2数据格式

Select2可以作为下拉选项呈现从数组或远程数据源(AJAX)以编程方式提供的数据。为了实现这一点,Select2需要一个非常特定的数据格式。这种格式由一个JSON对象组成,该对象包含由结果键键入的对象数组。

每个对象至少应该包含一个id和一个text属性。与数据对象一起传递的任何附加参数都将包含在Select2公开的数据对象中。
如果您想要使用“无限滚动”功能,那么响应对象也可以包含分页数据。这应该在分页键下指定。

3.1. 选择和禁用的选项

您还可以为该数据结构中的选项提供已选择和禁用的属性。例如:

在这种情况下,将预先选择选项2,并禁用选项3。

3.2. 将数据转换为所需的格式

3.2.1. 生成id属性

Select2要求使用id属性惟一地标识结果列表中显示的选项。如果您使用id(如pk)以外的属性来惟一地标识一个选项,那么您需要将您的旧属性映射到id,然后再将其传递给Select2。

如果您无法在服务器上执行此操作,或者您处于无法更改API的情况,您可以在将API传递给Select2之前使用JavaScript执行此操作

3.2.2. 生成text属性

就像使用id属性一样,Select2要求为选项显示的文本存储在text属性中。您可以使用以下JavaScript从任何现有属性映射此属性。

4. Ajax(远程数据)

Select2内置了AJAX支持,使用jQuery的AJAX方法。

HTML:

Javascript:

您可以使用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修改随请求发送的参数。

4.2. 转换响应数据

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

4.3. 默认选中值

您可能希望为Select2控件设置一个预先选择的默认值,该控件接收来自AJAX请求的数据。

要提供默认选择,您可以为每个包含应该显示的值和文本的选择包含一个<option>.

要以编程方式实现这一点,您将需要创建并附加一个新<option>。

4.4. Pagination(分页)

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

要使用分页,必须告诉Select2通过覆盖ajax向请求添加任何必要的分页参数。数据设置。要检索的当前页存储在params.page属性中。

Select2将期望响应中有一个pagination.more值。more的值应该是true或false,这将告诉Select2是否有更多页面的结果可供检索。

如果服务器端代码没有在响应中生成pagination.more属性,那么可以使用processResults从其他可用信息中生成这个值。

例如,假设你的API返回一个count_filtered值告诉你总共有多少(unpaginated)结果中可用数据集。如果你知道你的分页的API返回一次10个结果,您可以使用此连同count_filtered的价值来计算pagination.more的值。

4.5. Rate-limiting 请求

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

4.6. 简化动态网址

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

4.7. 选择运输方法(Alternative transport methods)

Select2使用ajax.transport中定义的传输方法向API发送请求。默认情况下,这种传输方法是jQuery.ajax,但是它可以很容易被覆盖:

4.8. jQuery $.ajax 选项

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

Select2将拦截一些自定义选项,允许您在发出请求时进行自定义:

4.9. 例子

5. Arrays(数组)

5.1. 加载数组数据

可以使用data configuration选项从本地数组加载下拉选项。

通过为所选值提供选项标记,可以为数组数据提供初始选择,类似于为标准选择提供选项标记。

与AJAX数据源提供的项目不同,以数组形式提供的项目将立即呈现为目标<select>控件中的<option>元素。

5.2. 与tags选项的向后兼容性

在Select2 v3.5中,这个选项被称为tags。但是在4.0版本中,tags现在处理标签特性。

对于向后兼容性,tags选项仍然可以接受对象数组,在这种情况下,它们将按照与data选项相同的方式处理。

6. Dropdown(下拉)

6.1. 模板

默认情况下,Select2将在结果列表中显示每个数据对象的文本属性。下拉菜单中的搜索结果的外观可以使用templateResult选项进行定制:

templateResult函数应该返回包含要显示的文本的字符串,或者返回包含应该显示的数据的对象(例如jQuery对象)。它还可以返回null,这将阻止该选项在结果列表中显示。

6.2. Built-in escaping

默认情况下,假设templateResult返回的字符串仅包含文本,并将通过escapeMarkup函数传递,该函数将剥离任何HTML标记。

如果需要用结果模板呈现HTML,则必须将呈现的结果封装到jQuery对象中。在本例中,结果将直接传递给jQuery.fn.append,并由jQuery直接处理。任何标记,如HTML,都不会被逃脱,而是由你来逃避用户提供的任何恶意输入。

6.3. 自动选择

Select2可以配置为使用selectOnClose选项在下拉菜单关闭时自动选择当前突出显示的结果

6.4. 在选择后强制下拉菜单保持打开

选择一个元素时,Select2将自动关闭下拉菜单,类似于普通的选择框。您可以使用closeOnSelect选项,以防止在选择结果时下拉菜单关闭:

==注意,此选项仅适用于多选择控件。==

6.5. 下拉的位置 (Dropdown placement)

默认情况下,Select2将把下拉菜单附加到主体的末端,并将它绝对地放置在选择容器的上方或下方。

如果容器下面没有足够的空间,但是容器上面有足够的空间,Select2将显示容器上方的下拉菜单。

dropdownParent选项允许您为要追加的下拉选择一个替代元素:

当试图正确地在模态和其他小容器内渲染Select2时,这是有用的。如果在Bootstrap模式中使用搜索框有困难,例如,尝试将dropdownParent选项设置为模态元素。

7. 选择

当从下拉菜单中选择一个选项时,Select2将在容器框中显示所选的值。默认情况下,它将显示Select2对所选选项的内部表示的文本属性。

7.1. 模板

可以通过使用templateSelection配置选项来定制所选结果的外观。这需要一个回调,将选择数据对象转换为字符串表示或jQuery对象。

7.2. Built-in escaping(内置逃离)

默认情况下,templateSelection返回的字符串被假定为只包含文本,并将通过“escapeMarkup”函数传递,该函数将删除任何HTML标记。

如果需要使用选择模板呈现HTML,则必须将呈现的选择包装在jQuery对象中。在本例中,选择将直接传递给jQuery.fn.append,并由jQuery直接处理。任何标记,如HTML,都不会被转义,它由您来避免用户提供的任何恶意输入。

7.3. 限制选择的数量

Select2多值选择框可以设置可以选择的最大选项数量的限制。下面的select用select2选项中的multiple属性和maximumSelectionLength声明。

7.4. 可清除的选择

当设置为true时,当选择一个值时,将在选择框中显示一个clear按钮(“x”图标)。单击clear按钮将清除选中的值,有效地将select框重新设置为其占位符值。

7.5. 动态选择创建

除了预先填充的选项菜单之外,Select2还可以从用户在搜索框中输入的文本中动态创建新的选项。这个特性叫做“tagging”。要启用标记,请将tags选项设置为true:

注意,当标签启用时,用户可以从已存在的选项中进行选择,或者通过选择第一个选项来创建一个新选项,这是用户到目前为止输入到搜索框中的内容。

7.6. 使用多值选择框进行标记

标签也可以在多值选择框中使用。在下面的示例中,我们在Select2控件上设置multiple="multiple"属性,该控件也启用了tags: true

尝试输入一个在下拉菜单中没有列出的值——你可以将它作为一个新选项添加进来!

7.7. 标签自动标记

Select2支持在用户键入搜索字段时自动添加选项的能力。尝试在下面的搜索字段中键入并输入一个空间或逗号。

可以使用tokenSeparators选项指定标记时应该使用的分隔符。

7.8. 创建自定义标签

7.8.1. 标签属性

通过定义一个createTag回调,您可以向新创建的标记添加额外的属性:

7.8.2. 约束标签创建

您可以控制Sealt2何时允许用户创建新的标签,如果添加无效的值,则通过添加一些逻辑来创建createTag返回空值。

7.8.3. 自定义下拉中的标签放置

您可以通过定义一个insertTag回调来控制新创建的选项的位置:

8. Placeholders

Select2支持使用占位符配置选项显示placeholder值。占位符值将显示出来,直到作出选择。

8.1. Text placeholders

最常见的情况是使用文本字符串作为占位符值。

8.2. Single select placeholders(单选择占位符)

HTML:

JS:

对于单选择,为了让占位符值出现,您必须在<select>控件中为第一个选项设置一个空白的<option>。这是因为浏览器试图在默认情况下选择第一个选项。如果您的第一个选项是非空的,浏览器将显示这个而不是占位符。

8.3. Multi-select placeholders(多选择占位符)

对于multi-selects,您必须没有空<option>元素
HTML:

JS:

Select2使用多个选择框上的placeholder属性,这需要IE 10 +。您可以用Placeholders.js polyfill支持旧版本。

8.4. 默认选择占位符

或者,placeholder选项的值可以是表示默认选择的数据对象(<option>)。在这种情况下,数据对象的id应该与相应的默认选择的value相匹配。

当您使用创建自己的placeholder选项的框架时,这是很有用的。

8.5. 使用AJAX使用placeholder

Select2支持所有配置的占位符,包括AJAX。如果您使用的是单个select,那么您仍然需要在空<option>中添加。

8.6. 自定义占位符的外表

当在单选择模式中使用Select2时,如果指定占位符选项,则通过templateSelection回调传递占位符选项。您可以在这个回调中使用一些附加逻辑来检查id属性,并对占位符选项应用另一种转换:

8.7. 旧的Internet Explorer版本中的占位符

Select2在多个select的输入框上使用本机X属性,旧版本的Internet Explorer不支持该属性。您需要在页面上包含Placeholders.js,或者使用完整的构建,以便将placeholder属性支持添加到输入框中。

9. Search

下拉菜单的顶部会自动添加一个搜索框,用于选择框只允许选择一个选项的情况。可以使用Select2轻松定制搜索框的行为和外观。

9.1. 定制结果如何匹配

当用户通过在搜索框中输入搜索词来过滤结果时,Select2使用一个内部的“matcher”来匹配搜索词与结果。您可以通过为matcher配置选项指定回调来定制Select2匹配搜索项的方式。

Select2将把它内部表示的每个选项传递到这个回调中,以确定是否应该显示它。

matcher只处理本地提供的数据。例如,通过一个数组!当使用远程数据集时,Select2期望返回的结果已经在服务器端进行了过滤。

9.2. 匹配分组选项

只有一级对象将被传递到matcher回调。如果使用嵌套数据,则必须遍历children数组并分别匹配它们。这允许在处理嵌套对象时进行更高级的匹配,允许您随心所欲地处理它们。

此示例仅在字符串开头出现术语时匹配结果:

9.3. 最小搜索词长度

有时,当处理大型数据集时,只有当搜索项的长度是一定的时,才开始过滤结果会更有效。这在处理远程数据集时非常常见,因为它只允许使用重要的搜索术语。

您可以使用X选项设置最小的搜索项长度:

9.4. 最大搜索词长度

在某些情况下,搜索术语需要限制在一定范围内。Select2允许限制搜索项的长度,使其不超过一定的长度。

您可以使用maximumInputLength选项限制搜索词的最大长度:

9.5. 将搜索框的显示限制为较大的结果集

minimumResultsForSearch选项确定下拉菜单中显示搜索框所需的初始搜索结果的最小数量。

这个选项对于使用小结果集的本地数据的情况非常有用,搜索框只会浪费屏幕空间。将此值设置为-1以永久隐藏搜索框。

9.6. 隐藏搜索框

9.6.1. 单项选择

对于单个选择,Select2允许使用minimumResultsForSearch配置选项隐藏搜索框。在本例中,我们使用值Infinity告诉Select2永远不要显示搜索框。

9.6.2. 多项选择

对于多选择框,没有单独的搜索控件。因此,要禁用对多选择框的搜索,需要在打开或关闭下拉菜单时将disabled属性设置为true:

10. 可编程控制

10.1. 添加、选择或清除项目(Add, select, or clear items)

10.1.1. 在下拉菜单中创建新的选项

可以通过编程方式向Select2控件添加新选项,方法是创建一个新的Javascript Option对象并将其附加到控件中:

new Option(...)的第三个参数确定项目是否为“默认选择”;也就是说,它为新选项设置selected属性。第四个参数设置选项的实际选择状态——如果设置为true,则默认选择新选项。

10.1.2. 如果不存在则创建

如果它已经存在,您可以使用.find来选择选项,否则创建它。

10.1.3. 选择选项

要以编程方式为Select2控件选择选项/项,请使用jQuery .val()方法:

还可以将数组传递给val以进行多个选择:

Select2将侦听其附加到的<select>元素上的更改事件。当您进行任何需要在Select2中反映的外部更改(例如更改值)时,您应该触发此事件。

10.1.4. 在远程(AJAX) Select2中预先选择选项

对于从AJAX源接收数据的Select2控件,使用.val()将不起作用。选项将不存在,因为AJAX请求在启动控制和/或用户开始搜索之前不会被激发。服务器端过滤和分页会使这一过程更加复杂——不能保证在什么时候将特定的项加载到Select2控件中!

因此,处理此问题的最佳方法是将预先选择的项添加为新选项。对于远程数据源数据,这可能涉及在服务器端应用程序中创建一个新的API端点,该端点可以检索单个项:

注意,我们手动触发select2:select事件并传递整个data对象。这允许其他处理程序访问所选项的其他属性。

10.1.5. 清除选择

您可以通过将控件的值设置为null来清除Select2控件中的所有当前选择:

10.2. 检索选择

有两种方法可以以编程方式访问当前的选择数据:使用.select2(“data”)或使用jQuery选择器。

10.2.1. 使用数据方法

调用select2('data')将返回表示当前选择的对象的JavaScript数组。每个对象将包含通过processResults和templateResult回调传递的源数据对象中的所有属性/值。

10.2.2. 使用jQuery选择器

还可以通过:selected jQuery选择器访问选定的项

可以使用HTML data-*属性扩展表示当前选择的<option>元素,以包含来自源数据对象的任意数据:

不要依赖于选择的<option>元素属性来确定当前选择的项。当从远程资源选项创建元素时,Select2不添加selected属性。

10.3. Methods

Select2有几个内置的方法,允许对组件进行编程控制。

10.3.1. 打开下拉

通过将方法名称传递给.select2(...),可以调用Select2直接处理的方法。

open方法将导致下拉菜单打开,显示可选择的选项。

10.3.2. 关闭下拉

close方法将导致下拉菜单关闭,隐藏可选选项:

10.3.3. 检查插件是否初始化

要测试Select2是否在特定的DOM元素上初始化,可以检查select2-hidden-accessible类:

10.3.4. 销毁Select2控制

destroy方法将从目标元素中删除Select2小部件。它将恢复到标准select控件:

10.3.5. 事件解脱(Event unbinding)

当您销毁Select2控件时,Select2将只解绑定插件自动绑定的事件。您在自己的代码中绑定的任何事件,包括显式绑定的Select2事件,都需要使用.off jQuery方法手动解除绑定:

10.4. Events

当使用组件执行不同的操作时,Select2将触发一些不同的事件,允许您添加自定义钩子并执行操作。您还可以使用.trigger在Select2控件上手动触发这些事件。

Event描述
change在选择或删除选项时触发。
change.select2change的作用域版本。
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方法附加到它们:

10.4.2. Event data

当select2:select被触发时,可以通过params.data属性访问选择的数据:

e.params.data将返回一个包含选择属性的对象。数据源中提供的选择的任何额外数据也将包含在这个对象中。例如:

10.4.3. Triggering events(触发事件)

您可以使用jQuery trigger方法在Select2控件上手动触发事件。但是,如果您想为事件传递一些数据给任何处理程序,您需要构造一个新的jQuery Event对象并对此进行触发器:

10.4.4. 限制change事件的范围

其他组件监听change事件或附加具有副作用的自定义事件处理程序是很常见的。要将范围限制为仅通知Select2更改,请使用.select2事件名称空间:

11. 国际化

11.1. 消息翻译

必要时,Select2将向用户显示某些消息。例如,当没有找到搜索结果或需要输入更多字符以进行搜索时,将出现一条消息。这些消息已经被Select2的贡献者翻译成多种语言,但是您也可以提供自己的翻译。

11.2. 语言文件

Select2可以从语言文件中加载不同语言的消息翻译。在使用Select2提供的翻译时,必须确保在Select2之后将翻译文件包含在页面中。

当字符串作为语言传入时,Select2将尝试将其解析为语言文件。这允许您指定自己的语言文件,这些文件必须定义为AMD模块。如果找不到语言文件,Select2将假定它是Select2的内置语言之一,它将尝试为该语言加载翻译。

在初始化Select2时,不需要定义这种语言,而是可以在任何父元素的[lang]属性中定义为[lang="es"]。

11.3. 翻译的对象

您也可以通过提供类似于下面的对象来提供您自己的自定义消息:

翻译由select2/translation模块处理。

11.4. RTL支持

如果dir属性设置在<select>或它的任何父属性上,Select2将在RTL网站上工作。您还可以使用dir:“rtl”配置选项初始化Select2。

11.5. 音译支持(变音符号) (Transliteration support (diacritics))

Select2的默认matcher会将修改后的字母转换成ASCII码,这样用户就更容易在国际选择中过滤结果。在下面的选择中输入“aero”。

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元素并绑定任何内部事件:

12.1.3. SelectionAdapter

选择是显示给用户的,以替换标准<select>框。它控制选择选项的显示,以及任何需要嵌入容器中的其他内容,例如搜索框。

用于覆盖默认selectionAdapter的适配器也必须实现update方法:

12.1.4. DataAdapter

Select2使用数据集生成可以选择的可能结果,以及当前选择的结果。
用于覆盖默认dataAdapter的适配器必须实现current和query方法:

12.1.5. Decorators

Select2使用decorator通过其配置选项公开适配器的功能。

您可以使用Select2提供的Utils.Decorate方法向适配器应用decorator:

使用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适配器。

评论 ( 0 )
最新评论
暂无评论

赶紧努力消灭 0 回复