بایدها و نبایدها در مورد استایل‌ها

این صفحه بهترین شیوه‌ها برای کار با سبک‌هایی که در سراسر کدبیس شما به ثبات می‌رسند، و همچنین اصولی که ما هنگام طراحی APIها دنبال کرده‌ایم را شرح می‌دهد.

بایدها

این بهترین شیوه‌ها را دنبال کنید:

انجام دهید: از Styles برای تصاویر و از modifiers برای رفتارها استفاده کنید

از API استایل‌ها برای پیکربندی بصری (پس‌زمینه‌ها، فاصله‌گذاری، حاشیه‌ها) استفاده کنید و اصلاح‌کننده‌ها را برای رفتارهایی مانند منطق کلیک، تشخیص حرکت یا دسترسی‌پذیری ذخیره کنید.

انجام دهید: پارامترهای Style را در سیستم‌های طراحی نمایش دهید

برای اجزای سیستم طراحی سفارشی خودتان، باید یک شیء 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 جایگزین کنید

در نظر بگیرید که پارامترهای موجود در composables خود را با یک پارامتر 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 به جای پشته‌سازی، بازنویسی می‌شوند، بهره ببرید. از این ویژگی برای لغو حاشیه‌ها یا پس‌زمینه‌های پیش‌فرض کامپوننت بدون نیاز به پارامترهای متعدد استفاده کنید.

نبایدها

الگوهای زیر توصیه نمی‌شوند:

نباید: از Styles برای منطق تعامل استفاده کنید

سعی نکنید تشخیص 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

انجام ندهید: پارامترهای استایل را به کامپوننت‌های مبتنی بر طرح‌بندی ارائه ندهید

اگرچه می‌توانید به هر ترکیب‌پذیری (composable) یک استایل ارائه دهید، اما انتظار نمی‌رود که ترکیب‌پذیرهای مبتنی بر طرح‌بندی یا ترکیب‌پذیرهای سطح صفحه، استایل را بپذیرند - از دیدگاه مصرف‌کننده مشخص نیست که یک استایل در این سطح چه کاری انجام می‌دهد. استایل‌ها برای کامپوننت‌ها طراحی شده‌اند، نه لزوماً برای طرح‌بندی‌ها.

نباید: ایجاد استایل در کامپوزیشن

CompositionLocals در نقطه‌ای که استایل تعریف شده است خوانده می‌شوند، نه در جایی که مصرف می‌شوند. وقتی استایل واقعاً استفاده می‌شود، وضعیت CompositionLocal می‌تواند تغییر کند و منجر به یک استایل نادرست شود.

// DON'T - Create styles in Composition that access composition locals in this way - this will likely lead to issues when style is used / accessed, as it would not get updated when the value changes.
@Composable
fun containerStyle(): Style {
    val background = MaterialTheme.colorScheme.background
    val onBackground = MaterialTheme.colorScheme.onBackground
    return Style {
        background(background)
        contentColor(onBackground)
    }
}

// Do: Instead, Create StyleScope extension functions for your subsystems to access themed composition Locals
val StyleScope.colors: JetsnackColors
    get() = JetsnackTheme.LocalJetsnackTheme.currentValue.colors

val StyleScope.typography: androidx.compose.material3.Typography
    get() = JetsnackTheme.LocalJetsnackTheme.currentValue.typography
val StyleScope.shapes: Shapes
    get() = JetsnackTheme.LocalJetsnackTheme.currentValue.shapes
// Access CompositionLocals
val button = Style {
    background(colors.brandSecondary)
    shape(shapes.small)
}
DosDonts.kt

انجام دهید: یک سبک برای تغییرات مقدار زیرسیستم ایجاد کنید

برای مثال، اگر بین حالت تاریک و روشن جابجا می‌شوید، مقادیر تم‌دار موجود را (از طریق CompositionLocal ) برای تغییر پویای Style پرس‌وجو کنید:

// Do: Use CompositionLocals or themed values to create a single style
val buttonStyle = Style {
    background(colors.brandSecondary)
    shape(shapes.small)
}
DosDonts.kt

انجام دهید: وقتی کامپوننت اساساً در تعاریف قالب متفاوت است، کل استایل‌ها را تغییر دهید

اگر تم‌های آنها اساساً متفاوت باشد، می‌توانید کل اشیاء استایل را در سطح تم تغییر دهید.

برای مثال، اگر در حال ساخت برنامه‌ای هستید که برای هر محصول/صفحه یا پیشنهاد، تم‌های مختلفی دارد و بسیاری از ویژگی‌های یک استایل متفاوت هستند، تغییر کل مجموعه استایل‌ها در سطح یک تم قابل قبول است.

// DO Switch out whole styles when many properties differ - if Product A and Product B are two white labelled apps that provide different Themes.
val productBThemedButton = Style {
    shape(shapes.small)
    background(colors.brandSecondary)
    // other properties are fundamentally different
}

val productAThemedButton = Style {
    shape(shapes.large)
    background(colors.brand)
    // other properties are fundamentally different
}
DosDonts.kt