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

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

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

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

تتطلّب "أدوات 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-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")
}

إنشاء تطبيق مصغّر "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

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

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

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

معاينة تطبيقك المصغّر في "استوديو Android"

يمكنك معاينة تخطيطات التطبيقات المصغّرة مباشرةً في لوحة التصميم في "استوديو Android" باستخدام androidx.glance.wear:wear-tooling-preview.

مجموعات المعاينة المحدّدة مسبقًا

توفّر مكتبة wear-tooling-preview مجموعات PreviewParameterProvider محدّدة مسبقًا لاختبار التصاميم على أشكال حاويات وإعدادات أجهزة مختلفة:

• حزمة Squircle (SquircleAllWidgetPreviewParams): حاويات مستطيلة مستديرة الزوايا
• Round Suite (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 (التي تنشئ صيغ معاينة لكل من الحاويات الصغيرة والكبيرة) وحدِّد كثافة شاشة ساعة ذكية تبلغ 320 نقطة لكل بوصة:

@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"، افتح مساحة التصميم للعنصر القابل للإنشاء الخاص بالمعاينة.
2. في نافذة المعاينة، انقر بزر الماوس الأيمن على المعاينة المعروضة أو استخدِم شريط أدوات المعاينة لاختيار نسخ الصورة أو حفظ الصورة. بدلاً من ذلك، يمكنك استخدام أدوات سطر الأوامر أو النصوص البرمجية المبرمَجة لاستخراج معاينات 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.

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

تعديل محتوى التطبيق المصغّر آليًا

عندما تتغيّر البيانات الأساسية لتطبيقك (مثل تلقّي مزامنة بيانات أو إشعار فوري أو إجراء من المستخدم)، أرسِل إشعارًا إلى النظام لإعادة تحميل محتوى التطبيق المصغّر.

لطلب تحديث جميع مثيلات التطبيق المصغّر النشطة، استدعِ الدالة triggerUpdateAll في فئة التطبيق المصغّر:

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

لتعديل نسخة معيّنة من التطبيق المصغّر بدون إعادة تحميل جميع النسخ النشطة، استخدِم الدالة triggerUpdate مع معرّف النسخة المستهدَفة.