Функция add_image_size() в WordPress: регистрация нового размера изображения

## Функция add_image_size() │ WP 2.9.0

Функция add_image_size() позволяет зарегистрировать новый размер изображения (миниатюры).

### Что делает функция?

Когда вы загружаете изображение, WordPress создает не только стандартные размеры изображений, но и размер, который вы указали — с заданной шириной и высотой.

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

- Для плагина лучше использовать хуки plugin_loaded с приоритетом 0.
- Для темы лучше вызывать ее прямо в файле functions.php.

Чтобы устанавливать миниатюры постов на странице редактирования в админке, необходимо активировать эту функцию с помощью add_theme_support( 'post-thumbnails' ). Вызовите эту функцию в файле functions.php.

Если вам нужно создавать миниатюры на лету с любым размером, вместо этой функции используйте плагин **Kama Thumbnail**.

Используйте remove_image_size() для удаления ранее созданного размера.

### Зарезервированные имена размеров

- thumb, thumbnail, medium, large, post-thumbnail.

Имена "thumb" и "thumbnail" — это синонимы и относятся к одним и тем же изображениям.

### Настройка параметров для созданной миниатюры

Вы такж�� можете настроить параметры для созданной миниатюры так:

```php
update_option( 'thumbnail_size_w', 160 );
update_option( 'thumbnail_size_h', 160 );
update_option( 'thumbnail_crop', 1 );

При создании своей темы для каталога тем WordPress, имя нового размера должно содержать название вашей темы. Например:

add_image_size( 'mytheme-mini', 200, 200, true );

Использование функции

add_image_size( $name, $width, $height, $crop );

• $name (строка) (обязательно) — имя размера изображения (идентификатор).
• $width (целое число) (обязательно) — ширина изображения в пикселях. По умолчанию: 0.
• $height (целое число) (обязательно) — высота изображения в пикселях. По умолчанию: 0.
• $crop (логическое/массив) — определяет, как создать миниатюру: обрезать ли изображение до указанных ширины и высоты или изменять его размер.

Параметр $crop

• false (по умолчанию) — масштабирование: изображение будет масштабироваться, но не обрезаться. Миниатюра создается по одной из сторон: указанной ширине или высоте. Конечное изображение не всегда будет точно соответствовать заданным размерам.

• true — обрезка: изображение будет обрезано до указанных размеров по центру.

• array(x_position, y_position) — определяет позицию обрезки. Например, если указать массив [ 'right', 'top' ], изображение будет обрезано с верхнего правого угла.

  • x_position может быть: left, center, right.
  • y_position может быть: top, center, bottom.

Важно! Параметр "crop" работает только для новых изображений. Если у вас уже есть изображения в библиотеке, новые размеры не будут применены к ним.

Примеры использования

Пример 1: Масштабирование (CROP = FALSE)

add_image_size( 'homepage-thumb', 220, 180 );

При загрузке нового файла, миниатюра будет подстраиваться по ширине или высоте в зависимости от ее соотношения. Например, если у вас оригинальное изображение 2500x1800 пикселей, оно будет уменьшено до 250x180 пикселей, сохраняя пропорции.

Пример 2: Обрезка (CROP = TRUE)

add_image_size( 'homepage-thumb', 220, 180, true );

В этом случае миниатюра будет обрезана до точно указанных размеров. Оригинальное изображение будет уменьшено до высоты 180px, а ширина будет обрезана на 15px по краям, в итоге получим 220x180 пикселей.

Пример 3: Обрезка с позициями (CROP = [X, Y])

add_image_size( 'custom-size', 220, 220, [ 'left', 'top' ] );

Здесь мы задаем миниатюру размером 220x220 пикселей с обрезкой от верхнего левого угла.

Пример 4: Как исп��льзовать новые размеры в коде?

Чтобы использовать новые размеры при выводе изображений, которые установлены как "миниатюры" постов, используйте функцию the_post_thumbnail():

if ( has_post_thumbnail() ) {
    the_post_thumbnail( 'category-thumb' ); // 'category-thumb' - имя размера
}

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

add_filter( 'image_size_names_choose', 'my_custom_sizes' );
function my_custom_sizes( $sizes ) {
    return array_merge( $sizes, array(
        'category-thumb' => 'Мой размер',
    ));
}

Примечания

• Глобальный массив $_wp_additional_image_sizes содержит ассоциативный массив дополнительных размеров изображений.

Изменения

С версии 2.9.0 — функция была добавлена.

Код функции add_image_size()

function add_image_size( $name, $width = 0, $height = 0, $crop = false ) {
    global $_wp_additional_image_sizes;

    $_wp_additional_image_sizes[ $name ] = array(
        'width'  => absint( $width ),
        'height' => absint( $height ),
        'crop'   => $crop,
    );
}

Связанные функции

• delete_post_thumbnail()
• get_intermediate_image_sizes()
• get_post_thumbnail_id()
• get_the_post_thumbnail()
• has_image_size()
• remove_image_size()
• set_post_thumbnail()
• the_post_thumbnail()