מקור מידע של תפריט

משאב תפריט מגדיר תפריט של אפליקציה – תפריט אפשרויות, תפריט הקשר או תפריט משנה – יכול להיות גבוה מ-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>

רכיבים:

<menu>

חובה. הוא חייב להיות צומת הרמה הבסיסית (root). מכיל <item> ו/או רכיבי <group>.

מאפיינים:

xmlns:android

מרחב שמות XML. חובה. מגדיר את מרחב השמות של XML, חייב להיות "http://schemas.android.com/apk/res/android".

<item>

אפשרות בתפריט. ייתכן שהיא תכלול רכיב <menu> (לתפריט משנה). חייב להיות צאצא של רכיב <menu> או <group>.

מאפיינים:

android:id

מזהה משאב מזהה משאב ייחודי. כדי ליצור מזהה משאב חדש לפריט, משתמשים בטופס הבא: "@+id/name" סמל הפלוס מציין שמחרוזת הזו נוצרה ID.

android:title

משאב מחרוזת. כותרת התפריט כמשאב מחרוזת או כמחרוזת גולמית.

android:titleCondensed

משאב מחרוזת. שם מרוכז כמשאב מחרוזת או מחרוזת גולמית. הזה הכותרת משמשת למצבים שבהם השם הרגיל ארוך מדי.

android:icon

משאב שניתן לשרטוט. תמונה שתשמש כסמל של אפשרות בתפריט.

android:onClick

שם ה-method. השיטה להפעיל כאשר לוחצים על האפשרות הזו בתפריט. יש להצהיר על השיטה כציבורית בפעילות. הוא מקבל MenuItem בתור בלבד, שמציין את הפריט שעליו המשתמש לחץ. השיטה הזו מקבלת עדיפות על פני השיטה הרגילה קריאה חוזרת אל onOptionsItemSelected(). לצפייה בסוף הדף הזה.

אזהרה: אם מבצעים ערפול קוד (obfuscation) באמצעות 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 כתצוגה של פעולה.

מידע נוסף זמין במאמר שימוש בפעולה ספקים של צפיות ופעולות.

אזהרה: אם מבצעים ערפול קוד (obfuscation) באמצעות ProGuard או כלי דומה, חשוב להחריג את המחלקה שציינתם במאפיין הזה כדי לא לשנות את השם שלה, כי היא עלולה לשבש את החדשה.

התכונה הופעלה ברמת API 11.

android:actionProviderClass

שם הכיתה. שם מחלקה מוגדר במלואו שבו ActionProvider יכול להשתמש במקום הפעולה לביצוע. לדוגמה, "android.widget.ShareActionProvider" כדי להשתמש ב-ShareActionProvider.

מידע נוסף זמין במאמר שימוש בפעולה ספקים של צפיות ופעולות.

אזהרה: אם מבצעים ערפול קוד (obfuscation) באמצעות ProGuard או כלי דומה, חשוב להחריג את המחלקה שציינתם במאפיין הזה כדי לא לשנות את השם שלה, כי היא עלולה לשבש את החדשה.

התכונה הופעלה ברמת API 14.

android:alphabeticShortcut

צ'אר. תו למקש הקיצור האלפביתי.

android:numericShortcut

מספר שלם. מספר למקש הקיצור המספרי.

android:alphabeticModifiers

מילת מפתח. מקש צירוף של האפשרות בתפריט מקש קיצור. ערך ברירת המחדל תואם לעמודה Control מקש. הערכים התקפים:

ערך	תיאור
META	תואם למטא מפתח Meta.
Ctrl	תואם למטא-מקש Control.
ALT	תואם למטא מקש Alt.
SHIFT	תואם למטא מקש Shift.
SYM	תואם למטא מפתח Sym.
פונקציות	תואם למטא מפתח Function.

הערה: ניתן לציין כמה מילות מפתח בכל מילת מפתח . לדוגמה, android:alphabeticModifiers="CTRL|SHIFT" מציין שכדי להפעיל את האפשרות המתאימה בתפריט, המשתמש צריך ללחוץ גם על מקשי המטא Control ו-Shift באמצעות קיצור הדרך.

אפשר להשתמש בשיטה setAlphabeticShortcut() כדי להגדיר את ערכי המאפיינים באופן פרוגרמטי. אפשר לקבל מידע נוסף על המאפיין alphabeticModifier, ראו alphabeticModifiers.

android:numericModifiers

מילת מפתח. מקש צירוף לקיצור הדרך המספרי של האפשרות בתפריט. ערך ברירת המחדל תואם למפתח Control. נתונים תקפים ערכים:

ערך	תיאור
META	תואם למטא מפתח Meta.
Ctrl	תואם למטא-מקש Control.
ALT	תואם למטא מקש Alt.
SHIFT	תואם למטא מקש Shift.
SYM	תואם למטא מפתח Sym.
פונקציות	תואם למטא מפתח Function.

הערה: ניתן לציין כמה מילות מפתח בכל מילת מפתח . לדוגמה, android:numericModifiers="CTRL|SHIFT" מציין שכדי להפעיל את האפשרות המתאימה בתפריט, המשתמש צריך ללחוץ גם על מקשי המטא Control ו-Shift באמצעות קיצור הדרך.

אפשר להשתמש ב-method setNumericShortcut() כדי להגדיר את ערכי המאפיינים באופן פרוגרמטי. מידע נוסף על המאפיין numericModifier: numericModifiers.

android:checkable

בוליאני. הערך הוא True אם ניתן לסמן את הפריט.

android:checked

בוליאני. הערך הוא True אם הפריט מסומן כברירת מחדל.

android:visible

בוליאני. הערך הוא True אם הפריט גלוי כברירת מחדל.

android:enabled

בוליאני. הערך הוא True אם הפריט מופעל כברירת מחדל.

android:menuCategory

מילת מפתח. ערך שתואם ל-Menu CATEGORY_* קבועים, שמגדירים את העדיפות של הפריט. הערכים התקפים:

ערך	תיאור
container	עבור פריטים שהם חלק מאגר תגים.
system	לגבי פריטים שסופקו על ידי המערכת.
secondary	לפריטים שסופקו על ידי המשתמשים כמשניים אפשרויות (בשימוש לעתים רחוקות).
alternative	לפריטים שהם פעולות חלופיות על הנתונים שמוצגים כרגע.

android:orderInCategory

מספר שלם. סדר החשיבות של הפריט בקבוצה.

<group>

קבוצת תפריטים, כדי ליצור אוסף של פריטים שיש להם מאפיינים משותפים, למשל אם הם גלוי, מופעל או ניתן לבחירה. מכיל רכיב <item> או יותר. חייב להיות צאצא של רכיב <menu>.

מאפיינים:

android:id

מזהה משאב מזהה משאב ייחודי. כדי ליצור מזהה משאב חדש לפריט הזה: יש להשתמש בטופס: "@+id/name" סמל הפלוס מציין שמחרוזת הזו נוצרה ID.

android:checkableBehavior

מילת מפתח. סוג ההתנהגות שניתן לבחור עבור הקבוצה. הערכים התקפים:

ערך	תיאור
none	לא ניתן לבחירה.
all	ניתן לבחור את כל הפריטים (יש להשתמש בתיבות סימון).
single	ניתן לבחור רק פריט אחד (יש להשתמש ברדיו) ).

android:visible

בוליאני. הערך הוא True אם הקבוצה גלויה.

android:enabled

בוליאני. הערך הוא True אם הקבוצה מופעלת.

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>

קוד האפליקציה הבא מגדיל את התפריט מהקריאה החוזרת (callback) של onCreateOptionsMenu(Menu) ומצהיר גם על פעולות לחיצה קריאה חוזרת (callback) לשניים מהפריטים:

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