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 qui est effectivement appliqué par TypeScript.

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 correctement les arguments
  • Définir les contrats d'actualisation
  • Protéger les canaux et la compatibilité
  • Enregistrer les Écouteurs de manière Sécurisée
  • Choisir la Méthode de Nettoyage Adéquate
  • Typiser les Entrées et Sorties avec Précision
  • Organiser 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 ?

Construire une Interface de Plugin Capacitor Fortement Typé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(‘Dispositif’);

Il y a beaucoup de choses en jeu dans ces quelques lignes.

• Types de retour explicites gardez chaque résultat prévisible.
• Objets d'options typés attrapez les propriétés manquantes ou mal orthographiées en temps de compilation.
• Méthodes basées sur des promesses travail natif qui se termine de manière asynchrone.
• Un type générique registerPlugin appel est ce qui relie le web API à la passerelle native.
• Interfaces documentent l'accord sans ajouter une seule octet 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' } et { name: 'Production' } et le compilateur le signale immédiatement. Cela bat le temps de découvrir la différence après une mise à jour mobile.

L'interface est également là où vous modélisez les valeurs optionnelles et les cas de défaillance. Si une méthode native ne peut pas toujours produire une lecture de 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 : Les définitions de type s'écoulent de l'interface web vers la logique de plateforme nativeet les vérifications de temps de compilation gardent la garde à chaque site d'appel.

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, le code natif code, les permissions de périphérique 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 cela 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 retourne 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 d'un million de __CAPGO_KEEP_0__ contributeurs un million GitHub contributeurs Listé comme leur langue principale d'ici 2025. Découvrez la version complète. plus d'un million de __CAPGO_KEEP_0__ contributeurs Si vous voulez les nombres bruts.

Cette trajectoire compte pour les organisations mobiles de manière pratique. Le recrutement, la mise en place et la code de la 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 requête native incomplète.

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

Avantages pour les Capacitor équipes.

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 chargeurs connus.
• Erreurs et valeurs de statut, les chemins de fallback restent donc 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 liés, 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 produit normalement entre la documentation API et l'application code.

Argumenter en faveur de l'entreprise

Le typage strict demande une certaine investissement à l'avance, surtout lorsque les anciens code JavaScript portent des formes de données incohérentes. Le retour s'affiche 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. Activer les contrôles compilateurs stricts de manière incrémentale.
4. Exécutez les contrôles 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 un excellent Exemple de TypeScript API car il cartographie une poignée de méthodes web simples sur le comportement de dispositif spécifique des 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éesD'orientation {\ntype: TypeD'orientation;\nangle: nombre;\n}

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

export interface ScreenOrientationPlugin { orientation(): Promise }; verrouille(options: OptionsDeVerrouillage): Promise; déverrouille(): Promise; ajouteEventListener( eventName: ‘changeDorientationDeL’écran’, listenerFunc: (données: DonnéesDorientation) => void, ): Promise<{ supprimer: () => Promise} } }

export const OrientationDeL’écran = registerPlugin(‘OrientationDeL’écran’);

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 comportement normal 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 spécial.

const current = attendre await ScreenOrientation.orientation();

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

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

Typifiez 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.

Typifiez Correctement les Arguments des Écouteurs

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

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

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

attendre subscription.remove();

Partagez uniquement un OrientationData type lorsqu'une implémentation native garantit les mêmes champs. Si l'un des plateformes omet angle, la marquez comme optionnel et forcez les appelleurs à gérer undefined.

L’interface est le contrat de pont, pas l'implémentation native. Gardez-le petit, prévisible et testable.

Pour les comportements de plateforme, les autorisations et les étapes d'installation, consultez 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 TypeScript strict. Cette combinaison repère 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 JavaScript, CSS, de configuration et d'actifs sans passer par la revue des magasins d'applications. Le secret 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 roulement, 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 DemandeD'actualisation { canal: Canal; bundleVersion: string; minNativeVersion: string; rolloutPercent: number; signé: boolean; }

interface ResultMiseÀ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 publierMiseAJour( request: DemandeMiseAJour, ): 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: DemandeMiseÀJour, versionNativeInstallée: string, ): boolean { return request.signed && versionNativeInstallée >= request.minNativeVersion; }

function peutDéployer(\nrequête: RequêteMiseÀJour,\nversionNATIVEInstallée: chaîne,\n): boolean {\nreturn requête.signée &amp;&amp;\nversionNATIVEInstallée >= requête.minVersionNATIVE;\n}

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

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 d'abord à un public limité.
5. Regardez les signaux de failure et gardez un rollback prêt.

Une pipeline d'actualisation typée transforme la politique de publication en code que les réviseurs et la CI peuvent inspecter effectivement.

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'administrateur doivent se trouver sur le serveur ou le système CI, et non dans l'application embarquée. Appliquez l'actualisation à 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 mise à jour mobile discipliné.

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

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

type Écouteur void (payload: T) => void

interface ServiceMiseÀJour { ajouterUnÉcouteur( evénement: ‘miseÀJourDisponible’, callback: Écouteur, ): Promise&lt;{ supprimer: () =&gt; Promise} &gt;; supprimerTousLesÉcouteurs(): Promise; }

Ceci Exemple TypeScript API fixe le nom de l'événement à une valeur littérale et relie le callback à un payload typé. Votre éditeur complète automatiquement version et le compilateur rejette tout callback qui attend des données non liées. Il s'agit d'une petite quantité de configuration, et cela rapporte à chaque fois que l’API change.

Préférez le voir en action ? Regardez la démonstration :

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

À l'intérieur d'un composant, gardez la référence de la souscription pour que la suppression reste explicite. Le même modèle se dépose dans les hooks de cycle de vie d'Angular, les effets React et les hooks de montage Vue sans changements.

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

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

Fonction asynchrone stop() { attendre 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.

Chaque framework vous offre un point d'entrée pour cela :

• Angular — déclenche la suppression ngOnDestroy
• React returner une fonction de nettoyage asynchrone sécurisée 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 de mise à jour séparés des événements du dispositif. Testez ensuite l'inscription, la livraison et la suppression sur leur propre — le 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 de rappel 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 noms qui décrivent l'intention. Les verbes pour les méthodes, les noms pour les interfaces et restez cohérent avec des suffixes comme Options, Resultet 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 étroitement liées sur un seul objet.

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

Définir 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 flexible. 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.

Faites les états invalides difficiles à représenterparticulièrement aux frontières natives, réseau et mise à jour.

Documenter le comportement en même temps que le contrat. Aborder les permissions, les unités, les promesses rejetées, les champs facultatifs et savoir si une méthode s'applique immédiatement ou lors du prochain démarrage. Les commentaires en ligne devraient expliquer les décisions, pas répéter les noms de méthode.

Organiser Code pour le Changement

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

Pour les modifications importantes des plugins, introduisez une nouvelle interface majeure ou un niveau de compatibilité, maintenez les méthodes obsolètes temporairement et documentez les étapes de migration. En savoir plus sur les stratégies de versionnement 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 Dois-je Typiser les Résultats Dynamiques Natives?

Ne laissez pas any se propager dans votre code lorsqu'une méthode native vous retourne des données imprévisibles. Au lieu de cela, définissez les champs dont vous pouvez vous fier, marquez les valeurs optionnelles réelles 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 lireValeur(): Promise const résultat = attendre NativePlugin.read(); retourner { succès : Boolean(résultat.succès), valeur : typeof résultat.valeur === 'chaîne' ? résultat.valeur : undefined, };

Cette approche garde vos appelsur la sécurité tout en rendant l'incertitude explicite dans le type lui-même. Pour une vue 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 la supprimez lorsque le composant se démonte. Cela empêche les appels de callbacks dupliqués et les mises à jour de l'état obsolètes — la section du cycle de vie du listener passe en détail par là.

Tout listener asynchrone nécessite à la fois une voie d'erreur et une voie 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 retrait. 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.