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

امتحان کردن روش «نوشتن»

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

نگاه سریع Jetpack →

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

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

از Android 12 (سطح API 31) شروع می‌شود، با انجام کارهای زیر، همان‌طور که در بخش‌های بعدی توضیح داده شده است، می‌توانید ویژگی‌های اندازه دقیق‌تر و چیدمان‌های انعطاف‌پذیرتری ارائه دهید:

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

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

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

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

‫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>
sizing_attributes.xml

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

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

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

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

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)
}
Layouts.kt

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

<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>
sizing_constraints.xml

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

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

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

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

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

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

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

1. «بار اضافه» 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 {
}
Layouts.kt

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

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

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

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

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

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

برای مثال، اگر می‌خواهید پهنای ابزارک شما در Google Pixel 4 تا یک سلول تغییر اندازه دهد، باید minResizeWidth را حداکثر روی ۵۶dp تنظیم کنید تا مطمئن شوید مقدار ویژگی minResizeWidth کمتر از ۵۷dp باشد، زیرا پهنای سلول در حالت عمودی حداقل ۵۷dp است. به‌همین ترتیب، اگر می‌خواهید ارتفاع ابزارک در یک سلول در همان دستگاه قابل‌تغییر اندازه باشد، باید 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>
default_size_attributes.xml

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

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

<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>
supported_size_ranges.xml

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

• دستگاه دارای شبکه ۵×۴ باشد.
• تطابق بین تعداد سلول‌ها و اندازه دردسترس در 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))
Layouts.kt

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

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