Einbettbarer Datei-Explorer

  • Nicht definierter Typ

Dieses Dokument ist die funktionale und technische Referenz für den File Explorer von RestFrontage. Es richtet sich an Nutzer, immersive Administratoren und Integratoren.

Explorer ermöglicht es, Ordner zu durchsuchen und Dateien von:

  • der Immersiven Datenbank (Media.Content) ;
  • eine serververwaltete Datei (Media.Handle) ;
  • ein Azure-Blob-Container, der auf einem Immersiver-Ordner montiert ist (Folder.VirtualFolderPath).

1. Zugang zum Explore

Die Seite ist über den RestFrontage-Server verfügbar:

/Business/Resources/Explorer

1.1 Standard-Multiroot-Modus

Ohne RootFolderIdentifier, der Explorer zeigt alle Immersiv-Ordner an, die du hast ParentIdentifier ist nicht:

https://mon-serveur/Business/Resources/Explorer

Diese Ordner erscheinen im Inhaltsbereich und im Ordner. Der Eingang Wurzel breadcrumb ermöglicht es uns, zu diesem Überblick zurückzukehren.

A RootFolderIdentifier abwesend, null oder negativ aktiviert diesen Multi-Root-Modus.

1.2 Begrenze Explorer auf einen Baum

Um nur eine Datei und ihre Nachfolger darzustellen:

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=131

Der Server verweigert das Surfen in einem Ordner, der nicht von dieser Wurzel abstammt.

1.3 Kioskanzeige

Der Kiosk-Modus verbirgt die übliche RestFrontage-Oberfläche:

https://mon-serveur/Business/Resources/Explorer?Render=Kiosk&RootFolderIdentifier=131

Wert Kiosk ist nicht groß- und kleinschreibungssensitiv. Jeder andere Wert behält das übliche Layout bei.

2. Verstehen und nutzen Sie die Schnittstelle

Die Benutzeroberfläche hat fünf Bereiche:

  1. Kommandoleiste : Erstellen Sie, verändern, löschen und aktualisieren Sie gemäß der Konfiguration und den Rechten des Benutzers.
  2. Ordner —Der Immersive und Blob-Baum auf der linken Seite großer Bildschirme.
  3. Breadcrumb Trail : Der Pfad des aktuellen Ordners und die Pfeiltaste, um zum Elternteil zurückzukehren.
  4. Inhalt : Unterordner- und Dateikarten.
  5. Status : lädt, möglicher Fehler und Knopf zum erneuten Versuch.

Um sich zurechtzufinden:

  • Wähle einen Ordner in der Baumansicht aus.
  • Wähle eine Ordnerkarte aus.
  • Wähle eine Etappe des Breadcrumb Trail aus;
  • Benutze die Pfeiltaste Vorrücken um den Elternteil zu erreichen;
  • Verwendung Wurzel um zur Multi-Root-Ansicht zurückzukehren, wenn keine Wurzel auferlegt ist.

Die Standardseite wird konfiguriert DownloadOnClick: true : Ein Klicken auf eine Datei ruft den Auswahl-Rückruf auf und öffnet oder lädt dann die Datei herunter. Erkannte Bilder werden als Vorschaubilder angezeigt.

Auf einem Bildschirm mit 720 px oder weniger ist das linke Panel nach unten geklappt. Der Knopf Ordner öffnet oder schließt sie. Die Befehlsleiste bleibt auf einer einzigen Zeile und kann horizontal scrollen. Bei 480 px oder weniger werden Steuerungen mit einem Symbol kompakter. Das Raster und die Karten passen sich ebenfalls an die verfügbare Breite an.

3. Umfassende URL-Parameterreferenz

Parameter Typ Erforderlich Default Beschreibung
RootFolderIdentifier positive ganze Zahl Nein Keine Beschränkt Explorer auf einen immersiveren Ordner und dessen Nachfolger. Ohne gültigen Wert aktiviert Multi-Root-Modus.
AllowedExtensions Wiederholbare Kette Nein alle Filtert die angezeigten Dateien nach ihrer Erweiterung.
RelativePath Kette Nein Keine Der anfängliche Pfad wird im Immersiven Baum gelöst und dann optional in einem Blob.
Render Kette Nein Normales Layout Wert Kiosk Ermöglicht das Kiosk-Layout.
Token Kette Kontextspezifisch Aktuelle Sitzung Ein Token, das verwendet wird, wenn der Aufrufer noch keine gültige immersive Sitzung hat.

Eine URL enthält nur eine ?. Alle folgenden Parameter sind durch Trennung getrennt &.

3.1 Filtererweiterungen

Der Parameter kann wiederholt werden:

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=131&AllowedExtensions=.jpg&AllowedExtensions=.png&AllowedExtensions=.pdf

Sie kann auch eine kommagetrennte Liste enthalten:

AllowedExtensions=.jpg,.png,.pdf

Regeln:

  • Der Fall wird ignoriert.
  • Der Anfangspunkt ist optional;
  • leere Werte werden ignoriert;
  • Wenn die Einstellung fehlt oder leer ist, werden alle Erweiterungen angezeigt;
  • Der Filter basiert auf dem Dateinamen;
  • Dieser Filter ist eine Anzeigeregel, keine Sicherheitsberechtigung.

3.2 Vollständige Auflösung von RelativePath

RelativePath kann nacheinander kreuzen:

  1. Immersive Ordner, identifiziert durch ihren Besitz Name ;
  2. der interne Pfad eines Blobs, vom ersten Ordner mit einem VirtualFolderPath.

Die Segmente sind getrennt durch /.

Mit RootFolderIdentifier

Der Pfad beginnt unter dem Zielordner. Der Wurzelname sollte nicht wiederholt werden.

Baumstruktur:

Projets (Identifier=10)
└── Chantier A
    └── MNM Blob (VirtualFolderPath configuré)
        └── 06 PLANS VITRINES
            └── SC01

URL:

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=10&RelativePath=Chantier%20A%2FMNM%20Blob%2F06%20PLANS%20VITRINES%2FSC01

Chantier A und MNM Blob werden in Immersive gelöst. 06 PLANS VITRINES/SC01 wird dann im Blob gelöst.

Wenn die Zielwurzel selbst der Blob-Ordner ist, enthält der Pfad nur die Blob-Segmente:

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=15&RelativePath=06%20PLANS%20VITRINES%2FSC01

Ohne RootFolderIdentifier

Das erste Segment muss der Name eines Immersiv-Ordners ohne Elternteil sein. Dieser Ordner wird zur Startwurzel der Auflösung.

https://mon-serveur/Business/Resources/Explorer?RelativePath=MNM%20Blob%2F06%20PLANS%20VITRINES%2FSC01

In diesem Beispiel gilt: MNM Blob muss ein Immersiver-Ordner ohne Elternteil sein. Die übrigen Segmente werden in seinem Blob aufgelöst.

Wenn mehr als ein Root-Ordner denselben Namen hat, wird der Ordner mit dem kleinsten Identifier verwendet wird. Daher wird empfohlen, den Root-Ordnern, die in einer URL verwendet werden, eindeutige Namen zu geben.

Pfadregeln

  • Verwendung / als Separator;
  • Geben Sie keine absolute URL an.
  • Verwenden Sie keine Segmente . oder .. ;
  • Spaces und Sonderzeichen in der URL kodieren;
  • Immersive Ordnernamen werden auf eine hoch- und kleinschreibungslose Weise verglichen.
  • Blob-Namen und Präfixe behalten die Fallregeln von Azure Blob Storage bei.
  • jedes Segment eines immersiven Ordners muss einem direkten Kind des vorherigen Segments entsprechen;
  • sobald ein virtueller Ordner gefunden wird, gehören alle verbleibenden Segmente dem Blob.

Es wird empfohlen, die URL zu erstellen mit URL und URLSearchParams :

const url = new URL("/Business/Resources/Explorer", window.location.origin);
url.searchParams.set("Render", "Kiosk");
url.searchParams.set("RootFolderIdentifier", "10");
url.searchParams.append("AllowedExtensions", ".pdf");
url.searchParams.append("AllowedExtensions", ".ifc");
url.searchParams.set(
    "RelativePath",
    "Chantier A/MNM Blob/06 PLANS VITRINES/SC01"
);

3.3 Vollständiges URL-Beispiel

https://mon-serveur/Business/Resources/Explorer?Render=Kiosk&Token=<JETON>&RootFolderIdentifier=15&AllowedExtensions=.jpg&AllowedExtensions=.png&AllowedExtensions=.pdf&AllowedExtensions=.ifc&AllowedExtensions=.riv&RelativePath=sous-repertoire%2Fsous-repertoire-2

4. Authentifizierung und Sicherheit

Die Seite und APIs des Explorers sind durch die globale Sicherheit von Immersive geschützt.

Es werden zwei Kontexte unterstützt:

  • Eine immersive Sitzung ist bereits aktiv.
  • Ein Token wird weitergegeben mit Token=<JETON>, besonders im Kiosk-Modus.

Die Komponente übergibt automatisch das in der URL der Seite vorhandene Token:

  • Im Header Authorization: Bearer seine JSON-Rufe;
  • in Medien-URLs, die zum selben Server gehören.

Best Practices:

  • verwenden Sie HTTPS;
  • Erstellen Sie URLs, die ein serverseitiges Token enthalten.
  • Begrenzen Sie die Dauer und die Rechte des Tokens.
  • Platzieren Sie niemals ein echtes Token in einem zugänglichen Repository, einer Dokumentation, einem Screenshot oder einem Protokoll.
  • Nicht verwenden AllowedExtensions als Zugangskontrolle.

4.1 Rechte zur Aktenverwaltung

Das Bearbeiten beruht auf den Berechtigungen des sicheren Objekts Folder :

Genehmigung Flaggenwert Verwendung im Explorer
See 1 Siehe das Dossier.
Read 3 Lies den Inhalt.
Modify 5 Ändere den Namen und die Beschreibung.
Write 11 Erstelle einen Unterordner und füge in einer späteren Entwicklung Medien hinzu.
FullControl 15 Lösche einen Ordner und verwalte alle seine Rechte.

Standardrechte werden auf jeden Immersive: Reading for Group-Ordner angewendet Users Organisation und volle Kontrolle über seine Administrators, globale Serveradministratoren, Domänenadministratoren und Cerebrate. Ordner, die vor dieser Änderung existierten, können aus dem RestFrontage-Standardrechte-Audit regularisiert werden.

EnableEditing stellt niemals eine Autorisierung dar. Der Server berechnet die an die Komponente zurückgegebenen Kapazitäten neu, steuert das Öffnen jedes Modals und kontrolliert dann die Registrierungsanfrage erneut.

Blob-Ordner bleiben nur lesegeschützt. Das Löschen eines Immersiv-Ordners wird abgelehnt, solange er mindestens einen Unterordner oder ein Medium enthält.

5. Mount an Azure Blob Container ein

Ein virtueller Ordner ist ein Folder Immersiv VirtualFolderPath enthält die Root-URL des Containers:

https://monstockage.blob.core.windows.net/mon-conteneur

Präfixe, getrennt durch / werden als Unterordner präsentiert:

06 PLANS VITRINES/SC01/plan-01.pdf
06 PLANS VITRINES/SC01/plan-02.pdf
06 PLANS VITRINES/SC02/plan-03.pdf

Aktuelle Veröffentlichungsbedingungen:

  • Der RestFrontage-Server muss Azure erreichen können.
  • Das Lesen und Aufzählen des Behälters muss anonym zugänglich sein;
  • VirtualFolderPath Muss die Wurzel des Containers anvisieren, nicht eine Datei.
  • Die Schauplätze danach ?, insbesondere ein SAS, während der Aufzählung nicht geführt werden;
  • Azure-Tagging wird noch nicht unterstützt: Ein sehr großer Container kann weitere Weiterentwicklung erfordern.

6. Integration in ein iframe

<iframe
    src="https://mon-serveur/Business/Resources/Explorer?Render=Kiosk&amp;RootFolderIdentifier=15&amp;AllowedExtensions=.pdf"
    title="Documents du projet"
    loading="lazy"
    allow="fullscreen">
</iframe>

Wenn sandbox verwendet wird, autorisieren Sie bei Bedarf:

  • allow-scripts die Explorer zu steuern;
  • allow-same-origin für den Authentifizierungskontext;
  • allow-downloads für Downloads;
  • allow-popups um Dateien in einem neuen Tab zu öffnen.

Sowohl das RestFrontage-CSP als auch das CSP der übergeordneten Seite müssen die Integration erlauben.

7. Umfassende JavaScript-Integrationsreferenz

7.1 Bau

Der Explorer wird als zwei eigenständige Dateien verteilt, wobei die Pfade zum aktuellen Rest-Server wie folgt sind:

/css/media-explorer.css
/js/media-explorer.js

Allein für die Beratung sind sie nicht abhängig von css/site.css, noch js/common.js, jQuery oder Bootstrap. Das Stylesheet muss auf der Seite geladen werden und das Skript muss vor dem Code geladen werden, der den Explorer erstellt.

Andererseits verwendet der Bearbeitungsmodus die RestFrontage-Modals und die ShowModal, UpdateData, ShowProcessingModal, HideProcessingModal und showToast von js/common.js. Externe Integration, die aktiviert wird EnableEditing müssen daher auch das Layout der Modals übernehmen, Bootstrap und common.js, oder kompatible Funktionen bereitzustellen.

const explorer = new MediaExplorer(hostElement, options);
await explorer.initialize();

hostElement muss ein existierendes HTML-Element sein. Der Konstruktor bereitet den Bericht vor; initialize() generiert die Schnittstelle und lädt dann die Daten.

Vollständiges Beispiel:

<link rel="stylesheet" href="/css/site.css">
<link rel="stylesheet" href="/css/media-explorer.css">

<div id="MediaExplorerHost"></div>

<script src="/js/commons.js"></script>
<script src="/js/media-explorer.js"></script>
<script>
    const explorer = new MediaExplorer(
        document.getElementById("MediaExplorerHost"),
        {
            RootFolderIdentifier: 15,
            CurrentFolderIdentifier: 15,
            RelativePath: "06 PLANS VITRINES/SC01",
            AllowedExtensions: [".pdf", ".ifc"],
            ApiBaseUrl: "/api/Explorer",
            DefaultFileIconUrl: "/Content/Common/file.svg",
            DefaultFolderIconUrl: "/Content/Common/folder.svg",
            DownloadOnClick: true,
            EnableEditing: true,
            ExtensionIconUrlBuilder: (extension, media) =>
                extension ? `/Content/Common/${extension.substring(1)}.svg` : null,
            MimeTypeIconUrlBuilder: (mimeType, media) =>
                mimeType ? `/Content/Common/${mimeType.replace("/", "-")}.svg` : null,
            Labels: {
                Up: "Niveau supérieur"
            },
            OnFolderChanged: folder => console.log("Dossier", folder),
            OnMediaClicked: media => console.log("Fichier", media),
            OnMediaDoubleClicked: media => console.log("Double-clic", media),
            OnError: error => console.error(error)
        }
    );

    await explorer.initialize();
</script>

Für die Ansicht können beide Dateien direkt von RestFrontage bereitgestellt oder in die Assets der Client-Anwendung kopiert werden. Wenn die Client-Anwendung und die RestFrontage-API nicht denselben Ursprung haben, ApiBaseUrl muss eine absolute URL sein, und RestFrontage muss diesen Ursprung in seiner CORS-Konfiguration zulassen.

7.2 Alle Optionen

Option Typ Default Beschreibung
RootFolderIdentifier number | null null Auferlegte Wurzel. null Aktiviert den Multi-Root-Modus.
CurrentFolderIdentifier number | null null Ursprünglich eröffnet in Abwesenheit von RelativePath. Es muss zur auferlegten Wurzel gehören.
RelativePath string | null null Mixed Immersive/Blob Anfangspfad. Er wird einmal beim ersten Laden aufgelöst.
AllowedExtensions string[] [] Sichtbare Erweiterungen. Ein leeres Array ermöglicht alles.
ApiBaseUrl string "/api/Explorer" API-Routenpräfix.
DefaultFileIconUrl string "/Content/Common/file.svg" Ein generisches Symbol, das für eine Datei verwendet wird, die nicht vorschauig oder gefaltet werden kann.
DefaultFolderIconUrl string "/Content/Common/folder.svg" Ordner- und Baumsymbol.
ExtensionIconUrlBuilder function | null null Baut ein Icon aus (extension, media). Eine URL zurückgeben oder null.
MimeTypeIconUrlBuilder function | null null Baut ein Icon aus (mimeType, media). Eine URL zurückgeben oder null.
DownloadOnClick boolean false Wenn true, öffnet ein Klick die Datei. Ansonsten wird die Standard-Öffnung doppelt geklickt.
EnableEditing boolean false Fordere die Anzeige von vom Server autorisierten Ordnerbefehle an. Gewährt keine Rechte.
Labels object Siehe unten Teilweise Überlastung von Texten der Benutzeroberfläche.
OnFolderChanged function | null null Erhält den Ordner nach erfolgreichem Durchsuchen.
OnMediaClicked function | null null Erhält die Medien nach einem einzigen Klick.
OnMediaDoubleClicked function | null null Empfängt Medien beim Doppelklick, wenn DownloadOnClick ist es wert false.
OnError function | null null Erhält den Gegenstand Error nachdem der Fehler in der Schnittstelle angezeigt wurde.

Die in RestFrontage eingebettete Seite überschreibt die folgenden Standardeinstellungen:

  • DownloadOnClick: true ;
  • EnableEditing: true ;
  • ExtensionIconUrlBuilder zu /Content/Common/{extension}.svg ;
  • MimeTypeIconUrlBuilder zu /Content/Common/{mime-type}.svg.

7.3 Alle Formulierungen (Labels)

Labels ist eine partielle Überlastung: Nur die bereitgestellten Schlüssel werden ersetzt.

Legende Default Lage oder Situation
Folders "Dossiers" Der Titel des linken Panels und der Text des mobilen Buttons, der dieses Panel öffnet.
Root "Racine" Der Name der synthetischen Wurzel des Mehrwurzelmodus.
Up "Remonter" Das zugängliche Label und Tooltip der übergeordneten Pfeiltaste. Um es zu ersetzen, verwenden Sie zum Beispiel Up: "Niveau supérieur".
Loading "Chargement…" Statusleiste während einer Abfrage.
EmptyFolder "Ce dossier est vide." Inhaltsbereich ohne Kinder oder Medien.
Folder "Dossier" Metadaten, die unter einer Ordnerkarte angezeigt werden. Dieser Schlüssel steuert den Titel nicht Ordner.
VirtualFolder "Dossier virtuel" Metadaten werden unter einer Blob-Ordnerkarte angezeigt.
Virtual "Virtuel" Metadaten, die unter einer Datei von einem Blob hinzugefügt werden.
CreateFolder "Nouveau dossier" Schaltfläche zum Erstellen im aktuellen Ordner.
EditFolder "Modifier" Schalte aktuellen Ordner bearbeiten.
DeleteFolder "Supprimer" Lösch-Button für den aktuellen Ordner.
Refresh "Rafraîchir" Button, um die Baumansicht und den aktuellen Ordner neu zu laden.
EditingUnavailable "Les outils d’édition de l’Explorer ne sont pas disponibles sur cette page." Fehler, wenn EnableEditing ist aktiv ohne ein kompatibles modales Rahmenwerk.
Retry "Réessayer" Button wird nach einem wiederherstellbaren Fehler angezeigt.
TreeLoadError "Impossible de charger l’arborescence." Netzwerk- oder generischer Fehler beim Laden des Baums.
FolderLoadError "Impossible de charger le contenu du dossier." Netzwerk- oder generischer Fehler beim Laden eines Ordners.
UnauthorizedError "Votre session a expiré ou le jeton est invalide." HTTP-401-Antwort.
ForbiddenError "Vous n’avez pas accès à cette ressource." HTTP-403-Antwort.
NotFoundError "La ressource demandée est introuvable." HTTP-404-Antwort.
UnexpectedError "Une erreur inattendue est survenue." Fehler ohne umsetzbare Meldung.

Beispiel mit allen Tasten:

Labels: {
    Folders: "Documents",
    Root: "Tous les espaces",
    Up: "Niveau supérieur",
    Loading: "Chargement en cours…",
    EmptyFolder: "Aucun document disponible.",
    Folder: "Répertoire",
    VirtualFolder: "Répertoire distant",
    Virtual: "Distant",
    CreateFolder: "Créer un répertoire",
    EditFolder: "Renommer",
    DeleteFolder: "Effacer",
    Refresh: "Actualiser",
    EditingUnavailable: "L’édition n’est pas disponible dans cette intégration.",
    Retry: "Recharger",
    TreeLoadError: "L’arborescence ne peut pas être chargée.",
    FolderLoadError: "Le contenu ne peut pas être chargé.",
    UnauthorizedError: "Authentification requise.",
    ForbiddenError: "Accès refusé.",
    NotFoundError: "Élément introuvable.",
    UnexpectedError: "Une erreur est survenue."
}

Navigationsgrafiken und Größeneinheiten sind nicht konfigurierbar durch Labels in der aktuellen Version. Der Schlüssel Up Konfiguriert jedoch den zugänglichen Namen und das Tooltip des übergeordneten Pfeils.

7.4 Icon-Auflösung

Für ein Medium lautet die Reihenfolge der Auflösung:

  1. echtes Vorschaubild, wenn media.IsImage und media.PreviewUrl werden ausgefüllt;
  2. Ergebnis von ExtensionIconUrlBuilder(extension, media) ;
  3. Ergebnis von MimeTypeIconUrlBuilder(media.ContentType, media) ;
  4. DefaultFileIconUrl.

Wenn das gewählte Bild nicht geladen wird, DefaultFileIconUrl versucht wird. Wenn auch der Fallback fehlschlägt, wird das Bild ausgeblendet. Ordnernutzung DefaultFolderIconUrl und dann das Bild ausblenden, falls diese URL fehlschlägt.

Die dem Builder bereitgestellte Erweiterung wird zum Beispiel in Kleinbuchstaben normalisiert und beginnt mit einem Punkt, zum Beispiel .pdf.

7.5 Klickverhalten

Konfiguration Einfacher Klick Doppelklick
DownloadOnClick: true Auswählen, rufen OnMediaClicked, dann öffnet sich DownloadUrl. Keine zusätzliche Behandlung.
DownloadOnClick: false Wählen und rufen OnMediaClicked. Ruf OnMediaDoubleClicked wenn es existiert; wenn nicht, öffnet sich DownloadUrl.

Dateien werden in einem neuen Tab geöffnet. Ein iframe mit sandbox muss daher die notwendigen Downloads oder Windows zulassen.

7.6 Alle Rückrufe

OnFolderChanged(folder)

Wurde danach gerufen navigateToFolder() und nach einer Rückkehr zur synthetischen Wurzel. Er wird nicht vom allerersten gerufen initialize().

OnMediaClicked(media)

Gerufen nach jedem einfachen Klick, bevor die endgültige automatische Öffnung begann.

OnMediaDoubleClicked(media)

Nur beim Doppelklick aufgerufen, wenn DownloadOnClick ist es wert false. Seine Präsenz ersetzt das automatische Doppelklick-Öffnen.

OnError(error)

Ruft auf, nachdem der Fehler angezeigt wurde. Für eine HTTP-Antwort, error.status Enthält insbesondere, 401, 403 oder 404. Für einen Netzwerkfehler, status vielleicht fehlt.

7.7 Alle unterstützten öffentlichen Methoden

Methode Zurück Beschreibung
initialize() Promise<void> Baut die Schnittstelle und führt die anfängliche Last durch. Wird einmal nach dem Konstruktor aufgerufen.
load() Promise<void> Lädt die aktuelle Welle und den Falter wieder auf. Löst auch das RelativePath falls es noch nicht verzehrt wurde.
navigateToFolder(folder) Promise<void> Öffnet einen Ordner aus einer Ordner-ID oder einem Objekt.
setAllowedExtensions(extensions) Promise<void> Ersetzt den Filter und lädt die aktuelle Ansicht neu. [] genehmigt alles.
setRootFolder(rootFolderIdentifier) Promise<void> Ändere die Wurzel, setze die Navigation zurück und lade neu. null, 0 oder ein negativer Wert aktiviert den Multi-Root-Modus wieder.
setSidebarOpen(isOpen) void Öffnet oder schließt das responsive Panel.
refreshFolder(folderIdentifier) Promise<void> Lädt den Baum neu und öffnet den gewünschten Ordner nach einer Mutation. null Kehrt zur verfügbaren Wurzel zurück. Wird normalerweise durch das teilweise Auffrischen ausgelöst.
destroy() void Löscht den HTML-Inhalt vom Host. Die Instanz sollte ohne Neuinitialisierung nicht erneut verwendet werden.

Beispiele:

await explorer.load();
await explorer.navigateToFolder(58);
await explorer.navigateToFolder({
    Identifier: 15,
    Path: "06 PLANS VITRINES/SC01",
    IsVirtual: true
});
await explorer.setAllowedExtensions([".jpg", ".png"]);
await explorer.setAllowedExtensions([]);
await explorer.setRootFolder(42);
await explorer.setRootFolder(null);
explorer.setSidebarOpen(true);
explorer.setSidebarOpen(false);
await explorer.refreshFolder(42);
explorer.destroy();

8. Struktur der an Callbacks übermittelten Objekte

8.1 Ordnerobjekt

Eigentum Typ Beschreibung
Identifier number | null Objekt-ID Folder. null Nur für die synthetische Wurzel.
Key string Stabile Taste anzeigen: Folder:{id}, Virtual:{path} oder ExplorerRoot.
Name string Anzeigename.
Description string | null Eine Beschreibung, falls vorhanden.
ParentIdentifier number | null Eltern-ID Folder.
Path string | null Ein relativer Blob-Pfad für einen virtuellen Ordner.
IsVirtual boolean Spezifiziert einen Blob-Ordner.
IsExplorerRoot boolean | undefined Worth true Nur für die Artenwurzel des Clients.
CreationDate JSON-Datum oder Abwesenheit Datum der Dateianlegung.
LastModificationDate JSON-Datum, null oder abwesend Letzte bekannte Änderung.
HasChildren boolean Zeigt das mögliche Vorhandensein von Unterordnern an.
HasMedia boolean Das deutet auf die mögliche Präsenz von Medien hin.

8.2 Medienobjekt

Eigentum Typ Beschreibung
Identifier number Kennung der Media ; ist es wert 0 für eine virtuelle Datei.
Key string Media:{id} oder VirtualMedia:{path}.
Name string Dateiname.
Description string | null Eine Beschreibung, falls vorhanden.
ContentType string | null Bekannter MIME-Typ.
Handle string | null Möglicher Serverpfad; sollte nicht direkt vom Client verwendet werden.
ParentFolderIdentifier number Datensatzkennung (Folder) Besitzer oder Timeline-Ordner.
Size number | null Größe in Bytes.
CreationDate JSON-Datum Bekanntes Entstehungsdatum.
LastModificationDate JSON-Datum oder null Letzte bekannte Änderung.
Extension string Standardisierte Erweiterung zum Beispiel .pdf.
Path string | null Der relative Blob-Pfad für eine virtuelle Datei.
IsVirtual boolean Spezifiziert eine Blob-Datei.
IsImage boolean Zeigt ein anerkanntes Seitenverhältnis an.
CanPreview boolean Zeigt an, dass eine Vorschau verfügbar ist.
PreviewUrl string | null Thumbnail- oder Bildinhalt-URL.
DownloadUrl string | null Die Eröffnungs- oder Download-URL.

9. Umfassende HTTP-API-Referenz

Alle Straßen sind GET unter /api/Explorer und den gleichen Authentifizierungskontext wie die Seite benötigen.

9.1 GET /api/Explorer/GetTree

Lädt den Immersiv-Baum.

Abfragestring Typ Erforderlich Beschreibung
RootFolderIdentifier Ganzzahl Nein Auferlegter Root. Wertlos, lädt alle Bäume aus einem Ordner ohne Elternteil.

JSON-Antwort:

{
  "RootFolderIdentifier": 0,
  "Folders": [
    {
      "Identifier": 15,
      "Name": "MNM Blob",
      "ParentIdentifier": null,
      "HasChildren": true
    }
  ]
}

RootFolderIdentifier ist es wert 0 in der Antwort des Multi-Root-Modus.

9.2 GET /api/Explorer/GetFolderContent

Lädt die aktuelle Datei, seinen Elternteil, seine Kinder, seine Medien und seine Brotkrumenspur.

Abfragestring Typ Erforderlich Beschreibung
RootFolderIdentifier Ganzzahl Nein Sicherheits-/Navigations-Root.
FolderIdentifier Ganzzahl Bedingt Aktueller Ordner. Kann weggelassen werden, wenn RelativePath wird bereitgestellt oder wenn eine Wurzel angegeben wird.
AllowedExtensions CSV-String Nein Sichtbare Erweiterungen. Ein leerer Wert erlaubt alles.
Path Kette Nein Interner Pfad zu einem bereits identifizierten Blob-Ordner durch FolderIdentifier. Wird für die tägliche Navigation genutzt.
RelativePath Kette Nein Der initiale Pfad von gemischtem Immersive/Blob wurde von der expliziten Wurzel oder globalen Wurzeln aufgelöst.

Path und RelativePath haben unterschiedliche Rollen: Ein Integrator muss sie nutzen RelativePath für eine Anfangsöffnung und lassen Sie die Komponente handhaben Path während er Blob durchstöbert.

Wichtige Antworteigenschaften:

Eigentum Beschreibung
RootFolderIdentifier Angeforderte Wurzel oder 0 im Multi-Root-Modus.
IsVirtual Zeigt an, dass der aktuelle Inhalt von einem Blob stammt.
Path Pfadlauf im Blob.
VirtualFolderPath Die virtuelle Ordner-Mount-URL.
CurrentFolder Aktuelle Akte.
ParentFolder Navigierbarer Eltern oder null.
Children Direkte Unterordner.
Media Direkte Dateien nach dem Filtern.
Breadcrumb Stufen der Immersiven Breadcrumb-Spur, dann Blob.
Capabilities.CanCreateFolder Ermöglicht es, die Kreativität anzuzeigen, wenn EnableEditing ist aktiv.
Capabilities.CanEditFolder Ermöglicht es, die Änderung anzuzeigen, wenn EnableEditing ist aktiv.
Capabilities.CanDeleteFolder Erlaubt das Anzeigen der Löschung, wenn EnableEditing ist aktiv.
RootCapabilities.CanCreateFolder Ermöglicht die Entstehung in der synthetischen Wurzel der aktuellen Organisation.

9.3 GET /api/Explorer/GetBreadcrumb

Route für Kompatibilität erhalten bleiben. Die aktuelle Komponente benötigt sie nicht mehr, weil GetFolderContent Ist schon zurückgekehrt Breadcrumb.

Abfragestring Typ Erforderlich Beschreibung
RootFolderIdentifier Ganzzahl Nein Auferlegte Wurzel.
FolderIdentifier Ganzzahl Ja Aktuelle Akte.
Path Kette Nein Common Blob Road.

Die Antwort enthält { "Items": [...] }.

9.4 GET /api/Explorer/GetContent/{mediaIdentifier}

Streams, Medien oder Dateien, referenziert von Handle.

Streckenparameter Typ Beschreibung
mediaIdentifier Ganzzahl Immersive Media ID.

Inhalte werden in aufeinanderfolgenden Strömen gelesen. Eine physische Datei unterstützt HTTP-Range-Anfragen.

9.5 GET /api/Explorer/GetVirtualContent

Servert eine Datei, die zu einem virtuellen Ordner gehört.

Abfragestring Typ Erforderlich Default Beschreibung
FolderIdentifier Ganzzahl Ja — Identifikator des Dateilagers VirtualFolderPath.
Path Kette Ja — Der Pfad der Datei im Blob.
Download Boolesch Nein false Fügt ein Layout hinzu attachment wenn der Wert ist true.

Der Server leitet die Blob-Inhalte per Streaming weiter.

9.8 Nützliche HTTP-Codes

Code Übliche Bedeutung
200 Anfrage erfolgreich.
400 Fehlender Parameter, absoluter Pfad oder Vorhandensein von . / ...
401 Sitzungsabwesenheit, abgelaufenes oder ungültiges Token.
403 Authentifizierte, aber nicht autorisierte Identität.
404 Wurzel, Ordner, Pfad oder Datei nicht gefunden; Ordner außerhalb der auferlegten Wurzel.

10. Fehlerbehebung

Abgelaufene Sitzung oder ungültiges Token

  • Überprüfe das Ablaufdatum des Tokens.
  • Überprüfen Sie, dass die URL nur eine enthält ? ;
  • Überprüfen Sie, dass Token wurde weder abgeschnitten noch doppelt codiert.

Zugang verweigert

Das Konto oder der Token hat nicht die notwendigen Rechte. Kontaktieren Sie einen immersivem Administrator.

Ressource nicht gefunden

  • Check RootFolderIdentifier ;
  • Entfernen Sie die Wurzel, um die Anwesenheit des Ordners im Multi-Root-Modus zu steuern.
  • Überprüfen Sie jeden Immersiv-Ordnernamen von RelativePath ;
  • mit einer auferlegten Wurzel, wiederhole seinen Namen nicht in RelativePath ;
  • ohne eine auferlegte Wurzel wird überprüft, dass das erste Segment der Name eines ordners ohne Elternteil ist;
  • Überprüfen Sie den Fall der Blob-Segmente.
  • Überprüfen Sie, ob die Datei oder der Container existiert.

Leerer Blob-Ordner oder fehlende Unterordner

  • Check VirtualFolderPath ;
  • Überprüfen Sie, dass die URL auf die Wurzel des Containers zielt.
  • Prüfen Sie anonyme Lese- und Aufzählungszugänge.
  • Überprüfen Sie, dass RestFrontage Azure erreichen kann.
  • Überprüfen Sie, dass Blob-Namen verwenden / ;
  • Überprüfen Sie, dass das Azure-Ergebnis keine nächste Seite benötigt, die noch nicht verwaltet wird.

Einige Dateien erscheinen nicht

  • Check AllowedExtensions ;
  • Entferne diese Einstellung komplett, um alles zu sehen.
  • Überprüfen Sie, ob die Datei die erwartete Erweiterung hat.

Das Herunterladen startet nicht in einem iframe

Check sandbox, allow-downloads, allow-popups, CSP und Browser-Pop-up-Blockierung.

11. Integrationscheckliste

  • Der Multi-Root-Modus oder die auferlegte Wurzel entspricht dem Bedarf an Sicherheit und Navigation.
  • Verwendete Namen in RelativePath Man kann einen echten Eltern-/Kind-String abstimmen.
  • Das erste Segment von RelativePath Bezieht sich auf eine Wurzel eines immersiveren Ordners, wenn RootFolderIdentifier fehlt.
  • Azure case-sensitive Blob-Segmente.
  • Erweiterungen werden angegeben oder der Filter wird weggelassen, um alles anzuzeigen.
  • Das Konto oder der Token hat die notwendigen Rechte.
  • Die URL verwendet eine einzelne ?, dann &.
  • Der Pfad ist relativ und korrekt codiert.
  • Der Blob-Container ist erreichbar, lesbar und aufzählbar.
  • Der iframe ermöglicht die notwendigen Skripte, Öffnungen und Downloads.
  • Im Quellcode oder in der Dokumentation werden keine echten Tokens gespeichert.
  • Das Verhalten wird sowohl auf dem Desktop als auch auf dem Handy überprüft.

Entwickler

  • Lernzentrum
  • Launcher
  • Immersive Script
  • Immersive Forge
  • SDK Immersive