본문으로 바로가기
플러그인으로 돌아가기
@capgo/capacitor-widget-kit
튜토리얼
github.com/Cap-go에 의해

위젯 키트

Capacitor에서 SVG 프레임, 타이머, 액션 핫 스폿 또는 전체 네이티브 위젯 상태 동기화와 함께 위젯 키트 및 라이브 활동 표면을 빌드합니다.

안내서

위젯 키트에 대한 튜토리얼

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 파일을 인터랙티브 버튼은 위젯 확장 기능이 플러그인 제공된 네이티브 브리지와 액션 인텐트를 연결해야 합니다.

전체 참조