Widget Kit

Menggunakan @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit memungkinkan aplikasi Capacitor mengendalikan pengalaman WidgetKit dan Aktivitas Hidup dalam dua cara:

• Mengrender permukaan template SVG yang terpecahkan dengan mengganti frame, hotspot sentuh, dan timer pause/play.
• Jaga widget sepenuhnya asli sementara aplikasi dan widget berbagi status sesi JSON dan pesan async.

Install

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

Menggunakan Template SVG Kapan

Menggunakan template SVG ketika permukaan widget dapat dijelaskan sebagai SVG. Aplikasi menyimpan definisi template, jembatan asli menyelesaikan tempat, dan sentuhan widget dapat mengubah status kemudian.

Contoh yang cocok termasuk timer olahraga, kartu status pengiriman, skor olahraga, atau UI kompak mana pun di mana beralih antara frame bernama cukup.

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

Tangani Aksi Widget Di Aplikasi

Aksi widget disimpan sebagai acara. Baca dan akui mereka ketika aplikasi kembali atau setelah langkah sinkronisasi latar belakang.

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

Menggunakan Sesinya Asli Penuh Kapan

Menggunakan sesi asli penuh ketika UI widget lebih baik dibangun secara langsung di Swift, Kotlin, atau Java. Capacitor masih memulai dan menghentikan sesi, menjaga status bersama terkini, dan mengantre kerja 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 },
});

Antre Kerja Async Antara Widget Dan Aplikasi

Pesan dapat mengalir dari aplikasi ke widget atau widget ke aplikasi. Mereka tetap menunggu sampai diakui dan diselesaikan.

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 pekerjaan gagal, lengkapi pesan dengan kesalahan:

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

Berhenti Sesi dengan Baik

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

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

Catatan Pengaturan Asli

Untuk WidgetKit dan Aktivitas Hidup iOS, konfigurasi sebuah Grup Aplikasi pada target aplikasi dan ekstensi widget, dan atur CapgoWidgetKitAppGroup di kedua Info.plist file. Tombol interaktif memerlukan ekstensi widget yang menghubungkan jembatan native yang disediakan plugin dan intent aksi.

Referensi Lengkap

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

Teruskan dari Menggunakan @capgo/capacitor-widget-kit

Jika Anda menggunakan Menggunakan @capgo/capacitor-widget-kit untuk merencanakan pekerjaan plugin native, hubungkannya dengan @capgo/capacitor-kit-widget untuk detail implementasi di @capgo/capacitor-kit-widget, Mengawali untuk detail implementasi di Mengawali, 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, dan Menambahkan atau Mengupdate Plugin untuk detail implementasi di Menambahkan atau Mengupdate Plugin.