paris

パリ

Paris を使用すると、カスタム属性を含むスタイルをプログラムで定義し、Android ビューに適用できます。

• いつでもプログラムでスタイルを適用できます。
• 複数のスタイルを組み合わせます。
• (XML を使用するのではなく) プログラムでスタイルを作成します。
• アノテーションを使用してカスタム属性を簡単にサポートします (Barber からインスピレーションを受けています)。
• カスタム ビューで明示的にサポートされるスタイルを宣言します。
• そしてさらに...

インストール

プロジェクトのbuild.gradle内:

 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 '
}

ライブラリ モジュールで Paris を使用するには、「ライブラリ モジュール」を参照してください。

クイックスタート

XML 定義のスタイルの適用

myView.style( R .style. MyStyle )

クリックすると Java の例が表示されます。

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

ここで、 myViewは任意のビュー インスタンス、 MyStyle XML 定義のスタイル、 style Paris が提供する拡張関数です。すべてではありませんが、多くの属性がサポートされています。詳細については、「サポートされているビューのタイプと属性」を参照してください。

2 つ以上のスタイルを組み合わせる

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

クリックすると Java の例が表示されます。

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

一部の重複がある場合は、最後に追加されたスタイルの属性値が優先されます。詳細については、「スタイルの結合」を参照してください。

プログラムによるスタイルの定義

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

クリックすると Java の例が表示されます。

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

スタイル リソースと組み合わせることもできます。

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

クリックすると 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 ();

詳細については、「プログラムによるスタイルの定義」を参照してください。

カスタムビュー属性

属性は次のように宣言されます。

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

カスタム ビューには@Styleableと@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.
    }
}

クリックすると 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.
    }
}

@Attr注釈付きメソッドは、ビューがAttributeSetで拡張されるとき、またはスタイルが適用されるときに、Paris によって呼び出されます。

詳細については、「カスタム ビュー属性」を参照してください。

サブビューのスタイリング

スタイルを設定できる 2 つのサブビューに対して、属性は次のように宣言されます。

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

サブビューのフィールドには@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)
    }
}

クリックすると 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.
}

タイトルとサブタイトルのスタイルを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)
    }
}

クリックすると 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 ();

注意: titleStyleやsubtitleStyleなどの拡張関数は、Paris アノテーション プロセッサによってコンパイル中に生成されます。新しい@StyleableChildアノテーションが追加された場合、関連する関数を使用できるようにするには、プロジェクトを 1 回 (再) コンパイルする必要があります。

詳細については、「サブビューのスタイル設定」を参照してください。

スタイルをビューにリンクする

@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)
        }
    }
}

クリックすると 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 );
    }
}

ヘルパー メソッドは、リンクされたスタイルごとに生成されます。

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)
    …
}

クリックすると 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 ();

注意: addRedやaddGreenなどの拡張関数は、Paris アノテーション プロセッサによってコンパイル中に生成されます。新しい@Styleアノテーションが追加された場合、関連する関数を使用できるようにするには、プロジェクトを 1 回 (再) コンパイルする必要があります。

詳細については、「スタイルをカスタム ビューにリンクする」を参照してください。

ドキュメント

Paris Wiki で例を参照し、完全なドキュメントを参照してください。

まだ質問がある場合は、お気軽に新しい問題を作成してください。

貢献する

私たちは貢献が大好きです!私たちの貢献ガイドラインを確認し、必ず行動規範に従ってください。

ライセンス

 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.