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

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

gallery_shortcode( array $attr ): string

Параметры:

• $attr (массив, обязательный) — атрибуты, которые используются для создания HTML-кода галереи.
  • order (строка) — порядок изображений в галерее. По умолчанию ‘ASC’. Принимает значения ‘ASC’ или ‘DESC’.
  • orderby (строка) — поле для сортировки изображений. По умолчанию ‘menu_order ID’. Принимает любое корректное SQL выражение ORDER BY.
  • id (int) — ID поста, к которому привязана галерея.
  • itemtag (строка) — HTML-тег для каждой картинки в галерее. По умолчанию ‘dl’, или ‘figure’ при поддержке HTML5.
  • icontag (строка) — HTML-тег для иконки изображения. По умолчанию ‘dt’, или ‘div’ при поддержке HTML5.
  • captiontag (строка) — HTML-тег для подписи изображения. По умолчанию ‘dd’, или ‘figcaption’ при поддержке HTML5.
  • columns (int) — количество колонок в галерее. По умолчанию 3.
  • size (строка | массив) — размер изображений в галерее. Принимает имя зарегистрированного размера или массив с шириной и высотой в пикселях. По умолчанию ‘thumbnail’.
  • ids (строка) — список ID изображений, разделенных запятыми. По умолчанию пусто.
  • include (строка) — список ID изображений, которые нужно включить в галерею. По умолчанию пусто.
  • exclude (строка) — список ID изображений, которые нужно исключить из галереи. По умолчанию пусто.
  • link (строка) — куда будет ссылаться каждое изображение. Принимает значения ‘file’, ‘none’. По умолчанию пусто (ссылка на страницу вложения).

Возвращаемое значение:

Функция возвращает строку с HTML-кодом для отображения галереи изображений.

Пример 1: Создание базовой галереи

Чтобы вывести простую галерею в посте или на странице, можно использовать следующий шорткод:

echo do_shortcode('');

Этот пример выведет изображения с указанными ID (101, 102, 103 и т.д.) в галерею.

Пример 2: Изменение количества колонок и размера изображений

Для вывода галереи с определённым количеством колонок и изменённым размером изображений:

echo do_shortcode('');

Этот код создаст галерею из четырех изображений в четыре колонки, а размер каждого изображения будет средним (medium).

Пример 3: Изменение порядка и сортировки изображений

Можно изменить порядок вывода изображений и способ их сортировки:

echo do_shortcode('');

Этот пример выведет изображения в обратном порядке (от новых к старым), сортируя их по дате добавления.

Пример 4: Отключение стандартных стилей галереи

WordPress по умолчанию добавляет стили для галереи. Чтобы отключить эти стили и добавить свои:

add_filter( 'use_default_gallery_style', '__return_false' );

После этого можно добавить свои CSS-стили в файл стилей вашей темы для настройки внешнего вида галереи.

Пример 5: Полное изменение вывода галереи с помощью фильтра post_gallery

Если вам нужно полностью изменить вывод галереи, вы можете использовать фильтр post_gallery и создать свою кастомную реализацию:

add_filter('post_gallery', 'my_custom_gallery_output', 10, 2);
function my_custom_gallery_output( $output, $attr ) {
    $ids = explode(',', $attr['ids']);
    $output = '<div class="my-custom-gallery">';

    foreach ($ids as $id) {
        $img_url = wp_get_attachment_url($id);
        $output .= '<div class="gallery-item"><img src="' . esc_url($img_url) . '" alt="" /></div>';
    }

    $output .= '</div>';
    return $output;
}

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

Пример 6: Удаление рамки вокруг изображений

Чтобы удалить рамку вокруг изображений в стандартной галерее, можно использовать фильтр gallery_style:

add_filter('gallery_style', function( $css ){
    return str_replace('border: 2px solid #cfcfcf;', '', $css);
});

Теперь рамки вокруг изображений галереи будут убраны.

Заключение

Функция gallery_shortcode() — это гибкий инструмент для создания галерей изображений в WordPress. Вы можете легко настраивать её с помощью множества параметров или использовать фильтры для полной кастомизации вывода. Это позволяет отображать изображения в различных форматах и стилях, удовлетворяя любые дизайнерские или функциональные требования вашего сайта.