LgDocument

LgDocument télécharge un document depuis une URI de contrôleur, crée une URL blob côté navigateur et l'affiche sous forme d'image, de vidéo ou de cadre intégré. Utilisez-le pour présenter des fichiers protégés par l'authentification Lagoon ou des documents publics interprétables par le navigateur.

<LgDocument ControllerUri="api/documents/preview/42" />

• Espace de noms : Lagoon.UI.Components
• Hérite de : LgComponentBase
• Package NuGet : Lagoon.UI

Utilisation

Contrat des endpoints

ControllerUri est appelé en GET par le JavaScript du composant. Sauf si AnonymousRequest vaut true, le composant demande un jeton d'accès et l'envoie à l'endpoint. Lorsque AllowDelete vaut true, la même URI doit aussi accepter DELETE.

GET — Télécharger le document (ControllerUri)

DocumentsController.cs

[ApiController]
[Route("api/documents")]
public class DocumentsController : LgControllerBase
{
    // Service métier responsable de retrouver les métadonnées et le chemin serveur du document.
    private readonly DocumentService _documentService;

    // Initialise le contrôleur avec le service d'accès aux documents.
    public DocumentsController(DocumentService documentService)
    {
        _documentService = documentService;
    }

    // Retourne le flux attendu par LgDocument pour créer l'URL blob côté navigateur.
    [HttpGet("preview/{documentId:guid}")]
    public async Task<ActionResult<FileStream>> PreviewAsync(Guid documentId)
    {
        DocumentFile document = await _documentService.GetFileAsync(documentId);
        return FileContent(document.Path, document.ContentType, document.FileName, false);
    }
}

• Entrée : paramètres de route ou de requête définis par votre URI, par exemple Guid documentId.
• Sortie : un contenu fichier, typiquement ActionResult<FileStream> retourné via FileContent(...) de LgControllerBase.
• Erreur : laissez LgControllerBase produire une réponse d'erreur cohérente via Problem(ex) si vous encapsulez votre logique dans un try / catch.

DELETE — Supprimer le document (ControllerUri)

DocumentsController.cs

[ApiController]
[Route("api/documents")]
public class DocumentsController : LgControllerBase
{
    // Service métier responsable de supprimer le fichier et ses métadonnées.
    private readonly DocumentService _documentService;

    // Initialise le contrôleur avec le service d'accès aux documents.
    public DocumentsController(DocumentService documentService)
    {
        _documentService = documentService;
    }

    // Supprime le document lorsque AllowDelete est activé sur LgDocument.
    [HttpDelete("preview/{documentId:guid}")]
    public async Task<IActionResult> DeleteAsync(Guid documentId)
    {
        await _documentService.DeleteAsync(documentId);
        return NoContent();
    }
}

• Entrée : les mêmes paramètres que l'URI affichée par ControllerUri.
• Sortie : toute réponse HTTP de succès convient ; le composant déclenche ensuite OnDelete si un gestionnaire est défini.

Afficher une image protégée

Par défaut, la requête est authentifiée. Kind="DocumentKind.Image" rend le document dans un élément image interne. Pour une image, ClickBehaviour peut ouvrir l'image en modale, dans un nouvel onglet ou lancer son téléchargement.

GalleryPage.razor

<LgDocument Kind="DocumentKind.Image"
            ControllerUri="@ImageUri"
            Filename="@ImageFileName"
            ClickBehaviour="DocumentClickBehaviour.OpenInModal"
            Tooltip="#OpenImagePreview" />

GalleryPage.razor.cs

public partial class GalleryPage : LgPage
{
    // URI du contrôleur qui retourne le contenu binaire de l'image.
    private string ImageUri { get; set; } = "api/documents/preview/4cf9aaf7-4d2f-4d68-9db7-e1285d1b5f61";

    // Nom proposé lors du téléchargement ou de l'ouverture du document.
    private string ImageFileName { get; set; } = "image-preview.png";
}

Afficher un PDF ou un document intégré

La valeur par défaut de Kind est DocumentKind.IFrame. Elle convient aux PDF et aux formats que le navigateur peut afficher dans un cadre intégré.

ContractPage.razor

<LgDocument ControllerUri="@ContractUri"
            Filename="@ContractFileName"
            ShowDownloadProgression="true" />

ContractPage.razor.cs

public partial class ContractPage : LgPage
{
    // URI du contrôleur qui fournit le PDF à prévisualiser.
    private string ContractUri { get; set; } = "api/documents/preview/2fbb8c23-9f9f-4e42-b8b4-39c7cf67290b";

    // Nom de fichier utilisé lorsque l'utilisateur ouvre ou télécharge le document.
    private string ContractFileName { get; set; } = "contract.pdf";
}

Afficher une vidéo

DocumentKind.Video rend le document comme vidéo. Réservez ce mode à des fichiers raisonnables : le composant télécharge le fichier complet avant l'affichage.

VideoPage.razor

<LgDocument Kind="DocumentKind.Video"
            ControllerUri="@VideoUri"
            Filename="@VideoFileName"
            VideoAutoPlay="true"
            VideoControlsDisabled="false" />

VideoPage.razor.cs

public partial class VideoPage : LgPage
{
    // URI du contrôleur qui retourne le fichier vidéo complet.
    private string VideoUri { get; set; } = "api/documents/preview/7f6202fa-b4bb-4e84-8918-0532feef8f7e";

    // Nom proposé lors du téléchargement de la vidéo.
    private string VideoFileName { get; set; } = "training-video.mp4";
}

Personnaliser le chargement et le rendu

LoaderContent reçoit la progression de téléchargement, avec -1 en cas d'erreur. ChildContent reçoit l'URL blob du document et remplace le rendu interne.

CustomDocumentPage.razor

<LgDocument ControllerUri="@DocumentUri" ShowDownloadProgression="true">
    <LoaderContent Context="progression">
        <LgCircleProgress Value="@Math.Max(progression, 0)" Min="0" Max="100" />
    </LoaderContent>
    <ChildContent Context="blobUrl">
        <LgButton Text="#OpenDocument"
                  Kind="ButtonKind.Link"
                  Uri="@blobUrl"
                  Target="_blank" />
    </ChildContent>
</LgDocument>

CustomDocumentPage.razor.cs

public partial class CustomDocumentPage : LgPage
{
    // URI du contrôleur appelée pour créer l'URL blob transmise au contenu personnalisé.
    private string DocumentUri { get; set; } = "api/documents/preview/854b69f6-5446-4c3d-9c63-99e8c3e3f4ef";
}

Mettre en cache plusieurs documents

Encapsulez plusieurs LgDocument dans LgDocumentsCache pour réutiliser les URL blob déjà téléchargées. Une référence au cache permet de supprimer une entrée avec Remove(...) ou de tout vider avec Clear().

CachedGalleryPage.razor

<LgDocumentsCache @ref="DocumentsCache">
    <LgDocument Kind="DocumentKind.Image"
                ControllerUri="@FirstImageUri"
                Filename="@FirstImageFileName" />
    <LgDocument Kind="DocumentKind.Image"
                ControllerUri="@SecondImageUri"
                Filename="@SecondImageFileName" />
</LgDocumentsCache>

<LgButton Text="#RefreshDocuments" OnClick="RefreshDocumentsAsync" />

CachedGalleryPage.razor.cs

public partial class CachedGalleryPage : LgPage
{
    // Référence au cache qui stocke les URL blob des documents enfants.
    private LgDocumentsCache DocumentsCache { get; set; }

    // URI du premier document affiché dans la galerie.
    private string FirstImageUri { get; set; } = "api/documents/preview/14153022-5d8f-45fe-9305-01dd176d60ce";

    // Nom du premier document affiché dans la galerie.
    private string FirstImageFileName { get; set; } = "first-image.png";

    // URI du deuxième document affiché dans la galerie.
    private string SecondImageUri { get; set; } = "api/documents/preview/54db6764-0dd9-4531-9826-6490e29f26bf";

    // Nom du deuxième document affiché dans la galerie.
    private string SecondImageFileName { get; set; } = "second-image.png";

    // Vide le cache pour forcer un nouveau téléchargement lors du prochain rendu.
    private Task RefreshDocumentsAsync(ActionEventArgs args)
    {
        DocumentsCache.Clear();
        return Task.CompletedTask;
    }
}

Propriétés

Nom	Type	Défaut	Déclaré dans	Description
ChildContent	RenderFragment<string>	null	LgDocument	Fragment personnalisé recevant l'URL blob du document téléchargé.
LoaderContent	RenderFragment<int>	null	LgDocument	Fragment personnalisé affiché pendant le téléchargement ; la valeur reçue est la progression.
AllowDelete	bool	false	LgDocument	Affiche une action de suppression et envoie une requête HTTP DELETE sur ControllerUri.
AnonymousRequest	bool	false	LgDocument	Désactive l'ajout du jeton d'authentification à la requête de téléchargement.
AdditionalAttributes	IReadOnlyDictionary<string, object>	null	LgDocument	Attributs supplémentaires capturés depuis le balisage du composant.
ClickBehaviour	DocumentClickBehaviour	DocumentClickBehaviour.None	LgDocument	Comportement appliqué lors du clic interne sur l'image rendue.
ControllerUri	string	null	LgDocument	URI du contrôleur utilisée pour télécharger le document et, si autorisé, le supprimer.
CssClass	string	null	LgDocument	Classes CSS ajoutées au conteneur du document.
Filename	string	null	LgDocument	Nom de fichier utilisé pour la modale, l'ouverture dans un nouvel onglet ou le téléchargement.
Kind	DocumentKind	DocumentKind.IFrame	LgDocument	Type de rendu utilisé pour présenter le document.
OnClick	EventCallback	default	LgDocument	Événement public déclaré pour un clic utilisateur sur le document.
OnDelete	EventCallback	default	LgDocument	Événement déclenché après une suppression HTTP réussie.
ShowDownloadProgression	bool	false	LgDocument	Active le suivi de progression du téléchargement.
Tooltip	string	null	LgDocument	Bulle d'aide associée au document. Utilisez une clé #....
TooltipIsHtml	bool	false	LgDocument	Indique que le contenu de la bulle d'aide est au format HTML.
VideoAutoPlay	bool	false	LgDocument	Demande la lecture automatique lorsque le document est une vidéo.
VideoControlsDisabled	bool	false	LgDocument	Désactive les contrôles vidéo lorsque le document est une vidéo.

Événements

Nom	Type	Description
OnClick	EventCallback	Événement public déclaré pour le clic utilisateur sur le document. Le rendu interne utilise ClickBehaviour pour l'action de clic intégrée sur une image.
OnDelete	EventCallback	Déclenché après l'appel DELETE réussi sur ControllerUri.

Énumérations associées

DocumentClickBehaviour

Valeur par défaut : DocumentClickBehaviour.None.

Valeur	Description
None	Ne fait rien lors du clic sur l'image.
OpenInModal	Ouvre le document dans une modale Lagoon depuis le clic sur l'image.
OpenInNewTab	Ouvre le document dans un nouvel onglet du navigateur depuis le clic sur l'image.
Download	Déclenche le téléchargement du document depuis le clic sur l'image.

DocumentKind

Valeur par défaut : DocumentKind.IFrame.

Valeur	Description
IFrame	Rend le document dans un cadre intégré.
Image	Rend le document comme image.
Video	Rend le document comme vidéo ; le fichier complet est téléchargé avant l'affichage.

Accessibilité

Renseignez Tooltip avec une clé traduite lorsque le document ou l'action de suppression nécessite une explication. Pour les images importantes, complétez AdditionalAttributes avec un texte alternatif ou fournissez un ChildContent accessible. Le mode IFrame et les URL blob dépendent du support du navigateur : prévoyez un lien ou une action de téléchargement pour les documents critiques.

Composants liés

• LgDocumentsCache : met en cache les documents téléchargés par plusieurs LgDocument enfants.
• LgInputFile : téléverse les fichiers que LgDocument peut ensuite afficher.
• LgButton : fournit une action personnalisée dans ChildContent.
• LgCircleProgress : affiche une progression personnalisée via LoaderContent.