विजेट का इस्तेमाल शुरू करना

ज़रूरी शर्तें और सेटअप

शुरू करने से पहले, पक्का करें कि आपका एनवायरमेंट इन ज़रूरी शर्तों को पूरा करता हो.

रनटाइम की ज़रूरी शर्तें

Wear विजेट के लिए, टारगेट डिवाइस पर com.google.android.wearable.protolayout.renderer APK का वर्शन 1.6.1 या इसके बाद का वर्शन होना चाहिए.

इनमें से किसी एक तरीके से, रेंडरर का ऐसा वर्शन पाएं जो आपके डिवाइस के साथ काम करता हो:

  • Wear OS 7 एम्युलेटर: Wear OS 7 एम्युलेटर की इमेज का इस्तेमाल करें. 7 से कम वर्शन वाले डिवाइसों पर यह सुविधा काम नहीं करती. सेटअप करने के निर्देशों के लिए, Wear OS 7 एम्युलेटर सेट अप करना लेख पढ़ें.
  • फ़िज़िकल डिवाइस: किसी ऐसे फ़िज़िकल Wear OS डिवाइस का इस्तेमाल करें जिसे Google Play Store से अपने-आप अपडेट मिलते हों. इसके अलावा, किसी ऐसे डेवलपर डिवाइस का इस्तेमाल करें जिसमें Google Play Store में साइन इन किया गया हो.

आपके डिवाइस पर कौनसा वर्शन इंस्टॉल है, यह देखने के लिए इस कमांड का इस्तेमाल करें:

adb shell dumpsys package com.google.android.wearable.protolayout.renderer | \
  grep -m 1 versionName | \
  awk -F= '{print $2}'

Gradle कॉन्फ़िगरेशन

Wear विजेट लाइब्रेरी, Google Maven पर उपलब्ध हैं.

1. SDK टूल का वर्शन कॉन्फ़िगर करें

पक्का करें कि आपके compileSdk और targetSdk, 37 या इसके बाद के वर्शन पर सेट हों.

android {
    compileSdk = 37
    // ...
    defaultConfig {
        targetSdk = 37
        // ...
    }
}

2. डिपेंडेंसी जोड़ें

अपने ऐप्लिकेशन की build.gradle.kts फ़ाइल में ये डिपेंडेंसी शामिल करें:

Groovy

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation "androidx.compose.remote:remote-creation-compose:1.0.0-alpha21"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha21"
    implementation "androidx.glance.wear:wear:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha20"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha13"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha21"
    implementation "androidx.wear.compose:compose-ui-tooling:1.7.1"
    implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2"
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"
}

Kotlin

dependencies {
    // Core Wear Widget and Remote Compose libraries
    implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha21")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha21")
    implementation("androidx.glance.wear:wear:1.0.0-alpha20")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha20")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha13")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha21")
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.1")
    implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2")
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")
}

'नमस्ते' विजेट बनाना

Wear विजेट में, GlanceWearWidgetService को एक्सटेंड करने वाली सेवा और GlanceWearWidget को एक्सटेंड करने वाली विजेट क्लास शामिल होती है. यूज़र इंटरफ़ेस (यूआई) को @RemoteComposable फ़ंक्शन का इस्तेमाल करके तय किया जाता है.

सेवा के बारे में जानकारी देना

सेवा, वह एंट्री पॉइंट है जिससे सिस्टम बाइंड होता है.

विजेट तय करने के लिए, ऐसी सेवा बनाएं जो GlanceWearWidgetService को एक्सटेंड करती हो. साथ ही, सेवा को सही GlanceWearWidget क्लास से जोड़ने के लिए, उसे @AssociateWithGlanceWearWidget के साथ एनोटेट करें.

@AssociateWithGlanceWearWidget(HelloWidget::class)
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}

विजेट को तय करना

विजेट क्लास, विजेट के लिए डेटा और लेआउट उपलब्ध कराती है.

class HelloWidget : GlanceWearWidget() {
    override suspend fun provideWidgetData(
        context: Context,
        params: WearWidgetParams,
    ): WearWidgetData {
        return WearWidgetDocument(
            background = WearWidgetBrush.color(Color.Blue.rc),
        ) {
            HelloWidgetContent()
        }
    }
}

कॉन्टेंट के बारे में जानकारी देना

कॉन्टेंट को रिमोट कंपोज़ कॉम्पोनेंट का इस्तेमाल करके बनाया गया हो.

@RemoteComposable
@Composable
fun HelloWidgetContent() {
    RemoteBox(
        modifier = RemoteModifier.fillMaxSize(),
        contentAlignment = RemoteAlignment.Center,
    ) {
        RemoteText(
            text = "Hello World".rs,
            color = Color.White.rc,
        )
    }
}

Android Studio में अपने विजेट की झलक देखना

androidx.glance.wear:wear-tooling-preview का इस्तेमाल करके, Android Studio के डिज़ाइन पैनल में सीधे तौर पर अपने विजेट के लेआउट की झलक देखी जा सकती है.

पहले से तय किए गए झलक वाले सुइट

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

  • स्क्विर्कल सुइट (SquircleAllWidgetPreviewParams): गोल कोनों वाले रेक्टैंगल कंटेनर.
  • राउंड सुइट (RoundAllWidgetPreviewParams): कैप्सूल के आकार वाले कंटेनर.
  • आयताकार सुइट (RectangularAllWidgetPreviewParams): बिना काटे गए आयताकार कंटेनर, जिनमें सुरक्षित पैडिंग होती है. प्रीव्यू टूल के इस कॉन्फ़िगरेशन से जनरेट की गई इमेज, APK में एम्बेड की गई इमेज की झलक के तौर पर इस्तेमाल की जा सकती हैं. इन इमेज का इस्तेमाल, विजेट पिकर करता है. इस बारे में ज़्यादा जानने के लिए, इमेज की झलक वाली ऐसेट जनरेट करना लेख पढ़ें.

Android Studio में अपने विजेट की झलक देखने के लिए, @WearWidgetPreview का इस्तेमाल करें:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}

विजेट कॉन्फ़िगरेशन की एक्सएमएल फ़ाइल बनाना

विजेट की प्रॉपर्टी और उसके लिए इस्तेमाल किए जा सकने वाले साइज़ तय करने के लिए, एक नई फ़ाइल res/xml/hello_widget_info.xml बनाएं. <wearwidget-provider> टैग में इस्तेमाल किए जा सकने वाले एक्सएमएल एट्रिब्यूट की पूरी जानकारी के लिए, WearWidgetProviderInfo दस्तावेज़ देखें.

<wearwidget-provider
    description="@string/hello_widget_description"
    icon="@mipmap/ic_launcher"
    label="@string/hello_widget_label"
    preferredType="SMALL">

    <container
        type="SMALL"
        previewImage="@drawable/widget_preview_small" />
    <container
        type="LARGE"
        previewImage="@drawable/widget_preview_large" />
</wearwidget-provider>

झलक दिखाने वाली इमेज ऐसेट जनरेट करना

<container> एलिमेंट का previewImage एट्रिब्यूट, सिस्टम विजेट पिकर में दिखाई गई ड्रॉएबल ऐसेट के बारे में बताता है. सही बाउंड और डेंसिटी वाली झलक दिखाने वाली ऐसेट जनरेट करने के लिए, RectangularAllWidgetPreviewParams के साथ Android Studio की झलक दिखाने वाली सुविधा का इस्तेमाल करें. इससे छोटे और बड़े, दोनों कंटेनर के लिए झलक दिखाने वाले वैरिएंट जनरेट होते हैं. साथ ही, स्मार्टवॉच के डिसप्ले की डेंसिटी 320 डीपीआई तय करें:

@Preview(
    name = "Widget Preview Asset",
    device = "spec:width=1000dp,height=1000dp,dpi=320",
)
@Composable
fun HelloWidgetCatalogPreview(
    @PreviewParameter(RectangularAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}

रेंडर की गई झलक वाली इमेज निकालने के लिए, यह तरीका अपनाएं:

  1. Android Studio में, झलक दिखाने वाले कंपोज़ेबल के लिए डिज़ाइन सरफ़ेस खोलें.
  2. झलक दिखाने वाली विंडो में, रेंडर की गई झलक पर राइट क्लिक करें या झलक दिखाने वाले टूलबार का इस्तेमाल करके, इमेज कॉपी करें को चुनें या इमेज सेव करें. इसके अलावा, Compose की झलक देखने के लिए, सीएलआई टूल या ऑटोमेटेड स्क्रिप्ट का इस्तेमाल करें.
  3. छोटी और बड़ी इमेज फ़ाइलों को अपने ऐप्लिकेशन की res/drawable-nodpi/ डायरेक्ट्री में सेव करें, जैसे कि res/drawable-nodpi/widget_preview_small.png और res/drawable-nodpi/widget_preview_large.png.

AndroidManifest.xml में रजिस्टर करना

ज़रूरी इंटेंट फ़िल्टर और मेटाडेटा के साथ, सेवा को अपने AndroidManifest.xml में रजिस्टर करें.

<service
    android:name=".snippets.widget.HelloWidgetService"
    android:exported="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/hello_widget_label"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">

    <intent-filter>
        <action android:name="androidx.glance.wear.action.BIND_WIDGET_PROVIDER" />
        <!-- If you already have a Tile, omit the following line. -->
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data
        android:name="androidx.glance.wear.widget.provider"
        android:resource="@xml/hello_widget_info" />

    <meta-data
        android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>

बिल्ड और डिप्लॉय करना

अपनी सेवा और विजेट तय करने के बाद, अपना प्रोजेक्ट बनाया जा सकता है और उसे किसी डिवाइस या एम्युलेटर पर डिप्लॉय किया जा सकता है.

बनाएं और इंस्टॉल करें

प्रोजेक्ट बनाएं और कनेक्ट किए गए डिवाइस या एम्युलेटर पर डीबग APK इंस्टॉल करें:

./gradlew :app:installDebug

विजेट जोड़ना और उसकी झलक देखना

ऐप्लिकेशन इंस्टॉल होने के बाद, प्रोग्राम के हिसाब से विजेट को कैरसेल में जोड़ने और उसे स्क्रीन पर दिखाने के लिए, adb का इस्तेमाल करें.

ध्यान दें: Wear विजेट, डीबग करने के लिए टाइल के बुनियादी इन्फ़्रास्ट्रक्चर का इस्तेमाल करते हैं. इस वजह से, adb कमांड के लिए add-tile और show-tile ऑपरेशन ज़रूरी हैं.

1. कैरसेल में विजेट जोड़ना:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SURFACE \
  --es operation add-tile \
  --ecn component <your_package_name>/.HelloWidgetService

2. विजेट दिखाएं:

adb shell am broadcast \
  -a com.google.android.wearable.app.DEBUG_SYSUI \
  --es operation show-tile \
  --ei index 0

प्रोग्राम के हिसाब से विजेट का कॉन्टेंट अपडेट करना

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

अपने विजेट के सभी चालू इंस्टेंस के लिए अपडेट का अनुरोध करने के लिए, अपनी विजेट क्लास पर triggerUpdateAll को कॉल करें:

// Request a content update for all active HelloWidget instances
HelloWidget().triggerUpdateAll(context)

सभी चालू इंस्टेंस को रीफ़्रेश किए बिना किसी खास विजेट इंस्टेंस को अपडेट करने के लिए, टारगेट इंस्टेंस आईडी के साथ triggerUpdate को कॉल करें.