媒体控制器

为了开发适用于各种浏览器和设备的应用，通常会遇到各种独特的挑战。其中最显著的挑战之一是确保在苹果的 iOS 设备上实现一致的媒体播放。

解释 iOS 媒体播放限制

苹果的 iOS 为音频和视频播放制定了特定的规则，以提升用户体验和管理数据消耗：

用户体验：iOS 禁止媒体自动播放，以防止意外干扰。这个设计选择确保用户在安静的环境中不会被突然的音频打扰。
数据效率：考虑到流媒体可能消耗大量数据，iOS 要求用户手动启动媒体播放。这个设计对于使用有限或按流量计费的数据计划的用户尤其有益。

解决 iOS 播放挑战

iOS 挑战的核心是系统坚持用户发起的媒体播放。例如，开始播放视频必须直接由用户操作，比如点击。然而，异步事件处理程序，比如 onClick$ (QRL)，可能导致用户的操作和播放命令之间存在不一致。这通常会导致 iOS 在第一次点击时阻止播放，需要进行第二次非直观的点击。

`playsinline` 属性

在 iOS 设备上，特别是 iPhone 上，视频会自动以全屏模式播放，除非 <video> 标签上存在 playsinline 属性。该属性确保视频在其指定的容器内播放，提供了在不同设备和平台上一致的体验。虽然主要用于 iOS，但在其他平台上包含 playsinline 是无害的，并确保更广泛的兼容性。

创建一个通用的播放解决方案

为了在各种浏览器和设备上实现一致的媒体播放，需要采用一种全面的方法。本指南提供了一个解决方案，可以解决不同平台的细微差别。为了在用户交互时立即播放，应该同步调用 .play() 方法。可以通过直接在 useVisibleTask$ 函数中附加 click 处理程序来实现这一点。

下面是一个针对 iOS 设备兼容的音频和视频控制器的原型。

https://qwik.builder.io/demo/cookbook/mediaController/

与 iOS 设备兼容的通用媒体控制器代码如下：

import {
  component$,
  useSignal,
  useStylesScoped$,
  useVisibleTask$,
} from '@builder.io/qwik';
import { useLocation } from '@builder.io/qwik-city';
 
const AUDIO_SRC =
  'https://cdn.builder.io/o/assets%2F5b8073f890b043be81574f96cfd1250b%2Fafe011812da146a5b2263196cb25f263?alt=media&token=c017cd87-0598-4af2-8afd-e9b5a3fba078&apiKey=5b8073f890b043be81574f96cfd1250b';
const VIDEO_SRC =
  'https://cdn.builder.io/o/assets%2F5b8073f890b043be81574f96cfd1250b%2F8b210c56974440649a0a78d4a3a0ddc5%2Fcompressed?apiKey=5b8073f890b043be81574f96cfd1250b&token=8b210c56974440649a0a78d4a3a0ddc5&alt=media&optimized=true';
 
export default component$(() => {
  const audioElementSignal = useSignal<HTMLAudioElement | undefined>();
  const audioPlayButtonSignal = useSignal<HTMLButtonElement | undefined>();
  const audioIsPlayingSignal = useSignal(false);
  const videoElementSignal = useSignal<HTMLAudioElement | undefined>();
  const videoPlayButtonSignal = useSignal<HTMLButtonElement | undefined>();
  const videoIsPlayingSignal = useSignal(false);
  const playsInlineSignal = useSignal(true);
  const location = useLocation();
 
  const videoPoster =
    location.url.origin + '/sample-media/qwik-koi-poster.jpg';
 
  useStylesScoped$(`
        segment {
          display: flex;
          flex-direction: column;
          align-items: center;
          text-align: center;
          width: 100%;
          padding: 20px;
          color: #1dacf2
        }
        .content {
          width: 60%;
          min-width: 250px;
        }   
        button {
          padding: 20px;
          font-weight: bold;
          font-size: 1.2em;
          width: 100%;
          background: #1dacf2;
          color: white;
        }
        .checkbox-container {
          display: flex;
          align-items: center;
          justify-content: center;
        }
        .checkbox {
          width: 20px;
          height: 20px;
          margin-right: 8px;
        }
        .video-container {
          position: relative;
          width: 100%;
          height: 0;
          padding-bottom: calc(56.25% + 1px);
        }
        video {
          position: absolute;
          top: 0;
          left: 0;
          width: 100%;
          height: 100%;
          box-sizing: border-box;
          border: 1px solid gray;
        }
        `);
 
  useVisibleTask$(({ track }) => {
    track(() => audioPlayButtonSignal.value);
    track(() => audioElementSignal.value);
 
    const play = () =>
      audioIsPlayingSignal.value
        ? audioElementSignal.value?.pause()
        : audioElementSignal.value?.play();
 
    audioPlayButtonSignal.value?.removeEventListener('click', play);
    audioPlayButtonSignal.value?.addEventListener('click', play);
 
    return () =>
      audioPlayButtonSignal.value?.removeEventListener('click', play);
  });
 
  useVisibleTask$(({ track }) => {
    track(() => videoPlayButtonSignal.value);
    track(() => videoElementSignal.value);
 
    const play = () =>
      videoIsPlayingSignal.value
        ? videoElementSignal.value?.pause()
        : videoElementSignal.value?.play();
 
    videoPlayButtonSignal.value?.addEventListener('click', play);
    return () =>
      videoPlayButtonSignal.value?.removeEventListener('click', play);
  });
 
  return (
    <segment>
      <div class="content">
        <h1>媒体控制器</h1>
        <h3>
          <i>带有 iOS 支持</i>
        </h3>
        <br />
        <div class="video-container">
          <video
            ref={videoElementSignal}
            src={VIDEO_SRC}
            poster={videoPoster}
            playsInline={playsInlineSignal.value}
            onPlay$={() => (videoIsPlayingSignal.value = true)}
            onPause$={() => (videoIsPlayingSignal.value = false)}
            onEnded$={() => (videoIsPlayingSignal.value = false)}
          />
        </div>
        <audio
          ref={audioElementSignal}
          src={AUDIO_SRC}
          onPlay$={() => (audioIsPlayingSignal.value = true)}
          onPause$={() => (audioIsPlayingSignal.value = false)}
          onEnded$={() => (audioIsPlayingSignal.value = false)}
        />
        <br />
        <div class="checkbox-container">
          <input
            type="checkbox"
            id="playsInlineCheckbox"
            class="checkbox"
            checked={playsInlineSignal.value}
            onChange$={() => {
              videoElementSignal.value?.pause();
              playsInlineSignal.value = !playsInlineSignal.value;
            }}
          />
          <label for="playsInlineCheckbox">playsInline (iOS)</label>
        </div>
 
        <br />
        <button ref={videoPlayButtonSignal}>
          {videoIsPlayingSignal.value ? '暂停' : '播放'} 视频
        </button>
        <br />
        <br />
        <button ref={audioPlayButtonSignal}>
          {audioIsPlayingSignal.value ? '暂停' : '播放'} 音频
        </button>
      </div>
    </segment>
  );
});

Contributors

Thanks to all the contributors who have helped make this documentation better!