get_post_galleries()
云策文档标注
概述
get_post_galleries() 函数用于从指定文章内容中提取所有图库数据,支持短代码和块编辑器格式。它根据参数返回 HTML 或数组形式的数据,并包含一个过滤器钩子用于自定义输出。
关键要点
- 参数:$post(必需,文章 ID 或 WP_Post 对象)和 $html(可选,布尔值,默认 true 返回 HTML,false 返回数组数据)。
- 返回值:一个数组列表,每个元素包含从短代码或块解析出的图库数据,如 src 属性。
- 支持短代码和块编辑器:函数同时处理 [gallery] 短代码和 core/gallery 块,包括新旧格式。
- 过滤器钩子:apply_filters('get_post_galleries', $galleries, $post) 允许开发者修改返回的图库列表。
- 相关函数:涉及 has_shortcode、parse_blocks、wp_get_attachment_url 等,用于内容解析和数据处理。
代码示例
// 示例:获取文章 ID 为 123 的图库数据,返回数组格式
$galleries = get_post_galleries( 123, false );
if ( ! empty( $galleries ) ) {
foreach ( $galleries as $gallery ) {
print_r( $gallery['src'] ); // 输出图库图片 URL 数组
}
}注意事项
- 函数在 WordPress 3.6.0 引入,最初仅支持短代码,从 WordPress 5.9 开始支持块编辑器图库。
- 如果文章内容中没有图库短代码或块,函数返回空数组。
- 使用 $html = false 时,返回的数组包含短代码属性和去重后的 src 列表,便于程序化处理。
原文内容
Retrieves galleries from the passed post’s content.
Parameters
$postint|WP_Postrequired-
Post ID or object.
$htmlbooloptional-
Whether to return HTML or data in the array.
Default:
true
Source
function get_post_galleries( $post, $html = true ) {
$post = get_post( $post );
if ( ! $post ) {
return array();
}
if ( ! has_shortcode( $post->post_content, 'gallery' ) && ! has_block( 'gallery', $post->post_content ) ) {
return array();
}
$galleries = array();
if ( preg_match_all( '/' . get_shortcode_regex() . '/s', $post->post_content, $matches, PREG_SET_ORDER ) ) {
foreach ( $matches as $shortcode ) {
if ( 'gallery' === $shortcode[2] ) {
$srcs = array();
$shortcode_attrs = shortcode_parse_atts( $shortcode[3] );
// Specify the post ID of the gallery we're viewing if the shortcode doesn't reference another post already.
if ( ! isset( $shortcode_attrs['id'] ) ) {
$shortcode[3] .= ' id="' . (int) $post->ID . '"';
}
$gallery = do_shortcode_tag( $shortcode );
if ( $html ) {
$galleries[] = $gallery;
} else {
preg_match_all( '#src=(['"])(.+?)1#is', $gallery, $src, PREG_SET_ORDER );
if ( ! empty( $src ) ) {
foreach ( $src as $s ) {
$srcs[] = $s[2];
}
}
$galleries[] = array_merge(
$shortcode_attrs,
array(
'src' => array_values( array_unique( $srcs ) ),
)
);
}
}
}
}
if ( has_block( 'gallery', $post->post_content ) ) {
$post_blocks = parse_blocks( $post->post_content );
while ( $block = array_shift( $post_blocks ) ) {
$has_inner_blocks = ! empty( $block['innerBlocks'] );
// Skip blocks with no blockName and no innerHTML.
if ( ! $block['blockName'] ) {
continue;
}
// Skip non-Gallery blocks.
if ( 'core/gallery' !== $block['blockName'] ) {
// Move inner blocks into the root array before skipping.
if ( $has_inner_blocks ) {
array_push( $post_blocks, ...$block['innerBlocks'] );
}
continue;
}
// New Gallery block format as HTML.
if ( $has_inner_blocks && $html ) {
$block_html = wp_list_pluck( $block['innerBlocks'], 'innerHTML' );
$galleries[] = '<figure>' . implode( ' ', $block_html ) . '</figure>';
continue;
}
$srcs = array();
// New Gallery block format as an array.
if ( $has_inner_blocks ) {
$attrs = wp_list_pluck( $block['innerBlocks'], 'attrs' );
$ids = wp_list_pluck( $attrs, 'id' );
foreach ( $ids as $id ) {
$url = wp_get_attachment_url( $id );
if ( is_string( $url ) && ! in_array( $url, $srcs, true ) ) {
$srcs[] = $url;
}
}
$galleries[] = array(
'ids' => implode( ',', $ids ),
'src' => $srcs,
);
continue;
}
// Old Gallery block format as HTML.
if ( $html ) {
$galleries[] = $block['innerHTML'];
continue;
}
// Old Gallery block format as an array.
$ids = ! empty( $block['attrs']['ids'] ) ? $block['attrs']['ids'] : array();
// If present, use the image IDs from the JSON blob as canonical.
if ( ! empty( $ids ) ) {
foreach ( $ids as $id ) {
$url = wp_get_attachment_url( $id );
if ( is_string( $url ) && ! in_array( $url, $srcs, true ) ) {
$srcs[] = $url;
}
}
$galleries[] = array(
'ids' => implode( ',', $ids ),
'src' => $srcs,
);
continue;
}
// Otherwise, extract srcs from the innerHTML.
preg_match_all( '#src=(['"])(.+?)1#is', $block['innerHTML'], $found_srcs, PREG_SET_ORDER );
if ( ! empty( $found_srcs[0] ) ) {
foreach ( $found_srcs as $src ) {
if ( isset( $src[2] ) && ! in_array( $src[2], $srcs, true ) ) {
$srcs[] = $src[2];
}
}
}
$galleries[] = array( 'src' => $srcs );
}
}
/**
* Filters the list of all found galleries in the given post.
*
* @since 3.6.0
*
* @param array $galleries Associative array of all found post galleries.
* @param WP_Post $post Post object.
*/
return apply_filters( 'get_post_galleries', $galleries, $post );
}
Hooks
- apply_filters( ‘get_post_galleries’, array $galleries, WP_Post $post )
-
Filters the list of all found galleries in the given post.
Changelog
| Version | Description |
|---|---|
| 3.6.0 | Introduced. |
Skip to note 3 content
bcworkz
This function does not support block editor galleries. It only works for the older gallery shortcode. The block gallery’s content is contained within the block itself.
Skip to note 4 content
jakeparis
As of WordPress 5.9, this function does support block editor galleries.