Jetpack WindowManager: mi ez, könyvtár hajlítható eszközökhöz

Mi az a Jetpack WindowManager?

Jetpack WindowManager — egy könyvtár az AndroidX csomagból, amely elvonatkoztatja az ablakokkal és képernyőkonfigurációkkal való munkát Android eszközökön. Megoldja a képernyők fragmentációjának problémáját: a kompakt telefonoktól a hajlítható eszközökig és az asztali móddal rendelkező táblagépekig.

A WindowManager megjelenése előtt a fejlesztők az elavult Display API-t és Resources#getConfiguration-t használták, amelyek nem vették figyelembe a hajlítható eszközöket és a multi-window módokat. A WindowManager egységes API-t biztosít minden forgatókönyvhöz: egyetlen könyvtár lefedi a FoldingFeature, WindowMetrics, WindowSizeClass és ScreenContinuity funkciókat. Ez csökkenti a boilerplate kód mennyiségét és kiküszöböli a hibákat a felület különböző eszközökhöz való igazításakor.

A Google I/O 2024 szerint a Jetpack WindowManager 1.3 stabil verziója támogatja a zsanérérzékelőket, API-t biztosít a nyitási szög meghatározásához és javított integrációt kínál a Jetpack Compose-szal. A könyvtár visszafelé kompatibilis Android 10-ig (API 29) a Support Library-n keresztül, és automatikusan alkalmazkodik az eszköz képességeihez.

FoldingFeature: munka az eszköz hajtásával

FoldingFeature — a Jetpack WindowManager központi osztálya a hajlítható eszközökkel való munkához. Beágyazza az összes információt a hajtás fizikai helyzetéről: állapot (HALF_OPENED, FLAT, TABLE_TOP), tájolás (VERTICAL, HORIZONTAL), a zsanér koordinátái és a nyitási szög fokokban.

A FoldingFeature állapotai

A könyvtár négy hajtási állapotot határoz meg. STATE_FLAT — az eszköz teljesen ki van hajtva, a képernyő lapos. STATE_HALF_OPENED — az eszköz részben össze van hajtva, a képernyő 30 és 160 fok közötti szögben van. STATE_TABLE_TOP — az eszköz laptop helyzetben áll a felületen. STATE_FULLY_OPENED — elavult állapot, amelyet az 1.2-es verzióban a FLAT váltott fel.

A hajtás tájolása és koordinátái

A hajtás lehet függőleges (VERTICAL_FOLD) vagy vízszintes (HORIZONTAL_FOLD). Bounds — egy téglalap, amely leírja a hajtás területét az alkalmazásablak koordinátáiban. A fejlesztő ezeket az adatokat használja a UI elemek elhelyezésére a hajtás felett és alatt, elkerülve a tartalom kritikus területtel való átfedését.

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 és WindowSizeClass

WindowMetrics — API az alkalmazásablak pontos méreteinek lekéréséhez, elérhető a WindowManager 1.0 óta. A Display#getSize-tól eltérően a WindowMetrics figyelembe veszi a multi-window módot, a DeX-et és az ablak szabad formáját. A metrikák visszaadják a currentWindowMetrics (aktuális méret) és a maximumWindowMetrics (maximális lehetséges méret az eszközön) értékeket.

WindowSizeClass — egy osztályozó, amely a WindowManager 1.1-ben jelent meg. Három kategóriába sorolja a képernyőket: Compact (600dp-nél kisebb szélesség — telefon), Medium (600–840dp — táblagép álló tájolásban) és Expanded (840dp felett — táblagép fekvő tájolásban). Ez az osztály leegyszerűsíti az adaptív elrendezést, tucatnyi méretellenőrzést egyetlen osztályozással helyettesítve.

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

ScreenContinuityController és a képernyő folytonossága

ScreenContinuityController — a WindowManager komponense, amely felelős az Activity állapotának megőrzéséért a hajlítható eszköz konfigurációjának változásakor. Amikor a felhasználó kihajtja vagy összehajtja a telefont, a kontroller értesíti az alkalmazást az új testtartásról és mechanizmusokat biztosít a zökkenőmentes átmenethez.

A kontroller a registerContinuityListener segítségével regisztrálja a hallgatókat, amely egy callback-et fogad a FoldingFeature objektummal. Minden testtartás-változáskor a callback az Activity újbóli létrehozása előtt aktiválódik, lehetőséget adva a fejlesztőnek az állapot manuális mentésére. Ha az alkalmazás ViewModel-t használ, nincs szükség további feldolgozásra — az adatok automatikusan mentésre kerülnek.

ScreenContinuity a Jetpack Compose-ban

A Compose alkalmazások a LocalWindowSizeClass és a CompositionLocalProvider segítségével élvezik a ScreenContinuity előnyeit. A komponensek automatikusan újrakomponálódnak a WindowMetrics változásakor. A rememberSaveable megőrzi az állapotot az újrakomponálások között, a Modifier.windowInsets pedig figyelembe veszi a képernyő rendszerterületeit.

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

Integrációs példák Kotlinban

Tekintsünk meg egy teljes Activity példát, amely a Jetpack WindowManager-t használja a felület különböző testtartásokhoz való igazítására. A WindowManagerActivity feliratkozik a FoldingFeature változásaira a Flow API-n keresztül, és az elrendezést az egy- és kétpaneles módok között váltogatja.

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)
    }
}

A példa egy alapvető forgatókönyvet mutat be: az alkalmazás ellenőrzi a WindowMetrics-ot, és kiválasztja az egy- vagy kétpaneles elrendezést. Valós projektekben ajánlott a WindowSizeClass használata a rugalmasabb alkalmazkodáshoz és a FoldingFeature a hajlítható eszközök kezeléséhez. A könyvtár támogatja a seamless transition funkciót is — zökkenőmentes animációt az elrendezések közötti váltáskor.

WindowManager tesztelése és hibakeresése

Android Studio beépített eszközöket tartalmaz a Jetpack WindowManager teszteléséhez. Az emulátor támogatja a hajlítható eszközöket (Pixel Fold, Galaxy Z Fold) a testtartások váltásával a Folding Postures fülön keresztül. Layout Inspector valós időben mutatja az aktuális WindowMetrics-ot és a FoldingFeature határait.

Hibakeresés ADB-n keresztül

Az adb shell dumpsys window displays parancs információkat jelenít meg az összes csatlakoztatott kijelzőről és azok konfigurációjáról. A hajtás szimulálásához használja az adb shell am broadcast -a android.intent.action.SCREEN_ON parancsot további testtartás-paraméterekkel. A WindowManager naplózza az összes FoldingFeature-változást a WindowManager#logState segítségével.

Tipikus hibák

A fő problémák az integráció során — a WindowMetrics frissítések figyelmen kívül hagyása multi-window módban, a bounds helytelen feldolgozása függőleges hajtásnál és a tesztelés hiánya minden testtartásban. Ajánlott minden testtartást külön tesztelni és ellenőrizni a viselkedést a köztük való váltáskor. A WindowSizeClass használata a kézi méretellenőrzések helyett 60%-kal csökkenti a hibák számát.