處理使用者互動

Glance 透過 Action 類別簡化使用者互動處理作業。Glance Action 類別會定義使用者可採取的動作,而您可以指定 所執行的作業。您可以將 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 使用 lambda 動作或 actionRunCallback:執行動作,例如更新 UI 或 互動。

執行 lambda 動作

您可以使用 lambda 函式做為 UI 互動的回呼。

例如,將 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 建立已輸入鍵/值組合的 API。舉例來說,如果想定義 目的地:

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