Widget'ları kullanmaya başlama

Ön koşullar ve kurulum

Başlamadan önce ortamınızın aşağıdaki gereksinimleri 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ü ayarlama 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 hangi sürümün yüklü olduğunu 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-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")
}

Hello World Widget'ı Oluşturma

Wear widget'ı, GlanceWearWidgetService sınıfını genişleten bir hizmetten 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 için @AssociateWithGlanceWearWidget ile ek 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ı önizleme

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ığı, farklı kapsayıcı şekilleri ve cihaz yapılandırmalarında düzenlerinizi test etmek için önceden tanımlanmış PreviewParameterProvider paketleri sunar:

  • Squircle Suite (SquircleAllWidgetPreviewParams): Köşeleri yuvarlatılmış dikdörtgen kapsayıcılar.
  • Round Suite (RoundAllWidgetPreviewParams): Hap şeklinde kapsayıcılar.
  • Dikdörtgen Suite (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 (Önizleme resmi öğeleri oluşturma bölümüne bakın).

Android Studio'da widget'ınızı önizlemek için @WearWidgetPreview kullanın:

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

Widget Yapılandırma XML'ini oluşturma

Widget'ın özelliklerini ve desteklenen boyutlarını tanımlamak için yeni bir res/xml/hello_widget_info.xml dosyası oluşturun. <wearwidget-provider> etiketinde desteklenen XML özelliklerinin tam listesi 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 resmi öğeleri oluşturma

<container> öğesinin previewImage özelliği, sistem widget seçicide gösterilen çizilebilir bir öğeye referans veriyor. Doğru sınır ve yoğunlukta önizleme öğeleri oluşturmak için RectangularAllWidgetPreviewParams ile Android Studio önizlemelerini kullanın (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ı uygulayın:

  1. Android Studio'da önizleme composable'ı için Design (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ı kullanabilirsiniz.
  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ına kaydetme

Hizmeti, gerekli intent filtreleri ve meta verilerle AndroidManifest.xml dosyanıza 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ğıtma

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

Derleme ve yükleme

Projeyi derleyin 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 rulo listeye eklemek ve ekranda göstermek için adb yöntemini kullanın.

Not: Wear widget'ları, hata ayıklama amacıyla temel kart altyapısını kullanır. Bu nedenle adb komutları, add-tile ve show-tile işlemlerini gerektirir.

1. Widget'ı rulo listeye 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) sistemden widget içeriğini yenilemesini isteyin.

Widget'ınızın tüm etkin örnekleri için güncelleme isteğinde bulunmak üzere widget sınıfınızda triggerUpdateAll yöntemini ç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 yöntemini çağırın.