處理使用者互動

Glance 使用 Action 類別簡化使用者互動處理程序。Glance 的 Action 類別會定義使用者可執行的動作，您可以指定為回應動作而執行的作業。您可以使用 GlanceModifier.clickable 方法，將 Action 套用至任何元件。

應用程式小工具位於遠端程序，因此動作是在建立時定義，並在遠端程序中執行。在原生 RemoteViews 中，這項操作是透過 PendingIntents 完成。

本頁面說明下列動作：

啟動活動

如要在使用者互動時啟動活動，請使用 GlanceModifier.clickable 修飾符，將 actionStartActivity 函式提供給 Button 或其他可組合項。

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

或者，將地圖 ID 傳送至支援的 composable 上的 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
    }
}

使用者點選時，系統會呼叫所提供 ActionCallback 的 suspend onAction 方法，執行定義的邏輯 (即要求重新整理資料)。

如要在執行動作後更新小工具，請建立新例項並呼叫 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
        // ...
    }
}

上一頁
使用 Glance 進行單元測試
下一頁
追蹤小工具的指標