Using @capgo/capacitor-widget-kit

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

프레임 Switching, Tap Hotspot, Pause/Play 타이머와 같은 SVG 템플릿 표면을 렌더링합니다.
앱과 위젯이 JSON 세션 상태 및 비동기 메시지를 공유하는 동안 위젯이 완전히 네이티브로 유지됩니다.

설치

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

SVG 템플릿 사용 시기

위젯 표면이 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>`,
          },
        ],
      },
    },
  },
});

앱에서 Widget 동작 처리하기

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

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 세션 사용할 때

Full-Native 세션을 사용할 때는 Swift, Kotlin, 또는 Java에서 widget UI가 직접적으로 더 잘 구축될 때입니다. Capacitor 여전히 세션을 시작하고 중단하고 공유 상태를 최신 상태로 유지하고 앱과 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 },
});

Widget와 앱 간의 비동기 작업 큐

메시지는 앱에서 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 },
});

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

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에 대한 Native 설정 참고

iOS WidgetKit 및 Live Activities에 대해 앱과 widget 확장 대상에 App Group을 구성하고 CapgoWidgetKitAppGroup 양쪽 모두에 Info.plist 파일을 인터랙티브 버튼은 위젯 확장 기능이 플러그인 제공된 네이티브 브리지와 액션 인텐트를 연결해야 합니다.

전체 참조

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

위젯 키트

위젯 키트에 대한 튜토리얼