Esempio TypeScript per API e Capacitor con Capgo

Tutto solido Esempio di API TypeScript 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.

Contenuto della Tabella

• Costruisci un'interfaccia di plugin Capacitor fortemente tipizzata
  • Ricerca rapida per API design
  • Segnali di adozione
  • Benefici per le Capacitor squadre
  • Presentare il caso d'uso
  • Ascolta correttamente gli argomenti del listener
  • Definisci i contratti di aggiornamento
  • Guarda i canali e la compatibilità
  • Registra Ascoltatori in Modo Sicuro
  • Scegli il Metodo di Pulizia Giusto
  • Tipizza Input e Output Precisamente
  • Organizza Code per il Cambio
  • Come devo Tipizzare i Risultati Nativi Dinamici?
  • Come possono gli Ascoltatori Evitare le Rifiuti Non Gestiti?
  • Come posso proteggere gli aggiornamenti Capgo?

Crea un'interfaccia di plugin fortemente tipizzata per Capacitor

The interface describes the API your web code sees. The native implementation behind it has to honor that contract — and TypeScript checks method names, parameters, and return values before your app ever runs.

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

export interface StatoDispositivo { online: boolean; batteryLevel?: number; }

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

export const Dispositivo = registrarePlugin(‘Device’);

C'è molto che accade in poche righe:

• Tipi di ritorno espliciti Tipi di ritorno espliciti
• mantengono ogni risultato predittibile. cattura proprietà mancanti o mal scritte al momento della compilazione.
• Metodi basati su promesse lavoro nativo che si conclude in modo asincrono.
• Un generico registerPlugin call è ciò che collega il web API al ponte nativo.
• Interfacce documentano il contratto senza aggiungere un solo byte di runtime code.

Ogni sito di chiamata riceve lo stesso trattamento:

const status = await dispositivo OttieniStato(); console.log(status.online);

Aspetta Device.setLabel({ label: ‘Produzione’ });

Sostituisci { label: 'Production' } per { name: 'Production' } e il compilatore lo segnala immediatamente. Questo supera la scoperta del mismatch dopo una rilascio mobile.

L'interfaccia è anche dove modelli i valori facoltativi e i casi di fallimento. Se un metodo nativo non può sempre produrre una lettura della batteria, batteryLevel?: number avverte ogni chiamante di gestire undefined.

Il diagramma sotto mostra come i metodi tipizzati, le opzioni, i valori di ritorno, le definizioni di bridge e le verifiche di tempo di compilazione si connettono all'interno di un Capacitor API.

Il concetto fondamentale: Le definizioni di tipo scorrono dall'interfaccia web verso la logica delle piattaforme native, e i controlli di tempo di compilazione sorvegliano ogni sito di chiamata.

Ricerca rapida per API Design

Per una riferimento più approfondito, leggi la guida al creazione di API in TypeScriptMantieni due abitudini: lascia i segreti e le credenziali di firma fuori dal client code, e testa l'interfaccia contro ogni implementazione di piattaforma prima di pubblicare.

I teami mobili gestiscono JavaScript, nativi code, permessi dispositivi e servizi piattaforma asincroni tutti allo stesso tempo. contratto TypeScript forte funziona come un elenco condiviso a ogni di quei confini, rendendo esplicite le aspettative prima che qualsiasi code atterri su un dispositivo iOS o Android.

Risultato della promessa Esempio API TypeScript, confronta un metodo che restituisce Promise<DeviceStatus> con uno che restituisce dati non tipizzati. La versione tipizzata informa il tuo editor e ogni revisore esattamente quali campi esistono. La versione non tipizzata sposta questo lavoro di scoperta sui log di esecuzione, sui test manuali e, nel peggiore dei casi, sugli incidenti di produzione.

Segnali di adozione

Il TypeScript ha superato da tempo il suo ruolo di primo piano nel front-end. 35% dei sviluppatori nel 2024, salendo da solo 12% nel 2017, e superando un milione di GitHub contributori elencato come lingua principale entro il 2025. Scopri il contenuto completo Risultati di adozione di TypeScript se desiderate i numeri bruti.

Quella traiettoria conta per le organizzazioni mobili in modi pratici. L'assunzione, l'assunzione e la code revisione aumentano sempre di più intorno ai tipi condivisi. Qualcuno che si unisce a un progetto Capacitor può leggere un'interfaccia e capire il comportamento nativo previsto senza seguire ogni implementazione.

Le API tipizzate rendono anche il lavoro di rilascio più facile da ragionare. Quando un metodo richiede un oggetto di opzioni specifico, una proprietà rinominata o un campo mancante fallisce al tempo di compilazione invece di produrre silenziosamente una richiesta nativa a forma di mezzo.

Tipizzazione forte sposta i feedback critici a sinistraQuando un fix richiede minuti invece di un rilascio di emergenza.

Benefici per Capacitor Team

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.

Applica tipi espliciti a:

• Istogrammi di input, inclusi opzioni richieste e facoltative
• Risultati di promesse, quindi i dati di successo hanno sempre una forma prevedibile
• Eventi e listener, quindi i callback gestiscono i payload noti
• Errori e valori di stato, quindi le rotte di fallback rimangono visibili

Quella struttura si ripaga quando si integra i plugin di dispositivo o i servizi operativi. Aiuta anche le squadre che esaminano l'automazione degli aggiornamenti, dove un canale sbagliato, un identificatore di bundle o un campo di compatibilità possono avere un impatto su una grande base di utenti.

Per una visione più approfondita dei modelli correlati, leggi il nostro manuale per generare API tipizzate con OpenAPI. Copre come le definizioni condivise riducono la deriva manuale che normalmente si insinua tra la documentazione API e l'applicazione code.

La Creazione di un Caso di Business

La tipizzazione rigorosa richiede un investimento iniziale, soprattutto quando il vecchio JavaScript code contiene forme di dati inconsistenti. Il ritorno si manifesta nel tempo: refactor più piccoli, proprietà più chiare e molte meno sorprese di integrazione.

Inizia con i confini che presentano il maggior rischio:

1. Definisci gli interfacce di risposta per le chiamate native e remote.
2. Digita gli oggetti delle tue opzioni e i payload degli eventi.
3. Attiva le verifiche del compilatore in modo incrementale.
4. Richiedi verifiche di tipo prima di pubblicare qualsiasi aggiornamento.

Per le squadre mobili aziendali, questa base mantiene la manutenzione prevedibile across piattaforme, rilasci e contributori.

Il plugin ScreenOrientation di Capacitor è molto utile Si tratta di un esempio di TypeScript API perché mappa una manciata di metodi web semplici su comportamenti di dispositivo specifici delle piattaforme. Il contratto pubblico rimane identico across piattaforme, mentre iOS e Android si occupano delle loro proprie dettagli nativi sotto. 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 } from ‘@capacitor/core’;

tipo Orientamento = | ‘ritratto primario’ | ‘ritratto secondario’ | ‘paesaggio primario’ | ‘paesaggio secondario’

export interface OptionBlocca { orientamento: TipoOrientamento; }

export interface ScreenOrientationPlugin { orientamento(): Promise

export interfaccia ScreenOrientationPlugin { orientamento(): Promessa }; blocca(options: LockOptions): Promise; svuota(): Promise; addListener( eventName: ‘cambiamentoOrientamentoSchermo’, listenerFunc: (data: OrientamentoDati) => void, ): Promise<{ remove: () => Promise} }

export const OrientamentoSchermo = registerPlugin(‘OrientamentoSchermo’);

Ecco la guida rapida per ogni firma:

• orientation() — legge l'orientamento corrente in modo asincrono
• lock() — accetta solo un valore di orientamento noto
• unlock() — restituisce il controllo alla normale comportamento del dispositivo
• addListener() — invia un payload tipizzato ogni volta che cambia l'orientamento

Poiché ogni metodo restituisce una Promise, puoi utilizzare lo stesso pattern di chiamata contro il ponte nativo e contro una implementazione del browser. Nessun branching, nessun casi speciali.

const current = await ScreenOrientation.orientation();

se l'attuale tipo inizia con 'landscape'Angle: ${current.angle}); }

Aspetta ScreenOrientation.lock({\norientamento: 'paesaggio-primario',\n});

await ScreenOrientation.lock({ 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.

Correggi gli Argomenti del Listener di Tipo

Ascoltatori meritano la stessa attenzione che si riserva ai metodi regolari. Evitare any qui, poiché cela nasconde la differenza tra un payload di evento e il risultato orientation() returns.

Gli ascoltatori meritano la stessa rigorosità delle metodi regolari. Evita

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

aspetta subscription.remove();

Condividi solo un OrientationData segnala quando entrambe le implementazioni native garantiscono gli stessi campi. Se una piattaforma omette angle, segnalarlo come facoltativo e obbligare i chiamanti a gestirlo undefined.

L'interfaccia è il contratto di bridge, non l'implementazione nativa. Tenilo piccolo, predittibile e testabile.

Per comportamento della piattaforma, autorizzazioni e passaggi di installazione, leggi il Capacitor Guida del plugin di orientamento della schermata. Un'ultima abitudine da adottare: testa sia le chiamate valide che le chiamate rifiutate con impostazioni TypeScript strette. Quella combinazione cattura i nomi di metodo sbagliati, i campi mancanti e i payload dei listener incompatibili molto prima di pacchettare l'applicazione mobile.

Capgo dà ai team Capacitor la possibilità di inviare modifiche al JavaScript, CSS, configurazione e asset senza dover attendere la revisione dell'app store. Il trucco è trattare il suo flusso di aggiornamento come qualsiasi altro confine API tipizzato, quindi i canali, le regole di distribuzione, le verifiche di compatibilità e le decisioni di rollback rimangono esplicite prima che un pacchetto raggiunga il dispositivo di un utente.

Definisci i contratti di aggiornamento

Inizia a fissare esattamente quali valori la tua automazione accetta. Le unioni letterali ti impediscono di distribuire accidentalmente su un canale sbagliato, e le interfacce rendono la relazione tra un pacchetto e la sua versione nativa richiesta auto-descrittiva.

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

interfaccia UpdateRequest { channel: Channel; bundleVersion: string; minNativeVersion: string; rolloutPercent: number; signed: boolean; }

interface RisultatoAggiornamento { accettato: boolean; applizzatoAllAvvioSuccessivo: boolean; abilitatoRovescio: boolean; }

Un esempio di TypeScript TypeScript API example valida la richiesta prima di passarla al client Capgo:

async function pubblicaAggiornamento( richiesta: RichiestaAggiornamento, ): Promise { se (!richiesta.sottoscritto || richiesta.percentualeRullo < 0 || richiesta.percentualeRullo > 100) { throw new Error(‘Richiesta di aggiornamento non sicura’); }

return capgo.pubblica(richiesta); }

Il nome esatto del metodo del client cambia tra le versioni Capgo SDK, quindi avvolgilo dietro la propria interfaccia. Quell'isolamento si rivela utile ogni volta che si aggiorna e mantiene i dettagli specifici del fornitore da diffondere attraverso il codicebase.

Canali di Guardia e Compatibilità

Scegliere un canale non dovrebbe essere casuale. Una versione di produzione richiede controlli più rigorosi di un esperimento beta, soprattutto quando il pacchetto web chiama capacità native che non esistevano nelle versioni dell'app precedenti.

function puòDistribuire( richiesta: RichiestaAggiornamento, versioneNativaInstallata: string, ): boolean { return richiesta.sottoscritto && versioneNativaInstallata >= richiesta.minVersioneNativa; }

Non confrontare le versioni con stringhe piane. Incorpora una biblioteca di versione semantica corretta 1.10.0 ordinati dopo 1.9.0. Prima che qualcosa raggiunga un canale, esegui un controllo di checklist:

1. Conferma che il pacchetto è firmato.
2. Verify the target channel matches intent.
3. Confronta le compatibilità di range native e pacchetto.
4. Pubblica per un pubblico limitato per primo.
5. Osserva i segnali di fallimento e mantieni pronto il rollback.

Un flusso di aggiornamento tipizzato trasforma la politica di rilascio in code che gli esaminatori e CI possono veramente ispezionare.

Capgo's consegna differenziale e controlli dei canali si inseriscono in quel modello in modo naturale, e la sua osservabilità a livello di dispositivo consente alle squadre di tracciare l'adozione o i segnali di fallimento dopo il fatto. Per la parte di strumentazione degli eventi, vedi questa guida per la tracciatura degli eventi personalizzati con Capgo.

Le chiavi di firma e le credenziali di amministrazione appartengono al server o al sistema CI, non nell'applicazione spedita. Applica l'aggiornamento alla prossima esecuzione, testa il rollback con un pacchetto intenzionalmente rifiutato e registra ogni decisione con un risultato tipizzato. Quella combinazione mantiene la consegna veloce compatibile con il controllo di rilascio mobile disciplinato.

Le ascoltatori tipizzate sono ciò che rende facili da fidarsi le API asincrone. Se un callback segue l'orientamento della schermata o un Capgo evento di aggiornamento, dovrebbe ricevere la stessa forma di payload su ogni piattaforma — e il compilatore dovrebbe essere quello che lo impone.

interface UpdateEvent { version: string; canale: ‘beta’ | ‘production’; avilità: boolean; }

tipo Listener = (payload: T) =&gt; void;

interface UpdateService { addListener( event: ‘aggiornamentoDisponibile’, callback: Listener, ): Promise&lt;{ rimuovi: () =&gt; Promise} &gt;; rimuoviTuttiGliAscoltatori(): Promise; }

Questo esempio TypeScript API blocca il nome dell'evento a una letterale e lega il callback a un payload tipizzato. Il tuo editor completa automaticamente version e il compilatore rifiuta qualsiasi callback che aspetta dati non correlati. È una piccola quantità di configurazione, e si ripaga ogni volta che il API cambia.

Vuoi vederlo in azione? Guarda il walkthrough:

Registra gli Ascoltatori in modo Sicuro

Inside un componente, mantieni il riferimento di sottoscrizione attivo per garantire che la pulizia rimanga esplicita. Lo stesso pattern si abbina alle funzioni di ciclo di vita di Angular, agli effetti di React e ai hook di Vue di montaggio senza modifiche.

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

funzione async start() {\norientamentoHandle = await ScreenOrientation.addListener(\n‘cambiamentoOrientamentoSchermo’,\n({ tipo, angolo }) =&gt; {\nconsole.log(tipo, angolo);\n},\n);\n}

funzione asincrona 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.

Ogni framework offre una funzione per questo:

• Angular — pulisci la pulizia da ngOnDestroy
• React ritornare una funzione di pulizia asincrona sicura useEffect
• Vue — annulla l'abbonamento in onBeforeUnmount

Tutti addListener call should have a matching removal path.

Scegli il metodo di pulizia giusto

Un handle restituito è la chiamata giusta quando un componente possiede una sola sottoscrizione. removeAllListeners() brilla quando un servizio tiene conto di diversi ascoltatori e viene resettato completamente.

funzione asincrona resetUpdates(servizio: UpdateService) { attendere servizio.removeAllListeners(); }

Non attiva il metodo ampio da un componente condiviso mentre altre schermate dipendono ancora dal servizio. Quando l'accesso è locale, rimani con gli individui remove() Situazione

Per le notifiche Capgo, mantieni i payload degli aggiornamenti separati dagli eventi del dispositivo. Poi testa la registrazione, la consegna e la pulizia separatamente. Capgo custom event tracking guide ha più informazioni sulla parte di integrazione.

Prima di distribuire, controlla tre cose: l'eliminazione effettiva degli handler, le promesse rifiutate sono catturate e nessun callback può aggiornare un componente distrutto. Quella disciplina mantiene gli app Capacitor reattivi across Angular, React e Vue.

A un buon progetto Esempio di TypeScript API Inizia con nomi che descrivono l'intento. Utilizza verbi per i metodi, sostantivi per gli interfacce e mantieni suffissi coerenti come Options, Result, e Event. I nomi chiari riducono il tempo di onboarding perché gli sviluppatori comprendono il contratto senza aprire l'implementazione.

Tenere le interfacce pubbliche piccole. Espone le capacità attraverso metodi focalizzati piuttosto che scaricare operazioni legate in modo flessibile su un singolo oggetto.

• getStatus() legge lo stato.
• updateConfig(options) modifica la configurazione.
• addListener(event, callback) si sottoscrive ai cambiamenti.

Tipi di Input e Output Precisi

Raggiungi le interfacce di opzione denominata quando i parametri possono crescere:

interface OpzioniDiPubblicazione { canale: ‘beta’ | ‘produzione’; percentualeDiDistribuzione: number; }

interface RisultatoPubblicazione { versione: string; accettato: boolean; }

async function pubblica( optioni: OpzioniPubblicazione, ): Promise { return client.pubblica(optioni); }

Il uso dei generici trova giustificazione quando un API avvolge diversi payload ma deve preservare i loro tipi specifici:

interface RispostaRichiesta { dati: T; idRichiesta: string; }

async function richiesta(percorso: string): Promise<RispostaRichiesta>{ return fetchJson<RispostaRichiesta>(percorso); }

Non aggiungere generici solo per sembrare flessibili. Un generico dovrebbe esprimere una vera relazione tra input e output — altrimenti un'interfaccia concreta è più facile da leggere e mantenere.

Fai degli stati invalidi difficile da rappresentarespecialmente ai confini nativi, di rete e di aggiornamento.

Documenta il comportamento accanto al contratto. Copri le autorizzazioni, le unità, le promesse rifiutate, i campi facoltativi e se un metodo si applica immediatamente o alla prossima avviamento. Gli commenti inline dovrebbero spiegare le decisioni, non ripetere i nomi dei metodi.

Organizza Code per il Cambio

Separate tipi, logica del client, adattatori di piattaforma e test in file prevedibili. Esporta i tipi pubblici da un punto di ingresso e mantiene i dettagli di implementazione privati.

Introduci un nuovo livello di compatibilità o un nuovo interfacce maggiore, mantieni temporaneamente le funzioni obsolete e documenta i passaggi di migrazione. Scopri di più sulle strategie di versionamento di API prima di modificare i consumatori.

Esegui controlli di tipo rigorosi e test di contratto in CI prima di distribuire. Per Capgo flussi di lavoro, verificare i valori del canale, la compatibilità nativa, i pacchetti firmati e il comportamento di rollback come regole di rilascio tipizzate — ciò mantiene aggiornamenti veloci sotto controllo mentre crescono le squadre, le piattaforme e le integrazioni.

Come Devo Tipizzare Risultati Dinamici Nativi?

Non lasciare any filtrare nei tuoi code quando un metodo nativo restituisce dati imprevedibili. Invece, elenca i campi su cui puoi contare, segnala valori genuinamente facoltativi con ?e sanita' l'input incerto al confine prima che qualcosa a valle lo tocchi.

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

funzione asincrona readValue(): Promise const risultato = await NativePlugin.read(); return { success: Boolean(risultato.success), value: typeof risultato.value === 'string' ? risultato.value : undefined, };

Questa approccio mantiene i chiamanti sicuri mentre rende l'incertezza esplicita nel tipo stesso. Per una visione più ampia di questo modello di interfaccia, ripassa costruire API in TypeScript.

Come Posso Evitare Rifiuti Non Gestiti dai Listener?

Aspettare le callback asincrone deve essere difensivo di progetto. Cattura le eccezioni all'interno del listener stesso piuttosto che fidarsi del sistema di eventi per inghiottire promesse rifiutate silenziosamente.

const handleUpdate = (evento: UpdateEvent): void =&gt; { void applyUpdate(evento).catch((errore: unknown) =&gt; { console.error(‘Aggiornamento fallito’, errore); }); };

Tenere riferimento alla sottoscrizione e rimuoverla quando il componente viene smontato. Ciò prevenire callback duplicati e aggiornamenti di stato obsoleti — la sezione del ciclo di vita del listener esamina questo in dettaglio.

Ogni asincrono listener necessita di un percorso di errore e un percorso di pulizia.

Come posso proteggere gli Capgo aggiornamenti?

Il segreto di firma e le credenziali amministrative rimangono sul tuo server o sistema CI. Periodo. Il client dovrebbe ricevere solo pacchetti firmati e utilizzare risultati tipizzati per visualizzare lo stato — mai per creare firme.

Prima di pubblicare, impostare unioni di canali separati, eseguire controlli di compatibilità, configurare limiti di distribuzione e pianificare il percorso di rollback. Capgo gestisce la consegna firmata, i controlli di canale, l'applicazione di lancio successivo e la protezione del rollback per Capacitor e le app Electron. I loro documenti mostrano come i flussi di rilascio tipizzati possono stringere il tuo pipeline di aggiornamento.