TypeScript API Example for Capacitor and Capgo

Jeder Erfolg TypeScript Beispiel für API for Capacitor begins the same way: with a typed plugin interface. Spell out your methods, options, and Promise results explicitly, and your web code and the native layer share one contract that TypeScript actually enforces.

Inhaltsverzeichnis

• Erstellen Sie eine stark typisierte Capacitor-Plugin-Schnittstelle
  • Rapid Lookup für API-Design
  • Anzeichen für die Übernahme
  • Vorteile für Capacitor-Teams
  • Geschäftsfälle begründen
  • Typen Sie Argumente von Listenern korrekt
  • Aktualisierungsverträge definieren
  • Kanäle und Kompatibilität schützen
  • Listener sicher registrieren
  • Wählen Sie die richtige Methode zum Aufräumen
  • Eingaben und Ausgaben genau tippen
  • Organisieren Sie Code für Änderungen
  • Wie sollte ich dynamische native Ergebnisse tippen?
  • Wie können Listener unbehandelte Ablehnungen vermeiden?
  • Wie schütze ich Capgo-Updates?

Erstellen Sie eine stark typisierte Capacitor-Plugin-Schnittstelle

Die Schnittstelle beschreibt die API Ihres Web code. Die native Implementierung dahinter muss dieses Abkommen einhalten – und TypeScript überprüft Methodennamen, Parameter und Rückgabewerte, bevor Ihre App überhaupt läuft.

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

export interface GeräteStatus { online: boolean; batterieLevel?: number; }

export interface GerätePlugin { getStatus(): Promise}; setLabel(options: { label: string }): Promise<{ gespeichert: boolean }>; }

export const Gerät = registerPlugin}(‘Gerät’);

Es geht in diesen wenigen Zeilen viel vor:

• Explicit Rückgabetypen stellen sicher, dass jeder Ergebnis vorhersehbar ist.
• Typisierte Optionenobjekte catch missing or misspelled properties at compile time.
• Versprechen-basierte Methoden asynchrone native Arbeit, die abgeschlossen wird.
• Ein allgemeiner registerPlugin Aufruf Das ist, was die Web API mit der native Bridge verbindet.
• Interfaces dokumentieren den Vertrag ohne eine Byte Laufzeit code hinzuzufügen.

Jeder Aufrufort erhält die gleiche Behandlung:

const status = await Gerät.getStatus(); console.log(status.online);

await Device.setLabel({ label: ‘Produktion’ });

Ersetzen { label: 'Production' } durch { name: 'Production' } und die Compilerflaggt es sofort. Das übertrifft die Entdeckung des Fehlers nach einer mobilen Veröffentlichung.

Die Schnittstelle ist auch der Ort, an dem Sie optionale Werte und Fehlerfälle modellieren. Wenn eine native Methode nicht immer eine Batterieladung liefern kann, batteryLevel?: number erzählt jedem Aufrufer, wie er damit umgehen soll undefined.

Das folgende Diagramm zeigt, wie typisierte Methoden, Optionen, Rückgabewerte, Bridge-Definitionen und Zeitpunktüberprüfungen innerhalb eines Capacitor API miteinander verbunden sind.

Das Kernkonzept: Typdefinitionen fließen von der webfassenden Schnittstelle in Richtung native Plattformlogik, und Zeitpunktüberprüfungen wachen über jeden Aufruf.

Rapid Lookup für API-Design

Für eine tiefergehende Referenz, lesen Sie die Anleitung zum Erstellen von APIs in TypeScriptZwei Gewohnheiten, die man beibehalten sollte: Gehe im Client code geheime Daten und Signaturzertifikate aus und teste die Schnittstelle vor der Veröffentlichung gegen jede Plattformimplementierung.

Mobile-Teams müssen JavaScript, native code, Geräteberechtigungen und asynchrone Plattformdienste gleichzeitig handhaben. starker TypeScript-Vertrag verhält sich wie eine gemeinsame Checkliste an jeder dieser Grenzen, indem sie Erwartungen explizit macht, bevor sich ein code auf einem iOS- oder Android-Gerät abspielt.

Für einen konkreten Ein TypeScript-API-Beispiel, vergleichen Sie eine Methode, die eine Promise<DeviceStatus> mit einer, die untypisierte Daten zurückgibt. Die getippte Version teilt Ihrem Editor und jedem Rezensenten genau mit, welche Felder existieren. Die ungetippte Version verlagert diese Entdeckungsarbeit auf Laufzeitprotokolle, manuelle Tests und, im schlimmsten Fall, Produktionsfehler.

Adoptionszeichen

TypeScript hat sich gut über seinen Frontend-Nischen hinaus entwickelt. Die Adoption stieg auf 35% der Entwickler im Jahr 2024, up from just 12% im Jahr 2017und mehr als eine Million GitHub Beiträge als ihre Hauptsprache aufgelistet haben. Eintauchen Sie in die vollständigen TypeScript-Zahlenerhebungen wenn Sie die Rohzahlen haben möchten.

Dieser Trend ist für mobile Organisationen in praktischen Wege wichtig. Die Einstellung, Einarbeitung und code Überprüfung werden zunehmend um gemeinsame Typen herum kreiseln. Wenn jemand einem Capacitor Projekt beitritt, kann er eine Schnittstelle lesen und das erwartete native Verhalten ohne das Durchlaufen jedes Implementierungsdetails verstehen.

Typisierte APIs machen die Arbeit mit Releases einfacher zu verstehen. Wenn eine Methode ein bestimmtes Optionsobjekt verlangt, schlägt ein umbenannter Eigenschaft oder ein fehlendes Feld bereits bei der Kompilierung fehl, anstatt stillschweigend einen halbgebildeten native Anfrage zu erzeugen.

Starke Typisierung verschiebt kritische Feedback links, wenn ein Fix nur Minuten statt einer Notfall-Release dauert.

Vorteile für Capacitor Teams

Cross-plattform-Anwendungen offenbaren typischerweise eine webfassende API , die sich auf mehrere native Implementierungen legt. TypeScript kann nicht beweisen, dass jede native Details identisch verhält, aber es kann Ihre Aufrufe konsistent über die gesamte Anwendung halten.

Anwenden Sie explizite Typen auf:

• Eingabeparameter, einschließlich erforderlicher und optionaler Optionen
• Versprechungsresultate, so hat Erfolgsdaten immer eine vorhersehbare Form
• Events und Hörer, so rufen Callbacks bekannte Payloads ab
• Fehler und Statuswerte, so bleiben Fallback-Pfade sichtbar

Diese Struktur lohnt sich, wenn man Geräteplugins oder Betriebsdienste integriert. Sie hilft auch Teams bei der Überprüfung der Update-Automatisierung, wo ein falscher Kanal, ein Bundle-Identifier oder ein Kompatibilitätsfeld sich auf eine große Benutzerbasis auswirken kann.

Für eine tiefergehende Einführung in verwandte Muster, lesen Sie unser Leitfaden zum Erstellen von getypten APIs mit OpenAPI. Er beschreibt, wie gemeinsame Definitionen den manuellen Drift reduzieren, der normalerweise zwischen API Dokumentation und Anwendungscode code auftritt.

Die Geschäftsfall Erstellung

Strikter Typing erfordert zwar einige Vorauszahlungen, insbesondere wenn älteres JavaScript code inkonsistente Datenformen enthält. Der Erfolg zeigt sich im Laufe der Zeit: kleinere Refaktorisierungen, klare Verantwortlichkeiten und viel weniger Überraschungen bei der Integration.

Beginnen Sie mit den Grenzen, die das größte Risiko darstellen:

1. Definieren Sie Schnittstellen für native und remote Aufrufe.
2. Typen Sie Ihre Optionenobjekte und Ereignisdaten.
3. Schalten Sie die strikten Compilerprüfungen schrittweise ein.
4. Überprüfe Typen vor der Veröffentlichung einer beliebigen Aktualisierung.

Für mobile Teams in Unternehmen bildet diese Grundlage eine vorhersehbare Wartung über Plattformen, Releases und Beiträger ab.

Capacitor’s ScreenOrientationPlugin ist ein großartiges Ein TypeScript-Beispiel für API weil es eine Handvoll einfacher Webmethoden auf plattformspezifische Geräteverhalten abbildet. Der öffentliche Vertrag bleibt identisch über Plattformen, während iOS und Android jeweils mit ihren eigenen nativen Details unterhalb zu tun haben.

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

export type OrientierungTyp = | ‘portrait-primary’ | ‘portrait-secondary’ | ‘landscape-primary’ | ‘landscape-secondary’;

export interface OrientierungDaten { typ: OrientierungTyp; winkel: number; }

export interface SperreOptionen { orientierung: OrientierungTyp; }

export interface BildschirmorientierungPlugin { orientierung(): Promise}; sperran(options: SperreOptionen): Promise}; entsperren(): Promise}; addListener( eventName: ‘bildschirmorientierungsänderung’, listenerFunc: (daten: OrientierungDaten) => void, ): Promise<{ entfernen: () => Promise} >; }

export const Bildschirmorientierung = registerPlugin}(‘Bildschirmorientierung’);

Hier ist der schnelle Überblick über jede Signatur:

• orientation() — liest die aktuelle Orientierung asynchron aus
• lock() — akzeptiert nur einen bekannten Orientierungswert
• unlock() — gibt die Kontrolle wieder an normales Geräteverhalten zurück
• addListener() — feuert ein gegebenes Payload aus, sobald sich die Orientierung ändert

Da jede Methode einen Promise zurückgibt, können Sie denselben Aufrufmuster gegenüber der nativen Bridge und gegenüber einer Browserimplementierung verwenden. Keine Abzweigung, keine besonderen Fälle.

const current = await ScreenOrientation.orientation();

Wenn (aktuelle.type mit 'landscape' beginnt) {Angle: ${current.angle}); }

await ScreenOrientation.lock({orientation: 'landscape-primary',});

Type ein falsch geschriebenes Wert wie landscape-main and the build fails on the spot. That’s a compile error you fix in seconds — not a platform-specific runtime bug you chase through device logs.

Type Listener Argumente korrekt einstellen

da dies die Differenz zwischen einem Ereignis-Payload und dem Ergebnis versteckt any da dies die Differenz zwischen einem Ereignis-Payload und dem Ergebnis versteckt orientation() returns.

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

const subscription = await ScreenOrientation.addListener( ‘screenorientierungsänderung’, handleChange, );

warten auf subscription.remove();

Teilen Sie nur eine einzelne OrientationData Typ, wenn beide native Implementierungen die gleichen Felder garantieren. Wenn eine Plattform ein Feld angleweist es als optional und zwingt Aufrufer, undefined.

Die Schnittstelle ist der Bridge-Vertrag, nicht die native Implementierung. Halten Sie es klein, vorhersehbar und testbar.

Für Plattformverhalten, Berechtigungen und Installationsanweisungen lesen Sie die Capacitor Bildschirmorientierung-Plugin-Anleitung. Ein letztes Verhalten, das sich lohnt, ist das Testen von gültigen Aufrufen und abgelehnten Aufrufen unter strengen TypeScript-Einstellungen. Diese Combination fängt falsche Methodennamen, fehlende Felder und inkompatible Listener-Payloads lange vor der Verpackung Ihrer mobilen Anwendung.

Capgo gibt Capacitor Teams die Möglichkeit, JavaScript, CSS, Konfiguration und Asset-Fixes ohne das Warten auf die App-Store-Bewertung zu pushen. Der Trick besteht darin, seinen Update-Pipeline wie jede andere getippte API-Grenze zu behandeln, sodass Kanäle, Rollout-Regeln, Kompatibilitätsprüfungen und Rollover-Entscheidungen explizit bleiben, bevor ein Bundle je ein Gerät des Benutzers erreicht.

Updateverträge definieren

Beginnen Sie damit, genau zu bestimmen, welche Werte Ihre Automatisierung akzeptiert. Literal-Unionen verhindern, dass Sie versehentlich auf das falsche Kanal deployen, und Interfaces machen die Beziehung zwischen einem Bundle und seiner erforderlichen nativen Version selbst dokumentarisch.

Typ Channel = 'beta' | 'staging' | 'production';

Schnittstelle UpdateRequest { kanal: Channel; bundleVersion: string; minNativeVersion: string; rolloutProzent: number; signiert: boolean; }

Schnittstelle UpdateResult { angekommen: boolean; appliziertAufNächsterStart: boolean; rollbackMöglich: boolean; }

A straightforward TypeScript API example prüft die Anfrage, bevor sie sie an den Capgo-Client weiterleitet:

Asynchrone Funktion publishUpdate( request: UpdateRequest, ): Versprechen { if (!request.signiert || request.rolloutProzent < 0 || request.rolloutProzent > 100) { werfen new Fehler('Unsicherer Updateantrag'); }

return capgo.publish(request);

Die genaue Client-Methode-Name ändert sich zwischen Capgo SDK Versionen, also verstecken Sie sie hinter Ihrer eigenen Schnittstelle. Diese Isolation zahlt sich aus, sobald Sie aktualisieren und verhindert, dass spezifische Anbieter-Details in Ihr Codebase dringen.

Schutzkanäle und Kompatibilität

Wählen Sie einen Kanal nicht leichtfertig. Eine Produktionsveröffentlichung erfordert strengere Überprüfungen als ein Beta-Experiment, insbesondere wenn der Web-Bundle native Fähigkeiten aufruft, die in früheren App-Versionen nicht existierten.

function kannDeploy( request: UpdateRequest, installierteNativeVersion: string, ): boolean { return request.unterschrieben &amp;&amp; installierteNativeVersion >= request.minNativeVersion; }

Don’t compare versions with plain strings. Pull in a proper semantic-version library so 1.10.0 sortiert nach 1.9.0Bevor etwas in einen Kanal kommt, führen Sie durch eine Liste:

1. Bestätigen Sie, dass der Bundle signiert ist.
2. Überprüfen Sie, ob der Zielkanal der Absicht entspricht.
3. Vergleichen Sie native und Bundle-Kompatibilitätsbereiche.
4. Zunächst an eine begrenzte Zielgruppe veröffentlichen.
5. Beobachten Sie Fehlerzeichen und bereiten Sie einen Rollback vor.

Ein typisiertes Updatepipeline verwandelt die Veröffentlichungspolitik in code , das Rezensenten und CI tatsächlich überprüfen können.

Capgo’s differential delivery und Kanalsteuerungen passen sich gut in dieses Muster an, und seine Geräteebene-Beobachtbarkeit ermöglicht es Teams, die Annahme oder das Scheitern von Signalen nachträglich nachzuverfolgen. Für die Instrumentierung von Ereignissen siehe Dieses Handbuch zur benutzerdefinierten Ereignisüberwachung mit Capgo.

Die Signatur- und Administrationsanmeldeinformationen sollten auf dem Server oder dem CI-System liegen und nicht im gelieferten App. Wenden Sie die Aktualisierung auf dem nächsten Start an, testen Sie die Rückschaltung mit einer absichtlich abgelehnten Pakete und loggen Sie jede Entscheidung mit einem getypten Ergebnis. Diese Combination hält die schnelle Lieferung mit disziplinierten mobilen Release-Kontrollen kompatibel.

Typisierte Listener machen es einfacher, sich auf asynchrone APIs zu verlassen. Ob ein Callback die Bildschirmorientierung oder ein Capgo-Update-Ereignis verfolgt, sollte es auf jedem Plattform die gleiche Payload-Form erhalten – und der Compiler sollte diejenige sein, die das durchsetzt.

interface UpdateEvent { version: string; kanal: 'beta' | 'produktion'; verfügbar: boolean; }

Typ Listener void (payload: T) => void

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

Dieses TypeScript API-Beispiel bindet den Ereignisnamen an eine Literal und verbindet die Callback-Funktion an einen typisierten Payload. Der Editor vervollständigt die Eingaben version kostenlos und der Compiler lehnt jede Callback-Funktion ab, die unabhängige Daten erwartet. Es ist ein kleiner Aufwand, der sich immer wieder auszahlt, wenn sich der API ändert.

Sie möchten es lieber sehen? Schauen Sie sich die Anleitung an:

Registrieren Sie sich sicherheitshalber

Innerhalb eines Komponenten behalten Sie den Abonnement-Handle bei, um die Auflösung explizit zu halten. Das gleiche Muster fällt in Angular Lifecycle Hooks, React-Effekte und Vue-Mount-Hooks ohne Änderungen.

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

async Funktion start() { orientationHandle = await ScreenOrientation.addListener( ‘screenOrientationChange’, ({ type, winkel }) => { console.log(type, winkel); }, ); }

async Funktion stop() { await orientationHandle?.remove(); orientationHandle = undefined; }

Run cleanup when a screen disappears — not only when the whole app closes. Skip it, and navigation leaves callbacks attached to native event sources. You end up with duplicate work and stale state updates that are painful to trace.

Jeder Framework bietet Ihnen einen Ansatzpunkt dafür:

• Bayern --- Auslösung der Reinigung von ngOnDestroy
• React --- Rückgabe einer asynchron sicheren Reinigungsfunktion von useEffect
• Vue --- Entfernen der Abonnements in onBeforeUnmount

Jeder addListener Jeder Aufruf sollte eine entsprechende Entfernungspfad haben.

Wählen Sie die richtige Reinigungsmethode

Ein zurückgegebener Handle ist die richtige Anrufliste, wenn ein Komponente eine Abonnements besitzt. removeAllListeners() strahlt, wenn ein Dienst mehrere Hörer und vollständig zurückgesetzt wird.

async Funktion resetUpdates(service: UpdateService) { await service.removeAllListeners(); }

Vermeide es, die breite Methode aus einem geteilten Komponenten auszuführen, während andere Bildschirme noch auf die Dienstleistung angewiesen sind. Wenn die Verantwortlichkeit lokal ist, bleibe bei der individuellen. remove() handhabt.

Für Capgo-Benachrichtigungen halten Sie die Aktualisierungsdaten getrennt von Geräteevents. Testen Sie dann die Registrierung, Lieferung und Bereinigung einzeln — die Capgo-Anleitung für benutzerdefinierte Ereignisse hat mehr zum Thema der Integration.

Bevor Sie das Produkt auf den Markt bringen, überprüfen Sie drei Dinge: Die Entfernung von Komponenten entfernt tatsächlich Handler, abgelehnte Versprechen werden aufgefangen und keine Callback-Funktion kann eine zerstörte Komponente aktualisieren. Diese Disziplin hält reaktive Capacitor-Anwendungen responsiv über Angular, React und Vue.

Ein gut gebauter Ein TypeScript-API-Beispiel beginnt mit Namen, die Absichten beschreiben. Verwenden Sie Verben für Methoden, Nomen für Interfaces und halten Sie sich an konsistente Suffixe wie Options, Resultund Event. Klarheit in den Namen reduziert die Einarbeitungszeit, da Entwickler den Vertrag ohne die Implementierung zu öffnen verstehen.

Halten Sie öffentliche Interfaces klein. Exponieren Sie Fähigkeiten über fokussierte Methoden anstatt lose verwandte Operationen auf einem einzelnen Objekt zu laden.

• getStatus() liest den Zustand.
• updateConfig(options) ändert die Konfiguration.
• addListener(event, callback) abonniert sich auf Änderungen.

Typen für Eingaben und Ausgaben genau definieren.

Wählen Sie für Optionen mit Namen, wenn Parameter wachsen können:

interface PublishOptions { kanal: ‘beta’ | ‘production’; rolloutProzent: number; }

interface PublishResult { version: string; akzeptiert: boolean; }

async Funktion publish( options: VeröffentlichungsOptionen, ): Promise {\nreturn client.publish(options);\n}

Generika verdienen ihren Platz, wenn ein API unterschiedliche Payloads umschließt, aber deren spezifische Typen beibehalten muss:

interface ApiResponse {\ndata: T;\nAnforderungs-Id: string;\n}

async Funktion anfordern(path: string): Promise&lt;ApiResponse>&gt; { return fetchJson&lt;ApiResponse&gt;(path); }&gt;(Pfad);

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.

, insbesondere an nativen, Netzwerk- und Update-Grenzen.besonders an native, Netzwerk- und Update-Grenzen.

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.

Ordne Code für Änderungen an.

Trennen Sie Typen, Client-Logik, Plattform-Adapter und Tests in vorhersehbare Dateien. Exportieren Sie öffentliche Typen aus einem Eintrittspunkt und halten Sie Implementierungsdetails privat.

Für wichtige Änderungen an Plugins, einführen Sie eine neue Hauptinterface oder eine Kompatibilitätslayer, behalten Sie veraltete Methoden vorübergehend bei und dokumentieren Sie die Migrationsschritte. Erfahren Sie mehr über die API-Versionierungsstrategien bevor Sie die Verbraucher ändern.

Führen Sie strenge Typprüfungen und Vertragsprüfungen in CI durch, bevor Sie das Produkt verschicken. Für Capgo-Workflows überprüfen Sie die Kanalwerte, die nativen Kompatibilität, die signierten Pakete und die Rolloververhalten als getippte Release-Regeln – dies hält schnelle Updates unter Kontrolle, während sich Teams, Plattformen und Integrationswachstum entwickeln.

Wie sollte ich dynamische native Ergebnisse typen?

Lassen Sie nicht any in Ihre code sickern, wenn eine native Methode unvorhersehbares Daten zurückgibt. Stattdessen beschreiben Sie die Felder, auf die Sie zählen können, markieren Sie genuin optionalen Werte mit ?und reinigen Sie unsichere Eingaben am Rand, bevor etwas Downstream es berührt.

interface NativeResult { success: boolean; value?: string; }

async Funktion lesen(): Promise const result = await NativePlugin.read(); return { success: Boolean(result.success), value: typeof result.value === 'string' ? result.value : undefined, };

Dieser Ansatz hält Ihre Aufrufer sicher, während die Unsicherheit explizit in der Typdefinition selbst ist. Für einen umfassenderen Blick auf dieses Schnittstellenmuster, besuchen Sie Sie wieder Erstellung von APIs in TypeScript.

Erstellung von APIs in TypeScript

Asynchronous callbacks need to be defensive by design. Catch failures inside the listener itself rather than trusting the event system to swallow rejected promises silently.

const handleUpdate = (event: UpdateEvent): void => { void applyUpdate(event).catch((error: unknown) => { console.error('Update fehlgeschlagen', error); }); };

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

Jeder asynchrone Listener benötigt sowohl einen Fehlerpfad als auch einen Reinigungs Pfad.

Wie schütze ich Capgo-Updates?

Signing keys and administrative credentials stay on your server or CI system. Period. The client should only ever receive signed bundles and use typed results to display status — never to create signatures.

Bevor Sie das Update veröffentlichen, müssen Sie separate Kanalunionen einrichten, die Kompatibilitätsprüfungen durchführen, die Rollout-Grenzen konfigurieren und Ihren Rückrufpfad planen. Capgo Verwaltet die signierte Lieferung, die Kanalsteuerung, die nächste Startanwendung und die Rückschrittsschutzfunktion für Capacitor- und Electron-Anwendungen. Ihre Dokumentation zeigt, wie sich die getippten Release-Workflows auf die Verkürzung Ihres Updatepipelines auswirken können.