Getting Started

Instal

Anda dapat menggunakan Pengaturan Bantuan AI kami untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI Anda 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 Pengaturan Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah:

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 ketika memungkinkan.
• Tambahkan NSSupportsLiveActivities ke aplikasi Info.plist ketika menggunakan ActivityKit.
• Tambahkan grup aplikasi yang sama ke target aplikasi dan target ekstensi widget.
• Set CapgoWidgetKitAppGroup dalam kedua file ke pengenal App Group bersama. Info.plist Salin ke clipboard

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

Bagian berjudul “Periksa Support”

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

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

Bagian berjudul “Pilihan 1: Aktivitas Template SVG”

Salin ke clipboard

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

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 state timer.

Widget native dapat memicu aksi yang sama melalui pengaturan 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 diluncurkan atau diresume:

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 keadaan. Sebuah layout dapat membacanya dengan frameIdPath.

Operasi	Tindakan
set	Atur id frame tertentu. String sederhana dianggap sebagai id frame literal; {{...}} template diresolusi terlebih dahulu.
next	Pindah ke frame berikutnya dari frameIds atau frame yang dideklarasikan pada surface.
previous	Pindah ke frame sebelumnya.
toggle	Tampilkan 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 sejalan dengan permukaan yang dirender.

Mutasi Timer

Mutasi Timer mengincar timer bernama dari definition.timers.

Operasi	Penggunaan
start / restart	Mulai dari nol menggunakan durasi saat ini.
pause	Simpan waktu yang telah berlalu dan hapus startedAt.
resume	Tetapkan ulang hanya timer yang terhenti. Timer yang berhenti akan tetap berhenti sampai ada permintaan start atau restart yang eksplisit.
toggle	Tetapkan ulang timer yang berjalan atau resume 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.

Option 2: Widget Penuh-Native Sesi

Gunakan mode ini ketika antarmuka pengguna 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 menangani pekerjaan yang memerlukan jawaban 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, lakukan error sebaliknya response:

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

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

Hentikan Sesi Native

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 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, Capgo Direktori Plugin untuk alur kerja produk di Capgo Direktori Plugin, Capacitor Plugin oleh Capgo untuk detail implementasi di Capacitor Plugin oleh Capgo, Mengambah atau Mengupdate Plugin untuk detail implementasi di Mengambah atau Mengupdate Plugin, dan Alternatif Plugin Enterprise Ionic untuk alur kerja produk di Alternatif Plugin Enterprise Ionic.