Wyświetlanie podglądu UI za pomocą podglądów kompozycyjnych

Element typu „composable” jest definiowany przez funkcję i oznaczony znacznikiem @Composable:

@Composable
fun SimpleComposable() {
    Text("Hello World")
}

Prosty element tekstowy zawierający słowa „Hello
World”.

Aby włączyć podgląd tego elementu, utwórz inny element z adnotacją @Composable i @Preview. Ta nowa, opatrzona adnotacjami kompozycja zawiera teraz kompozycję utworzoną początkowo, SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}

Adnotacja @Preview informuje Android Studio, że ten komponent powinien być wyświetlany w widoku projektu tego pliku. W miarę wprowadzania zmian możesz na bieżąco sprawdzać aktualizacje w podglądzie komponentu.

GIF pokazujący aktualizacje w czasie rzeczywistym za pomocą usługi Compose

Aby dostosować sposób renderowania @Preview w Android Studio, możesz ręcznie dodać parametry do kodu. Możesz nawet dodać adnotację @Preview do tej samej funkcji wiele razy, aby wyświetlić podgląd kompozytowego komponentu z różnymi właściwościami.

Jedną z głównych zalet komponentów @Preview jest to, że nie trzeba polegać na emulatorze w Android Studio. Możesz zaoszczędzić pamięć podczas uruchamiania emulatora, aby wprowadzić ostateczne zmiany w wyglądzie i działaniu, oraz wykorzystać możliwości @Preview do łatwego wprowadzania i testowania drobnych zmian w kodzie.

Aby w pełni wykorzystać adnotację @Preview, zdefiniuj ekrany pod kątem stanu, który jest przekazywany jako dane wejściowe, oraz zdarzeń, które są generowane.

Określ @Preview

Android Studio oferuje kilka funkcji umożliwiających rozszerzenie podglądów komponentów. Możesz zmienić ich wygląd, wchodzić z nimi w interakcje lub wdrażać je bezpośrednio na emulatorze lub urządzeniu.

Wymiary

Domyślnie wymiary @Preview są wybierane automatycznie, aby dopasować zawartość. Aby ustawić wymiary ręcznie, dodaj parametry heightDpwidthDp. Te wartości są już interpretowane jako dp, więc nie musisz dodawać do nich .dp:

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}

Żółty kwadrat z napisem „Hello World”

Dynamiczny podgląd koloru

Jeśli w aplikacji masz włączone dynamiczne kolory, użyj atrybutu wallpaper, aby przełączać tapety i obserwować, jak interfejs reaguje na tapety wybrane przez różnych użytkowników. Wybierz jeden z motywów tapety oferowanych przez klasę Wallpaper. Ta funkcja wymaga wersji Compose 1.4.0 lub nowszej.

Korzystanie z urządzeń

W Android Studio Flamingo możesz edytować parametr device adnotacji podglądu, aby definiować konfiguracje kompozytowych na różnych urządzeniach.

Przykładowa funkcja składana

Jeśli parametr device zawiera pusty ciąg znaków (@Preview(device = "")), możesz wywołać autouzupełnianie, naciskając Ctrl + Space. Następnie możesz ustawić wartości poszczególnych parametrów.

Edytowanie przykładowej funkcji

W autouzupełnianiu możesz wybrać dowolną opcję urządzenia z listy, np. @Preview(device = "id:pixel_4"). Możesz też wpisać niestandardowe urządzenie, wybierając spec:width=px,height=px,dpi=int…, aby ustawić poszczególne wartości każdego parametru.

Lista specyfikacji

Aby zastosować, naciśnij Enter, lub anulować za pomocą Esc.

Jeśli ustawisz nieprawidłową wartość, deklaracja zostanie podkreślona na czerwono, a Inspection spróbuje zaproponować poprawkę (Alt + Enter (⌥ + ⏎ w przypadku systemu macOS) > Zastąp przez…). Inspection próbuje zaproponować poprawkę, która najbardziej przypomina Twoje dane wejściowe.

Przykład nieprawidłowej wartości

Język

Aby przetestować różne języki użytkowników, dodaj parametr locale:

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greeting))
}

Prosty element tekstowy zawierający słowo „Bonjour” z francuską flagą

Ustawianie koloru tła

Domyślnie kompozyt wyświetla się z przezroczystym tłem. Aby dodać tło, dodaj parametry showBackgroundbackgroundColor. Pamiętaj, że backgroundColor to kolor ARGB Long, a nie wartość Color:

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}

Zielony prostokąt z napisem „Hello
World”

interfejs systemu

Jeśli chcesz wyświetlić paski stanu i działania w podglądzie, dodaj parametr showSystemUi:

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}

Okno podglądu z aktywizmem, paskiem stanu i paskiem działań

Tryb interfejsu

Parametr uiMode może przyjmować dowolną z konstant Configuration.UI_*i umożliwia zmianę działania podglądu. Możesz na przykład ustawić podgląd w trybie nocnym, aby sprawdzić, jak reaguje motyw.

Interfejs podglądu w widoku tworzenia

LocalInspectionMode

Aby sprawdzić, czy kompozyt jest renderowany w podglądzie (w ramach komponentu, który można sprawdzić), możesz odczytać wartość parametru LocalInspectionMode CompositionLocal. Jeśli kompozycja jest renderowana w podglądzie, LocalInspectionMode.current ma wartość true. Te informacje umożliwiają dostosowanie podglądu. Możesz na przykład wyświetlić w oknie podglądu obraz zastępczy zamiast rzeczywistych danych.

W ten sposób możesz też obejść ograniczenia. Na przykład wyświetlanie przykładowych danych zamiast wywoływania żądania sieciowego.

@Composable
fun GreetingScreen(name: String) {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}

Wejdź w interakcję z urządzeniem @Preview

Android Studio udostępnia funkcje, które umożliwiają interakcję z zdefiniowanymi podglądami. Dzięki tej interakcji możesz lepiej zrozumieć zachowanie podglądów w czasie wykonywania oraz łatwiej poruszać się po interfejsie za pomocą podglądów.

Tryb interaktywny

Tryb interaktywny umożliwia interakcję z podglądem w sposób podobny do tego, jak na urządzeniu z Twoim programem, np. na telefonie lub tablecie. Tryb interaktywny jest odizolowany w sandoboksie (czyli odizolowany od innych podglądów), w którym możesz klikać elementy i wprowadzać dane użytkownika w podglądzie. To szybki sposób na przetestowanie różnych stanów, gestów, a nawet animacji komponentu.

Użytkownik klika przycisk „Interaktywny” w podglądzie.

Film przedstawiający użytkownika w interakcji z podglądem

Nawigacja po kodzie i szkice do składania

Możesz najechać kursorem na podgląd, aby zobaczyć zarysy zawartych w nim komponentów. Kliknięcie zarysu kompozytowego powoduje przejście do definicji w widoku edytora.

Użytkownik najeżdża kursorem na podgląd, przez co Studio wyświetla zarysy komponentów.

Włącz podgląd

Możesz uruchomić określony @Preview w emulatorze lub na fizycznym urządzeniu. Podgląd jest wdrażany w ramach tej samej aplikacji projektu co nowy Activity, więc ma ten sam kontekst i te same uprawnienia. Nie wymaga pisania standardowego kodu z prośbą o uprawnienia, jeśli zostały już one przyznane.

Kliknij ikonę Uruchom podgląd Ikona obok adnotacji @Preview lub u góry podglądu. Android Studio wdroży @Preview na połączonym urządzeniu lub emulatorze.

Użytkownik klika przycisk „Uruchom podgląd” w podglądzie

Film przedstawiający użytkownika, który wyświetla podgląd na urządzeniu

Kopiuj renderowanie @Preview

Każdy wyrenderowany podgląd można skopiować jako obraz, klikając go prawym przyciskiem myszy.

Użytkownik klika podgląd, aby skopiować go jako obraz.

Wiele podglądów tej samej adnotacji @Preview

Możesz prezentować wiele wersji tego samego komponentu @Preview z różnymi specyfikacjami lub różnymi parametrami przekazywanymi do komponentu. Dzięki temu możesz ograniczyć ilość kodu stałego, który w przeciwnym razie musiałbyś napisać.

Szablony z wieloma podglądami

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ wprowadza szablony interfejsu Multipreview API: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark i @PreviewDynamicColors, dzięki czemu za pomocą jednego adnotacji możesz wyświetlić podgląd interfejsu tworzenia wiadomości w najczęstszych scenariuszach.

Podgląd różnych czcionek i rozmiarów ekranu za pomocą szablonów

Tworzenie niestandardowych adnotacji podglądu zbiorczego

Dzięki funkcji podglądu zbiorczego możesz zdefiniować klasę adnotacji, która zawiera wiele adnotacji @Preview z różnymi konfiguracjami. Dodanie tej adnotacji do funkcji składanej spowoduje automatyczne renderowanie wszystkich podglądów naraz. Możesz na przykład użyć tej adnotacji, aby wyświetlić podgląd wielu urządzeń, rozmiarów czcionek lub motywów jednocześnie bez powtarzania tych definicji w przypadku każdego komponentu.

Zacznij od utworzenia własnej klasy adnotacji niestandardowej:

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews

W przypadku elementów do wyświetlania w podglądzie możesz użyć tej adnotacji niestandardowej:

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}

Karta Design (Projekt) w Android Studio, na której widać komponent z małym i dużym fontem

Aby utworzyć pełniejszy zestaw podglądów, możesz połączyć wiele adnotacji z wielokrotnie wyświetlanym podglądem i adnotacji z normalnym podglądem. Połączenie adnotacji w ramach widoku łączonego nie oznacza, że wyświetlane są wszystkie kombinacje. Zamiast tego każda adnotacja w ramach podglądu wielopoziomowego działa niezależnie i renderuje tylko swoje warianty.

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}

Karta projektowania w Android Studio, na której widać komponent we wszystkich konfiguracjach

Dzięki możliwości mieszania i dopasowywania podglądów (zarówno wieloelementowych, jak i zwykłych) możesz dokładniej testować wiele właściwości projektów o większej skali.

@Preview i duże zbiory danych

Często zdarza się, że musisz przekazać duży zbiór danych do podglądu kompozytowego. Aby to zrobić, wystarczy przekazać dane przykładowe do funkcji Composable Preview, dodając parametr za pomocą adnotacji @PreviewParameter.

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}

Aby podać przykładowe dane, utwórz klasę, która implementuje interfejs PreviewParameterProvider i zwraca dane przykładowe jako sekwencję.

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}

W ten sposób dla każdego elementu danych w sekwencji generowany jest jeden podgląd:

Podglądy pokazujące Elise, Franka i Julię – elementy kompozytowane

Możesz używać tej samej klasy dostawcy do wielu podglądów. W razie potrzeby ogranicz liczbę podglądów, ustawiając parametr limit.

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}

Ograniczenia i sprawdzone metody

Android Studio wykonuje kod podglądu bezpośrednio w obszarze podglądu. Nie wymaga uruchamiania emulatora ani urządzenia fizycznego, ponieważ korzysta z przeniesionej części platformy Android o nazwie Layoutlib. Layoutlib to niestandardowa wersja platformy Android, która została zaprojektowana do działania poza urządzeniami z Androidem. Celem biblioteki jest wyświetlanie w Android Studio podglądu układu, który jest bardzo zbliżony do renderowania na urządzeniach.

Ograniczenia podglądu

Ze względu na sposób renderowania podglądów w Android Studio są one lekkie i nie wymagają całego frameworku Androida. Ma to jednak pewne ograniczenia:

  • Brak dostępu do sieci
  • Brak dostępu do plików
  • Niektóre interfejsy API Context mogą być niedostępne

Podglądy i ViewModels

Podglądy są ograniczone, gdy używasz ViewModel w komponowalnym. System podglądów nie jest w stanie utworzyć wszystkich parametrów przekazanych do ViewModel, takich jak repozytoria, przypadki użycia czy menedżerowie. Jeśli ViewModel korzysta z wstrzykiwania zależności (np. Hilt), system podglądów nie może utworzyć całego grafu zależności, aby stworzyć ViewModel.

Gdy próbujesz wyświetlić podgląd kompozytowalności za pomocą ViewModel, Android Studio wyświetla błąd podczas renderowania danej kompozytowalności:

Panel z problemem w Android Studio z komunikatem „Nie udało się utworzyć instancji ViewModel”

Jeśli chcesz wyświetlić podgląd komponentu, który używa komponentu ViewModel, utwórz inny komponent z parametrami z komponentu ViewModel przekazanymi jako argumenty tego komponentu. Dzięki temu nie musisz wyświetlać podglądu komponentu, który korzysta z funkcji ViewModel.

@Composable
fun AuthorColumn(viewModel: AuthorViewModel = viewModel()) {
  AuthorColumn(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorColumn(...) {
    name = NameLabel(name),
    posts = PostsList(posts)
  }
}

Klasa adnotacji @Preview

Aby wyświetlić pełną listę parametrów, które można dostosować podczas dostosowywania podglądu, w Android Studio możesz w każdej chwili kliknąć @Preview, przytrzymując klawisz Ctrl lub ⌘.

annotation class Preview(
    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,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)

Dodatkowe materiały

Aby dowiedzieć się więcej o tym, jak Android Studio ułatwia @Preview korzystanie z programu, oraz uzyskać więcej wskazówek dotyczących narzędzi, przeczytaj blog Compose Tooling.