위젯 킷

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

@capgo/capacitor-widget-kit Capacitor 앱은 위젯 키트 및 라이브 활동 경험을 두 가지 방식으로 구동합니다:

• 해당하는 SVG 템플릿 표면을 렌더링하고 프레임 Switching, 탭 핫 스폿 및 일시 정지/재생 타이머를 지원합니다.
• 앱과 위젯이 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>`,
          },
        ],
      },
    },
  },
});

앱에서 위젯 액션 처리

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

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 세션을 사용할 때는 위젯 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 위젯킷과 Live 활동을 위한 경우, 앱과 위젯 확장 대상에 App Group을 구성하고 CapgoWidgetKitAppGroup 두 파일 모두에 설정합니다. 인터랙티브 버튼은 위젯 확장에서 플러그인 제공된 네이티브 브리지와 액션 인텐트를 연결해야 합니다. Info.plist 전체 참조

__CAPGO_KEEP_0__:

• https://GitHub.com/Cap-go/__CAPGO_KEEP_1__-widget-kit/ https://github.com/Cap-go/capacitor-widget-kit/
• __CAPGO_KEEP_0__를 사용하여 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit를 계속 사용하세요.

capgo를 사용하여 @capgo/capacitor-widget-kit를 사용하는 경우

__CAPGO_KEEP_0__를 사용하여 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit와 연결하세요. capgo를 사용하여 @capgo/capacitor-widget-kit를 사용하세요. __CAPGO_KEEP_0__를 사용하여 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit를 사용하세요. capgo를 사용하여 @capgo/capacitor-widget-kit를 사용하세요. for the implementation detail in @capgo/capacitor-widget-kit, 시작하기 Capacitor-__CAPGO_KEEP_0__-widget-kit Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, and Capacitor 플러그인 디렉토리 Capacitor 앱을 위한 __CAPGO_KEEP_0__