云策 WordPress 开发者社区

函数文档

prepend_attachment()

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

概述

prepend_attachment() 是一个 WordPress 函数，用于在附件类型文章的内容前添加附件标记。它根据附件类型（如视频、音频或图像）生成相应的 HTML 输出，并通过过滤器允许自定义。

关键要点

  • 函数检查当前文章是否为附件类型，否则直接返回原内容
  • 针对视频附件，生成包含宽度、高度和海报图的视频短代码
  • 针对音频附件，生成音频短代码
  • 对于其他附件（如图像），生成中等尺寸的链接图像
  • 使用 apply_filters('prepend_attachment', $p) 允许开发者过滤附件输出
  • 最终将生成的附件标记前置到文章内容前

代码示例

function prepend_attachment( $content ) {
    $post = get_post();

    if ( empty( $post->post_type ) || 'attachment' !== $post->post_type ) {
        return $content;
    }

    if ( wp_attachment_is( 'video', $post ) ) {
        $meta = wp_get_attachment_metadata( get_the_ID() );
        $atts = array( 'src' => wp_get_attachment_url() );
        if ( ! empty( $meta['width'] ) && ! empty( $meta['height'] ) ) {
            $atts['width']  = (int) $meta['width'];
            $atts['height'] = (int) $meta['height'];
        }
        if ( has_post_thumbnail() ) {
            $atts['poster'] = wp_get_attachment_url( get_post_thumbnail_id() );
        }
        $p = wp_video_shortcode( $atts );
    } elseif ( wp_attachment_is( 'audio', $post ) ) {
        $p = wp_audio_shortcode( array( 'src' => wp_get_attachment_url() ) );
    } else {
        $p = '';
        // Show the medium sized image representation of the attachment if available, and link to the raw file.
        $p .= wp_get_attachment_link( 0, 'medium', false );
        $p .= '';
    }

    /**
     * Filters the attachment markup to be prepended to the post content.
     *
     * @since 2.0.0
     *
     * @see prepend_attachment()
     *
     * @param string $p The attachment HTML output.
     */
    $p = apply_filters( 'prepend_attachment', $p );

    return "$pn$content";
}

注意事项

  • 函数仅对附件类型文章生效，其他文章类型会直接返回原内容
  • 使用 wp_attachment_is() 判断附件类型，确保正确处理视频、音频等
  • 通过 prepend_attachment 过滤器，开发者可以修改附件输出的 HTML
  • 自 WordPress 2.0.0 版本引入，兼容性良好
📄 原文内容

Wraps attachment in paragraph tag before content.

Parameters

$contentstringrequired

Return

string

Source

function prepend_attachment( $content ) {
	$post = get_post();

	if ( empty( $post->post_type ) || 'attachment' !== $post->post_type ) {
		return $content;
	}

	if ( wp_attachment_is( 'video', $post ) ) {
		$meta = wp_get_attachment_metadata( get_the_ID() );
		$atts = array( 'src' => wp_get_attachment_url() );
		if ( ! empty( $meta['width'] ) && ! empty( $meta['height'] ) ) {
			$atts['width']  = (int) $meta['width'];
			$atts['height'] = (int) $meta['height'];
		}
		if ( has_post_thumbnail() ) {
			$atts['poster'] = wp_get_attachment_url( get_post_thumbnail_id() );
		}
		$p = wp_video_shortcode( $atts );
	} elseif ( wp_attachment_is( 'audio', $post ) ) {
		$p = wp_audio_shortcode( array( 'src' => wp_get_attachment_url() ) );
	} else {
		$p = '<p class="attachment">';
		// Show the medium sized image representation of the attachment if available, and link to the raw file.
		$p .= wp_get_attachment_link( 0, 'medium', false );
		$p .= '</p>';
	}

	/**
	 * Filters the attachment markup to be prepended to the post content.
	 *
	 * @since 2.0.0
	 *
	 * @see prepend_attachment()
	 *
	 * @param string $p The attachment HTML output.
	 */
	$p = apply_filters( 'prepend_attachment', $p );

	return "$pn$content";
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘prepend_attachment’, string $p )

Filters the attachment markup to be prepended to the post content.

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

Verifies an attachment is of a given type.
has_post_thumbnail()wp-includes/post-thumbnail-template.php

Determines whether a post has an image attached.
get_post_thumbnail_id()wp-includes/post-thumbnail-template.php

Retrieves the post thumbnail ID.
wp_get_attachment_link()wp-includes/post-template.php

Retrieves an attachment page link using an image or icon, if possible.
get_the_ID()wp-includes/post-template.php

Retrieves the ID of the current item in the WordPress Loop.
wp_video_shortcode()wp-includes/media.php

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

Builds the Audio shortcode output.
wp_get_attachment_metadata()wp-includes/post.php

Retrieves attachment metadata for attachment ID.
wp_get_attachment_url()wp-includes/post.php

Retrieves the URL for an attachment.
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 6 moreShow less

Used by Description
wp_embed_excerpt_attachment()wp-includes/embed.php

Filters the post excerpt for the embed template.

Changelog

Version Description
2.0.0 Introduced.