Getting Started

Instal

Kamu bisa menggunakan Pengaturan Bantu AI untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI kamu menggunakan perintah berikut:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-widget-kit` plugin in my project.

Jika Anda lebih suka Setup Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah ini:

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

Import

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

Pengaturan iOS

Untuk Aktivitas Hidup dan Ekstensi WidgetKit, konfigurasi aplikasi native terlebih dahulu:

• Pilih iOS 17+ untuk tombol Aktivitas Hidup interaktif ketika memungkinkan.
• Tambahkan NSSupportsLiveActivities ke aplikasi Info.plist ketika menggunakan ActivityKit.
• Tambahkan App Group yang sama ke target aplikasi dan target ekstensi widget.
• Atur CapgoWidgetKitAppGroup di kedua Info.plist file ke identifikasi App Group yang dibagikan.

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

Periksa Bantuan

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 telah diresolusi. Plugin menyimpan state, menyelesaikan tempat pengganti, menerapkan aksi sentuh, mengganti frame SVG, dan menjaga kekonsistenan state 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 mengeluarkan event sehingga aplikasi dapat memproses interaksi widget setelah peluncuran atau resume:

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

Pengubahan Frame

Pengubahan frame menulis id frame aktif ke dalam state. Suatu layout dapat membacanya dengan frameIdPath.

Operasi	Sifat
set	Set id frame tertentu. String sederhana dianggap sebagai id frame literal; {{...}} template diresolusi terlebih dahulu.
next	Pindah ke frame berikutnya dari frameIds atau frame yang diumumkan pada surface.
previous	Pindah ke frame sebelumnya.
toggle	Tampilkan perpindahan antara dua frame yang tersedia, 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.

Mutasi Timer

Mutasi timer mengarah ke timer bernama dari definition.timers.

Operasi	Behavior
start / restart	Mulai dari nol menggunakan durasi saat ini.
pause	Simpan waktu yang telah berlalu dan hapus startedAt.
resume	Mulai hanya timer yang tertunda. Timer yang berhenti tetap berhenti sampai ada permulaan atau restart yang eksplisit.
toggle	Pangkas waktu yang berjalan dan markah timer berhenti.
reset	Pangkas waktu yang berjalan dan kembalikan ke idle.
stop	Pangkas kemajuan waktu yang berjalan dan tandai timer berhenti.
setDuration	Rekomputasi status setelah perubahan durasi.

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

Option 2: Sesi Widget Penuh-Native

Pilih mode ini ketika antarmuka widget dibangun dalam native code. Plugin ini memberikan aplikasi dan widget sebuah rekaman sesi bersama 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 ini mencakup pekerjaan yang memerlukan tanggapan lebih lanjut, seperti widget yang meminta aplikasi untuk sinkronisasi 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 bukanlah response:

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

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

Berhenti Sesi Asli

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

API Kelompok

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

Sumber Kebenaran

Referensi jenis lengkap hidup di repository plugin di src/definitions.ts.

Maju terus 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, Capgo Direktori Plugin untuk alur kerja produk di Capgo Direktori Plugin, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin 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.