入门

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’, 回调)

监听音量按钮按下事件。

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

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

事件数据：

• direction: '向上' | 'down' - 按下按钮的方向

删除所有监听器()

删除所有已注册的侦听器。

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)+
• 要求应用程序位于前台
• 某些设备可能会有轻微延迟

网络

• 不支持网络平台
• 听众不会开火

故障排除

事件未触发：

• 确保应用程序具有焦点
• 检查监听器是否正确注册
• 验证插件是否已安装并同步

系统音量变化干扰：

• 这是预期的行为 - 插件检测按下但不会阻止系统音量变化
• 考虑与音量变化一起工作的用户体验

多个事件触发：

• 实施去抖处理快速按压
• 检查重复的监听器注册