图像帮助程序 API

添加了 @microsoft/sp-image-helper) 中的 ImageHelper 静态类 (，以允许 SPFx 开发人员在运行时访问：

• 存储在 SharePoint 中的页面和文档的自动生成缩略图图像的 Url
• 存储在 SharePoint 中的图像的更优化 Url

帮助程序方法 ImageHelper.convertToImageUrl() 采用指向 SharePoint 上资产的 Url、宽度和可选高度，并将执行客户端操作以尝试创建优化的 Url。

生成的 Url 将指向接近请求大小的图像。 生成的 Url 还将包括使用其他 SharePoint 媒体和图形服务。 如果可用于请求的资产、公共或私有 CDN 位置，以提供调整大小的图像和缩略图。

注意

图像帮助程序 API 是作为一项开发人员预览功能引入到 SharePoint 框架 v1.14 版本中的。

使用此 API 的好处

• 图像可能会更快地传递，因为它可能是在缓存之外提供的。
• 图像大小将相应调整，因为宽度是必需的，高度是可选的。 这允许客户在 SharePoint 中存储高分辨率图像，但在使用这些图像时不会延长下载时间。
• 源 Url 可能是 SharePoint 中可以生成缩略图的任何文件类型。 然后返回图像缩略图 Url。

说明 - ImageHelper.convertToImageUrl()

convertToImageUrl() 静态方法接受类型为 IImageHelperRequest 的单个参数。 此对象有两个必需属性 sourceUrl&width 和一个可选属性 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，这不是理想的 We 友好格式：

此文件存在于网站的默认文档库中：

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 的服务器端处理感知图像属性，请列出在 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 的映射。