Compose में एक्सएमएल थीम को Material 3 में माइग्रेट करना

किसी मौजूदा ऐप्लिकेशन में Compose को शामिल करने पर, आपको अपनी मटीरियल एक्सएमएल थीम को माइग्रेट करना होगा, ताकि Compose कॉम्पोनेंट के लिए MaterialTheme का इस्तेमाल किया जा सके. इसका मतलब है कि आपके ऐप्लिकेशन की थीम के लिए, दो सोर्स होंगे: व्यू-आधारित थीम और Compose थीम. स्टाइलिंग में किए जाने वाले किसी भी बदलाव को कई जगहों पर लागू करना पड़ता है. जब आपका ऐप्लिकेशन पूरी तरह से Compose पर माइग्रेट हो जाए, तो एक्सएमएल थीमिंग को हटा दें.

रंगों को माइग्रेट करने के लिए, Material Theme Builder टूल का इस्तेमाल किया जा सकता है.

एक्सएमएल से Compose पर माइग्रेट करते समय, थीम को Material 3 Compose थीम पर माइग्रेट करें.

शब्दावली

शब्द परिभाषा
MaterialTheme यह एक कंपोज़ेबल फ़ंक्शन है, जो Compose यूज़र इंटरफ़ेस (यूआई) के कॉम्पोनेंट को थीम (रंग, टाइपोग्राफ़ी, शेप) उपलब्ध कराता है.
Shapes एक Compose ऑब्जेक्ट, जिसका इस्तेमाल MaterialTheme के लिए कस्टम कॉम्पोनेंट के आकार तय करने के लिए किया जाता है.
Typography यह एक Compose ऑब्जेक्ट है. इसका इस्तेमाल, MaterialTheme के लिए कस्टम टेक्स्ट स्टाइल (फ़ॉन्ट फ़ैमिली, साइज़, वेट) तय करने के लिए किया जाता है.
ColorScheme एक Compose ऑब्जेक्ट, जिसका इस्तेमाल MaterialTheme के लिए पसंद के मुताबिक कलर स्कीम तय करने के लिए किया जाता है.
एक्सएमएल थीम Android का थीमिंग सिस्टम, एक्सएमएल फ़ाइलों में तय किया जाता है. इसका इस्तेमाल व्यू सिस्टम करता है.

सीमाएं

माइग्रेट करने से पहले, इन बातों का ध्यान रखें:

  • इस गाइड में, सिर्फ़ Material 3 पर माइग्रेट करने के बारे में बताया गया है. अन्य डिज़ाइन सिस्टम से माइग्रेट करने के लिए, Material 2 या Compose में कस्टम डिज़ाइन सिस्टम देखें.
  • आखिर में, Compose पर पूरी तरह से माइग्रेट करना है, ताकि एक्सएमएल थीम को हटाया जा सके. इस गाइड में, माइग्रेट करने का तरीका बताया गया है. हालांकि, इसमें एक्सएमएल थीम को हटाने का तरीका नहीं बताया गया है.

पहला चरण: डिज़ाइन सिस्टम का आकलन करना

यह पहचान करना कि एक्सएमएल व्यू प्रोजेक्ट में किस डिज़ाइन सिस्टम का इस्तेमाल किया गया है. माइग्रेशन के पाथ और मौजूदा डिज़ाइन सिस्टम को Compose में Material 3 पर माइग्रेट करने के लिए ज़रूरी चरणों का विश्लेषण करना.

दूसरा चरण: थीम की सोर्स फ़ाइलों की पहचान करना

एक्सएमएल में ?attr/colorPrimary लिखें. Compose में, MaterialTheme.* की मदद से थीम की वैल्यू ऐक्सेस की जा सकती हैं:

थीम बनाने के लिए ज़रूरी सभी एक्सएमएल रिसॉर्स और फ़ाइलों की पहचान करें और उन्हें ढूंढें: हल्के और गहरे रंग की कलर स्कीम और क्वालिफ़ायर, थीम, आकार, डाइमेंशन, टाइपोग्राफ़ी, स्टाइल, और अन्य ज़रूरी फ़ाइलें.

स्ट्रिंग जैसे रिसॉर्स को पहले की तरह ही फिर से इस्तेमाल किया जा सकता है. इन्हें माइग्रेट करने की ज़रूरत नहीं होती.

तीसरा चरण: कलर माइग्रेट करना

मुख्य सिद्धांत: एक्सएमएल में, रंग के हेक्स कोड के नाम इस्तेमाल किए जाते हैं. Material 3 में सेमैंटिक रोल का इस्तेमाल किया जाता है. जैसे, primary, onPrimary, surface. रंगों को उनके हेक्स कोड के बजाय, उनके रोल के हिसाब से नाम दें.

उदाहरण:

एक्सएमएल कलर का नाम Material 3 की भूमिका
colorPrimary primary
colorPrimaryDark / colorPrimaryVariant primaryContainer या secondary
colorAccent secondary या tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

गहरे और हल्के रंग वाली कलर स्कीम को एक्सएमएल से Material 3 Compose में माइग्रेट करें.

चौथा चरण: कस्टम शेप और टाइपोग्राफ़ी को माइग्रेट करना

  • अगर आपका ऐप्लिकेशन कस्टम शेप का इस्तेमाल करता है, तो:

    1. अपने Compose कोड में, Shapes ऑब्जेक्ट तय करें, ताकि एक्सएमएल शेप की परिभाषाओं को दोहराया जा सके.

    2. अपने MaterialTheme को यह Shapes ऑब्जेक्ट दें.

      ज़्यादा जानकारी के लिए, आकार देखें.

  • अगर आपका ऐप्लिकेशन कस्टम टाइपोग्राफ़ी का इस्तेमाल करता है, तो:

    1. अपने Compose कोड में, Typography ऑब्जेक्ट को तय करें, ताकि एक्सएमएल टेक्स्ट स्टाइल और फ़ॉन्ट डेफ़िनिशन को दोहराया जा सके.

    2. अपने MaterialTheme को यह Typography ऑब्जेक्ट दें.

      ज़्यादा जानकारी के लिए, टाइपोग्राफ़ी देखें.

लिखने की भूमिका एक्सएमएल नेम
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

पांचवां चरण: स्टाइल (styles.xml) माइग्रेट करना

एक्सएमएल स्टाइल (styles.xml) सिस्टम, स्टाइल और लुक तय करता है:

  1. विंडो और डायलॉग के लिए विजेट, कॉम्पोनेंट, और थीम
  2. टाइपोग्राफ़ी
  3. थीम और ओवरले
  4. आकार

एक्सएमएल व्यू और कॉम्पोनेंट, कई एट्रिब्यूट को जोड़कर एक स्टाइल बनाते हैं. वे styles.xml से अपनी स्टाइल को दो अलग-अलग तरीकों से सेट करते हैं:

  1. एक्सएमएल व्यू में, "style="@style/..." को सीधे और साफ़ तौर पर सेट करना
  2. किसी कॉम्पोनेंट के लिए, स्टाइल को किसी बड़ी थीम (theme.xml) के हिस्से के तौर पर, इनडायरेक्ट और इंप्लिसिट तरीके से सेट करना

Compose में स्टाइल का कोई सीधा विकल्प नहीं है. इसके बजाय, स्टाइल को इस तरह पास किया जाता है: AppTheme में तय किए गए नए, एक्सपेरिमेंट के तौर पर उपलब्ध Styles API का इस्तेमाल करके, कंपोज़ेबल के लिए पैरामीटर या मॉडिफ़ायर के तौर पर या तय की गई स्टाइल के साथ लेयर वाले, फिर से इस्तेमाल किए जा सकने वाले कंपोज़ेबल वैरिएशन बनाकर.

स्टाइल और बेस कॉम्पोनेंट के हिसाब से, अलग-अलग @Composable फ़ंक्शन उपलब्ध कराएं. इससे कॉम्पोनेंट की स्टाइल और इस्तेमाल के उदाहरणों में अंतर पता चलता है.

  • पैटर्न: अगर कोई एक्सएमएल एलिमेंट, पसंद के मुताबिक स्टाइल का इस्तेमाल करता है (जैसे, style="@style/MyPrimaryButton"), तो स्टाइल को इनलाइन दोहराने की कोशिश न करें. इसके बजाय, कोई खास कंपोज़ेबल बनाने का सुझाव दें.
  • उदाहरण:
    • एक्सएमएल: <Button style="@style/MyPrimaryButton" ... />
    • लिखें: MyPrimaryButton(onClick = { ... })
  • सामान्य एट्रिब्यूट ग्रुप: अगर कोई स्टाइल, पैडिंग + ऊंचाई जैसे सामान्य मॉडिफ़ायर सेट करती है, तो उन्हें पढ़ने लायक एक्सटेंशन प्रॉपर्टी या शेयर किए गए मॉडिफ़ायर वैरिएबल में निकालें.

सामान्य उदाहरण

XML लिखें
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium Typography(bodyMedium = ...) में TextStyle(...) को तय किया गया
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint ComponentDefaults.ComponentColors() में containerColor
android:textColor ComponentDefaults.ComponentColors() में contentColor
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) या Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor + strokeWidth border = BorderStroke(width, color)
android:textSize TextStyle में fontSize = X.sp

छठा चरण: थीम के माइग्रेशन की पुष्टि करना

Compose में नई मटीरियल थीमिंग के लिए, ओरिजनल एक्सएमएल थीम की मौजूदा थीम वैल्यू का इस्तेमाल करें. माइग्रेशन के दौरान, कभी भी नई थीम वैल्यू न बनाएं. इससे ब्रैंड की एक जैसी पहचान बनाए रखने और विज़ुअल रिग्रेशन से बचने में मदद मिलती है.

पुष्टि करें कि Compose थीम की सभी नई वैल्यू, मौजूदा एक्सएमएल वैल्यू से मेल खाती हों. माइग्रेट की गई किसी भी वैल्यू को हार्डकोड न करें.