الإجراءات المسموح بها وغير المسموح بها في"الأنماط"

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

الإجراءات التي يُنصح بها

يُرجى اتّباع أفضل الممارسات التالية:

يجب: استخدام "الأنماط" للعناصر المرئية و"المعدّلات" للسلوكيات

استخدِم Styles API للإعدادات المرئية (الخلفيات، والحشو، والحدود)، واحتفِظ بالمعدّلات للسلوكيات، مثل منطق النقر أو رصد الإيماءات أو تسهيل الاستخدام.

يجب: عرض مَعلمات الأنماط في أنظمة التصميم

بالنسبة إلى مكوّنات نظام التصميم المخصّص، يجب عرض عنصر Style بعد مَعلمة المعدِّل.

@Composable
fun GradientButton(
    modifier: Modifier = Modifier,
    // ✅ DO: for design system components, expose a style modifier to consumers to be able to customize the components
    style: Style = Style
) {
    // Consume the style
}
DosDonts.kt

الإجراء: استبدِل المَعلمات المستندة إلى العناصر المرئية بـ "نمط"

ننصحك باستبدال المَعلمات في العناصر القابلة للإنشاء بمَعلمة Style واحدة. مثلاً:

// Before
@Composable
fun OldButton(background: Color, fontColor: Color) {
}

// After
// ✅ DO: Replace visual-based parameters with a style that includes same properties
@Composable
fun NewButton(style: Style = Style) {
}
DosDonts.kt

يجب: تحديد أولويات الأنماط للصور المتحركة

استخدِم كتلة animate المضمّنة لتطبيق أنماط مستندة إلى الحالة مع صور متحركة لتحسين الأداء مقارنةً بالمعدّلات.

يجب: الاستفادة من ميزة "الكتابة الأخيرة هي الأهم"

استفِد من حقيقة أنّ سمات style تستبدل السمات السابقة بدلاً من تكديسها. استخدِم هذه السمة لتجاوز حدود المكوّنات أو خلفياتها التلقائية بدون الحاجة إلى مَعلمات متعدّدة.

الإجراءات التي يجب تجنُّبها

ننصح بعدم استخدام الأنماط التالية:

لا تستخدِم "الأنماط" لمنطق التفاعل

لا تحاول التعامل مع onClick أو رصد الإيماءات ضمن نمط. تقتصر الأنماط على الإعدادات المرئية استنادًا إلى الحالة، لذا يجب ألا تتعامل مع منطق النشاط التجاري، بل يجب أن تتضمّن فقط مظهرًا مرئيًا مختلفًا استنادًا إلى الحالة.

لا تفعل ما يلي: تقديم نمط تلقائي كمعلَمة تلقائية

يجب دائمًا تحديد مَعلمات النمط باستخدام style: Style = Style:

@Composable
fun BadButton(
    modifier: Modifier = Modifier,
    // ❌ DON'T set a default style here as a parameter
    style: Style = Style { background(Color.Red) }
) {
}
DosDonts.kt

لتضمين مَعلمة "تلقائية"، ادمج نمط المَعلمة الواردة مع المَعلمة التلقائية المحدّدة:

@Composable
fun GoodButton(
    modifier: Modifier = Modifier,
    // ✅ Do: always pass it as a Style, do not pass other defaults
    style: Style = Style
) {
    // ...
    val defaultStyle = Style { background(Color.Red) }
    // ✅ Do Combine defaults inside with incoming parameter
    Box(modifier = modifier.styleable(styleState, defaultStyle, style)) {
      // your logic
    }
}
DosDonts.kt

لا: تقديم مَعلمات نمط إلى عناصر قابلة للإنشاء مستندة إلى التنسيق

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