選單資源

選單資源會定義可使用 MenuInflater 加載的應用程式選單（選項選單、內容選單或子選單）。

如需選單的使用指南，請參閱「新增選單」。

檔案位置：
res/menu/filename.xml
系統會將檔案名稱做為資源 ID
編譯資源資料類型：
Menu (或子類別) 資源的資源指標。
資源參照：
Java：R.menu.filename
XML：@[package:]menu.filename
語法：
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@[+][package:]id/resource_name"
          android:title="string"
          android:titleCondensed="string"
          android:icon="@[package:]drawable/drawable_resource_name"
          android:onClick="method name"
          android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"]
          android:actionLayout="@[package:]layout/layout_resource_name"
          android:actionViewClass="class name"
          android:actionProviderClass="class name"
          android:alphabeticShortcut="string"
          android:alphabeticModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:numericShortcut="string"
          android:numericModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:checkable=["true" | "false"]
          android:visible=["true" | "false"]
          android:enabled=["true" | "false"]
          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
          android:orderInCategory="integer" />
    <group android:id="@[+][package:]id/resource name"
           android:checkableBehavior=["none" | "all" | "single"]
           android:visible=["true" | "false"]
           android:enabled=["true" | "false"]
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="integer" >
        <item />
    </group>
    <item >
        <menu>
          <item />
        </menu>
    </item>
</menu>
元素：
必要。這必須是根節點。包含 <item> 和/或 <group> 元素。

屬性：

xmlns:android
「XML 命名空間」。必要。定義 XML 命名空間，必須為 "http://schemas.android.com/apk/res/android"。
<item>
選單項目。可以包含 <menu> 元素 (適用於子選單)。必須是 <menu> 或 <group> 元素的子項。

屬性：

android:id
「資源 ID」。不重複的資源 ID。如要建立此項目的新資源 ID，請使用下列形式："@+id/name"。加號表示此應建立為新 ID。
android:title
「字串資源」。選單標題，以字串資源或原始字串表示。
android:titleCondensed
「字串資源」。精簡標題，以字串資源或原始字串表示。當正規標題過長時，可以使用這類精簡標題。
android:icon
「可繪製資源」。要當做選單項目圖示的圖片。
android:onClick
「方法名稱」。點選此選單項目時呼叫的方法。該方法必須在活動中宣告為公開。它可接受 MenuItem 做為唯一參數，用來指出點選的項目。此方法的優先順序高於 onOptionsItemSelected() 的標準回呼。請參閱本頁結尾處的範例。

警告：如果使用 ProGuard (或類似工具) 模糊處理程式碼，切勿讓這類工具把您在此屬性指定的方法重新命名，因為上述方法重新命名後可能會破壞功能。

在 API 級別 11 中導入。

android:showAsAction
「關鍵字」。指定此項目在應用程式列顯示為操作項目的時間和方式。只有在活動包含應用程式列時，選單項目才能以操作項目的方式顯示。有效值：
值說明
ifRoom除非有空間，否則不要在應用程式列中放置此項目。如果沒有足夠空間容納所有標示為 "ifRoom" 的項目，orderInCategory 值最低的項目會顯示為動作，其餘項目則會顯示在溢位選單中。
withText另外也請使用操作項目加入標題文字 (由 android:title 定義)。您可以使用管道符號 | 分隔值，將此值與另一個其他值合併為組合標記。
never切勿將此項目放在應用程式列中，改為安置在應用程式列的溢位選單中。
always此項目一律須放在應用程式列中。除非此項目必須在動作列中顯示，否則請避免使用此項目。將多個項目設為一律顯示為操作項目時，可能會導致這些項目與應用程式列中的其他使用者介面重疊。
collapseActionView與此操作項目相關的動作檢視畫面 (由 android:actionLayout 或 android:actionViewClass 宣告) 可以收合。
請在 API 級別 14 中導入。

詳情請參閱「新增應用程式列」。

在 API 級別 11 中導入。

android:actionLayout
「版面配置資源」。用於動作檢視畫面的版面配置。

詳情請參閱「使用動作檢視畫面和動作供應程式」。

在 API 級別 11 中導入。

android:actionViewClass
「類別名稱」。用於動作檢視畫面的 View 完整類別名稱。舉例來說，"android.widget.SearchView" 可以使用 SearchView 做為動作檢視畫面。

詳情請參閱「使用動作檢視畫面和動作供應程式」。

警告：如果使用 ProGuard (或類似工具) 模糊處理程式碼，切勿讓這類工具把您在此屬性指定的類別重新命名，因為上述類別重新命名後可能會破壞功能。

在 API 級別 11 中導入。

android:actionProviderClass
「類別名稱」。用於取代操作項目的 ActionProvider 完整類別名稱。例如 "android.widget.ShareActionProvider" 要使用 ShareActionProvider。

詳情請參閱「使用動作檢視畫面和動作供應程式」。

警告：如果使用 ProGuard (或類似工具) 模糊處理程式碼，切勿讓這類工具把您在此屬性指定的類別重新命名，因為上述類別重新命名後可能會破壞功能。

在 API 級別 14 中導入。

android:alphabeticShortcut
「字元」。字母快速鍵使用的字元。
android:numericShortcut
「整數」。數字快速鍵使用的數字。
android:alphabeticModifiers
「關鍵字」。選單項目字母快速鍵的修飾符。預設值會對應至 Control 鍵。有效值：
值說明
META 對應至 Meta 鍵的修飾鍵
CTRL 對應至 Control 鍵的修飾鍵
ALT 對應至 Alt 鍵的修飾鍵
SHIFT 對應至 Shift 鍵的修飾鍵
SYM 對應至 Sym 鍵的修飾鍵
FUNCTION 對應至 Function 鍵的修飾鍵

注意：您可以在屬性中指定多個關鍵字。舉例來說，android:alphabeticModifiers="CTRL|SHIFT" 表示如要觸發對應的選單項目，使用者必須同時按下 Control 和 Shift 修飾鍵與快速鍵。

您可以使用 setAlphabeticShortcut() 方法，透過程式輔助方式設定屬性值。如要進一步瞭解 alphabeticModifier 屬性，請參閱 alphabeticModifiers。

android:numericModifiers
「關鍵字」。選單項目數字快速鍵的修飾符。預設值會對應至 Control 鍵。有效值：
值說明
META 對應至 Meta 鍵的修飾鍵
CTRL 對應至 Control 鍵的修飾鍵
ALT 對應至 Alt 鍵的修飾鍵
SHIFT 對應至 Shift 鍵的修飾鍵
SYM 對應至 Sym 鍵的修飾鍵
FUNCTION 對應至 Function 鍵的修飾鍵

注意：您可以在屬性中指定多個關鍵字。舉例來說，android:numericModifiers="CTRL|SHIFT" 表示如要觸發對應的選單項目，使用者必須同時按下 Control 和 Shift 修飾鍵與快速鍵。

您可以使用 setNumericShortcut() 方法，透過程式輔助方式設定屬性值。如要進一步瞭解 numericModifier 屬性，請參閱 numericModifiers。

android:checkable
「布林值」。如果該項目可勾選，則為「是」。
android:checked
「布林值」。如果該項目預設為勾選，則為「是」。
android:visible
「布林值」。如果該項目預設為顯示，則為「是」。
android:enabled
「布林值」。如果該項目預設為啟用，則為「是」。
android:menuCategory
「關鍵字」。對應至 Menu CATEGORY_* 常數的值，用來定義該項目的優先順序。有效值：
值說明
container屬於容器的項目。
system適用於系統提供的項目。
secondary適用於使用者提供次要 (不常使用) 選項的項目。
alternative適用於目前顯示的資料額外動作項目。
android:orderInCategory
「整數」。項目在群組中的重要性順序。
<group>
選單群組 (用於建立有共用特徵的項目集合，例如是否「顯示」、「啟用」或「可選取」)。包含一或多個 <item> 元素，必須是 <menu> 元素的子項。

屬性：

android:id
「資源 ID」。不重複的資源 ID。如要建立此項目的新資源 ID，請使用下列形式："@+id/name"。加號表示此應建立為新 ID。
android:checkableBehavior
「關鍵字」。群組的可選行為類型。有效值：
值說明
none無法選取。
all所有項目均可選取 (使用核取方塊)。
single只能選取一個項目 (使用圓形按鈕)。
android:visible
「布林值」。如果群組可顯示，則為「是」。
android:enabled
「布林值」。如果群組已啟用，則為「是」。
android:menuCategory
「關鍵字」。與 Menu CATEGORY_* 常數相對應的值，該常數定義群組的優先順序。有效值：
值說明
container屬於容器的群組。
system適用於系統提供的群組。
secondary適用於使用者提供次要 (不常使用) 選項的群組。
alternative適用於目前顯示的資料額外動作群組。
android:orderInCategory
「整數」。類別中項目的預設順序。
例如：
XML 檔案儲存在 res/menu/example_menu.xml：
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item android:id="@+id/item1"
          android:title="@string/item1"
          android:icon="@drawable/group_item1_icon"
          app:showAsAction="ifRoom|withText"/>
    <group android:id="@+id/group">
        <item android:id="@+id/group_item1"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item1"
              android:icon="@drawable/group_item1_icon" />
        <item android:id="@+id/group_item2"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item2"
              android:icon="@drawable/group_item2_icon" />
    </group>
    <item android:id="@+id/submenu"
          android:title="@string/submenu_title"
          app:showAsAction="ifRoom|withText" >
        <menu>
            <item android:id="@+id/submenu_item1"
                  android:title="@string/submenu_item1" />
        </menu>
    </item>
</menu>

下列應用程式程式碼會從 onCreateOptionsMenu(Menu) 回呼加載選單，並宣告兩個項目的點按回呼：

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    menuInflater.inflate(R.menu.example_menu, menu)
    return true
}

fun onGroupItemClick(item: MenuItem) {
    // One of the group items (using the onClick attribute) was clicked.
    // The item parameter passed here indicates which item it is.
    // All other menu item clicks are handled by Activity.onOptionsItemSelected.
}

Java

public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.example_menu, menu);
    return true;
}

public void onGroupItemClick(MenuItem item) {
    // One of the group items (using the onClick attribute) was clicked.
    // The item parameter passed here indicates which item it is.
    // All other menu item clicks are handled by Activity.onOptionsItemSelected.
}
上一頁
Layout
下一頁
String