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

Toolbar کتابخانه AndroidX راه های مختلفی را برای تعامل کاربران با برنامه شما فراهم می کند. عملکردهای افزودن و رسیدگی را توضیح می دهد که چگونه می توان یک عملکرد را تعریف کرد که می تواند یک دکمه یا یک آیتم منو باشد. این سند نحوه اضافه کردن دو مؤلفه همه کاره را شرح می دهد:

• نمای اقدام عملی است که عملکردی غنی در نوار برنامه ارائه می دهد. برای مثال، نمای عمل جستجو به کاربر اجازه می‌دهد متن جستجوی خود را بدون نیاز به تغییر فعالیت‌ها یا قطعات در نوار برنامه تایپ کند.
• ارائه‌دهنده اکشن اقدامی با طرح‌بندی سفارشی‌شده خود است. عمل در ابتدا به عنوان یک دکمه یا آیتم منو ظاهر می شود. هنگامی که کاربر روی عمل ضربه می زند، ارائه دهنده اقدام، رفتار عمل را به هر طریقی که شما تعریف کنید کنترل می کند. به عنوان مثال، ارائه دهنده اقدام ممکن است با نمایش یک منو به یک ضربه پاسخ دهد.

AndroidX چندین ویجت اکشن ویژه و ویجت ارائه دهنده اقدام را ارائه می دهد. برای مثال، ویجت SearchView یک نمای عملی را برای وارد کردن عبارت‌های جستجو پیاده‌سازی می‌کند. ویجت ShareActionProvider یک ارائه‌دهنده اقدام برای اشتراک‌گذاری اطلاعات با برنامه‌های دیگر پیاده‌سازی می‌کند. همچنین می توانید نماهای اقدام و ارائه دهندگان اقدام خود را تعریف کنید.

یک نمای اقدام اضافه کنید

برای افزودن یک نمای اقدام، یک عنصر <item> در منبع منوی نوار ابزار ایجاد کنید، همانطور که در Add and handle actions توضیح داده شده است. یکی از ویژگی های زیر را به عنصر <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() را لغو کند، روش override شما باید super.onOptionsItemSelected() را فراخوانی کند تا superclass بتواند نمای عمل را گسترش دهد.

اگر می‌خواهید زمانی که اکشن باز یا جمع می‌شود کاری انجام دهید، می‌توانید کلاسی را تعریف کنید که 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;
}

یک ارائه دهنده اقدام اضافه کنید

برای اعلام یک ارائه دهنده اقدام، همانطور که در Add and handle actions توضیح داده شده است، یک عنصر <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 مراجعه کنید.