云策 WordPress 开发者社区

钩子文档

pre_oembed_result

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

概述

pre_oembed_result 过滤器允许在发起 HTTP 请求前修改或替换 oEmbed 结果，可用于优化默认逻辑或自定义嵌入处理。

关键要点

  • 过滤器在 oEmbed 检索过程中早期执行，可短路默认流程，直接返回自定义结果。
  • 参数包括 $result（未净化的 HTML）、$url（嵌入内容的 URL）和 $args（额外参数，如宽度、高度和发现设置）。
  • 返回非 null 值将跳过后续 HTTP 请求，直接使用该值作为嵌入结果。

代码示例

$pre = apply_filters( 'pre_oembed_result', null, $url, $args );

注意事项

  • $result 参数是未净化的 HTML，使用时需注意安全性，避免 XSS 攻击。
  • 过滤器自 WordPress 4.5.3 版本引入，主要用于 WP_oEmbed::get_html() 函数。
📄 原文内容

Filters the oEmbed result before any HTTP requests are made.

Description

This allows one to short-circuit the default logic, perhaps by replacing it with a routine that is more optimal for your setup.

Returning a non-null value from the filter will effectively short-circuit retrieval and return the passed value instead.

Parameters

$resultnull|string
The UNSANITIZED (and potentially unsafe) HTML that should be used to embed.
Default null to continue retrieving the result.
$urlstring
The URL to the content that should be attempted to be embedded.
$argsstring|array
Additional arguments for retrieving embed HTML.
See wp_oembed_get() for accepted arguments. Default empty.

More Arguments from wp_oembed_get( … $args )

Additional arguments for retrieving embed HTML. Default empty.

  • width int|string
    Optional. The maxwidth value passed to the provider URL.
  • height int|string
    Optional. The maxheight value passed to the provider URL.
  • discover bool
    Optional. Determines whether to attempt to discover link tags at the given URL for an oEmbed provider when the provider URL is not found in the built-in providers list. Default true.

Source

$pre = apply_filters( 'pre_oembed_result', null, $url, $args );

View all references View on Trac View on GitHub

Used by Description
WP_oEmbed::get_html()wp-includes/class-wp-oembed.php

The do-it-all function that takes a URL and attempts to return the HTML.

Changelog

Version Description
4.5.3 Introduced.