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

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

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

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

بدء نشاط

لتشغيل نشاط بناءً على تفاعل المستخدم، وفِّر دالة actionStartActivity لأي Button أو أي عنصر آخر يمكن تركيبه عبر أداة تعديل GlanceModifier.clickable(..).

يُرجى تقديم أي مما يلي في "actionStartActivity":

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

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

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

إطلاق خدمة

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

يُرجى تقديم أي مما يلي في "actionStartService":

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

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

إرسال حدث بث

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

يُرجى تقديم أي مما يلي في "actionSendBroadcast":

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

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

بدلاً من إطلاق هدف محدّد، يمكن لميزة "نظرة سريعة" استخدام إجراء lambda أو actionRunCallback لتنفيذ إجراء معيّن، مثل تعديل واجهة المستخدم أو الحالة عند تفاعل المستخدم.

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

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

على سبيل المثال، أدخِل دالة lambda في معدِّل GlanceModifier.clickable:

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

أو أدخِلها إلى المعلَمة onClick في المواد المرفَقة المتوافقة معها:

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

تشغيل 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
    }
}
GlanceSnippets.kt

عند نقر المستخدم، يتم استدعاء طريقة 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)
    }
}

GlanceSnippets.kt

توفير مَعلمات للإجراءات

لتوفير معلومات إضافية لأحد الإجراءات، استخدِم واجهة برمجة التطبيقات 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() }
    }
}
GlanceSnippets.kt

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

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

يتم تقديم المَعلمات أيضًا إلى 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
        // ...
    }
}
GlanceSnippets.kt

السابق
إنشاء تطبيق مصغّر باستخدام ميزة "نظرة سريعة"
التالي
إدارة GlanceAppWidget وتعديلها