Funkcja kompozycyjna jest definiowana przez funkcję i oznaczona adnotacją @Composable:
@Composable
fun SimpleComposable() {
Text("Hello World")
}
Aby włączyć podgląd tego elementu kompozycyjnego, utwórz inny kompozycję z adnotacjami @Composable i @Preview. Ten nowy element kompozycyjny z adnotacjami zawiera teraz utworzony przez Ciebie na początek kompozycję SimpleComposable:
@Preview
@Composable
fun SimpleComposablePreview() {
SimpleComposable()
}
Adnotacja @Preview informuje Android Studio, że funkcja kompozycyjna powinna być widoczna w widoku projektu tego pliku. Podczas wprowadzania zmian możesz widzieć bieżące zmiany w podglądzie kompozycyjnym.
Możesz dodać parametry ręcznie w kodzie, aby dostosować sposób renderowania elementu @Preview w Android Studio. Możesz nawet kilka razy 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 kompozycyjnych @Preview jest unikanie polegania na emulatorze w Android Studio. Możesz zapisać pochłaniające pamięć uruchomienie emulatora, aby uzyskać bardziej ostateczny wygląd i działanie. Dodatkowo możesz z łatwością wprowadzać i testować niewielkie zmiany w kodzie @Preview.
Aby efektywniej korzystać z adnotacji @Preview, zdefiniuj ekrany pod kątem stanu otrzymywanego jako danych wejściowych i wyjściowych zdarzeń.
Określ swoje urządzenie @Preview
Android Studio oferuje niektóre funkcje rozszerzające podglądy kompozycyjne. Możesz zmienić konstrukcję kontenera, wchodzić z nim w interakcję albo wdrożyć je bezpośrednio w emulatorze lub urządzeniu.
Wymiary
Domyślnie wymiary @Preview są wybierane automatycznie do zawijania 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ć do nich .dp:
@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
Box(Modifier.background(Color.Yellow)) {
Text("Hello World")
}
}
Dynamiczny podgląd kolorów
Jeśli w aplikacji masz włączony dynamiczny kolor, użyj atrybutu wallpaper, aby przełączać tapety i sprawdzać, jak Twój interfejs reaguje na wybrane przez użytkowników tapety. Wybieraj spośród różnych motywów tapet dostępnych w klasie Wallpaper. Ta funkcja wymaga tworzenia wiadomości w wersji 1.4.0 lub nowszej.
Używaj z różnymi urządzeniami
W Android Studio Flamingo możesz edytować parametr device w adnotacji do wersji testowej, by zdefiniować konfiguracje funkcji kompozycyjnych na różnych urządzeniach.
Gdy parametr urządzenia 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.
W autouzupełnianiu możesz wybrać z listy dowolną opcję urządzenia, na przykład @Preview(device = "id:pixel_4"). Możesz też podać urządzenie niestandardowe. Aby to zrobić, kliknij spec:width=px,height=px,dpi=int…, aby ustawić indywidualne wartości każdego parametru.
Aby się zgłosić, naciśnij Enter lub anuluj, używając Esc.
Jeśli ustawisz nieprawidłową wartość, deklaracja będzie podkreślona na czerwono i może być dostępna poprawka (Alt + Enter (⌥ +
w przypadku systemu macOS) > Zamień na...). Podczas inspekcji spróbuje znaleźć poprawkę najbardziej pasującą do Twoich danych wejściowych.
Język
Aby przetestować różne ustawienia języka użytkownika, dodaj parametr locale:
@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
Text(text = stringResource(R.string.greeting))
}
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 wartość Long ARGB, a nie Color:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
Text("Hello World")
}
interfejs systemu
Jeśli chcesz wyświetlać paski stanu i działań na podglądzie, dodaj parametr showSystemUi:
@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
Text("Hello World")
}
Tryb UI
Parametr uiMode może przyjmować dowolną ze stałych Configuration.UI_* i umożliwia odpowiednie dostosowanie działania podglądu. Możesz na przykład ustawić podgląd na Tryb nocny, aby sprawdzić działanie motywu.
LocalInspectionMode
Możesz sprawdzić w LocalInspectionMode
CompositionLocal, czy funkcja kompozycyjna jest renderowana na podglądzie (we nieodpowiednim komponencie). Jeśli kompozycja zostanie wyrenderowana na podglądzie, LocalInspectionMode.current przyjmuje wartość true. Informacje te umożliwiają dostosowanie podglądu. Możesz np. wyświetlać w oknie podglądu obraz zastępczy, zamiast wyświetlać rzeczywiste dane.
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ę ze zdefiniowanymi podglądami. Ta interakcja pomoże Ci zrozumieć zachowanie podglądów w czasie działania i ułatwi Ci poruszanie się po interfejsie.
Tryb interaktywny
Tryb interaktywny pozwala obsługiwać podgląd w podobny sposób jak na urządzeniu, na którym działa Twój program, np. na telefonie czy tablecie. Tryb interaktywny działa w izolowanym środowisku piaskownicy (czyli i odizolowanym od innych podglądów), w którym możesz klikać elementy i wprowadzać w podglądzie dane wejściowe użytkownika. To szybki sposób na przetestowanie różnych stanów, gestów, a nawet animacji funkcji kompozycyjnej.
Nawigacja po kodzie i konspekty funkcji
Najedź kursorem na podgląd, aby zobaczyć obrysy funkcji kompozycyjnych, które się w nim znajdują. Kliknięcie konspektu elementu kompozycyjnego powoduje wyświetlenie jego definicji w widoku edytora.
Uruchom podgląd
Możesz uruchomić określony plik @Preview w emulatorze lub na urządzeniu fizycznym. Podgląd jest wdrożony w tej samej aplikacji projektu co nowy zasób Activity, więc ma ten sam kontekst i ten sam kontekst. Nie wymaga pisania
standardowego kodu z prośbą o uprawnienia, jeśli zostało już przyznane.
Kliknij ikonę Wyświetl podgląd 
obok adnotacji @Preview lub u góry podglądu, a Android Studio wdroży @Preview na połączonym urządzeniu lub w emulatorze.
Kopiuj wyrenderowaną kreację @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óżne parametry przekazywane do funkcji kompozycyjnej. Pozwala to zmniejszyć ilość kodu, który w innym wypadku należałoby napisać.
Szablony wielu podglądów
androidx.compose.ui:ui-tooling-preview w wersji 1.6.0-alfa01+ wprowadza szablony interfejsu API wielu wersji roboczych: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark i @PreviewDynamicColors, dzięki którym za pomocą 1 adnotacji możesz wyświetlać podgląd interfejsu tworzenia wiadomości w typowych scenariuszach.
Tworzenie niestandardowych adnotacji z wieloma podglądami
Multipreview umożliwia zdefiniowanie klasy adnotacji, która ma wiele adnotacji @Preview o różnych konfiguracjach. Dodanie tej adnotacji do funkcji kompozycyjnej powoduje automatyczne renderowanie wszystkich podglądów. Możesz na przykład użyć tej adnotacji, aby jednocześnie wyświetlić podgląd wielu urządzeń, rozmiarów czcionek lub motywów, nie powtarzając 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
W przypadku elementów kompozycyjnych w wersji testowej możesz użyć tej adnotacji niestandardowej:
@FontScalePreviews
@Composable
fun HelloWorldPreview() {
Text("Hello World")
}
Aby uzyskać pełniejszy zestaw podglądów, możesz połączyć wiele adnotacji do wielu podglądów i zwykłych adnotacji do podglądu. Łączenie adnotacji z wieloma podglądami nie oznacza, że wyświetlają się wszystkie różne kombinacje. Zamiast tego każda adnotacja z podglądem wieloosobowym 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)) } }
}
Połączenie wielu podglądu i podglądu normalnego pozwala na bardziej wszechstronne testowanie wielu właściwości w projektach na większą skalę.
@Preview i duże zbiory danych
Bardzo często pojawia się konieczność przekazania dużego zbioru danych do podglądu kompozycyjnego. Aby to zrobić, przekaż przykładowe dane do funkcji podglądu kompozycyjnego, dodając parametr z adnotacją @PreviewParameter.
@Preview
@Composable
fun UserProfilePreview(
@PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
UserProfile(user)
}
Aby podać przykładowe dane, utwórz klasę, która implementuje metodę PreviewParameterProvider i zwraca przykładowe dane w postaci sekwencji.
class UserPreviewParameterProvider : PreviewParameterProvider<User> {
override val values = sequenceOf(
User("Elise"),
User("Frank"),
User("Julia")
)
}
Renderowany zostanie jeden podgląd na każdy element danych w sekwencji:
W przypadku wielu podglądów możesz użyć tej samej klasy dostawcy. 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)
}
Ograniczenia i sprawdzone metody
Android Studio uruchamia kod podglądu bezpośrednio w obszarze podglądu. Nie wymaga używania emulatora ani urządzenia fizycznego, ponieważ korzysta z przeniesionej części platformy Androida o nazwie Layoutlib. Layoutlib to niestandardowa wersja platformy Androida zaprojektowana do działania poza urządzeniami z Androidem. Celem biblioteki jest udostępnienie podglądu układu w Android Studio, który jest bardzo zbliżony do renderowania na urządzeniach.
Ograniczenia dotyczące podglądu
Ze względu na sposób renderowania podglądów w Android Studio są one nieskomplikowane i nie wymagają do ich renderowania całej platformy Androida. Wiąże się to jednak z następującymi ograniczeniami:
- Brak dostępu do sieci
- Brak dostępu do plików
- Niektóre interfejsy API
Contextmogą nie być w pełni dostępne
Podglądy i ViewModels
Gdy używasz ViewModel w komponencie, wyświetlanie podglądu jest ograniczone. System podglądu nie jest w stanie zbudować wszystkich parametrów przekazanych do obiektu ViewModel, np. repozytoriów, przypadków użycia, menedżerów itp. Jeśli ViewModel uczestniczy w wstrzykiwaniu zależności (np. w przypadku Hilt), system podglądu nie może utworzyć całego wykresu zależności, by utworzyć ViewModel.
Gdy spróbujesz wyświetlić podgląd funkcji kompozycyjnej za pomocą ViewModel, Android Studio wyświetli błąd podczas renderowania danego elementu kompozycyjnego:
Jeśli chcesz wyświetlić podgląd funkcji kompozycyjnej, która korzysta z funkcji ViewModel, utwórz kolejny element kompozycyjny z parametrami z ViewModel przekazywanymi jako argumenty funkcji kompozycyjnej. Dzięki temu nie musisz wyświetlać podglądu funkcji kompozycyjnej, która 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
Zawsze możesz nacisnąć Ctrl lub ⌘ i kliknąć adnotację @Preview w Android Studio, aby wyświetlić pełną listę parametrów, które możesz dostosować podczas dostosowywania 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,
)
Dodatkowe materiały
Aby dowiedzieć się więcej o tym, jak Android Studio promuje łatwość użycia @Preview, i poznać więcej wskazówek na temat narzędzi, odwiedź bloga o narzędziu do tworzenia wiadomości.
Polecane dla Ciebie
- Uwaga: tekst linku jest wyświetlany, gdy JavaScript jest wyłączony
- Dane o zakresie lokalnym w CompositionLocal
- Material Design 2 w obszarze Utwórz
- Korzystanie z widoków w sekcji Utwórz