处理用户交互

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

应用微件在远程进程中运行，因此操作在创建时定义，并在远程进程中执行。在原生 RemoteViews 中，此操作通过 PendingIntents 完成。

本页介绍了以下操作

启动 Activity

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

在 actionStartActivity 中提供以下任一项

目标 Activity 类
ComponentName
Intent

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

@Composable
fun MyContent() {
    // ..
    Button(
        text = "Go Home",
        onClick = actionStartActivity<MyActivity>()
    )
}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 函数传递给 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 方法，执行已定义的逻辑（即请求刷新数据）。

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

向操作提供参数

如需向操作提供额外信息，请使用 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

使用 Glance 进行单元测试

管理和更新 GlanceAppWidget