get_image_tag()
云策文档标注
概述
get_image_tag() 函数用于生成图像附件的 HTML img 标签，支持按需缩放图像。它通过参数控制图像属性，并提供了两个过滤器以允许插件自定义类名和 HTML 内容。
关键要点
- 函数接受附件 ID、alt 文本、title 文本、对齐方式和图像大小作为参数，返回完整的 img 元素。
- 使用 image_downsize() 和 image_hwstring() 辅助函数处理图像尺寸和属性。
- 提供 'get_image_tag_class' 过滤器，允许修改图像的 CSS 类名，无需直接操作 HTML。
- 提供 'get_image_tag' 过滤器，允许插件全面修改 img 标签的属性和 HTML 内容。
- 默认图像大小为 'medium'，但支持任何已注册的图像尺寸名称或自定义宽高数组。
代码示例
function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
list( $img_src, $width, $height ) = image_downsize( $id, $size );
$hwstring = image_hwstring( $width, $height );
$title = $title ? 'title="' . esc_attr( $title ) . '" ' : '';
$size_class = is_array( $size ) ? implode( 'x', $size ) : $size;
$class = 'align' . esc_attr( $align ) . ' size-' . esc_attr( $size_class ) . ' wp-image-' . $id;
$class = apply_filters( 'get_image_tag_class', $class, $id, $align, $size );
$html = '';
return apply_filters( 'get_image_tag', $html, $id, $alt, $title, $align, $size );
}注意事项
- 函数内部使用 esc_attr() 对属性进行转义，确保 HTML 安全。
- 图像对齐方式通过 'align' 参数集成到类名中，例如 'alignleft'。
- 相关函数包括 image_downsize()、image_hwstring() 和 apply_filters()，用于尺寸处理、属性生成和过滤器应用。
原文内容
Gets an img tag for an image attachment, scaling it down if requested.
Description
The ‘get_image_tag_class’ filter allows for changing the class name for the image without having to use regular expressions on the HTML content. The parameters are: what WordPress will use for the class, the Attachment ID, image align value, and the size the image should be.
The second filter, ‘get_image_tag’, has the HTML content, which can then be further manipulated by a plugin to change all attribute values and even HTML content.
Parameters
$idintrequired-
Attachment ID.
$altstringrequired-
Image description for the alt attribute.
$titlestringrequired-
Image description for the title attribute.
$alignstringrequired-
Part of the class name for aligning the image.
$sizestring|int[]optional-
Image size. Accepts any registered image size name, or an array of width and height values in pixels (in that order). Default
'medium'.
Source
function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
list( $img_src, $width, $height ) = image_downsize( $id, $size );
$hwstring = image_hwstring( $width, $height );
$title = $title ? 'title="' . esc_attr( $title ) . '" ' : '';
$size_class = is_array( $size ) ? implode( 'x', $size ) : $size;
$class = 'align' . esc_attr( $align ) . ' size-' . esc_attr( $size_class ) . ' wp-image-' . $id;
/**
* Filters the value of the attachment's image tag class attribute.
*
* @since 2.6.0
*
* @param string $class CSS class name or space-separated list of classes.
* @param int $id Attachment ID.
* @param string $align Part of the class name for aligning the image.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
$class = apply_filters( 'get_image_tag_class', $class, $id, $align, $size );
$html = '<img src="' . esc_url( $img_src ) . '" alt="' . esc_attr( $alt ) . '" ' . $title . $hwstring . 'class="' . $class . '" />';
/**
* Filters the HTML content for the image tag.
*
* @since 2.6.0
*
* @param string $html HTML content for the image.
* @param int $id Attachment ID.
* @param string $alt Image description for the alt attribute.
* @param string $title Image description for the title attribute.
* @param string $align Part of the class name for aligning the image.
* @param string|int[] $size Requested image size. Can be any registered image size name, or
* an array of width and height values in pixels (in that order).
*/
return apply_filters( 'get_image_tag', $html, $id, $alt, $title, $align, $size );
}
Hooks
- apply_filters( ‘get_image_tag’, string $html, int $id, string $alt, string $title, string $align, string|int[] $size )
-
Filters the HTML content for the image tag.
- apply_filters( ‘get_image_tag_class’, string $class, int $id, string $align, string|int[] $size )
-
Filters the value of the attachment’s image tag class attribute.
Changelog
| Version | Description |
|---|---|
| 2.5.0 | Introduced. |