Getting Started

Install

bun add @capgo/capacitor-widget-kit
bunx cap sync

Impor

import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

Pengaturan iOS

Untuk kegiatan hidup dan ekstensi WidgetKit, konfigurasi aplikasi asli terlebih dahulu:

• Gunakan iOS 17+ untuk tombol kegiatan hidup interaktif saat mungkin.
• Tambahkan NSSupportsLiveActivities ke aplikasi Info.plist saat menggunakan ActivityKit.
• Tambahkan grup aplikasi yang sama ke target aplikasi dan target ekstensi widget.
• Atur CapgoWidgetKitAppGroup dalam Info.plist kedua file ke identifikasi grup aplikasi yang dibagikan.

<key>CapgoWidgetKitAppGroup</key>
<string>group.app.capgo.widgetkit.exampleapp.widgetkit</string>

Periksa Support

const { supported, reason } = await CapgoWidgetKit.areActivitiesSupported();

if (!supported) {
  console.log('WidgetKit bridge unavailable:', reason);
}

Pilihan 1: Template Aktivitas SVG

Gunakan mode ini ketika widget dapat menampilkan SVG yang terpecahkan. Plugin menyimpan state, menyelesaikan tempat-tempat pengganti, menerapkan aksi sentuh, mengganti frame SVG, dan menjaga kekonsistenan timer.

const { activity } = await CapgoWidgetKit.startTemplateActivity({
  activityId: 'workout-session-1',
  openUrl: 'myapp://workout/session-1',
  state: {
    title: 'Chest Day',
    frame: 'summary',
    restDurationMs: 90000,
  },
  definition: {
    id: 'workout-card',
    timers: [
      {
        id: 'rest',
        durationPath: 'state.restDurationMs',
      },
    ],
    actions: [
      {
        id: 'next-frame',
        eventName: 'widget.frame.changed',
        frameMutations: [
          {
            op: 'next',
            path: 'frame',
            surface: 'lockScreen',
          },
        ],
      },
      {
        id: 'toggle-rest',
        eventName: 'widget.timer.toggled',
        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>`,
          },
        ],
      },
    },
  },
});

Jalankan Aksi Dari Aplikasi

Widget native dapat memicu aksi yang sama melalui pengkabelan hotspot/aksi. Aplikasi juga dapat menjalankannya secara langsung:

await CapgoWidgetKit.performTemplateAction({
  activityId: activity.activityId,
  actionId: 'toggle-rest',
  sourceId: 'app-pause-play-button',
});

Proses Event Widget

Aksi mengirimkan event sehingga aplikasi dapat memproses interaksi widget setelah diluncurkan atau diaktifkan kembali:

const { events } = await CapgoWidgetKit.listTemplateEvents({
  activityId: activity.activityId,
  unacknowledgedOnly: true,
});

for (const event of events) {
  console.log('Widget event:', event.eventName, event.state, event.timers);
}

await CapgoWidgetKit.acknowledgeTemplateEvents({
  activityId: activity.activityId,
});

Perbarui atau Selesai Aktivitas

await CapgoWidgetKit.updateTemplateActivity({
  activityId: activity.activityId,
  state: {
    title: 'Back Day',
    frame: 'summary',
    restDurationMs: 120000,
  },
});

await CapgoWidgetKit.endTemplateActivity({
  activityId: activity.activityId,
  state: { title: 'Workout complete', frame: 'summary' },
});

Mutasi Frame

Mutasi frame menulis id frame aktif ke dalam state. Sebuah layout dapat membacanya dengan frameIdPath.

Operasi	Pengaturan
set	Set __CAPGO_KEEP_0__ id frame. String-string biasa dianggap sebagai id frame literal; {{...}} template-template diresolusi terlebih dahulu.
next	Pindah ke frame selanjutnya dari frameIds atau frame-frame yang dideklarasikan pada surface.
previous	Pindah ke frame sebelumnya.
toggle	Toggle antara dua frame yang tersedia pertama, atau antara frame saat ini dan frameId.

Id frame yang tidak valid diabaikan ketika mutasi memiliki daftar frame yang dapat dipilih, sehingga keadaan tetap sinkron dengan permukaan yang dirender.

Pengaturan Waktu

Pengaturan waktu mengarah ke timer bernama dari definition.timers.

Aksi	Perilaku
start / restart	Mulai dari nol menggunakan durasi saat ini.
pause	Simpan waktu yang telah berlalu dan hapus. startedAt.
resume	Teruskan hanya timer yang terhenti. Timer yang berhenti akan tetap berhenti sampai ada permintaan start atau restart yang eksplisit.
toggle	Panggil timer yang berjalan atau teruskan timer yang terhenti.
reset	Hapus waktu yang telah berlalu dan kembali ke idle.
stop	Hapus kemajuan waktu jalannya dan tandai timer sebagai berhenti.
setDuration	Rekomputasi status setelah perubahan durasi.

Koneksi timer tersedia untuk SVG sebagai {{timers.<id>.remainingText}}, {{timers.<id>.elapsedMs}}, {{timers.<id>.status}}, dan bidang terkait.

Pilihan 2: Sesi Widget Penuh-Native

Pilih mode ini ketika antarmuka widget dibangun dalam native code. Plugin memberikan aplikasi dan widget sebuah rekaman sesi yang sama dan antrian pesan.

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 { sessions } = await CapgoWidgetKit.listWidgetSessions();
console.log('Known widget sessions:', sessions);

Pesan Widget Synchronous

Pesan yang dibahas adalah pekerjaan yang memerlukan jawaban lebih lanjut, seperti widget yang meminta aplikasi untuk sinkron data.

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

Untuk gagal pekerjaan, pass error bukan response:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Network unavailable',
});

completeWidgetMessage adalah idempoten. Jika pesan sudah selesai atau gagal, panggilan ulang akan mengembalikan snapshot pesan yang sudah ada.

Hentikan Sesi Native

await CapgoWidgetKit.stopWidgetSession({
  widgetId: session.widgetId,
  state: { isRunning: false },
});

Grup API

Grup	API
Kemampuan	areActivitiesSupported, getPluginVersion
Aktivitas siklus SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
SVG aksi dan event	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sesi widget native	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Pesan widget native	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Sumber Kebenaran

Referensi tipe penuh hidup di repositori plugin di src/definitions.ts.

Teruskan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan pekerjaan plugin native, hubungkannya dengan Menggunakan @capgo/capacitor-widget-kit untuk kemampuan native di Menggunakan @capgo/capacitor-widget-kit, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin-Plugin Capacitor oleh Capgo untuk detail implementasi di Plugin-Plugin Capacitor oleh Capgo, Menambahkan atau Mengupdate Plugin untuk detail implementasi di Menambahkan atau Mengupdate Plugin, dan Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic.