위젯킷

@capgo/capacitor-widget-kit을 사용하여

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

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

설치

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

SVG 템플릿 사용 시기

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

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

위젯 액션을 앱에서 처리하세요

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

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 WidgetKit 및 Live Activities를 위한 App Group을 앱과 위젯 확장 대상에 구성하고 CapgoWidgetKitAppGroup 두 개의 Info.plist 파일에 설정하세요. 인터랙티브 버튼은 위젯 확장 대상에서 플러그인 제공하는 네이티브 브리지와 액션 인텐트를 연결해야 합니다.

전체 참조

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

capgo를 사용하는 경우 @capgo/capacitor-widget-kit에서 계속 진행하세요.

__CAPGO_KEEP_0__를 사용하는 경우 @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-widget-kit Using @capgo/capacitor-widget-kit native 플러그인 작업을 계획하기 위해, 그것을 연결하세요. @capgo/capacitor-widget-kit for the implementation detail in @capgo/capacitor-widget-kit, Getting Started Getting Started의 implementation detail에 대해 Capgo Plugin Directory Capgo Plugin Directory의 product workflow에 대해 Capacitor Plugins by Capgo Capacitor-widget-kit의 implementation detail, Capacitor Plugins by Capgo에 대해 플러그인을 추가하거나 업데이트 플러그인을 추가하거나 업데이트하는 implementation detail에 대해