虽然功能块和 widget 都会在远程系统界面上显示您的内容，但构建它们需要采用不同的方法。将现有卡片迁移到 widget 意味着从刚性布局生成过渡到动态声明式界面，从而解锁新功能并简化开发模型。
选择实现策略
如果您要迁移的应用维护的是旧版卡片，则必须决定应用如何向系统提供内容。虽然全新的 widget 应使用单个 Widget Service，但具有现有卡片的应用必须选择保留这两个服务或整合到单个 Widget Service。
推荐：双服务（卡片 + widget）
对于所有具有现有卡片的应用，建议保留卡片和 widget。提供两个不同的服务可在不同设备上提供尽可能好的用户体验。
- Tile Service： 扩展
TileService并为androidx.wear.tiles.action.BIND_TILE_PROVIDER声明 intent 过滤器。 - Widget Service：扩展
GlanceWearWidgetService并为androidx.glance.wear.action.BIND_WIDGET_PROVIDER声明 intent 过滤器。 - 逻辑分组：在 widget
配置中使用
group属性，将新实现与现有TileService相关联。 这样，系统便可将它们识别为单个逻辑组件，并在 Wear OS 7 或更高版本上自动将用户的现有轮播界面槽位迁移到新的 widget。
双服务设置的系统行为 ：
| 操作系统 / 设备功能 | 最终体验 |
|---|---|
| Wear OS 3 | 使用卡片 |
| Wear OS 4、5、6 | 使用卡片 |
| Wear OS 7（不支持部分高度，例如 Pixel Watch） | 使用卡片 |
| Wear OS 7（支持部分高度，例如 Galaxy Watch） | 使用 widget |
替代方案：单服务（仅 widget）
单个服务同时处理这两种协议。虽然这种方法实现起来更快，但它依赖于兼容模式，以便在运行较低版本 Wear OS 的设备上将 widget“适配”为卡片。
如果您选择这种方法，请执行以下操作：
- 指定两个 intent 过滤器 ：您的服务必须包含
androidx.wear.tiles.action.BIND_TILE_PROVIDER和androidx.glance.wear.action.BIND_WIDGET_PROVIDER的 intent 过滤器。这样可确保您的 widget 显示在 Wear 4、5、6 和 7（如果需要）中的卡片界面上。 - 保留现有服务名称（实现无缝升级） ：如果您要替换的是一个活跃卡片，则保留相同的服务类名称可确保轮播界面中包含该卡片的用户会自动看到该卡片更新为新的 widget。虽然 Wear OS 7 在 widget 配置 XML 中使用
group属性以逻辑方式关联不同的组件，但低于 7 的 Wear OS 版本依赖于服务名称来将它们识别为“相同”的组件。如果您希望使用新的服务名称，您的应用仍可正常运行；不过，在运行 Wear OS 6 或更低版本的设备上，用户需要手动将 widget 重新添加到轮播界面。
单服务设置的系统行为 ：
| 操作系统 / 设备功能 | 最终体验 |
|---|---|
| Wear OS 3 | 不支持 |
| Wear OS 4、5、6 | widget 显示为全屏卡片 |
| Wear OS 7（不支持部分高度） | widget 转换为卡片 |
| Wear OS 7（支持部分高度） | 使用 widget |
*需要渲染器 1.6 或更高版本。
界面翻译提示
将界面从 ProtoLayout（卡片）翻译为 Remote Compose (widget) 时，心理模型会从命令式布局构建器转变为状态驱动的基于 Compose 的架构，其中界面更新通过重组来处理。 请谨记以下原则：
- 采用声明式界面：将命令式 ProtoLayout 构建器
(
LayoutElementBuilders) 替换为声明式 Remote Compose 等效项， 例如RemoteText、RemoteColumn和RemoteBox。 - 专注于核心内容 (
mainSlot) ：部分高度 widget（例如SMALL和LARGE容器类型）提供了一个专注的、可一览无余的界面。 与其将密集的、全屏的卡片布局一对一移植，不如简化设计，以突出显示主要内容区域中的主要信息。 - 重新设计边缘对齐的操作：在卡片架构中，与屏幕紧密贴合的
组件（如
EdgeButton）锚定到专用bottomSlot。由于部分高度 widget 直接集成到垂直滚动界面中，因此这种固定的bottomSlot范例不再存在。由于边缘对齐的按钮通常充当非常突出的主要操作，因此迁移需要经过深思熟虑的界面重新设计，而不是直接替换组件。评估主要操作的替代 UX 策略：- 内嵌操作：将内嵌
RemoteButton直接 集成到您的mainSlot布局中。 - 容器点按：使用
PendingIntentAction使整个 widget 容器可点按，从而整合互动。 - 内容透视 ：重新评估 widget 的焦点。如果没有专用的操作槽位，请考虑显示更丰富的可一览无余的数据，并依赖于单次点按来打开完整应用，而不是在 widget 界面上隔离特定操作。
- 内嵌操作：将内嵌
- 迁移事件处理（操作与 lambda） ：卡片依赖于互动（如
LoadAction）来触发完整服务回调，以刷新界面。 Wear Widget 由客户端驱动。标准 Compose lambda 无法远程运行；请改为提供可序列化的 声明式操作 （如ValueChange或PendingIntentAction）。将这些操作与声明式状态（例如rememberMutableRemoteInt）相结合，以支持即时界面更新，而无需应用往返。 - 调整尺寸和类型：迁移布局尺寸时，最好使用
延迟布局解析，使用
RemoteDp（例如10.rdp），而不是使用 标准Dp。这样可确保系统渲染器在显示时正确计算像素值。同样，使用 Remote Compose 扩展函数（Color为.rc，String为.rs，Dp为.rdp）可无缝转换标准 Kotlin 和 Remote Compose 类型。 - 查看示例代码：如需查看有关如何在 Remote Compose 中构建 布局、应用语义排版和管理状态的全面示例，请探索 Wear OS 示例 代码库中提供的官方示例代码。