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.

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.

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.

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

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.

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:

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.