Lompat ke konten utama
Capgo logo
Kembali ke plugin
@capgo/capacitor-kit-widget
Tutorial
oleh github.com/Cap-go

Kit Widget

Buat permukaan WidgetKit dan Aktivitas Hidup dari Capacitor dengan kerangka SVG, timer, hotspot aksi, atau sinkronisasi keadaan widget penuh-native

Unduhan/minggu

0

GitHub Bintang

1

Panduan

Tutorial Widget Kit

Menggunakan @capgo/capacitor-widget-kit

@capgo/capacitor-widget-kit Memungkinkan aplikasi Capacitor mengemudikan pengalaman WidgetKit dan Aktivitas Hidup dengan dua cara:

  • Mengrenderkan permukaan template SVG yang telah disesuaikan dengan penggantian frame, hotspot sentuh, dan timer pause/play.
  • Menggunakan widget secara penuh native sambil aplikasi dan widget berbagi status sesi JSON dan pesan async.

Install

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

Kapan Menggunakan Template SVG

Pilih template SVG ketika permukaan widget dapat dijelaskan sebagai SVG. Aplikasi menyimpan definisi template, jembatan native menyelesaikan tempat-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 penggantian antara frame yang dinamai sudah 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 event. 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 });

Kapan Menggunakan Sesi Penuh-Native

Gunakan sesi penuh-native ketika antarmuka UI widget lebih baik dibangun secara langsung di Swift, Kotlin, atau Java. Capacitor masih memulai dan menghentikan sesi, menjaga keadaan bersama terkini, dan mengantre 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 Pekerjaan Synchronous 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',
});

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 Pengaturan Native

Untuk WidgetKit iOS dan Aktivitas Hidup, konfigurasi sebuah Kelompok 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 niat aksi.

Referensi Lengkap