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

تجربة ميزة "الكتابة"

‫Jetpack Compose هي مجموعة أدوات واجهة المستخدم المُقترَحة لنظام التشغيل Android. تعرَّف على كيفية إضافة مكوّنات في ميزة "الإنشاء".

شريط التطبيقات →

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

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

يوفّر 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. إذا لم يكن هناك مساحة في شريط التطبيق، يضيف التطبيق الإجراء إلى قائمة الخيارات الإضافية.

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

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

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

@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(). على سبيل المثال، قد تحتاج إلى تعديل النشاط استنادًا إلى ما إذا كان عرض الإجراء منبسطًا أو مجمّعًا. يوضّح مقتطف الرمز البرمجي التالي كيفية تحديد مستمع وإرساله:

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
}

@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 للحصول على المزيد من المعلومات عن إنشاء مقدّم إجراءات مخصّص.