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

روش نوشتن را امتحان کنید

Jetpack Compose ابزار رابط کاربری پیشنهادی برای اندروید است. یاد بگیرید که چگونه کامپوننت‌ها را در Compose اضافه کنید.

نوار برنامه →

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

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

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

افزودن نمای اکشن

برای افزودن یک نمای اکشن، یک عنصر <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() ارسال کنید. برای مثال، ممکن است بخواهید اکتیویتی را بر اساس باز یا بسته شدن نمای اکشن به‌روزرسانی کنید. قطعه کد زیر نحوه تعریف و ارسال یک شنونده (listener) را نشان می‌دهد:

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 مراجعه کنید.