Aspectos básicos de los estilos

Existen tres formas de adoptar los estilos en toda tu app:

  1. Se usa directamente en componentes existentes que exponen un parámetro Style.
  2. Aplica un estilo con Modifier.styleable en elementos componibles de diseño que no acepten un parámetro Style.
  3. En tu propio sistema de diseño personalizado, usa Modifier.styleable{} y expón un parámetro de estilo en tus propios componentes.

Propiedades disponibles en Styles

Los estilos admiten muchas de las mismas propiedades que los modificadores. Sin embargo, no todo lo que es un modificador se puede replicar con un estilo. Aún necesitas modificadores para ciertos comportamientos, como interacciones, dibujo personalizado o apilamiento de propiedades.

Agrupación Propiedades Heredado por los elementos secundarios
Diseño y tamaño
Padding contentPadding (interior) y externalPadding (exterior). Disponible en variantes direccionales, horizontales, verticales y de todos los lados. No
Dimensiones fillWidth/Height/Size() y width, height y size (admite fracciones de Dp, DpSize o Float) No
Posicionamiento Desfases de left/top/right/bottom No
Apariencia visual
Llena background y foreground (admite Color o Brush) No
Bordes borderWidth, borderColor y borderBrush. No
Forma shape No, pero se usa en conjunto con otras propiedades. clip y border usan esta forma definida.
Sombras dropShadow, innerShadow No
Transformaciones
Movimiento espacial de la capa de gráficos translationX, translationY, scaleX/Y, rotationX/Y/Z No
Controla alpha, zIndex (orden de apilamiento) y transformOrigin (punto de pivote) No
Tipografía
Aplica estilos textStyle, fontSize, fontWeight, fontStyle y fontFamily Sí
Coloración contentColor y contentBrush. También se usa para el diseño de íconos. Sí
Párrafo lineHeight, letterSpacing, textAlign, textDirection, lineBreak y hyphens. Sí
Decoración textDecoration, textIndent y baselineShift. Sí

Cómo usar estilos directamente en componentes con parámetros de estilo

Los componentes que exponen un parámetro Style te permiten establecer su diseño:

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

Dentro de la lambda de estilo, puedes establecer varias propiedades, como externalPadding o background:

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

Para obtener la lista completa de las propiedades admitidas, consulta Propiedades disponibles en Styles.

Aplica estilos con modificadores para componentes sin parámetros existentes

En el caso de los componentes que no tienen un parámetro de diseño integrado, puedes aplicar diseños con el modificador styleable. Este enfoque también es útil cuando desarrollas tus propios componentes personalizados.

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

Al igual que con el parámetro style, puedes incluir propiedades como background o padding dentro de la expresión lambda.

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

Varios modificadores Modifier.styleable encadenados son aditivos con propiedades no heredadas en el elemento componible aplicado, y se comportan de manera similar a varios modificadores que definen las mismas propiedades. En el caso de las propiedades heredadas, se anulan y el último modificador styleable de la cadena establece los valores.

Cuando uses Modifier.styleable, también puedes crear y proporcionar un StyleState para usar con el modificador y aplicar un diseño basado en el estado. Para obtener más detalles, consulta Estados y animaciones con estilos.

Cómo definir un estilo independiente

Puedes definir un objeto Style independiente para reutilizarlo:

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

Luego, puedes pasar ese estilo definido al parámetro de estilo de un elemento componible o con Modifier.styleable. Cuando usas Modifier.styleable, también debes crear un objeto StyleState. StyleState se aborda en detalle en la documentación de Estados y animaciones con Styles.

En el siguiente ejemplo, se muestra cómo puedes aplicar un diseño directamente a través de los parámetros integrados de un componente o a través de un 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

También puedes pasar ese objeto Style a varios componentes:

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

Agrega varias propiedades de diseño

Puedes agregar varias propiedades de diseño estableciendo diferentes propiedades en cada línea:

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

Las propiedades de Styles no son aditivas, a diferencia del diseño basado en modificadores. Los estilos toman el último valor establecido en la lista de propiedades dentro de un bloque de estilo. En el siguiente ejemplo, con el fondo establecido dos veces, el TealColor es el fondo aplicado. En el caso del padding, contentPaddingTop anula el padding superior establecido por contentPadding y no combina los valores.

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

Botón con dos colores de fondo establecidos y dos anulaciones de contentPadding
Figura 1: Botón con dos colores de fondo establecidos y dos anulaciones de contentPadding.

Cómo combinar varios objetos de estilo

Puedes crear varios objetos Style y pasarlos al parámetro de estilo de tu elemento componible.

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

BaseButton(
    style = style1 then style2,
    onClick = {

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

Botón con color de fondo y contentPaddingTop establecidos
Figura 2: Botón con color de fondo y contentPaddingTop establecido.

Cuando varios objetos Style especifican la misma propiedad, se elige la última propiedad establecida. Dado que las propiedades no son aditivas en los estilos, el último padding que se pasa anula el contentPaddingHorizontal establecido por el contentPadding inicial. Además, el último color de fondo anula el color de fondo establecido por el estilo inicial que se pasó.

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

En este caso, el diseño aplicado tiene un fondo gris claro y un padding de 32.dp, excepto el padding izquierdo y derecho, que tiene un valor de 8.dp.

Botón con contentPadding anulado por diferentes estilos
Figura 3: Botón con contentPadding que se anula con diferentes diseños.

Herencia de estilos

Algunas propiedades de diseño, como contentColor y las relacionadas con el diseño de texto, se propagan a los elementos componibles secundarios. Un diseño establecido en un elemento componible secundario anula el diseño superior heredado para ese elemento secundario específico.

Propagación de diseño con parámetros de diseño, diseñables y directos
Figura 4: Propagación de estilo con parámetros Style, styleable y directos.
Prioridad Método Efecto
1 (más alta) Argumentos directos en un elemento componible Anula todo; por ejemplo, Text(color = Color.Red)
2 Parámetro de diseño Anulaciones de estilos locales Text(style = Style { contentColor(Color.Red)}
3 Cadena de modificadores Modifier.styleable{ contentColor(Color.Red) en el componente.
4 (más baja) Estilos principales Para las propiedades que se pueden heredar (tipografía o color) que se pasan del elemento principal.

Diseño superior

Puedes establecer propiedades de texto (como contentColor) desde el elemento superior componible, y se propagarán a todos los elementos Text componibles secundarios.

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

Herencia de propiedades de elementos componibles secundarios
Figura 5: Herencia de propiedades de elementos secundarios que admiten composición.

Anulación secundaria de propiedades

También puedes establecer el diseño en un elemento Text componible específico. Si el elemento componible principal tiene un diseño establecido, el diseño establecido en el elemento componible secundario anula el diseño del elemento componible principal.

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

Los elementos componibles secundarios anulan las propiedades principales
Figura 6: Los elementos componibles secundarios anulan las propiedades principales.

Implementa propiedades de diseño personalizadas

Puedes crear propiedades personalizadas que se asignen a definiciones de diseño existentes con funciones de extensión en StyleScope, como se muestra en el siguiente ejemplo:

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

Aplica esta nueva propiedad dentro de una definición de Style:

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

No se admite la creación de nuevas propiedades con diseño. Si tu caso de uso requiere este tipo de asistencia, envía una solicitud de función.

Lectura de valores CompositionLocal

Es un patrón común almacenar tokens del sistema de diseño dentro de un CompositionLocal, para acceder a las variables sin necesidad de pasarlas como parámetros. Los diseños pueden acceder a CompositionLocal para recuperar valores en todo el sistema dentro de un diseño:

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