Функция wp_audio_shortcode() в WordPress: Описание и Примеры

Функция wp_audio_shortcode() в WordPress используется для генерации HTML-кода аудио плеера, который отображает медиафайлы форматов, поддерживаемых браузерами. Она создает тег <audio> с нужными атрибутами для воспроизведения аудио в постах и страницах сайта.

wp_audio_shortcode( array $attr, string $content = '' ): string|void

• $attr (массив) — обязательный параметр, содержащий атрибуты аудио шорткода.
  • src (строка): URL аудио файла (например, mp3).
  • loop (строка): Атрибут для зацикливания аудио ('on' или пусто).
  • autoplay (строка): Атрибут для автозапуска аудио ('on' или пусто).
  • preload (строка): Определяет, как загружать аудио при загрузке страницы ('none', 'auto', 'metadata').
  • class (строка): Класс для тега <audio>. По умолчанию 'wp-audio-shortcode'.
  • style (строка): CSS стили для аудио. По умолчанию 'width: 100%;'.
• $content (строка) — Опциональный параметр. Контент шорткода.

Поддерживаемые аудио форматы

WordPress поддерживает следующие аудиоформаты: MP3, OGG, WAV, M4A, WMA. По умолчанию эта поддержка реализована через функцию wp_get_audio_extensions().

Пример 1: Вывод аудио плеера на странице

Этот пример показывает, как с помощью функции вывести плеер для MP3 файла.

$args = array(
  'src'      => 'https://mysite.com/audio-file.mp3',
  'loop'     => '',
  'autoplay' => '',
  'preload'  => 'metadata'
);

echo wp_audio_shortcode( $args );

Результат:

<audio class="wp-audio-shortcode" preload="metadata" style="width: 100%;" controls="controls">
  <source type="audio/mpeg" src="https://mysite.com/audio-file.mp3" />
  <a href="https://mysite.com/audio-file.mp3">https://mysite.com/audio-file.mp3</a>
</audio>

Этот код выводит стандартный аудио плеер с поддержкой HTML5 и заданными атрибутами.

Пример 2: Добавление аудио плеера в шаблон с параметром автозапуска

В этом примере мы добавляем плеер, который автоматически начнет воспроизведение при загрузке страницы.

$audio_attributes = array(
  'src'      => 'https://example.org/music-file.mp3',
  'autoplay' => 'on',
  'preload'  => 'auto'
);

echo wp_audio_shortcode( $audio_attributes );

Результат:

<audio class="wp-audio-shortcode" preload="auto" style="width: 100%;" controls="controls" autoplay="autoplay">
  <source type="audio/mpeg" src="https://example.org/music-file.mp3" />
  <a href="https://example.org/music-file.mp3">https://example.org/music-file.mp3</a>
</audio>

Этот плеер начинает воспроизведение автоматически, как только страница загружается.

Пример 3: Использование атрибута loop для зацикливания воспроизведения

Этот пример демонстрирует, как добавить в плеер возможность зацикливания аудио.

$looping_audio = array(
  'src'   => 'https://domain.com/track.mp3',
  'loop'  => 'on',
  'preload' => 'auto'
);

echo wp_audio_shortcode( $looping_audio );

Результат:

<audio class="wp-audio-shortcode" preload="auto" style="width: 100%;" controls="controls" loop="loop">
  <source type="audio/mpeg" src="https://domain.com/track.mp3" />
  <a href="https://domain.com/track.mp3">https://domain.com/track.mp3</a>
</audio>

Этот плеер будет повторно воспроизводить аудио после завершения.

Пример 4: Добавление нескольких форматов аудио для совместимости с разными браузерами

Чтобы обеспечить поддержку разных браузеров, можно указать несколько форматов аудио.

echo do_shortcode('
');

Результат:

<audio class="wp-audio-shortcode" preload="none" style="width: 100%;" controls="controls">
  <source type="audio/mpeg" src="https://site.com/audio.mp3" />
  <source type="audio/ogg" src="https://site.com/audio.ogg" />
  <source type="audio/wav" src="https://site.com/audio.wav" />
  <a href="https://site.com/audio.mp3">https://site.com/audio.mp3</a>
</audio>

Этот плеер включает резервные источники для разных аудио форматов, что повышает совместимость с браузерами.

Пример 5: Переопределение шорткода с помощью фильтра wp_audio_shortcode_override

Фильтр wp_audio_shortcode_override позволяет переопределить поведение аудио шорткода. Это полезно, если нужно полностью изменить вывод плеера.

add_filter( 'wp_audio_shortcode_override', 'custom_audio_shortcode', 10, 4 );
function custom_audio_shortcode( $empty, $attr, $content, $instance ) {
  // Переопределяем вывод плеера при включенном autoplay
  if ( isset( $attr['autoplay'] ) && $attr['autoplay'] == 'on' ) {
    return '<div class="custom-audio-player">Ваш кастомный аудио плеер здесь</div>';
  }
  return '';
}

Этот код переопределяет вывод плеера, если включен параметр автозапуска.

Заключение

Функция wp_audio_shortcode() в WordPress позволяет легко добавлять аудио плееры на сайт, поддерживая различные настройки и аудио форматы. Она поддерживает множество настроек, таких как зацикливание, автозапуск, предзагрузка и кастомизация через CSS классы и стили, а также может быть переопределена с помощью фильтров, что делает ее гибким инструментом для интеграции аудио на сайт.