媒体控制器

为各种浏览器和设备开发通常会带来独特的挑战。其中最显著的挑战之一是确保一致的媒体播放，尤其是在苹果的 iOS 设备上。

iOS 媒体播放限制说明

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

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

解读 iOS 播放挑战

iOS 挑战的核心在于系统坚持用户启动媒体播放。例如，启动视频必须直接来自用户操作，例如点击。但是，异步事件处理程序（例如 onClick$ (QRL)）会在用户操作和播放命令之间造成脱节。这通常会导致 iOS 在第一次点击时阻止播放，需要第二次非直观的点击。

`playsinline` 属性

在 iOS 设备上，尤其是 iPhone，视频会自动以全屏模式播放，除非 <video> 标签上存在 playsinline 属性。此属性确保视频在其指定容器内播放，从而在不同设备和平台上提供一致的体验。虽然主要针对 iOS，但在其他平台上包含 playsinline 不会造成任何危害，并确保更广泛的兼容性。

打造通用播放解决方案

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

下面，您将找到一个音频和视频控制器的原型，旨在为多个平台提供一致的用户体验。

https://qwik.node.org.cn/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>Media Controller</h1>
        <h3>
          <i>with iOS Support</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 ? 'Pause' : 'Play'} Video
        </button>
        <br />
        <br />
        <button ref={audioPlayButtonSignal}>
          {audioIsPlayingSignal.value ? 'Pause' : 'Play'} Audio
        </button>
      </div>
    </segment>
  );
});

贡献者

感谢所有帮助改进本文档的贡献者！

媒体控制器

iOS 媒体播放限制说明

解读 iOS 播放挑战

playsinline 属性

打造通用播放解决方案

贡献者

`playsinline` 属性