云策 WordPress 开发者社区

钩子文档

get_avatar

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

概述

get_avatar 过滤器用于修改 get_avatar() 函数返回的用户头像 HTML 代码。开发者可通过此钩子自定义头像输出，需处理多种输入类型并重建完整图像标签。

关键要点

  • 过滤器名称：get_avatar，用于过滤用户头像的 HTML 字符串。
  • 参数：$avatar（头像 HTML）、$id_or_email（用户 ID、Gravatar MD5 哈希、邮箱、WP_User、WP_Post 或 WP_Comment 对象）、$size（头像尺寸）、$default（默认图像类型或 URL）、$alt（替代文本）、$args（传递给 get_avatar_data() 的参数数组）。
  • 使用难点：需处理 $id_or_email 的多种类型（如用户 ID、对象或邮箱），并返回完整图像 HTML 而非仅 URL。
  • 相关函数：get_avatar()，位于 wp-includes/pluggable.php，用于检索头像标签。
  • 版本历史：WordPress 4.2.0 添加 $args 参数，2.5.0 引入此过滤器。

代码示例

// Apply filter
add_filter( 'get_avatar' , 'my_custom_avatar' , 1 , 5 );

function my_custom_avatar( $avatar, $id_or_email, $size, $default, $alt ) {
    $user = false;

    if ( is_numeric( $id_or_email ) ) {

        $id = (int) $id_or_email;
        $user = get_user_by( 'id' , $id );

    } elseif ( is_object( $id_or_email ) ) {

        if ( ! empty( $id_or_email->user_id ) ) {
            $id = (int) $id_or_email->user_id;
            $user = get_user_by( 'id' , $id );
        }

    } else {
        $user = get_user_by( 'email', $id_or_email );	
    }

    if ( $user && is_object( $user ) ) {

        if ( $user->data->ID == '1' ) {
            $avatar = 'YOUR_NEW_IMAGE_URL';
            $avatar = "<img src='YOUR_NEW_IMAGE_URL' width='{$size}' height='{$size}' alt='{$alt}' />";
        }

    }

    return $avatar;
}

注意事项

  • 处理 $id_or_email 时需检查其类型（数字、对象或字符串），以正确获取用户信息。
  • 必须返回完整的 标签 HTML，包括 src、width、height 和 alt 属性，而不仅仅是图像 URL。
  • args 参数包含 get_avatar_data() 的详细设置，如 size、default、rating 等，可用于进一步自定义。
📄 原文内容

Filters the HTML for a user’s avatar.

Parameters

$avatarstring
HTML for the user’s avatar.
$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.
$sizeint
Height and width of the avatar in pixels.
$default_valuestring
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)
  • 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
  • 'blank' (transparent GIF)
  • 'gravatar_default' (the Gravatar logo)

$altstring
Alternative text to use in the avatar image tag.
$argsarray
Arguments passed to get_avatar_data() , after processing.

More Arguments from get_avatar_data( … $args )

Arguments to use instead of the default arguments.

  • size int
    Height and width of the avatar in pixels. Default 96.
  • height int
    Display height of the avatar in pixels. Defaults to $size.
  • width int
    Display width of the avatar in pixels. Defaults to $size.
  • 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.
    For Gravatars this setting is ignored and HTTPS is used to avoid unnecessary redirects. The setting is retained for systems using the ‘pre_get_avatar_data’ filter to customize avatars.
  • processed_args array
    When the function returns, the value will be the processed/sanitized $args plus a “found_avatar” guess. Pass as a reference.
  • extra_attr string
    HTML attributes to insert in the IMG element. Is not sanitized.

More Information

The “get_avatar” filter can be used to alter the avatar image returned by the get_avatar() function.

There are two tricky parts to using this filter:

  1. get_avatar() can be passed a user ID, user object or email address. So we will not know what we are looking at and will need to check for them all.
  2. It returns the entire image html string with classes, alt, and src. So you need to recreate the entire thing, not just send back the image url.

Source

return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args );

View all references View on Trac View on GitHub

Used by Description
get_avatar()wp-includes/pluggable.php

Retrieves the avatar <img> tag for a user, email address, MD5 hash, comment, or post.

Changelog

Version Description
4.2.0 Added the $args parameter.
2.5.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Steven Lin


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

    Example migrating from Codex:

    In this example, I am looking for user with an id of 1 and sending back a custom image.

    // Apply filter
add_filter( 'get_avatar' , 'my_custom_avatar' , 1 , 5 );

function my_custom_avatar( $avatar, $id_or_email, $size, $default, $alt ) {
    $user = false;

    if ( is_numeric( $id_or_email ) ) {

        $id = (int) $id_or_email;
        $user = get_user_by( 'id' , $id );

    } elseif ( is_object( $id_or_email ) ) {

        if ( ! empty( $id_or_email->user_id ) ) {
            $id = (int) $id_or_email->user_id;
            $user = get_user_by( 'id' , $id );
        }

    } else {
        $user = get_user_by( 'email', $id_or_email );	
    }

    if ( $user && is_object( $user ) ) {

        if ( $user->data->ID == '1' ) {
            $avatar = 'YOUR_NEW_IMAGE_URL';
            $avatar = "<img alt='{$alt}' src='{$avatar}' class='avatar avatar-{$size} photo' height='{$size}' width='{$size}' />";
        }

    }

    return $avatar;
}