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

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

रंगों को माइग्रेट करने के लिए, मटीरियल थीम बिल्डर टूल का इस्तेमाल किया जा सकता है.

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

शब्दावली

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

सीमाएं

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

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

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

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

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

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

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

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

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

मुख्य सिद्धांत: XML में, नाम वाले हेक्स कलर का इस्तेमाल किया जाता है. 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 ऑब्जेक्ट दें.

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

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