# image_add_caption()

URL: https://chugunov.pro/api-wordpress/functions/image_add_caption/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 2.6.0.

## Сигнатура

```php
image_add_caption( string $html, int $id, string $caption, string $title, string $align, string $url, string $size, string $alt = '' ): string
```

## Описание

Добавляет в редактор шорткод изображения с подписью.

## Параметры

- `$html` `string` — обязательный. HTML-разметка изображения для отправки.
- `$id` `int` — обязательный. Идентификатор вложения-изображения.
- `$caption` `string` — обязательный. Подпись изображения.
- `$title` `string` — обязательный. Атрибут title изображения (не используется).
- `$align` `string` — обязательный. Свойство CSS-выравнивания изображения.
- `$url` `string` — обязательный. URL источника изображения (не используется).
- `$size` `string` — обязательный. Размер изображения (не используется).
- `$alt` `string` — необязательный, по умолчанию `''`. Атрибут alt изображения (не используется).

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

`string`

## Исходный код

Файл: `wp-admin/includes/media.php:188`

```php
function image_add_caption( $html, $id, $caption, $title, $align, $url, $size, $alt = '' ) {

	/**
	 * Filters the caption text.
	 *
	 * Note: If the caption text is empty, the caption shortcode will not be appended
	 * to the image HTML when inserted into the editor.
	 *
	 * Passing an empty value also prevents the 'image_add_caption_shortcode'
	 * Filters from being evaluated at the end of image_add_caption().
	 *
	 * @since 4.1.0
	 *
	 * @param string $caption The original caption text.
	 * @param int    $id      The attachment ID.
	 */
	$caption = apply_filters( 'image_add_caption_text', $caption, $id );

	/**
	 * Filters whether to disable captions.
	 *
	 * Prevents image captions from being appended to image HTML when inserted into the editor.
	 *
	 * @since 2.6.0
	 *
	 * @param bool $bool Whether to disable appending captions. Returning true from the filter
	 *                   will disable captions. Default empty string.
	 */
	if ( empty( $caption ) || apply_filters( 'disable_captions', '' ) ) {
		return $html;
	}

	$id = ( 0 < (int) $id ) ? 'attachment_' . $id : '';

	if ( ! preg_match( '/width=["\']([0-9]+)/', $html, $matches ) ) {
		return $html;
	}

	$width = $matches[1];

	$caption = str_replace( array( "\r\n", "\r" ), "\n", $caption );
	$caption = preg_replace_callback( '/<[a-zA-Z0-9]+(?: [^<>]+>)*/', '_cleanup_image_add_caption', $caption );

	// Convert any remaining line breaks to <br />.
	$caption = preg_replace( '/[ \n\t]*\n[ \t]*/', '<br />', $caption );

	$html = preg_replace( '/(class=["\'][^\'"]*)align(none|left|right|center)\s?/', '$1', $html );
	if ( empty( $align ) ) {
		$align = 'none';
	}

	$shcode = '' . $html . ' ' . $caption . '';

	/**
	 * Filters the image HTML markup including the caption shortcode.
	 *
	 * @since 2.6.0
	 *
	 * @param string $shcode The image HTML markup with caption shortcode.
	 * @param string $html   The image HTML markup.
	 */
	return apply_filters( 'image_add_caption_shortcode', $shcode, $html );
}
```

## История изменений

- 2.6.0 — Introduced.

## Связанные

Использует: [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/).

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/image_add_caption/