איך מטפלים באינטראקציות של משתמשים

‫Glance מפשטת את הטיפול באינטראקציות של משתמשים באמצעות המחלקות Action. המחלקות של Glance‏ Action מגדירות את הפעולות שמשתמש יכול לבצע, ואתם יכולים לציין את הפעולה שתתבצע בתגובה לפעולה של המשתמש. אפשר להחיל Action על כל רכיב באמצעות השיטה GlanceModifier.clickable.

ווידג'טים של אפליקציות פועלים בתהליך מרוחק, ולכן הפעולות מוגדרות בזמן היצירה והביצוע מתרחש בתהליך המרוחק. ב-RemoteViews המקורי, הפעולה הזו מתבצעת באמצעות PendingIntents.

בדף הזה מפורטות הפעולות הבאות:

הפעלת פעילות

כדי להפעיל פעילות באינטראקציה של משתמש, צריך לספק את הפונקציה actionStartActivity ל-Button או לרכיב אחר שאפשר להוסיף לו קומפוזיציה באמצעות המשנה GlanceModifier.clickable.

צריך לספק אחד מהפרטים הבאים בactionStartActivity:

  • הסיווג של פעילות היעד
  • ‫ComponentName
  • כוונת המשתמש

‫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(..). פרטים נוספים זמינים בקטע Manage GlanceAppWidget state.

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

ציון פרמטרים לפעולות

כדי לספק מידע נוסף על פעולה, משתמשים ב-API‏ 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 שמשמש להפעלת הפעילות, וכך מאפשרים לפעילות היעד לאחזר אותו.

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

הקודם
בדיקת יחידה באמצעות 'בקצרה'
הבא
מעקב אחר מדדים בווידג'ט