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

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

مهارت‌های Android

مشاهده در GitHub

ابزاره‌های Wear OS

از مهارت Android برای کمک به ساختن ابزاره‌های Wear OS با Glance،‏ RemoteViews، و ProtoLayout استفاده کنید.

برای نصب مهارت از Android CLI، این دستور را اجرا کنید:

android skills add wear-widgets

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

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

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

ابزاره‌های Wear به نسخه ۱.۶.۱ یا بالاتر 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}'

پیکربندی 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-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"
}

کاتلین

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

«ابزاره 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

هشدار: همیشه قلم‌موی پس‌زمینه ابزاره را مستقیماً به WearWidgetDocument(background = ...) ارائه دهید تا سیستم میزبان بتواند پس‌زمینه را به شکل محفظه OEM بومی رنگ‌آمیزی و ماسک کند. تنظیم بوم شفاف یا سیاه و کشیدن محفظه گرد سفارشی در داخل چیدمان می‌تواند باعث ایجاد نقص‌های جعبه شناور و جعبه نامه‌ای در برخی دستگاه‌ها شود.

تعریف محتوا

محتوا بااستفاده از مؤلفه‌های Remote Compose ساخته شده است.

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

هشدار: مطمئن شوید که ترکیب‌پذیر محفظه ریشه شما از RemoteModifier.fillMaxSize() استفاده می‌کند. چون ابعاد DP محفظه و حاشیه‌های امن در مدل‌های مختلف ساعت متفاوت است، کدگذاری سخت ابعاد ثابت یا لایه بیرونی می‌تواند باعث برش یا چیدمان‌های نامرتب شود.

پیش‌دید کردن ابزاره در «استودیو 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

نکته: همچنین می‌توانید با ارسال لامبدا محتوا و قلم‌موی پس‌زمینه به WearWidgetPreview، چیدمان‌های @RemoteComposable را مستقیماً بدون نمونه‌سازی کلاس ابزاره پیش‌نمایش کنید.

ایجاد 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 (که انواع پیش‌نمایش را برای محفظه‌های کوچک و بزرگ تولید می‌کند) استفاده کنید و تراکم نمایش ساعت هوشمند ۳۲۰ 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. در Android Studio، سطح طراحی را برای پیش‌نمایش ترکیب‌پذیر باز کنید.
2. در پنجره پیش‌نمایش، روی پیش‌نمایش پردازش‌شده کلیک راست کنید یا از نوارابزار پیش‌نمایش برای انتخاب کپی کردن تصویر یا ذخیره تصویر استفاده کنید. یا اینکه از ابزار CLI یا دستورگان‌های خودکار برای استخراج پیش‌نمایش‌های Compose استفاده کنید.
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

توجه: فرمان قبلی به‌طور پیش‌فرض کاشی «تمام‌صفحه» اضافه می‌کند. همچنین می‌توانید با ارسال --ei type [0|1|2] به فرمان، اندازه‌های LARGE (بزرگ) و SMALL (کوچک) را مشخص کنید (که نوع 0 آن FULLSCREEN (تمام‌صفحه) است). بسته به وضعیت دستگاه، به‌روزرسانی‌های محتوای راه‌اندازی‌شده توسط برنامه بااستفاده از triggerUpdate() ممکن است برای انواع غیرتمام‌صفحه هنگام استفاده از نسخه‌های کتابخانه «ابزاره Wear» تا 1.0.0-alpha10 ناموفق باشد (این مشکل از نسخه 1.0.0-alpha11 برطرف شده است).

۲. نمایش ابزاره:

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 را با شناسه نمونه هدف فراخوانی کنید.