处理用户互动

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

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

此页面介绍了以下操作：

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

。

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

启动 activity

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

在 actionStartActivity 中提供以下任一项：

• 目标 activity 类
• ComponentName
• Intent

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

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

启动服务

与启动 activity 类似，使用 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 回调在运行的 WorkManager 工作器上下文中运行 在 Service 中。以 Android 12 或更高版本为目标平台的应用无法启动 activity 来自充当 trampoline 的服务或广播接收器发送提醒。而不是 从 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

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

如需在执行操作后更新 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，以便目标 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