استخدام قوائم الإجراءات والإجراءات

توفّر مكتبة AndroidX Toolbar طرقًا مختلفة للمستخدمين للتفاعل مع تطبيقك. وتصف طريقة الإضافة والتعامل مع الإجراءات كيفية تحديد إجراء، والذي يمكن أن يكون زرًا أو عنصرًا في القائمة. يصف هذا المستند كيفية إضافة مكونين متعددي الاستخدامات:

  • عرض الإجراء هو إجراء يوفر وظائف كثيرة ضمن شريط التطبيقات. على سبيل المثال، تتيح طريقة عرض إجراء البحث للمستخدم كتابة نص البحث في شريط التطبيق بدون الحاجة إلى تغيير الأنشطة أو الأجزاء.
  • مزوّد الإجراءات هو إجراء بتنسيقه المخصّص. في البداية، يظهر الإجراء على شكل زرّ أو عنصر قائمة، وعندما ينقر المستخدم على الإجراء، يتحكّم موفر الإجراء في سلوك الإجراء بأي طريقة تحدِّدها. على سبيل المثال، قد يستجيب مقدّم الإجراءات لإحدى النقرات من خلال عرض قائمة.

يوفّر AndroidX العديد من الأدوات المتخصّصة لعرض الإجراءات ومقدمي الإجراءات. على سبيل المثال، تنفِّذ أداة SearchView عرض الإجراءات لإدخال طلبات البحث. تنفِّذ ShareActionProvider التطبيق مزوّد إجراءات لمشاركة المعلومات مع تطبيقات أخرى. يمكنك أيضًا تحديد طرق عرض الإجراءات ومزوّدي الإجراءات

إضافة عرض إجراء

لإضافة عرض إجراء، يمكنك إنشاء عنصر <item> في مورد القائمة بشريط الأدوات على النحو الموضّح في إضافة الإجراءات والتعامل معها. أضِف إحدى السمات التالية إلى عنصر <item>:

  • actionViewClass: فئة التطبيق المصغّر الذي ينفّذ الإجراء
  • actionLayout: مورد تنسيق يصف مكوّنات الإجراء

اضبط السمة showAsAction على "ifRoom|collapseActionView" أو "never|collapseActionView". وتوضّح العلامة collapseActionView طريقة عرض التطبيق المصغّر في حال عدم تفاعل المستخدم معه. إذا كانت الأداة على شريط التطبيق، فسيعرض التطبيق الأداة كرمز. إذا كانت الأداة موجودة في القائمة الكاملة، يعرض التطبيق الأداة كعنصر قائمة. عندما يتفاعل المستخدم مع عرض الإجراء، يتم توسيعه لملء شريط التطبيق.

على سبيل المثال، يضيف الرمز التالي أداة SearchView إلى شريط التطبيقات:

<item android:id="@+id/action_search"
     android:title="@string/action_search"
     android:icon="@drawable/ic_search"
     app:showAsAction="ifRoom|collapseActionView"
     app:actionViewClass="androidx.appcompat.widget.SearchView" />

وفي حال عدم تفاعل المستخدم مع التطبيق المصغّر، يعرضه كرمز محدّد في android:icon. إذا لم تكن هناك مساحة في شريط التطبيق، فسيضيف التطبيق الإجراء إلى القائمة الكاملة.

صورة تعرض شريط بحث يتضمّن رمزين في البداية والنهاية.
الشكل 1. شريط البحث الذي يتضمّن رمزين في البداية والنهاية

وعندما ينقر المستخدم على الرمز أو عنصر القائمة، يتم توسيع الأداة لملء شريط الأدوات، مما يتيح للمستخدم التفاعل معه.

صورة تعرض طريقة عرض البحث وهي مفتوحة بعد التركيز على شريط البحث.
الشكل 2. يتم فتح طريقة عرض البحث بعد التركيز على شريط البحث.

إذا أردت إعداد الإجراء، يمكنك تنفيذ ذلك من خلال ميزة معاودة الاتصال onCreateOptionsMenu() بنشاطك. يمكنك الحصول على مرجع كائن عرض الإجراء عن طريق استدعاء الطريقة getActionView(). على سبيل المثال، يحصل الرمز البرمجي التالي على مرجع الكائن للأداة SearchView المحدّدة في مثال الرمز السابق:

Kotlin

override fun onCreateOptionsMenu(menu: Menu?): Boolean {
    menuInflater.inflate(R.menu.main_activity_actions, menu)

    val searchItem = menu?.findItem(R.id.action_search)
    val searchView = searchItem?.actionView as SearchView

    // Configure the search info and add any event listeners.

    return super.onCreateOptionsMenu(menu)
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    getMenuInflater().inflate(R.menu.main_activity_actions, menu);

    MenuItem searchItem = menu.findItem(R.id.action_search);
    SearchView searchView =
            (SearchView) searchItem.getActionView();

    // Configure the search info and add any event listeners.

    return super.onCreateOptionsMenu(menu);
}

الاستجابة لتوسيع عرض الإجراء

إذا كان العنصر <item> الخاص بالإجراء يتضمّن العلامة collapseActionView، سيعرض التطبيق عرض الإجراء كرمز إلى أن يتفاعل المستخدم مع عرض الإجراء. عندما ينقر المستخدم على الرمز، يعمل المعالج المضمَّن في onOptionsItemSelected() على توسيع عرض الإجراء. إذا ألغت فئة نشاطك الفرعية طريقة onOptionsItemSelected()، يجب أن تستدعي طريقة الإلغاء super.onOptionsItemSelected() حتى تتمكّن الفئة الرئيسية من توسيع عرض الإجراء.

إذا أردت تنفيذ إجراء عندما يتم توسيع الإجراء أو تصغيره، يمكنك تحديد فئة ينفّذها MenuItem.OnActionExpandListener، وإضافة أحد أعضاء هذا الصف إلى setOnActionExpandListener(). على سبيل المثال، قد تحتاج إلى تعديل النشاط استنادًا إلى ما إذا كان عرض الإجراء قد تم توسيعه أو تصغيره. يوضّح مقتطف الرمز التالي كيفية تحديد أداة معالجة الحدث وتمريرها:

Kotlin

override fun onCreateOptionsMenu(menu: Menu?): Boolean {
    menuInflater.inflate(R.menu.options, menu)

    // Define the listener.
    val expandListener = object : MenuItem.OnActionExpandListener {
        override fun onMenuItemActionCollapse(item: MenuItem): Boolean {
            // Do something when the action item collapses.
            return true // Return true to collapse the action view.
        }

        override fun onMenuItemActionExpand(item: MenuItem): Boolean {
            // Do something when it expands.
            return true // Return true to expand the action view.
        }
    }

    // Get the MenuItem for the action item.
    val actionMenuItem = menu?.findItem(R.id.myActionItem)

    // Assign the listener to that action item.
    actionMenuItem?.setOnActionExpandListener(expandListener)

    // For anything else you have to do when creating the options menu,
    // do the following:

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    getMenuInflater().inflate(R.menu.options, menu);

    // Define the listener.
    OnActionExpandListener expandListener = new OnActionExpandListener() {
        @Override
        public boolean onMenuItemActionCollapse(MenuItem item) {
            // Do something when the action item collapses.
            return true;  // Return true to collapse action view.
        }

        @Override
        public boolean onMenuItemActionExpand(MenuItem item) {
            // Do something when it expands.
            return true;  // Return true to expand the action view.
        }
    };

    // Get the MenuItem for the action item.
    MenuItem actionMenuItem = menu.findItem(R.id.myActionItem);

    // Assign the listener to that action item.
    MenuItemCompat.setOnActionExpandListener(actionMenuItem, expandListener);

    // For anything else you have to do when creating the options menu,
    // do the following:

    return true;
}

إضافة مقدِّم إجراءات

للإعلان عن موفِّر إجراءات، أنشِئ عنصر <item> في مورد قائمة شريط الأدوات، كما هو موضّح في القسم إضافة الإجراءات والتعامل معها. أضِف السمة actionProviderClass واضبطها على اسم الفئة المؤهّل بالكامل لفئة مقدّم الإجراء.

على سبيل المثال، يذكر الرمز التالي ShareActionProvider، وهي أداة تم تعريفها في مكتبة AndroidX تتيح لتطبيقك مشاركة البيانات مع التطبيقات الأخرى:

<item android:id="@+id/action_share"
    android:title="@string/share"
    app:showAsAction="ifRoom"
    app:actionProviderClass="androidx.appcompat.widget.ShareActionProvider"/>

في هذه الحالة، ليس من الضروري الإعلان عن رمز للتطبيق المصغّر، لأنّ السمة ShareActionProvider توفّر رسوماتها الخاصة. إذا كنت تستخدم إجراءً مخصصًا، عليك تحديد رمز.

مراجع إضافية

  • ويمكنك الاطّلاع على ShareActionProvider للحصول على مثال لإضافة إجراء مشاركة إلى شريط التطبيقات العلوي.
  • يُرجى الاطّلاع على ActionProvider للحصول على مزيد من المعلومات عن إنشاء مقدِّم إجراءات مخصّصة.