Podstawy stylów

Style możesz zastosować w aplikacji na 3 sposoby:

1. Używaj bezpośrednio w przypadku istniejących komponentów, które udostępniają parametr Style.
2. Stosowanie stylu za pomocą Modifier.styleable w komponentach kompozycyjnych układu, które nie akceptują parametru Style.
3. W własnym systemie projektowania niestandardowego użyj Modifier.styleable{} i udostępnij parametr stylu we własnych komponentach.

Dostępne właściwości w przypadku stylów

Style obsługują wiele tych samych właściwości co modyfikatory, ale nie wszystko, co jest modyfikatorem, można odtworzyć za pomocą stylu. Nadal potrzebujesz modyfikatorów w przypadku niektórych działań, takich jak interakcje, rysowanie niestandardowe czy układanie właściwości.

Grupowanie	Właściwości	Odziedziczone przez wydawców podrzędnych
Układ i rozmiar
Dopełnienie	contentPadding (wewnętrzny) i externalPadding (zewnętrzny). Dostępne w wariantach kierunkowych, poziomych, pionowych i wszechstronnych.	Nie
Wymiary	fillWidth/Height/Size() i width, height i size (obsługuje ułamki Dp, DpSize i Float).	Nie
Pozycjonowanie	left/top/right/bottom kompensacje.	Nie
Wygląd
Ładowanie	background i foreground (obsługuje Color lub Brush).	Nie
Obramowanie	borderWidth, borderColor i borderBrush.	Nie
Kształt	shape	Nie, ale jest używany w połączeniu z innymi właściwościami. clip i border używają tego zdefiniowanego kształtu.
Cienie	dropShadow, innerShadow	Nie
Transformacje
Przemieszczanie przestrzenne warstwy graficznej	translationX, translationY, scaleX/Y, rotationX/Y/Z	Nie
Kontrola	alpha, zIndex (kolejność nakładania) i transformOrigin (punkt obrotu)	Nie
Typografia
Stylizacja	textStyle, fontSize, fontWeight, fontStyle i fontFamily	Tak
Kolorystyka	contentColor i contentBrush. Jest on też używany do stylizowania ikon.	Tak
Akapit	lineHeight, letterSpacing, textAlign, textDirection, lineBreak i hyphens.	Tak
Dekoracja	textDecoration, textIndent i baselineShift.	Tak

Używanie stylów bezpośrednio w komponentach za pomocą parametrów stylu

Komponenty, które udostępniają parametr Style, umożliwiają ustawienie stylu:

BaseButton(
    onClick = { },
    style = { }
) {
    BaseText("Click me")
}
StylesSnippets.kt

W funkcji lambda stylu możesz ustawić różne właściwości, np. externalPadding lub background:

BaseButton(
    onClick = { },
    style = { background(Color.Blue) }
) {
    BaseText("Click me")
}
StylesSnippets.kt

Pełną listę obsługiwanych właściwości znajdziesz w artykule Dostępne właściwości w sekcji Style.

Stosowanie stylów za pomocą modyfikatorów w przypadku komponentów bez istniejącego parametru

W przypadku komponentów, które nie mają wbudowanego parametru stylu, możesz nadal stosować style za pomocą modyfikatora styleable. To podejście jest też przydatne podczas tworzenia własnych komponentów niestandardowych.

Row(
    modifier = Modifier.styleable { }
) {
    BaseText("Content")
}
StylesSnippets.kt

Podobnie jak w przypadku parametru style, w funkcji lambda możesz uwzględnić właściwości takie jak background czy padding.

Row(
    modifier = Modifier.styleable {
        background(Color.Blue)
    }
) {
    BaseText("Content")
}
StylesSnippets.kt

Uwaga: gdy używasz Modifier.styleable, do elementów kompozycyjnych podrzędnych nie będą stosowane te właściwości, chyba że są to właściwości dziedziczone. Tylko kontener ze zmodyfikatorem styleable ma zastosowane te właściwości.

Wiele połączonych modyfikatorów Modifier.styleable jest dodawanych do właściwości nieprzekazywanych w zastosowanym komponencie, co działa podobnie jak wiele modyfikatorów definiujących te same właściwości. W przypadku właściwości dziedziczonych są one zastępowane, a wartości ustawia ostatni modyfikator styleable w łańcuchu.

Gdy używasz Modifier.styleable, możesz też utworzyć i dostarczyć StyleState, który będzie używany z modyfikatorem do stosowania stylów opartych na stanie. Więcej informacji znajdziesz w artykule Stany i animacje w stylach.

Definiowanie samodzielnego stylu

Możesz zdefiniować samodzielny styl, aby można go było używać wielokrotnie:

val style = Style { background(Color.Blue) }
StylesSnippets.kt

Następnie możesz przekazać zdefiniowany styl do parametru stylu komponentu lub za pomocą Modifier.styleable. Jeśli używasz Modifier.styleable, musisz też utworzyć obiekt StyleState. StyleState jest szczegółowo omówiony w dokumentacji Stany i animacje ze stylami.

Poniższy przykład pokazuje, jak zastosować styl bezpośrednio za pomocą wbudowanych parametrów komponentu lub za pomocą elementu Modifier.styleable:

val style = Style { background(Color.Blue) }

// built in parameter
BaseButton(onClick = { }, style = style) {
    BaseText("Button")
}

// modifier styleable
val styleState = remember { MutableStyleState(null) }
Column(
    Modifier.styleable(styleState, style)
) {
    BaseText("Column content")
}
StylesSnippets.kt

Możesz też przekazać ten styl do wielu komponentów:

val style = Style { background(Color.Blue) }

// built in parameter
BaseButton(onClick = { }, style = style) {
    BaseText("Button")
}
BaseText("Different text that uses the same style parameter", style = style)

// modifier styleable
val columnStyleState = remember { MutableStyleState(null) }
Column(
    Modifier.styleable(columnStyleState, style)
) {
    BaseText("Column")
}
val rowStyleState = remember { MutableStyleState(null) }
Row(
    Modifier.styleable(rowStyleState, style)
) {
    BaseText("Row")
}
StylesSnippets.kt

Dodawanie wielu właściwości stylu

Możesz dodać wiele właściwości stylu, ustawiając różne właściwości w każdym wierszu:

BaseButton(
    onClick = { },
    style = {
        background(Color.Blue)
        contentPaddingStart(16.dp)
    }
) {
    BaseText("Button")
}
StylesSnippets.kt

Ważne: w przeciwieństwie do stylów opartych na modyfikatorach właściwości w stylach zastępują się nawzajem. Ostatnia zdefiniowana właściwość ma pierwszeństwo.

Właściwości w stylach nie sumują się, w przeciwieństwie do stylów opartych na modyfikatorach. Style przyjmują ostatnią ustawioną wartość na liście właściwości w jednym bloku stylu. W poniższym przykładzie, w którym tło jest ustawione 2 razy, zastosowane tło to TealColor. W przypadku dopełnienia atrybut contentPaddingTop zastępuje dopełnienie górne ustawione przez atrybut contentPadding i nie łączy wartości.

BaseButton(
    style = {
        background(Color.Red)
        // Background of Red is now overridden with TealColor instead
        background(TealColor)
        // All directions of padding are set to 64.dp (top, start, end, bottom)
        contentPadding(64.dp)
        // Top padding is now set to 16.dp, all other paddings remain at 64.dp
        contentPaddingTop(16.dp)
    },
    onClick = {
        //
    }
) {
    BaseText("Click me!")
}
StylesSnippets.kt

Rysunek 1. Przycisk z ustawionymi 2 kolorami tła i 2 contentPaddingzastąpieniami

.

Scalanie wielu obiektów stylu

Możesz utworzyć wiele obiektów Style i przekazać je do parametru style w funkcji kompozycyjnej.

val style1 = Style { background(TealColor) }
val style2 = Style { contentPaddingTop(16.dp) }

BaseButton(
    style = style1 then style2,
    onClick = {

    },
) {
    BaseText("Click me!")
}
StylesSnippets.kt

Rysunek 2. Przycisk z ustawionym kolorem tła i wartością contentPaddingTop.

Jeśli kilka stylów określa tę samą właściwość, wybierana jest ostatnia ustawiona właściwość. W przypadku stylów właściwości nie są sumowane, więc ostatni przekazany dopełnienie zastępuje contentPaddingHorizontal ustawione przez początkowy contentPadding. Dodatkowo ostatni kolor tła zastępuje kolor tła ustawiony przez początkowy styl przekazany w parametrze.

val style1 = Style {
    background(Color.Red)
    contentPadding(32.dp)
}

val style2 = Style {
    contentPaddingHorizontal(8.dp)
    background(Color.LightGray)
}

BaseButton(
    style = style1 then style2,
    onClick = {

    },
) {
    BaseText("Click me!")
}
StylesSnippets.kt

W tym przypadku zastosowany styl ma jasnoszare tło i 32.dp dopełnienie, z wyjątkiem dopełnienia po lewej i prawej stronie, które ma wartość 8.dp.

Rysunek 3. Przycisk z ikoną contentPadding, który jest zastępowany przez różne style.

Dziedziczenie stylu

Niektóre właściwości stylu, takie jak contentColor i właściwości związane ze stylem tekstu, są przekazywane do funkcji kompozycyjnych podrzędnych. Styl ustawiony w kompozycji podrzędnej zastępuje odziedziczony styl nadrzędny w przypadku tej konkretnej kompozycji podrzędnej.

Rysunek 4. Propagowanie stylu za pomocą parametrów Style, styleable i bezpośrednich.

Priorytet	Metoda	Efekt
1 (najwyższy)	Argumenty bezpośrednie w funkcji kompozycyjnej	Zastępuje wszystko, np. Text(color = Color.Red)
2	Parametr stylu	Zastąpienia stylu lokalnego Text(style = Style { contentColor(Color.Red)}
3	Łańcuch modyfikatorów	Modifier.styleable{ contentColor(Color.Red) na samym komponencie.
4 (najniższy)	Style nadrzędne	W przypadku właściwości, które mogą być dziedziczone (typografia/kolor) przekazywanych z elementu nadrzędnego.

Uwaga: wiele połączonych modyfikatorów Modifier.styleable jest dodawanych do nieprzekazywanych właściwości w zastosowanym komponencie, podobnie jak w przypadku wielu modyfikatorów definiujących te same właściwości. W przypadku właściwości dziedziczonych są one zastępowane, a wartości ustawia ostatni modyfikator styleable w łańcuchu.

Styl nadrzędny

Właściwości tekstu (np. contentColor) możesz ustawić w funkcji kompozycyjnej nadrzędnej, a zostaną one przekazane do wszystkich funkcji kompozycyjnych podrzędnych Text.

val styleState = remember { MutableStyleState(null) }
Column(
    modifier = Modifier.styleable(styleState) {
        background(Color.LightGray)
        val blue = Color(0xFF4285F4)
        val purple = Color(0xFFA250EA)
        val colors = listOf(blue, purple)
        contentBrush(Brush.linearGradient(colors))
    },
) {
    BaseText("Children inherit", style = { width(60.dp) })
    BaseText("certain properties")
    BaseText("from their parents")
}
StylesSnippets.kt

Rysunek 5. dziedziczenie właściwości komponentów podrzędnych;

Zastępowanie właściwości w usłudze podrzędnej

Możesz też ustawić styl dla konkretnego komponentu Text. Jeśli element kompozycyjny nadrzędny ma ustawiony styl, styl ustawiony w elemencie kompozycyjnym podrzędnym zastępuje styl elementu kompozycyjnego nadrzędnego.

val styleState = remember { MutableStyleState(null) }
Column(
    modifier = Modifier.styleable(styleState) {
        background(Color.LightGray)
        val blue = Color(0xFF4285F4)
        val purple = Color(0xFFA250EA)
        val colors = listOf(blue, purple)
        contentBrush(Brush.linearGradient(colors))
    },
) {
    BaseText("Children can ", style = {
        contentBrush(Brush.linearGradient(listOf(Color.Red, Color.Blue)))
    })
    BaseText("override properties")
    BaseText("set by their parents")
}
StylesSnippets.kt

Rysunek 6. Komponenty kompozycyjne podrzędne zastępują właściwości nadrzędne.

Wdrażanie niestandardowych właściwości stylu

Możesz tworzyć właściwości niestandardowe, które są mapowane na istniejące definicje stylu, używając funkcji rozszerzeń w StyleScope, jak pokazano w tym przykładzie:

fun StyleScope.outlinedBackground(color: Color) {
    border(1.dp, color)
    background(color)
}
StylesSnippets.kt

Zastosuj tę nową właściwość w definicji stylu:

val customExtensionStyle = Style {
    outlinedBackground(Color.Blue)
}
StylesSnippets.kt

Tworzenie nowych właściwości, które można dostosowywać, jest niedostępne. Jeśli Twój przypadek użycia wymaga takiej obsługi, prześlij prośbę o dodanie funkcji.

Odczytywanie wartości CompositionLocal

Często stosuje się wzorzec przechowywania tokenów systemu projektowania w obiekcie CompositionLocal, aby uzyskać dostęp do zmiennych bez konieczności przekazywania ich jako parametrów. Style mogą uzyskiwać dostęp do CompositionLocal, aby pobierać wartości systemowe w ramach stylu:

val buttonStyle = Style {
    contentPadding(12.dp)
    shape(RoundedCornerShape(50))
    background(Brush.verticalGradient(LocalCustomColors.currentValue.background))
}
StylesSnippets.kt