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

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

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

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

ابزارک‌های پوشیدنی به نسخه ۱.۶.۱ یا بالاتر از فایل 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-alpha18"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha18"
    implementation "androidx.glance.wear:wear:1.0.0-alpha17"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha17"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha10"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha18"
    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"
}

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

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha18")
    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")
}

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

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

تعریف سرویس

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

برای تعریف ویجت خود، سرویسی ایجاد کنید که GlanceWearWidgetService ارث‌بری کند.

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

تعریف ویجت

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

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 ساخته می‌شود.

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

پیش‌نمایش ویجت خود را در اندروید استودیو مشاهده کنید

شما می‌توانید طرح‌بندی‌های ویجت خود را مستقیماً در پنل طراحی اندروید استودیو با استفاده از androidx.glance.wear:wear-tooling-preview پیش‌نمایش کنید.

مجموعه‌های پیش‌نمایش از پیش تعریف‌شده

کتابخانه wear-tooling-preview مجموعه‌های از پیش تعریف‌شده PreviewParameterProvider را برای آزمایش طرح‌بندی‌های شما در اشکال مختلف کانتینر و پیکربندی‌های دستگاه ارائه می‌دهد:

• مجموعه Squircle ( SquircleAllWidgetPreviewParams ): کانتینرهای مستطیلی گرد.
• Round Suite ( RoundAllWidgetPreviewParams ): ظروف قرص شکل.
• مجموعه مستطیلی (RectangularSuite ( RectangularAllWidgetPreviewParams ): کانتینرهای مستطیلی برش‌نخورده با حاشیه‌گذاری ایمن. تصاویر تولید شده با این پیکربندی پیش‌نمایش برای استفاده به عنوان تصاویر پیش‌نمایش تعبیه‌شده در APK که توسط انتخابگر ویجت استفاده می‌شود، مناسب هستند (به بخش «ایجاد دارایی‌های تصویر پیش‌نمایش » مراجعه کنید).

برای پیش‌نمایش ویجت خود در اندروید استودیو، @WearWidgetPreview ‎ استفاده کنید:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
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

ایجاد پیش‌نمایش تصاویر

ویژگی previewImage عنصر <container> به یک عنصر قابل ترسیم اشاره دارد که در انتخابگر ویجت سیستم نشان داده شده است. برای تولید عناصر پیش‌نمایش با محدوده‌ها و چگالی صحیح، از پیش‌نمایش‌های اندروید استودیو با RectangularAllWidgetPreviewParams (که انواع پیش‌نمایش را برای هر دو کانتینر کوچک و بزرگ تولید می‌کند) استفاده کنید و چگالی نمایشگر ساعت هوشمند را 320 DPI تعیین کنید:

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

برای استخراج تصاویر پیش‌نمایش رندر شده، مراحل زیر را انجام دهید:

1. در اندروید استودیو، سطح طراحی (Design surface) را برای پیش‌نمایش composable باز کنید.
2. در پنجره پیش‌نمایش، روی پیش‌نمایش رندر شده کلیک راست کنید یا از نوار ابزار پیش‌نمایش برای انتخاب «کپی تصویر» یا ذخیره تصویر استفاده کنید. روش دیگر، استفاده از ابزار CLI یا اسکریپت‌های خودکار برای استخراج پیش‌نمایش‌های «نوشتن» است.
3. فایل‌های تصویر کوچک و بزرگ را در پوشه res/drawable-nodpi/ برنامه خود ذخیره کنید، مانند res/drawable-nodpi/widget_preview_small.png و res/drawable-nodpi/widget_preview_large.png .

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