云策 WordPress 开发者社区

函数文档

image_add_caption()

查看官方原文 ↗
💡 云策文档标注

概述

image_add_caption() 函数用于向图像 HTML 标记添加带标题的短代码，以便在编辑器中插入。它处理标题文本、对齐方式，并应用相关过滤器来控制标题的生成和输出。

关键要点

  • 函数接受多个参数，包括图像 HTML、附件 ID、标题、对齐方式等，其中部分参数（如 title、url、size、alt）在函数内部未使用。
  • 通过 'image_add_caption_text' 过滤器可以修改标题文本；如果标题为空或 'disable_captions' 过滤器返回 true，则直接返回原始 HTML，不添加标题短代码。
  • 函数清理标题中的 HTML 标签和换行符，调整图像对齐类，并生成包含 [caption] 短代码的最终 HTML 标记，最后通过 'image_add_caption_shortcode' 过滤器输出。
  • 相关 Hook 包括 'disable_captions'、'image_add_caption_shortcode' 和 'image_add_caption_text'，用于自定义标题行为。

代码示例

function image_add_caption( $html, $id, $caption, $title, $align, $url, $size, $alt = '' ) {
    $caption = apply_filters( 'image_add_caption_text', $caption, $id );
    if ( empty( $caption ) || apply_filters( 'disable_captions', '' ) ) {
        return $html;
    }
    $caption = preg_replace( '/[ nt]*n[ t]*/', '', $caption );
    $html = preg_replace( '/(class=["'][^'"]*)align(none|left|right|center)s?/', '$1', $html );
    if ( empty( $align ) ) {
        $align = 'none';
    }
    $shcode = '' . $html . ' ' . $caption . '';
    return apply_filters( 'image_add_caption_shortcode', $shcode, $html );
}

注意事项

  • 标题文本为空时，不会添加标题短代码，且相关过滤器不会被评估。
  • 函数内部清理标题中的 HTML 标签和换行符，确保短代码格式正确。
  • 对齐参数 align 默认为 'none'，如果未提供则自动设置。
  • 部分参数（如 title、url、size、alt）在函数中未使用，但作为参数保留以保持兼容性。
📄 原文内容

Adds image shortcode with caption to editor.

Parameters

$htmlstringrequired
The image HTML markup to send.
$idintrequired
Image attachment ID.
$captionstringrequired
Image caption.
$titlestringrequired
Image title attribute (not used).
$alignstringrequired
Image CSS alignment property.
$urlstringrequired
Image source URL (not used).
$sizestringrequired
Image size (not used).
$altstringrequired
Image alt attribute (not used).

Return

string The image HTML markup with caption shortcode.

Source

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( "rn", "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( '/[ nt]*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 );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘disable_captions’, bool $bool )

Filters whether to disable captions.

apply_filters( ‘image_add_caption_shortcode’, string $shcode, string $html )

Filters the image HTML markup including the caption shortcode.

apply_filters( ‘image_add_caption_text’, string $caption, int $id )

Filters the caption text.

Uses Description
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Changelog

Version Description
2.6.0 Introduced.