Jetpack WindowManager: چیست، کتابخانه برای دستگاه‌های تاشو

Jetpack WindowManager چیست؟

Jetpack WindowManager — کتابخانه‌ای از مجموعه AndroidX که کار با پنجره‌ها و پیکربندی‌های صفحه را در دستگاه‌های اندروید انتزاعی می‌کند. این کتابخانه مشکل تکه‌تکه شدن صفحه‌نمایش‌ها را حل می‌کند: از تلفن‌های جمع‌وجور گرفته تا دستگاه‌های تاشو و تبلت‌های دارای حالت دسکتاپ.

پیش از ظهور WindowManager، توسعه‌دهندگان از Display API قدیمی و Resources#getConfiguration استفاده می‌کردند که دستگاه‌های تاشو و حالت‌های چندپنجره‌ای را در نظر نمی‌گرفتند. WindowManager یک API یکپارچه برای همه سناریوها ارائه می‌دهد: یک کتابخانه FoldingFeature، WindowMetrics، WindowSizeClass و ScreenContinuity را پوشش می‌دهد. این کار میزان کدهای تکراری را کاهش می‌دهد و باگ‌های تطبیق رابط با دستگاه‌های مختلف را برطرف می‌کند.

بر اساس داده‌های Google I/O 2024، نسخه پایدار ۱.۳ Jetpack WindowManager شامل پشتیبانی از حسگرهای لولا، API برای تشخیص زاویه باز شدن و یکپارچه‌سازی بهبودیافته با Jetpack Compose است. این کتابخانه از طریق Support Library تا Android 10 (API 29) سازگاری عقب‌گرد دارد و به طور خودکار با قابلیت‌های دستگاه تطبیق می‌یابد.

FoldingFeature: کار با تا شدن دستگاه

FoldingFeature — کلاس مرکزی Jetpack WindowManager برای کار با دستگاه‌های تاشو. این کلاس تمام اطلاعات مربوط به موقعیت فیزیکی تا شدن را محصور می‌کند: حالت (HALF_OPENED, FLAT, TABLE_TOP)، جهت (VERTICAL, HORIZONTAL)، مختصات لولا و زاویه باز شدن بر حسب درجه.

حالت‌های FoldingFeature

کتابخانه چهار حالت تا شدن را تعریف می‌کند. STATE_FLAT — دستگاه کاملاً باز است، صفحه صاف است. STATE_HALF_OPENED — دستگاه نیمه تا شده است، صفحه در زاویه ۳۰ تا ۱۶۰ درجه قرار دارد. STATE_TABLE_TOP — دستگاه روی سطح در حالت لپ‌تاپ قرار دارد. STATE_FULLY_OPENED — حالت قدیمی که در نسخه ۱.۲ با FLAT جایگزین شده است.

جهت و مختصات تا شدن

تا شدن می‌تواند عمودی (VERTICAL_FOLD) یا افقی (HORIZONTAL_FOLD) باشد. Bounds — مستطیلی که ناحیه تا شدن را در مختصات پنجره برنامه توصیف می‌کند. توسعه‌دهنده از این داده‌ها برای قرار دادن عناصر رابط کاربری در بالا و پایین تا شدن استفاده می‌کند و از همپوشانی محتوا با ناحیه بحرانی جلوگیری می‌کند.

val windowManager = WindowManager(context)
val flow = windowManager.foldingFeature()

flow.collect { feature: FoldingFeature ->
    when (feature.state) {
        FoldingFeature.State.FLAT -> showFullScreen(feature.bounds)
        FoldingFeature.State.HALF_OPENED -> splitContentAcrossFold(feature.bounds)
        FoldingFeature.State.TABLE_TOP -> enableTouchpadMode()
    }
}

WindowMetrics و WindowSizeClass

WindowMetrics — API برای دریافت اندازه‌های دقیق پنجره برنامه که از WindowManager 1.0 در دسترس است. بر خلاف Display#getSize، WindowMetrics حالت چندپنجره‌ای، DeX و شکل آزاد پنجره را در نظر می‌گیرد. متریک‌ها currentWindowMetrics (اندازه فعلی) و maximumWindowMetrics (حداکثر اندازه ممکن در دستگاه) را برمی‌گردانند.

WindowSizeClass — طبقه‌بندی‌کننده‌ای که در WindowManager 1.1 ظاهر شد. صفحه‌ها را به سه دسته تقسیم می‌کند: Compact (عرض کمتر از ۶۰۰dp — تلفن)، Medium (۶۰۰–۸۴۰dp — تبلت در حالت عمودی) و Expanded (بیش از ۸۴۰dp — تبلت در حالت افقی). این کلاس چیدمان تطبیقی را ساده‌تر می‌کند و ده‌ها بررسی اندازه را با یک طبقه‌بندی جایگزین می‌کند.

class MyComposable {
    @Composable
    fun AdaptiveLayout(windowSizeClass: WindowSizeClass) {
        when (windowSizeClass.widthSizeClass) {
            WindowWidthSizeClass.Compact -> CompactScreen()
            WindowWidthSizeClass.Expanded -> ExpandedScreen()
            else -> MediumScreen()
        }
    }
}

ScreenContinuityController و پیوستگی صفحه

ScreenContinuityController — مؤلفه WindowManager که مسئول حفظ وضعیت Activity هنگام تغییر پیکربندی دستگاه تاشو است. وقتی کاربر تلفن را باز یا تا می‌کند، کنترلر برنامه را از حالت جدید مطلع می‌کند و مکانیسم‌هایی برای انتقال روان فراهم می‌کند.

کنترلر شنوندگان را از طریق registerContinuityListener ثبت می‌کند که یک callback با شی FoldingFeature دریافت می‌کند. در هر تغییر حالت، callback قبل از بازآفرینی Activity فعال می‌شود و به توسعه‌دهنده امکان ذخیره دستی وضعیت را می‌دهد. اگر برنامه از ViewModel استفاده کند، پردازش اضافی لازم نیست — داده‌ها به طور خودکار ذخیره می‌شوند.

ScreenContinuity در Jetpack Compose

برنامه‌های Compose از مزایای ScreenContinuity از طریق LocalWindowSizeClass و CompositionLocalProvider بهره‌مند می‌شوند. مؤلفه‌ها هنگام تغییر WindowMetrics به طور خودکار بازترکیب می‌شوند. rememberSaveable وضعیت را بین بازترکیب‌ها حفظ می‌کند و Modifier.windowInsets نواحی سیستمی صفحه را در نظر می‌گیرد.

val controller = WindowManager(context).screenContinuityController
controller.registerContinuityListener { feature ->
    if (feature.state == FoldingFeature.State.FLAT) {
        logContinuityEvent("Device unfolded")
    }
}

نمونه‌های یکپارچه‌سازی در Kotlin

بیایید یک مثال کامل از Activity را بررسی کنیم که از Jetpack WindowManager برای تطبیق رابط با حالت‌های مختلف دستگاه تاشو استفاده می‌کند. WindowManagerActivity از طریق Flow API تغییرات FoldingFeature را دنبال می‌کند و چیدمان را بین حالت‌های یک و دو پنل تغییر می‌دهد.

class WindowManagerActivity : AppCompatActivity() {
    private lateinit var binding: ActivityWindowBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityWindowBinding.inflate(layoutInflater)
        setContentView(binding.root)

        val windowManager = WindowManager(this)
        val metrics = windowManager.currentWindowMetrics

        if (metrics.bounds.width() > dpToPx(600)) {
            showDualPaneLayout()
        } else {
            showSinglePaneLayout()
        }
    }

    private fun showDualPaneLayout() {
        binding.content.layoutManager = GridLayoutManager(this, 2)
    }

    private fun showSinglePaneLayout() {
        binding.content.layoutManager = LinearLayoutManager(this)
    }
}

این مثال یک سناریوی پایه را نشان می‌دهد: برنامه WindowMetrics را بررسی می‌کند و چیدمان یک یا دو پنل را انتخاب می‌کند. در پروژه‌های واقعی، توصیه می‌شود از WindowSizeClass برای تطبیق انعطاف‌پذیرتر و از FoldingFeature برای مدیریت دستگاه‌های تاشو استفاده کنید. این کتابخانه همچنین از seamless transition — انیمیشن روان هنگام جابجایی بین چیدمان‌ها پشتیبانی می‌کند.

تست و اشکال‌زدایی WindowManager

Android Studio شامل ابزارهای داخلی برای تست Jetpack WindowManager است. شبیه‌ساز از دستگاه‌های تاشو (Pixel Fold, Galaxy Z Fold) با قابلیت تغییر حالت از طریق برگه Folding Postures پشتیبانی می‌کند. Layout Inspector WindowMetrics فعلی و مرزهای FoldingFeature را در زمان واقعی نشان می‌دهد.

اشکال‌زدایی از طریق ADB

دستور adb shell dumpsys window displays اطلاعات مربوط به همه نمایشگرهای متصل و پیکربندی‌های آنها را نمایش می‌دهد. برای شبیه‌سازی تا شدن از adb shell am broadcast -a android.intent.action.SCREEN_ON با پارامترهای اضافی حالت استفاده کنید. WindowManager تمام تغییرات FoldingFeature را از طریق WindowManager#logState ثبت می‌کند.

خطاهای رایج

مشکلات اصلی هنگام یکپارچه‌سازی — نادیده گرفتن به‌روزرسانی‌های WindowMetrics در حالت چندپنجره‌ای، پردازش نادرست bounds در تا شدن عمودی و عدم تست در همه حالت‌ها. توصیه می‌شود هر حالت را جداگانه تست کنید و رفتار هنگام جابجایی بین آنها را بررسی کنید. استفاده از WindowSizeClass به جای بررسی‌های دستی اندازه، تعداد باگ‌ها را تا ۶۰٪ کاهش می‌دهد.