شروع به کار با ابزاره‌ها

پیش‌نیازها و راه‌اندازی

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

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

«ابزارک‌های Wear» به نسخه ۱.۶.۱ یا بالاتر از com.google.android.wearable.protolayout.renderer APK در دستگاه هدف نیاز دارد.

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

• شبیه‌ساز 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}'

پیکربندی Gradle

کتابخانه‌های «ابزاره Wear» در Google Maven دردسترس است.

۱. پیکربندی نسخه کیت توسعه نرم‌افزار

مطمئن شوید 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-alpha20"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha19"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha12"

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

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha20")
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.0")
    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 حاشیه‌نویسی کنید تا سرویس را با کلاس GlanceWearWidget مناسب مرتبط کنید.

@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

تعریف محتوا

محتوا بااستفاده از عناصر «ترکیب از دور» ساخته شده است.

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

پیش‌دید کردن ابزاره در «استودیو Android»

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

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

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

• مجموعه مربع با گوشه‌های گرد (SquircleAllWidgetPreviewParams): ظرف‌های مستطیل گردشده.
• مجموعه گرد (RoundAllWidgetPreviewParams): محفظه‌های قرصی‌شکل.
• مجموعه مستطیلی (RectangularAllWidgetPreviewParams): محتویات مستطیلی بدون برش با حاشیه امن. تصاویر تولیدشده با این پیکربندی پیش‌نمایش برای استفاده به‌عنوان تصاویر پیش‌نمایش جاسازی‌شده در APK که توسط انتخابگر ابزارک استفاده می‌شود مناسب است (به تولید دارایی‌های تصویر پیش‌نمایش مراجعه کنید).

برای پیش‌نمایش ابزاره در «استودیو Android»، از @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> به دارایی طراحی‌شدنی‌ای ارجاع می‌دهد که در انتخابگر ابزاره سیستم نشان داده می‌شود. برای تولید دارایی‌های پیش‌نمایش با محدوده و تراکم صحیح، از «پیش‌نمایش‌های استودیو Android» با RectangularAllWidgetPreviewParams (که گونه‌های پیش‌نمایش را برای ظرف‌های کوچک و بزرگ تولید می‌کند) استفاده کنید و تراکم نمایشگر ساعت هوشمند ۳۲۰ نقطه در اینچ را مشخص کنید:

@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. در Android Studio، سطح طراحی را برای عنصر ترکیبی پیش‌نمایش باز کنید.
2. در پنجره پیش‌نمایش، روی پیش‌نمایش پردازش‌شده کلیک راست کنید یا از نوارابزار پیش‌نمایش برای انتخاب کپی کردن تصویر یا ذخیره کردن تصویر استفاده کنید. یا از ابزارهای خط فرمان یا دستورگان‌های خودکارسازی‌شده برای استخراج پیش‌نمایش‌های «نوشتن» استفاده کنید.
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>
AndroidManifest.xml

ساختن و مستقر کردن

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

ساختن و نصب کردن

پروژه را بسازید و 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

به‌روزرسانی محتوای ابزاره به‌صورت برنامه‌ریزی‌شده

وقتی داده‌های زیربنایی برنامه شما تغییر می‌کند (مثلاً همگام‌سازی داده، اعلان لحظه‌ای، یا کنش کاربر دریافت می‌کند)، به سیستم اطلاع دهید محتوای ابزارک را بازآوری کند.

برای درخواست به‌روزرسانی برای همه نمونه‌های فعال ابزاره، triggerUpdateAll را در کلاس ابزاره‌تان فراخوانی کنید:

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

برای به‌روزرسانی نمونه ابزاره خاص بدون بازآوری همه نمونه‌های فعال، با شناسه نمونه هدف triggerUpdate را فراخوانی کنید.