Modyfikatory tworzenia wiadomości

Modyfikatory umożliwiają ozdabianie lub rozszerzanie komponentów. Zmienne umożliwiają wykonywanie takich czynności:

• zmieniać rozmiar, układ, zachowanie i wygląd komponentu;
• Dodawanie informacji, takich jak etykiety ułatwień dostępu
• Przetwarzanie danych wejściowych użytkownika
• Dodawanie interakcji na wysokim poziomie, np. klikania, przewijania, przeciągania lub powiększania elementów.

Modyfikatory to standardowe obiekty Kotlin. Aby utworzyć modyfikator, wywołaj jedną z funkcji klasy Modifier:

@Composable
private fun Greeting(name: String) {
    Column(modifier = Modifier.padding(24.dp)) {
        Text(text = "Hello,")
        Text(text = name)
    }
}
ModifierSnippets.kt

Możesz łączyć te funkcje, aby tworzyć z nich złożone wyrażenia:

@Composable
private fun Greeting(name: String) {
    Column(
        modifier = Modifier
            .padding(24.dp)
            .fillMaxWidth()
    ) {
        Text(text = "Hello,")
        Text(text = name)
    }
}
ModifierSnippets.kt

W kodzie powyżej zwróć uwagę na różne funkcje modyfikujące używane razem.

• padding umieszcza odstęp wokół elementu.
• fillMaxWidth powoduje, że kompozyt wypełnia maksymalną szerokość określoną przez jego nadrzędny element.

Zalecamy, aby wszystkie komponenty przyjmowały parametr modifieri przekazywały ten modyfikator do pierwszego podrzędnego elementu, który emituje interfejs użytkownika. Dzięki temu kod będzie można łatwiej wykorzystać ponownie, a jego działanie będzie bardziej przewidywalne i intuicyjne. Więcej informacji znajdziesz w wytycznych dotyczących interfejsu Compose API, w sekcji Elementy akceptują i szanują parametr Modifier.

Kolejność modyfikatorów ma znaczenie

Kolejność funkcji modyfikujących ma znaczenie. Każda funkcja wprowadza zmiany w wartości Modifier zwracanej przez poprzednią funkcję, więc kolejność ma wpływ na wynik końcowy. Spójrzmy na przykład:

@Composable
fun ArtistCard(/*...*/) {
    val padding = 16.dp
    Column(
        Modifier
            .clickable(onClick = onClick)
            .padding(padding)
            .fillMaxWidth()
    ) {
        // rest of the implementation
    }
}
ModifierSnippets.kt

W powyższym kodzie cała obszar jest klikalny, w tym otaczające go wypełnienie, ponieważ modyfikator padding został zastosowany po modyfikatorze clickable. Jeśli kolejność modyfikatorów zostanie odwrócona, miejsce dodane przez padding nie reaguje na dane wejściowe użytkownika:

@Composable
fun ArtistCard(/*...*/) {
    val padding = 16.dp
    Column(
        Modifier
            .padding(padding)
            .clickable(onClick = onClick)
            .fillMaxWidth()
    ) {
        // rest of the implementation
    }
}
ModifierSnippets.kt

Uwaga: wyraźny porządek pomaga określić, jak różne modyfikatory będą ze sobą współdziałać. Porównaj to z systemem opartym na widoku, w którym musisz poznać model pudełka, w którym marginesy są stosowane „na zewnątrz” elementu, a wypełnienie „wewnątrz”, a element tła jest odpowiednio dostosowywany. Dzięki temu projektowi modyfikatorów takie działanie jest wyraźne i przewidywalne, a Ty masz większą kontrolę nad tym, jak ma ono wyglądać. Wyjaśnia ona też, dlaczego nie ma modyfikatora marży, a tylko padding.

Wbudowane modyfikatory

Jetpack Compose udostępnia listę wbudowanych modyfikatorów, które ułatwiają dekorowanie i rozszerzanie komponentów. Oto kilka typowych modyfikatorów, których użyjesz do dostosowywania układów.

Uwaga: wiele z tych modyfikatorów ma na celu ułatwić Ci układ interfejsu zgodnie z Twoimi potrzebami. Więcej informacji o tym, jak modyfikatory działają w Twoim layout, znajdziesz w dokumentacji Podstawy tworzenia layoutu.

padding i size

Domyślnie układy podane w sekcji Tworzenie otaczają swoje elementy podrzędne. Możesz jednak ustawić rozmiar za pomocą modyfikatora size:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.size(width = 400.dp, height = 100.dp)
    ) {
        Image(/*...*/)
        Column { /*...*/ }
    }
}
ModifierSnippets.kt

Pamiętaj, że podany przez Ciebie rozmiar może nie zostać uwzględniony, jeśli nie spełnia ograniczeń narzuconych przez nadrzędny układ. Jeśli chcesz, aby rozmiar kompozytowego rozmiaru był stały niezależnie od dostępnych ograniczeń, użyj modyfikatora requiredSize:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.size(width = 400.dp, height = 100.dp)
    ) {
        Image(
            /*...*/
            modifier = Modifier.requiredSize(150.dp)
        )
        Column { /*...*/ }
    }
}
ModifierSnippets.kt

W tym przykładzie, nawet jeśli wartość nadrzędnego height zostanie ustawiona na 100.dp, wysokość elementu Image będzie wynosić 150.dp, ponieważ modyfikator requiredSize ma pierwszeństwo.

Uwaga: układy są oparte na ograniczeniach i zwykle element nadrzędny przekazuje te ograniczenia elementom podrzędnym. Uczeń powinien przestrzegać tych ograniczeń. Nie zawsze jednak jest to wymagane przez interfejs. Istnieją sposoby na obejście tego zachowania dziecka. Możesz na przykład przekazywać modyfikatory, takie jak requiredSize, bezpośrednio do podrzędnego, zastępując ograniczenia otrzymane przez podrzędny od nadrzędnego, lub możesz użyć niestandardowego układu z innym zachowaniem. Jeśli element podrzędny nie spełnia ograniczeń, system układu ukrywa go przed elementem nadrzędnym. Rodzic zobaczy wartości width i height dziecka tak, jakby były one skonwertowane zgodnie z ograniczeniami określonymi przez rodzica. System układu umieści element podrzędny w centrum przestrzeni przydzielonej przez element nadrzędny, zakładając, że element podrzędny respektuje ograniczenia. Deweloperzy mogą zmienić to zachowanie polegające na wyśrodkowywaniu, stosując modyfikatory wrapContentSize do elementów podrzędnych.

Jeśli chcesz, aby układ podrzędny wypełniał całą dozwoloną przez układ nadrzędny wysokość, dodaj modyfikator fillMaxHeight (w Compose dostępne są też modyfikatory fillMaxSize i fillMaxWidth):

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.size(width = 400.dp, height = 100.dp)
    ) {
        Image(
            /*...*/
            modifier = Modifier.fillMaxHeight()
        )
        Column { /*...*/ }
    }
}
ModifierSnippets.kt

Aby dodać wypełnienie wokół elementu, ustaw modyfikator padding.

Jeśli chcesz dodać wypełnienie nad poziomą linią tekstu, aby uzyskać określoną odległość od góry układu do tej linii, użyj modyfikatora paddingFromBaseline:

@Composable
fun ArtistCard(artist: Artist) {
    Row(/*...*/) {
        Column {
            Text(
                text = artist.name,
                modifier = Modifier.paddingFromBaseline(top = 50.dp)
            )
            Text(artist.lastSeenOnline)
        }
    }
}
ModifierSnippets.kt

Przesunięcie

Aby ustawić układ względem jego pierwotnego położenia, dodaj modyfikator offset i ustaw przesunięcie wzdłuż osi x i y. Odsunięcia mogą być dodatnie lub ujemne. Różnica między padding a offset polega na tym, że dodanie offset do kompozytowego nie zmienia jego pomiarów:

@Composable
fun ArtistCard(artist: Artist) {
    Row(/*...*/) {
        Column {
            Text(artist.name)
            Text(
                text = artist.lastSeenOnline,
                modifier = Modifier.offset(x = 4.dp)
            )
        }
    }
}
ModifierSnippets.kt

Modyfikator offset jest stosowany poziomo zgodnie z kierunkiem układu. W kontekście od lewej do prawej dodatnia wartość offset przesuwa element w prawo, a w kontekście od prawej do lewej – w lewo. Jeśli chcesz ustawić przesunięcie bez uwzględniania kierunku układu, użyj modyfikatora absoluteOffset, w którym dodatnia wartość przesunięcia zawsze przesuwa element w prawo.

Modyfikator offset ma 2 przeciążenia: offset, który przyjmuje przesunięcia jako parametry, oraz offset, który przyjmuje funkcję lambda. Więcej informacji o tym, kiedy i jak używać tych funkcji oraz jak optymalizować skuteczność, znajdziesz w sekcji Skuteczność tworzenia – odkładanie odczytów na jak najdłużej.

Bezpieczeństwo zakresu w Compose

W Compose dostępne są modyfikatory, które można stosować tylko do elementów podrzędnych niektórych komponentów. Compose zapewnia to za pomocą zakresów niestandardowych.

Jeśli na przykład chcesz, aby element potomny był tak duży jak element nadrzędny Box, ale nie wpływało to na rozmiar Box, użyj modyfikatora matchParentSize. Wartość matchParentSize jest dostępna tylko w BoxScope. Dlatego można go używać tylko na koncie podrzędnym w ramach Box.

Zabezpieczenie zakresu uniemożliwia dodawanie modyfikatorów, które nie działają w innych składaniach i zakresach, a także pozwala zaoszczędzić czas, który trzeba poświęcić na próby i błędy.

Uwaga: w systemie Android View nie ma ochrony zakresu. Deweloperzy zazwyczaj testują różne parametry układu, aby dowiedzieć się, które z nich są brane pod uwagę i co oznaczają w kontekście konkretnego elementu nadrzędnego.

Modyfikatory ograniczone informują rodzica o niektórych informacjach dotyczących dziecka. Są one też często nazywane modyfikatorami danych nadrzędnych. Ich wewnętrzna budowa różni się od modyfikatorów ogólnego przeznaczenia, ale z perspektywy użytkowania te różnice nie mają znaczenia.

matchParentSize w: Box

Jeśli chcesz, aby układ podrzędny miał taki sam rozmiar jak układ nadrzędny Box, bez wpływu na rozmiar Box, użyj modyfikatora matchParentSize.

Pamiętaj, że matchParentSize jest dostępna tylko w zakresie Box, co oznacza, że dotyczy tylko bezpośrednich elementów podrzędnych komponentów Box.

W przykładzie poniżej element podrzędny Spacer pobiera rozmiar od elementu nadrzędnego Box, który z kolei pobiera rozmiar od największego elementu podrzędnego, w tym przypadku jest to ArtistCard.

@Composable
fun MatchParentSizeComposable() {
    Box {
        Spacer(
            Modifier
                .matchParentSize()
                .background(Color.LightGray)
        )
        ArtistCard()
    }
}
ModifierSnippets.kt

Jeśli zamiast matchParentSize użyto fillMaxSize, element Spacer zająłby całą dostępną przestrzeń dozwoloną dla elementu nadrzędnego, co z kolei spowodowałoby rozszerzenie tego elementu i wypełnienie całej dostępnej przestrzeni.

weight w Row i Column

Jak już wiesz z poprzedniej sekcji dotyczącej wypełniania i rozmiaru, domyślnie rozmiar kompozytowy jest definiowany przez zawartość, którą otacza. Możesz ustawić rozmiar funkcji kompozytowej tak, aby był elastyczny w ramach elementu nadrzędnego, używając modyfikatora weight, który jest dostępny tylko w RowScope i ColumnScope.

Weźmy na przykład Row, który zawiera 2 komponenty Box. Pierwsze pole ma weight 2 razy większą wartość niż drugie, czyli 2 razy większą szerokość. Ponieważ Row ma szerokość 210.dp, pierwsza Box ma szerokość 140.dp, a druga 70.dp:

@Composable
fun ArtistCard(/*...*/) {
    Row(
        modifier = Modifier.fillMaxWidth()
    ) {
        Image(
            /*...*/
            modifier = Modifier.weight(2f)
        )
        Column(
            modifier = Modifier.weight(1f)
        ) {
            /*...*/
        }
    }
}
ModifierSnippets.kt

Wyodrębnianie i ponowne używanie modyfikatorów

Aby udekorować lub rozszerzyć kompozyt, można połączyć łańcuchowo wiele modyfikatorów. Ten łańcuch jest tworzony za pomocą interfejsu Modifier, który reprezentuje uporządkowaną, niezmienną listę pojedynczych Modifier.Elements.

Każdy element Modifier.Element reprezentuje indywidualne zachowanie, takie jak zachowanie związane z układem, rysowaniem i grafiką, wszystkie zachowania związane z gestami, zachowanie związane z skupieniem i semantyką, a także zdarzenia wprowadzania danych na urządzeniu. Ich kolejność ma znaczenie: najpierw zostaną zastosowane elementy modyfikujące, które zostały dodane jako pierwsze.

Czasami warto ponownie użyć tych samych instancji łańcucha modyfikatorów w kilku komponentach, wyodrębniając je w postaci zmiennych i przenosząc do szerszych zakresów. Może to poprawić czytelność kodu lub pomóc w zwiększeniu wydajności aplikacji z kilku powodów:

• ponowne przydzielenie modyfikatorów nie będzie powtarzane podczas ponownego skompilowania komponentów, które ich używają.
• Łańcuchy modyfikatorów mogą być bardzo długie i skomplikowane, więc ponowne użycie tego samego łańcucha może zmniejszyć obciążenie, jakie Compose musi ponieść podczas ich porównywania.
• Takie wyodrębnienie przyczynia się do czystości, spójności i łatwości utrzymania kodu w całym repozytorium

Sprawdzone metody ponownego używania modyfikatorów

Twórz własne łańcuchy Modifier i wyodbywaj je, aby używać ich w wielu komponentach składanych. Możesz po prostu zapisać modyfikator, ponieważ jest to obiekt podobny do danych:

val reusableModifier = Modifier
    .fillMaxWidth()
    .background(Color.Red)
    .padding(12.dp)
ModifierSnippets.kt

Wyodrębnianie i ponowne używanie modyfikatorów podczas obserwowania często zmieniającego się stanu

Gdy obserwujemy często zmieniające się stany w komponowalnych elementach, takich jak stany animacji czy scrollState, może to powodować znaczną liczbę ponownych składań. W takim przypadku modyfikatory zostaną przypisane do każdej rekompozycji i potencjalnie do każdego klatki:

@Composable
fun LoadingWheelAnimation() {
    val animatedState = animateFloatAsState(/*...*/)

    LoadingWheel(
        // Creation and allocation of this modifier will happen on every frame of the animation!
        modifier = Modifier
            .padding(12.dp)
            .background(Color.Gray),
        animatedState = animatedState
    )
}
ModifierSnippets.kt

Zamiast tego możesz utworzyć, wyodrębnić i ponownie użyć tej samej instancji modyfikatora i przekazać ją do komponentu w ten sposób:

// Now, the allocation of the modifier happens here:
val reusableModifier = Modifier
    .padding(12.dp)
    .background(Color.Gray)

@Composable
fun LoadingWheelAnimation() {
    val animatedState = animateFloatAsState(/*...*/)

    LoadingWheel(
        // No allocation, as we're just reusing the same instance
        modifier = reusableModifier,
        animatedState = animatedState
    )
}
ModifierSnippets.kt

Wyodrębnianie i ponowne używanie nieskoordynowanych modyfikatorów

Modyfikatory mogą być nieograniczone lub ograniczone do konkretnego kompozytowanego elementu. W przypadku modyfikatorów bez zakresu możesz je łatwo wyodrębnić spoza kompozytowych jako proste zmienne:

val reusableModifier = Modifier
    .fillMaxWidth()
    .background(Color.Red)
    .padding(12.dp)

@Composable
fun AuthorField() {
    HeaderText(
        // ...
        modifier = reusableModifier
    )
    SubtitleText(
        // ...
        modifier = reusableModifier
    )
}
ModifierSnippets.kt

Może to być szczególnie korzystne w połączeniu z schematami opóźnionego ładowania. W większości przypadków warto, aby wszystkie elementy, które mogą być znaczące, miały te same modyfikatory:

val reusableItemModifier = Modifier
    .padding(bottom = 12.dp)
    .size(216.dp)
    .clip(CircleShape)

@Composable
private fun AuthorList(authors: List<Author>) {
    LazyColumn {
        items(authors) {
            AsyncImage(
                // ...
                modifier = reusableItemModifier,
            )
        }
    }
}
ModifierSnippets.kt

Wyodrębnianie i ponowne używanie modyfikatorów ograniczonych

W przypadku modyfikatorów ograniczonych do określonych komponentów możesz wyodrębnić je na najwyższym możliwym poziomie i w odpowiednich przypadkach ponownie ich użyć:

Column(/*...*/) {
    val reusableItemModifier = Modifier
        .padding(bottom = 12.dp)
        // Align Modifier.Element requires a ColumnScope
        .align(Alignment.CenterHorizontally)
        .weight(1f)
    Text1(
        modifier = reusableItemModifier,
        // ...
    )
    Text2(
        modifier = reusableItemModifier
        // ...
    )
    // ...
}
ModifierSnippets.kt

Do bezpośrednich podrzędnych elementów o tym samym zakresie należy przekazywać tylko wyodrębnione modyfikatory zakresu. Więcej informacji o tym, dlaczego jest to ważne, znajdziesz w sekcji Bezpieczeństwo zakresu w Compose:

Column(modifier = Modifier.fillMaxWidth()) {
    // Weight modifier is scoped to the Column composable
    val reusableItemModifier = Modifier.weight(1f)

    // Weight will be properly assigned here since this Text is a direct child of Column
    Text1(
        modifier = reusableItemModifier
        // ...
    )

    Box {
        Text2(
            // Weight won't do anything here since the Text composable is not a direct child of Column
            modifier = reusableItemModifier
            // ...
        )
    }
}
ModifierSnippets.kt

dalsze łańcuchowanie wyodrębnionych modyfikatorów;

Wyodrębnione ciągi modyfikatorów możesz dalej łączyć lub dołączać, wywołując funkcję .then():

val reusableModifier = Modifier
    .fillMaxWidth()
    .background(Color.Red)
    .padding(12.dp)

// Append to your reusableModifier
reusableModifier.clickable { /*...*/ }

// Append your reusableModifier
otherModifier.then(reusableModifier)
ModifierSnippets.kt

Pamiętaj, że kolejność modyfikatorów ma znaczenie.

Więcej informacji

Udostępniamy pełną listę modyfikatorów wraz z ich parametrami i zakresami.

Aby dowiedzieć się więcej o używaniu modyfikatorów, możesz też skorzystać z podstawowych układów w ćwiczeniu z programowania Compose lub zapoznać się z repozytorium Now na Androida.

Więcej informacji o modyfikatorach niestandardowych i sposobie ich tworzenia znajdziesz w dokumentacji Niestandardowe układy – korzystanie z modyfikatora układu.