@capgo/capacitor-widget-kit

Capacitor를 사용하여 SVG 프레임, 타이머, 액션 핫스팟 또는 전체 네이티브 위젯 상태 동기화를 지원하는 WidgetKit 및 Live Activity 화면을 빌드하세요

개요

Capacitor를 사용하여 SVG 프레임, 타이머, 액션 핫스팟 또는 전체 네이티브 위젯 상태 동기화를 지원하는 WidgetKit 및 Live Activity 화면을 빌드하세요

다음으로 시작하세요 areActivitiesSupported() 그리고 아래에 나열된 다른 핵심 메서드도 살펴보세요.

플랫폼 지원

플랫폼	지원	참고 사항
iOS	지원	네이티브
Android	지원	네이티브
웹	아니요	Capacitor.getPlatform()으로 보호하세요

Siri, Shortcuts 및 App Intents

Widget Kit은 하지 마세요 대신 WidgetKit, ActivityKit 템플릿 Live Activities, 대화형 iOS 컨트롤을 번들링된 LiveActivityIntent 타입 (CapgoTemplateActionIntent, CompleteSetIntent)을 통해 지원합니다. 이 타입은 저장된 템플릿 상태를 업데이트하고 템플릿 이벤트 로그 (listTemplateEvents / acknowledgeTemplateEvents).

에 추가합니다. 하지 마세요 사용자 정의 단축어 구문, AppShortcutsProvider JavaScript 엔티티 카탈로그, Spotlight 항목 또는 Apple 앱 스키마를 등록합니다. 이를 위해 @capgo/capacitor-app-intents 를 사용하세요. 다음 도구들과의 전체 비교는 expo-app-intents, 참고: Siri, 단축어 및 위젯.

데모

모드 선택

모드	추천 대상	주요 API
SVG 템플릿 방식	SVG 출력을 통해 렌더링되는 Live Activities 또는 위젯 화면	`startTemplateActivity`, `performTemplateAction`, `listTemplateEvents`
전체 네이티브 위젯 방식	공유 상태 및 비동기 작업이 필요한 네이티브 렌더링 위젯	`startWidgetSession`, `updateWidgetSession`, `sendWidgetMessage`

두 모드를 한 앱에서 모두 사용할 수 있습니다. 예를 들어, 운동 앱에서 빠른 프레임/타이머 제어를 위해 SVG Live Activity를 사용하고, 더 풍부한 네이티브 레이아웃이 필요한 홈 화면 위젯에는 전체 네이티브 위젯 방식을 사용할 수 있습니다.

SVG 템플릿 기능

SVG 템플릿에는 인터랙티브 위젯 화면 구현에 필요한 요소들이 포함되어 있습니다:

frames 다음과 같은 이름이 지정된 SVG 변형을 유지합니다: summary, timer, 또는 details.
frameMutations 핫스팟 액션 후 switch, toggle 또는 프레임 전환을 수행합니다.
timerMutations 타이머를 시작, 일시 중지, 재개, 토글, 리셋, 중지하거나 지속 시간을 변경합니다.
patches 리터럴 값, 템플릿, 타임스탬프, 증감, 토글 또는 unset 작업을 사용하여 JSON 상태를 업데이트합니다.
hotspots 탭 영역을 액션 식별자에 매핑합니다.
listTemplateEvents 앱이 위젯에서 발생한 액션을 나중에 처리할 수 있도록 합니다.

런타임은 다음과 같은 플레이스홀더를 해결합니다: {{state.title}}, {{timers.rest.remainingText}}, 그리고 {{meta.template.kind}} 네이티브 브릿지가 렌더링을 위한 surface를 반환하기 전에 처리됩니다.

Full-Native Bridge 기능

Full-native 세션은 자체 UI를 네이티브로 렌더링하는 위젯을 위한 기능입니다:

startWidgetSession 네이티브 위젯 code를 위한 공유 상태 및 메타데이터를 생성합니다.
updateWidgetSession 상태를 병합 또는 교체하고 세션을 다시 활성 상태로 표시합니다.
stopWidgetSession 최종 상태를 기록하고 세션을 중지 상태로 표시합니다.
sendWidgetMessage 앱-위젯 간 또는 위젯-앱 간의 작업을 큐에 추가합니다.
acknowledgeWidgetMessages 메시지를 수신됨 상태로 표시합니다.
completeWidgetMessage 비동기 작업에 대한 응답 또는 실패 기록을 저장합니다.

메시지는 완료 후 멱등성이 보장됩니다. 완료되었거나 실패한 메시지를 재시도하면 기존 결과를 덮어쓰지 않고 그대로 반환합니다.

공개 API

메서드	설명
`areActivitiesSupported`	현재 기기에서 native template activity bridge를 실행할 수 있는지 확인합니다.
`startTemplateActivity`	SVG template activity를 저장하고 native Live Activity bridge를 시작합니다.
`updateTemplateActivity`	activity 정의, 상태 또는 open URL을 교체합니다.
`endTemplateActivity`	실행 중인 activity를 종료하고 선택적으로 마지막 상태 스냅샷을 저장합니다.
`performTemplateAction`	declarative patches, frame mutations, timer mutations 및 event logging을 실행합니다.
`getTemplateActivity`	저장된 template activity 하나를 읽어옵니다.
`listTemplateActivities`	저장된 모든 template activity 목록을 불러옵니다.
`listTemplateEvents`	template actions에서 발생한 action events를 읽어옵니다.
`acknowledgeTemplateEvents`	template events를 처리 완료 상태로 표시합니다.
`startWidgetSession`	공유된 JSON state를 기반으로 full-native widget 세션을 시작합니다.
`updateWidgetSession`	full-native widget 세션의 state를 병합하거나 교체합니다.
`stopWidgetSession`	full-native widget 세션을 중단하고 선택적으로 최종 state를 저장합니다.
`getWidgetSession`	전체 네이티브 위젯 세션 하나를 읽어옵니다.
`listWidgetSessions`	모든 전체 네이티브 위젯 세션 목록을 가져옵니다.
`sendWidgetMessage`	앱과 네이티브 위젯 code 사이의 메시지를 큐에 추가합니다.
`listWidgetMessages`	큐에 대기 중인 브릿지 메시지 목록을 가져옵니다.
`acknowledgeWidgetMessages`	브릿지 메시지를 확인 완료(acknowledged) 상태로 표시합니다.
`completeWidgetMessage`	비동기 브릿지 메시지를 완료 또는 실패 처리합니다.
`getPluginVersion`	플랫폼 구현 버전 마커를 반환합니다.

Native 구성 요소

이 플러그인은 위젯 타겟을 위한 네이티브 헬퍼도 함께 제공합니다:

CapgoTemplateWidgetBridge SVG 템플릿 서피스를 다음으로 렌더링합니다: svg, frameId, hotspots, 및 메타데이터.
CapgoTemplateActionIntent 대화형 iOS 위젯 버튼을 템플릿 액션에 연결합니다.
CapgoNativeWidgetBridge 네이티브 위젯 code에서 전체 네이티브 세션과 메시지를 로드합니다.
Android 템플릿 헬퍼는 일치하는 액션 리시버 및 위젯 브릿지 동작을 제공합니다.

Source of Truth

API 참조는 다음에서 동기화됩니다: src/definitions.ts 플러그인 저장소 내의

사용 중이라면 @capgo/capacitor-widget-kit CI/CD 자동화를 계획하려면, 다음을 연결하세요 @capgo/capacitor-widget-kit 사용하기 네이티브 기능은 @capgo/capacitor-widget-kit 사용하기, Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 제품 워크플로우는 Capgo 연동, CI/CD 통합 구현 세부 사항은 CI/CD 연동.