WordPress短代码显示用户头像缩略图教程

本教程旨在指导开发者如何在WordPress中创建自定义短代码，以封装并动态显示用户头像缩略图。通过分析现有PHP插件代码，我们将学习如何正确引入全局变量、获取当前用户上下文，并安全地在短代码回调函数中输出HTML和PHP逻辑，从而实现用户头像在网站任意位置的灵活展示。

引言：WordPress短代码与PHP逻辑集成

WordPress短代码（Shortcode）提供了一种便捷的方式，让用户无需编写复杂的PHP代码，即可在文章、页面或小工具中插入动态内容或特定功能。它们本质上是PHP函数的占位符，当WordPress解析内容时，会执行对应的PHP函数并将其返回值替换短代码。

将PHP逻辑封装进短代码有诸多优势：

• 内容与逻辑分离： 编辑者可以在不接触代码的情况下，通过简单的短代码来控制页面元素的显示。
• 可重用性： 一旦定义，短代码可以在网站的任何位置重复使用。
• 灵活性： 通过短代码属性，可以轻松定制功能的行为和显示。

对于需要动态显示用户头像缩略图的场景，例如在一个自定义的用户列表、作者简介区域或评论区，将获取头像的PHP逻辑封装为短代码，能够极大地提升网站开发的效率和灵活性。

理解现有用户头像插件的PHP代码

在将PHP代码封装进短代码之前，我们需要深入理解原始插件中用于显示用户头像缩略图的代码片段。以下是原始插件中负责显示缩略图的关键HTML结构：

这个HTML片段的显示依赖于两个关键的PHP变量：

1. $user：一个用户对象，用于获取用户ID和电子邮件。
2. $avatar_thumbnail：用户头像缩略图的URL。

为了生成 $avatar_thumbnail，原始插件代码执行了以下逻辑：

// 获取用户是否设置了自定义头像
$has_wp_user_avatar = has_wp_user_avatar( @$user->ID );

// 如果头像显示功能开启，获取原始头像图片源，否则使用默认空白图片
$avatar_medium_src = 1 == (bool) $show_avatars ? $wpua_functions->wpua_get_avatar_original( @$user->user_email, 'medium' ) : includes_url() . 'images/blank.gif';

// 检查用户是否设置了自定义头像，如果设置则获取自定义头像，否则使用原始头像图片源
$avatar_thumbnail = $has_wp_user_avatar ? get_wp_user_avatar_src( $user->ID, 96 ) : $avatar_medium_src;

从上述逻辑中，我们可以识别出短代码实现所需的关键依赖：

• 全局变量： $show_avatars (WordPress全局设置), $wpua_functions (插件的函数对象)。
• 插件函数： has_wp_user_avatar(), wpua_get_avatar_original(), get_wp_user_avatar_src()。
• 用户上下文： 短代码需要知道要显示哪个用户的头像。

开发自定义短代码的挑战与解决方案

在将上述PHP逻辑移植到短代码中时，我们需要解决几个关键挑战：

1. 用户上下文的获取：

   • 挑战： 原始插件代码通常在用户资料页面等特定上下文中运行，其中 $user 对象是预先定义的。短代码在任何位置都可能被调用，无法直接获得 $user 对象。
   • 解决方案： 我们可以默认显示当前登录用户的头像（通过 wp_get_current_user()），或者通过短代码属性（例如 user_id）允许用户指定要显示哪个用户的头像。

2. 全局变量的声明：

   • 挑战： $show_avatars 和 $wpua_functions 都是在插件或WordPress核心中定义的全局变量。在自定义函数中直接使用它们会导致“未定义变量”错误。
   • 解决方案： 在短代码回调函数的开头，使用 global 关键字明确声明这些全局变量，例如 global $current_user, $show_avatars, $wpua_functions;。

3. 插件函数的可用性：

   • 挑战： has_wp_user_avatar()、wpua_get_avatar_original() 和 get_wp_user_avatar_src() 都是特定于用户头像插件的函数。如果插件未激活，调用这些函数会导致致命错误。
   • 解决方案： 在调用这些函数之前，使用 function_exists() 和 is_object() / method_exists() 进行检查，确保它们可用。如果不可用，则返回一条错误消息或默认内容。

4. 短代码的输出方式：

   • 挑战： 短代码回调函数通常应该 return （返回）内容，而不是直接 echo （输出）内容。直接 echo 可能会导致内容在预期位置之前输出，破坏页面布局。
   • 解决方案： 使用PHP的输出缓冲（Output Buffering）机制。在需要输出HTML和PHP混合内容之前调用 ob_start()，在所有内容输出完毕后调用 ob_get_clean() 来捕获所有输出并将其作为字符串返回。

实现用户头像缩略图短代码

考虑到上述挑战和解决方案，我们现在可以编写一个功能完善、健壮且支持属性的短代码。

将以下代码添加到您的主题的 functions.php 文件或一个自定义插件中：

/**
 * WordPress短代码：显示用户头像缩略图
 *
 * @param array $atts 短代码属性数组。
 * @return string 生成的HTML内容。
 */
function display_user_avatar_thumbnail_shortcode( $atts ) {
    // 定义短代码的默认属性
    $atts = shortcode_atts( array(
        'user_id' => 0,    // 默认0表示当前登录用户
        'size'    => 96,   // 默认缩略图尺寸
        'class'   => '',   // 额外CSS类
    ), $atts, 'user_avatar_thumbnail' );

    $user_id = intval( $atts['user_id'] );
    $size    = intval( $atts['size'] );
    $extra_class = esc_attr( $atts['class'] );

    $user = null;

    // 根据user_id属性获取用户对象
    if ( $user_id > 0 ) {
        $user = get_user_by( 'ID', $user_id );
        if ( ! $user ) {
            return '
' . esc_html__( '指定用户不存在。', 'your-text-domain' ) . '
';
        }
    } else {
        // 如果没有指定user_id，则尝试获取当前登录用户
        if ( ! is_user_logged_in() ) {
            return '
' . esc_html__( '请登录以查看头像。', 'your-text-domain' ) . '
';
        }
        $user = wp_get_current_user();
    }

    // 声明必要的全局变量，这些变量通常由WordPress核心或插件提供
    global $current_user, $show_avatars, $wpua_functions;

    // 检查所需插件函数和对象是否存在，以防止插件未激活导致错误
    if ( ! function_exists( 'has_wp_user_avatar' ) || ! is_object( $wpua_functions ) || ! method_exists( $wpua_functions, 'wpua_get_avatar_original' ) || ! function_exists( 'get_wp_user_avatar_src' ) ) {
        return '
' . esc_html__( '用户头像插件功能不可用。', 'your-text-domain' ) . '
';
    }

    // 获取用户是否设置了自定义头像
    $has_wp_user_avatar = has_wp_user_avatar( $user->ID );

    // 获取原始头像图片源，如果未设置头像或禁用显示，则使用默认空白图片
    // 注意：`1 == (bool)$show_avatars` 是原插件的写法，表示如果头像显示功能开启
    $avatar_medium_src = ( 1 == (bool) $show_avatars ) ? $wpua_functions->wpua_get_avatar_original( $user->user_email, 'medium' ) : includes_url() . 'images/blank.gif';

    // 获取缩略图头像源，如果用户有自定义头像则获取，否则使用原始头像源
    $avatar_thumbnail = $has_wp_user_avatar ? get_wp_user_avatar_src( $user->ID, $size ) : $avatar_medium_src;

    // 使用输出缓冲捕获所有HTML输出
    ob_start();
    ?>