概述

get_adjacent_image_link() 函数用于获取具有相同父文章的相邻图像链接，支持指定方向、图像尺寸和链接文本。它通过查询附件数据并应用过滤器来生成 HTML 标记。

关键要点

• 函数返回相邻图像链接的 HTML 标记，基于当前附件对象的父文章 ID 进行查询。
• 参数包括 $prev（布尔值，控制方向，默认为 true 表示上一个）、$size（图像尺寸，默认为 'thumbnail'）和 $text（链接文本，默认为 false）。
• 内部使用 get_children() 获取图像附件，并通过 wp_get_attachment_link() 生成链接。
• 提供动态过滤器 {$adjacent}_image_link，允许自定义输出，其中 $adjacent 为 'next' 或 'previous'。

代码示例

function get_adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false ) {
    $post        = get_post();
    $attachments = array_values(
        get_children(
            array(
                'post_parent'    => $post->post_parent,
                'post_status'    => 'inherit',
                'post_type'      => 'attachment',
                'post_mime_type' => 'image',
                'order'          => 'ASC',
                'orderby'        => 'menu_order ID',
            )
        )
    );

    foreach ( $attachments as $k => $attachment ) {
        if ( (int) $attachment->ID === (int) $post->ID ) {
            break;
        }
    }

    $output        = '';
    $attachment_id = 0;

    if ( $attachments ) {
        $k = $prev ? $k - 1 : $k + 1;

        if ( isset( $attachments[ $k ] ) ) {
            $attachment_id = $attachments[ $k ]->ID;
            $attr          = array( 'alt' => get_the_title( $attachment_id ) );
            $output        = wp_get_attachment_link( $attachment_id, $size, true, false, $text, $attr );
        }
    }

    $adjacent = $prev ? 'previous' : 'next';

    /**
     * Filters the adjacent image link.
     *
     * The dynamic portion of the hook name, `$adjacent`, refers to the type of adjacency,
     * either 'next', or 'previous'.
     *
     * Possible hook names include:
     *
     *  - `next_image_link`
     *  - `previous_image_link`
     *
     * @since 3.5.0
     *
     * @param string $output        Adjacent image HTML markup.
     * @param int    $attachment_id Attachment ID
     * @param string|int[] $size    Requested image size. Can be any registered image size name, or
     *                              an array of width and height values in pixels (in that order).
     * @param string $text          Link text.
     */
    return apply_filters( "{$adjacent}_image_link", $output, $attachment_id, $size, $text );
}

注意事项

• 函数依赖于全局 $post 对象，确保在正确的上下文中调用，例如在附件页面或循环内。
• 图像尺寸参数 $size 可以是注册的尺寸名称或像素数组，需确保尺寸有效以避免错误。
• 过滤器 {$adjacent}_image_link 允许开发者修改输出，注意动态钩子名称的生成。