Menu Widget

Categories: Widgets

version added: 1.9

Description: 带有鼠标和键盘交互的用于导航的可主题化菜单。

QuickNavExamples

Options

• disabled
• icons
• menus
• position
• role

Methods

• blur
• collapse
• collapseAll
• destroy
• disable
• enable
• expand
• focus
• isFirstItem
• isLastItem
• next
• nextPage
• option
• previous
• previousPage
• refresh
• select
• widget

Events

• blur
• create
• focus
• select

菜单可以用任何有效的标记创建，只要元素有严格的父/子关系且每个条目都有一个锚。最常用的元素是无序列表（<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）

• UI 核心（UI Core）
• 部件库（Widget Factory）
• 定位（Position）

其他注意事项（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)

关闭全部打开的子菜单。

• eventType: Event什么事件触发关闭子菜单。
• allType: Boolean表示所有子菜单是否应该被关闭 或 只有子菜单中包括的菜单 或 包含触发事件的目标元素。

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事件。

• eventType: Event什么事件触发了菜单项获得焦点。
• itemType: jQuery要获取焦点/激活的菜单项

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 选项的值。

• optionNameType: String要设置的选项的名称。
• valueType: Object要为选项设置的值。

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失去焦点时触发这个事件。

• eventType: Event
• uiType: Object
  • itemType: jQuery当前激活的菜单项。

Code examples:

初始化带有指定 blur 回调的 menu：

$( ".selector" ).menu({
  blur: function( event, ui ) {}
});

绑定一个事件监听器到 menublur 事件：

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

create( event, ui )Type: menucreate

当创建 menu 时触发。

• eventType: Event
• uiType: Object

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

Code examples:

初始化带有指定 create 回调的 menu：

$( ".selector" ).menu({
  create: function( event, ui ) {}
});

绑定一个事件监听器到 menucreate 事件：

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

focus( event, ui )Type: menufocus

当当一个菜单获得焦点或当任意一个菜单项被激活时触发这个事件。

• eventType: Event
• uiType: Object
  • itemType: jQuery当前激活的菜单项。

Code examples:

初始化带有指定 focus 回调的 menu：

$( ".selector" ).menu({
  focus: function( event, ui ) {}
});

绑定一个事件监听器到 menufocus 事件：

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

select( event, ui )Type: menuselect

当才安被选中的时候触发该事件。

• eventType: Event
• uiType: Object
  • itemType: jQuery当前激活的菜单项。

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>