Widget Kit

Build WidgetKit and Live Activity surfaces from Capacitor with SVG frames, timers, action hotspots, or full-native widget state sync

每周下载量

0

GitHub 个星星

3

演示

WebP 动画演示

WidgetKit 和 Live Activity 模板控件以 WebP 动画演示的形式显示。

源资产

WebP 动画演示，展示模板小组件的状态和控件由 Capacitor 驱动 — 小组件模板流程

{"targetLanguage":"Simplified Chinese","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["","","使用 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit","让一个 __CAPGO_KEEP_0__ 应用程序驱动 WidgetKit 和 Live Activity 体验的两种方式：","渲染解析的 SVG 模板表面，具有帧切换、点击热点和暂停/播放计时器功能。","保持 widget 完全原生化，同时应用程序和 widget 共享 JSON 会话状态和异步消息。","安装","何时使用 SVG 模板","使用 SVG 模板时，widget 表面可以用 SVG 描述。应用程序存储一个模板定义，原生桥梁解析占位符，widget 点击可以后续改变状态。","适合的场景包括运动计时器、送货状态卡、体育比赛成绩或任何紧凑的 UI，其中切换到命名帧足够了。","在应用程序中处理 Widget 动作","Widget 动作被持久化为事件。读取并确认它们，当应用程序恢复或在后台同步步骤后。"]}

"

Using @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit lets a Capacitor app drive WidgetKit and Live Activity experiences in two ways:

"
"

"

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

"

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

"

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仍然启动和停止会话，保持共享状态当前，并在应用程序和小部件之间排队工作。 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 },
});

小部件和应用程序之间的异步工作队列

消息可以从应用程序流向小部件或从小部件流向应用程序。它们保持等待，直到被确认和完成。

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 全参考

__CAPGO_KEEP_0__:

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 的实现细节开始使用查看开始使用的实现细节 Capgo 插件目录查看 Capgo 插件目录中的产品工作流程 Capacitor 插件由 Capgo 提供 for the implementation detail in Capacitor Plugins by Capgo, and 添加或更新插件为添加或更新插件的实现细节提供