Zachowaj relacje między elementami, składnikami i modelami w usłudze ASP.NET Core Blazor

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję .NET 11 tego artykułu.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core — zasady pomocy technicznej. Aby zapoznać się z aktualną wersją, zobacz artykuł w wersji .NET 10.

W tym artykule wyjaśniono, jak za pomocą atrybutu dyrektywy @key zachować relacje elementów, składników i modelu podczas renderowania, gdy elementy lub składniki następnie ulegają zmianie.

Użycie atrybutu dyrektywy @key

Podczas renderowania listy elementów lub składników, a następnie zmiany tych elementów lub składników, Blazor musi zdecydować, które z poprzednich elementów lub składników są zachowywane i jak obiekty modelu powinny być na nie mapowane. Zwykle ten proces jest automatyczny i wystarczający do ogólnego renderowania, ale często zdarza się, że kontrola procesu przy użyciu atrybutu @key dyrektywy jest wymagana.

Rozważmy poniższy przykład, który demonstruje problem z mapowaniem kolekcji, który został rozwiązany przy użyciu @key.

W przypadku następujących komponentów:

  • Komponent Details odbiera dane (Data) z komponentu nadrzędnego, które są wyświetlane w elemencie <input>. Użytkownik może ustawić fokus strony na dowolnym wyświetlanym elemencie <input>, gdy wybierze jeden z elementów <input>.
  • Komponent nadrzędny tworzy listę obiektów osób do wyświetlenia przy użyciu komponentu Details. Co trzy sekundy do kolekcji jest dodawana nowa osoba.

Ten pokaz umożliwia:

  • Wybierz element <input> spośród kilku renderowanych komponentów Details.
  • Zbadaj zachowanie fokusu strony, gdy kolekcja osób automatycznie powiększa się.

Details.razor:

<input value="@Data" />

@code {
    [Parameter]
    public string? Data { get; set; }
}
<input value="@Data" />

@code {
    [Parameter]
    public string? Data { get; set; }
}
<input value="@Data" />

@code {
    [Parameter]
    public string? Data { get; set; }
}
<input value="@Data" />

@code {
    [Parameter]
    public string? Data { get; set; }
}
<input value="@Data" />

@code {
    [Parameter]
    public string Data { get; set; }
}
<input value="@Data" />

@code {
    [Parameter]
    public string Data { get; set; }
}

W poniższym składniku nadrzędnym każda iteracja dodawania osoby w OnTimerCallback powoduje, że Blazor przebudowuje całą kolekcję. Fokus na stronie pozostaje na tej samej pozycji indeksu elementu <input>, więc fokus przesuwa się za każdym razem, gdy dodawana jest osoba. Przenoszenie fokusu poza element wybrany przez użytkownika nie jest pożądanym zachowaniem. Po zademonstrowaniu niewłaściwego zachowania z użyciem poniższego składnika stosowany jest atrybut dyrektywy @key w celu poprawienia doświadczenia użytkownika.

People.razor:

@page "/people"
@using System.Timers
@implements IDisposable

<PageTitle>People</PageTitle>

<h1>People Example</h1>

@foreach (var person in people)
{
    <Details Data="@person.Data" />
}

@code {
    private Timer timer = new Timer(3000);

    public List<Person> people =
        new()
        {
            { new Person { Data = "Person 1" } },
            { new Person { Data = "Person 2" } },
            { new Person { Data = "Person 3" } }
        };

    protected override void OnInitialized()
    {
        timer.Elapsed += (sender, eventArgs) => OnTimerCallback();
        timer.Start();
    }

    private void OnTimerCallback()
    {
        _ = InvokeAsync(() =>
        {
            people.Insert(0,
                new Person
                {
                    Data = $"INSERTED {DateTime.Now.ToString("hh:mm:ss tt")}"
                });
            StateHasChanged();
        });
    }

    public void Dispose() => timer.Dispose();

    public class Person
    {
        public string? Data { get; set; }
    }
}

People.razor:

@page "/people"
@using System.Timers
@implements IDisposable

<PageTitle>People</PageTitle>

<h1>People Example</h1>

@foreach (var person in people)
{
    <Details Data="@person.Data" />
}

@code {
    private Timer timer = new Timer(3000);

    public List<Person> people =
        new()
        {
            { new Person { Data = "Person 1" } },
            { new Person { Data = "Person 2" } },
            { new Person { Data = "Person 3" } }
        };

    protected override void OnInitialized()
    {
        timer.Elapsed += (sender, eventArgs) => OnTimerCallback();
        timer.Start();
    }

    private void OnTimerCallback()
    {
        _ = InvokeAsync(() =>
        {
            people.Insert(0,
                new Person
                {
                    Data = $"INSERTED {DateTime.Now.ToString("hh:mm:ss tt")}"
                });
            StateHasChanged();
        });
    }

    public void Dispose() => timer.Dispose();

    public class Person
    {
        public string? Data { get; set; }
    }
}

PeopleExample.razor:

@page "/people-example"
@using System.Timers
@implements IDisposable

@foreach (var person in people)
{
    <Details Data="@person.Data" />
}

@code {
    private Timer timer = new Timer(3000);

    public List<Person> people =
        new()
        {
            { new Person { Data = "Person 1" } },
            { new Person { Data = "Person 2" } },
            { new Person { Data = "Person 3" } }
        };

    protected override void OnInitialized()
    {
        timer.Elapsed += (sender, eventArgs) => OnTimerCallback();
        timer.Start();
    }

    private void OnTimerCallback()
    {
        _ = InvokeAsync(() =>
        {
            people.Insert(0,
                new Person
                {
                    Data = $"INSERTED {DateTime.Now.ToString("hh:mm:ss tt")}"
                });
            StateHasChanged();
        });
    }

    public void Dispose() => timer.Dispose();

    public class Person
    {
        public string? Data { get; set; }
    }
}

PeopleExample.razor:

@page "/people-example"
@using System.Timers
@implements IDisposable

@foreach (var person in people)
{
    <Details Data="@person.Data" />
}

@code {
    private Timer timer = new Timer(3000);

    public List<Person> people =
        new()
        {
            { new Person { Data = "Person 1" } },
            { new Person { Data = "Person 2" } },
            { new Person { Data = "Person 3" } }
        };

    protected override void OnInitialized()
    {
        timer.Elapsed += (sender, eventArgs) => OnTimerCallback();
        timer.Start();
    }

    private void OnTimerCallback()
    {
        _ = InvokeAsync(() =>
        {
            people.Insert(0,
                new Person
                {
                    Data = $"INSERTED {DateTime.Now.ToString("hh:mm:ss tt")}"
                });
            StateHasChanged();
        });
    }

    public void Dispose() => timer.Dispose();

    public class Person
    {
        public string? Data { get; set; }
    }
}

PeopleExample.razor:

@page "/people-example"
@using System.Timers
@implements IDisposable

@foreach (var person in people)
{
    <Details Data="@person.Data" />
}

@code {
    private Timer timer = new Timer(3000);

    public List<Person> people =
        new()
        {
            { new Person { Data = "Person 1" } },
            { new Person { Data = "Person 2" } },
            { new Person { Data = "Person 3" } }
        };

    protected override void OnInitialized()
    {
        timer.Elapsed += (sender, eventArgs) => OnTimerCallback();
        timer.Start();
    }

    private void OnTimerCallback()
    {
        _ = InvokeAsync(() =>
        {
            people.Insert(0,
                new Person
                {
                    Data = $"INSERTED {DateTime.Now.ToString("hh:mm:ss tt")}"
                });
            StateHasChanged();
        });
    }

    public void Dispose() => timer.Dispose();

    public class Person
    {
        public string Data { get; set; }
    }
}

PeopleExample.razor:

@page "/people-example"
@using System.Timers
@implements IDisposable

@foreach (var person in people)
{
    <Details Data="@person.Data" />
}

@code {
    private Timer timer = new Timer(3000);

    public List<Person> people =
        new List<Person>()
        {
            { new Person { Data = "Person 1" } },
            { new Person { Data = "Person 2" } },
            { new Person { Data = "Person 3" } }
        };

    protected override void OnInitialized()
    {
        timer.Elapsed += (sender, eventArgs) => OnTimerCallback();
        timer.Start();
    }

    private void OnTimerCallback()
    {
        _ = InvokeAsync(() =>
        {
            people.Insert(0,
                new Person
                {
                    Data = $"INSERTED {DateTime.Now.ToString("hh:mm:ss tt")}"
                });
            StateHasChanged();
        });
    }

    public void Dispose() => timer.Dispose();

    public class Person
    {
        public string Data { get; set; }
    }
}

Zawartość kolekcji people zmienia się przy wstawieniu, usunięciu lub zmianie kolejności wpisów. Ponowne renderowanie może prowadzić do widocznych różnic w zachowaniu. Na przykład za każdym razem, gdy osoba zostanie wstawiona do kolekcji people, fokus użytkownika zostanie utracony.

Proces mapowania elementów lub składników na kolekcję można kontrolować atrybutem dyrektywy @key. Użycie atrybutu @key gwarantuje zachowywanie elementów lub składników na podstawie wartości klucza. Jeśli składnik Details w powyższym przykładzie ma klucz oparty na elemencie person, Blazor ignoruje ponowne renderowanie składników Details, które nie uległy zmianie.

Aby zmodyfikować komponent nadrzędny tak, aby używał atrybutu dyrektywy @key z kolekcją people, zaktualizuj element <Details> do następującego:

<Details @key="person" Data="@person.Data" />

Gdy zmienia się kolekcja people, zachowywane jest skojarzenie między wystąpieniami Details i wystąpieniami person. Gdy element Person jest wstawiany na początku kolekcji, jedno nowe wystąpienie elementu Details jest wstawiane na odpowiedniej pozycji. Inne wystąpienia pozostają bez zmian. Dlatego uwaga użytkownika nie zostaje rozproszona, gdy osoby są dodawane do kolekcji.

Inne aktualizacje kolekcji wykazują takie samo zachowanie, gdy jest używany atrybut dyrektywy @key:

  • Jeśli wystąpienie zostanie usunięte z kolekcji, tylko odpowiednie wystąpienie składnika zostanie usunięte z interfejsu użytkownika. Inne wystąpienia pozostają bez zmian.
  • Gdy kolejność wpisów kolekcji ulega zmianie, odpowiadające im instancje komponentów są zachowywane, a ich kolejność w interfejsie użytkownika jest zmieniana.

Ważne

Klucze są lokalne dla każdego elementu kontenera lub komponentu. Klucze nie są porównywane globalnie w całym dokumencie.

Kiedy używać @key

Zazwyczaj warto używać atrybutu @key zawsze, gdy jest renderowana lista (np. w bloku foreach) i istnieje odpowiednia wartość do zdefiniowania atrybutu @key.

Można też używać @key, aby zachowywać poddrzewo elementu lub składnika, gdy dany obiekt nie zmienia się, jak pokazują poniższe przykłady.

Przykład 1:

<li @key="person">
    <input value="@person.Data" />
</li>

Przykład 2:

<div @key="person">
    @* other HTML elements *@
</div>

Jeśli zmieni się wystąpienie elementu person, dyrektywa atrybutu @key wymusza na Blazor:

  • Odrzuć cały element <li> lub <div> oraz ich elementy podrzędne.
  • Przebuduj poddrzewo w interfejsie użytkownika przy użyciu nowych elementów i składników.

Jest to przydatne, aby zagwarantować, że żaden stan interfejsu użytkownika nie zostanie zachowany, gdy kolekcja zmieni się w obrębie poddrzewa.

Zakres @key

Dyrektywa atrybutu @key jest ograniczona do własnych elementów równorzędnych w obrębie elementu nadrzędnego.

Rozważmy następujący przykład. Klucze first i second są porównywane ze sobą w tym samym zakresie zewnętrznego elementu <div>:

<div>
    <div @key="first">...</div>
    <div @key="second">...</div>
</div>

Poniższy przykład przedstawia elementy first i second w ich własnych zakresach, niepowiązanych ze sobą i niemających na siebie wpływu. Zakres każdego atrybutu @key dotyczy tylko jego nadrzędnego elementu <div>, a nie rozciąga się na nadrzędne elementy <div>:

<div>
    <div @key="first">...</div>
</div>
<div>
    <div @key="second">...</div>
</div>

Dla przedstawionego wcześniej składnika Details poniższe przykłady renderują dane elementów person w obrębie tego samego zakresu @key oraz pokazują typowe przypadki użycia @key:

<div>
    @foreach (var person in people)
    {
        <Details @key="person" Data="@person.Data" />
    }
</div>
@foreach (var person in people)
{
    <div @key="person">
        <Details Data="@person.Data" />
    </div>
}
<ol>
    @foreach (var person in people)
    {
        <li @key="person">
            <Details Data="@person.Data" />
        </li>
    }
</ol>

Poniższe przykłady ograniczają zakres atrybutu @key tylko do elementu <div> lub <li>, który otacza każde wystąpienie składnika Details. Dlatego dane elementów person dla każdego elementu kolekcji peoplenie są kluczowane względem każdego wystąpienia elementu person we wszystkich renderowanych składnikach Details. Podczas używania @key należy unikać następujących wzorców:

@foreach (var person in people)
{
    <div>
        <Details @key="person" Data="@person.Data" />
    </div>
}
<ol>
    @foreach (var person in people)
    {
        <li>
            <Details @key="person" Data="@person.Data" />
        </li>
    }
</ol>

Kiedy nie używać @key

Renderowanie przy użyciu @key wiąże się z obciążeniem wydajnościowym. Spadek wydajności nie jest duży, ale @key należy określać tylko wtedy, gdy zachowanie elementu lub składnika przynosi korzyści aplikacji.

Nawet jeśli atrybut @key nie jest używany, platforma Blazor zachowuje wystąpienia elementów podrzędnych i instancji komponentów, na ile to możliwe. Jedyną zaletą używania atrybutu @key jest kontrola nad tym, jak wystąpienia modelu są mapowane na zachowywane wystąpienia składników, zamiast aby Blazor wybierał mapowanie.

Wartości do użycia dla @key

Ogólnie rzecz biorąc, ma sens podać jedną z następujących wartości dla @key:

  • Instancje obiektów modelu. Na przykład we wcześniejszym przykładzie użyto instancji Person (person). Zapewnia to zachowanie oparte na równości odwołań do obiektów.
  • Unikatowe identyfikatory. Na przykład unikatowe identyfikatory mogą być oparte na wartościach klucza podstawowego typu int, string lub Guid.

Upewnij się, że wartości używane dla @key nie kolidują ze sobą. Jeśli zostaną wykryte kolidujące wartości w obrębie tego samego elementu nadrzędnego, Blazor zgłosi wyjątek, ponieważ nie będzie mogło deterministycznie mapować starych elementów lub składników na nowe elementy lub składniki. Używaj tylko unikatowych wartości, takich jak wystąpienia obiektów lub wartości klucza podstawowego.