Iniziare

1. Installa il pacchetto

   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. Sincronizzazione con progetti nativi

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configura il plugin

   Imposta il colore della barra di navigazione:

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

   Supporto temi dinamici:

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

   Android

   Requisiti minimi:

   • Android 5.0 (API livello 21) o superiore
   • Il plug-in funziona solo su dispositivi Android

   Non è richiesta alcuna configurazione aggiuntiva in AndroidManifest.xml.

   iOS

   Questo plugin è solo Android. iOS non ha una barra di navigazione personalizzabile.

4. Utilizzo avanzato

   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. Integrazione con il ciclo di vita dell’app

   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 Riferimento

Metodi

setColor(options: ColorOptions)

Imposta il colore della barra di navigazione e lo stile dei pulsanti.

Parametri:

• options: oggetto di configurazione
  • color: stringa - Codice colore esadecimale (ad esempio, ‘#FF0000’)
  • darkButtons: booleano - Utilizza pulsanti scuri (vero) o pulsanti chiari (falso)

Resi: Promise<void>

getColor()

Ottieni il colore corrente della barra di navigazione.

Resi: Promise<{ color: string }>

Interfacce

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

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

Note sulla piattaforma

Android

• Richiede Android 5.0 (API livello 21) o successivo
• I cambiamenti di colore sono immediati
• Sono supportati i colori trasparenti (usa il canale alfa)
• La barra di navigazione potrebbe non essere visibile sui dispositivi con navigazione gestuale

iOS

• Questo plugin non ha effetto sui dispositivi iOS
• iOS non fornisce API per personalizzare la navigazione del sistema

Casi d’uso comuni

1. Coerenza del marchio: abbina la barra di navigazione al colore principale della tua app
2. Supporto temi: adatta dinamicamente ai temi chiari/scuri
3. Esperienze coinvolgenti: utilizza la navigazione trasparente per i contenuti a schermo intero
4. Indicazione stato: cambia colore per indicare gli stati dell’app (registrazione, errori, ecc.)

Migliori pratiche

1. Contrasto colore: garantisce un contrasto sufficiente tra la barra di navigazione e i pulsanti

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

2. Coerenza del tema: aggiorna la barra di navigazione quando il tema cambia

3. Accessibilità: considera gli utenti con problemi di vista nella scelta dei colori

4. Prestazioni: evita frequenti cambi di colore che potrebbero distrarre gli utenti

Risoluzione dei problemi

La barra di navigazione non cambia:

• Verificare che sul dispositivo sia in esecuzione Android 5.0+
• Controlla se sul dispositivo è abilitata la navigazione gestuale
• Assicurati che il formato del colore sia esadecimale valido (ad esempio, “#FF0000”)

Pulsanti non visibili:

• Controlla che il parametro darkButtons corrisponda al colore dello sfondo
• Gli sfondi chiari richiedono darkButtons: true
• Gli sfondi scuri richiedono darkButtons: false

Il colore appare diverso:

• Alcune versioni Android potrebbero modificare leggermente il colore
• Utilizza colori completamente opachi per ottenere i migliori risultati