Widget'ları kullanmaya başlama

Ön koşullar ve kurulum

Başlamadan önce ortamınızın aşağıdaki koşulları karşıladığından emin olun.

Çalışma Zamanı Gereksinimleri

Wear Widget'ları için hedef cihazda com.google.android.wearable.protolayout.renderer APK'sının 1.6.1 veya sonraki bir sürümü gerekir.

Aşağıdaki yöntemlerden birini kullanarak oluşturucunun uyumlu bir sürümünü edinin:

  • Wear OS 7 emülatörü: Wear OS 7 emülatör görüntüsünü kullanın. 7'den düşük sürümler uygun değildir. Kurulum talimatları için Wear OS 7 emülatörünü kurma başlıklı makaleyi inceleyin.
  • Fiziksel Cihaz: Google Play Store'dan otomatik güncellemeler alan fiziksel bir Wear OS cihazı veya Google Play Store'da oturum açmış bir geliştirici cihazı kullanın.

Cihazınızda yüklü olan sürümü kontrol etmek için aşağıdaki komutu kullanın:

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

Gradle Yapılandırması

Wear Widget kitaplıkları Google Maven'da mevcuttur.

1. SDK sürümünü yapılandırma

compileSdk ve targetSdk değerlerinizin 37 veya daha yüksek bir değere ayarlandığından emin olun.

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

2. Bağımlılık Ekleme

Uygulamanızın build.gradle.kts dosyasına aşağıdaki bağımlılıkları ekleyin:

Modern

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

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19"
    implementation "androidx.wear.compose:compose-ui-tooling:1.6.2"
    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-alpha19")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha19")
    implementation("androidx.glance.wear:wear:1.0.0-alpha18")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha18")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha11")

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

Hello World widget'ı oluşturma

Wear widget'ı, GlanceWearWidgetService sınıfını genişleten bir hizmet ve GlanceWearWidget sınıfını genişleten bir widget sınıfından oluşur. Kullanıcı arayüzünü @RemoteComposable işlevlerini kullanarak tanımlarsınız.

Hizmeti tanımlama

Hizmet, sistemin bağlandığı giriş noktasıdır.

Widget'ınızı tanımlamak için GlanceWearWidgetService sınıfını genişleten bir hizmet oluşturun ve hizmeti uygun GlanceWearWidget sınıfıyla ilişkilendirmek üzere @AssociateWithGlanceWearWidget ile açıklama ekleyin.

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

Widget'ı tanımlama

Widget sınıfı, widget'ın verilerini ve düzenini sağlar.

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

İçeriği tanımlama

İçerik, Remote Compose bileşenleri kullanılarak oluşturulur.

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

Android Studio'da widget'ınızın önizlemesini yapma

androidx.glance.wear:wear-tooling-preview kullanarak widget düzenlerinizi doğrudan Android Studio'nun Tasarım panelinde önizleyebilirsiniz.

Önceden tanımlanmış önizleme paketleri

wear-tooling-preview kitaplığı, düzenlerinizi farklı kapsayıcı şekillerinde ve cihaz yapılandırmalarında test etmek için önceden tanımlanmış PreviewParameterProvider paketleri sağlar:

  • Kare-daire paketi (SquircleAllWidgetPreviewParams): Köşeleri yuvarlatılmış dikdörtgen kapsayıcılar.
  • Round Suite (RoundAllWidgetPreviewParams): Yuvarlak kapsayıcılar.
  • Dikdörtgen Paket (RectangularAllWidgetPreviewParams): Güvenli dolguya sahip, kırpılmamış dikdörtgen kapsayıcılar. Bu önizleme yapılandırmasıyla oluşturulan resimler, widget seçici tarafından kullanılan APK'ya yerleştirilmiş önizleme resimleri olarak kullanılmaya uygundur (bkz. Önizleme resmi öğeleri oluşturma).

Android Studio'da widget'ınızın önizlemesini görmek için @WearWidgetPreview simgesini kullanın:

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

Widget yapılandırma XML'sini oluşturma

Widget'ın özelliklerini ve desteklenen boyutlarını tanımlamak için yeni bir dosya res/xml/hello_widget_info.xml oluşturun. <wearwidget-provider> etiketinde desteklenen XML özelliklerinin tam referansı için WearWidgetProviderInfo dokümanlarına bakın.

<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>

Önizleme resim öğeleri oluşturma

<container> öğesinin previewImage özelliği, sistem widget seçicisinde gösterilen bir çizilebilir öğeye referans veriyor. Doğru sınırlara ve yoğunluğa sahip önizleme öğeleri oluşturmak için RectangularAllWidgetPreviewParams ile Android Studio önizlemelerini kullanın (bu, hem küçük hem de büyük kapsayıcılar için önizleme varyantları oluşturur) ve 320 DPI akıllı saat ekran yoğunluğu belirtin:

@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,
    )
}

Oluşturulan önizleme resimlerini ayıklamak için aşağıdaki adımları tamamlayın:

  1. Android Studio'da, önizleme composable'ı için Tasarım yüzeyini açın.
  2. Önizleme penceresinde, oluşturulan önizlemeyi sağ tıklayın veya önizleme araç çubuğunu kullanarak Resmi Kopyala'yı seçin ya da resmi kaydedin. Alternatif olarak, Compose önizlemelerini ayıklamak için CLI araçlarını veya otomatik komut dosyalarını kullanın.
  3. Küçük ve büyük resim dosyalarını uygulamanızın res/drawable-nodpi/ dizinine (ör. res/drawable-nodpi/widget_preview_small.png ve res/drawable-nodpi/widget_preview_large.png) kaydedin.

AndroidManifest.xml dosyasında kaydetme

Hizmeti, AndroidManifest.xml içinde gerekli amaç filtreleri ve meta verilerle kaydedin.

<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>

Derleme ve Dağıtım

Hizmetinizi ve widget'ınızı tanımladıktan sonra projenizi oluşturup bir cihaza veya emülatöre dağıtabilirsiniz.

Derleme ve yükleme

Projeyi oluşturun ve hata ayıklama APK'sını bağlı cihazınıza veya emülatörünüze yükleyin:

./gradlew :app:installDebug

Widget'ınızı ekleme ve önizleme

Uygulama yüklendikten sonra, widget'ı programatik olarak karusellere eklemek ve ekranda göstermek için adb simgesini kullanın.

Not: Wear widget'ları, hata ayıklama amacıyla temel döşeme altyapısını kullanır. Bu nedenle, adb komutları için add-tile ve show-tile işlemleri gerekir.

1. Widget'ı banda ekleme:

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

2. Widget'ı gösterme:

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

Widget içeriğini programatik olarak güncelleme

Uygulamanızın temel verileri değiştiğinde (ör. veri senkronizasyonu, push bildirimi veya kullanıcı işlemi alındığında) sistemin widget içeriğini yenilemesi için bildirim gönderin.

Widget'ınızın etkin tüm örnekleri için güncelleme isteğinde bulunmak üzere widget sınıfınızda triggerUpdateAll işlevini çağırın:

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

Tüm etkin örnekleri yenilemeden belirli bir widget örneğini güncellemek için hedef örnek kimliğiyle triggerUpdate işlevini çağırın.