Esta página foi traduzida pela API Cloud Translation.

Recurso de menu

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

Confira como usar menus em Adicionar menus.

localização do arquivo:

res/menu/filename.xml
O nome do arquivo é usado como ID de recurso.

tipo de dados do 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 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 ele foi criado 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 vai ser chamado quando esse item de menu for clicado. O método precisa ser declarado na atividade como público. Ele aceita um MenuItem como único parâmetro, o que indica que o item foi clicado. Esse método tem precedência em relação ao callback para onOptionsItemSelected(). Confira o exemplo no final desta página.

Aviso: se você ofuscar seu código usando o ProGuard ou uma ferramenta semelhante, não esqueça de fazer com que o método especificado nesse atributo não seja renomeado, porque isso pode corromper a funcionalidade do código.

Introduzido no nível 11 da API.

android:showAsAction

Palavra-chave. Quando e como esse item aparece como um item de ação na barra de apps. Um item de menu pode ser mostrado 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 mostrados como ações, e os demais no menu flutuante.
`withText`	Inclua também o texto do título (definido por `android:title`) com o item de ação. Você pode incluir esse valor 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 usar o item, a não ser que seja essencial que ele sempre apareça na barra de ações. Definir vários itens para que sejam sempre mostrados como itens de ação pode fazer com que eles apareçam por cima de outros elementos da interface 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 fechada. Introduzido no nível 14 da API.

Consulte Adicionar a barra de apps para mais informações.

Introduzido no nível 11 da API.

android:actionLayout

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

Para mais informações, consulte Usar visualizações e provedores de ação.

Introduzido no nível 11 da API.

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.

Para mais informações, consulte Usar visualizações e provedores de ação.

Aviso: se você ofuscar seu código usando o ProGuard ou uma ferramenta semelhante, não esqueça de fazer com que a classe especificada nesse atributo não seja renomeada, porque isso pode corromper a funcionalidade do código.

Introduzido no nível 11 da API.

android:actionProviderClass

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

Para mais informações, consulte Usar visualizações e provedores de ação.

Introduzido no nível 14 da API.

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 `Control`.
`ALT`	Corresponde à tecla `Alt`.
`SHIFT`	Corresponde à tecla `Shift`.
`SYM`	Corresponde à tecla `Sym`.
`FUNCTION`	Corresponde à tecla `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 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, consulte 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 `Control`.
`ALT`	Corresponde à tecla `Alt`.
`SHIFT`	Corresponde à tecla `Shift`.
`SYM`	Corresponde à tecla `Sym`.
`FUNCTION`	Corresponde à tecla `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 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, consulte numericModifiers.

android:checkable

Booleano. Verdadeiro se o item puder ser selecionado.

android:checked

Booleano. Verdadeiro se o item estiver marcado por padrão.

android:visible

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

android:enabled

Booleano. Verdadeiro 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.

android:orderInCategory

Número inteiro. A ordem de importância do item em um grupo.

<group>

Um grupo de menus para criar um conjunto de itens que compartilham características, por exemplo, se sã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 ele foi criado 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 selecionável.
`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. Verdadeiro se o grupo estiver visível.

android:enabled

Booleano. Verdadeiro 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.

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 abaixo infla o menu no callback de onCreateOptionsMenu(Menu) e também declara o callback no clique para dois dos itens:

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