위젯 키트

@capgo/capacitor-위젯-키트를 사용하면

@capgo/capacitor-widget-kit Capacitor 앱은 위젯 키트 및 라이브 활동 경험을 두 가지 방식으로 제어할 수 있습니다.

• 해당하는 SVG 템플릿 표면을 렌더링하고 프레임 Switching, 탭 핫 스폿 및 일시 정지/재생 타이머를 지원합니다.
• 앱과 위젯이 JSON 세션 상태 및 비동기 메시지를 공유하는 동안 위젯을 완전히 네이티브로 유지합니다.

설치

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

When To Use SVG Templates

SVG 템플릿을 사용할 때는 위젯 표면이 SVG로 설명될 수 있는 경우입니다. 앱은 템플릿 정의를 저장하고, 네이티브 브리지에서는 홀더를 해결하고, 위젯 탭은 나중에 상태를 변경할 수 있습니다.

운동 타이머, 배송 상태 카드, 스포츠 점수 또는 이름된 프레임 간에 Switching이 충분한 compact 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>`,
          },
        ],
      },
    },
  },
});

위젯 액션은 이벤트로 저장됩니다. 앱이 재개되거나 배경 동기화 단계 후에 읽고 확인하세요.

When To Use Full-Native Sessions

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

Full-native 세션을 사용할 때는 위젯 UI가 직접 Swift, Kotlin, 또는 Java로 빌드될 때가 좋습니다. __CAPGO_KEEP_0__ 여전히 세션을 시작하고 중단하고 공유 상태를 최신 상태로 유지하며 앱과 위젯 간의 작업을 큐합니다. __CAPGO_KEEP_1__.

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

메시지는 앱에서 위젯으로 또는 위젯에서 앱으로 흐릅니다. 완료 및 확인될 때까지 대기합니다.

작업이 실패하면 에러와 함께 메시지를 완료하세요:

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

__CAPGO_KEEP_0__

For iOS WidgetKit and Live Activities, configure an App Group on the app and widget extension targets and set CapgoWidgetKitAppGroup in both Info.plist files. Interactive buttons require a widget extension that wires the plugin-provided native bridge and action intent.

Full Reference

• GitHub https://github.com/Cap-go/capacitor-widget-kit/
• Docs: /docs/plugins/widget-kit/

Keep going from Using @capgo/capacitor-widget-kit

iOS WidgetKit과 Live Activities를 사용하는 경우 앱과 위젯 확장 대상에 App Group을 구성하고 설정하세요. Using @capgo/capacitor-widget-kit 전체 참조 @capgo/capacitor-widget-kit implementation detail in @capgo/capacitor-widget-kit 에서 Getting Started implementation detail in Getting Started 에서 Capgo 플러그인 디렉토리 Capgo 플러그인에 대한 __CAPGO_KEEP_1__의 제품 워크플로우 implementation detail in Capacitor 플러그인에 대한 Capgo의 제품 워크플로우 에서 for the implementation detail in Capacitor Plugins by Capgo, and implementation detail in 플러그인 추가 또는 업데이트 에서 Footer