指南
如何在 Capacitor 中使用小部件套件
使用 @capgo/capacitor-widget-kit
@capgo/capacitor-widget-kit 让一个 Capacitor 应用程序驱动小部件套件和 Live 活动体验的两种方式：
- 渲染解析的 SVG 模板表面，具有帧切换、点击热点和暂停/播放计时器功能。
- 保持小部件完全本地化，同时应用程序和小部件共享 JSON 会话状态和异步消息。
安装
bun add @capgo/capacitor-widget-kit
bunx cap sync
何时使用 SVG 模板
使用 SVG 模板时，widget 表面可以用 SVG 描述。应用程序存储一个模板定义，原生桥梁解析占位符，widget 点击可以后续改变状态。
适合的场景包括运动计时器、送货状态卡、体育比分、或任何紧凑的 UI，其中切换到命名帧就足够了。
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';
const { activity } = await CapgoWidgetKit.startTemplateActivity({
activityId: 'session-1',
state: {
title: 'Chest Day',
frame: 'summary',
restDurationMs: 90000,
},
definition: {
id: 'workout-card',
timers: [{ id: 'rest', durationPath: 'state.restDurationMs' }],
actions: [
{
id: 'next-frame',
frameMutations: [{ op: 'next', path: 'frame', surface: 'lockScreen' }],
},
{
id: 'toggle-rest',
timerMutations: [{ op: 'toggle', timerId: 'rest' }],
},
],
layouts: {
lockScreen: {
width: 100,
height: 40,
frameIdPath: 'state.frame',
frames: [
{
id: 'summary',
hotspots: [{ id: 'switch', actionId: 'next-frame', x: 0, y: 0, width: 100, height: 40 }],
svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{state.title}}</text></svg>`,
},
{
id: 'timer',
hotspots: [{ id: 'pause-play', actionId: 'toggle-rest', x: 0, y: 0, width: 100, height: 40 }],
svg: `<svg viewBox="0 0 100 40"><text x="6" y="22">{{timers.rest.remainingText}}</text></svg>`,
},
],
},
},
},
});
在应用程序中处理 Widget 动作
Widget 动作会被持久化为事件。读取并确认它们，当应用程序恢复或在后台同步步骤后。
const { events } = await CapgoWidgetKit.listTemplateEvents({
activityId: activity.activityId,
unacknowledgedOnly: true,
});
for (const event of events) {
console.log(event.actionId, event.state, event.timers);
}
await CapgoWidgetKit.acknowledgeTemplateEvents({ activityId: activity.activityId });
何时使用全原生会话
使用全原生会话时，widget UI 更好地直接在 Swift、Kotlin 或 Java 中构建。Capacitor 还是启动和停止会话，保持共享状态最新，并在应用程序和widget 之间排队工作code。
const { session } = await CapgoWidgetKit.startWidgetSession({
widgetId: 'native-session-1',
kind: 'workout-controls',
state: { isRunning: true, selectedSetId: 'set-1' },
metadata: { accent: '#00d69c' },
});
await CapgoWidgetKit.updateWidgetSession({
widgetId: session.widgetId,
merge: true,
state: { isRunning: false },
});
widget 和应用程序之间排队异步工作
消息可以从应用程序流向widget 或widget 流向应用程序。它们会等待确认和完成。
const { message } = await CapgoWidgetKit.sendWidgetMessage({
widgetId: session.widgetId,
direction: 'widgetToApp',
name: 'syncWorkoutSet',
payload: { setId: 'set-1' },
expectsResponse: true,
});
await CapgoWidgetKit.acknowledgeWidgetMessages({ messageIds: [message.messageId] });
await CapgoWidgetKit.completeWidgetMessage({
messageId: message.messageId,
response: { synced: true },
});
如果任务失败，请将消息完成为错误：
await CapgoWidgetKit.completeWidgetMessage({
messageId: message.messageId,
error: 'Sync failed',
});
停止会话干净
await CapgoWidgetKit.endTemplateActivity({
activityId: activity.activityId,
state: { title: 'Workout complete', frame: 'summary' },
});
await CapgoWidgetKit.stopWidgetSession({
widgetId: session.widgetId,
state: { isRunning: false },
});
原生设置说明
对于 iOS WidgetKit 和 Live 活动，配置应用程序和widget 扩展目标的 App Group，并设置 CapgoWidgetKitAppGroup 在两个文件中 Info.plist 文件中。需要交互式按钮的扩展，需要将插件提供的原生桥接和动作意图连接起来。
全局参考
- GitHub: https://github.com/Cap-go/capacitor-widget-kit/
- 文档：/docs/plugins/widget-kit/
继续使用@capgo/capacitor-widget-kit
如果您正在使用 使用@capgo/capacitor-widget-kit 来规划原生插件工作，连接它与 @capgo/capacitor-小部件套件 在@capgo/capacitor-widget-kit中实现详细信息 开始使用 为开始使用中的实现细节 Capgo 插件目录 为Capgo 插件目录中的产品工作流 Capacitor 由 Capgo 提供的插件 为Capacitor 由 Capgo 提供的插件中的实现细节 添加或更新插件 为添加或更新插件中的实现细节