Tài nguyên trình đơn

Tài nguyên trình đơn xác định một trình đơn ứng dụng – trình đơn tuỳ chọn, trình đơn theo bối cảnh hoặc trình đơn phụ – có thể được tăng cường bằng MenuInflater.

Để xem hướng dẫn sử dụng trình đơn, hãy xem phần Thêm trình đơn.

vị trí tệp:
res/menu/filename.xml
Tên tệp được dùng làm mã nhận dạng tài nguyên
loại dữ liệu tài nguyên được biên dịch:
Con trỏ tài nguyên đến một tài nguyên Menu (hoặc lớp con)
mã tham chiếu tài nguyên:
Trong Java: R.menu.filename
Trong XML: @[package:]menu.filename
cú pháp:
<?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>
phần tử:
Bắt buộc. Đây phải là nút gốc. Chứa các phần tử <item> và/hoặc <group>.

Thuộc tính:

xmlns:android
Không gian tên XML. Bắt buộc. Xác định không gian tên XML phải là "http://schemas.android.com/apk/res/android".
<item>
Một mục trong trình đơn. Có thể chứa phần tử <menu> (cho một trình đơn phụ). Phải là phần tử con của phần tử <menu> hoặc <group>.

Thuộc tính:

android:id
Mã nhận dạng tài nguyên. Mã nhận dạng tài nguyên duy nhất. Để tạo mã nhận dạng tài nguyên mới cho mục này, hãy sử dụng biểu mẫu: "@+id/name". Biểu tượng dấu cộng cho biết mã này được tạo dưới dạng mã nhận dạng mới.
android:title
Tài nguyên chuỗi. Tiêu đề trình đơn dưới dạng một tài nguyên chuỗi hoặc chuỗi thô.
android:titleCondensed
Tài nguyên chuỗi. Tiêu đề ngắn gọn dưới dạng một tài nguyên chuỗi hoặc chuỗi thô. Tiêu đề này được dùng trong các trường hợp mà tiêu đề thông thường quá dài.
android:icon
Tài nguyên có thể vẽ. Một hình ảnh được dùng làm biểu tượng mục trong trình đơn.
android:onClick
Tên phương thức. Phương thức gọi khi mục này trong trình đơn được nhấp vào. Phương thức phải được khai báo trong hoạt động dưới dạng công khai. Phương thức này chấp nhận MenuItem làm tham số duy nhất, cho biết mục đã nhấp vào. Phương thức này được ưu tiên hơn lệnh gọi lại chuẩn đến onOptionsItemSelected(). Hãy xem ví dụ ở cuối trang này.

Cảnh báo: Nếu bạn làm rối mã nguồn của mình bằng cách sử dụng ProGuard hoặc một công cụ tương tự, hãy nhớ loại trừ việc đổi tên phương thức mà bạn chỉ định trong thuộc tính này, vì điều này có thể làm hỏng chức năng đó.

Ra mắt trong API cấp 11

android:showAsAction
Từ khoá. Thời điểm và cách thức mục này xuất hiện dưới dạng một mục hành động trên thanh ứng dụng. Một mục trong trình đơn chỉ có thể xuất hiện dưới dạng một mục hành động khi hoạt động có chứa một thanh ứng dụng. Giá trị hợp lệ:
Giá trịMô tả
ifRoomChỉ đặt mục này vào thanh ứng dụng nếu vẫn còn chỗ. Nếu không có chỗ cho tất cả các mục được đánh dấu là "ifRoom", thì các mục có giá trị orderInCategory thấp nhất sẽ hiển thị dưới dạng hành động, và các mục còn lại sẽ hiển thị trong trình đơn mục bổ sung.
withTextNgoài ra, hãy thêm văn bản tiêu đề (do android:title xác định) bằng mục hành động. Bạn có thể bao gồm giá trị này cùng với một trong các giá trị khác dưới dạng bộ cờ bằng cách phân tách các giá trị này bằng dấu gạch đứng |.
neverTuyệt đối không đặt mục này vào thanh ứng dụng. Thay vào đó, hãy liệt kê mục này trong trình đơn mục bổ sung của thanh ứng dụng.
alwaysLuôn đặt mục này vào thanh ứng dụng. Tránh sử dụng mục này trừ phi việc mục đó luôn xuất hiện trong thanh thao tác đóng một vai trò quan trọng. Việc đặt nhiều mục luôn xuất hiện dưới dạng các mục hành động có thể khiến các mục đó bị trùng lặp với giao diện người dùng khác trong thanh ứng dụng.
collapseActionViewKhung hiển thị hành động liên kết với mục hành động này (như được khai báo bởi android:actionLayout hoặc android:actionViewClass) có thể thu gọn.
Ra mắt trong API cấp 14.

Hãy xem phần Thêm thanh ứng dụng để biết thêm thông tin.

Ra mắt trong API cấp 11

android:actionLayout
Tài nguyên bố cục. Bố cục để sử dụng làm khung hiển thị hành động.

Để biết thêm thông tin, hãy xem phần Sử dụng khung hiển thị hành động và trình cung cấp hành động.

Ra mắt trong API cấp 11

android:actionViewClass
Tên lớp. Tên lớp đủ điều kiện để View sử dụng dưới dạng chế độ xem hành động. Ví dụ: "android.widget.SearchView" để sử dụng SearchView làm khung hiển thị hành động.

Để biết thêm thông tin, hãy xem phần Sử dụng thành phần hiển thị hành động và trình cung cấp hành động.

Cảnh báo: Nếu bạn làm rối mã nguồn của mình bằng cách sử dụng ProGuard hoặc một công cụ tương tự, hãy nhớ loại trừ việc đổi tên lớp mà bạn chỉ định trong thuộc tính này, vì điều này có thể làm hỏng chức năng đó.

Ra mắt trong API cấp 11

android:actionProviderClass
Tên lớp. Tên lớp đủ điều kiện để ActionProvider sử dụng thay cho mục hành động. Ví dụ: "android.widget.ShareActionProvider" để sử dụng ShareActionProvider.

Để biết thêm thông tin, hãy xem phần Sử dụng thành phần hiển thị hành động và trình cung cấp hành động.

Cảnh báo: Nếu bạn làm rối mã nguồn của mình bằng cách sử dụng ProGuard hoặc một công cụ tương tự, hãy nhớ loại trừ việc đổi tên lớp mà bạn chỉ định trong thuộc tính này, vì điều này có thể làm hỏng chức năng đó.

Ra mắt trong API cấp 14

android:alphabeticShortcut
Ký tự. Một ký tự cho phím tắt dạng chữ cái.
android:numericShortcut
Số nguyên. Một số cho phím tắt dạng số.
android:alphabeticModifiers
Từ khoá. Công cụ sửa đổi phím tắt chữ cái của mục trong trình đơn. Giá trị mặc định tương ứng với phím Control. Giá trị hợp lệ:
Giá trịMô tả
META Tương ứng với phím meta Meta.
CTRL Tương ứng với phím meta Control.
ALT Tương ứng với phím meta Alt.
SHIFT Tương ứng với phím meta Shift.
SYM Tương ứng với phím meta Sym.
FUNCTION Tương ứng với phím meta Function.

Lưu ý: Bạn có thể chỉ định nhiều từ khoá trong một thuộc tính. Ví dụ: android:alphabeticModifiers="CTRL|SHIFT" cho biết rằng để kích hoạt mục trong trình đơn tương ứng, người dùng cần nhấn cả hai phím meta ControlShift cùng với phím tắt.

Bạn có thể sử dụng phương thức setAlphabeticShortcut() để đặt giá trị thuộc tính theo phương thức lập trình. Để biết thêm thông tin về thuộc tính alphabeticModifier, hãy xem alphabeticModifiers.

android:numericModifiers
Từ khoá. Đối tượng sửa đổi phím tắt dạng số của mục trong trình đơn. Giá trị mặc định tương ứng với phím Control. Giá trị hợp lệ:
Giá trịMô tả
META Tương ứng với phím meta Meta.
CTRL Tương ứng với phím meta Control.
ALT Tương ứng với phím meta Alt.
SHIFT Tương ứng với phím meta Shift.
SYM Tương ứng với phím meta Sym.
FUNCTION Tương ứng với phím meta Function.

Lưu ý: Bạn có thể chỉ định nhiều từ khoá trong một thuộc tính. Ví dụ: android:numericModifiers="CTRL|SHIFT" cho biết rằng để kích hoạt mục trong trình đơn tương ứng, người dùng cần nhấn cả hai phím meta ControlShift cùng với phím tắt.

Bạn có thể sử dụng phương thức setNumericShortcut() để đặt giá trị thuộc tính theo phương thức lập trình. Để biết thêm thông tin về thuộc tính numericModifier, hãy xem numericModifiers.

android:checkable
Boolean. Đúng nếu mục đó có thể đánh dấu.
android:checked
Boolean. Đúng nếu mục đó được chọn theo mặc định.
android:visible
Boolean. Đúng nếu mục đó hiển thị theo mặc định.
android:enabled
Boolean. Đúng nếu mục đó được bật theo mặc định.
android:menuCategory
Từ khoá. Giá trị tương ứng với các hằng số Menu CATEGORY_*. Các hằng số này sẽ xác định mức độ ưu tiên của mục. Giá trị hợp lệ:
Giá trịMô tả
containerĐối với các mục là một phần của vùng chứa.
systemĐối với các mục do hệ thống cung cấp.
secondaryĐối với các mục là tuỳ chọn phụ do người dùng cung cấp (không thường xuyên sử dụng).
alternativeĐối với các mục là hành động thay thế trên dữ liệu đang hiển thị.
android:orderInCategory
Số nguyên. Thứ tự mức độ quan trọng của mục trong một nhóm.
<group>
Một nhóm trình đơn (để tạo một tập hợp các mục có chung đặc điểm, chẳng hạn như các mục đó có hiển thị, được bật hay có thể chọn hay không). Chứa một hoặc nhiều phần tử <item>. Phải là phần tử con của phần tử <menu>.

Thuộc tính:

android:id
Mã nhận dạng tài nguyên. Mã nhận dạng tài nguyên duy nhất. Để tạo mã nhận dạng tài nguyên mới cho mục này, hãy sử dụng biểu mẫu: "@+id/name". Biểu tượng dấu cộng cho biết mã này được tạo dưới dạng mã nhận dạng mới.
android:checkableBehavior
Từ khoá. Loại hành vi có thể chọn cho nhóm. Giá trị hợp lệ:
Giá trịMô tả
noneKhông thể chọn.
allBạn có thể chọn tất cả các mục (sử dụng hộp đánh dấu).
singleChỉ có thể chọn một mục (sử dụng nút chọn).
android:visible
Boolean. Đúng nếu nhóm đó hiển thị.
android:enabled
Boolean. Đúng nếu nhóm đó được bật.
android:menuCategory
Từ khoá. Giá trị tương ứng với các hằng số Menu CATEGORY_*. Các hằng số này sẽ xác định mức độ ưu tiên của nhóm. Giá trị hợp lệ:
Giá trịMô tả
containerĐối với các nhóm là một phần của vùng chứa.
systemĐối với các nhóm do hệ thống cung cấp.
secondaryĐối với các nhóm là tuỳ chọn phụ do người dùng cung cấp (không thường xuyên sử dụng).
alternativeĐối với các nhóm là hành động thay thế trên dữ liệu đang hiển thị.
android:orderInCategory
Số nguyên. Thứ tự mặc định của các mục trong danh mục.
ví dụ:
Tệp XML được lưu vào 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>

Mã xử lý ứng dụng sau đây sẽ tăng cường trình đơn từ lệnh gọi lại onCreateOptionsMenu(Menu), ngoài ra còn khai báo lệnh gọi lại khi nhấp vào hai trong số các mục:

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