pre_get_avatar

💡 云策文档标注

概述

pre_get_avatar 是一个 WordPress 过滤器，允许在 get_avatar() 函数执行前提前返回用户头像的 HTML 代码，从而可以短路默认的头像获取流程。

返回非空值将短路 get_avatar()，通过 'get_avatar' 过滤器并提前返回。
参数包括 $avatar（头像 HTML，默认 null）、$id_or_email（用户标识，支持多种类型）和 $args（传递给 get_avatar_url() 的参数数组）。
$args 参数包含 size、default、force_default、rating、scheme 等选项，用于自定义头像显示。
processed_args 参数作为引用传递，返回时包含处理后的 $args 和 "found_avatar" 猜测。

$avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );

📄 原文内容

Allows the HTML for a user’s avatar to be returned early.

Returning a non-null value will effectively short-circuit get_avatar() , passing the value through the ‘get_avatar’ filter and returning early.

$avatarstring|null

HTML for the user’s avatar. Default null.

$id_or_emailmixed

The avatar to retrieve. Accepts a user ID, Gravatar MD5 hash, user email, WP_User object, WP_Post object, or WP_Comment object.

$argsarray

Arguments passed to get_avatar_url() , after processing.

More Arguments from get_avatar_url( … $args )

Arguments to use instead of the default arguments.

size int
Height and width of the avatar in pixels. Default 96.
default string
URL for the default image or a default type. Accepts:
- '404' (return a 404 instead of a default image)
- 'retro' (a 8-bit arcade-style pixelated face)
- 'robohash' (a robot)
- 'monsterid' (a monster)
- 'wavatar' (a cartoon face)
- 'identicon' (the “quilt”, a geometric pattern)
- 'initials' (initials based avatar with background color)
- 'color' (generated background color)
- 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
- 'blank' (transparent GIF)
- 'gravatar_default' (the Gravatar logo) Default is the value of the 'avatar_default' option, with a fallback of 'mystery'.
force_default bool
Whether to always show the default image, never the Gravatar.
Default false.
rating string
What rating to display avatars up to. Accepts:
- 'G' (suitable for all audiences)
- 'PG' (possibly offensive, usually for audiences 13 and above)
- 'R' (intended for adult audiences above 17)
- 'X' (even more mature than above) Default is the value of the 'avatar_rating' option.
scheme string
URL scheme to use. See set_url_scheme() for accepted values.
processed_args array
When the function returns, the value will be the processed/sanitized $args plus a “found_avatar” guess. Pass as a reference.

$avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );

Used by	Description
get_avatar()`wp-includes/pluggable.php`	Retrieves the avatar `<img>` tag for a user, email address, MD5 hash, comment, or post.

Version	Description
4.2.0	Introduced.