@capgo/capacitor-widget-kit
@capgo/capacitor-widget-kit Capacitor 앱은 WidgetKit 및 Live Activity 경험을 두 가지 방식으로 Capacitor합니다.
- SVG 템플릿을 렌더링하여 프레임 Switching, 탭 핫 스폿, 및 일시 정지/재생 타이머를 지원합니다.
- 앱과 위젯이 JSON 세션 상태 및 비동기 메시지를 공유하는 동안 위젯을 완전히 네이티브로 유지합니다.
설치
bun add @capgo/capacitor-widget-kit
bunx cap sync
SVG 템플릿 사용 시기
위젯 표면이 SVG로 설명될 수 있는 경우 SVG 템플릿을 사용하세요. 앱은 템플릿 정의를 저장하고, 네이티브 브리지는 플레이스 홀더를 해결하고, 위젯 탭은 나중에 상태를 변경할 수 있습니다.
운동 타이머, 배송 상태 카드, 스포츠 점수 또는 이름된 프레임 사이에 Switching만 충분한 경우 등이 좋습니다.
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 });
완전 네이티브 세션 사용 시기
완전 네이티브 세션을 사용할 때는 Swift, Kotlin, 또는 Java에서 직접 위젯 UI를 빌드하는 것이 더 좋습니다. 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를 위해 앱과 위젯 확장 대상에서 앱 그룹을 구성하고 CapgoWidgetKitAppGroup 두 개의 Info.plist 파일에 설정하세요. 인터랙티브 버튼은 위젯 확장에서 플러그인 제공한 네이티브 브리지와 액션 인텐트를 연결해야 합니다.
전체 참조
- GitHub: https://github.com/Cap-go/capacitor-widget-kit/
- 문서: /docs/plugins/widget-kit/
Using @capgo/capacitor-widget-kit
앱을 사용 중이라면 Using @capgo/capacitor-widget-kit Capacitor-__CAPGO_KEEP_0__-widget-kit @capgo/capacitor-widget-kit for the implementation detail in @capgo/capacitor-widget-kit, Capacitor-__CAPGO_KEEP_0__-widget-kit Capacitor-__CAPGO_KEEP_0__-widget-kit Capacitor-Capgo-widget-kit Capacitor-Capgo-widget-kit Capacitor Capgo의 플러그인 for Capacitor 구현 세부사항을 위해 Capgo 플러그인에 의해 Capacitor-__CAPGO_KEEP_0__-widget-kit Capacitor-__CAPGO_KEEP_0__-widget-kit