处理用户互动

Glance 通过 Action 类简化了用户互动处理。Glance 的 Action 类定义了用户可以执行的操作，并且您可以指定为响应该操作而执行的操作。您可以使用 GlanceModifier.clickable 方法将 Action 应用于任何组件。

应用 widget 位于远程进程中，因此操作是在创建时定义的，执行发生在远程进程中。在原生 RemoteViews 中，此操作通过 PendingIntents 完成。

本页介绍了以下操作：

• 启动 activity
• 启动服务
• 发送广播事件
• 运行回调

注意 ：如需查看有关如何处理操作的示例，请参阅 ActionAppWidget.kt。

启动 activity

如需在用户互动时启动 activity，请通过 GlanceModifier.clickable(..) 修饰符将 actionStartActivity 函数提供给 Button 或其他可组合项。

在 actionStartActivity 中提供以下其中一项：

• 目标 activity 类
• ComponentName
• 一个 Intent

Glance 会将 Action 转换为 PendingIntent，并提供提供的目标和参数。在以下示例中，NavigationActivity 会在用户点击该按钮时启动：

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

启动服务

与启动 activity 类似，您可以使用任一 actionStartService 方法在用户互动时启动服务。

在 actionStartService 中提供以下其中一项：

• 目标 activity 类
• ComponentName
• intent

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

发送广播事件

使用以下任一 actionSendBroadcast 方法在用户互动时发送广播事件：

在 actionSendBroadcast 中提供以下其中一项：

• 字符串操作
• ComponentName
• intent
• BroadcastReceiver 类

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

执行自定义操作

Glance 可以使用 lambda 操作或 actionRunCallback 执行操作，例如在用户互动时更新界面或状态，而不是启动特定目标。

运行 lambda 操作

您可以使用 lambda 函数作为对界面交互的回调。

注意 ：lambda 回调在 Service 中运行的 WorkManager 工作器环境中运行。以 Android 12 或更高版本为目标平台的应用无法从充当 trampoline 的服务或广播接收器启动 activity。请使用 actionStartActivity 回调从 GlanceAppWidget 启动 activity，而不是从 lambda 启动 activity。

例如，将 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

在用户点击时，系统会调用所提供的 ActionCallback 的 suspend onAction 方法，执行定义的逻辑（即请求刷新数据）。

如需在执行操作后更新 widget，请创建一个新实例并调用 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

注意 ：Glance 使用自定义异步 BroadcastReceiver 来处理用户点击，并调用所提供 ActionCallback 的 onRun 方法。这可以延长执行时间，但需遵守某些限制。任何耗时或耗用任务都应偏移到 Worker 等位置。

为操作提供参数

如需为操作提供额外的信息，请使用 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() }
    }
}
GlanceSnippets.kt

在下方，这些参数包含在用于启动 activity 的 intent 中，允许目标 activity 检索它。

    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