بدء استخدام التطبيقات المصغّرة

المتطلّبات الأساسية والإعداد

قبل البدء، تأكَّد من أنّ بيئتك تستوفي المتطلبات التالية.

متطلبات وقت التشغيل

تتطلّب "أدوات Wear" الإصدار 1.6.1 أو الإصدارات الأحدث من حزمة APK الخاصة بتطبيق com.google.android.wearable.protolayout.renderer على جهاز الاختبار.

احصل على إصدار متوافق من أداة العرض بإحدى الطرق التالية:

  • محاكي Wear OS 7: استخدِم صورة محاكي Wear OS 7. الإصدارات الأقل من 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 Widget على Google Maven.

1. ضبط إصدار حزمة تطوير البرامج (SDK)

تأكَّد من ضبط compileSdk وtargetSdk على 37 أو أعلى.

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

2. إضافة التبعيات

أدرِج التبعيات التالية في ملف 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"
}

Kotlin

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")
}

إنشاء تطبيق مصغّر Hello World

تتألف أداة Wear من خدمة توسّع GlanceWearWidgetService وفئة أداة توسّع GlanceWearWidget. يتم تحديد واجهة المستخدم باستخدام دوال @RemoteComposable. @RemoteComposable.

تحديد الخدمة

الخدمة هي نقطة الدخول التي يربط بها النظام.

لتحديد التطبيق المصغّر، أنشئ خدمة توسّع GlanceWearWidgetService. بما أنّ هذه المكتبة في مرحلة التطوير النشط، يتم فرض قيود على بعض واجهات برمجة التطبيقات أثناء العمل على تحسين أسمائها وبنيتها النهائية. يؤدي استخدام التعليق التوضيحي @SuppressLint("RestrictedApi") إلى إعلام المترجم بأنّك تستخدم هذه الميزات الجديدة والمتطوّرة عن قصد. هذا الشرط مؤقت وسيتم إزالته بعد الانتهاء من واجهات برمجة التطبيقات في إصدار ثابت مستقبلي.

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

تحديد التطبيق المصغّر

يوفر فئة التطبيق المصغّر البيانات والتنسيق الخاصين بالتطبيق المصغّر.

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

تحديد المحتوى

يتم إنشاء المحتوى باستخدام مكوّنات Remote Compose.

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

إنشاء ملف 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>

التسجيل في ملف 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>

التطوير والنشر

بعد تحديد الخدمة والأداة، يمكنك إنشاء مشروعك ونشره على جهاز أو محاكي.

إنشاء وتثبيت

أنشئ المشروع وثبِّت حِزمة APK المخصّصة لتصحيح الأخطاء على جهازك المتصل أو المحاكي:

./gradlew :app:installDebug

إضافة التطبيق المصغّر ومعاينته

بعد تثبيت التطبيق، استخدِم adb لإضافة التطبيق المصغّر آليًا إلى لوحة العرض الدوّارة وعرضه على الشاشة.

ملاحظة: تستخدم "أدوات Wear" البنية الأساسية للّوحات بغرض تصحيح الأخطاء. نتيجةً لذلك، تتطلّب أوامر adb العمليتَين add-tile وshow-tile.

1. أضِف التطبيق المصغّر إلى منصّة العرض الدوّارة باتّباع الخطوات التالية:

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

2. عرض التطبيق المصغّر:

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

تتوفّر أيضًا معاينات &quot;استوديو Android&quot; لمساعدتك في اختبار تنسيقاتك على أحجام شاشات مختلفة.