API Assistant d’image

La classe statique ImageHelper (dans @microsoft/sp-image-helper) a été ajoutée pour permettre aux développeurs SPFx d’accéder au runtime :

• URL des images miniatures générées automatiquement des pages et des documents stockés dans SharePoint
• Autres URL optimisées pour les images stockées dans SharePoint

La méthode de l’assistant ImageHelper.convertToImageUrl() envoie une URL vers une ressources sur SharePoint, ainsi qu’une largeur et une hauteur facultative et effectue des opérations côté client pour essayer de créer une URL optimisée.

L’URL qui en découle montre une image proche de la taille demandée. L’URL qui en résulte inclut également l’utilisation d’autres multimédias SharePoint et de services graphiques. Si disponibles pour la ressource demandée, les emplacements de CDN publics ou privés pour servir les images et les miniatures redimensionnées.

Remarque

L'API Image Helper a été introduite dans la version SharePoint Framework v1.14 en tant que fonctionnalité de l'aperçu pour développeurs.

Avantages de l’utilisation de cette API

• L’image peut être remise plus rapidement, car elle est potentiellement purgée d’un cache.
• L’image est redimensionnée correctement, car la largeur est requise et la hauteur est facultative. Cela permet aux clients de stocker des images haute résolution dans SharePoint et ne payer aucune pénalité de temps de téléchargement lorsque ces images sont utilisées.
• L’URL source peut être n’importe quel type de fichier SharePoint dans lequel une miniature peut être générée. Une URL de miniature d’image est alors renvoyée.

Expliqué – ImageHelper.convertToImageUrl()

La méthode statique convertToImageUrl() accepte un seul argument de type IImageHelperRequest. Cet objet possède deux propriétés obligatoires, sourceUrl&width et une propriété facultative height.

Le traitement d’images côté serveur de SharePoint a une liste de largeurs de points d’arrêt de résolution qu’il prend en charge, notamment : 200, 400, 960, 1600, & 2560.

Bien que vous puissiez spécifier n’importe quelle largeur de redimensionnement de l’image, SharePoint choisira le point d’arrêt de résolution le plus proche. Par exemple, si vous spécifiez width: 250, la largeur de l’image redimensionnée sera de 400 px.

Si vous spécifiez la propriété height facultative, la largeur n'est pas ajustée au point d'arrêt le plus proche. Toutefois, si la height propriété est omise, SharePoint détermine automatiquement la hauteur de l’image redimensionnée à l’aide du point d’arrêt de largeur de hauteur & tout en conservant les proportions de l’image.

Conseil

L’omission de la propriété height fournit une réponse la plus rapide de SharePoint

Utiliser l’API Assistant d’image

Pour utiliser l’API Assistant d’image, vous devez d’abord l’installer dans votre projet :

npm install @microsoft/sp-image-helper

Ensuite, importez-le dans votre projet où vous prévoyez d’utiliser l’API :

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

Ensuite, utilisez l’API pour obtenir l’image miniature d’un fichier existant dans SharePoint. Dans ce cas, nous avons téléchargé un fichier à partir du site Bibliothèque d'images de Microsoft News. Dans cet exemple, nous utilisons un fichier d'une taille de 1,2 Mo avec une résolution de 1 920 x 1 080, ce qui n'est pas un format idéal pour le Web :

Le fichier existe dans la bibliothèque Documents par défaut de notre site :

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

Utilisez l’API Image Helper pour redimensionner l’image et utilisez le nouveau lien pour afficher l’image optimisée redimensionnée & :

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>
`;

La taille de cette image redimensionnée n’est que de 30 Ko avec une résolution de 400 x 225, ce qui améliore sensiblement les performances de l’utilisateur. Notez que l’URL de l’image redimensionnée diffère de l’URL d’origine que nous avons fournie à la méthode de l’assistant.

Prise en charge de CDN privé

Pour que les images soient disponibles pour être servies à partir d’un CDN privé, les conditions suivantes doivent être remplies :

• La fonctionnalité CDN privé doit être activée.
• Le fichier source doit être disponible dans une origine du CDN.
• Le prétraitement côté serveur de SharePoint doit savoir que la propriété du composant WebPart est une propriété d'image.

Pour que le traitement côté serveur de SharePoint prenne en compte la propriété image, répertoriez les propriétés dans lesquelles les URL d’image sont stockées dans la propriété manifest.jsonimageLinkPropertyNames du composant WebPart :

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

Cela permet à la logique de réécriture côté serveur de SharePoint d’inclure le mappage de ce fichier au CDN privé lors du rendu de la page à envoyer au client.