跳转到正文
Capgo - 构建、发布并更新 Capacitor 应用 Capgo

快速入门

GitHub

安装

“安装”章节

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

终端窗口
bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

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';

快速入门

章节标题为“快速入门”
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';


const result = await CapgoWidgetKit.areActivitiesSupported();
console.log(result);

示例：startTemplateActivity

标题为“示例：startTemplateActivity”的章节
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';


const result = await CapgoWidgetKit.startTemplateActivity({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

示例：startTemplateWidget

标题为“示例：startTemplateWidget”的章节
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';


const result = await CapgoWidgetKit.startTemplateWidget({
  definition: {
    id: 'id-123',
    layouts: {},
  },
  state: {},
});
console.log(result);

常见坑点

章节标题为“常见陷阱”
  • 原生同步：运行 bunx cap sync 在插件升级后。
  • 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

iOS 配置

“iOS 设置”章节

对于 Live Activities 和 WidgetKit 扩展，请先配置原生应用：

  • 请尽可能使用 iOS 17+，以支持交互式 Live Activity 按钮。
  • 添加 NSSupportsLiveActivities 到应用中 Info.plist 在使用 ActivityKit 时。
  • 请将相同的 App Group 添加到 app target 和 widget extension target 中。
  • 设置 CapgoWidgetKitAppGroup 在两者中 Info.plist 文件关联到共享的 App Group identifier。
<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

查看支持情况

标题为 “Check Support” 的章节
const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();


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

方案 1：SVG Template Activity

标题为 “Option 1: SVG Template Activity” 的章节

当 widget 可以渲染解析后的 SVG 时，请使用此模式。该 plugin 会负责存储状态、解析占位符、应用点击操作、切换 SVG 帧并保持 timer 状态一致。

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

在 App 中执行操作

标题为“在 App 中执行操作”的章节

原生小组件可以通过其热点/操作绑定触发相同的操作。App 也可以直接运行这些操作：

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

处理 Widget 事件

标题为“处理 Widget 事件”的章节

操作会发出事件，以便 App 在启动或恢复后处理 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,
});

在 iOS 上，小组件扩展按钮可以调用打包的 LiveActivityIntent 辅助函数（CapgoTemplateActionIntent）并写入同一个事件日志。这与 Siri 快捷指令短语或 Shortcuts App 不同。请参阅 Siri、快捷指令与小组件.

更新或结束 Activity

标题为“更新或结束 Activity”的章节
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' },
});

Frame 变更

标题为“Frame 变更”的章节

Frame 变更会将当前活跃的 frame id 写入 state。随后可以通过 frameIdPath.

Operation行为
set设置特定的 frame id。普通字符串将被视为字面量 frame id； {{...}} 模板会优先进行解析。
next从以下位置跳转至下一帧 frameIds 或在以下声明的 frames 上 surface.
previous移至上一帧。
toggle在首两个可用 frame 之间切换，或在当前 frame 与 frameId.

当 mutation 拥有已知的可选择 frame 列表时，无效的 frame id 会被忽略，从而确保状态与渲染界面保持一致。

定时器 Mutation

标题为 “Timer Mutations” 的章节

Timer mutations 针对来自 definition.timers.

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

计时器绑定可供 SVG 使用，形式为 {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}，以及相关字段。

方案 2：全原生 Widget 会话

标题为“方案 2：全原生 Widget 会话”的章节

当 Widget UI 使用原生 code 构建时，请使用此模式。该插件为 App 和 Widget 提供共享的会话记录和消息队列。

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

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

若要使任务失败，请传递 error 而不是 response:

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

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

停止 Native Session

标题为“停止 Native Session”的章节
await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

API 分组

标题为“API Groups”的章节
GroupAPI
能力areActivitiesSupported, getPluginVersion
SVG 生命周期startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG 操作与事件performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Native widget 会话startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Native widget 消息sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

单一事实来源

标题为“单一事实来源”的部分

完整的类型参考请查看插件仓库： src/definitions.ts.

从入门指南继续

“从入门指南继续”章节

如果你正在使用 快速入门 要规划原生插件工作，请将其与 使用 @capgo/capacitor-widget-kit 针对使用 @capgo/capacitor-widget-kit 时的原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。