jQuery UI Menu Widget

By:
On:
In: Widgets
Tagged: , , , , , , ,

前几天我看到商业周刊的囚犯的两难这本书介绍，标题这样写“母亲、爱人同时有难，只能择一的情况下，你该就谁？”这样的赛局理论，我也曾用于婚姻的路上，不过一开始老婆不选我，选母亲，我差一点离开她，后来因为我的坚持庆幸她改变选择而成功。今天我在读ASP.NET AJAX Control慨然叹曰: 既生瑜，何生亮?作者也是跟着jQuery私奔为爱走天涯了，朋友们你是否也在挣扎要学C或jQuery呢？今天我会劝你看看jQuery吧，因为实在是快，而我们要继续分享jQuery UI的选单小工具或小组件(widget)。

[adsense][/adsense]

重點整理

Menu Widget新增于版本 1.9

说明：使用滑鼠跟键盘来互动浏览的主题化选单。

快速浏览范例

[adsense][/adsense]

选单可以从任何有效的标记来建立只要内容有严格的父/子关系，大部分常用的元素是无序列表 (<ul>)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<ul id="menu">
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3
<ul>
<li>Item 3-1</li>
<li>Item 3-2</li>
<li>Item 3-3</li>
<li>Item 3-4</li>
<li>Item 3-5</li>
</ul>
</li>
<li>Item 4</li>
<li>Item 5</li>
</ul>

如果你使用结构而不是<ul>/<li>，含括选单跟选单项目使用相同的元素，使用menus选项来指定一个方法区分这两个元素，例如， menus: "div.menuElement"。

任何选单项目可以使用ui-state-disabled 类别到元素来停用。

图示

要新增图示到选单，把他们加进标记中：

1
2
3
<ul id="menu">
<li><span class="ui-icon ui-icon-disk"></span>Save</li>
</ul>

选单对没有图示的项目会自动加入需要的填充。

分隔

分隔元素可以加入没有关系的选单项目来建立，这些项目只包含空格且/或线条：

1
2
3
4
5
<ul id="menu">
<li>Item 1</li>
<li>-</li>
<li>Item 2</li>
</ul>

键盘互动

  • ENTER/空格：调用获得焦点的选单项目之操作，可以开启子选单。
  • ↑UP：移动焦点到前一个选单项目。
  • ↓DOWN：移动焦点到下一个选单项目。
  • →RIGHT：如果可以开启子选单。
  • ←LEFT：关闭目前的子选单，移动焦点到父选单项目，如果不是在子选单，什么也不做。
  • ESCAPE退出键：关闭目前的子选单，移动焦点到父选单项目，如果不是在子选单，什么也不做。

输入一个字母移动焦点到第一个项目，这个字元是其标题的开始字元，透过匹配项目来重复相同字元的循环，在一秒的计时内输入更多的字元来匹配那些字元。

停用的项目可以获得键盘的焦点，但是不允许任何其他的互动。

主题化

选单控制项使用 jQuery UI CSS架构来设计它的外观跟感觉，如果需要选单的指定样式，下面的CSS类别名称可以使用：

  • ui-menu：选单的外部容器，如果选单有图示，这个元素会有另一个ui-menu-icons类别。
    • ui-menu-item：个别选单项目的容器。
      • ui-menu-icon：透过icons选项来设定子选单图示。
    • ui-menu-divider：选单项目间的分隔元素。

相关程式库

补充事项：

  • 这个控制项需要一些功能的CSS，否则无法运作，如果你建置一个订制的主题，使用控制项的指定CSS档案作为起点。

选项

disabled型态：Boolean

预设值： false
如果设为true会停用选单。

程式范例：

指定disabled选项来初始化选单：

1
$( ".selector" ).menu({ disabled: true });

初始化后，取得或设定disabled选项：

1
2
3
4
5
// getter
var disabled = $( ".selector" ).menu( "option", "disabled" );
// setter
$( ".selector" ).menu( "option", "disabled", true );

icons型态： Object

预设值： { submenu: "ui-icon-carat-1-e" }

用于子选单的图示，符合由jQuery UI CSS架构提供的图示。

  • submenu (string, default: “ui-icon-carat-1-e”)

程式范例：

指定icons 选项来初始化选单：

1
$( ".selector" ).menu({ icons: { submenu: "ui-icon-circle-triangle-e" } });

初始化后，取得或设定icons选项：

1
2
3
4
5
// getter
var icons = $( ".selector" ).menu( "option", "icons" );
// setter
$( ".selector" ).menu( "option", "icons", { submenu: "ui-icon-circle-triangle-e" } );

menus型态： String

预设值： "ul"

作为选单容器元素的选择器，包括子选单。

注意：初始化后menus选项不应该被修改，现有的子选单将不会被更新。

程式范例：

初始化有menus 选项指定的选单：

1
$( ".selector" ).menu({ menus: "div" });

初始化后取得menus选项：

1
2
// getter
var menus = $( ".selector" ).menu( "option", "menus" );

position型态： Object

预设值： { my: "left top", at: "right top" }
识别跟父选单项目关联的子选单位置，of 选项是父选单项目的预设选项，你可以指定另一个元素给位置，如需了解各种选项的更多细节，请查看jQuery UI Position 工具。

程式范例：

初始化有指定position选项的选单：

1
$( ".selector" ).menu({ position: { my: "left top", at: "right-5 top+5" } });

初始化后取得或设定position选项：

1
2
3
4
5
// getter
var position = $( ".selector" ).menu( "option", "position" );
// setter
$( ".selector" ).menu( "option", "position", { my: "left top", at: "right-5 top+5" } );

role型态： String

预设值： "menu"

定义用于选单跟选单项目的ARIA roles（※注：参阅WAI-ARIA ），预设情况下选单项目使用"menuitem"，设定role选项给"listbox"会使用"option"作为选单项目，如果设为null，没有角色会设定，如果选单是由另一个有焦点的元素控制的话，会有有用。

注意： role选项在初始化后不应该被修改，现有的（子）选单跟选单项目不能被更新。

程式范例：

初始化有指定role选项的选单：

1
$( ".selector" ).menu({ role: null });

初始化后取得role选项：

1
2
// getter
var role = $( ".selector" ).menu( "option", "role" );

方法

blur( [event ] )传回值： jQuery (plugin only)

从选单中删除焦点，重设任何启用的元素样式以及触发选单的blur事件。
  • event
    型态： Event
    触发选单的事物给blur。

程式范例：呼叫blur方法：

1
$( ".selector" ).menu( "blur" );

collapse( [event ] )传回值： jQuery (plugin only)

关闭目前启用的子选单。
  • event
    型态： Event
    触发选单的事物给关闭。

程式范例：呼叫collapse方法：

1
$( ".selector" ).menu( "collapse" );

collapseAll( [event ] [, all ] )传回值： jQuery (plugin only)

关闭所有开启的子选单。
  • event
    型态： Event
    触发选单的事物给关闭。
  • all
    型态： Boolean
    指示所有的子选单应该被关闭或是只有下列的子选单以及包含是或含有触发事件的目标选单。

程式范例：呼叫collapseAll方法：

1
$( ".selector" ).menu( "collapseAll", null, true );

destroy()传回值： jQuery (plugin only)

移除选单所有功能，这将传回原先初始化状态前的元素。
  • 这个方法不接受任何参数。

程式范例：呼叫destroy方法：

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

disable()传回值： jQuery (plugin only)

停用选单。
  • 这个方法不接受任何参数。

程式范例：呼叫disable方法：

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

enable()传回值： jQuery (plugin only)

启用选单。
  • 这个方法不接受任何参数。

程式范例：呼叫enable方法：

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

expand( [event ] )传回值： jQuery (plugin only)

假如目前存在启用的项目，开启子选单。
  • event
    型态： Event
    触发选单的事物来展开。

程式范例：呼叫expand方法：

1
$( ".selector" ).menu( "expand" );

focus( [event ], item )传回值： jQuery (plugin only)

启用一个特定的选单项目，如果有存在开启其子选单并触发选单的focus事件。
  • event
    事件：Event
    触发选单项目的事物来取得焦点。
  • item
    型态：jQuery
    要取得焦点/启用的选单项目。

程式范例：呼叫focus方法：

1
$( ".selector" ).menu( "focus", null, menu.find( ".ui-menu-item:last" ) );

instance()传回值： Object

撷取选单的实例物件，如果元素没有相关的实例，传回undefined。

不像其他控制项方法，instance()在选单外挂载入后可以安全地呼叫任何一个元素。

  • 这个方法不接受任何参数。

程式范例：呼叫instance方法：

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

isFirstItem()传回值：jQuery (plugin only)

传回boolean值说明目前启用的项目是否是选单的第一个项目。
  • 这个方法不接受任何参数。

程式范例：呼叫isFirstItem方法：

1
var firstItem = $( ".selector" ).menu( "isFirstItem" );

isLastItem()传回值：jQuery (plugin only)

传回boolean值说明目前启用的项目是否是选单的最后一个项目。
  • 这个方法不接受任何参数。

程式范例：呼叫isLastItem方法：

1
var lastItem = $( ".selector" ).menu( "isLastItem" );

next( [event ] )传回值： jQuery (plugin only)

移动启用状态到下一个选单项目。
  • event
    型态： Event
    触发焦点的事物到移到。

程式范例：呼叫next方法：

1
$( ".selector" ).menu( "next" );

nextPage( [event ] )传回值： jQuery (plugin only)

移动启用状态到可卷动选单底部下的第一个选单项目或是不可卷动时则移到最后一个项目。
  • event
    型态： Event
    触发焦点的事物到移动。

程式范例：呼叫nextPage方法：

1
$( ".selector" ).menu( "nextPage" );

option( optionName )传回值： Object

获取目前跟指定的optionName相关的值。
  • optionName
    型态： String
    要取得的选项名称。

范例程式：呼叫此方法：

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

option()传回值：PlainObject

取得包含键/值配对的物件说明目前选单选项的杂凑。
  • 该方法不接受任何参数。

程式范例：呼叫此方法：

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

option( optionName, value )传回值：jQuery (plugin only)

设定与指定的optionName相关联的选单选项的值。
  • optionName
    型态： String
    要设定的选项名称。
  • value
    型态： Object
    设定给选项的值。

程式范例：呼叫此方法：

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

option( options )传回值： jQuery (plugin only)

设定选单一个或以上的选项。
  • options
    型态： Object
    要设定的选项-值对的映图。

程式范例：呼叫此方法：

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

previous( [event ] )传回值： jQuery (plugin only)

移动启用状态到前一个选单项目。
  • event
    型态： Event
    触发焦点的事物到移动。

程式范例：呼叫previous方法：

1
$( ".selector" ).menu( "previous" );

previousPage( [event ] )传回值： jQuery (plugin only)

移动启用状态到可卷动选单顶部的第一个选单项目，如果不能卷动就移动到第一个选单项目。
  • event
    型态： Event
    触发焦点的事物到移动。

程式范例：呼叫previousPage方法：

1
$( ".selector" ).menu( "previousPage" );

refresh()传回值： jQuery (plugin only)

初始化还没有被初始化的子选单跟选单项目，新的选单项目，包括子选单会被加入到选单或是选单所有的内容可以被取代，然后使用 refresh()方法来初始化。
  • 这个方法不接受任何参数。

程式范例：呼叫refresh方法：

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

select( [event ] )传回值： jQuery (plugin only)

选择目前启用的选单项目，折叠所有子选单并触发选单的select事件。
  • event
    型态：Event
    触发选择的事物。

程式范例：呼叫select方法：

1
$( ".selector" ).menu( "select" );

widget()传回值： jQuery

R传回一个含有选单的jQuery物件。
  • 这个方法不接受任何参数。

程式范例：呼叫widget方法：

1
var widget = $( ".selector" ).menu( "widget" );

扩充点

选单小组件内建于widget factory可以被扩充，在扩充这个小组件时，你可以覆写或是增加现有方法的行为，下面的方法被提供作为扩充点，跟上面所列的外挂方法有相同的API稳定性，关于小组件扩充的资讯可以参阅Extending Widgets with the Widget Factory。

_closeOnDocumentClick( event )传回值： Boolean

决定是否点击在文件上的方法应该关闭所有开启的选单，预设是选单是关闭的，除非有点击发生在选单上。

程式范例：在文件点击的时候从不关闭选单。

1
2
3
_closeOnDocumentClick: function( event ) {
return false;
}

_isDivider( item )传回值： Boolean

决定项目是否应该被看成是分隔符号而不是选单项目，预设是任何含有空格且/或破折号的项目就会被看成是分隔符号。

程式范例：处理所有的选单项目为没有分隔符。

1
2
3
_isDivider: function( item ) {
return false;
}

事件

blur( event, ui )型态： menublur

在选单丧失焦点时触发。
  • event
    型态：Event
  • ui
    型态： Object
    • item
      型态：jQuery
      目前启用的选单项目。

程式码范例：初始化带有blur呼叫的选单：

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

系结一个事件监听器到menublur事件：

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

create( event, ui )型态： menucreate

当选单建立时触发。

注意：ui 物件是空的，这里使用是为了与其他事件的使用有一致性。

程式码范例：初始化有指定create呼叫的选单：

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

系结一个事件监听器给menucreate事件：

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

focus( event, ui )型态： menufocus

当一个选单获得焦点或是任一个选单项目被启用时触发。
  • event
    型态： Event
  • ui
    型态： Object
    • item
      型态： jQuery
      目前启用的选单项目。

程式码范例：初始化有指定focus呼叫的选单：

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

系结一个事件监听器给menufocus 事件：

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

select( event, ui )型态： menuselect

当选单项目被选择时触发。
  • event
    型态： Event
  • ui
    型态： Object
    • item
      型态： jQuery
      目前启用的选单项目。

程式码范例：初始化有指定select呼叫的选单：

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

系结一个事件监听器给menuselect事件：

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

范例：

一个简单的jQuery UI Menu

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
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>menu demo</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.11.1/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.11.1/jquery-ui.js"></script>
</head>
<body>
<ul id="menu">
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3
<ul>
<li>Item 3-1</li>
<li>Item 3-2</li>
<li>Item 3-3</li>
<li>Item 3-4</li>
<li>Item 3-5</li>
</ul>
</li>
<li>Item 4</li>
<li>Item 5</li>
</ul>
<script>
$( "#menu" ).menu();
</script>
</body>
</html>

Demo:

Comments are closed.