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

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

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

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

शब्दावली

शब्द परिभाषा
MaterialTheme यह कंपोज़ेबल फ़ंक्शन, Compose के यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट को थीम (कलर, टाइपोग्राफ़ी, शेप) उपलब्ध कराता है.
Shape यह एक Compose ऑब्जेक्ट है. इसका इस्तेमाल, MaterialTheme के लिए कस्टम कॉम्पोनेंट शेप तय करने के लिए किया जाता है.
Typography यह एक Compose ऑब्जेक्ट है. इसका इस्तेमाल MaterialTheme के लिए, कस्टम टेक्स्ट स्टाइल (फ़ॉन्ट फ़ैमिली, साइज़, मोटाई) तय करने के लिए किया जाता है.
Color यह एक 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 कोड में, Shape ऑब्जेक्ट को परिभाषित करें, ताकि एक्सएमएल शेप की परिभाषाओं को दोहराया जा सके.

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

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

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

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

    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 में तय किए गए कंपोज़ेबल के पैरामीटर के तौर पर या स्टाइल तय करके, लेयर वाले, फिर से इस्तेमाल किए जा सकने वाले कंपोज़ेबल वेरिएशन बनाकर.

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

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

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

XML Compose
Theme.MaterialComponents.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium Typography(bodyMedium = ...) में TextStyle(...) को तय किया गया है
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.MaterialComponents.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.MaterialComponents.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 containerColor, ComponentDefaults.ComponentColors() में है
android:textColor contentColor, ComponentDefaults.ComponentColors() में है
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 fontSize = X.sp, TextStyle में है

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

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

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