API вспомогательного приложения для изображений
Добавлен статический класс ImageHelper (в @microsoft/sp-image-helper), чтобы разрешить разработчикам SPFx доступ к:
- URL-адреса автоматически созданных эскизов страниц и документов, хранящихся в SharePoint
- Более оптимизированные URL-адреса изображений, хранящихся в SharePoint
Метод вспомогательного приложения ImageHelper.convertToImageUrl()
принимает URL-адрес актива в SharePoint, ширину и необязательную высоту и выполняет операции на стороне клиента, чтобы попытаться создать оптимизированный URL-адрес.
В результате URL-адрес будет указывать на изображение, близкое к нужному размеру. Получившийся URL-адрес также будет включать использование других служб мультимедиа и графиков SharePoint. Общедоступные или частные расположения в CDN будут обслуживать изображения и эскизы с измененными размерами, если это доступно для запрашиваемого актива.
Примечание.
API вспомогательного приложения для изображений был представлен в выпуске SharePoint Framework версии 1.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 News. В этом примере мы используем файл размером 1,2 МБ с разрешением 1920x1080. Это не идеальный формат для отображения в Интернете.
Файл существует в стандартной библиотеке Документы нашего сайта:
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 КБ и имеет разрешение 400x225, что значительно улучшило производительность для пользователя. Обратите внимание, что URL-адрес изображения с измененным размером отличается от исходного URL-адреса, который мы предоставили в методе помощника.
Поддержка частных CDN
Чтобы изображения были доступны для частного CDN, должны быть выполнены следующие требования.
- Должна быть включена функция частной сети CDN.
- Исходный файл должен быть доступен в рамках источника в сети CDN.
- Предварительной серверной обработке SharePoint должно быть известно, что свойство веб-части является свойством изображения.
Чтобы серверная обработка SharePoint учитывала свойство image, перечислите свойства, в которых URL-адреса изображений хранятся в свойстве manifest.jsonimageLinkPropertyNames
веб-части:
{
"id": "374a1893-9b4d-4c10-bbe3-9411d74093e9",
"alias": "HelloWorldWebPart",
"componentType": "WebPart",
"supportedHosts": [ "SharePointWebPart" ],
"imageLinkPropertyNames": [ "defaultBannerImage" ],
"preconfiguredEntries": [{
"title": { "default": "HelloWorld" },
"properties: {
"defaultBannerImage": "..."
}
}]
}
Это позволяет логике перезаписи на стороне сервера в SharePoint включить сопоставление этого файла с частной CDN при отрисовке страницы, которая будет отправлена клиенту.