Menu Widget · jQuery UI API 中文文檔

# Menu Widget # Menu Widget Categories: [Widgets](http://www.css88.com/jquery-ui-api/category/widgets/ "View all posts in Widgets") ## version added: 1.9 **Description:** 帶有鼠標和鍵盤交互的用于導航的可主題化菜單。 ## QuickNav[Examples](#entry-examples) ### Options - [disabled](#option-disabled) - [icons](#option-icons) - [menus](#option-menus) - [position](#option-position) - [role](#option-role) ### Methods - [blur](#method-blur) - [collapse](#method-collapse) - [collapseAll](#method-collapseAll) - [destroy](#method-destroy) - [disable](#method-disable) - [enable](#method-enable) - [expand](#method-expand) - [focus](#method-focus) - [isFirstItem](#method-isFirstItem) - [isLastItem](#method-isLastItem) - [next](#method-next) - [nextPage](#method-nextPage) - [option](#method-option) - [previous](#method-previous) - [previousPage](#method-previousPage) - [refresh](#method-refresh) - [select](#method-select) - [widget](#method-widget) ### Events - [blur](#event-blur) - [create](#event-create) - [focus](#event-focus) - [select](#event-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`](#option-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 框架](theming/css-framework) 來定義它的外觀和感觀的樣式。如果需要使用菜單指定的樣式，則可以使用下面的 CSS class 名稱： - `ui-menu`：菜單的外層容器。如果菜單包含圖標，該元素會另外帶有一個 `ui-menu-icons` class。 - `ui-menu-item`：單個菜單項的容器。 - `ui-menu-icon`：通過 [`icons`](#option-icons) 選項進行子菜單圖標設置。 - `ui-menu-divider`：菜單項之間的分隔符元素。 ### 依賴（Dependencies） - [UI 核心（UI Core）](category/ui-core) - [部件庫（Widget Factory）](jQuery.widget) - [定位（Position）](position) ### 其他注意事項（Additional Notes:） - 該部件要求一些功能性的 CSS，否則將無法工作。如果您創建了一個自定義的主題，請使用小部件指定的 CSS 文件作為起點。 ## Options ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#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 ); ``` ### icons**Type:** [Object](http://api.jquery.com/Types/#Object) **Default:**`{ submenu: "ui-icon-carat-1-e" }`標題要使用的圖標，與 [jQuery UI CSS 框架提供的圖標（Icons）](theming/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" } ); ``` ### menus**Type:** [String](http://api.jquery.com/Types/#String) **Default:**`"ul"` 作為menu（菜單）容器的元素的選擇器，包括子菜單。 **注意:** 初始化后 `menus`選項不應該被更改。現有的子菜單將不會被更新。**Code examples:** 初始化帶有指定 `menus`選項的menu（菜單） ``` $( ".selector" ).menu({ menus: "div" }); ``` 獲取 `menus` 選項： ``` // getter var menus = $( ".selector" ).menu( "option", "menus" ); ``` ### position**Type:** [Object](http://api.jquery.com/Types/#Object) **Default:**`{ my: "left top", at: "right top" }`標識建議菜單的位置與相關的 input 元素有關系。`of` 選項默認為 input 元素，但是您可以指定另一個定位元素。如需了解各種選項的更多細節，請查看 [jQuery UI Position](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" } ); ``` ### role**Type:** [String](http://api.jquery.com/Types/#String) **Default:**`"menu"` 自定義用于菜單和菜單項的ARIA roles（愚人碼頭注：關于[ARIA roles](http://www.w3.org/TR/wai-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](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 從菜單中刪除焦點，重置任何激活樣式和觸發菜單的 [`blur`](#event-blur) 事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發了菜單失去焦點。 **Code examples:** 調用 blur 方法： ``` $( ".selector" ).menu( "blur" ); ``` ### collapse( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 關閉當前活動的子菜單。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發關閉子菜單 **Code examples:** 調用 collapse 方法： ``` $( ".selector" ).menu( "collapse" ); ``` ### collapseAll( \[event \] \[, all \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 關閉全部打開的子菜單。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發關閉子菜單。 - **all**Type: [Boolean](http://api.jquery.com/Types/#Boolean)表示所有子菜單是否應該被關閉或只有子菜單中包括的菜單或包含觸發事件的目標元素。 **Code examples:** 調用 collapseAll 方法： ``` $( ".selector" ).menu( "collapseAll", null, true ); ``` ### destroy()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 完全移除 menu 功能. 這將使元素返回到之前的初始化狀態. - 該方法不接受任何參數。 **Code examples:** 調用 destroy 方法： ``` $( ".selector" ).menu( "destroy" ); ``` ### disable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 禁用 menu. - 該方法不接受任何參數。 **Code examples:** 調用 disable 方法： ``` $( ".selector" ).menu( "disable" ); ``` ### enable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 啟用 menu. - 該方法不接受任何參數。 **Code examples:** 調用 enable 方法： ``` $( ".selector" ).menu( "enable" ); ``` ### expand( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 打開當前活動項目下的子菜單下，如果有的話。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么時間觸發打開子菜單。 **Code examples:** 調用 expand 方法： ``` $( ".selector" ).menu( "expand" ); ``` ### focus( \[event \], item )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 激活一個特定的菜單項，首先，如果打開存在的任何子菜單，并觸發菜單的[`focus`](#event-focus)事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發了菜單項獲得焦點。 - **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要獲取焦點/激活的菜單項 **Code examples:** 調用 focus 方法： ``` $( ".selector" ).menu( "focus", null, menu.find( ".ui-menu-item:last" ) ); ``` ### isFirstItem()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 返回一個布爾值，說明當前活動項目是否菜單的第一項。 - 該方法不接受任何參數。 **Code examples:** 調用 isFirstItem 方法： ``` var firstItem = $( ".selector" ).menu( "isFirstItem" ); ``` ### isLastItem()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 返回一個布爾值，說明當前活動項目是否菜單的最后一項。 - 該方法不接受任何參數。 **Code examples:** 調用 isLastItem 方法： ``` var lastItem = $( ".selector" ).menu( "isLastItem" ); ``` ### next( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 移動激活狀態到下一個菜單項。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發焦點轉移。 **Code examples:** 調用 next 方法： ``` $( ".selector" ).menu( "next" ); ``` ### nextPage( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 移動激活狀態到第一個菜單項下的可滾動菜單的底部，或最后一個項目，如果不可滾動。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發焦點轉移。 **Code examples:** 調用 nextPage 方法： ``` $( ".selector" ).menu( "nextPage" ); ``` ### option( optionName )Returns: [Object](http://api.jquery.com/Types/#Object) 獲取當前與指定的 `optionName` 關聯的值。 - **optionName**Type: [String](http://api.jquery.com/Types/#String)要獲取值的選項的名稱。 **Code examples:** 調用該方法： ``` var isDisabled = $( ".selector" ).menu( "option", "disabled" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個包含鍵/值對的對象，鍵/值對表示當前 menu 選項哈希。 - 該方法不接受任何參數。 **Code examples:** 調用該方法： ``` var options = $( ".selector" ).menu( "option" ); ``` ### option( optionName, value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 設置與指定的 `optionName` 關聯的 menu 選項的值。 - **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置的選項的名稱。 - **value**Type: [Object](http://api.jquery.com/Types/#Object)要為選項設置的值。 **Code examples:** 調用該方法： ``` $( ".selector" ).menu( "option", "disabled", true ); ``` ### option( options )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 為 menu 設置一個或多個選項。 - **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的 option-value 對。 **Code examples:** 調用該方法： ``` $( ".selector" ).menu( "option", { disabled: true } ); ``` ### previous( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 移動激活狀態到上一個菜單項。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發焦點轉移。 **Code examples:** 調用 previous 方法： ``` $( ".selector" ).menu( "previous" ); ``` ### previousPage( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 移動激活狀態到第一個菜單項下的可滾動菜單的頂部，或第一一個項目，如果不可滾動。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發焦點轉移。 **Code examples:** 調用 previousPage 方法： ``` $( ".selector" ).menu( "previousPage" ); ``` ### refresh()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 初始化還沒有被初始化的子菜單和菜單項。新的菜單項，包括子菜單可以被添加到菜單或所有的菜單的內容可以被替換然后使用`refresh()`方法初始化。 - 該方法不接受任何參數。 **Code examples:** 調用 refresh 方法： ``` $( ".selector" ).menu( "refresh" ); ``` ### select( \[event \] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 選擇當前活動的菜單項，折疊所有子菜單并觸發菜單中的 [`select`](#event-select) 事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event)什么事件觸發選擇。 **Code examples:** 調用 select 方法： ``` $( ".selector" ).menu( "select" ); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個包含 button 的 `jQuery` 對象。 - 該方法不接受任何參數。 **Code examples:** 調用 widget 方法： ``` var widget = $( ".selector" ).menu( "widget" ); ``` ## Events ### blur( event, ui )Type: `menublur` 當menu失去焦點時觸發這個事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) - **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)當前激活的菜單項。 **Code examples:** 初始化帶有指定 blur 回調的 menu： ``` $( ".selector" ).menu({ blur: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 menublur 事件： ``` $( ".selector" ).on( "menublur", function( event, ui ) {} ); ``` ### create( event, ui )Type: `menucreate` 當創建 menu 時觸發。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) *注意：`ui` 對象是空的，這里包含它是為了與其他事件保持一致性。* **Code examples:** 初始化帶有指定 create 回調的 menu： ``` $( ".selector" ).menu({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 menucreate 事件： ``` $( ".selector" ).on( "menucreate", function( event, ui ) {} ); ``` ### focus( event, ui )Type: `menufocus` 當當一個菜單獲得焦點或當任意一個菜單項被激活時觸發這個事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) - **item**Type: [jQuery](http://api.jquery.com/Types/#jQuery)當前激活的菜單項。 **Code examples:** 初始化帶有指定 focus 回調的 menu： ``` $( ".selector" ).menu({ focus: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 menufocus 事件： ``` $( ".selector" ).on( "menufocus", function( event, ui ) {} ); ``` ### select( event, ui )Type: `menuselect` 當才安被選中的時候觸發該事件。 - **event**Type: [Event](http://api.jquery.com/Types/#Event) - **ui**Type: [Object](http://api.jquery.com/Types/#Object) - **item**Type: [jQuery](http://api.jquery.com/Types/#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> ```