Vidstack Player 自定义快捷键的实现与注意事项

自定义快捷键的双重触发问题分析

在使用Vidstack Player进行媒体播放器开发时，许多开发者会遇到自定义快捷键的双重触发问题。具体表现为：当为播放器定义自定义快捷键时，绑定的回调函数会被执行两次，导致状态切换等操作无法按预期工作。

这个问题的根源在于旧版API中callback属性的设计缺陷。在Vidstack Player的早期版本中，callback函数会在按键按下(KeyDown)和按键释放(KeyUp)两个事件时都被触发。这种设计虽然在某些场景下可能有其用途，但对于大多数快捷键操作来说，这显然不是开发者期望的行为。

快捷键优先级与覆盖机制

另一个常见问题是自定义快捷键无法覆盖默认快捷键。Vidstack Player提供了一套默认的媒体快捷键(MEDIA_KEY_SHORTCUTS)，当开发者尝试添加自己的快捷键时，发现默认快捷键仍然有效。

这实际上是一个优先级处理的问题。Vidstack Player的快捷键匹配机制是按照定义的顺序进行匹配的，第一个匹配的快捷键会被触发，后续定义的相同快捷键将被忽略。因此，开发者需要特别注意自定义快捷键和默认快捷键的声明顺序。

最佳实践方案

1. 使用新版API：最新版本的Vidstack Player已经弃用了单一的callback属性，改为提供onKeyUp和onKeyDown两个独立的回调函数。这种设计更加清晰，开发者可以根据需要选择在按键按下或释放时触发操作。

2. 正确的快捷键声明顺序：当需要覆盖默认快捷键时，应该将自定义快捷键定义放在默认快捷键(MEDIA_KEY_SHORTCUTS)之前。这样自定义快捷键会优先匹配，达到覆盖默认行为的效果。

3. 状态管理优化：对于需要切换状态的操作，建议在回调函数中添加额外的逻辑判断，确保即使函数被意外多次调用，也不会导致状态错误。

实际应用示例

<MediaPlayer
  ref={playerRef}
  src={src}
  keyShortcuts={{
    // 自定义快捷键放在前面
    ambient: {
      keys: ['a'],
      onKeyDown(event) {
        setAmbient(prev => !prev);
      }
    },
    bigseek: {
      keys: ['Shift+ArrowLeft', 'Shift+ArrowRight'],
      onKeyDown(event) {
        const direction = event.key === 'ArrowLeft' ? -1 : 1;
        playerRef.current.currentTime += direction * 90;
      }
    },
    // 默认快捷键放在后面
    ...MEDIA_KEY_SHORTCUTS
  }}
>

通过以上改进，开发者可以更精准地控制快捷键行为，避免意外触发，同时确保自定义快捷键能够正确覆盖默认设置。