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 kolejną funkcję kompozycyjną z adnotacjami z użytkownikami @Composable i @Preview. Ten nowy element kompozycyjny z adnotacjami zawiera teraz kompozycję utworzoną przez Ciebie początkowo (SimpleComposable):

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

Adnotacja @Preview informuje Android Studio, że Funkcja kompozycyjna powinna być widoczna w widoku projektu tego pliku. W miarę wprowadzania zmian możesz na bieżąco sprawdzać aktualizacje podglądu komponentu.

Możesz ręcznie dodać parametry w kodzie, aby dostosować sposób, w jaki Android Studio renderuje element @Preview. Możesz nawet dodać adnotację @Preview do tego samego aby wyświetlić podgląd funkcji kompozycyjnej 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 skorzystać z możliwości @Preview, aby łatwo wprowadzać i testować drobne zmiany 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 owinąć zawartość. 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

Dynamiczny podgląd koloru

Po włączeniu dynamicznego kolor w aplikacji, użyj atrybutu wallpaper, aby przełączać tapety i sprawdzić, jak zareaguje Twój interfejs dla różnych użytkowników wybraną tapetę. Wybieraj spośród różnych motywów tapet oferowanych przez Wallpaper zajęcia. Ta funkcja wymaga Utwórz w wersji 1.4.0 lub nowszej.

Korzystanie z urządzeń

W Android Studio Flamingo możesz edytować parametr device podglądu pozwalająca zdefiniować konfiguracje funkcji kompozycyjnych na różnych urządzeniach.

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 każdego parametru.

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

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

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

Język

Aby przetestować różne ustawienia językowe 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

Funkcja kompozycyjna jest domyślnie wyświetlana na przezroczystym tle. Aby dodać tło, dodaj parametry showBackground i backgroundColor. Zachowaj w pamiętaj, że backgroundColor to Long ARGB, a nie Color wartość:

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

interfejs systemu

Jeśli chcesz wyświetlić paski stanu i 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 konstant Configuration.UI_*i umożliwia zmianę działania podglądu. Dla: na przykład możesz włączyć tryb nocny, żeby sprawdzić, jak zareaguje motyw.

LocalInspectionMode

Treść możesz czytać tutaj: LocalInspectionMode CompositionLocal, by sprawdzić, czy funkcja kompozycyjna jest renderowana w podglądzie (wewnątrz komponent możliwy do sprawdzenia). Jeśli kompozycja jest renderowana w podglądzie, LocalInspectionMode.current jest obliczane jako 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!")
    }
}
AndroidStudioComposeSnippets.kt

Wejdź w interakcję z urządzeniem @Preview

Android Studio udostępnia funkcje, które umożliwiają interakcję z podgląd. Ta interakcja pomaga zrozumieć podglądy działanie w czasie działania i pozwala na lepszą nawigację po interfejsie dzięki podglądom.

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 izolowana w środowisku piaskownicy (co oznacza, że jest odizolowana od innych podglądów), gdzie możesz klikać elementy i wprowadzać dane wejściowe użytkownika na podglądzie. To szybki sposób na przetestowanie różnych stanów, gestów, a nawet animacji komponentu.

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.

Uruchom podgląd

Możesz uruchomić określony @Preview w emulatorze lub na fizycznym urządzeniu. Podgląd jest wdrożony 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  obok adnotacji @Preview lub u góry podglądu. Android Studio wdroży @Preview na połączonym urządzeniu lub emulatorze.

Skopiuj @Preview renderowanie

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 dostępnego za pomocą różne specyfikacje lub różne parametry przekazywane do elementu kompozycyjnego. Dzięki temu możesz ograniczyć ilość kodu stałego, który w przeciwnym razie musiałbyś napisać.

Szablony wielu podglądów

androidx.compose.ui:ui-tooling-preview W wersji 1.6.0-alfa01 lub nowszej wprowadzamy multipodgląd Szablony API: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, i @PreviewDynamicColors, dzięki czemu jedna adnotacja w typowych scenariuszach wyświetlania podglądu interfejsu tworzenia wiadomości.

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. Za pomocą tej adnotacji możesz na przykład wyświetlić podgląd wielu urządzeń, rozmiarów czy motywów jednocześnie, nie powtarzając tych definicji funkcję kompozycyjną.

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

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

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

Możesz połączyć wiele adnotacji podglądu na wielu platformach i normalne adnotacje podglądu aby stworzyć pełniejszy zestaw podglądów. 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)) } }
}
AndroidStudioComposeSnippets.kt

Dzięki możliwości mieszania i dopasowywania elementów w podglądzie kilku rozmiarów (i w podglądzie normalnym) możesz dokładniej testować wiele właściwości projektów o większej skali.

@Preview i duże zbiory danych

Często pojawia się potrzeba przekazania dużego zbioru danych do podglądu kompozytowego. Aby to zrobić, po prostu prześlij przykładowe dane do funkcji Composable Preview, dodając parametr za pomocą adnotacji @PreviewParameter.

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

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

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

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

Ograniczenia i sprawdzone metody

Android Studio wykonuje kod podglądu bezpośrednio w obszarze podglądu. Nie wymaga użycia emulatora lub urządzenia fizycznego, ponieważ wykorzystuje stanowią część platformy Androida o nazwie Layoutlib. Layoutlib jest niestandardowym platformy Android, która działa poza urządzeniami z Androidem. Celem biblioteki jest udostępnienie podglądu układu w Android Studio, który jest bardzo zbliżona do renderowania na urządzeniach.

Ograniczenia podglądu

Ze względu na sposób renderowania podglądów w Android Studio są one są proste i nie wymagają całej platformy Androida do ich renderowania. Wiąże się to jednak z tymi ograniczeniami:

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

Podglądy i ViewModels

Podglądy są ograniczone, jeśli używasz ViewModel w kompozycyjne. System podglądów nie jest w stanie utworzyć wszystkich parametrów przekazanych do ViewModel, takich jak repozytoria, przypadki użycia czy menedżerowie. Poza tym, jeśli ViewModel uczestniczy we wstrzykiwaniu zależności (na przykład tak jak w przypadku Hilt), system podglądu nie może utworzyć całej zależności aby utworzyć ViewModel.

Gdy spróbujesz wyświetlić podgląd funkcji kompozycyjnej w ViewModel, Android Studio wyświetli podczas renderowania konkretnego elementu kompozycyjnego:

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 będzie trzeba wyświetlać podglądu funkcji kompozycyjnej, w której 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

Zawsze możesz użyć skrótu „Ctrl” lub „⌘ + kliknij” adnotacja @Preview na Androidzie Studio, gdzie znajduje się pełna lista parametrów, które można dostosować przy dostosowywaniu podgląd.

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

Dodatkowe materiały

Aby dowiedzieć się więcej o tym, jak Android Studio promuje łatwość obsługi @Preview, i dowiedz się więcej więcej wskazówek dotyczących narzędzi można znaleźć na blogu Tworzenie wiadomości Narzędzia.