处理用户互动

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

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

本页面介绍了以下操作：

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

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

启动 activity

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

在 actionStartActivity 中提供以下任一内容：

• 目标 activity 类
• ComponentName
• 意向

Glance 会根据提供的目标和参数将操作转换为 PendingIntent。在以下示例中，当用户点击按钮时，系统会启动 NavigationActivity：

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

启动服务

与启动 activity 类似，使用某个 actionStartService 方法在用户互动时启动服务。

在 actionStartService 中提供以下任一内容：

• 目标 activity 类
• ComponentName
• 意图

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

发送广播事件

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

在 actionSendBroadcast 中提供以下任一内容：

• 字符串操作
• ComponentName
• 意图
• BroadcastReceiver 类

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

执行自定义操作

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

运行 lambda 操作

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

注意： Lambda 回调在 Service 中运行的 WorkManager 工作器的上下文中运行。以 Android 12 或更高版本为目标平台的应用无法从充当 trampoline 的服务或广播接收器中启动 activity。不要从 lambda 启动 activity，而是使用 actionStartActivity 回调从 GlanceAppWidget 启动 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