云策 WordPress 开发者社区

函数文档

get_attached_media()

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

概述

get_attached_media() 函数用于检索附加到指定文章的媒体附件。它基于 MIME 类型和文章参数，通过 WP_Query 参数调用 get_children() 来获取结果。

关键要点

  • 参数：$type（必需，MIME 类型字符串），$post（可选，文章 ID 或 WP_Post 对象，默认为全局 $post）。
  • 返回值：返回 WP_Post[] 数组，包含附加到指定文章的媒体附件对象。
  • 内部实现：使用 get_children() 查询，默认按 menu_order 升序排序，posts_per_page 为 -1 以获取所有结果。
  • 过滤器：提供 get_attached_media_args 和 get_attached_media 两个过滤器，允许开发者自定义查询参数和结果。
  • 注意事项：函数仅返回首次上传或添加到文章的附件；若媒体先附加到其他文章，则可能返回空数组。

代码示例

// 获取当前文章的所有图像附件
$media = get_attached_media( 'image' );

// 获取文章 ID 102 的所有音频附件
$media = get_attached_media( 'audio', 102 );

// 获取所有类型的附件（传递空字符串）
$media = get_attached_media( '' );

注意事项

  • 返回的数组以附件 ID 为键，默认按 menu_order 排序，这常用于插件处理附件顺序。
  • 若媒体先附加到其他文章，再添加到目标文章，函数可能返回空数组，需注意附件上传顺序。
📄 原文内容

Retrieves media attached to the passed post.

Parameters

$typestringrequired
Mime type.
$postint|WP_Postoptional
Post ID or WP_Post object. Default is global $post.

Return

WP_Post[] Array of media attached to the given post.

Source

function get_attached_media( $type, $post = 0 ) {
	$post = get_post( $post );

	if ( ! $post ) {
		return array();
	}

	$args = array(
		'post_parent'    => $post->ID,
		'post_type'      => 'attachment',
		'post_mime_type' => $type,
		'posts_per_page' => -1,
		'orderby'        => 'menu_order',
		'order'          => 'ASC',
	);

	/**
	 * Filters arguments used to retrieve media attached to the given post.
	 *
	 * @since 3.6.0
	 *
	 * @param array   $args Post query arguments.
	 * @param string  $type Mime type of the desired media.
	 * @param WP_Post $post Post object.
	 */
	$args = apply_filters( 'get_attached_media_args', $args, $type, $post );

	$children = get_children( $args );

	/**
	 * Filters the list of media attached to the given post.
	 *
	 * @since 3.6.0
	 *
	 * @param WP_Post[] $children Array of media attached to the given post.
	 * @param string    $type     Mime type of the media desired.
	 * @param WP_Post   $post     Post object.
	 */
	return (array) apply_filters( 'get_attached_media', $children, $type, $post );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_attached_media’, WP_Post[] $children, string $type, WP_Post $post )

Filters the list of media attached to the given post.

apply_filters( ‘get_attached_media_args’, array $args, string $type, WP_Post $post )

Filters arguments used to retrieve media attached to the given post.

Uses Description
get_children()wp-includes/post.php

Retrieves all children of the post parent ID.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.

Show 1 moreShow less

Used by Description
wp_video_shortcode()wp-includes/media.php

Builds the Video shortcode output.
wp_audio_shortcode()wp-includes/media.php

Builds the Audio shortcode output.

Changelog

Version Description
3.6.0 Introduced.

User Contributed Notes

  2. Skip to note 6 content


    Uriahs Victor


    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    Important to note that this function only returns the attachments that were first uploaded/added to the post.

    Uploading an image to Post A(ID 1) and then adding that image later to Post B(ID 2) would give an empty array if the following code was used:

    <br />
    $media = get_attached_media( 'image', 2 );<br />
    var_dump( $media );<br />

    You’d only get array data if you upload your media and add it to Post B before any other post.