ارائه چیدمان‌های انعطاف‌پذیر ابزاره

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

این صفحه اصلاحات مربوط به اندازه ابزاره و انعطاف‌پذیری بیشتر را که در Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۱) معرفی شده است شرح می‌دهد. همچنین نحوه تعیین اندازه برای ابزاره را شرح می‌دهد.

استفاده از میاناهای برنامه‌سازی کاربردی بهبودیافته برای اندازه‌ها و چیدمان‌های ابزارک

از Android نسخه ۱۲ (سطح میانای برنامه‌سازی کاربردی ۳۱) به بعد، می‌توانید با انجام کارهای زیر، که در بخش‌های بعدی شرح داده شده است، مشخصه‌های اندازه دقیق‌تر و چیدمان‌های انعطاف‌پذیرتری ارائه دهید:

  1. محدودیت‌های اضافی برای اندازه ابزاره مشخص کنید.

  2. ارائه چیدمان‌های واکنش‌گرا یا چیدمان‌های دقیق.

در نسخه‌های قبلی Android، می‌توان بااستفاده از موارد اضافی OPTION_APPWIDGET_MIN_WIDTH، OPTION_APPWIDGET_MIN_HEIGHT، OPTION_APPWIDGET_MAX_WIDTH، و OPTION_APPWIDGET_MAX_HEIGHT محدوده اندازه ابزاره را دریافت کرد و سپس اندازه ابزاره را تخمین زد، اما این منطق در همه شرایط کار نمی‌کند. برای ابزارهایی که Android نسخه ۱۲ یا بالاتر را هدف قرار می‌دهند، توصیه می‌کنیم چیدمان‌های واکنش‌گرا یا دقیق ارائه دهید.

محدودیت‌های اضافی برای اندازه ابزاره مشخص کنید

Android 12 میاناهای برنامه‌سازی کاربردی‌ای اضافه می‌کند که به شما امکان می‌دهد مطمئن شوید ابزاره‌تان در دستگاه‌های مختلف با اندازه‌های صفحه‌نمایش متفاوت، به‌طور مطمئن‌تری اندازه‌بندی می‌شود.

علاوه‌بر مشخصه‌های موجود minWidth، minHeight، minResizeWidth، و minResizeHeight، از مشخصه‌های جدید appwidget-provider زیر استفاده کنید:

  • targetCellWidth و targetCellHeight: اندازه هدف ابزارک را براساس سلول‌های جدول راه‌انداز تعریف می‌کند. اگر تعریف شده باشد، از این مشخصه‌ها به‌جای minWidth یا minHeight استفاده می‌شود.

  • maxResizeWidth و maxResizeHeight: حداکثر اندازه‌ای را که راه‌انداز به کاربر اجازه می‌دهد اندازه ابزارک را به آن تغییر دهد تعریف می‌کند.

XML زیر نحوه استفاده از مشخصه‌های اندازه‌گذاری را نشان می‌دهد.

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
  android:targetCellWidth="3"
  android:targetCellHeight="2"
  android:maxResizeWidth="250dp"
  android:maxResizeHeight="110dp">
</appwidget-provider>

ارائه چیدمان‌های واکنش‌گرا

اگر چیدمان باید بسته به اندازه ابزاره تغییر کند، توصیه می‌کنیم مجموعه کوچکی از چیدمان‌ها ایجاد کنید که هرکدام برای طیفی از اندازه‌ها معتبر باشد. اگر این کار امکان‌پذیر نیست، گزینه دیگر این است که چیدمان‌ها را براساس اندازه دقیق ابزاره در زمان اجرا ارائه دهید، همان‌طور که در این صفحه شرح داده شده است.

این ویژگی امکان مقیاس‌بندی روان‌تر و به‌طور کلی سلامت بهتر سیستم را فراهم می‌کند، زیرا سیستم مجبور نیست هر بار که ابزاره را در اندازه متفاوتی نمایش می‌دهد، برنامه را بیدار کند.

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

override fun onUpdate(
    /* ... */
) {
    val smallView = RemoteViews(
        /* ... */
    )
    val tallView = RemoteViews(
        /* ... */
    )
    val wideView = RemoteViews(
        /* ... */
    )

    val viewMapping: Map<SizeF, RemoteViews> = mapOf(
        SizeF(150f, 100f) to smallView,
        SizeF(150f, 200f) to tallView,
        SizeF(215f, 100f) to wideView
    )
    val remoteViews = RemoteViews(viewMapping)

    appWidgetManager.updateAppWidget(id, remoteViews)
}

فرض کنید ابزاره مشخصه‌های زیر را دارد:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="160dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="200dp">
</appwidget-provider>

تکه‌کد قبلی به‌معنی موارد زیر است:

  • smallView از ۱۶۰ دی‌پی (minResizeWidth) × ۱۱۰ دی‌پی (minResizeHeight) تا ۱۶۰ دی‌پی × ۱۹۹ دی‌پی (نقطه قطع بعدی - ۱ دی‌پی) را پشتیبانی می‌کند.
  • tallView از ۱۶۰ دی‌پی × ۲۰۰ دی‌پی تا ۲۱۴ دی‌پی (نقطه قطع بعدی - ۱) × ۲۰۰ دی‌پی را پشتیبانی می‌کند.

  • wideView از ۲۱۵dp ×‏ ۱۱۰dp‏ (minResizeHeight) تا ۲۵۰dp‏ (maxResizeWidth) ×‏ ۲۰۰dp‏ (maxResizeHeight) را پشتیبانی می‌کند.

ابزاره شما باید از محدوده اندازه minResizeWidth × minResizeHeight تا maxResizeWidth × maxResizeHeight پشتیبانی کند. در این محدوده، می‌توانید نقطه قطع را برای تغییر چیدمان‌ها تعیین کنید.

نمونه چیدمان واکنش‌گرا
شکل ۱. نمونه‌ای از چیدمان واکنش‌گرا.

ارائه طرح‌بندی‌های دقیق

اگر مجموعه کوچکی از طرح‌بندی‌های واکنش‌گرا امکان‌پذیر نیست، می‌توانید درعوض طرح‌بندی‌های مختلفی را ارائه دهید که متناسب با اندازه‌هایی باشد که ابزاره در آن‌ها نشان داده می‌شود. این معمولاً دو اندازه برای تلفن‌ها (حالت عمودی و افقی) و چهار اندازه برای دستگاه‌های تاشو است.

برای پیاده‌سازی این راه‌حل، برنامه‌تان باید مراحل زیر را انجام دهد:

  1. Overload AppWidgetProvider.onAppWidgetOptionsChanged()، که وقتی مجموعه اندازه‌ها تغییر می‌کند فراخوانی می‌شود.

  2. AppWidgetManager.getAppWidgetOptions() را فراخوانی کنید، که Bundle حاوی اندازه‌ها را برمی‌گرداند.

  3. از Bundle به کلید AppWidgetManager.OPTION_APPWIDGET_SIZES دسترسی پیدا کنید.

نمونه کد زیر نحوه ارائه چیدمان‌های دقیق را نشان می‌دهد.

override fun onAppWidgetOptionsChanged(
    context: Context,
    appWidgetManager: AppWidgetManager,
    id: Int,
    newOptions: Bundle?
) {
    super.onAppWidgetOptionsChanged(context, appWidgetManager, id, newOptions)
    // Get the new sizes.
    val sizes = newOptions?.let {
        BundleCompat.getParcelableArrayList(
            it,
            AppWidgetManager.OPTION_APPWIDGET_SIZES,
            SizeF::class.java
        )
    }
    // Check that the list of sizes is provided by the launcher.
    if (sizes.isNullOrEmpty()) {
        return
    }
    // Map the sizes to the RemoteViews that you want.
    val remoteViews = RemoteViews(sizes.associateWith(::createRemoteViews))
    appWidgetManager.updateAppWidget(id, remoteViews)
}

// Create the RemoteViews for the given size.
private fun createRemoteViews(size: SizeF): RemoteViews {
}

اندازه ابزاره را تعیین کنید

هر ابزاره باید targetCellWidth و targetCellHeight را برای دستگاه‌های دارای Android نسخه ۱۲ یا بالاتر—یا minWidth و minHeight را برای همه نسخه‌های Android—تعریف کند تا حداقل فضای مصرفی به‌طور پیش‌فرض مشخص شود. اما وقتی کاربران ابزاره‌ای را به صفحه اصلی‌شان اضافه می‌کنند، معمولاً بیشتر از حداقل عرض و ارتفاعی که مشخص کرده‌اید را اشغال می‌کند.

صفحه‌های اصلی Android شبکه‌ای از فضاهای دردسترس را به کاربران ارائه می‌دهند که می‌توانند ابزاره‌ها و نمادها را در آن قرار دهند. این شبکه می‌تواند بسته به دستگاه متفاوت باشد؛ برای مثال، بسیاری از گوشی‌ها شبکه ۵×۴ ارائه می‌دهند و رایانه‌های لوحی می‌توانند شبکه بزرگ‌تری ارائه دهند. وقتی ابزاره شما اضافه می‌شود، کشیده می‌شود تا حداقل تعداد سلول‌های لازم را به‌صورت افقی و عمودی اشغال کند تا محدودیت‌های targetCellWidth و targetCellHeight آن در دستگاه‌های دارای Android 12 یا بالاتر، یا محدودیت‌های minWidth و minHeight در دستگاه‌های دارای Android 11 (سطح میانای برنامه‌سازی کاربردی ۳۰) یا پایین‌تر برآورده شود.

ابعاد سلول و حاشیه‌های خودکار در دستگاه‌های مختلف متفاوت است. از جدول زیر برای تخمین حداقل ابعاد ابزاره‌تان در یک گوشی معمولی با شبکه ۵×۴ استفاده کنید، با توجه به تعداد سلول‌های شبکه اشغال‌شده‌ای که می‌خواهید:

تعداد سلول‌ها (عرض × ارتفاع) اندازه دردسترس در حالت عمودی (dp) اندازه دردسترس در حالت افقی (dp)
۱x۱ ‫۵۷×۱۰۲ پیکسل مستقل از تراکم ‫۱۲۷×۵۱ پیکسل مستقل از تراکم
‫۱×۲ ‫۱۳۰×۱۰۲ پیکسل مستقل از تراکم ‫۲۶۹×۵۱ پیکسل مستقل از تراکم
‫۳×۱ ‫۲۰۳×۱۰۲ پیکسل مستقل از تراکم ۴۱۲×۵۱dp
‫۴×۱ ‫۲۷۶×۱۰۲ پیکسل مستقل از تراکم ‫۵۵۴×۵۱dp
‫‎۵×۱ ‫۳۴۹×۱۰۲ پیکسل مستقل از تراکم ۶۹۷×۵۱dp
۵×۲ ‫۳۴۹×۲۲۰ پیکسل مستقل از تراکم 697x117dp
‫۵×۳ ‫۳۴۹×۳۳۷ پیکسل مستقل از تراکم ‫۶۹۷×۱۸۴ پیکسل مستقل از تراکم
۵×۴ ‫۳۴۹×۴۵۵ پیکسل مستقل از تراکم ‫۶۹۷×۲۵۰ پیکسل مستقل از تراکم
… … …
n x m (73n - 16) x (118m - 16) (142n - 15) x (66m - 15)

از اندازه‌های سلول حالت عمودی برای اطلاع از مقادیری که برای مشخصه‌های minWidth، minResizeWidth، و maxResizeWidth ارائه می‌دهید استفاده کنید. به‌طور مشابه، از اندازه‌های سلول حالت افقی برای اطلاع از مقادیری که برای مشخصه‌های minHeight، minResizeHeight، و maxResizeHeight ارائه می‌دهید استفاده کنید.

دلیل این امر این است که عرض سلول معمولاً در حالت عمودی کوچک‌تر از حالت افقی است و به‌طور مشابه، ارتفاع سلول معمولاً در حالت افقی کوچک‌تر از حالت عمودی است.

برای مثال، اگر می‌خواهید عرض ابزاره‌تان تا یک سلول در Google Pixel 4 قابل‌تغییر باشد، باید minResizeWidth را حداکثر روی 56dp تنظیم کنید تا مطمئن شوید مقدار مشخصه minResizeWidth از 57dp کوچک‌تر است—زیرا عرض سلول در حالت عمودی حداقل 57dp است. به‌طور مشابه، اگر می‌خواهید ارتفاع ابزاره‌تان در یک سلول در همان دستگاه قابل‌تغییر باشد، باید minResizeHeight را حداکثر روی ۵۰dp تنظیم کنید تا مطمئن شوید مقدار مشخصه minResizeHeight کمتر از ۵۱dp است—زیرا یک سلول در حالت افقی حداقل ۵۱dp ارتفاع دارد.

هر ابزاره در محدوده اندازه بین مشخصه‌های minResizeWidth/minResizeHeight و maxResizeWidth/maxResizeHeight قابل‌تغییر اندازه است، یعنی باید با هر محدوده اندازه‌ای بین آن‌ها سازگار شود.

برای مثال، برای تنظیم اندازه پیش‌فرض ابزاره در جای‌گذاری، می‌توانید ویژگی‌های زیر را تنظیم کنید:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:targetCellWidth="3"
    android:targetCellHeight="2"
    android:minWidth="180dp"
    android:minHeight="110dp">
</appwidget-provider>

این یعنی اندازه پیش‌فرض ابزاره ۳×۲ سلول است، همان‌طور که با مشخصه‌های targetCellWidth و targetCellHeight مشخص شده است—یا ۱۸۰×۱۱۰ پیکسل مستقل از تراکم، همان‌طور که با minWidth و minHeight برای دستگاه‌های دارای Android نسخه ۱۱ یا پایین‌تر مشخص شده است. در حالت دوم، اندازه سلول‌ها می‌تواند بسته به دستگاه متفاوت باشد.

همچنین، برای تنظیم کردن محدوده‌های اندازه پشتیبانی‌شده ابزاره‌تان، می‌توانید مشخصه‌های زیر را تنظیم کنید:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minResizeWidth="180dp"
    android:minResizeHeight="110dp"
    android:maxResizeWidth="530dp"
    android:maxResizeHeight="450dp">
</appwidget-provider>

همان‌طور که در ویژگی‌های قبلی مشخص شده است، عرض ابزاره از ۱۸۰ پیکسل مستقل از تراکم تا ۵۳۰ پیکسل مستقل از تراکم قابل‌تغییر است و ارتفاع آن از ۱۱۰ پیکسل مستقل از تراکم تا ۴۵۰ پیکسل مستقل از تراکم قابل‌تغییر است. سپس ابزارک را می‌توان از سلول‌های ۳×۲ به ۵×۲ تغییر اندازه داد، به‌شرطی که شرایط زیر وجود داشته باشد:

  • دستگاه دارای شبکه ۵×۴ است.
  • نگاشت بین تعداد سلول‌ها و اندازه دردسترس در dps از جدول نشان‌دهنده تخمین حداقل ابعاد در این صفحه پیروی می‌کند.
  • ابزاره با آن محدوده اندازه سازگار می‌شود.

val smallView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_small)
val mediumView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_medium)
val largeView = RemoteViews(context.packageName, R.layout.widget_weather_forecast_large)

val viewMapping: Map<SizeF, RemoteViews> = mapOf(
    SizeF(180f, 110f) to smallView,
    SizeF(270f, 110f) to mediumView,
    SizeF(270f, 280f) to largeView
)

appWidgetManager.updateAppWidget(appWidgetId, RemoteViews(viewMapping))

فرض کنید ابزاره از چیدمان‌های واکنش‌گرای تعریف‌شده در تکه‌کدهای قبلی استفاده می‌کند. این یعنی چیدمان مشخص‌شده به‌عنوان R.layout.widget_weather_forecast_small از ۱۸۰ دی‌پی (minResizeWidth) × ۱۱۰ دی‌پی (minResizeHeight) تا ۲۶۹×۲۷۹ دی‌پی (نقاط قطع بعدی - ۱) استفاده می‌شود. به‌طور مشابه، R.layout.widget_weather_forecast_medium از ۲۷۰x۱۱۰dp تا ۲۷۰x۲۷۹dp استفاده می‌شود، و R.layout.widget_weather_forecast_large از ۲۷۰x۲۸۰dp تا ۵۳۰dp‏ (maxResizeWidth) x‏ ۴۵۰dp‏ (maxResizeHeight) استفاده می‌شود.

وقتی کاربر اندازه ابزاره را تغییر می‌دهد، ظاهر آن تغییر می‌کند تا با هر اندازه در سلول‌ها مطابقت داشته باشد، همان‌طور که در مثال‌های زیر نشان داده شده است.

نمونه ابزاره آب‌وهوا در کوچک‌ترین اندازه شبکه ۳×۲. میانای کاربری نام مکان (توکیو)، دما (۱۴ درجه)، و نماد نشان‌دهنده هوای نیمه‌ابری را نشان می‌دهد.
شکل ۲. ‫۳×۲ R.layout.widget_weather_forecast_small.

نمونه ابزاره آب‌وهوا در اندازه «متوسط» ۴×۲. تغییر اندازه ابزاره به این روش، براساس کل میانای کاربر از اندازه قبلی ابزاره ساخته می‌شود، و برچسب «غالباً ابری» و پیش‌بینی دما از ساعت ۴ تا ۷ بعدازظهر را اضافه می‌کند.
شکل ۳. ‫۴×۲ R.layout.widget_weather_forecast_medium.

نمونه ابزاره آب‌وهوا در اندازه «متوسط» ۵×۲. تغییر اندازه ابزارک به این روش منجر به همان واسط کاربری اندازه قبلی می‌شود، با این تفاوت که به‌اندازه یک سلول کشیده می‌شود تا فضای افقی بیشتری را اشغال کند.
شکل ۴. ‫۵×۲ R.layout.widget_weather_forecast_medium.

نمونه ابزاره آب‌وهوا در اندازه «بزرگ» ۵×۳. تغییر اندازه ابزاره به این روش براساس همه واسط‌های کاربر از اندازه‌های قبلی ابزاره ساخته می‌شود، و نمایی را در داخل ابزاره اضافه می‌کند که حاوی پیش‌بینی آب‌وهوا در روزهای سه‌شنبه و چهارشنبه است. نمادهایی که نشان‌دهنده هوای آفتابی یا بارانی و دمای بالا و پایین برای هر روز هستند.
شکل ۵. ‫۵×۳ R.layout.widget_weather_forecast_large.

نمونه ابزاره آب‌وهوا در اندازه «بزرگ» ۵×۴. تغییر اندازه ابزاره به این روش، بر همه واسط‌های کاربر از اندازه‌های قبلی ابزاره ساخته می‌شود، و پنجشنبه و جمعه (و نمادهای مربوطه آن‌ها که نشان‌دهنده نوع آب‌وهوا و همچنین دمای بالا و پایین برای هر روز است) را اضافه می‌کند.
شکل ۶. ‫۵×۴ R.layout.widget_weather_forecast_large.