Recurso de menu

Um recurso de menu define um menu de aplicativo (menu de opções, menu de contexto ou submenu) que pode ser inflado com MenuInflater.

Para ver uma guia do uso de menus, consulte Menus guia do desenvolvedor.

localização do arquivo:

res/menu/filename.xml
O nome do arquivo será usado como o ID do recurso.

tipo de dado de recurso compilado:

Ponteiro de recurso para um recurso Menu (ou subclasse).

referência de recurso:

Em Java: R.menu.filename
Em XML: @[package:]menu.filename

sintaxe:

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

elementos:

<menu>

Obrigatório. Precisa ser o nó raiz. Contém elementos <item> e/ou <group>.

atributos:

xmlns:android: Namespace XML. Obrigatório. Define o namespace XML que precisa ser "http://schemas.android.com/apk/res/android".

<item>

Um item de menu. Pode conter um elemento <menu> (para um submenu). Precisa ser um filho de um elemento <menu> ou <group>.

atributos:

android:id

ID de recurso. Um ID de recurso exclusivo. Para criar um novo ID de recurso para este item, use o formulário: "@+id/name". O símbolo de adição indica que você deve criá-lo como um novo ID.

android:title

Recurso de string . O título do menu como um recurso de string ou uma string bruta.

android:titleCondensed

Recurso de string . Um título condensado como um recurso de string ou uma string bruta. Esse título é usado em situações em que o título normal é longo demais.

android:icon

Recurso drawable. Uma imagem usada como ícone do item de menu.

android:onClick

Nome do método. O método que será chamado quando esse item de menu é clicado. O método precisa ser declarado na atividade como público e aceitar um MenuItem como seu único parâmetro, o que indica que o item foi clicado. Esse método é prioritário em relação ao callback para onOptionsItemSelected(). Veja o exemplo na parte inferior.

Aviso: se você ofuscar seu código usando ProGuard ou uma ferramenta semelhante, exclua o método especificado nesse atributo da renomeação, porque ele pode danificar a funcionalidade.

Introduzido na API de nível 11.

android:showAsAction

Palavra-chave. Quando e como esse item deve ser exibido como um item de ação na barra de apps. Um item de menu pode ser exibido como um item de ação somente quando a atividade inclui uma barra de apps. Valores válidos:

Valor	Descrição
`ifRoom`	Só coloque este item na barra de apps se houver espaço para ele. Se não houver espaço para todos os itens marcados como `"ifRoom"`, os itens com os menores valores `orderInCategory` serão exibidos como ações, e os demais serão exibidos no menu flutuante.
`withText`	Inclua também o texto título (definido por `android:title`) com o item de ação. Você pode incluir esse valor junto com um dos outros valores como um conjunto de sinalizações, separando-os com uma barra vertical `\|`.
`never`	Nunca coloque este item na barra de apps. Em vez disso, liste o item na barra de apps do menu flutuante.
`always`	Sempre coloque este item na barra de apps. Evite usá-lo, a não ser que seja essencial que o item sempre apareça na barra de ações. Definir vários itens para que sejam sempre exibidos como itens de ação pode fazer com que eles sobreponham outra IU na barra de apps.
`collapseActionView`	A visualização de ações associadas a esse item de ação, conforme declarado por `android:actionLayout` ou `android:actionViewClass`, pode ser recolhida. Introduzido na API de nível.

Consulte o treinamento sobre Como adicionar a barra de apps para ver mais informações.

Introduzido na API de nível 11.

android:actionLayout

Recurso de layout. Um layout para ser usado como visualização de ação.

Consulte Visualizações e provedores de ação para ver mais informações.

Introduzido na API de nível 11.

android:actionViewClass

Nome de classe. Um nome de classe totalmente qualificado para View usar como visualização de ação. Por exemplo, "android.widget.SearchView" para usar SearchView como uma visualização de ação.

Consulte Visualizações e provedores de ação para ver mais informações.

Aviso: se você ofuscar seu código usando ProGuard ou uma ferramenta semelhante, exclua a classe especificada nesse atributo da renomeação, porque ele pode danificar a funcionalidade.

Introduzido na API de nível 11.

android:actionProviderClass

Nome de classe. Um nome de classe totalmente qualificado para ActionProvider usar no lugar do item de ação. Por exemplo, "android.widget.ShareActionProvider" para usar ShareActionProvider.

Consulte Visualizações e provedores de ação para ver mais informações.

Aviso: se você ofuscar seu código usando ProGuard ou uma ferramenta semelhante, exclua a classe especificada nesse atributo da renomeação, porque ele pode danificar a funcionalidade.

Introduzido na API de nível 14.

android:alphabeticShortcut

Char. Um caractere para a tecla de atalho alfabética.

android:numericShortcut

Número inteiro. Um número para a tecla de atalho numérico.

android:alphabeticModifiers

Palavra-chave. Um modificador para o atalho alfabético do item de menu. O valor padrão corresponde à tecla Control . Valores válidos:

Valor	Descrição
`META`	Corresponde à tecla `Meta`
`CTRL`	Corresponde à tecla meta `Control`
`ALT`	Corresponde à tecla meta `Alt`
`SHIFT`	Corresponde à tecla meta `Shift`
`SYM`	Corresponde à tecla meta `Sym`
`FUNCTION`	Corresponde à tecla meta `Function`

Observação: Você pode especificar várias palavras-chave em um atributo. Por exemplo, android:alphabeticModifiers="CTRL|SHIFT" indica que, para acionar o item de menu, o usuário precisa pressionar as teclas metas Control e Shift junto com o atalho.

Você pode usar o método setAlphabeticShortcut() para definir os valores de atributo de forma programática. Para mais informações sobre o atributo alphabeticModifier, acesse alphabeticModifiers.

android:numericModifiers

Palavra-chave. Um modificador para o atalho numérico do item de menu. O valor padrão corresponde à tecla Control. Valores válidos:

Valor	Descrição
`META`	Corresponde à tecla `Meta`
`CTRL`	Corresponde à tecla meta `Control`
`ALT`	Corresponde à tecla meta `Alt`
`SHIFT`	Corresponde à tecla meta `Shift`
`SYM`	Corresponde à tecla meta `Sym`
`FUNCTION`	Corresponde à tecla meta `Function`

Observação: Você pode especificar várias palavras-chave em um atributo. Por exemplo, android:numericModifiers="CTRL|SHIFT" indica que, para acionar o item de menu, o usuário precisa pressionar as teclas metas Control e Shift junto com o atalho.

Você pode usar o método setNumericShortcut() para definir os valores de atributo de forma programática. Para mais informações sobre o atributo numericModifier, acesse numericModifiers.

android:checkable

Booleano. "true" se o item puder ser selecionado.

android:checked

Booleano. "true" se o item estiver selecionado por padrão.

android:visible

Booleano. "true" se o item estiver visível por padrão.

android:enabled

Booleano. "true" se o item estiver ativado por padrão.

android:menuCategory

Palavra-chave. Valor correspondente às constantes Menu CATEGORY_*, que definem a prioridade do item. Valores válidos:

Valor	Descrição
`container`	Para itens que fazem parte de um contêiner.
`system`	Para itens fornecidos pelo sistema.
`secondary`	Para itens que são opções secundárias (raramente usadas) fornecidas pelo usuário.
`alternative`	Para itens que são ações alternativas nos dados exibidos atualmente.

android:orderInCategory

Número inteiro. A ordem de "importância" do item, dentro de um grupo.

<group>

Um grupo de menus para criar um conjunto de itens que compartilham traços, por exemplo, se estão visíveis, ativados ou selecionáveis. Contém um ou mais elementos <item>. Precisa ser um filho de um elemento <menu>.

atributos:

android:id

ID de recurso. Um ID de recurso exclusivo. Para criar um novo ID de recurso para este item, use o formulário: "@+id/name". O símbolo de adição indica que você deve criá-lo como um novo ID.

android:checkableBehavior

Palavra-chave. O tipo de comportamento que pode ser selecionado para o grupo. Valores válidos:

Valor	Descrição
`none`	Não é possível selecionar
`all`	Todos os itens podem ser selecionados (use caixas de seleção)
`single`	Somente um item pode ser selecionado (use botões de opção)

android:visible

Booleano. "true" se o grupo estiver visível.

android:enabled

Booleano. "true" se o grupo estiver ativado.

android:menuCategory

Palavra-chave. Valor correspondente às constantes Menu CATEGORY_*, que definem a prioridade do grupo. Valores válidos:

Valor	Descrição
`container`	Para grupos que fazem parte de um contêiner.
`system`	Para grupos fornecidos pelo sistema.
`secondary`	Para grupos que são opções secundárias fornecidas pelo usuário (usadas com pouca frequência).
`alternative`	Para grupos que são ações alternativas nos dados exibidos no momento.

android:orderInCategory

Número inteiro. A ordem padrão dos itens na categoria.

Exemplo:

Arquivo XML salvo em 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>

O código do aplicativo a seguir infla o menu no callback de onCreateOptionsMenu(Menu) e também declara o callback no clique para dois dos itens a seguir:

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 <code><a href="/reference/android/app/Activity.html#onOptionsItemSelected(android.view.MenuItem)">onOptionsItemSelected()</a></code>
    }

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 <code><a href="/reference/android/app/Activity.html#onOptionsItemSelected(android.view.MenuItem)">onOptionsItemSelected()</a></code>
    }

Layout

String