小部件套件

使用 @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit 让一个 Capacitor 应用驱动小部件和实时活动体验的两种方式：

• 渲染解析的 SVG 模板表面，支持帧切换、点击热点和暂停/播放计时器。
• 保持小部件完全原生化，同时应用和小部件共享 JSON 会话状态和异步消息。

安装

bun add @capgo/capacitor-widget-kit
bunx cap sync

When To Use SVG Templates

使用 SVG 模板

当小部件表面可以用 SVG 描述时，使用 SVG 模板。应用程序存储一个模板定义，原生桥梁解析占位符，widget 点击可以在后续状态中改变。

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>`,
          },
        ],
      },
    },
  },
});

适合的场景包括运动计时器、送货状态卡、体育比分、或任何紧凑的 UI，其中切换到命名帧就足够了。

在 App 中处理小部件动作

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 });

小部件动作会被持久化为事件。读取并确认它们，当应用程序恢复或在后台同步步骤后。

Use full-native sessions when the widget UI is better built directly in Swift, Kotlin, or Java. Capacitor still starts and stops the session, keeps shared state current, and queues work between app and 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 UI 更好地直接在 Swift、Kotlin 或 Java 中构建。__CAPGO_KEEP_0__ 还会启动和停止会话，保持共享状态最新，并在应用程序和小部件之间排队工作。

在 Widget 和 App 之间排队异步工作

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 Activities 配置一个 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-widget-kit 为 @capgo/capacitor-widget-kit 的实现细节 开始使用 为 Getting Started 的实现细节 Capgo 插件目录 为 Capgo 插件目录中的产品工作流程 Capacitor 由 Capgo 提供的插件 为 Capacitor 插件由 Capgo 提供的实现细节，并且 添加或更新插件 为添加或更新插件的实现细节。