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

تسهّل 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:

@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 إجراء لامدا أو actionRunCallback لتنفيذ إجراء، مثل تعديل واجهة المستخدم أو الحالة عند تفاعل المستخدم.

تنفيذ إجراءات لامدا

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

على سبيل المثال، مرِّر دالة لامدا إلى المعدِّل 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() }
    }
}

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

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

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