Contoh TypeScript API untuk Capacitor dan Capgo

Setiap aplikasi Contoh TypeScript API Untuk membuat Capacitor yang kuat, setiap sistem harus dimulai dengan cara yang sama: dengan antarmuka plugin yang ditipekan. Jelaskan secara eksplisit metode, opsi, dan hasil Promise, dan lapisan web code dan lapisan native berbagi satu kontrak yang ditepati oleh TypeScript.

Tabel Konten

• Bangun Antarmuka Plugin yang Ditipekan Capacitor
  • Cari Tahu Cepat untuk API
  • Tanda Adopsi
  • Manfaat untuk Tim Capacitor
  • Membuat Kasus Bisnis
  • Menggunakan Argument Listener dengan Benar
  • Mengdefinisikan Kontrak Perbarui
  • Mengamankan Saluran dan Kompabilitas
  • Mendaftarkan Listener dengan Aman
  • Menggunakan Metode Pembersihan yang Tepat
  • Menggunakan Input dan Output dengan Tepat
  • Mengorganisir Code untuk Perubahan
  • Mengapa Menggunakan Tipe Hasil Nativ Dinamis?
  • Mengapa Listeners Harus Menghindari Penolakan yang Tidak Dibawah?
  • Mengapa Mengamankan Perbarui Capgo?

Membangun Interface Plugin Capacitor yang Tipe kuat

Interface ini menjelaskan API yang dilihat oleh web code Anda. Implementasi asli di baliknya harus menghormati kontrak tersebut — dan TypeScript memeriksa nama metode, parameter, dan nilai kembalian sebelum aplikasi Anda berjalan.

import { registerPlugin } dari ‘@capacitor/core’;

export interface Status Perangkat { statusOnline: boolean; batteryLevel?: number; }

export interface Plugin Perangkat { getStatus(): Promise}; setLabel(options: { label: string }): Promise<{ saved: boolean }>;

export const Perangkat = registerPlugin(‘Perangkat’);

Ada banyak hal yang terjadi dalam beberapa baris tersebut:

• Jenis kembalian eksplisit pastikan setiap hasil dapat diprediksi.
• Objek pilihan yang ditetapkan periksa properti yang hilang atau salah eja pada saat kompilasi.
• Metode berdasarkan janji kerja asli model yang selesai secara tidak bersamaan.
• Sebuah umum registerPlugin panggilan adalah apa yang menghubungkan web API ke jembatan asli.
• Interface mendokumentasikan kontrak tanpa menambahkan satu byte runtime code.

Setiap situs panggilan mendapatkan perlakuan yang sama:

const status = menunggu Device.getStatus(); console.log(status.online);

menunggu Device.setLabel({ label: 'Produksi' });

Ganti { label: 'Production' } untuk { name: 'Production' } dan compiler menandainya di tempat itu. Itu lebih baik daripada menemukan kesalahan setelah rilis mobile.

The interface juga adalah tempat Anda mengatur nilai opsional dan kasus gagal. Jika sebuah metode native tidak selalu dapat menghasilkan bacaan baterai, batteryLevel?: number menginformasikan setiap pemanggil untuk mengatasi undefined.

Diagram di bawah ini menunjukkan cara metode yang ditipe, opsi, nilai kembali, definisi bridge, dan pengecekan waktu kompilasi terhubung dalam sebuah Capacitor API.

The ide utama: definisi tipe mengalir dari interface web-facing menuju logika platform native, dan pengecekan waktu kompilasi menjaga setiap situs panggilan.

Quick Lookup untuk API Desain

Untuk referensi yang lebih dalam, baca panduan untuk membangun API di TypeScript. Dua kebiasaan yang patut Anda jaga: tinggalkan rahasia dan kunci tanda tangan di luar klien code, dan uji antarmuka terhadap setiap implementasi platform sebelum Anda publikasikan.

Tim mobile harus mengelola JavaScript, native code, izin perangkat, dan layanan platform asinkron semua sekaligus. Sebuah kontrak TypeScript yang kuat berfungsi seperti daftar checklist bersama di setiap batasan, membuat harapan eksplisit sebelum code apa pun mendarat di perangkat iOS atau Android.

Untuk contoh konkret Contoh API TypeScript, bandingkan metode yang mengembalikan Promise<DeviceStatus> dengan satu yang mengembalikan data tidak ditipekan. Versi yang ditipekan memberitahu editor dan setiap reviewer secara spesifik tentang bidang-bidang yang ada. Versi tidak ditipekan memindahkan pekerjaan penemuan ke log runtime, pengujian manual, dan, kasus terburuk, insiden produksi.

Tanda Penerimaan

TypeScript telah bergerak jauh melebihi wilayah niche front-end-nya. Pengadopsian meningkat ke 35% pengembang pada tahun 2024, meningkat dari hanya 12% pada tahun 2017dan lebih dari satu juta GitHub kontributor dijadikan bahasa utama mereka pada tahun 2025. Cari tahu lebih lanjut tentang hal ini jika Anda ingin angka-angka mentah. Jika Anda ingin angka mentah.

That trajectory matters for mobile organizations in practical ways. Hiring, onboarding, and code review increasingly revolve around shared types. Someone joining a Capacitor project can read an interface and understand the expected native behavior without tracing through every implementation.

Typed APIs also make release work easier to reason about. When a method demands a specific options object, a renamed property or a missing field fails at compile time instead of silently producing a half-formed native request.

, ketika perbaikan membutuhkan menit daripada rilis darurat.Ketika suatu perbaikan memakan waktu menit daripada rilis darurat.

Benefits for Capacitor Teams

Cross-platform apps typically expose one web-facing API that sits on top of several native implementations. TypeScript cannot prove every native detail behaves identically, but it can keep your calls consistent across the entire application.

Terapkan tipe eksplisit pada:

• Metode input, termasuk pilihan yang wajib dan opsional
• Hasil promise, sehingga data kesuksesan selalu memiliki bentuk yang dapat diprediksi
• Event dan listener, sehingga callback menangani payload yang diketahui
• Kesalahan dan nilai status, sehingga jalur cadangan tetap terlihat

Struktur tersebut berbuah manfaat ketika mengintegrasikan plugin perangkat atau layanan operasional. Struktur tersebut juga membantu tim yang memeriksa otomatisasi update, di mana saluran yang salah, identifikasi paket, atau bidang kompatibilitas dapat menyebar ke basis pengguna yang luas.

Untuk penjelasan yang lebih dalam terkait pola terkait, baca panduan kami untuk menghasilkan API yang tipe dengan OpenAPI. Panduan tersebut menjelaskan bagaimana definisi yang dibagikan mengurangi pergeseran manual yang biasanya muncul antara dokumentasi API dan aplikasi code.

Membuat Kasus Bisnis

Menggunakan tipe ketat memerlukan investasi awal, terutama ketika JavaScript code yang lebih tua membawa bentuk data yang tidak konsisten. Hasilnya muncul dalam waktu yang lama: refaktor yang lebih kecil, kepemilikan yang lebih jelas, dan banyak sekali kejutan integrasi yang lebih sedikit.

Mulai dengan batasan yang membawa risiko paling banyak:

1. Tentukan interface respons untuk panggilan asli dan remote.
2. Tipekan objek pilihan dan payload acara.
3. Nyalakan periksa compiler ketat secara bertahap.
4. Perlukan periksa tipe sebelum memublikasikan update apa pun.

Untuk tim mobile perusahaan, dasar ini menjaga perawatan yang prediktif di antara platform, rilis, dan kontributor.

Capacitor’s Plugin Orientasi Layar membuatnya sangat baik TypeScript API example because it maps a handful of simple web methods onto platform-specific device behavior. The public contract stays identical across platforms, while iOS and Android each deal with their own native details underneath.

import { registerPlugin } dari ‘@capacitor/core’;

export type OrientasiTipe = | ‘potret-utama’ | ‘potret-kedua’ | ‘lanskap-utama’ | ‘lanskap-kedua’;

export interface OrientasiData { tipe: OrientasiTipe; angle: number; }

export interface OpsiKunci { orientasi: OrientasiTipe; }

export interface PluginOrientasiLayar { orientasi(): Promise }; lock(options: OpsiKunci): Promise }; unlock(): Promise }; addListener( eventName: ‘perubahanOrientasiLayar’, listenerFunc: (data: OrientasiData) => void, ): Promise<{ remove: () => Promise }>; } }>; }

export const OrientasiLayar =\nregisterPlugin(‘ScreenOrientation’);

— membaca orientasi saat ini secara asynchronous

• orientation() Baca orientasi saat ini secara asinkron
• lock() — hanya menerima nilai orientasi yang diketahui
• unlock() — mengembalikan kendali ke perilaku perangkat normal
• addListener() — melepaskan payload yang ditipekan setiap kali orientasi berubah

Sejak setiap metode mengembalikan sebuah Promise, Anda dapat menggunakan pola panggilan yang sama terhadap jembatan asli dan terhadap implementasi browser. Tidak ada cabang, tidak ada kasus khusus.

const current = menunggu ScreenOrientation.orientation();

jika (current.type.startsWith(‘landscape’)) { console.log(Angle: ${current.angle}); }

Tunggu ScreenOrientation.lock({\norientation: ‘landscape-primary’,\n});

Masukkan nilai yang salah seperti landscape-main dan proses pembangunan gagal secara langsung. Itu adalah kesalahan kompilasi yang Anda perbaiki dalam beberapa detik — bukan bug runtime spesifik platform yang Anda cari melalui log perangkat.

Jangan Lupa Menggunakan Argument yang Benar

Listener layak mendapatkan ketegasan yang sama seperti metode biasa. Hindari any di sini karena itu menyembunyikan perbedaan antara payload acara dan hasilnya orientation() mengembalikan.

const handleChange = (data: DataOrientasi) => { document.body.dataset.orientation = data.type; };

const subscription = menunggu ScreenOrientation.addListener( ‘perubahanOrientasiLayar’, handleChange, );

menunggu subscription.remove();

Hanya berbagi satu OrientationData jenis ketika kedua implementasi asli menjamin bidang yang sama. Jika salah satu platform mengabaikan angle, tandai sebagai optional dan paksa pemanggil untuk mengatasi undefined.

Antarmuka adalah kontrak jembatan, bukan implementasi asli. Jadikanlah kecil, prediktif, dan dapat diuji.

Baca informasi tentang perilaku platform, izin, dan langkah instalasi di Capacitor Panduan Plugin Orientasi Layar. One last habit worth adopting: test both valid calls and rejected calls under strict TypeScript settings. That combination catches wrong method names, missing fields, and incompatible listener payloads long before you package your mobile application.

Capgo gives Capacitor teams a way to push JavaScript, CSS, configuration, and asset fixes without sitting through app store review. The trick is treating its update pipeline like any other typed API boundary, so channels, rollout rules, compatibility checks, and rollback decisions stay explicit before a bundle ever reaches a user’s device.

Menentukan Kontrak Perbaruan

Mulai dengan menentukan nilai-nilai yang diterima oleh otomatisasi Anda. Unsur-unsur literal mencegah Anda mengirimkan perbaruan ke saluran yang salah, dan interface membuat hubungan antara bundle dan versi native yang diperlukan menjadi self-documenting.

tipe Saluran = ‘beta’ | ‘staging’ | ‘produksi’;

interface PermintaanPerbaruan { channel: Saluran; bundleVersion: string; minNativeVersion: string; rolloutPercent: number; signed: boolean; }

interface HasilPerbaruan { accepted: boolean; appliedOnNextLaunch: boolean; rollbackEnabled: boolean; }

Contoh yang sederhana Contoh TypeScript API memvalidasi permintaan sebelum mengirimkannya ke klien Capgo:

fungsi async publishUpdate( request: UpdateRequest, ): Promise { if (!request.signed || request.rolloutPercent < 0 || request.rolloutPercent > 100) { throw new Error(‘Permintaan perbaruan tidak aman’); }

return capgo.publish(request);

Nama metode klien yang tepat berubah antara versi Capgo SDK, jadi tutupi dengan interface Anda sendiri. Isolasi ini membayar dirinya setiap kali Anda mengupgrade dan mencegah detail vendor tertentu mengalir ke kodebase Anda.

Jangan Biarkan Saluran dan Kompabilitas

Pilih saluran tidak boleh sembarangan. Rilis produksi memerlukan pengecekan yang lebih ketat daripada eksperimen beta, terutama ketika bundle web memanggil kemampuan native yang tidak ada di versi aplikasi sebelumnya.

fungsi dapatMenginstal ( permintaan: Permintaan Perbarui, versiNativeTerinstal: string, ): boolean { return permintaan.tandaTangan &amp;&amp; versiNativeTerinstal >= permintaan.minNativeVersion; }

Tidak perlu membandingkan versi dengan string biasa. Tarik dalam sebuah library versi semantik yang tepat sehingga 1.10.0 setelah 1.9.0. Sebelum apa pun mencapai saluran, jalankan checklist:

1. Pastikan bundle ditandatangani.
2. Verifikasi saluran target sesuai dengan tujuan.
3. Bandingkan rentang kompatibilitas native dan bundle.
4. Publikasikan ke audiens terbatas terlebih dahulu.
5. Perhatikan signal kegagalan dan siapkan rollback.

Aliran perbarui yang tipe membalikkan kebijakan rilis menjadi code yang dapat diperiksa oleh reviewer dan CI.

Capgo’s pengiriman diferensial dan pengendalian saluran masuk ke pola tersebut dengan baik, dan kemampuan observabilitas perangkatnya memungkinkan tim untuk mengikuti sinyal adopsi atau kegagalan setelahnya. Untuk sisi instrumentasi acara, lihat Capgo guide untuk pengaturan acara kustom.

Kunci tanda tangan dan kredit admin harus berada di server atau sistem CI, bukan di aplikasi yang dikirimkan. Terapkan update pada peluncuran berikutnya, tes rollback dengan bundle yang ditolak sengaja, dan log setiap keputusan dengan hasil yang ditipekan. kombinasi tersebut menjaga pengiriman cepat kompatibel dengan pengendalian rilis mobile yang disiplin.

Listener yang ditipekan adalah yang membuat API asinkron mudah dipercaya. Apakah callback mengikuti orientasi layar atau acara Capgo yang diperbarui, maka harus menerima bentuk payload yang sama di setiap platform — dan kompiler haruslah yang menegakkan itu.

interface UpdateEvent { versi: string; channel: ‘beta’ | ‘produksi’; tersedia: boolean; }

tipe Listener Fungsi (payload: T) =&gt; void;

interface UpdateService { addListener( event: ‘tersediaUpdate’, callback: Listener, ): Promise&lt;{ remove: () =&gt; Promise} removeAllListeners(): Promise; }

Ini Contoh API dengan TypeScript mengikat nama acara ke literal dan mengikat callback ke payload yang ditipekan. Editor Anda akan menyelesaikan otomatis version gratis, dan kompiler menolak callback yang mengharapkan data yang tidak terkait. Ini adalah jumlah setup yang kecil, dan ini akan membayar setiap kali API berubah.

Apakah Anda ingin melihatnya dalam aksi? Tonton walkthrough:

Mendaftar Pembuat Pemberitahuan dengan Aman

Dalam komponen, simpanlah tanggung jawab pendaftaran agar cleanup tetap eksplisit. Pola yang sama dapat masuk ke dalam hook siklus Angular, efek React, dan hook mount Vue tanpa perubahan.

let orientationHandle: { remove: () =&gt; Promise} } | undefined;

fungsi async start() { orientationHandle = await ScreenOrientation.addListener( ‘perubahan orientasi layar’, ({ type, angle }) =&gt; { console.log(type, angle); }, ); }

fungsi async stop() { await orientationHandle?.remove(); orientationHandle = tidak terdefinisi; }

Jalankan cleanup ketika layar hilang — bukan hanya ketika aplikasi tutup sepenuhnya. Lebih baik tidak melakukannya, dan navigasi meninggalkan callback terikat ke sumber acara native. Anda akan mengalami kerja ganda dan pembaruan status yang ketinggalan zaman yang menyakitkan untuk ditemukan.

Setiap framework memberikan Anda hook untuk ini:

• Angular --- trigger pembersihan dari ngOnDestroy
• React --- kembalikan fungsi pembersihan aman asinkron dari useEffect
• Vue --- hapuskan langganan dalam onBeforeUnmount

Setiap addListener harus memiliki jalur penghapusan yang sesuai.

Pilih Metode Pembersihan yang Tepat

Sebuah tanggung jawab yang tepat ketika satu komponen menguasai satu langganan. removeAllListeners() berkilau ketika sebuah layanan memegang beberapa pendengar dan sedang dalam proses reset yang penuh.

fungsi asinkron resetUpdates(service: LayananPembaruan) { await service.removeAllListeners(); }

Tidak tembakkan metode yang luas dari komponen bersama sementara layar lain masih bergantung pada layanan. Ketika kepemilikan lokal, tetaplah dengan individu remove() mengatasi.

Untuk notifikasi Capgo, jaga agar payload pembaruan tetap terpisah dari event perangkat. Lalu, tes registrasi, pengiriman, dan penghapusan secara terpisah — Capgo contoh penggunaan API TypeScript Pada sisi integrasi ada lebih banyak lagi.

Sebelum Anda mengirimkan, periksa tiga hal: apakah penghapusan benar-benar menghapus handler, apakah janji yang ditolak ditangkap, dan tidak ada callback yang dapat memperbarui komponen yang telah dihancurkan. Disiplin ini menjaga aplikasi reaktif Capacitor responsif di Angular, React, dan Vue.

Contoh __CAPGO_KEEP_0__ yang baik Contoh API TypeScript yang baik dimulai dengan nama yang menjelaskan tujuan. Gunakan kata kerja untuk metode, kata benda untuk interface, dan tetap konsisten dengan sufiks seperti Options, Resultdan EventNama yang jelas mengurangi waktu onboarding karena pengembang memahami kontrak tanpa membuka implementasi.

Jaga interface publik kecil. Ungkapkan kemampuan melalui metode yang fokus daripada membuang operasi yang tidak terkait secara longgar ke dalam objek tunggal.

• getStatus() membaca keadaan.
• updateConfig(options) mengubah konfigurasi.
• addListener(event, callback) terdaftar untuk perubahan.

Menentukan Input dan Output dengan Tepat

Mencapai pilihan nama antarmuka ketika parameter dapat berkembang:

interface PublishOptions { channel: ‘beta’ | ‘produksi’; rolloutPercent: number; }

interface PublishResult { versi: string; terima: boolean; }

fungsi async publish( options: PublishOptions, ): Promise {\nreturn client.publish(options);\n}

Jenis-jenis mendapatkan tempat mereka ketika sebuah API mengelilingi berbagai muatan tetapi perlu mempertahankan jenis-jenis spesifik mereka:

interface ApiResponse { data: T; idPengajuan: string; }

fungsi async request(path: string): Promise&lt;ApiResponse&gt;&gt; { return fetchJson&lt;ApiResponse&gt;(path); &gt;(path);

But don’t add generics just to look flexible. A generic should express a real relationship between input and output — otherwise a concrete interface is easier to read and maintain.

terutama di batas-batas native, jaringan, dan pembaruan.terutama di batas-batas native, jaringan, dan pembaruan.

Document behavior right beside the contract. Cover permissions, units, rejected promises, optional fields, and whether a method applies immediately or on the next launch. Inline comments should explain decisions, not restate method names.

Sistemkan Code untuk Perubahan

Terpisahkan jenis tipe, logika klien, adapter platform, dan tes ke dalam file yang dapat diprediksi. Eksport jenis tipe publik dari satu titik masuk dan jaga detail implementasi privat.

Untuk perubahan plugin yang memecah, masukkan interface baru mayor atau lapisan kompatibilitas, biarkan metode yang sudah tidak digunakan tetap ada sementara, dan tuliskan langkah migrasi. Baca lebih lanjut tentang strategi API versi sebelum mengubah konsumen.

Jalankan pengecekan tipe ketat dan uji kontrak di CI sebelum mengirim. Untuk Capgo alur kerja, verifikasi nilai saluran, kompatibilitas asli, bundle yang ditandatangani, dan perilaku rollback sebagai aturan rilis yang ditipekan — ini menjaga pembaruan cepat tetap terkendali seiring pertumbuhan tim, platform, dan integrasi.

Bagaimana Saya Mengetik Hasil Asli Dinamis?

Tidak biarkan any mengalir ke code Anda ketika metode asli mengembalikan data yang tidak dapat diprediksi. Sebaliknya, tuliskan bidang-bidang yang dapat Anda hitung, tandai nilai yang sebenarnya optional dengan ?, dan sanitasi input yang tidak pasti di batas sebelum apa pun yang mengikuti menyentuhnya.

interface Hasil Asli { sukses: boolean; nilai?: string; }

fungsi async readValue(): Promise Konstanta hasil = menunggu NativePlugin.read(); return { sukses: Boolean(hasil.success), nilai: typeof hasil.value === ‘string’ ? hasil.value : tidak ditemukan, };

Metode ini menjaga panggilan Anda aman sambil menjadikan ketidakpastian eksplisit dalam jenisnya sendiri. Untuk melihat pola antarmuka yang lebih luas, ulangi pembangunan API di TypeScript Bagaimana Membuat API di TypeScript.

Bagaimana Membuat Daftar Penerimaan yang Tidak Dibatalkan?

Panggilan balik asinkron harus defensif oleh desain. Tangkap gagal di dalam pendengar itu sendiri daripada mengandalkan sistem acara untuk menelan janji yang ditolak diam-diam.

const handleUpdate = (event: UpdateEvent): void =&gt; { void applyUpdate(event).catch((error: unknown) =&gt; { console.error(‘Gagal memperbarui’, error); }); }

Tahanlah referensi pendaftaran dan hapusnya ketika komponen tidak terpasang. Itu mencegah panggilan ganda dan pembaruan status yang ketinggalan — bagian siklus pendengar menjelaskan ini secara rinci.

Setiap pendengar asinkron membutuhkan jalur kesalahan dan jalur pembersihan.

Bagaimana Saya Melindungi Capgo Perbarui?

Kunci tanda tangan dan kredit administratif tetap di server atau sistem CI Anda. Sama sekali. Klien hanya perlu menerima paket yang ditandatangani dan menggunakan hasil yang ditipekan untuk menampilkan status — tidak untuk membuat tanda tangan.

Sebelum mempublikasikan, aturkan union saluran yang terpisah, jalankan cek kompatibilitas, atur batas perbarui, dan rencanakan jalur rollback Anda. Capgo menangani pengiriman yang ditandatangani, pengendalian saluran, aplikasi peluncuran berikutnya, dan perlindungan rollback untuk Capacitor dan aplikasi Electron. Dokumen mereka menunjukkan bagaimana alur kerja rilis yang ditipekan dapat memperketat pipa update Anda.