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

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

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

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

تتطلّب تطبيقات 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 المصغّرة على 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-alpha11"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha11"
    implementation "androidx.glance.wear:wear:1.0.0-alpha10"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha10"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha04"

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

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

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

إنشاء ملف 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 باستخدام فلاتر الأهداف والبيانات الوصفية المطلوبة.

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

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

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