شروع کار با ویجت‌ها

پیش‌نیازها و تنظیمات

قبل از شروع، مطمئن شوید که محیط شما الزامات زیر را برآورده می‌کند.

الزامات زمان اجرا

ابزارک‌های پوشیدنی به نسخه ۱.۶.۱ یا بالاتر از فایل APK مربوط به com.google.android.wearable.protolayout.renderer در دستگاه هدف نیاز دارند.

یک نسخه سازگار از رندرکننده را از یکی از روش‌های زیر دریافت کنید:

• شبیه‌ساز Wear OS 7 : از ایمیج شبیه‌ساز Wear OS 7 استفاده کنید. نسخه‌های پایین‌تر از ۷ مناسب نیستند. برای دستورالعمل‌های راه‌اندازی، به راه‌اندازی شبیه‌ساز Wear OS 7 مراجعه کنید.
• دستگاه فیزیکی : از یک دستگاه فیزیکی Wear OS که به‌روزرسانی‌های خودکار را از فروشگاه Google Play دریافت می‌کند، یا یک دستگاه توسعه‌دهنده که به فروشگاه Google Play وارد شده است، استفاده کنید.

برای بررسی نسخه نصب شده روی دستگاه خود، از دستور زیر استفاده کنید:

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

پیکربندی گریدل

کتابخانه‌های Wear Widget در Google Maven موجود هستند.

۱. پیکربندی نسخه SDK

مطمئن شوید که compileSdk و targetSdk شما روی ۳۷ یا بالاتر تنظیم شده‌اند.

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

۲. وابستگی‌ها را اضافه کنید

وابستگی‌های زیر را در فایل build.gradle.kts برنامه خود وارد کنید:

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

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

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

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

ساخت ویجت سلام دنیا

یک ویجت Wear شامل یک سرویس است که GlanceWearWidgetService و یک کلاس ویجت که GlanceWearWidget توسعه می‌دهد، تشکیل @RemoteComposable است. رابط کاربری با استفاده از توابع @RemoteComposable تعریف می‌شود.

تعریف سرویس

سرویس نقطه ورودی است که سیستم به آن متصل می‌شود.

برای تعریف ویجت خود، سرویسی ایجاد کنید که GlanceWearWidgetService ارث‌بری کند. از آنجا که این کتابخانه در حال توسعه فعال است، برخی از APIها در حین اصلاح نام‌ها و ساختارهای نهایی خود محدود شده‌اند. استفاده از حاشیه‌نویسی @SuppressLint("RestrictedApi") به کامپایلر شما می‌گوید که شما عمداً از این ویژگی‌های جدید و در حال تکامل استفاده می‌کنید. این الزام موقتی است و پس از نهایی شدن APIها در نسخه پایدار آینده، حذف خواهد شد.

@SuppressLint("RestrictedApi")
class HelloWidgetService : GlanceWearWidgetService() {
    override val widget: GlanceWearWidget = HelloWidget()
}
GetStarted.kt

تعریف ویجت

کلاس ویجت، داده‌ها و طرح‌بندی ویجت را فراهم می‌کند.

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

محتوا را تعریف کنید

محتوا با استفاده از کامپوننت‌های Remote Compose ساخته می‌شود.

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

ایجاد فایل XML پیکربندی ویجت

یک فایل جدید res/xml/hello_widget_info.xml ایجاد کنید تا ویژگی‌های ویجت و اندازه‌های پشتیبانی‌شده را تعریف کنید. برای مشاهده‌ی مرجع کامل ویژگی‌های 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>
hello_widget_info.xml

در AndroidManifest.xml ثبت کنید

سرویس را در AndroidManifest.xml خود به همراه فیلترهای intent و متادیتای مورد نیاز ثبت کنید.

<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>
AndroidManifest.xml

ساخت و استقرار

پس از تعریف سرویس و ویجت خود، می‌توانید پروژه خود را بسازید و آن را روی یک دستگاه یا شبیه‌ساز مستقر کنید.

ساخت و نصب

پروژه را بسازید و debug APK را روی دستگاه یا شبیه‌ساز متصل خود نصب کنید:

./gradlew :app:installDebug

ویجت خود را اضافه کنید و پیش‌نمایش آن را ببینید

پس از نصب برنامه، adb برای اضافه کردن ویجت به چرخ فلک به صورت برنامه‌نویسی شده و نمایش آن روی صفحه استفاده کنید.

نکته: ویجت‌های Wear از زیرساخت کاشی‌های زیرین برای اشکال‌زدایی استفاده می‌کنند. در نتیجه، دستورات adb به عملیات add-tile و show-tile نیاز دارند.

۱. ویجت را به چرخ فلک اضافه کنید:

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

۲. نمایش ویجت:

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

پیش‌نمایش‌های اندروید استودیو نیز برای کمک به شما در آزمایش طرح‌بندی‌هایتان در اندازه‌های مختلف صفحه نمایش در دسترس هستند.