⚡ 3.4 Utiliser les API natives avec Capacitor

Ionic est un framework web. Grâce à Capacitor, vous pouvez accéder à des fonctionnalités 100% natives :

  • appareil photo 📷
  • stockage & fichiers 📂
  • réseau 🌐
  • partage 📨
  • vibrations / haptique 📳
  • … et bien plus

👉 Capacitor agit comme un pont entre votre code JavaScript/Vue et les API Android / iOS.

⚠️ Important – Plugins Capacitor

  • Les plugins vus en cours ne sont qu’une sélection.

  • Il existe aussi des plugins “Community” (créés par la communauté).

  • Certains plugins nécessitent des configurations supplémentaires dans :

    • le projet Android (Android Studio)
    • le projet iOS (Xcode)

➡️ Toujours lire la doc officielle du plugin utilisé : https://capacitorjs.com/docs/plugins

📘 3.4.1 – Qu’est-ce que Capacitor ?

Capacitor permet à une application Ionic de :

  • s’afficher dans une WebView native (Android / iOS)
  • accéder aux API natives (caméra, fichiers, réseau…)
  • générer des projets Android / iOS automatiquement
  • utiliser des plugins écrits en Swift (iOS) et Kotlin/Java (Android)
  • rester 100% JavaScript/TypeScript côté développeur

🔌 Capacitor – Vue d’ensemble

Rôle de Capacitor : faire le lien entre :

  • votre app Ionic-Vue (HTML/CSS/TS)
  • les projets natifs Android / iOS
  • les API natives (camera, haptics, filesystem…)

⚔️ Capacitor vs Cordova

Feature Cordova Capacitor
Architecture Ancienne Moderne
Plugins Nombreux mais vieillissants Officiels + support TypeScript
Intégration web Moyenne Excellente
Maintenance Faible Très active
Web-first ❌ ✔️

👉 Conclusion : Capacitor est aujourd’hui l’outil recommandé pour les apps Ionic.

🆕 Ajouter Capacitor à un projet

À la création d’un projet Ionic-Vue :

ionic start my-app blank --type=vue --capacitor

  • --capacitor ajoute Capacitor dès le départ

  • Génère automatiquement :

    • config Capacitor
    • structure pour Android / iOS

🗃️ 3.4.2 – Structure d’un projet avec Capacitor

Après création / ajout de Capacitor :

my-app/
├─ android/              # Projet Android natif (Kotlin/Java)
├─ ios/                  # Projet iOS natif (Swift)
├─ src/                  # Votre app Vue/Ionic
├─ capacitor.config.ts   # Config Capacitor
└─ package.json

🛠️ Commandes importantes

Synchroniser et ouvrir les projets natifs :

ionic cap sync
ionic cap open android
ionic cap open ios
ionic cap run android --livereload

Installer un plugin (ex. caméra) :

npm install @capacitor/camera

➡️ Vérifier la doc officielle pour chaque plugin.

🔁 Cycle typique de développement mobile

  1. Vous modifiez le code Ionic-Vue (src/…)
  2. Build de la partie web :
ionic build
  1. Sync avec les projets natifs :
ionic cap sync
  1. Ouverture du projet :
ionic cap open android   # ou ios

En pratique :

  • 90% du temps : ionic serve (dev UI)
  • ponctuellement : build + tests sur émulateur / téléphone pour les APIs natives

📷 3.4.3 – API native : Camera (intro)

L’API Camera permet de :

  • prendre une photo

  • choisir une photo dans la galerie

  • récupérer l’image en :

    • URI
    • base64
    • fichier temporaire

Cas d’usage :

  • photo de profil
  • scan de document
  • capture de reçu / justificatif

📷 Camera – Exemple complet (template)

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Caméra</ion-title>
      </ion-toolbar>
    </ion-header>

    <ion-content class="ion-padding">
      <ion-button expand="block" @click="takePhoto">
        Prendre une photo
      </ion-button>

      <img v-if="photo" :src="photo" class="preview" />
    </ion-content>
  </ion-page>
</template>

📷 Camera – Exemple complet (script + style)

<script setup lang="ts">
import { Camera, CameraResultType, CameraSource } from '@capacitor/camera'
import { ref } from 'vue'

const photo = ref<string | null>(null)

async function takePhoto() {
  const img = await Camera.getPhoto({
    quality: 70,
    resultType: CameraResultType.Uri,
    source: CameraSource.Camera
  })

  photo.value = img.webPath ?? null
}
</script>

<style>
.preview {
  width: 100%;
  margin-top: 16px;
  border-radius: 12px;
}
</style>

📷 Camera – Permissions Android / iOS

Sur Android :

  • les permissions nécessaires sont ajoutées au AndroidManifest
  • Capacitor vous signale ce qu’il faut configurer si besoin

Sur iOS : ➜ ajouter des descriptions dans Info.plist :

  • NSCameraUsageDescription
  • NSPhotoLibraryUsageDescription

iOS affiche ce texte dans le popup de demande d’autorisation.

📂 3.4.4 – API native : Filesystem (intro)

L’API Filesystem permet :

  • d’écrire des fichiers localement
  • de lire des fichiers
  • de définir un répertoire (Documents, Data, Cache…)

Cas d’usage :

  • stocker des exports temporaires
  • générer un fichier texte, JSON, PDF…
  • conserver des données hors-ligne plus “brutes”

📂 Filesystem – Écrire un fichier

import { Filesystem, Directory, Encoding } from '@capacitor/filesystem'

await Filesystem.writeFile({
  path: 'note.txt',
  data: 'Hello world!',
  directory: Directory.Documents,
  encoding: Encoding.UTF8
})

📂 Filesystem – Lire un fichier

const result = await Filesystem.readFile({
  path: 'note.txt',
  directory: Directory.Documents
})

console.log(result.data)

🌐 Filesystem – Web vs Natif

Dans un navigateur :

  • Filesystem utilise un espace sandboxé
  • pas d’accès au “vrai” système de fichiers de l’OS

Sur mobile (Android / iOS) :

  • accès à des répertoires natifs :

    • Documents
    • Data
    • Cache

  • persistance plus “profonde” côté OS

🔑 3.4.5 – API native : Preferences (clé → valeur)

Stockage simple clé → valeur, idéal pour :

  • préférences utilisateur (thème, langue…)
  • paramètres (options activées / désactivées)
  • token d’authentification
  • flag “déjà vu le tutoriel”

🔑 Preferences – Exemple complet

import { Preferences } from '@capacitor/preferences'

// Sauvegarde
await Preferences.set({
  key: 'theme',
  value: 'dark'
})

// Lecture
const res = await Preferences.get({ key: 'theme' })
console.log(res.value)

Fonctionnellement proche de localStorage, mais avec une API asynchrone et un stockage natif.

🌐 3.4.6 – API native : Network (important)

Permet de :

  • savoir si l’utilisateur est en ligne ou non

  • écouter les changements de réseau :

    • wifi → 4G/5G
    • 4G → offline
    • etc.

Très utile pour :

  • activer un mode offline
  • déclencher une synchronisation (voir chapitres 2.4 et 2.6.8)

🌐 Network – Récupérer l’état du réseau

import { Network } from '@capacitor/network'

const status = await Network.getStatus()

console.log('Connected ?', status.connected)
// status.connectionType → wifi, cellular, none, unknown…

🌐 Network – Écouter les changements

import { Network } from '@capacitor/network'

Network.addListener('networkStatusChange', status => {
  console.log('Network status:', status.connected)
})

Cas d’usage :

  • afficher un toast “Vous êtes hors ligne”
  • lancer syncPendingActions() quand status.connected === true

📳 3.4.7 – API native : Haptics (vibrations)

L’API Haptics permet :

  • des vibrations courtes
  • des retours tactiles discrets
  • un feedback “physique” pour l’utilisateur

Idéal pour :

  • valider une action
  • signaler une erreur
  • accompagner un geste (glisser, drag & drop, swipe…)

📳 Haptics – Exemple complet

import { Haptics, ImpactStyle } from '@capacitor/haptics'

await Haptics.impact({ style: ImpactStyle.Medium })

Autres méthodes :

  • Haptics.vibrate({ duration })
  • Haptics.selectionStart()
  • Haptics.selectionChanged()

Très utile pour rendre l’UI plus “vivante” sur mobile.

📨 3.4.8 – API native : Share (partage)

L’API Share permet d’ouvrir la feuille de partage native :

  • sur Android : partage vers toutes les apps compatibles
  • sur iOS : même principe (AirDrop, Messages, Mail, etc.)

Cas d’usage :

  • partager une note, un lien, une image
  • inviter un ami
  • envoyer une information rapidement

📨 Share – Exemple complet

import { Share } from '@capacitor/share'

await Share.share({
  title: 'Ma note',
  text: 'Voici une note importante.',
  url: 'https://example.com'
})

Capacitor se charge d’ouvrir l’UI de partage appropriée.

🆚 3.4.9 – Différencier Web vs Mobile

Certaines APIs ne fonctionnent pas en Web (navigateur).

Exemples :

  • Camera
  • Haptics (partiellement)
  • certains plugins “hardware”

👉 Il faut parfois tester la plateforme avant d’appeler un plugin.

🆚 Détection de plateforme (Capacitor)

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()
console.log(isNative) // true = Android/iOS, false = Web

const platform = Capacitor.getPlatform()
console.log(platform) // 'ios', 'android', 'web', 'electron'

Cas d’usage :

  • adapter le comportement en Web
  • proposer un fallback (input file, message, etc.)

🆚 Fallback caméra en Web – Exemple

import { Capacitor } from '@capacitor/core'
import { Camera, CameraResultType } from '@capacitor/camera'

if (!Capacitor.isNativePlatform()) {
  // Fallback navigateur
  document.querySelector('#fileInput')?.click()
} else {
  const image = await Camera.getPhoto({
    resultType: CameraResultType.Uri
  })
}

Idée : sur Web, on utilise un <input type="file"> à la place.

🧩 Vérifier la disponibilité d’un plugin

import { Capacitor } from '@capacitor/core'

const isAvailable = Capacitor.isPluginAvailable('Camera')

if (!isAvailable) {
  // Proposer une alternative
} else {
  const image = await Camera.getPhoto({
    resultType: CameraResultType.Uri
  })
}

Permet d’éviter les erreurs si un plugin n’est pas supporté sur une plateforme.

🧪 3.4.10 – Activité : “Mini Kit Natif”

🎯 Objectif : créer une page pour tester plusieurs APIs natives.

Dans une nouvelle page :

  1. Ajouter 4 boutons :

    • Caméra → prendre une photo et l’afficher
    • Haptique → vibration / impact
    • Réseau → afficher un toast “En ligne / Hors ligne”
    • Préférences → sauvegarder un paramètre utilisateur

  2. Afficher les résultats dans l’UI :

    • image
    • message
    • console, etc.

🧪 Interface suggérée

<ion-button expand="block" @click="takePhoto">
  Caméra
</ion-button>

<ion-button expand="block" @click="vibrate">
  Haptique
</ion-button>

<ion-button expand="block" @click="checkNetwork">
  Réseau
</ion-button>

<ion-button expand="block" @click="savePref">
  Préférences
</ion-button>

Bonus : ajoutez des ion-toast pour afficher les messages de résultat.

💻 Variante Web (si pas d’appareil physique)

Si vous ne pouvez pas déployer sur un téléphone :

  • Caméra :

    • utiliser un <input type="file"> en fallback si !Capacitor.isNativePlatform()

  • Haptics :

    • si non dispo → afficher un toast “Vibration simulée”

  • Réseau :

    • Network.getStatus() fonctionne aussi en Web

  • Préférences :

    • Preferences fonctionne en Web → vérifier après refresh

🎯 But : la page doit fonctionner sans erreur :

  • en Web (ionic serve)
  • en natif (Android / iOS) avec les mêmes boutons

✅ Résumé 3.4 – Capacitor

  • Capacitor = pont entre Ionic et les API natives

  • Plugins principaux vus :

    • Camera, Filesystem, Preferences
    • Network, Haptics, Share

  • Nécessité de :

    • synchroniser (ionic cap sync)
    • distinguer web / natif si besoin
    • vérifier la disponibilité des plugins

💡 Retenir : vous pouvez faire beaucoup de choses “comme une vraie app native”, tout en restant en Ionic-Vue + TypeScript.