Como Usar a Função wp_get_attachment_image no WordPress + Exemplos Úteis

A wp_get_attachment_image é uma função do WordPress que permite recuperar e exibir facilmente anexos de imagem com base em seus IDs.

Não importa se você está construindo um tema personalizado ou um plugin, essa função oferece uma maneira flexível de exibir imagens com tamanhos e atributos personalizados.

Neste tutorial, vamos abordar a função wp_get_attachment_image() e explicar seus parâmetros. Nós também vamos mostrar alguns casos de uso populares que você pode testar em seu site hospedado no WordPress.

Parâmetros da Função wp_get_attachment_image

A função wp_get_attachment_image() (link em inglês) permite que os usuários recuperem um elemento HTML do tipo img para um anexo de imagem.

wp_get_attachment_image( int $attachment_id, string|int[] $size = 'medium', bool $icon = false, string|array $attr = '' );

Por padrão, a função wp_get_attachment_image() requer pelo menos um parâmetro, o ID do anexo. Ele serve como um identificador único para a imagem. A função então exibe a imagem em tamanho completo sem atributos HTML adicionais ou qualquer personalização.

Além disso, você pode incluir vários parâmetros adicionais para personalizar a saída da imagem, como o tamanho da imagem, a classe CSS, ou o texto alternativo:

$attachment_id

É necessário especificar o ID da imagem anexada que será exibida. Se o parâmetro estiver vazio ou definido como falso, a função não retornará nenhuma imagem.

$size

Um parâmetro opcional que define o tamanho da imagem que o WordPress vai exibir. Você pode especificar qualquer rótulo de tamanho de imagem registrado, por exemplo, miniatura, média, grande, ou um tamanho personalizado em pixels.

$icon

Outro parâmetro opcional que determina se a imagem deve ser tratada como um ícone. Se for configurado para true (verdadeiro), a função exibirá o ícone de anexo em vez da imagem real.

$attr

Este parâmetro permite que você adicione mais atributos à tag de imagem, como uma classe ou um estilo. Você pode passar uma matriz de pares de key-value (chave-valor) para adicionar os seguintes atributos:

• class (classe) – manipula a classe CSS da tag de imagem. Você pode adicionar várias classes criando uma lista separada por espaços.
• alt – define o texto alternativo da imagem. Um valor de atributo alt é importante para acessibilidade e para otimização de SEO no WordPress.
• srcset – especifica múltiplas fontes de imagem com diferentes resoluções, tamanhos ou proporções. O navegador escolherá automaticamente a melhor fonte com base na resolução da tela do dispositivo usado para acessar o site.
• sizes (tamanhos) – trabalha em conjunto com o atributo srcset. Especifica o tamanho da imagem exibida numa página com base no espaço disponível.
• loading (carregando) – determina como a imagem é carregada. Por exemplo, o valor padrão é lazy (preguiçoso) para ativar o lazy loading (link em inglês) ou carregamento preguiçoso.
• decoding (decodificação) – permite que você especifique como o navegador deve interpretar a imagem. Os valores válidos são async para decodificar a imagem assincronamente, sync para decodificar a imagem de maneira síncrona, ou auto (automático).

Como Usar o wp_get_attachment_image

Nesta seção, explicaremos como usar a função wp_get_attachment_image() de maneira eficaz. Verifique o código abaixo para ter mais informações:

<?php
if ( has_post_thumbnail() ) { // check if the post has a featured image
    $thumbnail_id = get_post_thumbnail_id(); // get the ID of the post thumbnail image
    $image = wp_get_attachment_image( $thumbnail_id, 'large' ); // get the HTML code for the post default thumbnail image
    echo $image; // display the image
}
?>

Aqui está o que fizemos com o código acima:

1. Usamos a função has_post_thumbnail() (link em inglês) para verificar se a postagem possui uma imagem em destaque.
2. Aplicamos get_post_thumbnail_id() (link em inglês) para obter o ID da imagem em destaque.
3. Usamos a função wp_get_attachment_image() para obter o código HTML da imagem.
4. Passamos a variável $thumbnail_id como o ID da imagem e large (grande) como o tamanho especificado.
5. Empregamos o echo para exibir o código HTML da imagem na página.

Lembre-se de que você pode substituir o parâmetro large por qualquer tamanho de imagem registrado.

Exemplos da Função do WordPress wp_get_attachment_image

Confira alguns casos de uso populares para a função wp_get_attachment_image() e entenda como ela pode ajudá-lo com seus projetos WordPress.

Exibir uma Imagem HTML Pronta para Uso

A maneira mais simples de testar a função wp_get_attachment_image() é passar um ID de anexo de imagem para ela.

<?php echo wp_get_attachment_image( 37);?>

Lembre-se de que não fornecemos nenhum tamanho específico de imagem neste exemplo. Portanto, a função recuperou a imagem em tamanho real com o ID de anexo 37.

No HTML, a saída ficará assim. O texto alternativo existirá se já tiver sido adicionado:

<img width="500" height="500" src="http://exemplo.com/wp-content/uploads/2023/03/imagem.jpg" class="attachment-full size-full" alt="Texto Alternativo">

Por padrão, o HTML define as imagens em tamanho real para 500 pixels de largura e 500 pixels de altura. No entanto, os valores reais de largura e altura em pixels podem variar dependendo das suas dimensões originais.

Usar um Tamanho Personalizado

Imagens personalizadas podem melhorar o desempenho do site, reduzindo os tempos de carregamento da página e aprimorando a aparência geral. Elas também garantem consistência em diferentes dispositivos e telas:

<?php echo wp_get_attachment_image( 37, [ 100,100 ], true); ?>

No HTML, a saída ficará assim:

<img width="40" height="40" src="http://exemplo.com.br/wp-content/uploads/2023/03/imagem.jpg" class="attachment-thumbnail size-thumbnail" alt="Descrição para o texto alternativo">

Neste caso, o segundo parâmetro da função wp_get_attachment_image() é uma matriz contendo a largura e a altura em pixels do tamanho da imagem solicitada. O terceiro parâmetro está definido como true (verdadeiro), o que significa que a função vai recortar a imagem para as dimensões exatas especificadas no array.

Veja como esse exemplo fica numa publicação online:

Exibir Todas as Imagens Associadas ao Post

Você pode exibir todas as imagens associadas a um ID de postagem específico. Fazer isso permite que você visualize todas as imagens relevantes sem navegar por toda a postagem.

<?php
$attachments = get_attached_media('image', get_the_ID());
if (!empty($attachments)) {
    foreach ($attachments as $image) {
        echo wp_get_attachment_image($image->ID, 'full');
    }
} 
?>

Neste exemplo, o código recupera todas as imagens anexadas ao post atual usando a função get_attached_media() e as percorre usando um loop foreach.

Para cada imagem, ele chama a função wp_get_attachment_image() para recuperar a versão em tamanho real da imagem com o ID do anexo.

Especificando Atributos Class, Alt, e Título de uma Imagem

Também é possível especificar a classe personalizada, o texto alternativo e os atributos de título para uma imagem. Tudo o que você precisa fazer é defini-los para uma variável Em nosso caso, é $custom:

<?php
$custom = [ 'class' => 'minha-classe', 'alt' => 'texto alternativo', 'title' => 'meu título' ];
echo wp_get_attachment_image( 37, 'medium', false, $custom );
?>

Neste exemplo, o quarto parâmetro é uma matriz contendo os atributos adicionais para a tag <img>.

A wp_get_attachment_image() é uma função versátil do WordPress que permite exibir facilmente imagens anexadas a posts ou páginas

Neste tutorial, falamos sobre a função  wp_get_attachment_image() e seus parâmetros. Também fornecemos alguns exemplo de uso dela para você testar no seu site WordPress.

Esperamos que você tenha achado este tutorial útil. Caso tenha alguma dúvida, deixe um comentário abaixo.