Mulai Menggunakan

Instal

Anda dapat menggunakan Pengaturan AI Bantu 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 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 Langsung dan Ekstensi WidgetKit, konfigurasi aplikasi asli terlebih dahulu:

• Gunakan iOS 17+ untuk tombol Aktivitas Interaktif yang dapat diakses ketika memungkinkan.
• Tambahkan NSSupportsLiveActivities ke aplikasi Info.plist ketika menggunakan ActivityKit.
• Tambahkan grup aplikasi yang sama ke target aplikasi dan target ekstensi widget.
• Setel CapgoWidgetKitAppGroup di kedua Info.plist file ke identifikasi Grup Aplikasi yang dibagikan.

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

Cek Bantuan

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

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

Option 1: Template Aktivitas SVG

Pilih mode ini ketika widget dapat menampilkan SVG yang sudah terpecahkan. Plugin menyimpan keadaan, menyelesaikan tempat penempatan, menerapkan aksi sentuh, mengganti frame SVG, dan menjaga keadaan timer tetap konsisten.

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

Operasi	Behavior
set	Setel id frame tertentu. String sederhana dianggap sebagai id frame literal; {{...}} template diperiksa terlebih dahulu.
next	Pindah ke frame berikutnya dari frameIds atau frame yang dideklarasikan pada surface.
previous	Berpindah ke frame sebelumnya.
toggle	Toggle antara dua frame yang tersedia pertama, 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	Perilaku
start / restart	Mulai dari nol menggunakan durasi saat ini.
pause	Simpan waktu yang telah berlalu dan hapus startedAt.
resume	Mulai kembali hanya timer yang terhenti. Timer yang berhenti tetap berhenti sampai dimulai atau diulang secara eksplisit.
toggle	Pauskan timer yang berjalan atau mulai kembali timer yang terhenti.
reset	Waktu yang telah berlalu dibersihkan dan kembali ke idle.
stop	Progress waktu eksekusi dibersihkan dan timer dihentikan.
setDuration	Status direkalkulasi setelah perubahan durasi.

Keterkaitan 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 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 menangani pekerjaan yang memerlukan respons lebih lanjut, seperti widget 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 gagalkan pekerjaan, lakukan error sebaliknya dari response:

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

completeWidgetMessage Jika pesan sudah selesai atau gagal, panggilan ulang akan mengembalikan snapshot pesan yang sudah ada.

Hentikan Sesi Asli

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

API Kelompok

Kelompok	API
Kemampuan	areActivitiesSupported, getPluginVersion
Siklus Hidup Aktivitas SVG	startTemplateActivity, updateTemplateActivity, endTemplateActivity, getTemplateActivity, listTemplateActivities
Aksi dan Event SVG	performTemplateAction, listTemplateEvents, acknowledgeTemplateEvents
Sesi Widget Asli	startWidgetSession, updateWidgetSession, stopWidgetSession, getWidgetSession, listWidgetSessions
Pesan Widget Asli	sendWidgetMessage, listWidgetMessages, acknowledgeWidgetMessages, completeWidgetMessage

Sumber Kebenaran

Referensi jenis penuh hidup di repositori plugin di src/definitions.ts.

Teruskan dari Getting Started

Jika Anda menggunakan Mulai Menggunakan untuk merencanakan pekerjaan plugin native, hubungkannya dengan Menggunakan @capgo/capacitor-widget-kit untuk kemampuan native di Menggunakan @capgo/capacitor-widget-kit, Daftar Direktori Plugin Capgo untuk alur kerja produk di Daftar Direktori Plugin Capgo, Plugin-Plugin Capacitor oleh Capgo untuk detail implementasi di Plugin-Plugin Capacitor 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.