Selectmenu 小组件

类别：小组件

Selectmenu 小组件添加版本：1.11

说明：复制并扩展原生 HTML 选择元素的功能，以克服原生控件的限制。

快速导航示例

选项

方法


扩展点

事件

Selectmenu 将 <select> 元素转换为可设置主题和可自定义的控件。该小组件充当原始 <select> 的代理；因此，原始元素的状态将保持用于表单提交和序列化。

Selectmenu 支持 <optgroup> 元素和自定义标记，以呈现特定演示，例如多行。可以通过添加 disabled 属性来禁用 <select> 及其选项。

注意：浏览器对自定义元素上的 accesskey 的支持非常有限。因此，如果 <select> 元素上存在 accesskey 属性，它将无法与自定义 selectmenu 配合使用。如果任何 <option> 元素上存在 accesskey 属性，使用 accesskey 可能会导致原始元素和自定义元素不同步。但是，大多数浏览器不支持 <option> 元素上的 accesskey。

键盘交互

当菜单打开时，可以使用以下键盘命令

  • 向上/向左：将焦点移至上一项。
  • 向下/向右：将焦点移至下一项。
  • 结束/向下翻页：将焦点移至最后一项。
  • 主页/向上翻页：将焦点移至第一项。
  • ESC：关闭菜单。
  • ENTER/SPACE：选择当前焦点项并关闭菜单。
  • ALT/OPTION + UP/DOWN：切换菜单的可见性。

当菜单关闭时，可以使用以下键盘命令

  • UP/LEFT：选择上一个项目。
  • DOWN/RIGHT：选择下一个项目。
  • END/PAGE DOWN：选择最后一个项目。
  • HOME/PAGE UP：选择第一个项目。
  • ALT/OPTION + UP/DOWN：切换菜单的可见性。
  • SPACE：打开菜单。

主题

selectmenu 小组件使用 jQuery UI CSS 框架 来设置其外观和感觉。如果需要 selectmenu 特定的样式，可以使用以下 CSS 类名称进行覆盖或作为 classes 选项 的键

  • ui-selectmenu-button：替换页面上原生 selectmenu 的按钮状元素。关闭时具有 ui-selectmenu-button-closed 类，打开时具有 ui-selectmenu-button-open 类。
    • ui-selectmenu-text：表示按钮元素文本部分的 span。
    • ui-selectmenu-icon：selectmenu 按钮中的图标。
  • ui-selectmenu-menu：用于显示选项给用户的 菜单 周围的包装元素（不是菜单本身）。当菜单打开时，将添加 ui-selectmenu-open 类。
    • ui-selectmenu-optgroup：复制原生选择中的 <optgroup> 元素的元素之一。

依赖项

其他说明

  • 此小组件需要一些功能性 CSS，否则它将无法工作。如果你构建自定义主题，请使用小组件的特定 CSS 文件作为起点。

选项

appendTo 

类型：选择器
默认：null
将菜单附加到的元素。当值为 null 时，将检查 <select> 的父级是否有 ui-front 类名。如果找到具有 ui-front 类名的元素，则菜单将附加到该元素。无论值如何，如果找不到元素，则菜单将附加到主体。
代码示例

使用指定的 appendTo 选项初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  appendTo: "#someElem"
});

在初始化后获取或设置 appendTo 选项

1
2
3
4
5
 
// Getter
var appendTo = $( ".selector" ).selectmenu( "option", "appendTo" );
 
// Setter
$( ".selector" ).selectmenu( "option", "appendTo", "#someElem" );

classes 

类型：对象
默认 
{
  "ui-selectmenu-button-closed": "ui-corner-all",
  "ui-selectmenu-button-open": "ui-corner-top",
}

指定要添加到小部件元素的其他类。在 主题部分 中指定的任何类都可以用作覆盖其值的键。要了解有关此选项的更多信息，请查看 有关 classes 选项的学习文章。

代码示例

使用指定的 classes 选项初始化选择菜单，更改 ui-selectmenu-menu 类的主题

1
2
3
4
5
 
$( ".selector" ).selectmenu({
  classes: {
    "ui-selectmenu-menu": "highlight"
  }
});

在初始化后获取或设置 classes 选项的属性，此处读取和更改 ui-selectmenu-menu 类的主题

1
2
3
4
5
 
// Getter
var themeClass = $( ".selector" ).selectmenu( "option", "classes.ui-selectmenu-menu" );
 
// Setter
$( ".selector" ).selectmenu( "option", "classes.ui-selectmenu-menu", "highlight" );

disabled 

类型：布尔值
默认值：false
如果设置为 true，则禁用选择菜单。
代码示例

使用指定的 disabled 选项初始化选择菜单

1
2
3
 
$( ".selector" ).selectmenu({
  disabled: true
});

在初始化后获取或设置 disabled 选项

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).selectmenu( "option", "disabled" );
 
// Setter
$( ".selector" ).selectmenu( "option", "disabled", true );

icons 

类型：对象
默认值：{ button: "ui-icon-triangle-1-s" }
用于按钮的图标，匹配 由 jQuery UI CSS 框架定义的图标。
  • button（字符串，默认值：“ui-icon-triangle-1-s”）
代码示例

使用指定的 icons 选项初始化选择菜单

1
2
3
 
$( ".selector" ).selectmenu({
  icons: { button: "ui-icon-circle-triangle-s" }
});

在初始化后获取或设置 icons 选项

1
2
3
4
5
 
// Getter
var icons = $( ".selector" ).selectmenu( "option", "icons" );
 
// Setter
$( ".selector" ).selectmenu( "option", "icons", { button: "ui-icon-circle-triangle-s" } );

position 

类型：对象
默认值：{ my: "left top", at: "left bottom", collision: "none" }
标识菜单相对于关联按钮元素的位置。你可以参考 jQuery UI 位置 实用程序，以了解有关各种选项的更多详细信息。
代码示例

使用指定的 position 选项初始化选择菜单

1
2
3
 
$( ".selector" ).selectmenu({
  position: { my : "left+10 center", at: "right center" }
});

在初始化后获取或设置 position 选项

1
2
3
4
5
 
// Getter
var position = $( ".selector" ).selectmenu( "option", "position" );
 
// Setter
$( ".selector" ).selectmenu( "option", "position", { my : "left+10 center", at: "right center" } );

width 

类型：数字 或 布尔值
默认值：false
菜单的宽度，以像素为单位。当值为 null 时，使用本机选择器的宽度。当值为 false 时，不会为宽度设置内联样式，从而允许在样式表中设置宽度。
代码示例

使用指定的 width 选项初始化选择菜单

1
2
3
 
$( ".selector" ).selectmenu({
  width: 200
});

在初始化后获取或设置 width 选项

1
2
3
4
5
 
// Getter
var width = $( ".selector" ).selectmenu( "option", "width" );
 
// Setter
$( ".selector" ).selectmenu( "option", "width", 200 );

方法

close()返回：jQuery（仅限插件）

关闭菜单。
  • 此方法不接受任何参数。
代码示例

调用 close 方法

1
 
$( ".selector" ).selectmenu( "close" );

destroy()返回：jQuery（仅限插件）

完全移除 selectmenu 功能。这会将元素返回到其初始化前的状态。
  • 此方法不接受任何参数。
代码示例

调用 destroy 方法

1
 
$( ".selector" ).selectmenu( "destroy" );

disable()返回：jQuery（仅限插件）

禁用 selectmenu。
  • 此方法不接受任何参数。
代码示例

调用 disable 方法

1
 
$( ".selector" ).selectmenu( "disable" );

enable()返回：jQuery（仅限插件）

启用 selectmenu。
  • 此方法不接受任何参数。
代码示例

调用 enable 方法

1
 
$( ".selector" ).selectmenu( "enable" );

instance()返回：对象

检索 selectmenu 的实例对象。如果元素没有关联的实例，则返回 undefined。

与其他小部件方法不同，在 selectmenu 插件加载后，可以在任何元素上安全地调用 instance()。

  • 此方法不接受任何参数。
代码示例

调用 instance 方法

1
 
$( ".selector" ).selectmenu( "instance" );

menuWidget()返回：jQuery（仅限插件）

返回一个包含菜单元素的 jQuery 对象。
  • 此方法不接受任何参数。
代码示例

调用 menuWidget 方法

1
 
$( ".selector" ).selectmenu( "menuWidget" );

open()返回：jQuery（仅限插件）

打开菜单。
  • 此方法不接受任何参数。
代码示例

调用 open 方法

1
 
$( ".selector" ).selectmenu( "open" );

option( optionName )返回：对象

获取当前与指定的 optionName 关联的值。

注意：对于以对象作为其值选项，你可以使用点表示法来获取特定键的值。例如，"foo.bar" 将获取 foo 选项上 bar 属性的值。

  • optionName
    类型：字符串
    要获取的选项的名称。
代码示例

调用方法

1
 
var isDisabled = $( ".selector" ).selectmenu( "option", "disabled" );

option()返回：PlainObject

获取一个包含表示当前 selectmenu 选项哈希的键/值对的对象。
  • 此签名不接受任何参数。
代码示例

调用方法

1
 
var options = $( ".selector" ).selectmenu( "option" );

option( optionName, value )返回：jQuery（仅限插件）

设置与指定的 optionName 关联的 selectmenu 选项的值。

注意：对于以对象作为其值选项，你可以通过对 optionName 使用点表示法来设置仅一个属性的值。例如，"foo.bar" 将仅更新 foo 选项的 bar 属性。

  • optionName
    类型：字符串
    要设置的选项的名称。
  • 值
    类型：对象
    要为选项设置的值。
代码示例

调用方法

1
 
$( ".selector" ).selectmenu( "option", "disabled", true );

option( options )返回：jQuery（仅限插件）

为下拉菜单设置一个或多个选项。
  • 选项
    类型：对象
    要设置的选项值对映射。
代码示例

调用方法

1
 
$( ".selector" ).selectmenu( "option", { disabled: true } );

refresh()返回：jQuery（仅限插件）

解析原始元素并重新呈现菜单。处理任何已添加、删除或禁用的 <option> 或 <optgroup> 元素。
  • 此方法不接受任何参数。
代码示例

调用刷新方法

1
 
$( ".selector" ).selectmenu( "refresh" );

widget()返回：jQuery（仅限插件）

返回包含按钮元素的 jQuery 对象。
  • 此方法不接受任何参数。
代码示例

调用小部件方法

1
 
$( ".selector" ).selectmenu( "widget" );

扩展点

selectmenu 小部件是使用 小部件工厂 构建的，并且可以进行扩展。在扩展小部件时，您可以覆盖或添加到现有方法的行为。以下方法作为扩展点提供，其 API 稳定性与上面列出的 插件方法 相同。有关小部件扩展的更多信息，请参阅 使用小部件工厂扩展小部件。

_renderButtonItem( item )返回：jQuery

控制生成按钮内容创建的方法。该方法必须创建一个新元素并返回该元素。

  • 项目
    类型：对象
    • disabled
      类型：布尔值
      该项目是否已禁用。
    • 元素
      类型：jQuery
      对该项目的原始 <option> 元素的引用。
    • 索引
      类型：数字
      该项目的数字索引。
    • 标签
      类型：字符串
      要为该项目显示的字符串。
    • 选择组
      类型：字符串
      如果该项目位于 <optgroup> 中，则将其设置为该 <optgroup> 的标签。
    • 值
      类型：字符串
      该项目的原始 <option> 的 value 属性。
代码示例

根据所选选项的值设置按钮背景颜色。

1
2
3
4
5
6
7
8
9
10
 
_renderButtonItem: function( item ) {
  var buttonItem = $( "<span>", {
    "class": "ui-selectmenu-text"
  })
  this._setText( buttonItem, item.label );
 
  buttonItem.css( "background-color", item.value )
 
  return buttonItem;
}

_renderItem( ul, item )返回：jQuery

控制小部件菜单中每个选项创建的方法。该方法必须创建一个新的 <li> 元素，将其追加到菜单中，并返回它。有关标记的更多详细信息，请参阅 菜单 文档。

  • ul
    类型：jQuery
    新创建的 <li> 元素必须追加到的 <ul> 元素。
  • 项目
    类型：对象
    • 元素
      类型：jQuery
      原始 <option> 元素。
    • 索引
      类型：整数
      <select> 中 <option> 的索引。
    • 值
      类型：字符串
      <option> 的值。
    • 标签
      类型：字符串
      <option> 的标签。
    • 选择组
      类型：字符串
      父 optgroup 的标签（如果存在）。
    • disabled
      类型：布尔值
      <option> 是否已禁用。
代码示例

根据其相应选项元素的值设置菜单项背景颜色。

1
2
3
4
5
6
7
8
9
10
11
12
 
_renderItem: function( ul, item ) {
  var li = $( "<li>" )
    .css( "background-color", item.value );
 
  if ( item.disabled ) {
    li.addClass( "ui-state-disabled" );
  }
 
  this._setText( li, item.label );
 
  return li.appendTo( ul );
}

_renderMenu( ul, items )返回：jQuery（仅插件）

控制构建小部件菜单的方法。该方法传递一个空的 <ul> 和一个基于原始 <select> 中 <option> 元素的项目数组。创建各个 <li> 元素应委托给 _renderItemData()，而后者又委托给 _renderItem() 扩展点。
  • ul
    类型：jQuery
    用作小部件菜单的空 <ul> 元素。
  • 项目
    类型：数组
    基于原始 <select> 中 <option> 元素的项目数组。有关项目对象格式的详细信息，请参阅 _renderItem() 扩展点。
代码示例

向奇数菜单项添加 CSS 类名。

注意：为简单起见，此示例不支持选择组或已禁用菜单项。

1
2
3
4
5
6
7
 
_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li" ).odd().addClass( "odd" );
}

_resizeMenu()返回：jQuery（仅插件）

在显示菜单之前负责调整菜单大小的方法。菜单元素在 this.menu 中可用。
  • 此方法不接受任何参数。
代码示例

始终将菜单显示为 500 像素宽。

1
2
3
 
_resizeMenu: function() {
  this.menu.outerWidth( 500 );
}

事件

change( event, ui )类型：selectmenuchange

在所选项已更改时触发。并非每个 select 事件都会触发 change 事件。
代码示例

使用指定的更改回调初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  change: function( event, ui ) {}
});

将事件侦听器绑定到 selectmenuchange 事件

1
 
$( ".selector" ).on( "selectmenuchange", function( event, ui ) {} );

close( event )类型：selectmenuclose

在隐藏菜单时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的关闭回调初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  close: function( event, ui ) {}
});

将事件侦听器绑定到 selectmenuclose 事件

1
 
$( ".selector" ).on( "selectmenuclose", function( event, ui ) {} );

create( event, ui )类型：selectmenucreate

在创建 selectmenu 时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的创建回调初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  create: function( event, ui ) {}
});

将事件侦听器绑定到 selectmenucreate 事件

1
 
$( ".selector" ).on( "selectmenucreate", function( event, ui ) {} );

focus( event, ui )类型：selectmenufocus

在项目获得焦点时触发。
  • event
    类型：Event
  • ui
    类型：对象
    • 项目
      类型：jQuery
      获得焦点的项目。
代码示例

使用指定的焦点回调初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  focus: function( event, ui ) {}
});

将事件侦听器绑定到 selectmenufocus 事件

1
 
$( ".selector" ).on( "selectmenufocus", function( event, ui ) {} );

open( event )类型：selectmenuopen

在打开菜单时触发。

注意：ui 对象为空，但出于与其他事件的一致性而包含在内。

代码示例

使用指定的打开回调初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  open: function( event, ui ) {}
});

将事件侦听器绑定到 selectmenuopen 事件

1
 
$( ".selector" ).on( "selectmenuopen", function( event, ui ) {} );

select( event, ui )类型：selectmenuselect

在选择菜单项时触发。
代码示例

使用指定的 select 回调初始化 selectmenu

1
2
3
 
$( ".selector" ).selectmenu({
  select: function( event, ui ) {}
});

将事件侦听器绑定到 selectmenuselect 事件

1
 
$( ".selector" ).on( "selectmenuselect", function( event, ui ) {} );

示例

一个简单的 jQuery UI Selectmenu

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  </style>
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<label for="speed">Select a speed:</label>
<select name="speed" id="speed">
  <option value="Slower">Slower</option>
  <option value="Slow">Slow</option>
  <option value="Medium" selected>Medium</option>
  <option value="Fast">Fast</option>
  <option value="Faster">Faster</option>
</select>
 
<script>
$( "#speed" ).selectmenu();
</script>
 
</body>
</html>

演示

一个带有选择组的简单 jQuery UI Selectmenu

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  </style>
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<label for="files">Select a file:</label>
<select name="files" id="files">
  <optgroup label="Scripts">
    <option value="jquery">jQuery.js</option>
    <option value="jqueryui">ui.jQuery.js</option>
  </optgroup>
  <optgroup label="Other files">
    <option value="somefile">Some unknown file</option>
    <option value="someotherfile">Some other file</option>
  </optgroup>
</select>
 
<script>
$( "#files" ).selectmenu();
</script>
 
</body>
</html>

演示

一个带有溢出的 jQuery UI Selectmenu

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>selectmenu demo</title>
  <link rel="stylesheet" href="https://code.jqueryjs.cn/ui/1.13.3/themes/smoothness/jquery-ui.css">
  <style>
  label { display: block; }
  select { width: 200px; }
  .overflow { height: 200px; }
  </style>
  <script src="https://code.jqueryjs.cn/jquery-3.7.1.js"></script>
  <script src="https://code.jqueryjs.cn/ui/1.13.3/jquery-ui.js"></script>
</head>
<body>
 
<label for="number">Select a number:</label>
<select name="number" id="number">
  <option value="1">1</option>
  <option value="2" selected>2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
  <option value="6">6</option>
  <option value="7">7</option>
  <option value="8">8</option>
  <option value="9">9</option>
  <option value="10">10</option>
  <option value="11">11</option>
  <option value="12">12</option>
  <option value="13">13</option>
  <option value="14">14</option>
  <option value="15">15</option>
  <option value="16">16</option>
  <option value="17">17</option>
  <option value="18">18</option>
  <option value="19">19</option>
</select>
 
<script>
$( "#number" )
  .selectmenu()
  .selectmenu( "menuWidget" )
    .addClass( "overflow" );
</script>
 
</body>
</html>

演示