أساسيات الأنماط

هناك ثلاث طرق يمكنك من خلالها استخدام "الأنماط" في تطبيقك:

1. يمكنك استخدامها مباشرةً في المكوّنات الحالية التي تعرض المَعلمة Style.
2. تطبيق نمط يتضمّن Modifier.styleable على عناصر قابلة للإنشاء في التصميم لا تقبل المَعلمة Style
3. في نظام التصميم المخصّص الخاص بك، استخدِم Modifier.styleable{} واعرض مَعلمة نمط على المكوّنات الخاصة بك.

الخصائص المتاحة في "الأنماط"

تتضمّن الأنماط العديد من الخصائص نفسها التي تتضمّنها المعدِّلات، ولكن لا يمكن تكرار كل ما هو معدِّل باستخدام نمط. ستظل بحاجة إلى معدِّلات لبعض السلوكيات، مثل التفاعلات أو الرسومات المخصّصة أو ترتيب الخصائص.

استخدام "الأنماط" مباشرةً على المكوّنات باستخدام مَعلمات "النمط"

تتيح لك المكوّنات التي تعرض المَعلمة Style ضبط نمطها:

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

يمكنك ضمن دالة lambda الخاصة بالتصميم ضبط سمات مختلفة، مثل externalPadding أو background:

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

للاطّلاع على القائمة الكاملة بالسمات المتوافقة، يُرجى الرجوع إلى السمات المتاحة في "الأنماط".

تطبيق الأنماط باستخدام أدوات التعديل على المكوّنات التي لا تتضمّن مَعلمة حالية

بالنسبة إلى المكوّنات التي لا تتضمّن مَعلمة نمط مضمّنة، يظل بإمكانك تطبيق الأنماط باستخدام المعدِّل styleable. ويكون هذا النهج مفيدًا أيضًا عند تطوير مكوّنات مخصّصة.

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

على غرار المَعلمة style، يمكنك تضمين سمات مثل background أو contentPadding أو externalPadding داخل تعبير lambda.

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

تكون معدِّلات Modifier.styleable المتسلسلة المتعدّدة مضافة إلى الخصائص غير الموروثة في العنصر القابل للإنشاء الذي تم تطبيقه، وتتصرّف بشكل مشابه للمعدِّلات المتعدّدة التي تحدّد الخصائص نفسها. بالنسبة إلى الخصائص الموروثة، يتم إلغاء هذه الخصائص، ويحدّد المعدِّل الأخير styleable في السلسلة القيم.

عند استخدام Modifier.styleable، قد تحتاج أيضًا إلى إنشاء وتوفير StyleState لاستخدامه مع المعدِّل لتطبيق تصميم مستند إلى الحالة. لمزيد من التفاصيل، اطّلِع على الحالات والحركات باستخدام الأنماط.

تحديد نمط مستقل

يمكنك تحديد "نمط" مستقل لأغراض إعادة الاستخدام:

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

يمكنك بعد ذلك تمرير هذا النمط المحدّد إلى مَعلمة النمط في عنصر قابل للإنشاء أو باستخدام Modifier.styleable. عند استخدام Modifier.styleable، عليك أيضًا إنشاء عنصر StyleState. يتم تناول StyleState بالتفصيل في مستند الحالات والرسوم المتحركة باستخدام الأنماط.

يوضّح المثال التالي كيف يمكنك تطبيق نمط إما مباشرةً من خلال المَعلمات المضمّنة في أحد المكوّنات، أو من خلال 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

يمكنك أيضًا تمرير هذا النمط إلى عدة مكوّنات:

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

إضافة سمات "النمط" المتعددة

يمكنك إضافة خصائص "النمط" المتعددة من خلال ضبط خصائص مختلفة في كل سطر:

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

لا يمكن إضافة خصائص في "الأنماط"، على عكس التصميم المستند إلى المعدِّلات. تستخدم الأنماط آخر قيمة تم ضبطها في قائمة الخصائص ضمن حزمة نمط واحدة. في المثال التالي، تم ضبط الخلفية مرتين، وبالتالي فإنّ TealColor هي الخلفية التي تم تطبيقها. بالنسبة إلى المساحة المتروكة، تلغي contentPaddingTop المساحة المتروكة العلوية التي تم ضبطها بواسطة contentPadding ولا تجمع القيم.

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

دمج عناصر أنماط متعددة

يمكنك إنشاء عناصر Style متعددة وتمريرها إلى مَعلمة style الخاصة بالدالة المركّبة.

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

BaseButton(
    style = style1 then style2,
    onClick = {

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

عندما تحدّد عدة "أنماط" السمة نفسها، يتم اختيار السمة التي تم ضبطها آخر مرة. بما أنّ الخصائص ليست إضافية في "الأنماط"، فإنّ آخر مسافة بادئة تم تمريرها تلغي contentPaddingHorizontal التي تم ضبطها بواسطة contentPadding الأولية. بالإضافة إلى ذلك، يلغي لون الخلفية الأخير لون الخلفية الذي تم ضبطه بواسطة النمط الأولي الذي تم تمريره.

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

في هذه الحالة، يكون التنسيق المطبَّق بخلفية رمادية فاتحة ومساحة متروكة 32.dp، باستثناء المساحة المتروكة على اليمين واليسار التي تبلغ قيمتها 8.dp.

اكتساب الأنماط

تنتقل بعض خصائص الأنماط، مثل contentColor والخصائص ذات الصلة بنمط النص، إلى العناصر القابلة للإنشاء التابعة. يؤدي ضبط نمط على دالة مركّبة فرعية إلى إلغاء نمط العنصر الرئيسي الموروث لهذه الدالة المركّبة الفرعية المحدّدة.

النمط الرئيسي

يمكنك ضبط خصائص النص (مثل contentColor) من الدالة المركّبة الرئيسية، وسيتم نقلها إلى جميع الدوال المركّبة الفرعية 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

استبدال المواقع الفرعية للسمات

يمكنك أيضًا ضبط الأنماط على عنصر 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 can ", style = {
        contentBrush(Brush.linearGradient(listOf(Color.Red, Color.Blue)))
    })
    BaseText("override properties")
    BaseText("set by their parents")
}
StylesSnippets.kt

تنفيذ خصائص "النمط" المخصّصة

يمكنك إنشاء سمات مخصّصة يتم ربطها بتعريفات "النمط" الحالية باستخدام دوال الإضافة على StyleScope، كما هو موضّح في المثال التالي:

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

طبِّق هذه السمة الجديدة ضمن تعريف "نمط":

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

لا تتوفّر إمكانية إنشاء سمات جديدة قابلة للتصميم. إذا كانت حالة الاستخدام تتطلّب توفير هذا الدعم، يُرجى إرسال طلب ميزة.

قراءة قيم CompositionLocal

من الأنماط الشائعة تخزين رموز نظام التصميم داخل CompositionLocal، للوصول إلى المتغيرات بدون الحاجة إلى تمريرها كمعلمات. يمكن أن تصل الأنماط إلى CompositionLocal لاسترداد القيم على مستوى النظام ضمن نمط:

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