本頁面由 Cloud Translation API 翻譯而成。

選單資源

選單資源會定義可使用 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>

元素：

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

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

在 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.
}

版面配置

字串