Exemple de TypeScript API pour Capacitor et Capgo

Tout solide Exemple de TypeScript API pour Capacitor commence de la même manière : par une interface de plugin typée. Définissez explicitement vos méthodes, options et résultats de Promesse, et votre code web et la couche native partagent un contrat que TypeScript applique effectivement.

Table des Matières

• Construire une interface de plugin fortement typée Capacitor
  • Recherche rapide pour le design de API
  • Signaux d'adoption
  • Avantages pour les équipes de Capacitor
  • Établir un dossier
  • Écouter les arguments correctement
  • Définir les contrats d'actualisation
  • Protéger les canaux et la compatibilité
  • Enregistrer les Écouteurs de manière Sécurisée
  • Choisissez la Méthode de Nettoyage Adéquate
  • Typisez les Entrées et Sorties avec Précision
  • Organisez les Code pour les Changements
  • Comment Typiser les Résultats Natives Dynamiques ?
  • Comment les Écouteurs Évitent-ils les Rejets Non Gérés ?
  • Comment Protéger les Mises à Jour des Capgo ?

Construirez une Interface de Plugin Capacitor Fortement Typisée

L'interface décrit les API que votre web code voit. La mise en œuvre native derrière elle doit respecter cet accord — et TypeScript vérifie les noms de méthode, les paramètres et les valeurs de retour avant que votre application ne s'exécute.

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

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

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

export const Dispositif = enregistrerPlugin(‘Device’);

There’s a lot going on in those few lines:

• Types explicitement Types explicites de retour
• gardez chaque résultat prévisible. Vérifiez les propriétés manquantes ou mal orthographiées en temps de compilation.
• Méthodes basées sur des promesses Méthodes basées sur des promesses
• un générique registerPlugin call C'est ce qui relie le web API à la passerelle native.
• Interfaces documentent le contrat sans ajouter un seul byte de runtime code.

Tout site d'appel reçoit le même traitement :

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

await Device.setLabel({ label: 'Production' });

Échange { label: 'Production' } pour { name: 'Production' } et le compilateur l'indique immédiatement. Cela bat l'idée de découvrir le déséquilibre après une mise à jour mobile.

L'interface est également où vous modélisez des valeurs optionnelles et des cas de défaillance. Si une méthode native ne peut pas toujours produire une lecture de la batterie, batteryLevel?: number indique à chaque appelant de gérer undefined.

Le diagramme ci-dessous montre comment les méthodes typées, les options, les valeurs de retour, les définitions de pont et les vérifications en temps de compilation s'intègrent dans un Capacitor API.

L'idée centrale : Définitions de type s'écoulent de l'interface web vers la logique de la plateforme native., and compile-time checks stand guard at every call site.

Recherche rapide pour API Design

Pour une référence plus approfondie, lisez le guide à création d'APIs en TypeScriptLes équipes mobiles gèrent le JavaScript, les code natifs, les permissions de dispositif et les services de plateforme asynchrones en même temps. Un

Équipes mobiles gèrent le JavaScript, les permissions natives code, et les services de plateforme asynchrones, tout en même temps. contrat TypeScript solide Une personne en train de coder sur un ordinateur portable affichant code sur un bureau à côté d'une tasse de café.

Résultat de la promesse Exemple de TypeScript API, comparez une méthode qui retourne Promise<DeviceStatus> avec une qui renvoie des données non typées. La version typée informe votre éditeur et chaque réviseur des champs qui existent. La version non typée reporte cette découverte sur les journaux de runtime, les tests manuels et, au pire, les incidents en production.

Signaux d'adoption

TypeScript a dépassé bien son niché front-end. L'adoption est montée à 35% des développeurs en 2024, en passant de juste 12% en 2017, et plus de un million de GitHub contributeurs listed it as their primary language by 2025. Explore the full 35% des développeurs en 2024 Si vous voulez les nombres bruts.

Ce trajectoire compte pour les organisations mobiles de manière pratique. Le recrutement, la mise en place et la code de revue deviennent de plus en plus axés sur les types partagés. Quelqu'un rejoignant un projet Capacitor peut lire une interface et comprendre le comportement natif attendu sans suivre chaque mise en œuvre.

Les API typées rendent également le travail de mise en production plus facile à raisonner. Lorsqu'une méthode exige un objet d'options spécifique, une propriété renommée ou un champ manquant échoue à la compilation au lieu de produire silencieusement une demande native incomplète.

Strong typing shifts critical feedback leftQuand une correction prend des minutes au lieu d'une mise en production d'urgence.

Avantages pour les équipes Capacitor

Les applications cross-platform exposent généralement une seule interface web API qui se trouve au-dessus de plusieurs implémentations natives. TypeScript ne peut pas prouver que chaque détail natif se comporte de la même manière, mais il peut garder vos appels cohérents tout au long de l'application.

Appliquez des types explicites à :

• Les entrées de méthodey compris les options requises et facultatives
• Les résultats de promesseafin que les données de succès aient toujours une forme prévisible
• Événements et écouteurs, les appels de rappel gèrent les payloads connus
• Erreurs et valeurs de statut, les chemins de fallback restent visibles

Cette structure se révèle payante lors de l'intégration de plugins de périphériques ou de services opérationnels. Cela aide également les équipes à examiner l'automatisation des mises à jour, où un mauvais canal, un identifiant de bundle ou un champ de compatibilité peuvent se propager à une grande base d'utilisateurs.

Pour une plongée plus approfondie dans les modèles connexes, lisez notre guide de génération d'APIs de type avec OpenAPI. Il couvre comment les définitions partagées réduisent la dérive manuelle qui se glisse normalement entre la documentation API et l'application code.

Argumenter en faveur de l'entreprise

Le typage strict demande un investissement initial, surtout lorsque les anciens code JavaScript portent des formes de données incohérentes. Le retour se manifeste sur le long terme : des réfacteurs plus petits, une propriété plus claire et beaucoup moins de surprises d'intégration.

Commencez par les limites qui portent le plus de risque :

1. Définez les interfaces de réponse pour les appels natifs et distants.
2. Entrez vos objets d'options et vos chargeurs d'événements.
3. Turn on strict compiler checks incrementally.
4. Exigez des vérifications de type avant de publier tout mises à jour.

Pour les équipes mobiles d'entreprise, cette base garde la maintenance prévisible sur les plateformes, les versions et les contributeurs.

Capacitor’s ScreenOrientationPlugin fait une excellente Exemple de TypeScript API car il cartographie une poignée de méthodes web simples sur le comportement du dispositif spécifique aux plateformes. Le contrat public reste identique sur les plateformes, tandis que iOS et Android gèrent leurs propres détails natifs en dessous.

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

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

export interface Données d'orientation {\ntype : Type d'orientation;\nangle : nombre;\n}

export interface Options de verrouillage { orientation : Type d'orientation; }

export interface ScreenOrientationPlugin { orientation(): Promise }; attente(options: OptionsDeVerrouillage): Promise; libérer(): Promise; ajouterUnEcouteur( eventName: ‘le ChangementDorientationDeLecran’, listenerFunc: (données: DonnéesDorientation) => void, ): Promise<{ supprimer: () => Promise} } }

export const OrientationDeLecran = registerPlugin(‘OrientationDeLecran’);

Voici la référence rapide pour chaque signature :

• orientation() — lit l'orientation actuelle de manière asynchrone
• lock() — accepte uniquement une valeur d'orientation connue
• unlock() — restitue le contrôl’à la normale du comportement du dispositif
• addListener() — déclenche un payload typé chaque fois que l'orientation change

Depuis que chaque méthode renvoie une Promise, vous pouvez utiliser le même modèle d'appel contre le pont natif et contre une implémentation de navigateur. Aucune branchement, aucune cas particulier.

const current = attendre await ScreenOrientation.orientation();

if (current.type.startsWith('landscape')) { console.log(Angle: ${current.angle}); }

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

Typerez une valeur mal orthographiée comme 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.

Typez les arguments des écouteurs correctement

Les écouteurs méritent le même soin que les méthodes régulières. Évitez any car elle masque la différence entre un payload d'événement et le résultat orientation() returns.

const handleChange = (donnees : DonneesOrientation) => {\ndocument.body.dataset.orientation = donnees.type;\n};

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

Typez les arguments des écouteurs correctement

Partagez uniquement un OrientationData type lorsque les deux implémentations natives garantissent les mêmes champs. Si une plateforme omite angle, marquez-le comme optionnel et forcez les appels à gérer undefined.

Le contrat d'interface est le contrat de pont, et non l'implémentation native. Gardez-le petit, prévisible et testable.

Pour les comportements de plateforme, les permissions et les étapes d'installation, consultez le Capacitor guide de l'extension d'orientation d'écran. Une dernière habitude à adopter : testez les appels valides et les appels rejetés sous les paramètres de TypeScript strict. Cette combinaison attrape les noms de méthode incorrects, les champs manquants et les payloads de listener incompatibles bien avant que vous ne packagiez votre application mobile.

Capgo permet aux équipes de Capacitor de pousser des correctifs de JavaScript, CSS, de configuration et d'actifs sans passer par la revue de l'application store. Le truc est de traiter son pipeline d'actualisation comme n'importe quelle autre limite de API typée, afin que les canaux, les règles de lancement, les vérifications de compatibilité et les décisions de reversion restent explicites avant qu'un bundle ne parvienne jamais à un appareil de l'utilisateur.

Définir les contrats d'actualisation

Commencez par fixer exactement quelles valeurs votre automatisation accepte. Les unions littérales vous empêchent de déployer par erreur sur le mauvais canal, et les interfaces rendent la relation entre un bundle et sa version native requise auto-documentée.

type Canal = ‘beta’ | ‘staging’ | ‘production’;

interface Demande d'actualisation { chanel: Canal; bundleVersion: string; minNativeVersion: string; rolloutPercent: number; signed: boolean; }

interface ResultDeMiseÀJour { accepted: boolean; appliedOnProchaineLancement: boolean; rollbackEnabled: boolean; }

Un exemple TypeScript simple vérifie la demande avant de la transmettre au client API : vérifie la demande avant de la transmettre au client Capgo :

async fonction publierMiseÀJour( requête : RequêteDeMiseÀJour, ): Promise Si (!request.signed || request.rolloutPercent < 0 || request.rolloutPercent > 100) { throw new Error('Mise à jour non sécurisée'); }

return capgo.publish(request);

The exact client method name shifts between Capgo SDK versions, so wrap it behind your own interface. That isolation pays off every time you upgrade and keeps vendor-specific details from leaking across your codebase.

Protéger les canaux et la compatibilité

function peutDéployer( request: DemandeDeMiseÀJour, versionNativeInstallée: string, ): boolean { return request.signed && versionNativeInstallée >= request.minNativeVersion; }

N'effectuez pas de comparaison de versions avec des chaînes simples. Intégrez une bibliothèque de versionnement semantique appropriée pour

Don’t compare versions with plain strings. Pull in a proper semantic-version library so 1.10.0 tri après 1.9.0Avant que quoi que ce soit atteigne un canal, passez par un contrôle de checklist :

1. Confirmez que le bundle est signé.
2. Vérifiez que le canal cible correspond à l'intention.
3. Comparez les plages de compatibilité natives et de bundle.
4. Publiez auprès d'un public limité en premier.
5. Regardez les signaux de failure et gardez un rollback prêt.

Un pipeline d'update typé transforme la politique de publication en code que les réviseurs et CI peuvent inspecter réellement.

Capgo’s livraison différentielle et contrôles de canal s’insèrent dans ce modèle de manière naturelle, et sa visibilité à niveau de périphérique permet aux équipes de suivre l’adoption ou les signaux de failure après coup. Pour la partie instrumentation d’événements, consultez ce guide à la traçabilité d’événements personnalisés avec Capgo.

Les clés de signature et les informations d’administration doivent se trouver sur le serveur ou le système CI, et non dans l’application embarquée. Appliquez l’update à la prochaine mise en route, testez le rollback avec un bundle intentionnellement refusé, et enregistrez chaque décision avec un résultat typé. Cette combinaison maintient une livraison rapide compatible avec un contrôle de publication mobile discipliné.

Les écouteurs typés sont ce qui rend les APIs asynchrones faciles à faire confiance. Que ce soit un callback qui suit l'orientation de l'écran ou un Capgo événement d'update, il devrait recevoir la même forme de payload sur chaque plateforme — et c'est le compilateur qui devrait s'en charger.

interface ÉvénementMiseÀJour { version: string; chaîne: ‘bêta’ | ‘production’; disponible: boolean; }

= (payload: T) =&gt; void; interface ServiceMiseÀJour { ajouterUnÉcouteur( evénement: ‘miseÀJourDisponible’, callback: Écouteur

interface ServiceMiseÀJour { ajouterUnÉcouteur( événement: 'miseÀJourDisponible', callback: Écouteur )}&gt;; supprimerTousLesÉcouteurs(): Promise }&gt;;\nremoveAllListeners(): Promesse; }

This TypeScript API example fixe le nom d'événement à une valeur littérale et relie le callback à un payload typé. Votre éditeur complète automatiquement 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.

Enregistrer les Écouteurs de manière sécurisée

Enregistrer les Écouteurs de Façon Sécurisée

À l'intérieur d'un composant, gardez la gestion de la souscription à proximité pour que la suppression reste explicite. Le même modèle s'insère dans les hooks de cycle de vie d'Angular, les effets React et les hooks de montage Vue sans changements.

let orientationHandle: { remove: () =&gt; Promise} } | indéfini;

async function start() { orientationHandle = await ScreenOrientation.addListener( ‘écran d'orientationChange’, ({ type, angle }) => { console.log(type, angle); }, ); }

Fonction asynchrone stop() { await orientationHandle?.supprimer(); orientationHandle = undefined; }

Effectuez la suppression lorsque l'écran disparaît — et non seulement lorsque l'application entière se ferme. Omettez-le, et la navigation laisse des appels de rappel attachés à des sources d'événements natives. Vous finissez par avoir du travail redondant et des mises à jour de l'état périmées qui sont douloureux à suivre.

Chaque framework vous donne un crochet pour cela:

• Angular — déclenchez la suppression à partir de ngOnDestroy
• React — retourner une fonction de nettoyage asynchrone sûre useEffect
• Vue — annulez l'abonnement en onBeforeUnmount

Tout addListener appel doit avoir un chemin de suppression correspondant.

Choisissez la bonne méthode de nettoyage

Un handle retourné est la bonne approche lorsque l'un des composants possède une seule souscription. removeAllListeners() brille lorsque un service détient plusieurs écouteurs et est complètement réinitialisé.

async function resetUpdates(service: UpdateService) { attend service.removeAllListeners(); }

N'activez pas la méthode large depuis un composant partagé tandis que d'autres écrans dépendent encore du service. Lorsque la propriété est locale, restez avec les handles individuels. remove() Situation

Pour les notifications Capgo, gardez les payloads d'actualisation séparés des événements du dispositif. Testez ensuite l'inscription, la livraison et la suppression en les traitant séparément. guide de suivi des événements personnalisés Capgo a plus sur la partie intégration.

Avant de livrer, vérifiez trois choses : l'annulation supprime effectivement les gestionnaires, les promesses rejetées sont capturées et aucune fonction callback ne peut mettre à jour un composant détruit. Cette discipline garde les applications réactives Capacitor responsives sur Angular, React et Vue.

A bien construit Exemple de TypeScript API utilisez des verbes pour les méthodes, des noms pour les interfaces et restez fidèl’à des suffixes cohérents comme Options, Result, et EventLes noms clairs réduisent le temps d'abordage car les développeurs comprennent le contrat sans ouvrir la mise en œuvre.

Gardez les interfaces publiques petites. Exposez les capacités à travers des méthodes ciblées plutôt que de déposer des opérations liées de manière floue sur un seul objet.

• getStatus() lit l'état.
• updateConfig(options) modifie la configuration.
• addListener(event, callback) s'abonne aux changements.

Définissez les Entrées et Sorties avec Précision

Utilisez des interfaces d'options nommées lorsque les paramètres peuvent grandir :

interface Options de publication { channel : ‘beta’ | ‘production’; rolloutPercent : nombre; }

interface RésultatDePublication { version: string; accepté: boolean; }

async function publier( options: OptionsDePublication, ): Promise { return client.publier(options); }

Les génériques gagnent leur place lorsque un API encapsule différents payloads mais doit conserver leurs types spécifiques :

interface ReponseDeLAPI { data: T; idRequête: string; }

async function requêter(chemin: string): Promise&lt;ReponseDeLAPI&gt; { return fetchJson&lt;ReponseDeLAPI&gt;(chemin); }

Ne pas ajouter des génériques juste pour paraître flexibles. Un générique doit exprimer une relation réelle entre l'entrée et la sortie — sinon une interface concrète est plus facile à lire et à maintenir.

Rendre les états invalides difficiles à représenter, en particulier aux limites natives, réseau et mise à jour.

Documenter le comportement à côté du contrat. Aborder les permissions, les unités, les promesses rejetées, les champs optionnels et savoir si une méthode s'applique immédiatement ou lors du lancement suivant. Les commentaires en ligne devraient expliquer les décisions, pas répéter les noms de méthode.

Organiser Code pour le Changement

Séparer les types, la logique client, les adaptateurs de plateforme et les tests dans des fichiers prévisibles. Exporter les types publics à partir d'un point d'entrée et conserver les détails d'implémentation privés.

Pour les changements de plugin brisants, introduire une nouvelle interface majeure ou un niveau de compatibilité, conserver les méthodes obsolètes temporairement et écrire les étapes de migration. En savoir plus sur les stratégies de versionnage API avant de modifier les consommateurs.

Exécutez des contrôles de types stricts et des tests de contrat dans CI avant de livrer. Pour les Capgo workflows, vérifiez les valeurs de canal, la compatibilité native, les ensembles de fichiers signés et le comportement de retrait comme des règles de publication typées — cela maintient les mises à jour rapides sous contrôl’à mesure que les équipes, les plateformes et les intégrations grandissent.

Comment Typiser les Résultats Natives Dynamiques?

Ne laissez pas any se propager dans votre code lorsque une méthode native vous retourne des données imprévisibles. Au lieu de cela, définissez les champs que vous pouvez compter sur, marquez les valeurs optionnelles authentiques avec ?Et nettoyer les entrées douteuses avant qu'elles ne soient traitées par les composants suivants.

interface RésultatNatif { succès: boolean; valeur?: string; }

async fonction de lecture de valeur : Promesse const result = attend await NativePlugin.read(); return { succès : Boolean(result.succès), valeur : typeof result.valeur === 'chaîne' ? result.valeur : undefined, };

Cette approche garde vos appels utilisateurs en sécurité tout en rendant l'incertitude explicite dans le type lui-même. Pour une vision plus large de ce modèle d'interface, reprenez la construction d'APIs en TypeScript.

Comment les Écouteurs Peuvent-ils Éviter les Rejets Non Gérés?

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 =&gt; { void applyUpdate(event).catch((error: unknown) =&gt; { console.error(‘Mise à jour échouée’, error); }); };

Retenez la référence de la souscription et supprimez-la lorsque le composant se démonte. Cela empêche les appels de callbacks dupliqués et les mises à jour de l'état périmées — la section du cycle de vie du listener passe en revue cela en détail.

Tout listener asynchrone nécessite à la fois un chemin d'erreur et un chemin de nettoyage.

Comment Protéger les Mises à jour Capgo?

Les clés de signature et les informations d'identification administratives restent sur votre serveur ou votre système CI. La période. Le client ne devrait recevoir que des ensembles signés et utiliser des résultats typés pour afficher le statut — jamais pour créer des signatures.

Avant de publier, configurez des unions de canaux séparés, exécutez des contrôles de compatibilité, configurez des limites de lancement et planifiez votre chemin de reprise. Capgo handles signed delivery, channel controls, next-launch application, and rollback protection for Capacitor and Electron apps. Their docs show how typed release workflows can tighten up your update pipeline.