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

Komponent composable jest definiowany przez funkcję i opatrywany adnotacją @Composable:

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

Aby włączyć podgląd tego komponentu composable, utwórz inny komponent composable opatrzony adnotacjami @Composable i @Preview. Ten nowy komponent composable z adnotacjami zawiera teraz komponent composable utworzony na początku, czyli SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

Adnotacja @Preview informuje Android Studio, że ten komponent composable ma być wyświetlany w widoku projektu tego pliku. Podczas edycji możesz na bieżąco obserwować zmiany w podglądzie komponentu composable.

Uwaga: Android Wear używa innych adnotacji do podglądów (@WearPreviewDevices i @WearPreviewFontScales). Więcej informacji znajdziesz w artykule Testowanie kombinacji rozmiarów ekranu i czcionki za pomocą podglądów.

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

Uwaga: jeśli masz kilka podglądów funkcji kompozycyjnych, ale chcesz skupić się na jednym podglądzie naraz, zalecamy użycie trybu pełnej koncentracji, aby zaoszczędzić zasoby renderowania. Gdy musisz zobaczyć wszystkie warianty interfejsu naraz, przełącz się na tryb siatki lub listy. Możesz przełączać się między trybami za pomocą menu u góry karty Projekt.

Jedną z głównych zalet korzystania z komponentów composable z adnotacją @Preview jest to, że nie musisz polegać na emulatorze w Android Studio. Możesz zaoszczędzić pamięć, która jest potrzebna do uruchomienia emulatora, na potrzeby zmian w ostatecznym wyglądzie i działaniu, a także na łatwe wprowadzanie i testowanie drobnych zmian w kodzie za pomocą adnotacji @Preview.

Aby jak najefektywniej korzystać z adnotacji @Preview, zdefiniuj ekrany w kategoriach stanu, który otrzymują jako dane wejściowe, oraz zdarzeń, które generują.

Definiowanie adnotacji @Preview

Android Studio oferuje kilka funkcji rozszerzających podglądy komponentów composable. Możesz zmieniać projekt kontenera, wchodzić w interakcje z komponentami composable lub wdrażać je bezpośrednio w emulatorze lub na urządzeniu.

Wymiary

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

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

Podgląd kolorów dynamicznych

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

Używanie na różnych urządzeniach

W Android Studio Flamingo możesz edytować parametr device adnotacji Preview, aby zdefiniować konfiguracje komponentów composable na różnych urządzeniach.

Gdy parametr device ma pusty ciąg znaków (@Preview(device = "")), możesz wywołać autouzupełnianie, naciskając Ctrl + Space. Następnie możesz ustawić wartości każdego parametru.

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.

Aby zastosować zmiany, naciśnij Enter, a aby anulować, naciśnij Esc.

Jeśli ustawisz nieprawidłową wartość, deklaracja zostanie podkreślona na czerwono i może być dostępna poprawka (Alt + Enter (⌥ + ⏎ w macOS) > Zastąp przez…). Kontrola próbuje znaleźć poprawkę, która najbardziej przypomina Twoje dane wejściowe.

Język

Aby przetestować różne ustawienia regionalne użytkowników, dodaj parametr locale:

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

Ustaw kolor tła

Domyślnie komponent composable jest wyświetlany z przezroczystym tłem. Aby dodać tło, dodaj parametry showBackground i backgroundColor. Pamiętaj, że backgroundColor to wartość Long w formacie ARGB, a nie wartość Color:

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

Interfejs systemu

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

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

Tryb interfejsu

Parametr uiMode może przyjmować dowolną z Configuration.UI_* stałych i umożliwia odpowiednie zmienianie zachowania podglądu. Możesz na przykład ustawić podgląd w trybie nocnym, aby zobaczyć, jak reaguje motyw.

LocalInspectionMode

Możesz odczytać wartość z LocalInspectionMode CompositionLocal, aby sprawdzić, czy funkcja kompozycyjna jest renderowana w podglądzie (wewnątrz komponentu, który można sprawdzić). Jeśli kompozycja jest renderowana w podglądzie, wartość LocalInspectionMode.current to true. Te informacje pozwalają dostosować podgląd. Możesz na przykład wyświetlać w oknie podglądu obraz zastępczy zamiast rzeczywistych danych.

W ten sposób możesz też obejść ograniczenia. Możesz na przykład wyświetlać przykładowe dane zamiast wywoływać żądanie sieciowe.

@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!")
    }
}
AndroidStudioComposeSnippets.kt

Interakcja z adnotacją @Preview

Android Studio udostępnia funkcje, które pozwalają wchodzić w interakcje ze zdefiniowanymi podglądami. Ta interakcja pomaga zrozumieć zachowanie podglądów w czasie działania i umożliwia lepsze poruszanie się po interfejsie za pomocą podglądów.

Tryb interaktywny

Tryb interaktywny umożliwia interakcję z podglądem podobnie jak na urządzeniu z uruchomionym programem, np. na telefonie lub tablecie. Tryb interaktywny jest izolowany w środowisku piaskownicy (czyli odizolowany od innych podglądów), w którym możesz klikać elementy i wprowadzać dane wejściowe użytkownika w podglądzie. To szybki sposób na testowanie różnych stanów, gestów, a nawet animacji komponentu composable.

Nawigacja po kodzie i kontury komponentów composable

Możesz najechać kursorem na podgląd, aby zobaczyć kontury komponentów composable, które się w nim znajdują. Kliknięcie konturu komponentu composable powoduje przejście widoku edytora do jego definicji.

Uruchom podgląd

Możesz uruchomić konkretną adnotację @Preview w emulatorze lub na urządzeniu fizycznym. Podgląd jest wdrażany w tej samej aplikacji projektu jako nowa Activity, więc ma ten sam kontekst i te same uprawnienia. Nie musisz pisać powtarzalnego kodu, który prosi o uprawnienia, jeśli zostały one już przyznane.

Uwaga: argumenty zastosowane w adnotacji @Preview (np. widthDp, locale itp.) nie są stosowane do uruchomionego i wdrożonego podglądu.

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

Kopiowanie renderowania adnotacji @Preview

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

Wiele podglądów tej samej adnotacji @Preview

Możesz prezentować wiele wersji tego samego komponentu composable z adnotacją @Preview z różnymi specyfikacjami lub różnymi parametrami przekazywanymi do komponentu composable. W ten sposób możesz ograniczyć ilość powtarzalnego kodu, który musisz napisać.

Szablony multipodglądu

Wersja 1.6.0-alpha01+ biblioteki androidx.compose.ui:ui-tooling-preview wprowadza szablony interfejsu API multipodglądu: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark i @PreviewDynamicColors. Dzięki temu za pomocą jednej adnotacji możesz wyświetlać podgląd interfejsu Compose w typowych scenariuszach.

Tworzenie niestandardowych adnotacji multipodglądu

Dzięki multipodglądowi możesz zdefiniować klasę adnotacji, która sama ma wiele adnotacji @Preview z różnymi konfiguracjami. Dodanie tej adnotacji do funkcji typu „composable” automatycznie renderuje wszystkie różne podglądy naraz. Możesz na przykład użyć tej adnotacji, aby wyświetlić podgląd na wielu urządzeniach, z różnymi rozmiarami czcionki lub motywami jednocześnie, bez powtarzania tych definicji dla każdego komponentu composable.

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
AndroidStudioComposeSnippets.kt

Możesz użyć tej adnotacji niestandardowej w przypadku komponentów composable podglądu:

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

Możesz łączyć ze sobą wiele adnotacji multipodglądu i zwykłych adnotacji podglądu, aby utworzyć bardziej kompletny zestaw podglądów. Łączenie adnotacji multipodglądu nie oznacza, że będą wyświetlane wszystkie różne kombinacje. Każda adnotacja multipodglądu działa niezależnie i renderuje tylko własne warianty.

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

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

Możliwość łączenia i dopasowywania multipodglądu – i zwykłego podglądu! – pozwala dokładniej testować wiele właściwości projektów na większą skalę.

@Preview i duże zbiory danych

Bardzo często trzeba przekazać duży zbiór danych do podglądu komponentu composable. Aby to zrobić, po prostu przekaż przykładowe dane do funkcji podglądu komponentu composable, dodając parametr z @PreviewParameteradnotacją.

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

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

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

Spowoduje to renderowanie 1 podglądu na element danych w sekwencji:

Tej samej klasy dostawcy możesz używać w przypadku wielu podglądów. W razie potrzeby możesz ograniczyć liczbę podglądów, ustawiając parametr limit.

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

Podglądy korzystające z adnotacji @PreviewParameter są domyślnie nazywane za pomocą indeksu parametru i nazwy właściwości (użytkownik 0, użytkownik 1, użytkownik 2 itd.), co może utrudniać ich rozróżnianie. Aby zwiększyć przejrzystość podglądu, możesz podać niestandardowe nazwy wyświetlane dla każdego podglądu, zastępując getDisplayName() w PreviewParameterProvider. Ułatwia to rozróżnianie różnych wariantów danych lub stanów interfejsu. Możesz na przykład oznaczać podglądy na podstawie danych wejściowych:

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}
AndroidStudioComposeSnippets.kt

Wskazówka: aby zwiększyć wydajność, użyj List w PreviewParameterProvider jako kopii zapasowej Sequence. Zapewnia to wydajny dostęp oparty na indeksach w getDisplayName() i pozwala uniknąć powolnego wyszukiwania w dużych sekwencjach.

Generowanie podglądu wspomagane przez AI

Agent AI w Android Studio może automatycznie generować podglądy Compose dla Twoich komponentów composable. Kliknij prawym przyciskiem myszy funkcję typu „composable” i wybierz AI > Wygeneruj podgląd dla [nazwa funkcji typu „composable”]. Agent analizuje Twój komponent composable, aby wygenerować niezbędny kod standardowy @Preview z prawidłowymi parametrami, co pomaga szybko sprawdzić, czy interfejs jest renderowany zgodnie z oczekiwaniami.

Generowanie podglądu Compose za pomocą AI.

Klasa adnotacji @Preview

W Android Studio zawsze możesz kliknąć adnotację @Preview z wciśniętym klawiszem Ctrl lub ⌘, aby wyświetlić pełną listę parametrów, które można dostosować podczas konfigurowania podglądu.

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,
)
AndroidStudioComposeSnippets.kt

Ograniczenia i sprawdzone metody

Android Studio wykonuje kod podglądu bezpośrednio w obszarze podglądu. Nie wymaga to 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 jest przeznaczona do działania poza urządzeniami z Androidem. Celem biblioteki jest zapewnienie podglądu układu w Android Studio, który jest bardzo zbliżony do renderowania na urządzeniach.

Ograniczenia podglądów

Ze względu na sposób renderowania podglądów w Android Studio są one lekkie i nie wymagają do renderowania całej platformy Android. Ma to jednak następujące ograniczenia:

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

Podglądy i ViewModels

Podglądy są ograniczone, gdy w komponencie composable używasz ViewModel. System podglądów nie jest w stanie skonstruować wszystkich parametrów przekazywanych do ViewModel, takich jak repozytoria, przypadki użycia, menedżery itp. Jeśli ViewModel uczestniczy w iniekcji zależności (np. za pomocą Hilt), system podglądów nie może też zbudować całego grafu zależności, aby skonstruować ViewModel.

Gdy próbujesz wyświetlić podgląd komponentu composable z ViewModel, Android Studio wyświetla błąd podczas renderowania danego komponentu composable:

Ostrzeżenie: nie należy przekazywać instancji ViewModel do innych funkcji composable. W takim przypadku łączysz komponenty composable z typem ViewModel, co sprawia, że są one mniej użyteczne, trudniejsze do testowania i nie można ich wyświetlać w podglądzie.

Jeśli chcesz wyświetlić podgląd komponentu composable, który używa ViewModel, utwórz inny komponent composable z parametrami z ViewModel przekazanymi jako argumenty komponentu composable. W ten sposób nie musisz wyświetlać podglądu komponentu composable, który używa ViewModel.

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

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@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]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

Dodatkowe materiały

• Więcej informacji o tym, jak Android Studio ułatwia korzystanie z @Preview, oraz dodatkowe wskazówki dotyczące narzędzi znajdziesz na blogu Compose Tooling.
• Wskazówki dotyczące starszych widoków znajdziesz w artykule Tworzenie układu za pomocą widoków.