paris

Paris

Paris permite definir e aplicar estilos de forma programática às visualizações do Android, incluindo atributos personalizados.

• Aplique estilos programaticamente a qualquer momento.
• Combine vários estilos juntos.
• Crie estilos programaticamente (em vez de usar XML).
• Use anotações para oferecer suporte facilmente a atributos personalizados (inspirados em Barber).
• Declare estilos explicitamente suportados para suas visualizações personalizadas.
• E muito mais...

Instalação

build.gradle do seu projeto:

 dependencies {
    implementation ' com.airbnb.android:paris:2.0.0 '
    // Apply the Paris processor if you're using Paris annotations for code gen.
    kapt ' com.airbnb.android:paris-processor:2.0.0 '
    // or if you are using Kotlin Symbol Processing
    ksp ' com.airbnb.android:paris-processor:2.0.0 '
}

Para usar Paris em um módulo de biblioteca, consulte Módulos de Biblioteca.

Início rápido

Aplicando um estilo definido por XML

myView.style( R .style. MyStyle )

Clique para ver o exemplo em Java.

 Paris . style ( myView ). apply ( R . style . MyStyle );

Onde myView é uma instância de visualização arbitrária, MyStyle é um estilo definido por XML e style é uma função de extensão fornecida por Paris. Muitos atributos, mas não todos, são suportados. Para obter mais informações, consulte Tipos e atributos de visualização compatíveis.

Combinando 2 ou mais estilos

myView.style {
    add( R .style. StyleA )
    add( R .style. StyleB )
    …
}

Clique para ver o exemplo em Java.

 Paris . styleBuilder ( myView )
        . add ( R . style . StyleA )
        . add ( R . style . StyleB )
        …
        . apply ();

Nos casos em que haja alguma sobreposição prevalece o valor do atributo do último estilo adicionado. Para mais informações, consulte Combinando estilos.

Definindo Estilos Programaticamente

textView.style {
    // Using an actual value.
    textColor( Color . GREEN )
    // Or a resource.
    textSizeRes( R .dimen.my_text_size_small)
}

Clique para ver o exemplo em Java.

 Paris . styleBuilder ( textView )
        // Using an actual value.
        . textColor ( Color . GREEN )
        // Or a resource.
        . textSizeRes ( R . dimen . my_text_size_small )
        . apply ();

Também pode ser combinado com recursos de estilo:

textView.style {
    // Adds all the attributes defined in the MyGreenTextView style.
    add( R .style. MyGreenTextView )
    textSizeRes( R .dimen.my_text_size_small)
}

Clique para ver o exemplo em Java.

 Paris . styleBuilder ( textView )
        // Adds all the attributes defined in the MyGreenTextView style.
        . add ( R . style . MyGreenTextView )
        . textSizeRes ( R . dimen . my_text_size_small )
        . apply ();

Para obter mais informações, consulte Definindo estilos programaticamente.

Atributos de visualização personalizada

Os atributos são declarados da seguinte forma:

< declare-styleable name = " MyView " >
    < attr name = " title " format = " string " />
    < attr name = " image " format = " reference " />
    < attr name = " imageSize " format = " dimension " />
</ declare-styleable >

A visualização personalizada é anotada com @Styleable e @Attr :

 // The value here corresponds to the name chosen in declare-styleable.
@Styleable( " MyView " )
class MyView (…) : ViewGroup(…) {

    init {
        // This call enables the custom attributes when used in XML layouts. It
        // extracts styling information from AttributeSet like it would a StyleRes.
        style(attrs)
    }

    @Attr( R .styleable. MyView_title )
    fun setTitle ( title : String ) {
        // Automatically called with the title value (if any) when an AttributeSet
        // or StyleRes is applied to the MyView instance.
    }

    @Attr( R .styleable. MyView_image )
    fun setImage ( image : Drawable ? ) {
        // Automatically called with the image value (if any) when an AttributeSet
        // or StyleRes is applied to the MyView instance.
    }

    @Attr( R .styleable. MyView_imageSize )
    fun setImageSize (@Px imageSize : Int ) {
        // Automatically called with the imageSize value (if any) when an
        // AttributeSet or StyleRes is applied to the MyView instance.
    }
}

Clique para ver o exemplo em Java.

 // The value here corresponds to the name chosen in declare-styleable.
@ Styleable ( "MyView" )
public class MyView extends ViewGroup {

    public MyView ( Context context ) {
        super ( context );
    }

    public MyView ( Context context , AttributeSet attrs ) {
        this ( context , attrs , 0 );
    }

    public MyView ( Context context , AttributeSet attrs , int defStyle ) {
        this ( context , attrs , defStyle );
        // This call enables the custom attributes when used in XML layouts. It
        // extracts styling information from AttributeSet like it would a StyleRes.
        Paris . style ( this ). apply ( attrs );
    }

    @ Attr ( R . styleable . MyView_title )
    public void setTitle ( String title ) {
        // Automatically called with the title value (if any) when an AttributeSet
        // or StyleRes is applied to the MyView instance.
    }

    @ Attr ( R . styleable . MyView_image )
    public void setImage ( Drawable image ) {
        // Automatically called with the image value (if any) when an AttributeSet
        // or StyleRes is applied to the MyView instance.
    }

    @ Attr ( R . styleable . MyView_imageSize )
    public void setImageSize ( @ Px int imageSize ) {
        // Automatically called with the imageSize value (if any) when an
        // AttributeSet or StyleRes is applied to the MyView instance.
    }
}

Os métodos anotados @Attr serão chamados por Paris quando a visualização for inflada com um AttributeSet ou quando um estilo for aplicado.

Para obter mais informações, consulte Atributos de visualização personalizada.

Subvisualizações de estilo

Os atributos são declarados da seguinte forma para as 2 subvisões que gostaríamos de poder estilizar:

< declare-styleable name = " MyHeader " >
    < attr name = " titleStyle " format = " reference " />
    < attr name = " subtitleStyle " format = " reference " />
    ...
</ declare-styleable >

Os campos da subvisão são anotados com @StyleableChild :

@Styleable( " MyHeader " )
class MyHeader (…) : ViewGroup(…) {

    @StyleableChild( R .styleable. MyHeader_titleStyle )
    internal val title : TextView …
    
    @StyleableChild( R .styleable. MyHeader_subtitleStyle )
    internal val subtitle : TextView …
    
    init {
        style(attrs)
    }
}

Clique para ver o exemplo em Java.

 @ Styleable ( "MyHeader" )
public class MyHeader extends ViewGroup {

    @ StyleableChild ( R . styleable . MyHeader_titleStyle )
    TextView title ;
    
    @ StyleableChild ( R . styleable . MyHeader_subtitleStyle )
    TextView subtitle ;
    
    …
    // Make sure to call Paris.style(this).apply(attrs) during initialization.
}

Os estilos de título e subtítulo agora podem fazer parte dos estilos MyHeader :

< MyHeader
    ...
    app : titleStyle = " @style/Title2 "
    app : subtitleStyle = " @style/Regular " />

myHeader.style {
    // Defined in XML.
    titleStyle( R .style. Title2 )
    // Defined programmatically.
    subtitleStyle {
        textColorRes( R .color.text_color_regular)
        textSizeRes( R .dimen.text_size_regular)
    }
}

Clique para ver o exemplo em Java.

 Paris . styleBuilder ( myHeader )
        // Defined in XML.
        . titleStyle ( R . style . Title2 )
        // Defined programmatically.
        . subtitleStyle (( builder ) -> builder
                . textColorRes ( R . color . text_color_regular )
                . textSizeRes ( R . dimen . text_size_regular ))
        . apply ();

Atenção: Funções de extensão como titleStyle e subtitleStyle são geradas durante a compilação pelo processador de anotação Paris. Quando novas anotações @StyleableChild são adicionadas, o projeto deve ser (re)compilado uma vez para que as funções relacionadas fiquem disponíveis.

Para obter mais informações, consulte Subvisões de estilo.

Vinculando estilos a visualizações

@Styleable
class MyView (…) : View(…) {

    companion object {
        // For styles defined in XML.
        @Style
        val RED_STYLE = R .style. MyView_Red

        // For styles defined programmatically.
        @Style
        val GREEN_STYLE = myViewStyle {
            background( R .color.green)
        }
    }
}

Clique para ver o exemplo em Java.

 @ Styleable
public class MyView extends View {

    // For styles defined in XML.
    @ Style
    static final int RED_STYLE = R . style . MyView_Red ;

    // For styles defined programmatically.
    @ Style
    static void greenStyle ( MyViewStyleApplier . StyleBuilder builder ) {
        builder . background ( R . color . green );
    }
}

Métodos auxiliares são gerados para cada estilo vinculado:

myView.style { addRed() } // Equivalent to style(R.style.MyView_Red)
myView.style { addGreen() } // Equivalent to add(MyView.GREEN_STYLE)

myView.style {
    addRed() // Equivalent to add(R.style.MyView_Red)
    addGreen() // Equivalent to add(MyView.GREEN_STYLE)
    …
}

Clique para ver o exemplo em Java.

 Paris . style ( myView ). applyRed (); // Equivalent to apply(R.style.MyView_Red)
Paris . style ( myView ). applyGreen (); // No equivalent.

Paris . styleBuilder ( myView )
        . addRed () // Equivalent to add(R.style.MyView_Red)
        . addGreen () // No equivalent.
        …
        . apply ();

Atenção: Funções de extensão como addRed e addGreen são geradas durante a compilação pelo processador de anotação Paris. Quando novas anotações @Style são adicionadas, o projeto deve ser (re)compilado uma vez para que as funções relacionadas fiquem disponíveis.

Para obter mais informações, consulte Vinculando estilos a visualizações personalizadas.

Documentação

Veja exemplos e navegue pela documentação completa no Paris Wiki.

Se você ainda tiver dúvidas, fique à vontade para criar um novo problema.

Contribuindo

Adoramos contribuições! Confira nossas diretrizes de contribuição e certifique-se de seguir nosso código de conduta.

Licença

 Copyright 2018 Airbnb, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.