云策 WordPress 开发者社区

函数文档

wp_embed_defaults()

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

概述

wp_embed_defaults() 函数用于生成嵌入内容的默认宽度和高度数组。宽度默认基于主题设置的 content_width，若无设置则使用 500px；高度为宽度的 1.5 倍，但不超过 1000px。

关键要点

  • 函数返回一个索引数组，包含宽度和高度（单位：像素），索引 0 为宽度，索引 1 为高度。
  • 宽度优先从全局变量 $GLOBALS['content_width'] 获取，若未定义则默认为 500。
  • 高度计算为 min(ceil(宽度 * 1.5), 1000)，确保不超过 1000px。
  • 可通过 'embed_defaults' 过滤器钩子调整默认尺寸数组。
  • 函数接受一个可选的 $url 参数，用于在过滤器中传递嵌入 URL。

代码示例

$defaults = wp_embed_defaults();
var_dump( $defaults );

/* 示例输出：
array(2) {
  ["width"]=>
  int(625)
  ["height"]=>
  float(938)
}
*/
📄 原文内容

Creates default array of embed parameters.

Description

The width defaults to the content width as specified by the theme. If the theme does not specify a content width, then 500px is used.

The default height is 1.5 times the width, or 1000px, whichever is smaller.

The ’embed_defaults’ filter can be used to adjust either of these values.

Parameters

$urlstringoptional
The URL that should be embedded. Default empty.

Return

int[] Indexed array of the embed width and height in pixels.

  • 0 int
    The embed width.
  • 1 int
    The embed height.

Source

function wp_embed_defaults( $url = '' ) {
	if ( ! empty( $GLOBALS['content_width'] ) ) {
		$width = (int) $GLOBALS['content_width'];
	}

	if ( empty( $width ) ) {
		$width = 500;
	}

	$height = min( (int) ceil( $width * 1.5 ), 1000 );

	/**
	 * Filters the default array of embed dimensions.
	 *
	 * @since 2.9.0
	 *
	 * @param int[]  $size {
	 *     Indexed array of the embed width and height in pixels.
	 *
	 *     @type int $0 The embed width.
	 *     @type int $1 The embed height.
	 * }
	 * @param string $url  The URL that should be embedded.
	 */
	return apply_filters( 'embed_defaults', compact( 'width', 'height' ), $url );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ’embed_defaults’, int[] $size, string $url )

Filters the default array of embed dimensions.

Uses Description
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
Used by Description
WP_Embed::get_embed_handler_html()wp-includes/class-wp-embed.php

Returns embed HTML for a given URL from embed handlers.
WP_Embed::shortcode()wp-includes/class-wp-embed.php

The do_shortcode() callback function.
WP_oEmbed::fetch()wp-includes/class-wp-oembed.php

Connects to an oEmbed provider and returns the result.

Changelog

Version Description
2.9.0 Introduced.

User Contributed Notes