Предварительный просмотр файлов в приложении

Применимо к: Разработчик

Добавьте возможности предварительного просмотра файлов, чтобы пользователи могли просматривать содержимое SharePoint Embedded, не скачивая файлы или не открывая полный интерфейс редактирования Office.

Завершите открытие файлов Office из приложения при необходимости редактирования Office. Используйте эту статью для упрощенных предварительных версий.

Общие сведения о потоке предварительной версии

Поток предварительного просмотра состоит из двух этапов:

Вызовите конечную точку Предварительной версии Microsoft Graph DriveItem.
Используйте возвращенный URL-адрес на странице iframe или новой страницы браузера.

Конечная точка Graph:

POST https://graph.microsoft.com/{version}/drives/{driveId}/items/{itemId}/preview

Где:

{version} — это версия Microsoft Graph, например v1.0.
{driveId} — это идентификатор контейнера, начинающийся с b!.
{itemId} — идентификатор DriveItem.

Справочник по каноническим API см. в разделе Предварительный просмотр DriveItem.

Сведения о поддерживаемых типах файлов

Microsoft 365 поддерживает предварительные версии для многих типов файлов, включая распространенные форматы документов, изображений, видео и PDF.

Вот некоторые примеры.

PDF-файлы.
JPG и другие файлы изображений.
MP4 и другие поддерживаемые файлы мультимедиа.
Файлы Office, поддерживаемые предварительными версиями Microsoft 365.

Текущий список см . в статье Типы файлов, поддерживаемые для предварительного просмотра файлов в OneDrive, SharePoint и Teams.

Примечание.

Поддержка типов файлов может отличаться в зависимости от возможностей службы, политики клиента и взаимодействия с клиентом. Всегда корректно обрабатывайте сбои предварительного просмотра.

Просмотр pdf-файлов в собственном коде

Встроенный интерфейс просмотра PDF-файлов SharePoint Embedded поддерживает поиск в файле, просмотр комментариев и заметок , внедренных в файл, а также печать (добавлено в марте 2026 г.). Эти возможности доступны через API предварительной версии driveItem: в бета-версии и конечных точках Microsoft Graph версии 1.0.

Расширение средства предварительного просмотра PDF с помощью параметров запроса

Улучшайте средство предварительного просмотра PDF-файлов SharePoint Embedded, добавив параметры запроса в свойство driveItem webUrl . Чтобы получить webUrl, вызовите API GET driveItem, например GET /drives/{drive-id}/items/{item-id}?$select=webUrl.

Передайте параметры в виде строки запроса в кодировке embed JSON. В один и тот же объект можно включить один или несколько параметров.

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}

Параметр	Эффект
`mpp`	Включает значок печати и печать ctrl+P. Например, `<webUrl>?&embed={"mpp":true}`.
`mpsn`	Отображает содержимое заметок, если pdf-файл содержит заметки. Например, `<webUrl>?&embed={"mpsn":true}`.

Предварительные условия

Перед созданием предварительных версий убедитесь, что:

Файл хранится в контейнере SharePoint Embedded.
Вашему приложению известен идентификатор контейнера и идентификатор DriveItem.
Приложение может получить маркер Microsoft Graph.
Вызывающий объект имеет разрешение на чтение файла.
Тип файла поддерживается для предварительной версии.
В пользовательском интерфейсе можно разместить iframe или открыть новую страницу.

Создание ссылки на предварительный просмотр

Вызовите конечную точку предварительного просмотра из уровня служб.

Используйте следующий шаблон пакета SDK для C#:

ItemPreviewInfo preview = await graphServiceClient.Drives[driveId].Items[itemId]
    .Preview
    .PostAsync(null);

Ответ содержит сведения о ПРЕДВАРИТЕЛЬНОМ URL-адресе:

{
  "getUrl": "https://www.onedrive.com/embed?foo=bar&bar=baz",
  "postParameters": "param1=value&param2=another%20value",
  "postUrl": "https://www.onedrive.com/embed_by_post"
}

Используйте, getUrl если доступно.

Предостережение

getUrl в настоящее время содержит зашифрованный маркер, который можно использовать только с приложением. Это поведение может измениться.

Добавьте nb=true к полученному URL-адресу, чтобы удалить баннер вверху.

Пример:

https://contoso.sharepoint.com/restOfUrl/embed.aspx?param1=value&nb=true

Используйте его только в том случае, если он соответствует вашим требованиям к пользовательскому интерфейсу и соответствию требованиям.

Внедрение предварительной версии в iframe

Создайте страницу приложения, на котором размещен URL-адрес предварительного просмотра.

Пример фигуры:

<!DOCTYPE html>
<html>
  <body>
    <h2>Preview</h2>
    <p>Preview of {file name}:</p>
    <iframe src="{preview URL}" height="200" width="300" id="preview" title="File preview"></iframe>
  </body>
</html>

В рабочей среде также предоставляется:

Описательное название iframe.
Адаптивный размер.
Состояния загрузки.
Состояния ошибок.
Резервное скачивание или открытие действия.

Динамическая загрузка предварительных версий

Не вызывайте Microsoft Graph напрямую из сценария браузера, если он создает проблемы с общим доступом к ресурсам между источниками (CORS) или предоставляет маркеры.

Используйте серверную конечную точку, которая:

Выполняет проверку подлинности пользователя.
Проверяет доступ к запрошенным файлам.
Получает токен Graph.
Вызывает конечную точку предварительной версии DriveItem.
Возвращает url-адрес предварительного просмотра для клиента.

Используйте следующий шаблон на стороне сервера:

[HttpGet]
[AuthorizeForScopes(Scopes = new string[] { "Files.Read.All" })]
public async Task<ActionResult<string>> GetPreviewUrl(string driveId, string itemId)
{
  return url + "&nb=true";
}

Затем клиент может запросить URL-адрес и задать источник iframe.

async function preview(driveId, itemId) {
  const url = `/GetPreviewUrl?driveId=${driveId}&itemId=${itemId}`;
  const response = await fetch(url, {
      credentials: 'include',
  }).then(response => response.text());
  document.getElementById('preview').src = response + "&nb=true";
}

Разработка интерфейса предварительной версии

Хороший предварительный просмотр должен:

Отображение имени файла.
Отображение индикатора загрузки.
Зарезервируйте достаточно места для iframe.
Предоставьте действие "Открыть в Office" для файлов Office.
Предоставьте действие скачивания, если предварительная версия недоступна.
Сохраните специальные возможности клавиатуры.
Избегайте перехвата фокуса внутри кадра предварительного просмотра.
Объяснять ошибки на понятном языке.

Обработка ошибок предварительного просмотра

Сбоя	Обработки
Неподдерживаемый тип файла	Вместо этого покажите действие скачивания или открытия.
Отсутствует разрешение	Попросите пользователя запросить доступ или войти еще раз.
URL-адрес с истекшим сроком действия	Запросите новый URL-адрес предварительной версии.
Ошибка CORS	Переместите вызов Graph в конечную точку на стороне сервера.
Файл удален	Обновите список файлов и удалите устаревшие выбранные фрагменты.
Ошибка службы	Повторите попытку один раз, а затем отобразите стабильный резервный вариант.

Важно!

Не кэшируйте URL-адреса предварительного просмотра в качестве устойчивых идентификаторов. Сохраните идентификатор контейнера и идентификатор DriveItem, а затем при необходимости создайте новый URL-адрес предварительной версии.

Запросы безопасной предварительной версии

Рассматривайте предварительный просмотр как операцию чтения для защищенного содержимого.

Ваша служба должна:

Проверьте контекст вошедшего пользователя или службы.
Убедитесь, что вызывающий объект может считывать содержимое контейнера.
Убедитесь, что запрошенный элемент принадлежит ожидаемому контейнеру.
Избегайте предоставления маркеров Graph браузеру.
Избегайте ведения журнала URL-адресов предварительного просмотра, включающих конфиденциальные маркеры.
Истекает срок действия сеансов предварительной версии приложения при выходе пользователя.

Проверка предварительной версии

Тестирование с несколькими типами файлов и пользователями:

Отправьте PDF-файл.
Отправьте файл изображения.
Отправьте файл Office.
Создайте URL-адрес предварительного просмотра для каждого файла.
Отрисовка каждого предварительного просмотра в iframe.
Протестируйте пользователя с доступом на чтение.
Протестируйте пользователя без доступа.
Удалите файл и подтвердите, что ошибка обработана.
Обновите URL-адрес предварительной версии с истекшим сроком действия.
Убедитесь, что резервное действие работает.

Подключение к следующей задаче сборки

После завершения предварительной версии добавьте возможности обнаружения, чтобы пользователи могли находить содержимое в контейнерах и файлах.

Перейдите к статье Поиск контейнеров и файлов.

Дальнейшие действия

Поиск контейнеров и файлов

Last updated on 2026-07-15