Commencer

1. Installez le package

   npm

   npm i @capgo/capacitor-navigation-bar

   pnpm

   pnpm add @capgo/capacitor-navigation-bar

   yarn

   yarn add @capgo/capacitor-navigation-bar

   bun

   bun add @capgo/capacitor-navigation-bar

2. Synchronisation avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurez le plugin

   Définir la couleur de la barre de navigation :

   import { NavigationBar } from '@capgo/capacitor-navigation-bar';
   
   // Set navigation bar color
   await NavigationBar.setColor({
     color: '#FF0000', // Red color
     darkButtons: false // Use light buttons
   });

   Prise en charge des thèmes dynamiques :

   // Set color based on theme
   const isDarkMode = window.matchMedia('(prefers-color-scheme: dark)').matches;
   
   await NavigationBar.setColor({
     color: isDarkMode ? '#000000' : '#FFFFFF',
     darkButtons: !isDarkMode
   });

   Android

   Exigences minimales :

   • Android 5.0 (API niveau 21) ou supérieur
   • Le plugin ne fonctionne que sur les appareils Android

   Aucune configuration supplémentaire requise dans AndroidManifest.xml.

   iOS

   Ce plugin est uniquement Android. iOS n’a pas de barre de navigation personnalisable.

4. Utilisation avancée

   import { NavigationBar } from '@capgo/capacitor-navigation-bar';
   
   export class ThemeService {
     // Set transparent navigation bar
     async setTransparent() {
       await NavigationBar.setColor({
         color: '#00000000', // Transparent
         darkButtons: true
       });
     }
   
     // Match app theme
     async matchAppTheme(primaryColor: string, isLight: boolean) {
       await NavigationBar.setColor({
         color: primaryColor,
         darkButtons: isLight
       });
     }
   
     // Get current navigation bar color
     async getCurrentColor() {
       const result = await NavigationBar.getColor();
       console.log('Current color:', result.color);
       return result.color;
     }
   
     // Reset to default
     async resetToDefault() {
       await NavigationBar.setColor({
         color: '#000000',
         darkButtons: false
       });
     }
   }

5. Intégration avec le cycle de vie des applications

   import { App } from '@capacitor/app';
   import { NavigationBar } from '@capgo/capacitor-navigation-bar';
   
   // Update navigation bar on app state changes
   App.addListener('appStateChange', async ({ isActive }) => {
     if (isActive) {
       // Restore your app's navigation bar color
       await NavigationBar.setColor({
         color: '#YourAppColor',
         darkButtons: true
       });
     }
   });
   
   // Handle theme changes
   window.matchMedia('(prefers-color-scheme: dark)')
     .addEventListener('change', async (e) => {
       await NavigationBar.setColor({
         color: e.matches ? '#121212' : '#FFFFFF',
         darkButtons: !e.matches
       });
     });

API Référence

Méthodes

setColor(options: ColorOptions)

Définissez la couleur de la barre de navigation et le style des boutons.

Paramètres :

• options : Objet de configuration
  • color : chaîne - Code couleur hexadécimal (par exemple, ‘#FF0000’)
  • darkButtons : booléen - Utiliser des boutons sombres (vrai) ou des boutons clairs (faux)

Retours : Promise<void>

getColor()

Obtenez la couleur actuelle de la barre de navigation.

Retours : Promise<{ color: string }>

###Interfaces

interface ColorOptions {
  color: string;      // Hex color code
  darkButtons: boolean; // Button style
}

interface ColorResult {
  color: string;      // Current hex color
}

## Remarques sur la plate-forme

Android

• Nécessite Android 5.0 (API niveau 21) ou supérieur
• Les changements de couleur sont immédiats
• Les couleurs transparentes sont prises en charge (utilisez le canal alpha)
• La barre de navigation peut ne pas être visible sur les appareils dotés de navigation gestuelle

iOS

• Ce plugin n’a aucun effet sur les appareils iOS
• iOS ne fournit pas d’API pour personnaliser la navigation du système

Cas d’utilisation courants

1. Cohérence de la marque : faites correspondre la barre de navigation avec la couleur principale de votre application
2. Prise en charge des thèmes : Adaptez-vous dynamiquement aux thèmes clairs/sombres
3. Expériences immersives : utilisez une navigation transparente pour le contenu en plein écran
4. Indication d’état : changez la couleur pour indiquer les états de l’application (enregistrement, erreurs, etc.)

## meilleures pratiques

1. Contraste des couleurs : assurez un contraste suffisant entre la barre de navigation et les boutons

   // Good contrast examples
   setColor({ color: '#FFFFFF', darkButtons: true });  // White bar, dark buttons
   setColor({ color: '#000000', darkButtons: false }); // Black bar, light buttons

2. Cohérence du thème : mettre à jour la barre de navigation lorsque le thème change

3. Accessibilité : Tenez compte des utilisateurs malvoyants lors du choix des couleurs

4. Performance : évitez les changements de couleur fréquents qui pourraient distraire les utilisateurs

Dépannage

La barre de navigation ne change pas :

• Vérifiez que l’appareil exécute Android 5.0+
• Vérifiez si la navigation gestuelle est activée sur l’appareil
• Assurez-vous que le format de couleur est un hexadécimal valide (par exemple, « #FF0000 »)

Boutons non visibles :

• Vérifiez que le paramètre darkButtons correspond à votre couleur de fond
• Les arrière-plans clairs nécessitent darkButtons: true
• Les arrière-plans sombres nécessitent darkButtons: false

La couleur semble différente :

• Certaines versions Android peuvent modifier légèrement la couleur
• Utilisez des couleurs entièrement opaques pour de meilleurs résultats