Widget Kit plugin Capacitor

Menggunakan @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit memungkinkan aplikasi Capacitor menjalankan pengalaman WidgetKit dan Live Activity dalam dua cara:

• Render surface template SVG yang sudah di-resolve dengan pergantian frame, hotspot tap, dan timer pause/play.
• Menjaga widget tetap sepenuhnya native saat aplikasi dan widget berbagi state sesi JSON dan pesan async.

Instal

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

Kapan Menggunakan Template SVG

Gunakan template SVG saat surface widget dapat dideskripsikan sebagai SVG. Aplikasi menyimpan definisi template, native bridge me-resolve placeholder, dan tap widget dapat mengubah state nanti.

Cocok untuk timer workout, kartu status pengiriman, skor olahraga, atau UI ringkas apa pun yang cukup dengan berpindah antar frame bernama.

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

Menangani Widget Actions di App

Aksi widget disimpan sebagai event. Baca dan konfirmasi event tersebut saat aplikasi kembali berjalan atau setelah proses background sync.

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

Kapan Menggunakan Full-Native Sessions

Gunakan sesi full-native jika UI widget lebih baik dibuat langsung menggunakan Swift, Kotlin, atau Java. Capacitor tetap akan memulai dan menghentikan sesi, menjaga state tetap sinkron, serta mengantrekan pekerjaan antara aplikasi dan widget 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 },
});

Antrekan Async Work Antara Widget dan App

Pesan dapat mengalir dari aplikasi ke widget atau sebaliknya. Pesan akan tetap berstatus pending sampai dikonfirmasi dan selesai.

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

Jika job gagal, selesaikan pesan dengan error:

await CapgoWidgetKit.completeWidgetMessage({
  messageId: message.messageId,
  error: 'Sync failed',
});

Hentikan Sesi dengan Bersih

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

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

Catatan Setup Native

Untuk iOS WidgetKit dan Live Activities, konfigurasi App Group pada target aplikasi dan widget extension, lalu atur CapgoWidgetKitAppGroup di keduanya Info.plist file. Tombol interaktif memerlukan widget extension yang menghubungkan native bridge dan action intent yang disediakan plugin.

Referensi Lengkap

• GitHub: https://github.com/Cap-go/capacitor-widget-kit/
• Dokumentasi: /docs/plugins/widget-kit/

Lanjutkan dari Menggunakan @capgo/capacitor-widget-kit

Jika Anda menggunakan Menggunakan @capgo/capacitor-widget-kit untuk merencanakan pekerjaan plugin native, hubungkan dengan @capgo/capacitor-widget-kit untuk detail implementasi di @capgo/capacitor-widget-kit, Panduan Memulai untuk detail implementasi di Getting Started, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi di Plugin Capacitor oleh Capgo, dan Menambahkan atau Memperbarui Plugin untuk detail implementasi di bagian Menambahkan atau Memperbarui Plugin.