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

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

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

Install

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

SVG 템플릿을 사용할 때

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

__CAPGO_KEEP_0__에서 사용할 때 적합한 예로는 운동 타이머, 배송 상태 카드, 스포츠 점수, 또는 이름된 프레임 간 Switching만으로 충분한 콤팩트 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>`,
          },
        ],
      },
    },
  },
});

__CAPGO_KEEP_0__

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

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 세션 사용 시기

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

iOS WidgetKit 및 Live Activities에 대한 네이티브 설정 주의사항

iOS WidgetKit 및 Live Activities에 대한 앱 그룹을 앱 및 위젯 확장 대상에 구성하고 두 파일 모두에 설정하세요. CapgoWidgetKitAppGroup 위젯 확장에서 인터랙티브 버튼을 사용하려면 플러그인 제공 네이티브 브리지와 액션 인텐트를 연결해야 합니다. Info.plist __CAPGO_KEEP_1__

전체 참조

GitHub: https://github.com/Cap-go/capacitor-widget-kit/
문서: /docs/plugins/widget-kit/

위젯 키트

위젯 키트에 대한 튜토리얼