28. Feb 2023Android

Jetpack Compose Basics – Preview a jeho parametry

Každý vývojář v systému Android, který píše uživatelské rozhraní, potřebuje v určitém okamžiku vidět výsledky svého úsilí, ať už jde o kontrolu, ladění nebo uhlazení kódu. Jednou z možností, které jsou k dispozici v Jetpack Compose, je použití sestavy preview integrované do Android Studio (dalšími možnostmi může být zabudování aplikace do zařízení, layout inspector atd.).

Peter ŠulyAndroid developer

Pokud chcete použít preview, jednoduše vytvořte funkci composable funkci s anotací @Preview. Pokud je composable funkce opatřena anotací @Preview, měl by se preview vykreslit v designovém okně Android Studio (integrace v AS zatím není dokonalá, ale vývojáři ji neustále vylepšují. Někdy je k vykreslení preview potřeba víc buildů).

Anotace preview poskytuje řadu způsobů, jak preview nakonfigurovat a tím zvýšit produktivitu (např. produktivitu lidí, kteří se k projektu připojí později). Níže je uvedený minimální příklad @Preview bez použití některého z příslušných parametrů. Funkci je možné napsat ručně nebo pomocí šablony prev live template.

@Preview
@Composable
fun ExamplePreview() {
  Button(
    modifier = Modifier.fillMaxWidth(),
    onClick = {},
    content = { Text(text = "Button") })
}

Parametry preview

Anotace preview nacházející se v balíčku ui.tooling má mnoho parametrů, které určují, jak se bude composable renderovat.

val name: String = "",
val group: String = "",
@IntRange(from = 1) val apiLevel: Int = -1,
val widthDp: Int = -1,
val heightDp: Int = -1,
val locale: String = "",
@FloatRange(from = 0.01) val fontScale: Float = 1f,
val showSystemUi: Boolean = false,
val showBackground: Boolean = false,
val backgroundColor: Long = 0,
@UiMode val uiMode: Int = 0,
@Device val device: String = Devices.DEFAULT

name

Každé preview je možné rozpoznat podle názvu, který je standardně názvem funkce preview. Ve výše uvedeném příkladu je název ukázky ExamplePreview.

@Preview(name = "Some preview name")
@Composable
fun ExamplePreview() {
  ...
}

group

Podobná preview lze v zájmu lepší čitelnosti seskupit. Může to být opravdu užitečné, pokud existuje množství composable previews.

@Preview(group = "Buttons")
@Composable
fun ButtonEnabledPreview() {...}

@Preview(group = "Buttons")
@Composable
fun ButtonDisabledPreview() {...}

@Preview(group = "Texts")
@Composable
fun TextBigPreview() {...}

@Preview(group = "Texts")
@Composable
fun TextSmallPreview() {...}

apiLevel

Úroveň API použitá při renderování preview.

widthDP a heightDp

Standardně má okno preview šířku a výšku použité composable položky (chování je podobné jako u wrap_content v layoutech xml). To je možné změnit pomocí widthDp a heightDp. Maximální hodnota pro šířku i výšku je 2000. Nastavením vyššího čísla se šířka preview nezvětší.

@Preview(widthDp = 100, heightDp = 100)
@Composable
fun ExamplePreview() {...}

locale

Určuje, které místní nastavení se má použít k vykreslení preview (parametr akceptuje tento formát místního nastavení). Pokud se nepoužije, použijí se předvolené zdroje. Tento parametr může být užitečný, pokud je vaše aplikace vícejazyčná.

V níže uvedeném příkladu je třeba se zaměřit na několik věcí. Pro jednu sestavu composable lze použít víc anotací preview, což vede k vícenásobným previews. Druhé preview využívá francouzské zdroje.

@Preview
@Preview(locale = "fr")
@Composable
fun ButtonPreview() {
  Button(
    ...
    content = { Text(text = stringResource(id = R.string.day_monday)) })
}

fontScale

Lze použít k testování škálovatelnosti měřítka písma.

showSystemUi

Boolean, který určuje, jestli se má v preview zobrazit status bar a navigation bar.

showBackground a backgroundColor

Pokud má showBackground boolean hodnotu true, použije se pro náhled předvolená barva pozadí. Tuto barvu jde přizpůsobit parametrem backgroundColor. Měla by se použít barva ARGB int.

@Preview(showBackground = true, backgroundColor = 0xff0000)
@Composable
fun ExamplePreview() {...}

uiMode

Konfigurace režimu uživatelského rozhraní se používá, když potřebujete zobrazit preview určitých podmínek uživatelského rozhraní. To je nejužitečnější, pokud chcete composable vidět ve světlém nebo v tmavém režimu (nebo v obou).

@Preview(uiMode = UI_MODE_NIGHT_NO)
@Preview(uiMode = UI_MODE_NIGHT_YES)
@Composable
fun ExamplePreview() {...}

device

Zařízení, které se má použít v preview. Třída Devices obsahuje seznam použitelných konstant (většinou zařízení Nexus a Pixel).

@Preview(device = Devices.PIXEL_3A)
@Composable
fun ExamplePreview() {...}

Interactive Mode

Interaktivní režim lze zapnout tlačítkem nad preview. Umožňuje vám pracovat s preview stejně jako na zařízení. Jedná se o jednoduchý a rychlý způsob testování prvků s více stavy, jako je zaškrtnutí políčka nebo použití přepínače. Interaktivní režim běží přímo uvnitř AS, což vede k omezením, jako je zakázaný přístup k síti nebo zakázaný přístup k souborům.