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

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

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

एक्सएमएल से Compose पर माइग्रेशन शुरू करने पर, थीमिंग को Material 3 Compose थीमिंग पर माइग्रेट करें.

शब्दावली

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

सीमाएं

माइग्रेट करने से पहले, इन सीमाओं के बारे में जान लें:

• यह गाइड, सिर्फ़ Material 3 पर माइग्रेट करने पर फ़ोकस करती है. Compose में, डिज़ाइन के अन्य सिस्टम से माइग्रेट करने के लिए, Material 2 या डिज़ाइन के कस्टम सिस्टम देखें.
• हमारा लक्ष्य, 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. इस Shapes ऑब्जेक्ट को अपने MaterialTheme में शामिल करें.

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

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

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

  2. इस Typography ऑब्जेक्ट को अपने MaterialTheme में शामिल करें.

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

Compose में रोल	एक्सएमएल में नाम
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" ... />
  • Compose: MyPrimaryButton(onClick = { ... })
• आम एट्रिब्यूट ग्रुप: अगर कोई स्टाइल, आम मॉडिफ़ायर (जैसे, पैडिंग + ऊंचाई) सेट करती है, तो उन्हें पढ़ने में आसान एक्सटेंशन प्रॉपर्टी या शेयर किए गए मॉडिफ़ायर वैरिएबल में एक्सट्रैक्ट करें.

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

एक्सएमएल	Compose
Theme.Material3.*	MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium	TextStyle(...) को Typography(bodyMedium = ...) में तय किया गया है
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	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 में नई मटीरियल थीम के लिए, सोर्स ऑफ़ ट्रुथ के तौर पर हमेशा ओरिजनल एक्सएमएल थीम की मौजूदा थीम वैल्यू का इस्तेमाल करें. ब्रैंड की पहचान को बनाए रखने और विज़ुअल रिग्रेशन से बचने के लिए, माइग्रेशन के दौरान थीम की नई वैल्यू कभी न बनाएं.

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