开始

安装

您可以使用我们的 AI-Assisted Setup 来安装插件。将 Capgo 技能添加到您的 AI 工具中，使用以下命令:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下提示:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

如果您更喜欢手动设置，请按照以下命令安装插件，并遵循以下平台特定的说明：

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

导入

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

iOS设置

为了Live活动和小部件扩展，首先配置原生应用：

• 尽可能使用iOS 17+进行交互式Live活动按钮。
• 添加 NSSupportsLiveActivities 到应用程序 Info.plist 当使用 ActivityKit 时
• 将相同的 App Group 添加到应用程序目标和小部件扩展目标
• 设置 CapgoWidgetKitAppGroup 在两个 Info.plist 文件中添加到共享 App Group 标识符

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

查看支持

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

选项 1：SVG 模板活动

在 widget 可以渲染解析的 SVG 时使用此模式。该插件存储状态、解析占位符、应用点击操作、切换 SVG 框架并保持计时器状态一致。

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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 可以通过热点/动作编程触发相同的动作。应用也可以直接运行它们：

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

处理 widget 事件

动作发出事件，使应用可以在启动或恢复后处理 widget 交互：

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

更新或结束活动

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

框架变动

框架变动会将当前框架的id写入状态。一个布局可以通过读取它来获取当前框架的id frameIdPath.

操作	行为
set	设置一个特定的框架id。普通字符串会被当作字面框架id来处理； {{...}} 模板会在此之前被解析。
next	移动到下一个框架 frameIds 或声明在 surface.
previous	移动到上一个框架
toggle	切换到可用的前两个框架之间，或当前框架和 frameId.

无效的框架 ID 在有已知可选择框架列表的变异时会被忽略，因此状态与渲染表面保持一致。

计时器变异

计时器变异目标一个命名计时器 definition.timers.

操作	行为
start / restart	使用当前持续时间从零开始。
pause	存储已过时间并清除 startedAt.
resume	仅恢复暂停的计时器。停止的计时器保持停止状态，直到显式启动或重启。
toggle	暂停正在运行的计时器或恢复暂停的计时器。
reset	清除已过时间并返回空闲状态。
stop	清除运行时间进度并标记计时器停止。
setDuration	重新计算状态后，根据持续时间变化。

SVG 中可用的定时器绑定是 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}},以及相关字段。

选项 2：全本地小部件会话

Use this mode when the widget UI is built in native code. The plugin gives the app and widget a shared session record and a message queue.

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

const { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

异步小部件消息

消息涵盖需要稍后响应的工作，例如小部件要求应用程序同步数据。

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

要失败该任务，请传递 error 取而代之 response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage 该操作是幂等的。如果消息已经完成或失败，重复调用返回现有消息快照。

停止本机会话

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

API 组

组	API
能力	areActivitiesSupported, getPluginVersion
SVG 活动生命周期	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG 动作和事件	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
原生小部件会话	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
原生小部件消息	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

真实数据来源

完整类型参考在插件仓库中存放于 src/definitions.ts.

继续从 Getting Started

如果您正在使用 Getting Started 为原生插件工作做好准备，连接它到 使用 @capgo/capacitor-widget-kit 为使用 @capgo/capacitor-widget-kit 的原生能力 Capgo 插件目录 为 Capgo 插件目录 中的产品流程 Capacitor 由 Capgo 提供的插件 为 Capacitor 由 Capgo 提供的插件 中的实现细节 添加或更新插件 为添加或更新插件 中的实现细节,以及 Ionic 企业插件替代方案 为 Ionic 企业插件替代方案 中的产品流程