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

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

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

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

تتطلّب تطبيقات 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-alpha19"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear:1.0.0-alpha18"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha18"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha11"

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

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha19")
    implementation("androidx.wear.compose:compose-ui-tooling:1.6.2")
    implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2")
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")
}

إنشاء تطبيق مصغّر "مرحبًا بالعالم"

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

تحديد الخدمة

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

لتحديد تطبيقك المصغّر، أنشئ خدمة توسّع GlanceWearWidgetService.

@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‏ (RoundAllWidgetPreviewParams): حاويات على شكل حبّة دواء
• حزمة Rectangular‏ (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