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

ملاحظة: يفترض هذا الدليل التعليمي أنّك تنشئ تطبيقًا مصغّرًا جديدًا وليس لديك بطاقة حالية. إذا كنت بصدد تحديث تطبيق يتضمّن مربّعًا حاليًا، يُرجى قراءة دليل النقل من المربّعات إلى التطبيقات المصغّرة لضبط خدماتك.

مهارات Android

العرض على GitHub

تطبيقات Wear OS المصغّرة

يمكنك استخدام مهارة Android لمساعدتك في إنشاء تطبيقات Wear OS المصغّرة باستخدام Glance وRemoteViews وProtoLayout.

لتثبيت المهارة من Android CLI، شغِّل:

android skills add wear-widgets

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

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

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

تتطلّب تطبيقات 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-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"
}

Kotlin

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

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

يتكوّن تطبيق Wear Widget من خدمة تمدّد 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 = ...) ليتمكّن النظام المضيف من رسم الخلفية وإخفائها وفقًا لشكل حاوية المصنّع الأصلي للجهاز. قد يؤدي ضبط لوحة رسم شفافة أو سوداء ورسم حاوية مستديرة مخصّصة داخل التنسيق إلى حدوث عيوب في المربّع العائم والشاشة العريضة على بعض الأجهزة.

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

يتم إنشاء المحتوى باستخدام مكوّنات 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" باستخدام androidx.glance.wear:wear-tooling-preview.

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

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

• ‫Squircle Suite (SquircleAllWidgetPreviewParams): حاويات مستطيلة مستديرة الزوايا
• مجموعة Round Suite (RoundAllWidgetPreviewParams): حاويات على شكل حبوب دواء
• الحزمة المستطيلة (RectangularAllWidgetPreviewParams): حاويات مستطيلة غير مقتصّة مع مساحة متروكة آمنة إنّ الصور التي يتم إنشاؤها باستخدام إعدادات المعاينة هذه مناسبة للاستخدام كصور معاينة مضمّنة في حزمة APK يستخدمها منتقي التطبيقات المصغّرة (يُرجى الاطّلاع على إنشاء مواد عرض صور المعاينة).

لمعاينة التطبيق المصغّر في "استوديو Android"، استخدِم @WearWidgetPreview:

@Preview
@Composable
fun HelloWidgetPreview(
    @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams,
) {
    WearWidgetPreview(
        widget = HelloWidget(),
        params = params,
    )
}
GetStarted.kt

ملاحظة: يمكنك أيضًا معاينة تنسيقات @RemoteComposable مباشرةً بدون إنشاء مثيل لفئة التطبيق المصغّر من خلال تمرير دالة lambda للمحتوى وفرشاة الخلفية إلى WearWidgetPreview.

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

ملاحظة: يضيف الأمر السابق مربّعًا بملء الشاشة تلقائيًا. يمكنك أيضًا تحديد الحجمين LARGE وSMALL من خلال تمرير --ei type [0|1|2] إلى الأمر (حيث يكون النوع 0 هو FULLSCREEN). استنادًا إلى حالة الجهاز، قد يتعذّر تحديث المحتوى الذي يتم تشغيله من خلال التطبيق باستخدام triggerUpdate() للأنواع التي لا تظهر في وضع ملء الشاشة عند استخدام إصدارات مكتبة Wear Widget حتى 1.0.0-alpha10 (تم إصلاح هذه المشكلة بدءًا من الإصدار 1.0.0-alpha11).

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 باستخدام رقم تعريف المثيل المستهدَف.