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

Funkcja kompozycyjna jest definiowana przez funkcję i oznaczona adnotacją @Composable:

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

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

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

Adnotacja @Preview informuje Android Studio, że ten element kompozycyjny powinien być widoczny w widoku projektu tego pliku. Podczas wprowadzania zmian możesz na żywo obserwować aktualizacje podglądu funkcji kompozycyjnej.

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

Jedną z głównych zalet korzystania z komponentów @Preview jest to, że nie trzeba polegać na emulatorze w Android Studio. Możesz zapisać wymagające dużej ilości pamięci uruchomienie emulatora, aby wprowadzić bardziej ostateczne zmiany w wyglądzie i działaniu, oraz wykorzystać możliwości @Preview, aby łatwo wprowadzać i testować niewielkie zmiany w kodzie.

Aby jak najskuteczniej wykorzystać adnotację @Preview, zdefiniuj ekrany pod kątem stanu, który otrzymują jako dane wejściowe, oraz zdarzeń, które generują.

Określ @Preview

Android Studio oferuje kilka funkcji, które rozszerzają podglądy funkcji kompozycyjnych. Możesz zmienić projekt kontenera, wejść z nim w interakcję lub wdrożyć go bezpośrednio w emulatorze lub na urządzeniu.

Wymiary

Domyślnie wymiary @Preview są wybierane automatycznie, aby dopasować je do zawartości. Aby ustawić wymiary ręcznie, dodaj parametry heightDp i widthDp. 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")
    }
}
AndroidStudioComposeSnippets.kt

Podgląd kolorów dynamicznych

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

Używanie z różnymi urządzeniami

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

Gdy parametr urządzenia 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.

Z listy autouzupełniania możesz wybrać dowolne urządzenie, na przykład @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 je zastosować, naciśnij Enter, lub anuluj, naciskając Esc.

Jeśli ustawisz nieprawidłową wartość, deklaracja zostanie podkreślona na czerwono i może być dostępna poprawka (Alt + Enter (⌥ + ⏎ w systemie macOS) > Zastąp…. Inspekcja próbuje podać poprawkę, która jest najbardziej zbliżona do wprowadzonych danych.

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

Ustaw kolor tła

Domyślnie funkcja kompozycyjna jest wyświetlana z przezroczystym tłem. Aby dodać tło, dodaj parametry showBackground i backgroundColor. Pamiętaj, że backgroundColor to Long 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 UI

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

LocalInspectionMode

Możesz odczytać wartość LocalInspectionMode CompositionLocal, aby sprawdzić, czy element kompozycyjny jest renderowany w podglądzie (wewnątrz komponentu możliwego do sprawdzenia). Jeśli kompozycja jest renderowana w podglądzie, LocalInspectionMode.current ma wartość true. Te informacje pozwalają dostosować podgląd. 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!")
    }
}
AndroidStudioComposeSnippets.kt

Interakcja z urządzeniem @Preview

Android Studio udostępnia funkcje, które umożliwiają interakcję ze zdefiniowanymi podglądami. Ta interakcja pomaga zrozumieć działanie podglądów w czasie działania i ułatwia poruszanie się po interfejsie za pomocą podglądów.

Tryb interaktywny

Tryb interaktywny umożliwia interakcję z podglądem w podobny sposób jak na urządzeniu, na którym działa program, np. na telefonie lub tablecie. Tryb interaktywny jest odizolowany w środowisku piaskownicy (czyli odizolowany od innych podglądów), w którym możesz klikać elementy i wpisywać dane użytkownika w podglądzie. To szybki sposób na przetestowanie różnych stanów, gestów, a nawet animacji funkcji kompozycyjnej.

Nawigacja po kodzie i konspekty funkcji kompozycyjnych

Możesz najechać kursorem na podgląd, aby zobaczyć kontury zawartych w nim elementów kompozycyjnych. Kliknięcie elementu kompozycyjnego w konspekcie powoduje przejście do jego definicji w widoku edytora.

Uruchom podgląd

Możesz uruchomić konkretną @Preview na emulatorze lub urządzeniu fizycznym. Wersja testowa jest wdrażana w tej samej aplikacji projektu co nowa Activity, więc ma ten sam kontekst i uprawnienia. Nie wymaga pisania powtarzalnego kodu z prośbą o uprawnienia, jeśli zostały 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 emulatorze.

Kopiuj renderowanie @Preview

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

Wiele podglądów tej samej adnotacji @Preview

Możesz zaprezentować wiele wersji tego samego elementu kompozycyjnego @Preview z różnymi specyfikacjami lub różnymi parametrami przekazywanymi do elementu kompozycyjnego. W ten sposób możesz ograniczyć powtarzalny kod, który w przeciwnym razie trzeba by było napisać.

Szablony podglądu wielu wersji

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

Tworzenie niestandardowych adnotacji do wielu podglądów

Dzięki funkcji multipodglądu możesz zdefiniować klasę adnotacji, która sama ma wiele adnotacji @Preview o różnych konfiguracjach. Dodanie tej adnotacji do funkcji typu „composable” powoduje automatyczne wyrenderowanie wszystkich różnych podglądów jednocześnie. 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 dla każdego elementu kompozycyjnego.

Zacznij od utworzenia własnej niestandardowej klasy adnotacji:

@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 niestandardowej adnotacji w przypadku funkcji kompozycyjnych podglądu:

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

Możesz połączyć kilka adnotacji multipodglądu i zwykłych adnotacji podglądu, aby utworzyć bardziej kompletny zestaw podglądów. Połączenie adnotacji z wieloma podglądami nie oznacza, że wyświetlane są wszystkie kombinacje. Zamiast tego każda adnotacja wielokrotnego podglą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 w ramach podglądu wielokrotnego i zwykłego pozwala na bardziej kompleksowe testowanie wielu właściwości projektów na większą skalę.

@Preview i dużych zbiorów danych

Bardzo często pojawia się potrzeba przekazania dużego zbioru danych do podglądu funkcji kompozycyjnej. Aby to zrobić, wystarczy przekazać dane próbkowane do funkcji podglądu funkcji kompozycyjnej, dodając parametr z adnotacją @PreviewParameter.

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

Aby dostarczyć dane próbkowane, utwórz klasę, która implementuje interfejs PreviewParameterProvider i zwraca dane próbkowane jako sekwencję.

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

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

Możesz używać tej samej klasy dostawcy w przypadku 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)
}
AndroidStudioComposeSnippets.kt

Podglądy korzystające z @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óżnienie. Aby poprawić przejrzystość podglądu, możesz podać niestandardowe wyświetlane nazwy dla każdego podglądu, zastępując getDisplayName() w PreviewParameterProvider. Pomaga to rozróżniać różne odmiany danych lub stany interfejsu. Możesz na przykład oznaczyć 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 funkcji kompozycyjnych. Kliknij prawym przyciskiem myszy funkcję typu „composable” i wybierz AI > Wygeneruj podgląd dla [nazwa funkcji typu „composable”]. Agent analizuje element kompozycyjny, aby wygenerować niezbędny kod boilerplate @Preview z prawidłowymi parametrami, co pomoże Ci szybko sprawdzić, czy interfejs renderuje się zgodnie z oczekiwaniami.

Klasa adnotacji: @Preview

Zawsze możesz nacisnąć Ctrl lub ⌘ i kliknąć adnotację @Preview w Android Studio, aby wyświetlić pełną listę parametrów, które można dostosować podczas personalizowania 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 uruchamiania emulatora ani urządzenia fizycznego, ponieważ wykorzystuje przeniesioną część platformy Androida 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 udostępnienie w Android Studio podglądu układu, który jest bardzo zbliżony do renderowania na urządzeniach.

Ograniczenia wersji testowych

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

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

Podglądy i ViewModels

Podglądy są ograniczone, gdy używasz ViewModel w funkcji kompozycyjnej. System podglądu nie jest w stanie skonstruować wszystkich parametrów przekazywanych do ViewModel, takich jak repozytoria, przypadki użycia, menedżery itp. Jeśli ViewModel uczestniczy we wstrzykiwaniu zależności (np. z Hilt), system podglądu nie może utworzyć całego wykresu zależności, aby utworzyć ViewModel.

Gdy spróbujesz wyświetlić podgląd funkcji kompozycyjnej z ViewModel, Android Studio wyświetli błąd podczas renderowania tej funkcji:

Jeśli chcesz wyświetlić podgląd funkcji kompozycyjnej, która używa ViewModel, utwórz inną funkcję kompozycyjną z parametrami z ViewModel przekazanymi jako argumenty funkcji kompozycyjnej. Dzięki temu nie musisz wyświetlać podglądu elementu kompozycyjnego, 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

• Aby dowiedzieć się więcej o tym, jak Android Studio ułatwia korzystanie z @Preview, i poznać więcej wskazówek dotyczących narzędzi, przeczytaj artykuł na blogu Narzędzia Compose.
• Wskazówki dotyczące starszych widoków znajdziesz w artykule Tworzenie układu z widokami.