API auxiliar de imagem

A classe estática ImageHelper (em @microsoft/sp-image-helper) foi adicionada para permitir que os desenvolvedores do SPFx acessem o runtime:

• URLs de imagens em miniatura geradas automaticamente de páginas e documentos armazenados no Microsoft Office SharePoint Online
• URLs mais otimizadas para imagens armazenadas no Microsoft Office SharePoint Online

O método auxiliar ImageHelper.convertToImageUrl() uma URL para um ativo no Microsoft Office SharePoint Online, uma largura e uma altura opcional e executará operações do lado do cliente para tentar criar uma URL otimizada.

A URL resultante apontará para uma imagem próxima ao tamanho solicitado. A URL resultante também incluirá o uso de outros serviços de mídia e grafo do Microsoft Office SharePoint Online. Se disponível para o ativo solicitado, locais de CDN públicos ou privados para atender às imagens e miniaturas redimensionadas.

Observação

A API Auxiliar de Imagem foi introduzida na versão v1.14 da Estrutura do SharePoint como uma versão prévia do recurso de desenvolvedor.

Benefícios de usar esta API

• A imagem pode ser entregue mais rapidamente porque é potencialmente servida fora de um cache.
• A imagem será dimensionada adequadamente, pois a largura é necessária e a altura é opcional. Isso permite que os clientes armazenem imagens de alta resolução no Microsoft Office SharePoint Online, mas não paguem a penalidade de tempo de download quando essas imagens forem usadas.
• A URL de origem pode ser qualquer tipo de arquivo no Microsoft Office SharePoint Online em que uma miniatura pode ser gerada. Uma URL em miniatura de imagem seria retornada.

Explicado - ImageHelper.convertToImageUrl()

O convertToImageUrl() método estático aceita um único argumento do tipo IImageHelperRequest. Esse objeto tem duas propriedades necessárias, sourceUrl&widthe uma propriedade opcional height.

O processamento de imagem do lado do servidor do SharePoint tem uma lista de larguras de pontos de interrupção de resolução compatíveis, incluindo: 200, 400, 960, 1600, & 2560.

Embora você possa especificar qualquer largura para redimensionar a imagem, o Microsoft Office SharePoint Online escolherá o maior ponto de interrupção de resolução mais próximo. Por exemplo, se você especificar width: 250, a largura da imagem redimensionada será de 400 px.

Se você especificar a propriedade height, a largura não será ajustada para o ponto de interrupção mais próximo. Mas se a height propriedade for omitida, o SharePoint determinará automaticamente a altura da imagem redimensionada usando o ponto de interrupção de largura de altura & , mantendo a proporção da imagem.

Dica

A omissão height propriedade fornece a resposta mais rápida do Microsoft Office SharePoint Online

Usar a API auxiliar de imagem

Para usar a API auxiliar de imagem, primeiro você deve instalá-la em seu projeto:

npm install @microsoft/sp-image-helper

Em seguida, importe-o para o projeto em que você planeja usar a API:

import { ImageHelper, IImageHelperRequest } from "@microsoft/sp-image-helper";

Em seguida, use a API para obter uma imagem em miniatura de um arquivo existente no Microsoft Office SharePoint Online. Nesse caso, carregamos um arquivo do site da Galeria de Imagens do Microsoft News. Neste exemplo, estamos usando um arquivo com tamanho de 1,2 MB com uma resolução de 1920x1080, que não é um formato amigável para a Web ideal:

O arquivo existe na biblioteca padrão de Documentos site:

const originalImageUrl = '/sites/dev002/Shared%20Documents/ignite2021-m365-keynote.jpeg';

Use a API do Auxiliar de Imagem para redimensionar a imagem e usar o novo link para exibir a imagem otimizada redimensionada & :

const resizedImage = ImageHelper.convertToImageUrl(
  <IImageHelperRequest>{
    sourceUrl: originalImageUrl,
    width: 400
  }
);

this.domElement.innerHTML = `
  <div class="${ styles.helloWorld }">New Image</div>
  <div><img src="${ resizedImage }" /></div>
  <div>
    <div>Original image URL: <a href="${originalImageUrl}">${originalImageUrl}</a>
    <div>Resized image URL: <a href="${resizedImage}">${resizedImage}</a>
  </div>
`;

Essa imagem redimensionada tem apenas 30 kB de tamanho com uma resolução de 400x225, uma melhoria significativa no desempenho do usuário. Observe que a URL da imagem redimensionada difere da URL original que fornecemos ao método auxiliar.

Suporte à CDN privada

Para que as imagens sejam disponibilizadas a partir de uma CDN privada, os seguintes requisitos devem ser atendidos:

• O recurso CDN privado deve ser habilitado.
• O arquivo de origem deve estar disponível em uma origem para a CDN.
• O pré-processamento do lado do servidor do SharePoint deve saber que a propriedade da Web Part é uma propriedade de imagem.

Para conscientizar o processamento do lado do servidor do SharePoint sobre a propriedade da imagem, liste as propriedades em que as Urls de imagem são armazenadas na propriedade manifest.jsonimageLinkPropertyNames da Web Part:

{
  "id": "374a1893-9b4d-4c10-bbe3-9411d74093e9",
  "alias": "HelloWorldWebPart",
  "componentType": "WebPart",
  "supportedHosts": [ "SharePointWebPart" ],
  "imageLinkPropertyNames": [ "defaultBannerImage" ],
  "preconfiguredEntries": [{
    "title": { "default": "HelloWorld" },
    "properties: {
      "defaultBannerImage": "..."
    }
  }]
}

Isso permite que a lógica de regravação do lado do servidor do Microsoft Office SharePoint Online inclua o mapeamento desse arquivo para a CDN privada ao renderizar a página a ser enviada ao cliente.