Menu Widget
Categories: Widgets
version added: 1.9
Description: 带有鼠标和键盘交互的用于导航的可主题化菜单。
QuickNavExamples
Options
Methods
- blur
- collapse
- collapseAll
- destroy
- disable
- enable
- expand
- focus
- isFirstItem
- isLastItem
- next
- nextPage
- option
- previous
- previousPage
- refresh
- select
- widget
Events
菜单可以用任何有效的标记创建,只要元素有严格的父/子关系且每个条目都有一个锚。最常用的元素是无序列表(<ul>
):
<ul id="menu">
<li><a href="#">Item 1</a></li>
<li><a href="#">Item 2</a></li>
<li><a href="#">Item 3</a>
<ul>
<li><a href="#">Item 3-1</a></li>
<li><a href="#">Item 3-2</a></li>
<li><a href="#">Item 3-3</a></li>
<li><a href="#">Item 3-4</a></li>
<li><a href="#">Item 3-5</a></li>
</ul>
</li>
<li><a href="#">Item 4</a></li>
<li><a href="#">Item 5</a></li>
</ul>
如果使用一个非 <ul>
/<li>
的结构,为菜单和菜单条目使用相同的元素,请使用 menus
选项来区分两个元素,例如 menus: "div.menuElement"
。
可通过向元素添加 ui-state-disabled
class 来禁用任何菜单条目。
图标(Icons)
为了向菜单添加图标,请在标记中包含图标:
<ul id="menu">
<li><a href="#"><span class="ui-icon ui-icon-disk"></span>Save</a></li>
</ul>
菜单(Menu)会自动向无图标的条目添加必要的内边距。
分隔符(Dividers)
分隔符元素可通过包含未链接的菜单条目来创建,菜单条目只能是空格/破折号:
<ul id="menu">
<li><a href="#">Item 1</a></li>
<li>-</li>
<li><a href="#">Item 2</a></li>
</ul>
键盘交互(Keyboard interaction)
- ENTER/SPACE:调用获得焦点的菜单项的动作,可能会打开一个子菜单。
- UP:移动教导到上一个菜单项。
- DOWN:移动教导到下一个菜单项。
- RIGHT:如果可用,则打开子菜单。
- LEFT:关闭当前子菜单,移动焦点到父菜单项。如果焦点不在子菜单上,则不进行任何操作。
- ESCAPE:关闭当前子菜单,移动焦点到父菜单项。如果焦点不在子菜单上,则不进行任何操作。
输入一个字母,移动焦点到以该字母开头的第一个条目。重复相同的字符会循环显示匹配的条目。在一个时间内输入更多的字符则匹配所输入的字符。
禁用项可获得键盘焦点,但是不允许任何交互。
主题化(Theming)
菜单部件(Menu Widget)使用 jQuery UI CSS 框架 来定义它的外观和感观的样式。如果需要使用菜单指定的样式,则可以使用下面的 CSS class 名称:
ui-menu
:菜单的外层容器。如果菜单包含图标,该元素会另外带有一个ui-menu-icons
class。ui-menu-item
:单个菜单项的容器。ui-menu-icon
:通过icons
选项进行子菜单图标设置。
ui-menu-divider
:菜单项之间的分隔符元素。
依赖(Dependencies)
其他注意事项(Additional Notes:)
- 该部件要求一些功能性的 CSS,否则将无法工作。如果您创建了一个自定义的主题,请使用小部件指定的 CSS 文件作为起点。
Options
disabledType: Boolean
Default: false
如果设置为 true
,则禁用该 menu(菜单)。Code examples:
初始化带有指定 disabled
选项的menu(菜单)
$( ".selector" ).menu({ disabled: true });
在初始化后,获取或设置disabled
选项:
// getter
var disabled = $( ".selector" ).menu( "option", "disabled" );
// setter
$( ".selector" ).menu( "option", "disabled", true );
iconsType: Object
Default: { submenu: "ui-icon-carat-1-e" }
标题要使用的图标,与 jQuery UI CSS 框架提供的图标(Icons) 匹配。设置为 false 则不显示图标。
- submenu (string, default: "ui-icon-carat-1-e")
Code examples:
初始化带有指定 icons
选项的menu(菜单)
$( ".selector" ).menu({ icons: { submenu: "ui-icon-circle-triangle-e" } });
在初始化后,获取或设置icons
选项:
// getter
var icons = $( ".selector" ).menu( "option", "icons" );
// setter
$( ".selector" ).menu( "option", "icons", { submenu: "ui-icon-circle-triangle-e" } );
menusType: String
Default: "ul"
作为menu(菜单)容器的元素的选择器, 包括子菜单。
注意: 初始化后 menus
选项不应该被更改。 现有的子菜单将不会被更新。Code examples:
初始化带有指定 menus
选项的menu(菜单)
$( ".selector" ).menu({ menus: "div" });
获取 menus
选项:
// getter
var menus = $( ".selector" ).menu( "option", "menus" );
positionType: Object
Default: { my: "left top", at: "right top" }
标识建议菜单的位置与相关的 input 元素有关系。of
选项默认为 input 元素,但是您可以指定另一个定位元素。如需了解各种选项的更多细节,请查看 jQuery UI Position。Code examples:
初始化带有指定 position
选项的menu(菜单)
$( ".selector" ).menu({ position: { my: "left top", at: "right-5 top+5" } });
在初始化后,获取或设置position
选项:
// getter
var position = $( ".selector" ).menu( "option", "position" );
// setter
$( ".selector" ).menu( "option", "position", { my: "left top", at: "right-5 top+5" } );
roleType: String
Default: "menu"
自定义用于菜单和菜单项的ARIA roles(愚人码头注:关于ARIA roles)。 在默认情况下菜单项使用"menuitem"
。 设置role
选项为了使"listbox"
使用"option"
作为菜单项。 如果设置为null
, 没有roles将被设置,如果菜单是由被保持焦点另一个元件控制时候,非常有用。
注意: 初始化后role
选项 不应该被更改。 现有(子)菜单和菜单项将不会被更新。Code examples:
初始化带有指定 role
选项的menu(菜单)
$( ".selector" ).menu({ role: null });
获取 role
选项:
// getter
var role = $( ".selector" ).menu( "option", "role" );
Methods
blur( [event ] )Returns: jQuery (plugin only)
从菜单中删除焦点, 重置任何激活样式 和 触发菜单的 blur
事件。
- eventType: Event什么事件触发了菜单失去焦点。
Code examples:
调用 blur 方法:
$( ".selector" ).menu( "blur" );
collapse( [event ] )Returns: jQuery (plugin only)
关闭当前活动的子菜单。
- eventType: Event什么事件触发关闭子菜单
Code examples:
调用 collapse 方法:
$( ".selector" ).menu( "collapse" );
collapseAll( [event ] [, all ] )Returns: jQuery (plugin only)
关闭全部打开的子菜单。
Code examples:
调用 collapseAll 方法:
$( ".selector" ).menu( "collapseAll", null, true );
destroy()Returns: jQuery (plugin only)
完全移除 menu 功能. 这将使元素返回到之前的初始化状态.
- 该方法不接受任何参数。
Code examples:
调用 destroy 方法:
$( ".selector" ).menu( "destroy" );
disable()Returns: jQuery (plugin only)
禁用 menu.
- 该方法不接受任何参数。
Code examples:
调用 disable 方法:
$( ".selector" ).menu( "disable" );
enable()Returns: jQuery (plugin only)
启用 menu.
- 该方法不接受任何参数。
Code examples:
调用 enable 方法:
$( ".selector" ).menu( "enable" );
expand( [event ] )Returns: jQuery (plugin only)
打开当前活动项目下的子菜单下,如果有的话。
- eventType: Event什么时间触发打开子菜单。
Code examples:
调用 expand 方法:
$( ".selector" ).menu( "expand" );
focus( [event ], item )Returns: jQuery (plugin only)
激活一个特定的菜单项, 首先,如果打开存在的任何子菜单,并触发菜单的focus
事件。
Code examples:
调用 focus 方法:
$( ".selector" ).menu( "focus", null, menu.find( ".ui-menu-item:last" ) );
isFirstItem()Returns: jQuery (plugin only)
返回一个布尔值,说明当前活动项目是否菜单的第一项。
- 该方法不接受任何参数。
Code examples:
调用 isFirstItem 方法:
var firstItem = $( ".selector" ).menu( "isFirstItem" );
isLastItem()Returns: jQuery (plugin only)
返回一个布尔值,说明当前活动项目是否菜单的最后一项。
- 该方法不接受任何参数。
Code examples:
调用 isLastItem 方法:
var lastItem = $( ".selector" ).menu( "isLastItem" );
next( [event ] )Returns: jQuery (plugin only)
移动激活状态到下一个菜单项。
- eventType: Event什么事件触发焦点转移。
Code examples:
调用 next 方法:
$( ".selector" ).menu( "next" );
nextPage( [event ] )Returns: jQuery (plugin only)
移动激活状态到第一个菜单项下的可滚动菜单的底部,或最后一个项目,如果不可滚动。
- eventType: Event什么事件触发焦点转移。
Code examples:
调用 nextPage 方法:
$( ".selector" ).menu( "nextPage" );
option( optionName )Returns: Object
获取当前与指定的 optionName
关联的值。
- optionNameType: String要获取值的选项的名称。
Code examples:
调用该方法:
var isDisabled = $( ".selector" ).menu( "option", "disabled" );
option()Returns: PlainObject
获取一个包含键/值对的对象,键/值对表示当前 menu 选项哈希。
- 该方法不接受任何参数。
Code examples:
调用该方法:
var options = $( ".selector" ).menu( "option" );
option( optionName, value )Returns: jQuery (plugin only)
设置与指定的 optionName
关联的 menu 选项的值。
Code examples:
调用该方法:
$( ".selector" ).menu( "option", "disabled", true );
option( options )Returns: jQuery (plugin only)
为 menu 设置一个或多个选项。
- optionsType: Object要设置的 option-value 对。
Code examples:
调用该方法:
$( ".selector" ).menu( "option", { disabled: true } );
previous( [event ] )Returns: jQuery (plugin only)
移动激活状态到上一个菜单项。
- eventType: Event什么事件触发焦点转移。
Code examples:
调用 previous 方法:
$( ".selector" ).menu( "previous" );
previousPage( [event ] )Returns: jQuery (plugin only)
移动激活状态到第一个菜单项下的可滚动菜单的顶部,或第一一个项目,如果不可滚动。
- eventType: Event什么事件触发焦点转移。
Code examples:
调用 previousPage 方法:
$( ".selector" ).menu( "previousPage" );
refresh()Returns: jQuery (plugin only)
初始化还没有被初始化的子菜单和菜单项。 新的菜单项, 包括子菜单可以被添加到菜单 或 所有的菜单的内容可以被替换 然后使用refresh()
方法初始化。
- 该方法不接受任何参数。
Code examples:
调用 refresh 方法:
$( ".selector" ).menu( "refresh" );
select( [event ] )Returns: jQuery (plugin only)
选择当前活动的菜单项, 折叠所有子菜单 并触发菜单中的 select
事件。
- eventType: Event什么事件触发选择。
Code examples:
调用 select 方法:
$( ".selector" ).menu( "select" );
widget()Returns: jQuery
返回一个包含 button 的 jQuery
对象。
- 该方法不接受任何参数。
Code examples:
调用 widget 方法:
var widget = $( ".selector" ).menu( "widget" );
Events
blur( event, ui )Type: menublur
当menu失去焦点时触发这个事件。
Code examples:
初始化带有指定 blur 回调的 menu:
$( ".selector" ).menu({
blur: function( event, ui ) {}
});
绑定一个事件监听器到 menublur 事件:
$( ".selector" ).on( "menublur", function( event, ui ) {} );
create( event, ui )Type: menucreate
当创建 menu 时触发。
注意:ui
对象是空的,这里包含它是为了与其他事件保持一致性。
Code examples:
初始化带有指定 create 回调的 menu:
$( ".selector" ).menu({
create: function( event, ui ) {}
});
绑定一个事件监听器到 menucreate 事件:
$( ".selector" ).on( "menucreate", function( event, ui ) {} );
focus( event, ui )Type: menufocus
当当一个菜单获得焦点或当任意一个菜单项被激活时触发这个事件。
Code examples:
初始化带有指定 focus 回调的 menu:
$( ".selector" ).menu({
focus: function( event, ui ) {}
});
绑定一个事件监听器到 menufocus 事件:
$( ".selector" ).on( "menufocus", function( event, ui ) {} );
select( event, ui )Type: menuselect
当才安被选中的时候触发该事件。
Code examples:
初始化带有指定 select 回调的 menu:
$( ".selector" ).menu({
select: function( event, ui ) {}
});
绑定一个事件监听器到 menuselect 事件:
$( ".selector" ).on( "menuselect", function( event, ui ) {} );
Example:
一个简单的 jQuery UI Menu
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>menu demo</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<style>
.ui-menu {
width: 200px;
}
</style>
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<ul id="menu">
<li><a href="#">Item 1</a></li>
<li><a href="#">Item 2</a></li>
<li><a href="#">Item 3</a>
<ul>
<li><a href="#">Item 3-1</a></li>
<li><a href="#">Item 3-2</a></li>
<li><a href="#">Item 3-3</a></li>
<li><a href="#">Item 3-4</a></li>
<li><a href="#">Item 3-5</a></li>
</ul>
</li>
<li><a href="#">Item 4</a></li>
<li><a href="#">Item 5</a></li>
</ul>
<script>
$( "#menu" ).menu();
</script>
</body>
</html>