Pular para o conteúdo principal

O que são mídias?

Nas seções anteriores, descrevemos as diversas maneiras na qual o conteúdo é criado, gerenciado e organizado dentro do Starlight. Porém, esse conteúdo não é meramente textual - ele também é algo visual por meio das Mídias, que são arquivos enviados para o Starlight que podem ser usados nos conteúdos da sua aplicação como imagens.

Arquivos suportados​

Atualmente o Starlight dá suporte a 4 tipos de arquivos: .jpg, .png, .pdf e .svg. JPGs e PNGs são simplesmente arquivos de imagem comuns (de "funcionamento interno" diferente) formados por pixels, PDFs são arquivos que representam documentos (que podem ter várias páginas) e SVGs são arquivos de imagens "vetorizadas" - isto é, são compostas de formas, linhas, curvas, etc. e podem ter seu tamanho modificado sem perda de qualidade.

Variações​

Quando você envia uma mídia para o Starlight, ele faz certos "processamentos" nela com o intuito de otimizá-la para uma utilização ideal na sua aplicação. Esses processos geram até 5 variações do arquivo enviado, dependendo do seu tipo:

  • Original (todos os tipos): Arquivo original da imagem com suas dimensões e tamanho (de arquivo) originais.
  • Otimizado (JPG, PNG): Imagem redimensionada a um máximo de 2000 pixels de altura ou largura, também sendo comprimida para ser mais leve do que o arquivo original (otimizada, como o nome sugere).
  • Grande (JPG, PNG): Imagem redimensionada a um máximo de 1200 pixels de altura ou largura.
  • Médio (JPG, PNG, PDF): Imagem redimensionada a um máximo de 600 pixels de altura ou largura. No caso de PDFs, será uma imagem da primeira página do arquivo.
  • Miniatura (JPG, PNG, PDF): Imagem redimensionada a um máximo de 200 pixels de altura ou largura. No caso de PDFs, será uma imagem da primeira página do arquivo.
Sobre o redimensionamento

Quando uma imagem é redimensionada, isso significa que a sua maior dimensão (dentre altura e largura) será redimensionada ao valor máximo daquela variação (2000, 1200, 600 ou 200 pixels) e a sua menor dimensão será redimensionada proporcionalmente. Por exemplo, uma imagem de 500 x 250 pixels terá uma miniatura (com máximo de 200 pixels) de dimensão 200 x 100.

A tabela abaixo resume a "compatibilidade" de cada variação com cada tipo de arquivo, além de mencionar a "chave" (identificador único em inglês) daquela variação na API do Starlight:

VariaçãoJPGPNGPDFSVGNome na API
Original✔️✔️✔️✔️original
Otimizado✔️✔️❌❌optimized
Grande✔️✔️❌❌large
Médio✔️✔️✔️❌medium
Miniatura✔️✔️✔️❌thumbnail

Ao requisitar um conteúdo com imagens (entradas, Seções, coleções, etc.), cada imagem terá um array (files) com as variações existentes daquela imagem e as informações daquela variação. Cada variação será identificada pelo nome na API (mostrado na tabela acima).

Como escolher uma variação​

Qual variação você vai utilizar na sua aplicação depende muito do intuito daquela imagem, e não existe uma maneira 100% correta de definir o que você vai usar. O ideal é que você use a variação mais leve possível que condiz com a utilização daquela imagem, para que o site fique menos pesado e o seu usuário tenha de carregar menos conteúdo.

Digamos que você tenha um blog com uma lista de postagens e as páginas da postagem em si, e que cada postagem tenha uma imagem "principal" que será utilizada junto ao seu título. Na lista de postagens, que mostrará apenas a imagem principal e o nome da postagem (com o intuito de poder listar várias na mesma página), o ideal seria utilizar a variação Médio ou Miniatura, dependendo do tamanho de cada item da lista. Já na página da postagem em si, que terá a imagem principal mostrada com destaque no topo da página, o ideal seria mostrar a variação Otimizado, caso exista.

Componentes do SDK​

Tanto o SDK do React quanto o do Next têm componentes com suporte a imagens que selecionam a variação automaticamente de acordo com a largura da tela do usuário. No do React temos o ResponsiveImage e no do Next temos o Image. Diferente do ResponsiveImage, que é um componente "independente", o Image é baseado no next/image do próprio Next.js, sendo apenas um wrapper ao redor deste que adiciona suporte a imagens do Starlight. Para saber mais, basta visitar a documentação do next/image.