استفاده از نماهای کنش و ارائه‌دهندگان کنش

امتحان کردن روش Compose
Jetpack Compose جعبه‌ابزار واسط کاربر توصیه‌شده برای Android است. با نحوه افزودن مؤلفه‌ها در Compose آشنا شوید.
نوار برنامه →

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() فراخوانی فعالیتتان انجام دهید. با فراخوانی روش 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 را ببینید.