componenti ASP.NET core Blazor basato su modelli

Di Robert Haken

Questo articolo illustra in che modo i componenti modelli possono accettare uno o più modelli di interfaccia utente come parametri, che possono quindi essere usati come parte della logica di rendering del componente.

Componenti basati su modelli

I componenti modello sono componenti che ricevono uno o più modelli di interfaccia utente come parametri, che possono essere utilizzati nella logica di rendering del componente. Usando i componenti basati su modelli, è possibile creare componenti di livello superiore più riutilizzabili. Alcuni esempi:

• Componente di tabella che consente a un utente di specificare modelli per l'intestazione, le righe e il piè di pagina della tabella.
• Componente elenco che consente a un utente di specificare un modello per il rendering degli elementi in un elenco.
• Componente della barra di spostamento che consente a un utente di specificare un modello per avviare il contenuto e i collegamenti di spostamento.

Un componente basato su modelli viene definito specificando uno o più parametri del componente di tipo RenderFragment o RenderFragment<TValue>. Un frammento di rendering rappresenta un segmento dell'interfaccia utente di cui eseguire il rendering. RenderFragment<TValue> accetta un parametro di tipo che può essere specificato quando viene richiamato il frammento di rendering.

Nota

Per altre informazioni su RenderFragment, vedere ASP.NET Componenti di baseRazor.

Spesso, i componenti modello sono tipizzato in modo generico, come illustrato nel componente seguente TemplatedNavBar (TemplatedNavBar.razor). Il tipo generico (<T>) nell'esempio seguente viene usato per eseguire il rendering IReadOnlyList<T> dei valori, che in questo caso è un elenco di animali domestici per un componente che visualizza una barra di spostamento con collegamenti a un componente dettagli animale domestico.

TemplatedNavBar.razor:

@typeparam TItem

<nav class="navbar navbar-expand navbar-light bg-light">
    <div class="container justify-content-start">
        @StartContent
        <div class="navbar-nav">
            @foreach (var item in Items)
            {
                @ItemTemplate(item)
            }
        </div>
    </div>
</nav>

@code {
    [Parameter]
    public RenderFragment? StartContent { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> ItemTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Quando si usa un componente basato su modelli, è possibile specificare i parametri del modello usando elementi figlio che corrispondono ai nomi dei parametri. Nell'esempio <StartContent>...</StartContent> seguente e <ItemTemplate>...</ItemTemplate> fornire RenderFragment<TValue> modelli per StartContent e ItemTemplate del TemplatedNavBar componente.

Specificare l'attributo nell'elemento Context componente quando si desidera specificare il nome del parametro di contenuto per il contenuto figlio implicito (senza alcun elemento figlio di wrapping). Nell'esempio seguente l'attributo Context viene visualizzato nell'elemento TemplatedNavBar e si applica a tutti i RenderFragment<TValue> parametri del modello.

Pets1.razor:

@page "/pets-1"

<PageTitle>Pets 1</PageTitle>

<h1>Pets Example 1</h1>

<TemplatedNavBar Items="pets" Context="pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-1")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

In alternativa, è possibile modificare il nome del parametro usando l'attributo nell'elemento ContextRenderFragment<TValue> figlio. Nell'esempio seguente l'oggetto Context è impostato su ItemTemplate anziché TemplatedNavBarsu .

Pets2.razor:

@page "/pets-2"

<PageTitle>Pets 2</PageTitle>

<h1>Pets Example 2</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate Context="pet">
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-2")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Gli argomenti del componente di tipo RenderFragment<TValue> hanno un parametro implicito denominato context, che può essere usato. Nell'esempio Context seguente non è impostato. @context.{PROPERTY} fornisce valori per animali domestici al modello, dove {PROPERTY} è una Pet proprietà:

Pets3.razor:

@page "/pets-3"

<PageTitle>Pets 3</PageTitle>

<h1>Pets Example 3</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{context.PetId}?ReturnUrl=%2Fpets-3")" class="nav-link">
            @context.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Quando si usano componenti tipizzato generico, il parametro di tipo viene dedotto, se possibile. Tuttavia, è possibile specificare in modo esplicito il tipo con un attributo con un nome corrispondente al parametro di tipo , che si trova TItem nell'esempio precedente:

Pets4.razor:

@page "/pets-4"

<PageTitle>Pets 4</PageTitle>

<h1>Pets Example 4</h1>

<TemplatedNavBar Items="pets" Context="pet" TItem="Pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-4")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 2, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 4, Name = "Salem Saberhagen" },
        new Pet { PetId = 7, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

L'esempio TemplatedNavBar fornito nel componente (TemplatedNavBar.razor) presuppone che la Items raccolta non venga modificata dopo il rendering iniziale o che, se cambia, mantenere lo stato dei componenti o degli elementi usati in ItemTemplate non è necessario. Per i componenti modello in cui non è possibile prevedere tale utilizzo, vedere la sezione Mantenere le relazioni con @key .

Mantenere le relazioni con @key

I componenti modelli vengono spesso usati per eseguire il rendering di raccolte di elementi, ad esempio tabelle o elenchi. In questi scenari generali, non è possibile presupporre che l'utente eviterà componenti/elementi con stato nella definizione del modello di elemento o che non ci saranno modifiche aggiuntive alla Items raccolta. Per tali componenti basato su modelli, è necessario mantenere le relazioni con l'attributo della @key direttiva.

Nota

Per altre informazioni sull'attributo @key della direttiva, vedere Mantenere le relazioni tra elementi, componenti e modelli in ASP.NET Core Blazor.

Il componente seguente TableTemplate (TableTemplate.razor) illustra un componente basato su modelli che mantiene le relazioni con @key.

TableTemplate.razor:

@typeparam TItem

<table class="table">
    <thead>
        <tr>@TableHeader</tr>
    </thead>
    <tbody>
        @foreach (var item in Items)
        {
            <tr @key="@item">@RowTemplate(item)</tr>
        }
    </tbody>
</table>

@code {
    [Parameter]
    public RenderFragment? TableHeader { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> RowTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Si consideri il componente seguente Pets5 (Pets5.razor), che dimostra l'importanza della chiave dei dati per mantenere le relazioni del modello. Nel componente, ogni iterazione dell'aggiunta di un animale domestico comporta OnAfterRenderAsyncBlazor il rerendering del TableTemplate componente.

Pets5.razor:

@page "/pets-5"

<PageTitle>Pets 5</PageTitle>

<h1>Pets Example 5</h1>

<TableTemplate Items="pets" Context="pet">
    <TableHeader>
        <th>ID</th>
        <th>Name</th>
    </TableHeader>
    <RowTemplate>
        <td><input value="@pet.PetId" /></td>
        <td><input value="@pet.Name" /></td>
    </RowTemplate>
</TableTemplate>


@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        // Insert new pet every 5 seconds
        if (pets.Count < 10)
        {
            await Task.Delay(5000);
            pets.Insert(0, new Pet() { PetId = pets.Count + 1, Name = "<new pet>" });
            StateHasChanged();
        }
    }

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Questa dimostrazione consente di:

• Selezionare un oggetto <input> tra diverse righe di tabella di cui è stato eseguito il rendering.
• Studiare il comportamento dello stato attivo della pagina man mano che la raccolta di animali domestici cresce automaticamente.

Senza usare l'attributo @key direttiva nel TableTemplate componente, lo stato attivo della pagina rimane sulla stessa posizione di indice (riga) della tabella, causando lo spostamento dello stato attivo ogni volta che viene aggiunto un animale domestico. Per dimostrare questo problema, rimuovere l'attributo e il valore della @key direttiva, riavviare l'app e tentare di modificare un valore di campo man mano che vengono aggiunti elementi.

Risorse aggiuntive

• procedure consigliate per le prestazioni principali Blazor di ASP.NET
• Mantenere le relazioni tra elementi, componenti e modelli in ASP.NET Core Blazor
• Blazorrepository GitHub di esempi () (dotnet/blazor-samplescome scaricare)