منبع منو

منبع منو، منوِ برنامه (منوِ گزینه‌ها، منوِ بافت، یا منوِ فرعی) را تعریف می‌کند که می‌تواند با MenuInflater گسترش یابد.

برای راهنمای استفاده از منوها، افزودن منو را ببینید.

مکان فایل:
res/menu/filename.xml
نام فایل به‌عنوان شناسه منبع استفاده می‌شود
نوع داده منبع کامپایل‌شده:
اشاره‌گر منبع به منبع 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/name". علامت جمع نشان می‌دهد که این شناسه به‌عنوان شناسه جدیدی ایجاد شده است.
android:title
منبع رشته. عنوان منو به‌عنوان منبع رشته یا رشته خام.
android:titleCondensed
منبع رشته. عنوان خلاصه به‌عنوان منبع رشته یا رشته خام. این عنوان برای موقعیت‌هایی استفاده می‌شود که عنوان عادی خیلی طولانی است.
android:icon
منبع ترسیم‌شدنی. تصویری که به‌عنوان نماد گزینه منو استفاده می‌شود.
android:onClick
نام روش. روشی که هنگام کلیک کردن روی این گزینه منو فراخوانی می‌شود. روش باید در فعالیت به‌عنوان عمومی اعلام شود. یک MenuItem را به‌عنوان تنها پارامتر خود می‌پذیرد که نشان‌دهنده مورد کلیک‌شده است. این روش بر فراخوانی برگشتی استاندارد به onOptionsItemSelected() اولویت دارد. نمونه را در انتهای این صفحه ببینید.

هشدار: اگر کدتان را بااستفاده از ProGuard یا ابزار مشابهی مبهم‌سازی می‌کنید، حتماً روشی را که در این مشخصه تعیین می‌کنید از تغییر نام مستثنی کنید، زیرا می‌تواند عملکرد را مختل کند.

در سطح میانای برنامه‌سازی کاربردی ۱۱ معرفی شد.

android:showAsAction
کلیدواژه. زمان و نحوه نمایش این مورد به‌عنوان مورد اقدام در نوار برنامه. یک مورد منو فقط زمانی می‌تواند به‌عنوان یک مورد اقدام ظاهر شود که فعالیت شامل یک نوار برنامه باشد. مقادیر معتبر:
مقدارشرح
ifRoomفقط درصورتی این مورد را در نوار برنامه قرار دهید که برای آن جا وجود داشته باشد. اگر برای همه موارد علامت‌گذاری‌شده با "ifRoom" فضا وجود نداشته باشد، موارد با کمترین مقدار orderInCategory به‌عنوان کنش نمایش داده می‌شوند و موارد باقی‌مانده در منو سرریز نمایش داده می‌شوند.
withTextهمچنین نوشتار عنوان (تعریف‌شده توسط android:title) را با دستور اقدام اضافه کنید. می‌توانید این مقدار را همراه با یکی از مقادیر دیگر به‌عنوان مجموعه پرچم با جدا کردن آن‌ها با خط عمودی | اضافه کنید.
neverهرگز این مورد را در نوار برنامه قرار ندهید. درعوض، آن مورد را در منو سرریز نوار برنامه فهرست کنید.
alwaysهمیشه این مورد را در نوار برنامه قرار دهید. از این گزینه استفاده نکنید، مگراینکه ضروری باشد که مورد همیشه در نوار اقدام نشان داده شود. تنظیم کردن چند مورد برای اینکه همیشه به‌عنوان دستور اقدام نشان داده شوند می‌تواند باعث شود که آن‌ها با دیگر میانای کاربری در نوار برنامه هم‌پوشانی داشته باشند.
collapseActionViewنمای کنش مرتبط با این مورد اقدام (همان‌طور که توسط android:actionLayout یا android:actionViewClass اعلام شده است) جمع‌شدنی است.
در سطح میانای برنامه‌سازی کاربردی ۱۴ معرفی شده است.

برای اطلاعات بیشتر، به افزودن نوار برنامه مراجعه کنید.

در سطح میانای برنامه‌سازی کاربردی ۱۱ معرفی شد.

android:actionLayout
منبع چیدمان. چیدمانی برای استفاده به‌عنوان نمای کنش.

برای اطلاعات بیشتر، به استفاده از نماهای کنش و ارائه‌دهندگان کنش مراجعه کنید.

در سطح میانای برنامه‌سازی کاربردی ۱۱ معرفی شد.

android:actionViewClass
نام کلاس. نام کلاس کاملاً واجد شرایط برای View برای استفاده به‌عنوان نمای کنش. برای مثال، "android.widget.SearchView" برای استفاده از SearchView به‌عنوان نمای کنش.

برای اطلاعات بیشتر، به استفاده از نماهای کنش و ارائه‌دهندگان کنش مراجعه کنید.

هشدار: اگر کدتان را بااستفاده از ProGuard یا ابزار مشابهی مبهم‌سازی می‌کنید، حتماً کلاسی را که در این مشخصه تعیین می‌کنید از تغییر نام مستثنی کنید، زیرا می‌تواند عملکرد را مختل کند.

در سطح میانای برنامه‌سازی کاربردی ۱۱ معرفی شد.

android:actionProviderClass
نام کلاس. نام کلاس کاملاً واجدشرایط برای ActionProvider برای استفاده به‌جای دستور اقدام. برای مثال، "android.widget.ShareActionProvider" برای استفاده از ShareActionProvider.

برای اطلاعات بیشتر، به استفاده از نماهای کنش و ارائه‌دهندگان کنش مراجعه کنید.

هشدار: اگر کدتان را بااستفاده از ProGuard یا ابزار مشابهی مبهم‌سازی می‌کنید، حتماً کلاسی را که در این ویژگی مشخص می‌کنید از تغییر نام مستثنی کنید، زیرا می‌تواند عملکرد را مختل کند.

در سطح میانای برنامه‌سازی کاربردی ۱۴ معرفی شد.

android:alphabeticShortcut
Char. نویسه‌ای برای کلید میان‌بر الفبایی.
android:numericShortcut
عدد صحیح. عددی برای کلید میان‌بر عددی.
android:alphabeticModifiers
کلیدواژه. اصلاح‌کننده‌ای برای میان‌بر الفبایی گزینه منو. مقدار پیش‌فرض با کلید Control مطابقت دارد. مقادیر معتبر:
مقدارشرح
META مطابق با کلید متا Meta.
CTRL با کلید متا Control مطابقت دارد.
ALT با کلید متا Alt مطابقت دارد.
تبدیل مطابق با کلید متا تبدیل.
SYM با کلید متا Sym مطابقت دارد.
تابع با کلید متا تابع مطابقت دارد.

توجه: می‌توانید چند کلیدواژه را در یک مشخصه تعیین کنید. برای مثال، android:alphabeticModifiers="CTRL|SHIFT" نشان می‌دهد که برای راه‌اندازی گزینه منو مربوطه، کاربر باید هر دو کلید متا مهار و تبدیل را همراه با میان‌بر فشار دهد.

می‌توانید از روش setAlphabeticShortcut() برای تنظیم مقادیر مشخصه به‌صورت برنامه‌نویسی‌شده استفاده کنید. برای اطلاعات بیشتر درباره مشخصه alphabeticModifier، به alphabeticModifiers مراجعه کنید.

android:numericModifiers
کلیدواژه. تغییردهنده‌ای برای میان‌بر عددی گزینه منو. مقدار پیش‌فرض با کلید Control مطابقت دارد. مقادیر معتبر:
مقدارشرح
META مطابق با کلید متا Meta.
CTRL با کلید متا Control مطابقت دارد.
ALT با کلید متا Alt مطابقت دارد.
تبدیل مطابق با کلید متا تبدیل.
SYM با کلید متا Sym مطابقت دارد.
تابع با کلید متا تابع مطابقت دارد.

توجه: می‌توانید چند کلیدواژه را در یک مشخصه تعیین کنید. برای مثال، android:numericModifiers="CTRL|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/name". علامت به‌علاوه نشان می‌دهد که این شناسه به‌عنوان شناسه جدیدی ایجاد شده است.
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) باز می‌کند و همچنین بازخوانی کلیک کردن را برای دو مورد اعلام می‌کند:

کاتلین

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

جاوا

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