위젯 키트

Using @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit Capacitor 앱은 WidgetKit 및 Live Activity 경험을 두 가지 방식으로 제어할 수 있습니다.

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

위젯 액션을 앱에서 처리

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

When To Use Full-Native Sessions

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

Queue Async Work Between Widget And App

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

Native Setup Notes

iOS WidgetKit 및 Live Activities의 경우 앱과 widget 확장 대상에서 App Group을 구성하고 CapgoWidgetKitAppGroup 두 개의 Info.plist 파일에서 설정하세요. 인터랙티브 버튼은 플러그인 제공된 네이티브 브리지와 액션 인텐트를 연결하는 widget 확장 대상이 필요합니다.

Full Reference

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

capgo을 사용하여 capacitor-widget-kit을 계속 진행하세요.

__CAPGO_KEEP_0__을 사용하는 경우 capgo을 사용하여 capacitor-widget-kit을 사용하는 경우 자연스러운 네이티브 플러그인 작업을 계획하려면 __CAPGO_KEEP_0__을 __CAPGO_KEEP_1__-widget-kit과 연결하세요. capgo을 capacitor-widget-kit과 연결하여 capgo의 구현 세부 정보를 확인하세요. for the implementation detail in @capgo/capacitor-widget-kit, Getting Started의 구현 세부 정보를 확인하세요. __CAPGO_KEEP_0__ 플러그인 디렉토리 Capgo Capgo 제품 워크플로우 디렉토리에서 Capacitor 플러그인에 의해 Capgo Capacitor 플러그인에 의해 Capgo의 구현 세부 사항, 그리고 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트의 구현 세부 사항.