TypeScript API Example for Capacitor and Capgo

Eine solide Eine TypeScript API-Beispiel Für Capacitor beginnt jede Capacitor-Beispiel auf die gleiche Weise: mit einer getypteten Plugin-Schnittstelle. Beschreiben Sie Ihre Methoden, Optionen und Promise-Ergebnisse explizit, und Ihre Web-code- und die native Layer teilen eine Vertrags, die TypeScript tatsächlich durchsetzt.

Inhaltsverzeichnis

• Erstellen Sie eine stark typisierte Capacitor-Plugin-Schnittstelle
  • Ein stark getypter API-Plugin-Interface erstellen
  • Schneller Überblick über __CAPGO_KEEP_0__-Design
  • Vorteile für Capacitor Teams
  • Vorteile für __CAPGO_KEEP_0__-Teams
  • Die Geschäftsfallenstellung
  • Type Listener-Argumente richtig definieren
  • Update-Verträge definieren
  • Registrieren Sie Listener sicher
  • Wählen Sie die richtige Methode zum Aufräumen
  • Typen Sie Eingaben und Ausgaben genau
  • Organisieren Sie Code für Änderungen
  • Wie sollte ich dynamische Ergebnisse von Native-Code typen?
  • Wie können Listener unbehandelte Rejectionen vermeiden?
  • Wie schütze ich Capgo-Updates?

Erstellen Sie eine stark typisierte Schnittstelle für Capacitor-Plugins

Die Schnittstelle beschreibt die API die Ihre Web-code sieht. 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<{ saved: boolean }>;

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

Es gibt viel los in diesen wenigen Zeilen.

• Explicit return types Explicit return types
• Typisierte Optionen-Objekte Fehlerhafte oder fehlende Eigenschaften bei der Kompilierung erkennen.
• Versprechungs-basierte Methoden asynchrone native Arbeit, die abgeschlossen wird.
• Ein allgemeiner registerPlugin call is what connects the web API to die native Brücke.
• Interfaces beschreiben den Vertrag ohne einen Byte Laufzeit code hinzuzufügen.

Jeder Aufruf erhält die gleiche Behandlung:

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

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

Umschalten { label: 'Production' } anstatt { name: 'Production' } und der Compiler markiert es sofort. Das ist besser als die Mismatch nach einer mobilen Veröffentlichung zu entdecken.

Die Schnittstelle ist auch der Ort, an dem Sie optionalen 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.

Die folgende Abbildung zeigt, wie typisierte Methoden, Optionen, Rückgabewerte, Brückendefinitionen und Laufzeitprüfungen innerhalb eines Capacitor API miteinander verbunden sind.

Das Kernkonzept: Typdefinitionen fließen von der webfassenden Schnittstelle in Richtung nativer Plattformlogikund laufen bei jedem Aufruf durch Zeitkontrollen.

Schnellsuche für API-Design

Für eine tiefergehende Referenz, lesen Sie die Anleitung zum Erstellen von APIs in TypeScript. Two habits worth keeping: leave secrets and signing credentials out of client code, and test the interface against each platform implementation before you publish.

Mobile-Teams balancieren JavaScript, native code, Geräteeinstellungen und asynchrone Plattformdienste gleichzeitig. starker TypeScript-Vertrag funktioniert wie eine gemeinsame Checkliste an jeder dieser Grenzen, wodurch Erwartungen explizit gemacht werden, bevor sich ein code auf einem iOS- oder Android-Gerät abspielt.

Für eine konkrete TypeScript API Beispiel, vergleichen Sie eine Methode, die Promise<DeviceStatus> eine Rückgabewert mit einem untypischen Daten zurückgibt. Die getippte Version teilt Ihrem Editor und jedem Rezensenten genau welche Felder existieren. Die ungetippte Version schiebt diese Entdeckungsarbeit auf Laufzeitprotokolle, manuelle Tests und, im schlimmsten Fall, Produktionsunfälle.

Adoptionszeichen

TypeScript hat sich weit über seinen Frontend-Nischen bewegt. Die Akzeptanz stieg auf 35% der Entwickler im Jahr 2024, von nur 12% im Jahr 2017, und mehr als eine Million GitHub-Beiträge , die es als ihre HauptSprache angaben, bis 2025. Erfahren Sie mehr über die vollständigen TypeScript-Akzeptanz-Ergebnisse Wenn Sie die Rohzahlen wollen.

Diese Trajektorie ist für mobile Organisationen in praktischen Wege relevant. 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 Durchsuchen jedes Implementierungsdetails verstehen.

Gepflegte APIs machen die Arbeit mit Releases einfacher zu verstehen. Wenn eine Methode ein bestimmtes Optionsobjekt verlangt, wird ein umbenannter Eigenschaft oder ein fehlender Feld bei der Kompilierung fehlschlagen, anstatt stillschweigend einen halbgebildeten native Anfrage zu produzieren.

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

Vorteile für Capacitor Teams

Cross-plattform-Apps 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.

Wenden Sie explizite Typen auf:

• Eingabe von Methoden, einschließlich erforderlicher und optionaler Optionen
• Versprechen von Ergebnissen, so dass Erfolgdaten immer eine vorhersehbare Form haben
• Events und Hörer, also rufen Callbacks bekannte Payloads an
• Fehler und Statuswerte, also bleiben Fallback-Pfade sichtbar

Dieses Muster zahlt sich aus, wenn Sie Geräteplugins oder Betriebsdienste integrieren. Es hilft auch Teams bei der Überprüfung der Update-Automatisierung, bei der ein falscher Kanal, ein falscher Bundle-Identifier oder ein inkompatibler Feldwert sich auf eine große Benutzerbasis auswirken kann.

Für eine tiefergehende Einführung in verwandte Muster lesen Sie unsere Anleitung zur Erstellung von getypten APIs mit OpenAPI. Sie behandelt, wie gemeinsame Definitionen die manuelle Drift reduzieren, die normalerweise zwischen API Dokumentation und Anwendungscode code auftritt.

Die Geschäftsfallerstellung

Striktes Typisieren erfordert jedoch einige Vorauszahlungen, insbesondere wenn älterer JavaScript code inkonsistente Datenformen enthält. Der Gewinn zeigt sich im Laufe der Zeit: kleinere Refaktorisierungen, klarere Verantwortung und viel weniger Überraschungen bei der Integration.

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

1. Definieren Sie Antwortinterfaces für native und remote Aufrufe.
2. Typen Sie Ihre Optionenobjekte und Ereignisdaten ein.
3. Schalten Sie die strengen Compilerprüfungen schrittweise ein.
4. Require type checks before publishing any update.

Für Unternehmensteams von mobilen Anwendungen stellt diese Grundlage die Wartung vorhersehbar über Plattformen, Releases und Beiträger sicher.

Capacitor’s ScreenOrientationPlugin ist eine großartige Ein TypeScript-Beispiel für API weil es eine Handvoll einfacher Webmethoden auf Plattform-spezifische 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 Orientierungstyp = | ‘portrait-primary’ | ‘portrait-secondary’ | ‘landscape-primary’ | ‘landscape-secondary’;

export interface Orientierungsdaten { typ: Orientierungstyp; Winkel: number; }

export interface Sperresoptionen { orientierung: Orientierungstyp; }

export interface ScreenOrientationPlugin { orientierung(): Versprechen};\nlock(options: LockOptions): Promiseunlock(): Versprechen; addListener( eventName: ‘screenOrientationChange’, listenerFunc: (data: OrientationData) => void, ): Promise<{ remove: () => Promise}>; } }>; }

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

— liest die aktuelle Orientierung asynchron ab

• orientation() — akzeptiert nur einen bekannten Orientierungswert
• lock() — gibt die Kontrolle an die normale Geräteverhalten zurück
• unlock() — gibt die Kontrolle wieder an normales Gerätverhalten zurück
• addListener() — fügt bei jeder Orientierungsänderung ein typisiertes Payload aus

Since every method returns a Promise, you can use the same calling pattern against the native bridge and against a browser implementation. No branching, no special cases.

const current = await ScreenOrientation.orientation();

if (aktuelle.art.startsWith('landschaft')) {Angle: ${current.angle}); }

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

Tippen Sie einen falsch geschriebenen Wert ein wie landscape-main und das Build scheitert sofort. Das ist ein Kompilierungsfehler, den Sie in Sekunden beheben – nicht ein plattformabhängiger Laufzeitfehler, den Sie durch Geräteprotokolle aufspüren müssen.

Typische Listener-Argumente korrigieren

Listener verdienen denselben Rigor wie reguläre Methoden. Vermeiden Sie any da dies die Unterschiede zwischen einem Ereignis-Payload und dem Ergebnis orientation() verdeckt.

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

const subscription = await ScreenOrientation.addListener('screenOrientationChange', handleChange,);

warten auf subscription.remove();

Teilen Sie nur eine OrientationData Typ, wenn beide native Implementierungen die gleichen Felder garantieren. Wenn eine Plattform ein Feld angle, optional machen und den Aufrufer dazu zwingen, es zu behandeln 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 Anleitung zum Bildschirmorientierungs-Plugin. 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-Pakete lange vor der Verpackung Ihrer mobilen Anwendung.

Capgo bietet Capacitor Teams eine Möglichkeit, JavaScript, CSS, Konfiguration und Asset-Fixes ohne das Sitzen durch App-Store-Überprüfung 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 sind, bevor ein Bundle je einem Gerät des Benutzers erreicht.

Update-Verträge definieren

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

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

interface UpdateRequest { channel: Kanal; bundleVersion: string; minNativeVersion: string; rolloutPercent: number; signed: boolean; }

interface UpdateResult { akzeptiert: boolean; appliedOnNextLaunch: boolean; rollbackEnabled: boolean; }

Ein einfacher TypeScript API example überprüft die Anfrage, bevor sie sie an den Capgo-Client weiterleitet:

async function publishUpdate( request: UpdateRequest, ): Promise} { if (!request.signed || request.rolloutPercent < 0 || request.rolloutPercent > 100) { throw new Error(‘Ungültige Update-Anfrage’); }

return capgo.publish(request);

Die genaue Client-Methode-Name ändert sich zwischen den Capgo SDK Versionen, also schließen Sie sie hinter einer eigenen Schnittstelle ein. Diese Isolation zahlt sich immer wieder aus, wenn Sie aktualisieren und hält die Hersteller-spezifischen Details von Ihrem Codebase fern.

Wächterkanäle und Kompatibilität

Die Auswahl eines Kanals sollte nicht leichtfertig erfolgen. Ein Produktionsrelease erfordert strengere Überprüfungen als ein Beta-Experiment, insbesondere wenn das Web-Bundle native Fähigkeiten aufruft, die in früheren App-Versionen nicht existierten.

function canDeploy( request: UpdateRequest, installedNativeVersion: string, ): boolean { return request.signed && installedNativeVersion >= request.minNativeVersion; }

Vergleichen Sie keine Versionen mit einfachen Zeichenketten. Ziehen Sie eine semantische Versionen-Bibliothek heran, um 1.10.0 sortiert nach 1.9.0. Bevor etwas in einen Kanal gelangt, führen Sie eine Liste durch:

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

Ein typisiertes Updatepipeline verwandelt die Releasepolitik in code, die Reviewer und CI tatsächlich überprüfen können.

Capgo's Differential-Delivery und Kanalsteuerung passen gut in dieses Muster und ermöglichen es den Teams, die Adoption oder Fehlerzeichen nachträglich zu verfolgen. Für die Ereignisinstrumentierung siehe dieses Leitfaden für die Anpassung von Ereignissen mit Capgo.

Signierungschlüssel und Administrationsanmeldeinformationen sollten auf dem Server oder CI-System liegen und nicht im gelieferten App. Wenden Sie die Aktualisierung auf dem nächsten Launch an, testen Sie den Rollback mit einem absichtlich abgelehnten Bundle und loggen Sie jede Entscheidung mit einem typisierten Ergebnis. Diese Combination hält eine schnelle Lieferung mit disziplinierten mobilen Releasekontrolle kompatibel.

Typisierte Listener machen es leicht, Asynchron-APIs zu vertrauen. Ob ein Callback die Bildschirmorientierung oder ein Capgo-Update-Ereignis verfolgt, sollte es auf jedem Plattform dieselbe Payload-Struktur erhalten – und der Compiler sollte die Einhaltung dieser Struktur überprüfen.

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; }

Dies TypeScript API Beispiel pins die Ereignisname an eine Literal und bindet die Callback an einen getypten Payload. Der Editor vervollständigt automatisch version for free, and the compiler rejects any callback that expects unrelated data. It’s a small amount of setup, and it pays off every time the API changes.

Möchten Sie es lieber sehen? Schauen Sie sich den Rundgang an:

Registriere Listener sicher

Innerhalb eines Komponents behalten Sie den Abonnement-Handle, damit die Auflösung explizit bleibt. Der gleiche Muster fällt in Angular Lifecycle Hooks, React-Effekte und Vue-Mount-Hooks ohne Änderungen ab.

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

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

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

Beim Verschwinden einer Bildschirmfläche wird die Auflösung durchgeführt – nicht nur beim Schließen der gesamten App. Wenn Sie es überspringen, bleiben Callbacks an nativen Ereignissen angehängt. Sie enden mit doppeltem Arbeit und veralteten Zustandsupdates, die schmerzhaft zu verfolgen sind.

Jedes Framework bietet einen Hook für diese Aufgabe:

• Angular — Auflösung auslösen von ngOnDestroy
• React — eine asynchron-sichere Auflösungsfunktion zurückgeben von useEffect
• Vue — die Abonnementabonnement in onBeforeUnmount

Jeder addListener Jeder Aufruf sollte eine entsprechende Entfernungspfad haben.

Wählen Sie die richtige Methode zum Aufräumen

Ein zurückgegebenes Handle ist die richtige Anrufliste, wenn ein Komponente eine Abonnement 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 Verantwortung lokal ist, verwende eine einzelne Instanz. remove() Händen.

Für Capgo-Benachrichtigungen sollten die Aktualisierungsdaten von den Geräteereignissen getrennt gehalten werden. Dann testen Sie die Registrierung, die Lieferung und die Bereinigung einzeln — die Capgo custom event tracking guide Es gibt mehr auf der Integrationsseite.

Before you ship, check three things: unmounting actually removes handlers, rejected promises are caught, and no callback can update a destroyed component. That discipline keeps reactive Capacitor apps responsive across Angular, React, and Vue.

Aufgebaut Eine gut aufgebaute TypeScript API-Beispiel beginnt mit Namen, die Absicht beschreiben. Verwenden Sie Verben für Methoden, Nomen für Interfaces und halten Sie sich an konsistente Suffixe wie Options, Result, und Event. Klar benannte Namen reduzieren die Einarbeitungszeit, da sich Entwickler ohne die Implementierung den Vertrag ansehen können.

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

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

Typen Eingaben und Ausgaben genau

Ziehen Sie für Parameter, die wachsen können, nach benannten Optioneninterfaces heran:

interface VeröffentlichungsOptionen { channel: 'beta' | 'produktionsbereit'; rolloutProzent: number; }

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

async Funktion publish( options: VeröffentlichungsOptionen, ): Versprechen return client.publish(options);

Generische Typen verdienen ihren Platz, wenn ein API unterschiedliche Daten, aber ihre spezifischen Typen, umfasst:

interface ApiResponse { data: T; Anforderungs-Id: string; }

async Funktion anfordern(path: string): Versprechen von ApiResponse&gt; {return fetchJson&lt;ApiResponse}&gt;(path);\n}

Aber fügen Sie Generics nicht nur hinzu, um flexibel zu wirken. Ein Generic sollte eine echte Beziehung zwischen Eingabe und Ausgabe ausdrücken – ansonsten ist ein konkreter Interface einfacher zu lesen und zu pflegen.

Machen Sie ungültige Zustände schwierig darzustellenbesonders an native, Netzwerk- und Aktualisierungsgrenzen.

Verhalten dokumentieren Sie direkt neben dem Vertrag. Decken Sie Rechte, Einheiten, abgelehnte Versprechen, optionale Felder und die Frage ab, ob eine Methode sofort oder bei der nächsten Startphase wirksam ist. Inline-Kommentare sollten Entscheidungen erklären, nicht Methode-Namen wiederholen.

Organisieren Sie Code für Änderungen

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

Für umfassende Plugin-Änderungen sollten Sie eine neue Haupt-Schnittstelle oder eine Kompatibilitäts-Schicht einführen, veraltete Methoden vorübergehend beibehalten und Migrations-Schritte festhalten. Mehr über die API Versionsstrategien erfahren vor dem Wechsel der Verbraucher.

Laufen Sie strenge Typprüfungen und Vertragsprüfungen in CI vor dem Versand. 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 Integrations wachsen.

Wie sollte ich dynamische native Ergebnisse typen?

Lasst sie nicht any leak in Ihr code ein, wenn eine native Methode unvorhersehbare 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 an der Grenze, bevor etwas Downstream es berührt.

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

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

Diese Vorgehensweise hält Ihre Aufrufer sicher, während die Unsicherheit explizit im Typ selbst ist. Für einen umfassenderen Blick auf dieses Schnittstellenmuster besuchen Sie APIs in TypeScript erstellen.

Wie können Hörer unbehandelte Ablehnungen vermeiden?

Asynchrone Callbacks müssen defensiv sein. Fehlschläge innerhalb des Hörers selbst auffangen, anstatt auf das Ereignissystem zu vertrauen, das abgelehnte Versprechen stillschweigend verschluckt.

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

Halten Sie den Abonnentenbezug und entfernen Sie ihn, wenn der Komponenten entladen wird. Das verhindert doppelte Callbacks und veraltete Zustandsaktualisierungen — der Abschnitt zum Lebenszyklus des Hörers geht in die Details.

Jeder asynchrone Hörer benötigt sowohl einen Fehlerweg als auch einen Reinigungsweg.

Auf welche Weise schütze ich Capgo Updates?

Signierungschlüssel und administrative Anmeldeinformationen bleiben auf Ihrem Server oder CI-System. Punkt. Der Client sollte nur signierte Pakete erhalten und mit getypten Ergebnissen den Status anzeigen — nie, um Signaturen zu erstellen.

Bevor Sie das Update veröffentlichen, müssen Sie separate Kanalunionen einrichten, die Kompatibilitätsprüfungen durchführen, die Ausrollenlimits konfigurieren und Ihren Rückroll-Plan vorbereiten. Capgo Capgo-Updates werden durch Capacitor und Electron-Apps gehandhabt. Ihre Dokumentation zeigt, wie sich getypte Release-Workflows auf die Vertrauenswürdigkeit Ihres Update-Pipelines auswirken können.