Getting Started

Instalasi

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 ini:

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

Import

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

Pengaturan iOS

Untuk Live Activities dan WidgetKit extension, konfigurasi aplikasi native terlebih dahulu:

• Gunakan iOS 17+ untuk tombol Live Activity interaktif ketika memungkinkan.
• Tambahkan NSSupportsLiveActivities ke aplikasi Info.plist ketika menggunakan ActivityKit.
• Tambahkan grup aplikasi yang sama ke target aplikasi dan target ekstensi widget.
• Atur CapgoWidgetKitAppGroup dalam kedua hal Info.plist file-file ke identifikasi App Group bersama.

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

Periksa Support

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 sudah terpecahkan. Plugin menyimpan state, menyelesaikan tempat-tempat yang kosong, menerapkan aksi ketika disentuh, mengganti frame SVG, dan menjaga agar state 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 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 Berakhir 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	Set ID frame tertentu. String-string biasa dianggap sebagai ID frame literal; {{...}} template diterjemahkan terlebih dahulu.
next	Pindah ke frame berikutnya dari frameIds atau daftar frame yang dideklarasikan pada surface.
previous	Pindah ke frame sebelumnya.
toggle	Tampilkan 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	Sikap
start / restart	Mulai dari nol menggunakan durasi saat ini.
pause	Simpan waktu yang telah berlalu dan hapus startedAt.
resume	Tetapkan hanya timer yang terhenti. Timer yang berhenti akan tetap berhenti sampai dimulai atau diulang secara eksplisit.
toggle	Tetapkan timer yang berjalan atau lanjutkan 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.

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

Pilihan 2: Sesi Widget Penuh-Native

Pilih 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 yang dibahas di sini adalah pekerjaan yang memerlukan respons lebih lanjut, seperti widget yang meminta aplikasi untuk sinkron 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 bukan response:

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

completeWidgetMessage berlaku sekali saja. 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
Siklus 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 tipe lengkap hidup di repository plugin di src/definitions.ts.

Lanjutkan 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, 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 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.