टाइल के वर्शन

संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

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

• Jetpack टाइल से जुड़ी लाइब्रेरी: ये लाइब्रेरी (इनमें Wear टाइल और Wear ProtoLayout शामिल हैं) आपके ऐप्लिकेशन में एम्बेड होती हैं. साथ ही, डेवलपर के तौर पर आपके पास इनके वर्शन को कंट्रोल करने का विकल्प होता है. आपका ऐप्लिकेशन, सिस्टम के onTileRequest() कॉल के जवाब में, TileBuilder.Tile ऑब्जेक्ट (आपकी टाइल को दिखाने वाला डेटा स्ट्रक्चर) बनाने के लिए, इन लाइब्रेरी का इस्तेमाल करता है.
• ProtoLayout रेंडरर: यह सिस्टम कॉम्पोनेंट, डिसप्ले पर Tile ऑब्जेक्ट को रेंडर करने और उपयोगकर्ता इंटरैक्शन को मैनेज करने के लिए ज़िम्मेदार है. रेंडरर के वर्शन को ऐप्लिकेशन डेवलपर कंट्रोल नहीं करता. यह अलग-अलग डिवाइसों पर अलग-अलग हो सकता है. भले ही, उन डिवाइसों का हार्डवेयर एक जैसा हो.

आपके ऐप्लिकेशन के Jetpack Tiles लाइब्रेरी के वर्शन और उपयोगकर्ता के डिवाइस पर मौजूद ProtoLayout रेंडरर के वर्शन, दोनों के आधार पर टाइल का दिखना या काम करने का तरीका अलग-अलग हो सकता है. उदाहरण के लिए, हो सकता है कि एक डिवाइस पर रोटेशन की सुविधा काम करे या धड़कन की दर का डेटा दिखे, लेकिन दूसरे डिवाइस पर ऐसा न हो.

इस दस्तावेज़ में यह पक्का करने का तरीका बताया गया है कि आपका ऐप्लिकेशन, Tiles लाइब्रेरी और ProtoLayout रेंडरर के अलग-अलग वर्शन के साथ काम करता है. साथ ही, इसमें Jetpack लाइब्रेरी के नए वर्शन पर माइग्रेट करने का तरीका भी बताया गया है.

यह देखना कि यह सुविधा किन मॉडल पर काम करेगी

अलग-अलग डिवाइसों पर सही तरीके से काम करने वाली टाइल बनाने के लिए, आपको इन बातों का ध्यान रखना चाहिए.

रेंडरर के वर्शन का पता लगाना

• onTileRequest() तरीके में पास किए गए DeviceParameters ऑब्जेक्ट के getRendererSchemaVersion() तरीके का इस्तेमाल करें. यह तरीका, डिवाइस पर ProtoLayout रेंडरर के मेजर और माइनर वर्शन नंबर दिखाता है.
• इसके बाद, onTileRequest() लागू करने के लिए कंडीशनल लॉजिक का इस्तेमाल किया जा सकता है. इससे, टाइल के डिज़ाइन या व्यवहार को, रेंडरर के पता लगाए गए वर्शन के आधार पर अडजस्ट किया जा सकता है.
  • उदाहरण के लिए, अगर कोई खास ऐनिमेशन काम नहीं करता है, तो उसकी जगह पर स्टैटिक इमेज दिखाई जा सकती है.

@RequiresSchemaVersion एनोटेशन

• ProtoLayout के तरीकों पर मौजूद @RequiresSchemaVersion एनोटेशन से पता चलता है कि उस तरीके के काम करने के लिए, रेंडरर स्कीमा का कम से कम कौनसा वर्शन ज़रूरी है, जैसा कि दस्तावेज़ में बताया गया है (उदाहरण).
  • अगर किसी ऐसे तरीके को कॉल किया जाता है जिसके लिए डिवाइस पर उपलब्ध रेंडरर वर्शन से ज़्यादा वर्शन की ज़रूरत होती है, तो आपका ऐप्लिकेशन क्रैश नहीं होगा. हालांकि, इससे कॉन्टेंट न दिखने या सुविधा को अनदेखा किए जाने की समस्या हो सकती है.

उदाहरण

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

रेंडरर के अलग-अलग वर्शन के साथ टेस्ट करना

अपनी टाइल को रेंडरर के अलग-अलग वर्शन के साथ टेस्ट करने के लिए, उन्हें Wear OS एमुलेटर के अलग-अलग वर्शन पर डिप्लॉय करें. (फ़िज़िकल डिवाइसों पर, ProtoLayout रेंडरर के अपडेट, Play Store या सिस्टम अपडेट से डिलीवर किए जाते हैं. किसी खास रेंडरर वर्शन को इंस्टॉल करने के लिए, उसे ज़बरदस्ती नहीं किया जा सकता.)

Android Studio की टाइल की झलक देखने की सुविधा, 'Jetpack ProtoLayout' लाइब्रेरी में एम्बेड किए गए रेंडरर का इस्तेमाल करती है. आपका कोड इस लाइब्रेरी पर निर्भर करता है. इसलिए, टाइल की जांच करते समय, 'Jetpack' लाइब्रेरी के अलग-अलग वर्शन का इस्तेमाल किया जा सकता है.

Tiles 1.5 / ProtoLayout 1.3 (Material 3 Expressive) पर माइग्रेट करना

नई सुविधाओं का फ़ायदा पाने के लिए, अपनी Jetpack टाइल लाइब्रेरी अपडेट करें. इनमें यूज़र इंटरफ़ेस (यूआई) में किए गए बदलाव भी शामिल हैं, ताकि आपकी टाइल सिस्टम के साथ आसानी से इंटिग्रेट हो सकें.

Jetpack Tiles 1.5 और Jetpack ProtoLayout 1.3 में कई अहम सुधार और बदलाव किए गए हैं. इनमें शामिल हैं:

• यूज़र इंटरफ़ेस (यूआई) के बारे में बताने के लिए, Compose जैसा एपीआई.
• Material 3 एक्सप्रेशन कॉम्पोनेंट, जिनमें सबसे नीचे मौजूद ऐज बटन और बेहतर विज़ुअल के लिए सहायता शामिल है: Lottie ऐनिमेशन, ज़्यादा ग्रेडिएंट टाइप, और नई आर्क लाइन स्टाइल. - ध्यान दें: इनमें से कुछ सुविधाओं का इस्तेमाल, नए एपीआई पर माइग्रेट किए बिना भी किया जा सकता है.

सुझाव

• एक साथ सभी टाइल माइग्रेट करें. अपने ऐप्लिकेशन में टाइल के अलग-अलग वर्शन इस्तेमाल करने से बचें. Material 3 कॉम्पोनेंट, एक अलग आर्टफ़ैक्ट (androidx.wear.protolayout:protolayout-material3) में मौजूद होते हैं. इसलिए, तकनीकी तौर पर एक ही ऐप्लिकेशन में M2.5 और M3, दोनों टाइल का इस्तेमाल किया जा सकता है. हालांकि, हमारा सुझाव है कि जब तक ज़रूरी न हो, तब तक ऐसा न करें. उदाहरण के लिए, अगर आपके ऐप्लिकेशन में बड़ी संख्या में टाइल हैं और उन्हें एक साथ माइग्रेट नहीं किया जा सकता.
• टाइल के यूज़र एक्सपीरियंस से जुड़े दिशा-निर्देशों का पालन करें. टाइल की स्ट्रक्चर्ड और टेंप्लेट वाली प्रकृति को ध्यान में रखते हुए, मौजूदा सैंपल में मौजूद डिज़ाइन का इस्तेमाल, अपने डिज़ाइन के लिए शुरुआती बिंदु के तौर पर करें.
• अलग-अलग स्क्रीन और फ़ॉन्ट साइज़ पर टेस्ट करें. टाइल में अक्सर ज़्यादा जानकारी होती है. इससे टेक्स्ट, खास तौर पर बटन पर होने पर, ओवरफ़्लो और क्लिपिंग की समस्या हो सकती है. इसे कम करने के लिए, पहले से बने कॉम्पोनेंट का इस्तेमाल करें और ज़्यादा कस्टमाइज़ेशन से बचें. Android Studio की टाइल की झलक दिखाने वाली सुविधा का इस्तेमाल करके, कई असल डिवाइसों पर जांच करें.

माइग्रेशन की प्रोसेस

डिपेंडेंसी अपडेट करना

सबसे पहले, अपनी build.gradle.kts फ़ाइल अपडेट करें. वर्शन अपडेट करें और protolayout-material डिपेंडेंसी को protolayout-material3 में बदलें, जैसा कि यहां दिखाया गया है:

// In build.gradle.kts

//val tilesVersion = "1.4.1"
//val protoLayoutVersion = "1.2.1"

// Use these versions for M3.
val tilesVersion = "1.5.0-rc01"
val protoLayoutVersion = "1.3.0-rc01"

 dependencies {
     // Use to implement support for wear tiles
     implementation("androidx.wear.tiles:tiles:$tilesVersion")

     // Use to utilize standard components and layouts in your tiles
     implementation("androidx.wear.protolayout:protolayout:$protoLayoutVersion")

     // Use to utilize components and layouts with Material Design in your tiles
     // implementation("androidx.wear.protolayout:protolayout-material:$protoLayoutVersion")
     implementation("androidx.wear.protolayout:protolayout-material3:$protoLayoutVersion")

     // Use to include dynamic expressions in your tiles
     implementation("androidx.wear.protolayout:protolayout-expression:$protoLayoutVersion")

     // Use to preview wear tiles in your own app
     debugImplementation("androidx.wear.tiles:tiles-renderer:$tilesVersion")

     // Use to fetch tiles from a tile provider in your tests
     testImplementation("androidx.wear.tiles:tiles-testing:$tilesVersion")
 }

TileService में काफ़ी बदलाव नहीं हुआ है

इस माइग्रेशन में हुए मुख्य बदलावों का असर यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट पर पड़ता है. इसलिए, TileService को लागू करने के लिए, संसाधन लोड करने के किसी भी तरीके में कम से कम बदलाव करने होंगे या कोई बदलाव नहीं करना पड़ेगा.

टाइल गतिविधि को ट्रैक करने से जुड़ा मुख्य अपवाद: अगर आपका ऐप्लिकेशन onTileEnterEvent() या onTileLeaveEvent() का इस्तेमाल करता है, तो आपको onRecentInteractionEventsAsync() पर माइग्रेट करना चाहिए. एपीआई 36 से, इन इवेंट को एक साथ भेजा जाएगा.

लेआउट जनरेट करने वाले कोड में बदलाव करना

ProtoLayout 1.2 (M2.5) में, onTileRequest() तरीका TileBuilders.Tile दिखाता है. इस ऑब्जेक्ट में कई एलिमेंट शामिल थे. इनमें TimelineBuilders.Timeline भी शामिल था. इसमें टाइल के यूज़र इंटरफ़ेस (यूआई) के बारे में बताने वाला LayoutElement भी शामिल था.

ProtoLayout 1.3 (M3) में, डेटा का पूरा स्ट्रक्चर और फ़्लो नहीं बदला है. हालांकि, LayoutElement को अब Compose से प्रेरित तरीके का इस्तेमाल करके बनाया गया है. यह तरीका, तय किए गए स्लॉट पर आधारित लेआउट के साथ काम करता है. ये स्लॉट, ऊपर से नीचे के क्रम में ये हैं: titleSlot (आम तौर पर मुख्य टाइटल या हेडर के लिए), mainSlot (मुख्य कॉन्टेंट के लिए), और bottomSlot (आम तौर पर ऐक्शन के लिए, जैसे कि किनारे पर बटन या कम शब्दों में दी गई जानकारी). यह लेआउट, primaryLayout() फ़ंक्शन से बनाया जाता है.

लेआउट M2.5 और M3 लेआउट फ़ंक्शन की तुलना

fun myLayout(
    context: Context,
    deviceConfiguration: DeviceParametersBuilders.DeviceParameters
) =
    PrimaryLayout.Builder(deviceConfiguration)
        .setResponsiveContentInsetEnabled(true)
        .setContent(
            Text.Builder(context, "Hello World!")
                .setTypography(Typography.TYPOGRAPHY_BODY1)
                .setColor(argb(0xFFFFFFFF.toInt()))
                .build()
        )
        .build()

fun myLayout(
    context: Context,
    deviceConfiguration: DeviceParametersBuilders.DeviceParameters,
) =
    materialScope(context, deviceConfiguration) {
        primaryLayout(mainSlot = { text("Hello, World!".layoutString) })
    }

मुख्य अंतरों को हाइलाइट करने के लिए:

1. बिल्डर को हटाना. Material3 के यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट के लिए, पारंपरिक बिल्डर पैटर्न को ज़्यादा एलान वाले और Compose से प्रेरित सिंटैक्स से बदल दिया गया है. (स्ट्रिंग/रंग/बदलाव करने वाले टूल जैसे नॉन-यूआई कॉम्पोनेंट को भी नए Kotlin wrapper मिलते हैं.)
2. स्टैंडर्डाइज़ किए गए शुरुआती और लेआउट फ़ंक्शन. M3 लेआउट, स्टैंडर्ड शुरू करने और स्ट्रक्चर फ़ंक्शन पर निर्भर करते हैं: materialScope() और primaryLayout(). ये ज़रूरी फ़ंक्शन, M3 एनवायरमेंट (materialScope के ज़रिए थीमिंग, कॉम्पोनेंट का दायरा) को शुरू करते हैं और primaryLayout के ज़रिए मुख्य स्लॉट-आधारित लेआउट तय करते हैं. हर लेआउट के लिए, दोनों को एक बार कॉल किया जाना चाहिए.

थीम बनाई जा रही है

रंग

Material 3 Expressive की सबसे खास सुविधा "डाइनैमिक थीम" है. इस सुविधा को चालू करने पर, डिफ़ॉल्ट रूप से चालू रहने वाली टाइल, सिस्टम की दी गई थीम में दिखेंगी. हालांकि, यह सुविधा उपयोगकर्ता के डिवाइस और कॉन्फ़िगरेशन के हिसाब से उपलब्ध होती है.

M3 में एक और बदलाव यह है कि रंग के टोकन की संख्या बढ़ाई गई है. अब इनकी संख्या चार से बढ़कर 29 हो गई है. नए कलर टोकन, ColorScheme क्लास में देखे जा सकते हैं.

टाइपोग्राफ़ी

M2.5 की तरह ही, M3 भी फ़ॉन्ट साइज़ के लिए पहले से तय किए गए कॉन्स्टेंट पर काफ़ी निर्भर करता है. इसलिए, फ़ॉन्ट साइज़ को सीधे तौर पर तय करने का सुझाव नहीं दिया जाता. ये कॉन्स्टेंट, Typography क्लास में मौजूद होते हैं. साथ ही, ये ज़्यादा बेहतर विकल्पों की एक छोटी सी रेंज उपलब्ध कराते हैं.

पूरी जानकारी के लिए, टाइपोग्राफ़ी से जुड़ा दस्तावेज़ देखें.

आकार

ज़्यादातर M3 कॉम्पोनेंट, आकार और रंग के डाइमेंशन के हिसाब से अलग-अलग हो सकते हैं.

full आकार वाला textButton (mainSlot में):

आकार small वाला वही टेक्स्ट बटन:

Components

M3 कॉम्पोनेंट, M2.5 के मुकाबले ज़्यादा फ़्लेक्सिबल और कॉन्फ़िगर किए जा सकने वाले होते हैं. M2.5 में अलग-अलग विज़ुअल के लिए अक्सर अलग-अलग कॉम्पोनेंट की ज़रूरत होती है, जबकि M3 में अक्सर सामान्य और ज़्यादा कॉन्फ़िगर किए जा सकने वाले "बेस" कॉम्पोनेंट का इस्तेमाल किया जाता है. इसमें डिफ़ॉल्ट तौर पर अच्छे विकल्प होते हैं.

यह सिद्धांत "रूट" लेआउट पर लागू होता है. M2.5 में, यह PrimaryLayout या EdgeContentLayout था. M3 में, एक टॉप-लेवल MaterialScope सेट अप होने के बाद, primaryLayout() फ़ंक्शन को कॉल किया जाता है. यह सीधे रूट लेआउट दिखाता है. इसके लिए, किसी बिल्डर की ज़रूरत नहीं होती. साथ ही, यह कई "स्लॉट" के लिए LayoutElements को स्वीकार करता है, जैसे कि titleSlot, mainSlot, और bottomSlot. इन स्लॉट में यूज़र इंटरफ़ेस (यूआई) के कॉम्पोनेंट डाले जा सकते हैं. जैसे, text(), button() या card() से मिले कॉम्पोनेंट या लेआउट स्ट्रक्चर. जैसे, LayoutElementBuilders से मिले Row या Column.

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

मॉडिफ़ायर

M3 में, Modifiers, Compose के ज़्यादा मिलते-जुलते हैं. इनका इस्तेमाल, किसी कॉम्पोनेंट को सजाने या बेहतर बनाने के लिए किया जाता है. इस बदलाव से, सही इंटरनल टाइप अपने-आप बनने की वजह से, बोइलरप्लेट कम हो सकता है. (यह बदलाव, M3 यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट के इस्तेमाल से अलग है. अगर ज़रूरी हो, तो M3 यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट के साथ ProtoLayout 1.2 के बिल्डर-स्टाइल मॉडिफ़ायर का इस्तेमाल किया जा सकता है. इसके अलावा, ProtoLayout 1.2 के साथ M3 यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट का इस्तेमाल भी किया जा सकता है.)

// A Builder-style modifier to set the opacity of an element to 0.5
fun myModifier(): ModifiersBuilders.Modifiers =
    ModifiersBuilders.Modifiers.Builder()
        .setOpacity(TypeBuilders.FloatProp.Builder(0.5F).build())
        .build()

// The equivalent Compose-like modifier is much simpler
fun myModifier(): LayoutModifier = LayoutModifier.opacity(0.5F)

एपीआई के किसी भी स्टाइल का इस्तेमाल करके, मॉडिफ़ायर बनाए जा सकते हैं. साथ ही, LayoutModifier को ModifiersBuilders.Modifier में बदलने के लिए, toProtoLayoutModifiers() एक्सटेंशन फ़ंक्शन का भी इस्तेमाल किया जा सकता है.

हेल्पर फ़ंक्शन

ProtoLayout 1.3 में, Compose से प्रेरित एपीआई का इस्तेमाल करके कई यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट दिखाए जा सकते हैं. हालांकि, LayoutElementBuilders के लाइन और कॉलम जैसे बुनियादी लेआउट एलिमेंट के लिए, अब भी बिल्डर पैटर्न का इस्तेमाल किया जाता है. स्टाइल में इस अंतर को दूर करने और नए M3 कॉम्पोनेंट एपीआई के साथ एक जैसी सुविधाएं देने के लिए, हेल्पर फ़ंक्शन का इस्तेमाल करें.

primaryLayout(
    mainSlot = {
        LayoutElementBuilders.Column.Builder()
            .setWidth(expand())
            .setHeight(expand())
            .addContent(text("A".layoutString))
            .addContent(text("B".layoutString))
            .addContent(text("C".layoutString))
            .build()
    }
)

// Function literal with receiver helper function
fun column(builder: Column.Builder.() -> Unit) =
    Column.Builder().apply(builder).build()

primaryLayout(
    mainSlot = {
        column {
            setWidth(expand())
            setHeight(expand())
            addContent(text("A".layoutString))
            addContent(text("B".layoutString))
            addContent(text("C".layoutString))
        }
    }
)

Tiles 1.2 / ProtoLayout 1.0 पर माइग्रेट करना

वर्शन 1.2 के हिसाब से, ज़्यादातर टाइल लेआउट एपीआई, androidx.wear.protolayout नेमस्पेस में हैं. नए एपीआई का इस्तेमाल करने के लिए, अपने कोड में माइग्रेशन के लिए यह तरीका अपनाएं.

डिपेंडेंसी अपडेट करना

अपने ऐप्लिकेशन मॉड्यूल की बिल्ड फ़ाइल में, ये बदलाव करें:

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

नेमस्पेस अपडेट करना

अपने ऐप्लिकेशन की Kotlin और Java-आधारित कोड फ़ाइलों में, ये अपडेट करें. इसके अलावा, नेमस्पेस का नाम बदलने वाली स्क्रिप्ट को भी चलाया जा सकता है.

1. सभी androidx.wear.tiles.material.* इंपोर्ट को androidx.wear.protolayout.material.* से बदलें. androidx.wear.tiles.material.layouts लाइब्रेरी के लिए भी यह चरण पूरा करें.

2. ज़्यादातर अन्य androidx.wear.tiles.* इंपोर्ट को androidx.wear.protolayout.* से बदलें.

   androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders, और androidx.wear.tiles.TileService के लिए इंपोर्ट पहले जैसे ही रहेंगे.

3. TileService और TileBuilder क्लास के कुछ ऐसे तरीकों के नाम बदलें जो अब काम नहीं करते:

   1. TileBuilders: getTimeline() से getTileTimeline() और setTimeline() से setTileTimeline()
   2. TileService: onResourcesRequest() से onTileResourcesRequest() तक
   3. RequestBuilders.TileRequest: getDeviceParameters() से getDeviceConfiguration(), setDeviceParameters() से setDeviceConfiguration(), getState() से getCurrentState(), और setState() से setCurrentState()