云策 WordPress 开发者社区

函数文档

wp_embed_register_handler()

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

概述

wp_embed_register_handler() 函数用于在 WordPress 中注册自定义嵌入处理器，主要用于不支持 oEmbed 的网站。它通过指定 ID、正则表达式和回调函数来匹配并处理特定 URL 的嵌入内容。

关键要点

  • 函数用于注册嵌入处理器，适用于非 oEmbed 支持的站点
  • 参数包括：唯一 ID、用于匹配 URL 的正则表达式、回调函数和可选的优先级（默认 10）
  • 内部调用 WP_Embed::register_handler() 方法实现功能
  • 自 WordPress 2.9.0 版本引入

代码示例

wp_embed_register_handler(
    'forbes',
    '#http://(?:www|video).forbes.com/(?:video/embed/embed.html|embedvideo/)?show=([d]+)&format;=frame&height;=([d]+)&width;=([d]+)&video;=(.+?)($|&)#i',
    'wpdocs_embed_handler_forbes'
);

注意事项

  • 正则表达式参数针对 URL 进行匹配，可使用 ^ 和 $ 锚定，支持非贪婪匹配
  • 回调函数需处理匹配结果并返回嵌入代码，注意使用 esc_attr() 等函数确保安全性
  • 在 sprintf() 中使用 % 符号时需注意转义，避免格式化错误
📄 原文内容

Registers an embed handler.

Description

Should probably only be used for sites that do not support oEmbed.

Parameters

$idstringrequired
An internal ID/name for the handler. Needs to be unique.
$regexstringrequired
The regex that will be used to see if this handler should be used for a URL.
$callbackcallablerequired
The callback function that will be called if the regex is matched.
$priorityintoptional
Used to specify the order in which the registered handlers will be tested.

Default:10

Source

function wp_embed_register_handler( $id, $regex, $callback, $priority = 10 ) {
	global $wp_embed;
	$wp_embed->register_handler( $id, $regex, $callback, $priority );
}

View all references View on Trac View on GitHub

Uses Description
WP_Embed::register_handler()wp-includes/class-wp-embed.php

Registers an embed handler.
Used by Description
wp_maybe_load_embeds()wp-includes/embed.php

Determines if default embed handlers should be loaded.

Changelog

Version Description
2.9.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    Codex


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

    Basic Example

    Register an embed handler for Forbes video embeds.

    wp_embed_register_handler(
	'forbes',
	'#http://(?:www|video).forbes.com/(?:video/embed/embed.html|embedvideo/)?show=([d]+)&format;=frame&height;=([d]+)&width;=([d]+)&video;=(.+?)($|&)#i',
	'wpdocs_embed_handler_forbes'
);

function wpdocs_embed_handler_forbes( $matches, $attr, $url, $rawattr ) {

	$embed = sprintf(
			'<iframe src="<a href="http://www.forbes.com/video/embed/embed.html?show=%1$s&format=frame&height=%2$s&width=%3$s&video=%4$s&mode=render&quot" rel="nofollow ugc">http://www.forbes.com/video/embed/embed.html?show=%1$s&format;=frame&height;=%2$s&width;=%3$s&video;=%4$s&mode;=render"</a>; width="%3$spx" height="%2$spx" frameborder="0" scrolling="no" marginwidth="0" marginheight="0"></iframe>',
			esc_attr($matches[1]),
			esc_attr($matches[2]),
			esc_attr($matches[3]),
			esc_attr($matches[4])
			);

	return $embed;
}

  2. Skip to note 5 content


    cogdog


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

    Here is a means to add oembed support for web-based audio recorders Vocaroo and Sodaphonic. I found the hard way that sprintf fails when you have a “%” in the string

    add_action( 'init', 'cdb_register_embeds' );
function dcb_register_embeds() {
	// handler for vocaroo audio
	wp_embed_register_handler(
		'vocaroo',
		'#^https?://(vocaroo.com|voca.ro)/([a-zAA-Z0-9]+)$#i',
		'cdb_handler_vocaroo'
	);
	
	// handler for sodaphonic boombox audio	
	wp_embed_register_handler(
		'sodaphonic',
		'#^https?://sodaphonic.com/audio/([a-zAA-Z0-9]+)(.*)$#i',
		'cdb_handler_sodaphonic'
	);
}

function cdb_handler_vocaroo( $matches, $attr, $url, $rawattr ) {
$embed = '';
return $embed;
}

function cdb_handler_sodaphonic( $matches, $attr, $url, $rawattr ) {
$embed = '';
	
return $embed;
}

  3. Skip to note 6 content


    Ryan McCue


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

    Note that the $regex parameter is checked against the URL, not against the content, so you can anchor the regular expression with ^ and $. This is useful if you want to use an ungreedy match group at the end of your URL:

    wp_embed_register_handler( $id, '#^http://example.com/(?.+)?$#', __NAMESPACE__ . '\handle_embed' );