@capgo/capacitor-위젯 키트

개요

@capgo/capacitor-widget-kit Capacitor 앱에 두 가지 방법으로 위젯과 라이브 활동을 구동합니다.

• SVG 템플릿 활동: SVG로 WidgetKit 표면을 정의하고 탭에서 이름이 지정된 프레임을 Switch, 타이머를 일시 중단/재생하고 JSON 상태를 변형하고 앱에서 액션 이벤트를 수집합니다.
• 전체 네이티브 위젯 세션: 위젯 UI를 완전히 Swift/Kotlin/Java로 유지하면서 Capacitor이 공유된 JSON 상태와 앱에서 위젯으로 또는 위젯에서 앱으로의 메시지를 소유합니다.

SVG 템플릿을 사용하여 SVG 문자열을 해결할 수 있는 위젯이 렌더링될 수 있는 경우 SVG 템플릿을 사용하십시오. 전체 네이티브 세션을 사용하여 위젯이 커스텀 네이티브 UI가 필요하지만 여전히 시작, 중단, 동기화 상태 또는 앱에서 비동기 작업을 완료하도록 요청해야 할 경우.

선택 모드

모드	추천	주요 API
SVG 템플릿 활동	라이브 활동 또는 SVG 출력으로 렌더링되는 위젯 표면	startTemplateActivity, performTemplateAction, listTemplateEvents
전체 네이티브 위젯 세션	자원 공유 및 비동기 작업이 필요한 원생 위젯	startWidgetSession, updateWidgetSession, sendWidgetMessage

두 가지 모드도 동일한 앱에 존재할 수 있습니다. 예를 들어, 운동 앱은 SVG Live Activity를 사용하여 빠른 프레임/타이머 제어와 더 풍부한 원생 레이아웃을 가진 홈 스크린 위젯 세션을 사용할 수 있습니다.

SVG 템플릿 기능

SVG 템플릿은 상호 작용 위젯 표면에 필요한 조각을 포함합니다:

• frames 이름이 지정된 SVG 변형 summary, timeror details.
• frameMutations 스위치, 토글, 또는 핫スポ트 액션 후 프레임을 순환하는
• timerMutations 시작, 일시 중단, 재개, 토글, 리셋, 중단, 또는 타이머 지속 시간을 변경
• patches literal 값, 템플릿, 타임스탬프, 증가치, 토글, 또는 삭제 연산을 사용하여 JSON 상태를 업데이트
• hotspots 터치 영역을 액션 식별자와 매핑
• listTemplateEvents 앱은 위젯에서 발생한 액션을 나중에 처리할 수 있습니다.

실행 시간은 __CAPGO_KEEP_0__와 같은 플레이스 홀더를 해결합니다. {{state.title}}, {{timers.rest.remainingText}}그리고 {{meta.template.kind}} 자연적인 브리지가 렌더링을 위한 표면을 반환하기 전에.

전체 네이티브 브리지 기능

네이티브 위젯 __CAPGO_KEEP_0__의 공유 상태와 메타데이터를 생성합니다.

• startWidgetSession creates shared state and metadata for native widget code.
• updateWidgetSession 마지막 상태를 기록하고 세션을 중지합니다.
• stopWidgetSession 앱에서 위젯 또는 위젯에서 앱으로의 작업을 큐합니다.
• sendWidgetMessage 메시지를 수신한 것으로 표시합니다.
• acknowledgeWidgetMessages 비동기 작업의 응답 또는 실패를 저장합니다.
• completeWidgetMessage Full-Native Bridge Capabilities

완료 후 메시지는 중복 처리가 가능합니다: 완료 또는 실패한 메시지를 다시 시도하면 기존 결과가 반환되며 덮어쓰지 않습니다.

공개 API

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

원생 조각

위젯 대상에 대한 네이티브 헬퍼도 제공됩니다.

• CapgoTemplateWidgetBridge __CAPGO_KEEP_0__ SVG 템플릿 표면을 해결합니다. svg, frameId, hotspots, 및 메타데이터.
• CapgoTemplateActionIntent 템플릿 액션에 연결된 인터랙티브 iOS 위젯 버튼을 연결합니다.
• CapgoNativeWidgetBridge 네이티브 위젯 code에서 전체 네이티브 세션 및 메시지를 로드합니다.
• Android 템플릿 헬퍼는 액션 수신자 및 위젯 브리지를 위한 일치하는 동작을 제공합니다.

진실의 근원

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