post_playlist

💡 云策文档标注

概述

post_playlist 是一个 WordPress 过滤器，用于自定义播放列表短码的输出。通过返回非空值，可以完全替换默认的播放列表生成逻辑，实现高度定制化。

关键要点

过滤器名称：post_playlist，用于拦截和修改播放列表输出。
参数：$output（播放列表输出字符串）、$attr（短码属性数组）、$instance（短码实例的唯一数字 ID）。
作用：返回非空值将短路默认输出，直接返回该值，适用于自定义播放列表样式或功能。
应用场景：例如，通过添加自定义属性（如 cover_size）来调整专辑封面的图像尺寸。

代码示例

function wpdocs_mytheme_custom_playlist( $output, $attr, $instance ) {
    if ( 'false' == $attr['images'] || 'video' == $attr['type'] ) {
        return;
    }
    $cover_size = $attr['cover_size'] ?? 'thumbnail';
    // 自定义逻辑，例如使用指定图像尺寸生成播放列表数据
    $data = array(
        'type' => $attr['type'],
        'tracks' => $tracks // 自定义轨道数组
    );
    // 生成并返回自定义 HTML 输出
    ob_start();
    // 输出 HTML 模板
    return ob_get_clean();
}
add_filter( 'post_playlist', 'wpdocs_mytheme_custom_playlist', 10, 3 );

注意事项

在 PHP 7.0 及以上版本中，建议使用 null 合并运算符（??）处理默认值，例如 $cover_size = $attr['cover_size'] ?? 'thumbnail';。
自定义输出时需确保正确处理所有短码属性，避免破坏播放列表功能。
参考 wp_playlist_shortcode() 函数（位于 wp-includes/media.php）以了解默认实现细节。

📄 原文内容

Filters the playlist output.

Description

Returning a non-empty value from the filter will short-circuit generation of the default playlist output, returning the passed value instead.

Parameters

$outputstring: Playlist output. Default empty.
$attrarray: An array of shortcode attributes.
$instanceint: Unique numeric ID of this playlist shortcode instance.

Source

$output = apply_filters( 'post_playlist', '', $attr, $instance );

View all references View on Trac View on GitHub

Used by	Description
wp_playlist_shortcode()`wp-includes/media.php`	Builds the Playlist shortcode output.

Changelog

Version	Description
4.2.0	The `$instance` parameter was added.
3.9.0	Introduced.

User Contributed Notes

Skip to note 2 content

luboslives

6 years ago

How to display the album art from your audio files in a size other than ‘thumbnail’:

Sadly we can’t use responsive image sets with the default playlist / media player without completely rewriting the whole stack, which appears to involve jQuery, Backbone, undescore, a couple of mediaelement JS files, inlined JSON, and PHP templating. See /wp-includes⁩/js⁩/mediaelement/ and /wp-includes/media.php and media-template.php.

The next-best thing we can do is to use a higher-res image for the album artwork thumbnail. The JS files will read from the inlined JSON data, and by default will use the specified “thumb” property. That’s all we’re updating with the code below.

1. Add a custom attribute to your playlist shortcode to signify which registered image size you’d like to use. We’ll use a cover_size="medium" attribute.

2. Write your custom output using the post_playlist filter inside your functions.php file or elsewhere in your theme includes. Here I’ve removed any video playlist logic, see /wp-includes/media.php for the original.

/**

 * Passing a non-empty value to the filter will short-circuit the default output.

 *

 * @param string $output   Playlist output. Default empty.

 * @param array  $attr     An array of shortcode attributes.

 * @param int    $instance Unique numeric ID of this playlist shortcode instance.

 */

function wpdocs_mytheme_custom_playlist( $output, $attr, $instance ) {
	if ( 'false' == $attr['images'] || 'video' == $attr['type'] ) {

		return;

	}
	$cover_size = $attr['cover_size'] || 'thumbnail';

	$post = get_post();
	if ( ! empty( $attr['ids'] ) ) {

		if ( empty( $attr['orderby'] ) ) {

			$attr['orderby'] = 'post__in';

		}

		$attr['include'] = $attr['ids'];

	}
	$atts = shortcode_atts(

		array(

			'type'         => 'audio',

			'order'        => 'ASC',

			'orderby'      => 'menu_order ID',

			'id'           => $post ? $post->ID : 0,

			'include'      => '',

			'exclude'      => '',

			'style'        => 'light',

			'tracklist'    => true,

			'tracknumbers' => true,

			'images'       => true,

			'artists'      => true,

		),

		$attr,

		'playlist'

	);
	$id = intval( $atts['id'] );
	$args = array(

		'post_status'    => 'inherit',

		'post_type'      => 'attachment',

		'post_mime_type' => $atts['type'],

		'order'          => $atts['order'],

		'orderby'        => $atts['orderby'],

	);
	if ( ! empty( $atts['include'] ) ) {

		$args['include'] = $atts['include'];

		$_attachments    = get_posts( $args );
		$attachments = array();

		foreach ( $_attachments as $key => $val ) {

			$attachments[ $val->ID ] = $_attachments[ $key ];

		}

	} elseif ( ! empty( $atts['exclude'] ) ) {

		$args['post_parent'] = $id;

		$args['exclude']     = $atts['exclude'];

		$attachments         = get_children( $args );

	} else {

		$args['post_parent'] = $id;

		$attachments         = get_children( $args );

	}
	if ( empty( $attachments ) ) {

		return '';

	}
	if ( is_feed() ) {

		$output = "n";

		foreach ( $attachments as $att_id => $attachment ) {

			$output .= wp_get_attachment_link( $att_id ) . "n";

		}

		return $output;

	}
	$data = array(

		'type'         => $atts['type'],

		'tracklist'    => wp_validate_boolean( $atts['tracklist'] ),

		'tracknumbers' => wp_validate_boolean( $atts['tracknumbers'] ),

		'images'       => wp_validate_boolean( $atts['images'] ),

		'artists'      => wp_validate_boolean( $atts['artists'] ),

	);
	$tracks = array();

	foreach ( $attachments as $attachment ) {

		$url   = wp_get_attachment_url( $attachment->ID );

		$ftype = wp_check_filetype( $url, wp_get_mime_types() );

		$track = array(

			'src'         => $url,

			'type'        => $ftype['type'],

			'title'       => $attachment->post_title,

			'caption'     => $attachment->post_excerpt,

			'description' => $attachment->post_content,

		);
		$track['meta'] = array();

		$meta          = wp_get_attachment_metadata( $attachment->ID );

		if ( ! empty( $meta ) ) {

			foreach ( wp_get_attachment_id3_keys( $attachment ) as $key => $label ) {

				if ( ! empty( $meta[ $key ] ) ) {

					$track['meta'][ $key ] = $meta[ $key ];

				}

			}

		}
		if ( $atts['images'] ) {

			$thumb_id = get_post_thumbnail_id( $attachment->ID );

			if ( ! empty( $thumb_id ) ) {

				list( $src, $width, $height ) = wp_get_attachment_image_src( $thumb_id, 'full' );

				$track['image']               = compact( 'src', 'width', 'height' );

				// use our custom size

				list( $src, $width, $height ) = wp_get_attachment_image_src( $thumb_id, $cover_size );

				$track['thumb']               = compact( 'src', 'width', 'height' );

			} else {

				$src            = wp_mime_type_icon( $attachment->ID );

				$width          = 48;

				$height         = 64;

				$track['image'] = compact( 'src', 'width', 'height' );

				$track['thumb'] = compact( 'src', 'width', 'height' );

			}

		}
		$tracks[] = $track;

	}

	$data['tracks'] = $tracks;
	$safe_type  = esc_attr( $atts['type'] );

	$safe_style = esc_attr( $atts['style'] );
	// begin output

	ob_start();
	if ( 1 === $instance ) {

		// Prints and enqueues playlist scripts, styles, and JavaScript templates.

		do_action( 'wp_playlist_scripts', $atts['type'], $atts['style'] );

	}

	?>

	<div class="wp-playlist wp-<?php echo $safe_type; ?>-playlist wp-playlist-<?php echo $safe_style; ?>">
		<div class="wp-playlist-current-item"></div>
		< controls="controls" preload="none"><!--<?php echo $safe_type; ?-->>

		<div class="wp-playlist-next"></div>

		<div class="wp-playlist-prev"></div>

		<noscript>

		<ol>

		 $attachment ) {

			printf( '<li>%s</li>', wp_get_attachment_link( $att_id ) );

		}

		?>

		</ol>

		</noscript>

		<script type="application/json" class="wp-playlist-script"><?php echo wp_json_encode( $data ); ?></script>

	</div>

	</pre>

				</div><!-- .comment-content -->
					<section id='feedback-4033' class='wporg-has-embedded-code feedback hide-if-js' data-comment-count='1'>

<ul class='children'>

			<li id="comment-4056" data-comment-id="4056" class="comment byuser comment-author-luboslives odd alt depth-2">

			<article id="div-comment-4056" class="comment-body">
				<div class="wporg-has-embedded-code comment-content" id="comment-content-4056">

				<div><strong>Correction:</strong> the conditional assignment should read <code>$cover_size = $attr['cover_size'] ?? 'thumbnail'; (using the null coalescing operator, PHP >= 7.0)

luboslives 6 years ago

云策 WordPress 开发者社区

钩子文档

post_playlist

概述

关键要点

代码示例

注意事项

Description

Parameters

Source

Changelog

User Contributed Notes

钩子文档

概述

关键要点

代码示例

注意事项

Description

Parameters

Source

Related

Changelog

User Contributed Notes