مورد القائمة

يحدّد مورد القائمة قائمة تطبيق، مثل قائمة خيارات أو قائمة سياق أو قائمة فرعية، يمكن تضخيمها باستخدام 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 أو أداة مشابهة، احرص على استبعاد الطريقة التي تحدّدها في هذه السمة من إعادة التسمية، لأن ذلك قد يؤدي إلى إيقاف الوظائف.

تم تقديمه في المستوى 11 من واجهة برمجة التطبيقات.

android:showAsAction
الكلمة الرئيسية: وقت ظهور هذا العنصر وكيفية ظهوره كبند عمل في شريط التطبيق. لا يمكن أن يظهر عنصر القائمة كبند عمل إلا عندما يتضمن النشاط شريط تطبيقات. قيم صالحة:
القيمةالوصف
ifRoomضَع هذا العنصر في شريط التطبيقات فقط إذا كان هناك مساحة له. وإذا لم تتوفر مساحة لكل العناصر التي تم وضع علامة "ifRoom" عليها، يتم عرض العناصر ذات أدنى قيمة orderInCategory كإجراءات، ويتم عرض العناصر المتبقية في القائمة الكاملة.
withTextأدرِج أيضًا نص العنوان (من خلال android:title) مع بند العمل. يمكنك تضمين هذه القيمة مع واحدة من القيم الأخرى كعلامة تم ضبطها من خلال الفصل بينها باستخدام ممر |.
neverلا تضع هذا العنصر في شريط التطبيقات مطلقًا. يمكنك بدلاً من ذلك إدراج العنصر في القائمة الكاملة لشريط التطبيق.
alwaysضع هذا العنصر في شريط التطبيق دائمًا. تجنَّب استخدام هذا إلا إذا كان من الضروري أن يظهر العنصر دائمًا في شريط الإجراءات. قد يؤدي تعيين عناصر متعددة لتظهر دائمًا كبنود عمل إلى تداخلها مع واجهة مستخدم أخرى في شريط التطبيق.
collapseActionViewإنّ عرض الإجراء المرتبط بعنصر العمل هذا (كما هو موضّح في android:actionLayout أو android:actionViewClass) يمكن تصغيره.
تم طرحه في المستوى 14 من واجهة برمجة التطبيقات.

راجِع مقالة إضافة شريط التطبيقات لمعرفة مزيد من المعلومات.

تم تقديمه في المستوى 11 من واجهة برمجة التطبيقات.

android:actionLayout
مورد التنسيق. تنسيق لاستخدامه في عرض الإجراء

لمزيد من المعلومات، اطّلِع على استخدام طرق عرض الإجراءات ومزوّدي الإجراءات.

تم تقديمه في المستوى 11 من واجهة برمجة التطبيقات.

android:actionViewClass
اسم الصف. اسم فئة مؤهل بالكامل لـ View لاستخدامه كعرض إجراء على سبيل المثال، "android.widget.SearchView" لاستخدام SearchView في عرض الإجراء.

لمزيد من المعلومات، اطّلِع على استخدام طرق عرض الإجراءات ومزوّدي الإجراءات.

تحذير: إذا خفّفت في الرمز باستخدام ProGuard أو أداة مشابهة، احرص على استبعاد الفئة التي تحدّدها في هذه السمة من إعادة التسمية، لأنّ ذلك قد يؤدي إلى إيقاف الوظائف.

تم تقديمه في المستوى 11 من واجهة برمجة التطبيقات.

android:actionProviderClass
اسم الصف. اسم فئة مؤهل تمامًا لـ ActionProvider لاستخدامه بدلاً من بند العمل. على سبيل المثال، "android.widget.ShareActionProvider" لاستخدام ShareActionProvider.

لمزيد من المعلومات، اطّلِع على استخدام طرق عرض الإجراءات ومزوّدي الإجراءات.

تحذير: إذا خفّفت في الرمز باستخدام ProGuard أو أداة مشابهة، احرص على استبعاد الفئة التي تحدّدها في هذه السمة من إعادة التسمية، لأنّ ذلك قد يؤدي إلى إيقاف الوظائف.

تم تقديمه في المستوى 14 من واجهة برمجة التطبيقات.

android:alphabeticShortcut
Char: حرف لمفتاح الاختصار الأبجدي.
android:numericShortcut
عدد صحيح. رقم لمفتاح الاختصار الرقمي.
android:alphabeticModifiers
الكلمة الرئيسية: معدِّل للاختصار الأبجدي لعنصر القائمة. وتطابق القيمة التلقائية المفتاح Control. قيم صالحة:
القيمةالوصف
META يتطابق مع المفتاح الوصفي Meta.
مفتاح CTRL يناظر المفتاح الوصفي Control.
نص بديل يتطابق مع المفتاح الوصفي Alt.
النوبة يتطابق مع المفتاح الوصفي Shift.
SYM يتطابق مع المفتاح الوصفي Sym.
الوظيفة يناظر المفتاح الوصفي Function.

ملاحظة: يمكنك تحديد كلمات رئيسية متعددة في سمة واحدة. على سبيل المثال، تشير السمة android:alphabeticModifiers="CTRL|SHIFT" إلى أنّ المستخدم بحاجة إلى الضغط على مفتاحَي التعريف Control وShift مع الاختصار.

يمكنك استخدام الطريقة setAlphabeticShortcut() لضبط قيم السمات بشكل آلي. لمزيد من المعلومات حول السمة alphabeticModifier، يمكنك مراجعة alphabeticModifiers.

android:numericModifiers
الكلمة الرئيسية: معدِّل للاختصار الرقمي لعنصر القائمة. تتطابق القيمة التلقائية مع المفتاح Control. القيم الصالحة:
القيمةالوصف
الشرق الأوسط يتطابق مع المفتاح الوصفي Meta.
مفتاح CTRL يناظر المفتاح الوصفي Control.
نص بديل يتطابق مع المفتاح الوصفي Alt.
النوبة يتطابق مع المفتاح الوصفي Shift.
SYM يتطابق مع المفتاح الوصفي Sym.
الوظيفة يناظر المفتاح الوصفي Function.

ملاحظة: يمكنك تحديد كلمات رئيسية متعددة في سمة واحدة. على سبيل المثال، تشير السمة android:numericModifiers="CTRL|SHIFT" إلى أنّ المستخدم بحاجة إلى الضغط على مفتاحَي التعريف Control وShift مع الاختصار.

يمكنك استخدام الطريقة 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". يشير رمز الجمع إلى أنه تم إنشاؤه كمعرف جديد.
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>

يعمل رمز التطبيق التالي على تضخيم القائمة من خلال معاودة الاتصال onCreateOptionsMenu(Menu) كما يعلن عن معاودة الاتصال عند النقر لاثنين من العناصر:

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