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

تجربة طريقة "الكتابة"

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

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

ملاحظة: للحصول على أسلوب أفضل وتجربة مستخدم أفضل، ننصحك بنقل مشاريعك تدريجيًا إلى Jetpack Compose.

توفّر مكتبة 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);
}

ملاحظة: لتحسين مظهر SearchView، راجِع مكوِّن البحث في التصميم المتعدد الأبعاد 3.

الردّ على توسيع عرض الإجراء

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