Empezando

1. Instalar el paquete

   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. Sincronización con proyectos nativos

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Uso

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();

API Referencia

addListener(‘volumeButtonPressed’, devolución de llamada)

Escuche los eventos de pulsación del botón de volumen.

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

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

Datos del evento:

• direction: 'arriba' | 'abajo' - Dirección de pulsación del botón

eliminarTodos los oyentes()

Elimine a todos los oyentes registrados.

await VolumeButtons.removeAllListeners();

obtenerPluginVersion()

Obtenga la versión del complemento.

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

Ejemplo 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');
  }
}

Casos de uso

Captura de foto/vídeo

Utilice los botones de volumen como disparadores del obturador de la cámara:

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

Navegación de página

Navega por el contenido con los botones de volumen:

let currentPage = 0;

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

Control de medios

Controlar la reproducción multimedia:

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

Controles del juego

Utilice botones de volumen para acciones del juego:

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

Mejores prácticas

1. Limpiar a los oyentes Elimine siempre los oyentes cuando su componente se desmonte:

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

2. Proporcione comentarios visuales Muestre a los usuarios que los botones de volumen se utilizan para controles personalizados:

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

3. Considere la accesibilidad Recuerde que algunos usuarios confían en los botones de volumen para controlar el volumen real. Proporcionar controles alternativos.

4. Presiones rápidas antirrebote Evite pulsaciones dobles accidentales:

   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. Documente el comportamiento Deje claro a los usuarios que los botones de volumen tienen una funcionalidad personalizada:

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

Notas de plataforma

iOS

• Funciona en iOS 10.0+
• Botones de volumen detectados de forma fiable
• Es posible que la interfaz de usuario del volumen del sistema aún aparezca brevemente

Android

• Funciona en Android 5.0 (API 21)+
• Requiere que la aplicación esté en primer plano
• Algunos dispositivos pueden tener un ligero retraso

Web

• No compatible con la plataforma web
• Los oyentes no dispararán.

Solución de problemas

Eventos que no se activan:

• Asegúrese de que la aplicación tenga el foco
• Comprobar que los oyentes estén correctamente registrados.
• Verificar que el complemento esté instalado y sincronizado

Los cambios de volumen del sistema interfieren:

• Este es el comportamiento esperado: el complemento detecta pulsaciones pero no evita los cambios de volumen del sistema.
• Considere una UX que funcione junto con los cambios de volumen

Activación de múltiples eventos:

• Implementar antirrebote para manejar prensas rápidas.
• Verifique si hay registros de oyentes duplicados