jQuery UI Menu Widget

前幾天我看到商業周刊的囚犯的兩難這本書介紹,標題這樣寫「母親、愛人同時有難,只能擇一的情況下,你該就誰?」這樣的賽局理論,我也曾用於婚姻的路上,不過一開始老婆不選我,選母親,我差一點離開她,後來因為我的堅持慶幸她改變選擇而成功。今天我在讀ASP.NET AJAX Control慨然嘆曰: 既生瑜,何生亮?作者也是跟著jQuery私奔為愛走天涯了,朋友們你是否也在掙扎要學C或jQuery呢?今天我會勸你看看jQuery吧,因為實在是快,而我們要繼續分享jQuery UI的選單小工具或小組件()。

Widget新增於版本 1.9

說明:使用滑鼠跟鍵盤來互動瀏覽的主題化選單。

快速瀏覽範例

選單可以從任何有效的標記來建立只要內容有嚴格的父/子關係,大部分常用的元素是無序列表 (<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..com/ui/1.11.1/themes/smoothness/-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:

馬上成為工作達人的Fans

About ㄚ琪

工作達人Fun Taiwan的創辦者及總編,可以在這裡更認識他。

One comment

發表迴響

你的電子郵件位址並不會被公開。 Required fields are marked *

*

Scroll To Top
按讚 !
愛你喔!