Vai al contenuto
Capgo

Getting Started

Questo contenuto non è ancora disponibile nella tua lingua.

  1. Install the package

    Terminal window
    npm i @capgo/capacitor-volume-buttons

  2. Sync with native projects

    Terminal window
    npx cap sync

Usage

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 Reference

addListener(‘volumeButtonPressed’, callback)

Listen for volume button press events.

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


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

Event Data:

  • direction: 'up' | 'down' - Direction of the button press

removeAllListeners()

Remove all registered listeners.

await VolumeButtons.removeAllListeners();

getPluginVersion()

Get the plugin version.

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

Complete Example

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

Use Cases

Photo/Video Capture

Use volume buttons as camera shutter triggers:

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

Page Navigation

Navigate through content with volume buttons:

let currentPage = 0;


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

Media Control

Control media playback:

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

Game Controls

Use volume buttons for game actions:

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

Best Practices

  1. Clean up listeners Always remove listeners when your component unmounts:

    useEffect(() => {
      const listener = VolumeButtons.addListener('volumeButtonPressed', handler);
    

      return () => {
        listener.remove();
      };
    }, []);

  2. Provide visual feedback Show users that volume buttons are being used for custom controls:

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

  3. Consider accessibility Remember that some users rely on volume buttons for actual volume control. Provide alternative controls.

  4. Debounce rapid presses Prevent accidental double-presses:

    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. Document the behavior Make it clear to users that volume buttons have custom functionality:

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

Platform Notes

iOS

  • Works on iOS 10.0+
  • Volume buttons detected reliably
  • System volume UI may still appear briefly

Android

  • Works on Android 5.0 (API 21)+
  • Requires app to be in foreground
  • Some devices may have slight delay

Web

  • Not supported on web platform
  • Listeners will not fire

Troubleshooting

Events not firing:

  • Ensure app has focus
  • Check that listeners are properly registered
  • Verify plugin is installed and synced

System volume changes interfere:

  • This is expected behavior - the plugin detects presses but doesn’t prevent system volume changes
  • Consider UX that works alongside volume changes

Multiple events firing:

  • Implement debouncing to handle rapid presses
  • Check for duplicate listener registration