@capgo/capacitor-widget-kit

개요

@capgo/capacitor-widget-kit gives a Capacitor app two ways to drive widgets and Live Activities:

• 전체 네이티브 위젯 세션: 위젯 UI를 완전히 Swift/Kotlin/Java로 유지하면서 __CAPGO_KEEP_0__이 공유된 JSON 상태와 앱에서 위젯으로 또는 위젯에서 앱으로의 메시지를 소유합니다.
• Full-native widget sessions: keep the widget UI fully in Swift/Kotlin/Java while Capacitor owns shared JSON state and app-to-widget or widget-to-app messages.

개요

모드 선택

모드	추천	주요 API
SVG 템플릿 활동	실시간 활동 또는 위젯 표면이 SVG 출력에서 렌더링	startTemplateActivity, performTemplateAction, listTemplateEvents
전체 네이티브 위젯 세션	네이티브 렌더링 위젯이 공유 상태와 비동기 작업이 필요	startWidgetSession, updateWidgetSession, sendWidgetMessage

두 모드 모두 동일한 앱에 존재할 수 있습니다. 예를 들어, 운동 앱은 빠른 프레임/타이머 제어를 위해 SVG Live Activity를 사용하고 richer 네이티브 레이아웃을 가진 홈 스크린 위젯을 위해 전체 네이티브 위젯 세션을 사용할 수 있습니다.

SVG 템플릿 기능

SVG 템플릿은 인터랙티브 위젯 표면을 위한 필요한 조각을 포함합니다.:

• frames __CAPGO_KEEP_0__ summary, timer이름이 지정된 SVG 변형 details.
• frameMutations or
• timerMutations 스위치, 토글, 또는 프레임을 핫スポ트 액션 후에 통과하는 단계
• patches 시작, 일시 중단, 재개, 토글, 초기화, 중단, 또는 타이머 지속 시간을 변경
• hotspots literal 값, 템플릿, 타임스탬프, 증가치, 토글, 또는 삭제 연산을 사용하여 JSON 상태를 업데이트
• listTemplateEvents 터치 영역을 액션 식별자와 매핑

앱은 위젯에서 발생한 액션을 나중에 처리할 수 있도록 합니다. {{state.title}}, {{timers.rest.remainingText}}Capgo 런타임은 __CAPGO_KEEP_0__와 __CAPGO_KEEP_1__와 같은 플레이스 홀더를 해결하기 전에 네이티브 브리지가 렌더링을 위한 표면을 반환하기 전에 {{meta.template.kind}} Full-Native Bridge Capabilities

Full-Native Bridge Capabilities

네이티브 UI를 렌더링하는 위젯에 대한 전체 네이티브 세션은 다음과 같습니다:

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

완료된 또는 실패한 메시지의 재시도는 기존 결과를 반환하는 대신 결과를 덮어쓰지 않습니다.

공개 API

메소드	설명
areActivitiesSupported	현재 기기에 native template activity bridge가 실행될 수 있는지 확인합니다.
startTemplateActivity	SVG template activity를 저장하고 native Live Activity bridge를 시작합니다.
updateTemplateActivity	활동 정의, 상태 또는 URL을 열어 변경합니다.
endTemplateActivity	실행 중인 활동을 종료하고 optionally 마지막 상태 스냅샷을 저장합니다.
performTemplateAction	선언적 패치, 프레임 변형, 타이머 변형 및 이벤트 로깅을 실행합니다.
getTemplateActivity	저장된 template activity를 한 번 읽습니다.
listTemplateActivities	저장된 template activity 목록을 모두 읽습니다.
listTemplateEvents	template action으로부터 발생한 액션 이벤트를 읽습니다.
acknowledgeTemplateEvents	template 이벤트를 처리한 것으로 표시합니다.
startWidgetSession	공유된 JSON 상태를 기반으로 전체 네이티브 위젯 세션을 시작합니다.
updateWidgetSession	전체 네이티브 위젯 세션 상태를 병합하거나 대체합니다.
stopWidgetSession	전체 네이티브 위젯 세션을 중지하고 최종 상태를 옵션으로 저장합니다.
getWidgetSession	한 번의 전체 네이티브 위젯 세션을 읽습니다.
listWidgetSessions	모든 전체 네이티브 위젯 세션을 목록화합니다.
sendWidgetMessage	앱과 네이티브 위젯 code 사이에 메시지를 큐에 넣습니다.
listWidgetMessages	큐에 있는 브리지 메시지를 목록화합니다.
acknowledgeWidgetMessages	브리지 메시지를 확인합니다.
completeWidgetMessage	비동기 브리지 메시지를 완료하거나 실패합니다.
getPluginVersion	플랫폼 구현 버전 마커를 반환합니다.

네이티브 피스

이 플러그인은 위젯 대상에 대한 네이티브 헬퍼를 포함하여 배포합니다:

• CapgoTemplateWidgetBridge SVG 템플릿 표면을 해석합니다. svg, frameId, hotspots데이터 및 메타데이터.
• CapgoTemplateActionIntent iOS 위젯 버튼을 템플릿 액션과 연결합니다.
• CapgoNativeWidgetBridge 자연스러운 UI 경험을 위해 native 세션과 메시지를 native 위젯 code 에서 로드합니다.
• Android 템플릿 헬퍼는 액션 수신자와 위젯 브리지를 위한 일치하는 동작을 제공합니다.

진실의 근원

API 참조는 src/definitions.ts 플러그인 저장소에서同步됩니다.