イメージ ヘルパー API

ImageHelper 静的クラス (@microsoft/sp-image-helper) が追加され、SPFx 開発者は次のランタイムにアクセスできます。

  • SharePoint に保存されているページとドキュメントの自動生成されたサムネイル画像の URL
  • SharePoint に保存されている画像へのより最適化された URL

ヘルパー メソッド ImageHelper.convertToImageUrl() は、SharePoint 上のアセットへの URL、幅、およびオプションの高さを取得し、クライアント側の操作を実行して、最適化された URL を作成しようとします。

結果の URL は、要求されたサイズに近い画像を指します。 結果の URL には、他の SharePoint メディアおよびグラフ サービスの使用も含まれます。 サイズ変更された画像とサムネイルを提供するために、要求されたアセット、パブリックまたはプライベート CDN ロケーションで利用可能な場合。

注:

イメージ ヘルパー API は、開発者向けプレビュー機能として、SharePoint Framework v1.14 リリースで導入されました。

この API を使用する利点

  • 画像はキャッシュから提供される可能性があるため、より速く配信される場合があります。
  • 幅は必須で、高さはオプションであるため、画像のサイズは適切になります。 これにより、顧客は高解像度の画像を SharePoint に保存できますが、それらの画像を使用するときにダウンロード時間のペナルティを支払う必要はありません。
  • ソース URL は、サムネイルを生成できる SharePoint 内の任意のファイルタイプである可能性があります。 次に、画像のサムネイル URL が返されます。

説明 - ImageHelper.convertToImageUrl()

convertToImageUrl() 静的メソッドは、種類 IImageHelperRequest の単一の引数を受け入れます。 このオブジェクトには、2 つの必須プロパティ、sourceUrl&width、および 1 つのオプション プロパティ height があります。

SharePoint のサーバー側画像処理には、200、400、960、1600 & 、2560 など、サポートされている解像度ブレークポイントの幅の一覧があります。

画像のサイズを変更する幅を指定できますが、SharePoint は最も近い最大の解像度ブレークポイントを選択します。 たとえば、width: 250 を指定すると、サイズ変更された画像の幅は 400 ピクセルになります。

オプションの height プロパティを指定した場合、幅は最も近いブレークポイントに調整されません。 ただし、 プロパティを height 省略すると、SharePoint は、イメージの縦横比を維持しながら、高さの幅ブレークポイントを使用してサイズ変更されたイメージの高さを & 自動的に決定します。

ヒント

height プロパティを省略すると、SharePoint からの応答が最も速くなります。

イメージ ヘルパー API の使用

イメージ ヘルパー API を使用するには、最初にそれをプロジェクトにインストールする必要があります。

npm install @microsoft/sp-image-helper

次に、API を使用する予定のプロジェクトにインポートします。

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

次に、API を使用して、SharePoint 内の既存のファイルのサムネイル画像を取得します。 この場合、Microsoft ニュース イメージ ギャラリー サイトからファイルをアップロードしました。 この例では、サイズが 1.2 MB、解像度が 1920x1080 のファイルを使用しています。これは理想的な Web フレンドリ形式ではありません。

元の画像の詳細パネルのスクリーンショット。

このファイルは、当サイトの既定のドキュメント ライブラリにあります。

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

イメージ ヘルパー API を使用してイメージのサイズを変更し、新しいリンクを使用してサイズ変更された & 最適化されたイメージを表示します。

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

サイズ変更された画像のスクリーンショット。

このサイズ変更された画像のサイズはわずか 30 kB で、解像度は 400x225 であり、ユーザーのパフォーマンスが大幅に向上しています。 サイズ変更された画像の URL は、ヘルパー メソッドを提供した元の URL とは異なることに注意してください。

プライベート CDN サポート

プライベート CDN から画像を提供できるようにするには、次の要件を満たす必要があります。

  • プライベート CDN 機能を有効にする必要があります。
  • ソース ファイルは、CDN のオリジン内で利用可能である必要があります。
  • SharePoint のサーバー側の前処理では、Web パーツのプロパティが画像のプロパティであることを認識している必要があります。

SharePoint のサーバー側処理で image プロパティを認識するには、Web パーツの manifest.jsonimageLinkPropertyNames プロパティにイメージ URL が格納されているプロパティを一覧表示します。

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

これにより、SharePoint のサーバー側の書き換えロジックに、クライアントに送信するページをレンダリングするときに、そのファイルのプライベート CDN へのマッピングを含めることができます。