Guida Introduttiva

1. Installa il pacchetto

   npm

   npm i @capgo/capacitor-volume-buttons

   pnpm

   pnpm add @capgo/capacitor-volume-buttons

   yarn

   yarn add @capgo/capacitor-volume-buttons

   bun

   bun add @capgo/capacitor-volume-buttons

2. Sincronizza con i progetti nativi

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Utilizzo

import { VolumeButtons } from '@capgo/capacitor-volume-buttons';

// Listen for volume button presses
VolumeButtons.addListener('volumeButtonPressed', (event) => {
  console.log('Volume button pressed:', event.direction);

  if (event.direction === 'up') {
    console.log('Volume up pressed');
    // Handle volume up
  } else if (event.direction === 'down') {
    console.log('Volume down pressed');
    // Handle volume down
  }
});

// Remove all listeners when done
await VolumeButtons.removeAllListeners();

Riferimento API

addListener(‘volumeButtonPressed’, callback)

Ascolta gli eventi di pressione dei pulsanti volume.

const handle = VolumeButtons.addListener('volumeButtonPressed', (event) => {
  console.log('Direction:', event.direction); // 'up' or 'down'
});

// Remove specific listener
await handle.remove();

Dati Evento:

• direction: 'up' | 'down' - Direzione della pressione del pulsante

removeAllListeners()

Rimuovi tutti gli ascoltatori registrati.

await VolumeButtons.removeAllListeners();

getPluginVersion()

Ottieni la versione del plugin.

const { version } = await VolumeButtons.getPluginVersion();
console.log('Plugin version:', version);

Esempio Completo

import { VolumeButtons } from '@capgo/capacitor-volume-buttons';

export class VolumeButtonController {
  private listener: any;

  async initialize() {
    this.listener = VolumeButtons.addListener(
      'volumeButtonPressed',
      this.handleVolumeButton.bind(this)
    );

    console.log('Volume button listener initialized');
  }

  private handleVolumeButton(event: { direction: 'up' | 'down' }) {
    switch (event.direction) {
      case 'up':
        this.handleVolumeUp();
        break;
      case 'down':
        this.handleVolumeDown();
        break;
    }
  }

  private handleVolumeUp() {
    console.log('Volume up pressed');
    // Your custom logic for volume up
    // e.g., navigate forward, increase brightness, etc.
  }

  private handleVolumeDown() {
    console.log('Volume down pressed');
    // Your custom logic for volume down
    // e.g., navigate backward, decrease brightness, etc.
  }

  async cleanup() {
    if (this.listener) {
      await this.listener.remove();
    }
    await VolumeButtons.removeAllListeners();
    console.log('Volume button listener cleaned up');
  }
}

Casi d’Uso

Cattura Foto/Video

Usa i pulsanti volume come trigger per l’otturatore della fotocamera:

VolumeButtons.addListener('volumeButtonPressed', async (event) => {
  // Any volume button triggers camera
  await capturePhoto();
});

Navigazione Pagine

Naviga attraverso i contenuti con i pulsanti volume:

let currentPage = 0;

VolumeButtons.addListener('volumeButtonPressed', (event) => {
  if (event.direction === 'up') {
    currentPage++;
    showPage(currentPage);
  } else {
    currentPage = Math.max(0, currentPage - 1);
    showPage(currentPage);
  }
});

Controllo Media

Controlla la riproduzione multimediale:

VolumeButtons.addListener('volumeButtonPressed', (event) => {
  if (event.direction === 'up') {
    skipForward();
  } else {
    skipBackward();
  }
});

Controlli di Gioco

Usa i pulsanti volume per azioni di gioco:

VolumeButtons.addListener('volumeButtonPressed', (event) => {
  if (event.direction === 'up') {
    player.jump();
  } else {
    player.crouch();
  }
});

Migliori Pratiche

1. Pulisci gli ascoltatori Rimuovi sempre gli ascoltatori quando il tuo componente viene smontato:

   useEffect(() => {
     const listener = VolumeButtons.addListener('volumeButtonPressed', handler);
   
     return () => {
       listener.remove();
     };
   }, []);

2. Fornisci feedback visivo Mostra agli utenti che i pulsanti volume vengono utilizzati per controlli personalizzati:

   VolumeButtons.addListener('volumeButtonPressed', (event) => {
     showNotification(`Volume ${event.direction} pressed`);
     performAction(event.direction);
   });

3. Considera l’accessibilità Ricorda che alcuni utenti si affidano ai pulsanti volume per il controllo effettivo del volume. Fornisci controlli alternativi.

4. Debounce delle pressioni rapide Previeni doppie pressioni accidentali:

   let lastPress = 0;
   const DEBOUNCE_MS = 300;
   
   VolumeButtons.addListener('volumeButtonPressed', (event) => {
     const now = Date.now();
     if (now - lastPress < DEBOUNCE_MS) {
       return; // Ignore rapid presses
     }
     lastPress = now;
     handlePress(event.direction);
   });

5. Documenta il comportamento Rendi chiaro agli utenti che i pulsanti volume hanno funzionalità personalizzate:

   function showVolumeButtonHelp() {
     alert('Use Volume Up/Down buttons to navigate pages');
   }

Note sulle Piattaforme

iOS

• Funziona su iOS 10.0+
• Pulsanti volume rilevati in modo affidabile
• L’interfaccia volume di sistema potrebbe apparire brevemente

Android

• Funziona su Android 5.0 (API 21)+
• Richiede che l’app sia in primo piano
• Alcuni dispositivi potrebbero avere un leggero ritardo

Web

• Non supportato sulla piattaforma web
• Gli ascoltatori non si attiveranno

Risoluzione dei Problemi

Gli eventi non si attivano:

• Assicurati che l’app abbia il focus
• Verifica che gli ascoltatori siano registrati correttamente
• Verifica che il plugin sia installato e sincronizzato

Le modifiche del volume di sistema interferiscono:

• Questo è un comportamento previsto - il plugin rileva le pressioni ma non impedisce le modifiche del volume di sistema
• Considera un’esperienza utente che funzioni insieme alle modifiche del volume

Si attivano eventi multipli:

• Implementa il debouncing per gestire pressioni rapide
• Controlla la registrazione duplicata degli ascoltatori