Gestire l'interazione utente

Glance semplifica la gestione dell'interazione utente utilizzando le classi Action. Le classi Action di Glance definiscono le azioni che un utente può intraprendere e puoi specificare l'operazione eseguita in risposta all'azione. Puoi applicare un Action a qualsiasi componente con il metodo GlanceModifier.clickable.

I widget delle app si trovano in un processo remoto, quindi le azioni vengono definite al momento della creazione e l'esecuzione avviene nel processo remoto. In RemoteViews nativo, questa operazione viene eseguita utilizzando PendingIntents.

In questa pagina sono descritte le seguenti azioni:

Avvia un'attività

Per avviare un'attività in base all'interazione dell'utente, fornisci la funzione actionStartActivity a un Button o a un altro componibile utilizzando il modificatore GlanceModifier.clickable.

Fornisci uno dei seguenti elementi in actionStartActivity:

Glance traduce l'azione in un PendingIntent con il target e i parametri forniti. Nell'esempio seguente, NavigationActivity viene avviato quando un utente fa clic sul pulsante:

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

Lancia un servizio

Analogamente all'avvio di un'attività, avvia un servizio in base all'interazione dell'utente utilizzando uno dei metodi actionStartService.

Fornisci uno dei seguenti elementi in actionStartService:

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

Invia un evento di trasmissione

Invia un evento di trasmissione in base all'interazione dell'utente utilizzando uno dei metodi actionSendBroadcast:

Fornisci uno dei seguenti elementi in actionSendBroadcast:

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

Esegui azioni personalizzate

Anziché lanciare un target specifico, Glance può utilizzare un'azione lambda o un actionRunCallback per eseguire un'azione, ad esempio l'aggiornamento della UI o dello stato in base all'interazione dell'utente.

Esegui azioni Lambda

Puoi utilizzare le funzioni lambda come callback per le interazioni con la UI.

Ad esempio, passa la funzione lambda al modificatore GlanceModifier.clickable:

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

In alternativa, passalo al parametro onClick sui componibili che lo supportano:

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

Esegui ActionCallback

In alternativa, utilizza i metodi actionRunCallback per eseguire un'azione in base all'interazione dell'utente. Per farlo, fornisci un'implementazione personalizzata di 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
    }
}

Quando l'utente fa clic, viene chiamato il metodo suspend onAction dell'interfaccia ActionCallback fornita, eseguendo la logica definita (ovvero richiedendo i dati di aggiornamento).

Per aggiornare il widget dopo l'esecuzione dell'azione, crea una nuova istanza e chiama update(..). Per maggiori dettagli, consulta la sezione Gestisci lo stato di 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)
    }
}

Fornisci parametri alle azioni

Per fornire informazioni aggiuntive a un'azione, utilizza l'API ActionParameters per creare una coppia chiave-valore tipizzata. Ad esempio, per definire la destinazione selezionata:

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

In background, i parametri vengono inclusi nell'intent utilizzato per avviare l'attività, consentendo all'attività di destinazione di recuperarlo.

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

I parametri vengono forniti anche a ActionCallback. Utilizza il Parameters.Key definito per recuperare il valore:

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

Indietro
Test delle unità con Glance
Avanti
Monitora le metriche per il widget