التعامل مع تفاعل المستخدم

تسهّل Glance التعامل مع تفاعل المستخدمين باستخدام فئات Action. تحدّد فئات Action في Glance الإجراءات التي يمكن للمستخدم اتّخاذها، ويمكنك تحديد العملية التي يتم تنفيذها استجابةً للإجراء. يمكنك تطبيق Action على أي مكوّن باستخدام الطريقة GlanceModifier.clickable.

تكون التطبيقات المصغّرة نشطة في عملية عن بُعد، لذا يتم تحديد الإجراءات في وقت الإنشاء ويتم التنفيذ في العملية عن بُعد. في RemoteViews الأصلي، يتم ذلك باستخدام PendingIntents.

يتم توضيح الإجراءات التالية في هذه الصفحة:

بدء نشاط

لبدء نشاط عند تفاعل المستخدم، يمكنك تقديم الدالة actionStartActivity إلى Button أو دالة مركّبة أخرى باستخدام المُعدِّل GlanceModifier.clickable.

يُرجى تقديم أحد المستندات التالية باللغة actionStartActivity:

تحوّل Glance الإجراء إلى PendingIntent مع الهدف والمعلَمات المقدَّمة. في المثال التالي، يتم تشغيل NavigationActivity عندما ينقر المستخدم على الزر:

@Composable
fun MyContent() {
    // ..
    Button(
        text = "Go Home",
        onClick = actionStartActivity<MyActivity>()
    )
}

إطلاق خدمة

على غرار بدء نشاط، يمكنك بدء خدمة عند تفاعل المستخدم باستخدام إحدى طرق actionStartService.

يُرجى تقديم أحد المستندات التالية باللغة actionStartService:

  • فئة النشاط المستهدَف
  • ComponentName
  • النية

@Composable
fun MyButton() {
    // ..
    Button(
        text = "Sync",
        onClick = actionStartService<SyncService>(
            isForegroundService = true // define how the service is launched
        )
    )
}

إرسال حدث بث

أرسِل حدث بث عند تفاعل المستخدم باستخدام إحدى طرق actionSendBroadcast التالية:

يُرجى تقديم أحد المستندات التالية باللغة actionSendBroadcast:

@Composable
fun MyButton() {
    // ..
    Button(
        text = "Send",
        onClick = actionSendBroadcast<MyReceiver>()
    )
}

تنفيذ إجراءات مخصّصة

بدلاً من تشغيل هدف معيّن، يمكن أن تستخدم Glance إجراء lambda أو actionRunCallback لتنفيذ إجراء، مثل تعديل واجهة المستخدم أو الحالة عند تفاعل المستخدم.

تنفيذ إجراءات Lambda

يمكنك استخدام دوال lambda كعمليات استدعاء لتفاعلات واجهة المستخدم.

على سبيل المثال، مرِّر دالة lambda إلى المُعدِّل GlanceModifier.clickable:

Text(
    text = "Submit",
    modifier = GlanceModifier.clickable {
        submitData()
    }
)

أو يمكنك تمريرها إلى المَعلمة onClick في الدوال المركّبة التي تتيح ذلك:

Button(
    text = "Submit",
    onClick = {
        submitData()
    }
)

تنفيذ ActionCallback

بدلاً من ذلك، يمكنك استخدام طرق actionRunCallback لتنفيذ إجراء عند تفاعل المستخدم. لإجراء ذلك، عليك توفير تنفيذ مخصّص لـ ActionCallback:

@Composable
private fun MyContent() {
    // ..
    Image(
        provider = ImageProvider(R.drawable.ic_hourglass_animated),
        modifier = GlanceModifier.clickable(
            onClick = actionRunCallback<RefreshAction>()
        ),
        contentDescription = "Refresh"
    )
}

class RefreshAction : ActionCallback {
    override suspend fun onAction(
        context: Context,
        glanceId: GlanceId,
        parameters: ActionParameters
    ) {
        // TODO implement
    }
}

عندما ينقر المستخدم، يتم استدعاء طريقة suspend onAction في ActionCallback المقدَّم، ويتم تنفيذ المنطق المحدّد (أي طلب إعادة تحميل البيانات).

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

class RefreshAction : ActionCallback {
    override suspend fun onAction(
        context: Context,
        glanceId: GlanceId,
        parameters: ActionParameters
    ) {
        // do some work but offset long-term tasks (e.g a Worker)
        MyAppWidget().update(context, glanceId)
    }
}

تقديم مَعلمات للإجراءات

لتقديم معلومات إضافية لإجراء معيّن، استخدِم واجهة برمجة التطبيقات ActionParameters لإنشاء زوج مفتاح/قيمة مكتوب. على سبيل المثال، لتحديد الوجهة التي تم النقر عليها:

private val destinationKey = ActionParameters.Key<String>(
    NavigationActivity.KEY_DESTINATION
)

class MyAppWidget : GlanceAppWidget() {

    // ..

    @Composable
    private fun MyContent() {
        // ..
        Button(
            text = "Home",
            onClick = actionStartActivity<NavigationActivity>(
                actionParametersOf(destinationKey to "home")
            )
        )
        Button(
            text = "Work",
            onClick = actionStartActivity<NavigationActivity>(
                actionParametersOf(destinationKey to "work")
            )
        )
    }

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        provideContent { MyContent() }
    }
}

في الخلفية، يتم تضمين المَعلمات في الغرض المستخدَم لبدء النشاط، ما يسمح للنشاط المستهدَف باستردادها.

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val destination = intent.extras?.getString(KEY_DESTINATION) ?: return
        // ...
    }
}

يتم أيضًا تقديم المَعلمات إلى ActionCallback. استخدِم Parameters.Key المحدَّد لاسترداد القيمة:

class RefreshAction : ActionCallback {

    private val destinationKey = ActionParameters.Key<String>(
        NavigationActivity.KEY_DESTINATION
    )

    override suspend fun onAction(
        context: Context,
        glanceId: GlanceId,
        parameters: ActionParameters
    ) {
        val destination: String = parameters[destinationKey] ?: return
        // ...
    }
}

السابق
اختبار الوحدات من خلال ميزة "نظرة سريعة"
التالي
تتبُّع مقاييس تطبيقك المصغّر