Getting Started

1. パッケージをインストールする

   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. ネイティブプロジェクトと同期する

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

使用方法

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リファレンス

addListener(‘volumeButtonPressed’, callback)

ボリュームボタンの押下イベントをリッスンします。

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

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

イベントデータ:

• direction: 'up' | 'down' - ボタン押下の方向

removeAllListeners()

登録されているすべてのリスナーを削除します。

await VolumeButtons.removeAllListeners();

getPluginVersion()

プラグインのバージョンを取得します。

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

完全な例

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

ユースケース

写真/動画撮影

ボリュームボタンをカメラシャッタートリガーとして使用します：

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

ページナビゲーション

ボリュームボタンでコンテンツをナビゲートします：

let currentPage = 0;

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

メディアコントロール

メディアの再生を制御します：

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

ゲームコントロール

ボリュームボタンをゲームアクションに使用します：

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

ベストプラクティス

1. リスナーのクリーンアップ コンポーネントがアンマウントされるときは、常にリスナーを削除してください：

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

2. 視覚的なフィードバックを提供 ボリュームボタンがカスタムコントロールに使用されていることをユーザーに示してください：

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

3. アクセシビリティを考慮 一部のユーザーは実際のボリュームコントロールのためにボリュームボタンに依存していることを忘れないでください。代替コントロールを提供してください。

4. 連続押下のデバウンス 誤ったダブルプレスを防ぎます：

   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. 動作を文書化 ボリュームボタンがカスタム機能を持つことをユーザーに明確に示してください：

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

プラットフォームに関する注意事項

iOS

• iOS 10.0以降で動作
• ボリュームボタンは確実に検出されます
• システムのボリュームUIが短時間表示される場合があります

Android

• Android 5.0 (API 21)以降で動作
• アプリがフォアグラウンドにある必要があります
• 一部のデバイスではわずかな遅延がある場合があります

Web

• Webプラットフォームではサポートされていません
• リスナーは起動しません

トラブルシューティング

イベントが起動しない:

• アプリにフォーカスがあることを確認してください
• リスナーが適切に登録されていることを確認してください
• プラグインがインストールされ、同期されていることを確認してください

システムのボリューム変更が干渉する:

• これは予想される動作です - プラグインは押下を検出しますが、システムのボリューム変更を防ぐことはありません
• ボリューム変更と併用できるUXを検討してください

複数のイベントが起動する:

• 連続した押下を処理するためにデバウンスを実装してください
• リスナーの重複登録を確認してください