Vorschau von Dateien in Ihrer App

Gilt für: Entwickler

Fügen Sie die Benutzeroberfläche für die Dateivorschau hinzu, damit Benutzer SharePoint Embedded-Inhalte untersuchen können, ohne Dateien herunterzuladen oder eine vollständige Office-Bearbeitungsumgebung zu öffnen.

Schließen Sie Office-Dateien aus Ihrer App öffnen ab , wenn Sie Office-Bearbeitung benötigen. Verwenden Sie diesen Artikel für einfache Vorschauversionen.

Grundlegendes zum Vorschauflow

Der Vorschauflow umfasst zwei Schritte:

  1. Rufen Sie den Microsoft Graph DriveItem Preview-Endpunkt auf.
  2. Verwenden Sie die zurückgegebene URL in einem iFrame oder einer neuen Browserseite.

Der Graph-Endpunkt lautet:

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

Dabei gilt:

  • {version} ist die Microsoft Graph-Version, z v1.0. B. .
  • {driveId} ist die Container-ID, die mit b!beginnt.
  • {itemId} ist die DriveItem-ID.

Die kanonische API-Referenz finden Sie unter Vorschau eines DriveItem.For the canonical API reference, see Preview a DriveItem.

Unterstützte Dateitypen kennen

Microsoft 365 unterstützt Vorschauversionen für viele Dateitypen, einschließlich gängiger Dokument-, Bild-, Video- und PDF-Formate.

Dazu gehören:

  • PDF-Dateien.
  • JPG- und andere Bilddateien.
  • MP4 und andere unterstützte Mediendateien.
  • Office-Dateien, die von Microsoft 365 Preview-Funktionen unterstützt werden.

Die aktuelle Liste finden Sie unter Unterstützte Dateitypen für die Vorschau von Dateien in OneDrive, SharePoint und Teams.

Hinweis

Die Unterstützung von Dateitypen kann je nach Dienstfunktion, Mandantenrichtlinie und Clienterfahrung variieren. Behandeln Sie Vorschaufehler immer ordnungsgemäß.

Native PDF-Anzeige

Die native PDF-Anzeige von SharePoint Embedded unterstützt das Suchen in der Datei, dasAnzeigen von Kommentaren und Kurznotizen , die in die Datei eingebettet sind, und das Drucken (hinzugefügt vom März 2026). Diese Funktionen sind über die api driveItem: previewin den Beta- und v1.0-Endpunkten von Microsoft Graph verfügbar.

Verbessern der PDF-Vorschau mit Abfrageparametern

Verbessern Sie die SharePoint Embedded PDF-Vorschau, indem Sie Abfrageparameter an die Eigenschaft von webUrl driveItem anfügen. Rufen Sie zum Abrufen webUrldie get-API driveItem auf, z. B GET /drives/{drive-id}/items/{item-id}?$select=webUrl. .

Übergeben Sie Parameter als JSON-codierte embed Abfragezeichenfolge. Sie können einen oder mehrere Parameter in dasselbe Objekt einschließen.

<webUrl>?&embed={"<param1>":<value>,"<param2>":<value>}
Parameter Effekt
mpp Aktiviert das Drucksymbol und STRG+P-Druck. Beispiel: <webUrl>?&embed={"mpp":true}.
mpsn Zeigt Den Inhalt von Kurznotizen an, wenn die PDF-Datei Kurznotizen enthält. Beispiel: <webUrl>?&embed={"mpsn":true}.

Voraussetzungen

Stellen Sie vor dem Erstellen von Vorschauversionen Folgendes sicher:

  • Die Datei wird in einem SharePoint Embedded-Container gespeichert.
  • Ihre App kennt die Container-ID und die DriveItem-ID.
  • Ihre App kann ein Microsoft Graph-Token abrufen.
  • Der Aufrufer verfügt über die Berechtigung zum Lesen der Datei.
  • Der Dateityp wird für die Vorschau unterstützt.
  • Ihre Benutzeroberfläche kann einen iFrame hosten oder eine neue Seite öffnen.

Rufen Sie den Vorschauendpunkt von Ihrer Dienstebene aus auf.

Verwenden Sie dieses C#-SDK-Muster:

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

Die Antwort enthält Url-Vorschauinformationen:

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

Verwenden Sie getUrl , wenn verfügbar.

Achtung

getUrl enthält derzeit ein verschlüsseltes Token, das nur mit Ihrer Anwendung verwendet werden kann. Dieses Verhalten kann sich ändern.

Entfernen des Vorschaubanners

Fügen Sie nb=true der abgerufenen URL hinzu, um das Banner oben zu entfernen.

Beispiel:

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

Verwenden Sie dies nur, wenn es Ihren Benutzererfahrungs- und Complianceanforderungen entspricht.

Einbetten der Vorschau in einen iframe

Erstellen Sie eine App-Seite, die die Vorschau-URL hostet.

Beispielform:

<!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>

Stellen Sie in der Produktion auch Folgendes bereit:

  • Ein beschreibender iframe-Titel.

  • Dynamische Größenanpassung.

  • Ladezustände.

  • Fehlerzustände.

  • Eine Fallback-Download- oder Open-Aktion.

Dynamisches Laden von Vorschauversionen

Rufen Sie Microsoft Graph nicht direkt aus einem Browserskript auf, wenn dadurch CORS-Probleme erstellt oder Token verfügbar gemacht werden.

Verwenden Sie einen serverseitigen Endpunkt, der:

  1. Authentifiziert den Benutzer.
  2. Überprüft den Zugriff auf die angeforderte Datei.
  3. Ruft ein Graphtoken ab.
  4. Ruft den DriveItem-Vorschauendpunkt auf.
  5. Gibt die Vorschau-URL an den Client zurück.

Verwenden Sie dieses serverseitige Muster:

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

Anschließend kann der Client die URL anfordern und die iframe-Quelle festlegen.

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";
}

Entwurfsvorschau-UX

Eine gute Vorschau-UX sollte:

  • Zeigen Sie den Dateinamen an.
  • Zeigt einen Ladeindikator an.
  • Reservieren Sie genügend Platz für den iframe.
  • Stellen Sie eine Open-in-Office-Aktion für Office-Dateien bereit.
  • Stellen Sie eine Downloadaktion bereit, wenn die Vorschau nicht verfügbar ist.
  • Barrierefreiheit auf der Tastatur beibehalten.
  • Vermeiden Sie das Überfangen des Fokus innerhalb des Vorschauframes.
  • Erläutern Sie Fehler in benutzerfreundlicher Sprache.

Behandeln von Vorschaufehlern

Fehler Handhabung
Nicht unterstützter Dateityp Zeigen Sie stattdessen eine Download- oder Öffnen-Aktion an.
Fehlende Berechtigung Bitten Sie den Benutzer, zugriff anzufordern oder sich erneut anzumelden.
Abgelaufene URL Fordern Sie eine neue Vorschau-URL an.
CORS-Fehler Verschieben Sie den Graph-Aufruf an Ihren serverseitigen Endpunkt.
Datei gelöscht. Aktualisieren Sie die Dateiliste, und entfernen Sie veraltete Auswahlen.
Dienstfehler Wiederholen Sie es einmal, und zeigen Sie dann einen stabilen Fallback an.

Wichtig

Speichern Sie Vorschau-URLs nicht als dauerhafte Bezeichner zwischen. Speichern Sie die Container-ID und die DriveItem-ID, und erstellen Sie dann bei Bedarf eine neue Vorschau-URL.

Sichere Vorschauanforderungen

Behandeln Sie die Vorschau als Lesevorgang für geschützte Inhalte.

Ihr Dienst sollte:

  1. Überprüfen Sie den angemeldeten Benutzer- oder Dienstkontext.
  2. Vergewissern Sie sich, dass der Aufrufer den Containerinhalt lesen kann.
  3. Vergewissern Sie sich, dass das angeforderte Element zum erwarteten Container gehört.
  4. Vermeiden Sie das Verfügbarmachen von Graphtoken für den Browser.
  5. Vermeiden Sie die Protokollierung von Vorschau-URLs, die vertrauliche Token enthalten.
  6. Ablaufen von App-seitigen Vorschausitzungen, wenn sich der Benutzer abmeldet.

Überprüfen der Vorschauumgebung

Testen mit mehreren Dateitypen und Benutzern:

  1. Laden Sie eine PDF-Datei hoch.
  2. Laden Sie eine Bilddatei hoch.
  3. Laden Sie eine Office-Datei hoch.
  4. Erstellen Sie eine Vorschau-URL für jede Datei.
  5. Rendern Sie jede Vorschau in einem iframe.
  6. Testen sie einen Benutzer mit Lesezugriff.
  7. Testen sie einen Benutzer ohne Zugriff.
  8. Löschen Sie eine Datei, und vergewissern Sie sich, dass der Fehler behandelt wurde.
  9. Aktualisieren Sie eine abgelaufene Vorschau-URL.
  10. Vergewissern Sie sich, dass die Fallbackaktion funktioniert.

Herstellen einer Verbindung mit der nächsten Buildaufgabe

Nachdem die Vorschauversion funktioniert, fügen Sie Ermittlungsfunktionen hinzu, damit Benutzer Inhalte über Container und Dateien hinweg finden können.

Fahren Sie mit Durchsuchen von Containern und Dateien fort.

Nächste Schritte

  • Last updated on