कंपोज़ेबल प्रीव्यू की मदद से, अपने यूज़र इंटरफ़ेस (यूआई) की झलक देखें

किसी कंपोज़ेबल को एक फ़ंक्शन के ज़रिए तय किया जाता है. साथ ही, इस पर @Composable एनोटेशन लगाया जाता है:

@Composable
fun SimpleComposable() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

इस कंपोज़ेबल की झलक देखने के लिए, एक और कंपोज़ेबल बनाएं. इस पर @Composable और @Preview एनोटेशन लगाएं. एनोटेशन वाला यह नया कंपोज़ेबल, अब आपके बनाए गए कंपोज़ेबल SimpleComposable को दिखाता है:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

@Preview एनोटेशन, Android Studio को बताता है कि इस कंपोज़ेबल को इस फ़ाइल के डिज़ाइन व्यू में दिखाया जाना चाहिए. बदलाव करने पर, कंपोज़ेबल की झलक में लाइव अपडेट दिखते हैं.

Android Studio, @Preview को जिस तरह से रेंडर करता है उसे अपनी पसंद के मुताबिक बनाने के लिए, कोड में मैन्युअल तरीके से पैरामीटर जोड़े जा सकते हैं. अलग-अलग प्रॉपर्टी वाले कंपोज़ेबल की झलक देखने के लिए, एक ही फ़ंक्शन में @Preview एनोटेशन को कई बार जोड़ा जा सकता है.

@Preview कंपोज़ेबल का इस्तेमाल करने का एक मुख्य फ़ायदा यह है कि Android Studio में एम्युलेटर पर निर्भर रहने की ज़रूरत नहीं पड़ती. एम्युलेटर को शुरू होने में लगने वाली ज़्यादा मेमोरी को, लुक ऐंड फ़ील में बड़े बदलावों के लिए सेव किया जा सकता है. साथ ही, @Preview की मदद से, कोड में छोटे-मोटे बदलाव आसानी से किए जा सकते हैं और उनकी जांच की जा सकती है.

@Preview एनोटेशन का सबसे असरदार तरीके से इस्तेमाल करने के लिए, पक्का करें कि आपने अपनी स्क्रीन को उस स्थिति के हिसाब से तय किया हो जो उसे इनपुट के तौर पर मिलती है. साथ ही, उन इवेंट के हिसाब से तय किया हो जो वह आउटपुट करती है.

अपना @Preview तय करना

Android Studio, कंपोज़ेबल की झलकें बढ़ाने के लिए कुछ सुविधाएं उपलब्ध कराता है. इन सुविधाओं की मदद से, कंपोज़ेबल की झलक के कंटेनर का डिज़ाइन बदला जा सकता है, उनसे इंटरैक्ट किया जा सकता है या उन्हें सीधे किसी एम्युलेटर या डिवाइस पर डिप्लॉय किया जा सकता है.

डाइमेंशन

डिफ़ॉल्ट रूप से, @Preview के डाइमेंशन, उसके कॉन्टेंट को रैप करने के लिए अपने-आप चुने जाते हैं. डाइमेंशन को मैन्युअल तरीके से सेट करने के लिए, heightDp और widthDp पैरामीटर जोड़ें. इन वैल्यू को पहले से ही dp के तौर पर इंटरप्रेट किया जाता है. इसलिए, आपको इनमें .dp जोड़ने की ज़रूरत नहीं है:

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}
AndroidStudioComposeSnippets.kt

डाइनैमिक रंग की झलक

अगर आपने अपने ऐप्लिकेशन में डाइनैमिक रंग की सुविधा चालू की है, तो वॉलपेपर बदलने के लिए wallpaper एट्रिब्यूट का इस्तेमाल करें. साथ ही, देखें कि अलग-अलग उपयोगकर्ताओं के चुने गए वॉलपेपर पर आपका यूज़र इंटरफ़ेस (यूआई) कैसा दिखता है. क्लास से मिलने वाली अलग-अलग वॉलपेपर थीम में से कोई थीम चुनें. offered by the Wallpaper इस सुविधा के लिए, Compose 1.4.0 या इसके बाद का वर्शन ज़रूरी है.

अलग-अलग डिवाइसों के साथ इस्तेमाल करना

Android Studio Flamingo में, झलक वाले एनोटेशन के device पैरामीटर में बदलाव करके, अलग-अलग डिवाइसों में अपने कंपोज़ेबल के लिए कॉन्फ़िगरेशन तय किए जा सकते हैं.

जब डिवाइस पैरामीटर में खाली स्ट्रिंग (@Preview(device = "")) होती है, तो + Space दबाकर, अपने-आप पूरा होने की सुविधा का इस्तेमाल किया जा सकता है.Ctrl इसके बाद, हर पैरामीटर की वैल्यू सेट की जा सकती है.

अपने-आप पूरा होने की सुविधा से, सूची में मौजूद किसी भी डिवाइस का विकल्प चुना जा सकता है. उदाहरण के लिए, @Preview(device = "id:pixel_4"). इसके अलावा, हर पैरामीटर की अलग-अलग वैल्यू सेट करने के लिए, spec:width=px,height=px,dpi=int… चुनकर, कस्टम डिवाइस की जानकारी डाली जा सकती है.

लागू करने के लिए, Enter दबाएं. रद्द करने के लिए, Esc दबाएं.

अगर कोई अमान्य वैल्यू सेट की जाती है, तो घोषणा के नीचे लाल रंग की लाइन दिखती है. साथ ही, इसे ठीक करने का विकल्प उपलब्ध हो सकता है. इसके लिए, Alt + Enter (macOS के लिए ⌥ + ⏎) > … से बदलें पर जाएं. जांच के दौरान, आपके इनपुट से मिलती-जुलती वैल्यू को ठीक करने की कोशिश की जाती है.

स्थान-भाषा

उपयोगकर्ताओं की अलग-अलग स्थान-भाषाओं की जांच करने के लिए, locale पैरामीटर जोड़ें:

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greeting))
}
AndroidStudioComposeSnippets.kt

बैकग्राउंड का रंग सेट करें

डिफ़ॉल्ट रूप से, आपका कंपोज़ेबल पारदर्शी बैकग्राउंड के साथ दिखता है. बैकग्राउंड जोड़ने के लिए, showBackground और backgroundColor पैरामीटर जोड़ें. ध्यान रखें कि backgroundColor एक ARGB Long है, न कि एक Color वैल्यू:

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

सिस्टम यूज़र इंटरफ़ेस (यूआई)

अगर आपको झलक में स्टेटस और ऐक्शन बार दिखाने हैं, तो showSystemUi पैरामीटर जोड़ें:

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

यूज़र इंटरफ़ेस (यूआई) मोड

uiMode पैरामीटर, Configuration.UI_* कॉन्स्टैंट में से कोई भी ले सकता है. इसकी मदद से, झलक के व्यवहार में बदलाव किया जा सकता है. उदाहरण के लिए, थीम की प्रतिक्रिया देखने के लिए, झलक को नाइट मोड पर सेट किया जा सकता है.

LocalInspectionMode

LocalInspectionMode CompositionLocal से यह देखा जा सकता है कि कंपोज़ेबल को झलक में रेंडर किया गया है या नहीं. यह झलक, जांच किए जा सकने वाले कॉम्पोनेंट में दिखती है . अगर कंपोज़िशन को झलक में रेंडर किया जाता है, तो LocalInspectionMode.current की वैल्यू true होती है. इस जानकारी से, झलक को अपनी पसंद के मुताबिक बनाया जा सकता है. उदाहरण के लिए, असली डेटा दिखाने के बजाय, झलक विंडो में प्लेसहोल्डर इमेज दिखाई जा सकती है.

इस तरह, सीमाओं से जुड़ी समस्याओं को भी हल किया जा सकता है. उदाहरण के लिए, नेटवर्क अनुरोध करने के बजाय, सैंपल डेटा दिखाना.

@Composable
fun GreetingScreen(name: String) {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}
AndroidStudioComposeSnippets.kt

अपने @Preview के साथ इंटरैक्ट करना

Android Studio, ऐसी सुविधाएं उपलब्ध कराता है जिनकी मदद से, तय की गई झलक के साथ इंटरैक्ट किया जा सकता है. इस इंटरैक्शन से, झलक के रनटाइम के व्यवहार को समझने में मदद मिलती है. साथ ही, झलक की मदद से यूज़र इंटरफ़ेस (यूआई) पर बेहतर तरीके से नेविगेट किया जा सकता है.

इंटरैक्टिव मोड

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

कोड नेविगेशन और कंपोज़ेबल की आउटलाइन

किसी झलक पर कर्सर घुमाकर, उसमें शामिल कंपोज़ेबल की आउटलाइन देखी जा सकती हैं. किसी कंपोज़ेबल की आउटलाइन पर क्लिक करने से, एडिटर व्यू ट्रिगर हो जाता है. इससे, उसकी डेफ़िनिशन पर नेविगेट किया जा सकता है.

झलक देखें

किसी एम्युलेटर या फ़िज़िकल डिवाइस पर, @Preview की झलक देखी जा सकती है. झलक को उसी प्रोजेक्ट ऐप्लिकेशन में एक नई Activity के तौर पर डिप्लॉय किया जाता है. इसलिए, यह एक ही कॉन्टेक्स्ट और अनुमतियां शेयर करती है. अगर अनुमति पहले ही दी जा चुकी है, तो अनुमति के लिए अनुरोध करने वाला बॉयलरप्लेट कोड लिखने की ज़रूरत नहीं होती.

`@Preview` एनोटेशन के बगल में या झलक के सबसे ऊपर मौजूद झलक देखें आइकॉन पर क्लिक करें. इसके बाद, Android Studio, कनेक्ट किए गए डिवाइस या एम्युलेटर पर `@Preview` को डिप्लॉय कर देता है.

@Preview रेंडर को कॉपी करना

रेंडर की गई हर झलक को, उस पर राइट क्लिक करके इमेज के तौर पर कॉपी किया जा सकता है.

एक ही @Preview एनोटेशन की कई झलकें

एक ही @Preview कंपोज़ेबल के कई वर्शन, अलग-अलग स्पेसिफ़िकेशन या कंपोज़ेबल को पास किए गए अलग-अलग पैरामीटर के साथ दिखाए जा सकते हैं. इस तरह, बॉयलरप्लेट कोड को कम किया जा सकता है. ऐसा कोड, जिसे आपको कंपोज़ेबल के अलग-अलग वर्शन के लिए लिखना पड़ता.

मल्टीप्रीव्यू टेंप्लेट

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ में, मल्टीप्रीव्यू एपीआई टेंप्लेट जोड़े गए हैं: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, और @PreviewDynamicColors. इनकी मदद से, एक ही एनोटेशन का इस्तेमाल करके, सामान्य स्थितियों में Compose यूज़र इंटरफ़ेस (यूआई) की झलक देखी जा सकती है.

कस्टम मल्टीप्रीव्यू एनोटेशन बनाना

मल्टीप्रीव्यू की मदद से, एक एनोटेशन क्लास तय की जा सकती है. इसमें अलग-अलग कॉन्फ़िगरेशन वाले कई @Preview एनोटेशन होते हैं. किसी कंपोज़ेबल फ़ंक्शन में यह एनोटेशन जोड़ने पर, सभी अलग-अलग झलकें अपने-आप रेंडर हो जाती हैं. उदाहरण के लिए, इस एनोटेशन का इस्तेमाल करके, एक साथ कई डिवाइस, फ़ॉन्ट साइज़ या थीम की झलक देखी जा सकती है. इसके लिए, हर कंपोज़ेबल के लिए उन डेफ़िनिशन को दोहराने की ज़रूरत नहीं होती.

सबसे पहले, अपनी पसंद के मुताबिक एनोटेशन क्लास बनाएं:

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews
AndroidStudioComposeSnippets.kt

झलक वाले कंपोज़ेबल के लिए, इस कस्टम एनोटेशन का इस्तेमाल किया जा सकता है:

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

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

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
AndroidStudioComposeSnippets.kt

मल्टीप्रीव्यू और सामान्य प्रीव्यू को मिलाकर इस्तेमाल करने की सुविधा से, बड़े प्रोजेक्ट की कई प्रॉपर्टी की ज़्यादा बेहतर तरीके से जांच की जा सकती है.

@Preview और बड़े डेटासेट

कई बार, कंपोज़ेबल की झलक में बड़ा डेटासेट पास करने की ज़रूरत पड़ती है. ऐसा करने के लिए, कंपोज़ेबल की झलक वाले फ़ंक्शन में सैंपल डेटा पास करें. ऐसा करने के लिए, @PreviewParameter एनोटेशन वाला पैरामीटर जोड़ें.

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

सैंपल डेटा उपलब्ध कराने के लिए, एक क्लास बनाएं. यह क्लास, PreviewParameterProvider को लागू करती है और सैंपल डेटा को क्रम के तौर पर दिखाती है.

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}
AndroidStudioComposeSnippets.kt

इससे, क्रम में मौजूद हर डेटा एलिमेंट के लिए एक झलक रेंडर होती है:

एक ही प्रोवाइडर क्लास का इस्तेमाल, कई झलक के लिए किया जा सकता है. ज़रूरत पड़ने पर, सीमा पैरामीटर सेट करके, झलक की संख्या सीमित करें.

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

@PreviewParameter का इस्तेमाल करने वाली झलकें, डिफ़ॉल्ट रूप से पैरामीटर इंडेक्स और प्रॉपर्टी के नाम (user 0, user 1, user 2 वगैरह) का इस्तेमाल करके दिखाई जाती हैं. इससे, उन्हें अलग-अलग पहचानना मुश्किल हो सकता है. झलक को बेहतर तरीके से समझने के लिए, PreviewParameterProvider में getDisplayName() को बदलकर, हर झलक के लिए कस्टम डिसप्ले नेम उपलब्ध कराए जा सकते हैं. इससे, डेटा के अलग-अलग वैरिएंट या यूज़र इंटरफ़ेस (यूआई) की स्थितियों के बीच अंतर करने में मदद मिलती है. उदाहरण के लिए, इनपुट डेटा के आधार पर झलक को लेबल किया जा सकता है:

class UserAgePreviewParameterProvider : PreviewParameterProvider<User> {
    // Using a List internally for efficient index-based access
    private val userList = listOf(
        User(name = "Elise", age = 30),
        User(name = "Frank", age = 31),
        User(name = "Julia", age = 40)
    )

    override val values = userList.asSequence()

    override fun getDisplayName(index: Int): String? {
        // Return null or an empty string to use the default index-based name
        val user = userList.getOrNull(index) ?: return null
        return "${user.name} - ${user.age}"
    }
}
AndroidStudioComposeSnippets.kt

एआई की मदद से झलक जनरेट करना

Android Studio में मौजूद एआई एजेंट, आपके कंपोज़ेबल के लिए Compose की झलकें अपने-आप जनरेट कर सकता है. किसी कंपोज़ेबल फ़ंक्शन पर राइट-क्लिक करें और एआई > [कंपोज़ेबल का नाम]के लिए झलक जनरेट करें को चुनें. एजेंट, आपके कंपोज़ेबल का विश्लेषण करके, सही पैरामीटर के साथ ज़रूरी @Preview बॉयलरप्लेट जनरेट करता है. इससे, यह पुष्टि करने में मदद मिलती है कि आपका यूज़र इंटरफ़ेस (यूआई) उम्मीद के मुताबिक रेंडर हो रहा है या नहीं.

एनोटेशन क्लास @Preview

Android Studio में, @Preview एनोटेशन पर 'ctrl या ⌘ + क्लिक' करके, पैरामीटर की पूरी सूची देखी जा सकती है. झलक को पसंद के मुताबिक बनाते समय, इन पैरामीटर को अडजस्ट किया जा सकता है.

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)
AndroidStudioComposeSnippets.kt

सीमाएं और सबसे सही तरीके

Android Studio, झलक के कोड को सीधे झलक वाले एरिया में एक्ज़ीक्यूट करता है. इसके लिए, एम्युलेटर या फ़िज़िकल डिवाइस चलाने की ज़रूरत नहीं होती, क्योंकि यह Android फ़्रेमवर्क के पोर्ट किए गए हिस्से का इस्तेमाल करता है. इसे Layoutlib कहा जाता है. Layoutlib , Android फ़्रेमवर्क का कस्टम वर्शन है. इसे Android डिवाइसों के बाहर चलाने के लिए डिज़ाइन किया गया है. इस लाइब्रेरी का मकसद, Android Studio में लेआउट की झलक दिखाना है. यह झलक, डिवाइसों पर रेंडरिंग से काफ़ी मिलती-जुलती होती है.

झलक की सीमाएं

Android Studio में झलकें जिस तरह से रेंडर की जाती हैं, वे हल्की होती हैं. साथ ही, उन्हें रेंडर करने के लिए, पूरे Android फ़्रेमवर्क की ज़रूरत नहीं होती. हालांकि, इसकी कुछ सीमाएं हैं:

• नेटवर्क ऐक्सेस नहीं है
• फ़ाइल ऐक्सेस नहीं है
• Context के कुछ एपीआई पूरी तरह से उपलब्ध नहीं हो सकते हैं

झलक और ViewModels

किसी कंपोज़ेबल में ViewModel का इस्तेमाल करने पर, झलक की सीमाएं होती हैं. झलक का सिस्टम, ViewModel को पास किए गए सभी पैरामीटर को नहीं बना सकता. जैसे, रिपॉज़िटरी, यूज़ केस, मैनेजर या इसी तरह के अन्य पैरामीटर. इसके अलावा, अगर आपका ViewModel डिपेंडेंसी इंजेक्शन में हिस्सा लेता है (जैसे कि Hilt के साथ), तो झलक का सिस्टम, पूरे डिपेंडेंसी ग्राफ़ को नहीं बना सकता ताकि ViewModel बनाया जा सके.

ViewModel के साथ किसी कंपोज़ेबल की झलक देखने की कोशिश करने पर, Android Studio उस कंपोज़ेबल को रेंडर करते समय गड़बड़ी दिखाता है:

अगर आपको ViewModel का इस्तेमाल करने वाले कंपोज़ेबल की झलक देखनी है, तो एक और कंपोज़ेबल बनाएं. इसमें, ViewModel से मिले पैरामीटर को कंपोज़ेबल के आर्ग्युमेंट के तौर पर पास करें. इस तरह, ViewModel का इस्तेमाल करने वाले कंपोज़ेबल की झलक देखने की ज़रूरत नहीं होती.

@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
  AuthorScreen(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Composable
fun AuthorScreen(
  name: NameLabel,
  posts: PostsList
) {
  // ...
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorScreen(
      name = NameLabel(name),
      posts = PostsList(posts)
  )
}

अन्य संसाधन

Android Studio, @Preview को आसानी से इस्तेमाल करने की सुविधा कैसे देता है, इस बारे में ज़्यादा जानने के लिए, Compose Tooling ब्लॉग देखें. साथ ही, टूलिंग से जुड़ी अन्य सलाह भी देखें.