LgInputFile

LgInputFile est le composant Lagoon de sélection, téléversement, téléchargement et suppression de fichiers liés. Il prend en charge la sélection multiple, les dossiers, le glisser-déposer, les restrictions d'extensions ou de types MIME, les modes de téléversement automatique, par bouton ou manuel, ainsi que le suivi de modification d'un formulaire.

<LgInputFile Label="Pièces jointes"
             UploadUri="api/InputFile/Upload"
             LinkedFilesUri="api/InputFile/Files"
             Authenticate="false" />

• Espace de noms : Lagoon.UI.Components
• Hérite de : LgAriaComponentBase → LgComponentBase
• Interfaces : IFormTrackerComponent
• Package NuGet : Lagoon.UI

Modes de téléversement

UploadMode.Automatic lance le transfert dès la sélection. UploadMode.Button affiche un bouton interne. UploadMode.Manual laisse la page appeler DoUploadAsync() via @ref.

Utilisation

Démonstration

Essayez ce composant dans le showcase Lagoon.

Contrat des endpoints

LgInputFile utilise UploadUri pour l'envoi et LinkedFilesUri comme racine pour la liste, le téléchargement et la suppression. Les routes ci-dessous correspondent à UploadUri="api/documents/upload" et LinkedFilesUri="api/documents/files".

POST — Réception des fichiers (UploadUri)

Le composant envoie un multipart/form-data. Les fichiers sont disponibles dans Request.Form.Files.

DocumentController.cs

[ApiController]
[Route("api/documents")]
public class DocumentController : LgControllerBase
{
    // Contexte applicatif utilisé pour persister les métadonnées des fichiers.
    private readonly ApplicationDbContext _db;

    // Répertoire racine configuré côté serveur pour ne jamais exposer un chemin fourni par le client.
    private readonly string _storagePath;

    // Initialise les dépendances nécessaires au stockage des fichiers et de leurs métadonnées.
    public DocumentController(ApplicationDbContext db, IConfiguration configuration)
    {
        _db = db;
        _storagePath = configuration["Documents:StoragePath"];
    }

    // Reçoit les fichiers envoyés par LgInputFile sur UploadUri.
    [HttpPost("upload")]
    public IActionResult Upload()
    {
        Directory.CreateDirectory(_storagePath);

        foreach (IFormFile file in Request.Form.Files)
        {
            // Crée un identifiant serveur afin de ne jamais réutiliser directement un chemin fourni par le client.
            Document document = new()
            {
                Id = Guid.NewGuid(),
                Name = file.FileName,
                ContentType = string.IsNullOrEmpty(file.ContentType) ? "application/octet-stream" : file.ContentType,
                Size = file.Length
            };

            // Stocke le fichier dans un répertoire configuré et conserve uniquement les métadonnées en base.
            string path = Path.Combine(_storagePath, $"{document.Id}_{document.Name}");
            using FileStream stream = new(path, FileMode.Create, FileAccess.Write);
            file.CopyTo(stream);
            _db.Documents.Add(document);
        }

        _db.SaveChanges();
        return NoContent();
    }
}

GET — Liste des fichiers liés (LinkedFilesUri)

La liste doit retourner des LinkedFile. CanDownload et CanDelete pilotent l'affichage des actions dans le composant.

DocumentController.cs

// Retourne les fichiers liés que LgInputFile doit afficher dans sa zone de téléchargement.
[HttpGet("files")]
public IEnumerable<LinkedFile> GetFiles()
{
    // Charge seulement les métadonnées nécessaires à l'affichage pour éviter de rapatrier les contenus binaires.
    return _db.Documents.Select(document => new LinkedFile
    {
        Id = document.Id,
        Name = document.Name,
        Size = document.Size,
        ContentType = document.ContentType,
        CanDownload = true,
        CanDelete = true
    });
}

Propriété de LinkedFile	Rôle côté client
Id	Ajouté à LinkedFilesUri pour télécharger ou supprimer le fichier.
Name	Nom affiché et nom proposé au téléchargement.
Size	Taille affichée dans la liste.
ContentType	Type MIME retourné par le serveur.
CanDownload	Affiche ou masque l'action de téléchargement.
CanDelete	Affiche ou masque l'action de suppression.

GET — Téléchargement (LinkedFilesUri/{id})

En DownloadMode.Direct ou DownloadMode.NewTab, l'endpoint retourne le flux du fichier. En DownloadMode.PresignedUrl, il retourne une URL sous forme de chaîne.

DocumentController.cs

// Retourne le contenu d'un fichier demandé par LgInputFile depuis LinkedFilesUri/{id}.
[HttpGet("files/{id:guid}")]
public IActionResult GetFile(Guid id)
{
    Document document = _db.Documents.FirstOrDefault(item => item.Id == id);
    if (document is null)
    {
        return NotFound();
    }

    // Reconstruit le chemin depuis l'identifiant serveur ; le client ne transmet jamais de chemin physique.
    string path = Path.Combine(_storagePath, $"{document.Id}_{document.Name}");
    return FileContent(path, document.Name);
}

DELETE — Suppression (LinkedFilesUri/{id})

DocumentController.cs

// Supprime un fichier lié lorsque l'utilisateur clique sur l'action de suppression du composant.
[HttpDelete("files/{id:guid}")]
public IActionResult DeleteFile(Guid id)
{
    Document document = _db.Documents.FirstOrDefault(item => item.Id == id);
    if (document is null)
    {
        return NotFound();
    }

    // Supprime d'abord les métadonnées, puis le fichier physique s'il existe encore.
    _db.Documents.Remove(document);
    _db.SaveChanges();

    string path = Path.Combine(_storagePath, $"{document.Id}_{document.Name}");
    if (System.IO.File.Exists(path))
    {
        System.IO.File.Delete(path);
    }

    return NoContent();
}

Sécurité

N'exposez jamais un endpoint qui reçoit un chemin physique en paramètre. Le client doit seulement manipuler un identifiant (LinkedFile.Id) et le serveur reconstruit le chemin depuis ses propres données.

Sélection et téléversement automatique

UploadMode.Automatic envoie les fichiers dès la sélection si UploadUri est renseigné et si MaxUploadSize est respecté.

DocumentPage.razor

@inherits LgPage

<LgInputFile Label="#Attachments"
             UploadUri="api/documents/upload"
             LinkedFilesUri="api/documents/files"
             UploadMode="UploadMode.Automatic"
             AllowMultipleFiles="true"
             ShowFileList="true" />

Choisir le mode d'envoi

Mode	Comportement
UploadMode.Automatic	Envoi immédiat après sélection.
UploadMode.Button	Affiche un bouton interne de lancement.
UploadMode.Manual	Laisse la page appeler DoUploadAsync() via @ref.

DocumentPage.razor

@inherits LgPage

<LgInputFile @ref="_inputFile"
             Label="#Attachments"
             UploadUri="api/documents/upload"
             UploadMode="UploadMode.Manual"
             OnChange="OnFilesChangedAsync"
             OnUploadComplete="OnUploadCompleteAsync" />

<LgButton Text="#Upload" IconName="@IconNames.All.Upload" OnClick="UploadAsync" />

DocumentPage.razor.cs

public partial class DocumentPage : LgPage
{
    // Référence au composant nécessaire uniquement en mode manuel pour déclencher l'envoi par code.
    private LgInputFile _inputFile;

    // Mémorise la taille sélectionnée afin d'afficher ou de contrôler l'état d'un bouton externe.
    private long _selectedSize;

    // Met à jour les informations locales après chaque changement de sélection.
    private Task OnFilesChangedAsync(IFileListEntry[] files)
    {
        _selectedSize = files.Sum(file => file.Size);
        return Task.CompletedTask;
    }

    // Lance l'upload manuel et intercepte les erreurs via le mécanisme standard de la page.
    private async Task UploadAsync(ActionEventArgs args)
    {
        try
        {
            await _inputFile.DoUploadAsync();
        }
        catch (Exception ex)
        {
            ShowException(ex);
        }
    }

    // Rafraîchit explicitement la liste liée après un upload réussi si d'autres données de la page en dépendent.
    private Task OnUploadCompleteAsync()
    {
        ShowSuccess("#UploadCompleted");
        return Task.CompletedTask;
    }
}

Restreindre les fichiers acceptés

Les restrictions alimentent l'attribut accept et le filtrage côté composant. Elles ne remplacent pas les validations serveur.

DocumentPage.razor

@inherits LgPage

<LgInputFile Label="#Documents"
             UploadUri="api/documents/upload"
             AllowedFileExtensions="@(new List<string> { ".pdf", ".docx" })"
             MaxUploadSize="10485760"
             AllowDuplicate="false" />

<LgInputFile Label="#Images"
             UploadUri="api/documents/upload"
             AllowedFileTypes="@(new List<string> { "image/*" })"
             AllowMultipleFiles="true" />

<LgInputFile Label="#FolderImport"
             UploadUri="api/documents/upload"
             AllowDirectories="true"
             AllowMultipleFiles="true" />

Personnaliser la carte des fichiers sélectionnés

FileCardTemplate reçoit chaque IFileListEntry avant l'envoi. Utilisez-le pour afficher la taille, une icône ou une information projet.

DocumentPage.razor

@inherits LgPage

<LgInputFile Label="#Images"
             UploadUri="api/documents/upload"
             AllowedFileTypes="@(new List<string> { "image/*" })"
             ShowFileList="true">
    <FileCardTemplate Context="file">
        <LgIcon IconName="@IconNames.All.Image" />
        <span>@file.Name</span>
        <span>@Tools.BytesToHumanReadable(file.Size)</span>
    </FileCardTemplate>
</LgInputFile>

Afficher seulement les fichiers liés

Désactivez ShowUpload pour utiliser le composant comme liste de téléchargement/suppression, par exemple sur une fiche déjà validée.

DocumentPage.razor

@inherits LgPage

<LgInputFile Label="#LinkedFiles"
             LinkedFilesUri="api/documents/files"
             ShowUpload="false"
             FileListLabel="#LinkedFileCount"
             DownloadMode="DownloadMode.NewTab"
             VerticalDisplay="false"
             OnDeleteComplete="OnDeleteCompleteAsync" />

DocumentPage.razor.cs

public partial class DocumentPage : LgPage
{
    // Notifie la page après suppression serveur pour mettre à jour d'autres compteurs ou états métier.
    private Task OnDeleteCompleteAsync(LinkedFile file)
    {
        ShowSuccess("#FileDeleted");
        return Task.CompletedTask;
    }
}

Gérer l'authentification et les erreurs

Par défaut, les requêtes utilisent un jeton Bearer. OnTokenRequested permet de fournir explicitement le jeton ; OnErrorHandling permet d'intercepter une erreur d'upload ou de téléchargement.

DocumentPage.razor

@inherits LgPage

<LgInputFile Label="#SecureAttachments"
             UploadUri="api/documents/upload"
             LinkedFilesUri="api/documents/files"
             Authenticate="true"
             OnTokenRequested="GetUploadTokenAsync"
             OnErrorHandling="HandleUploadErrorAsync" />

DocumentPage.razor.cs

public partial class DocumentPage : LgPage
{
    // Fournit un jeton spécifique lorsque les endpoints de fichiers n'utilisent pas le jeton applicatif par défaut.
    private Task<string> GetUploadTokenAsync()
    {
        return App.GetAccessTokenValueAsync();
    }

    // Centralise l'affichage des erreurs de transfert pour ajouter un message métier ou une télémétrie.
    private Task HandleUploadErrorAsync(Exception ex)
    {
        ShowException(ex);
        return Task.CompletedTask;
    }
}

Taille maximale côté serveur

Si le serveur retourne une erreur 413 (RequestEntityTooLarge), augmentez aussi la limite côté hébergement (IIS, reverse proxy ou serveur applicatif). MaxUploadSize ne contrôle que la sélection côté client.

Propriétés

Toutes les propriétés [Parameter] du composant, y compris celles héritées.

Nom	Type	Défaut	Déclaré dans	Description
ActionMessage	string	"#lgFileUploadDragAndDropMessage"	LgInputFile	Message affiché dans la zone de sélection. La valeur est traduite avec CheckTranslate().
AllowDirectories	bool	false	LgInputFile	Autorise la sélection de dossiers via l'attribut webkitdirectory.
AllowDuplicate	bool	true	LgInputFile	Autorise plusieurs fichiers portant le même nom dans la sélection courante.
AllowMultipleFiles	bool	false	LgInputFile	Autorise la sélection de plusieurs fichiers.
AllowedFileExtensions	List<string>	new List<string>()	LgInputFile	Extensions autorisées, utilisées pour l'attribut accept et le filtrage côté composant (ex. .docx).
AllowedFileTypes	List<string>	new List<string>()	LgInputFile	Types MIME autorisés, ajoutés à l'attribut accept (ex. image/*).
Authenticate	bool	true	LgInputFile	Ajoute un jeton Bearer aux requêtes de transfert et de liste si true.
CssClass	string	null	LgInputFile	Classes CSS additionnelles appliquées au conteneur lg-input-file.
DownloadMode	DownloadMode	DownloadMode.Direct	LgInputFile	Mode de téléchargement des fichiers liés.
FileCardTemplate	RenderFragment<IFileListEntry>	null	LgInputFile	Template personnalisé pour afficher chaque fichier sélectionné avant transfert.
FileListLabel	string	"#lgFileUploadLinkedFileList"	LgInputFile	Texte affiché avant la liste des fichiers liés ; reçoit le nombre de fichiers.
IgnoreFormTracking	bool	false	LgInputFile	Ignore le suivi de modification fourni par un LgFormTracker parent.
Label	string	null	LgInputFile	Libellé associé au champ de sélection.
LabelContent	RenderFragment	null	LgInputFile	Contenu personnalisé du libellé.
LinkedFilesUri	string	null	LgInputFile	URI de l'endpoint listant les fichiers déjà liés ; sert aussi de base pour télécharger ou supprimer un fichier par identifiant.
MaxUploadSize	long	-1	LgInputFile	Taille maximale totale, en octets, pour la sélection à transférer. -1 désactive la limite.
OnChange	EventCallback<IFileListEntry[]>	—	LgInputFile	Callback déclenché après modification de la sélection locale.
OnDeleteComplete	EventCallback<LinkedFile>	—	LgInputFile	Callback déclenché après suppression réussie d'un fichier lié.
OnErrorHandling	EventCallback<Exception>	—	LgInputFile	Callback déclenché lorsqu'une erreur survient pendant un transfert ; si absent, l'erreur est affichée par ShowException.
OnTokenRequested	Func<Task<string>>	null	LgInputFile	Callback optionnel qui fournit le jeton Bearer lorsque Authenticate vaut true.
OnUploadComplete	EventCallback	—	LgInputFile	Callback déclenché après téléversement réussi.
ShowFileList	bool	true	LgInputFile	Affiche la liste des fichiers sélectionnés dans la zone de téléversement.
ShowUpload	bool	true	LgInputFile	Active et affiche la zone de sélection/téléversement.
ShowUploadSpeed	bool	false	LgInputFile	Affiche le débit dans le libellé de progression si JavaScript le fournit.
UploadedFailureMessage	string	"lgFileUploadUploadedFailureMessage".Translate()	LgInputFile	Message affiché lorsque le transfert échoue.
UploadingMessage	string	"lgFileUploadUploadingMessage".Translate()	LgInputFile	Message de progression pendant le transfert.
UploadIconName	string	IconNames.UploadBoxIcon	LgInputFile	Icône affichée dans la zone de sélection.
UploadMode	UploadMode	UploadMode.Automatic	LgInputFile	Comportement de lancement du téléversement.
UploadUri	string	null	LgInputFile	URI de l'endpoint recevant les fichiers sélectionnés. Obligatoire pour téléverser.
VerticalDisplay	bool	true	LgInputFile	Affiche la zone de téléversement et la liste des fichiers liés verticalement ; false les place côte à côte.
AriaLabel	string	null	LgAriaComponentBase	Valeur de l'attribut aria-label du groupe.
AriaLabelledBy	string	null	LgAriaComponentBase	Valeur de l'attribut aria-labelledby du groupe.

Paramètres en cascade

LgInputFile consomme aussi FormTracker (LgFormTracker) lorsqu'un ancêtre fournit un suivi de formulaire. Ce paramètre est automatique : utilisez IgnoreFormTracking pour désactiver la participation du composant au suivi de modification.

Événements

Événement	Type	Description
OnChange	EventCallback<IFileListEntry[]>	Déclenché après sélection ou retrait d'un fichier local.
OnDeleteComplete	EventCallback<LinkedFile>	Déclenché après suppression serveur d'un fichier lié.
OnErrorHandling	EventCallback<Exception>	Déclenché lorsqu'une erreur de téléversement ou téléchargement doit être interceptée par la page.
OnUploadComplete	EventCallback	Déclenché après téléversement réussi et réinitialisation de la sélection.

Méthodes publiques

Méthode	Signature	Description
CancelUploadAsync	Task CancelUploadAsync()	Annule le transfert JavaScript direct en cours, vide la sélection locale et remet l'état à ReadyToUpload.
CheckUploadSize	bool CheckUploadSize()	Indique si la taille totale sélectionnée respecte MaxUploadSize.
DoUploadAsync	Task<bool> DoUploadAsync()	Lance le téléversement des fichiers sélectionnés. Retourne true si le transfert direct aboutit.
GetTotalSizeToUpload	long GetTotalSizeToUpload()	Retourne la somme des tailles des fichiers sélectionnés, en octets.
RefreshFilesListAsync	Task RefreshFilesListAsync()	Recharge la liste des fichiers liés à partir de LinkedFilesUri et rafraîchit l'affichage.

Énumérations associées

UploadMode

Valeur	Description
Automatic	Téléverse les fichiers immédiatement après la sélection.
Button	Affiche un bouton interne pour déclencher le téléversement.
Manual	Nécessite un appel explicite à DoUploadAsync().

DownloadMode

Valeur	Description
Direct	L'endpoint retourne le flux du fichier ; le composant télécharge via JavaScript.
PresignedUrl	L'endpoint retourne une URL pré-signée ouverte par le navigateur.
NewTab	Le document est ouvert dans un nouvel onglet.

Accessibilité

• Le composant rend un groupe (role="group") avec aria-label et aria-labelledby issus de AriaLabel et AriaLabelledBy.
• Fournissez Label, LabelContent, AriaLabel ou AriaLabelledBy pour décrire clairement la zone de dépôt.
• Les fichiers sélectionnés et liés sont rendus comme des listes (role="list" / role="listitem") et les erreurs de taille utilisent role="alert".
• Les restrictions AllowedFileExtensions et AllowedFileTypes ne remplacent pas un message utilisateur clair sur les formats attendus.

Composants liés

• LgButton — utilisé pour les actions internes de transfert, réessai et annulation.
• LgLabelAction — associe une valeur affichée à une action contextuelle.