ASP.NET Core Blazor 템플릿 기반 구성 요소

로버트 하켄

이 문서에서는 템플릿 기반 구성 요소에서 하나 이상의 UI 템플릿을 매개 변수로 허용한 다음, 이 매개 변수를 구성 요소 렌더링 논리의 일부로 사용할 수 있는 방법을 설명합니다.

템플릿 기반 구성 요소

템플릿 구성 요소는 하나 이상의 UI 템플릿을 매개 변수로 수신하는 구성 요소이며, 구성 요소의 렌더링 논리에서 활용할 수 있습니다. 템플릿 기반 구성 요소를 사용하면 더 재사용 가능한 상위 수준 구성 요소를 만들 수 있습니다. 예를 들면 다음과 같습니다.

• 사용자가 테이블의 헤더, 행, 바닥글의 템플릿을 지정할 수 있게 해주는 테이블 구성 요소
• 사용자가 목록으로 항목을 렌더링하기 위한 템플릿을 지정할 수 있게 해주는 목록 구성 요소
• 사용자가 시작 콘텐츠 및 탐색 링크에 대한 템플릿을 지정할 수 있도록 하는 탐색 모음 구성 요소입니다.

템플릿 기반 구성 요소는 RenderFragment 또는 RenderFragment<TValue> 형식의 구성 요소 매개 변수를 하나 이상 지정하여 정의합니다. 렌더링 조각은 렌더링할 UI 세그먼트를 나타냅니다. RenderFragment<TValue>는 렌더링 조각을 호출할 때 지정할 수 있는 형식 매개 변수를 사용합니다.

참고 항목

RenderFragment에 대한 자세한 내용은 ASP.NET Core Razor 구성 요소를 참조하세요.

템플릿 구성 요소는 다음 구성 요소(TemplatedNavBar.razor)에서 TemplatedNavBar 보여 주듯이 일반적으로 형식이 지정되는 경우가 많습니다. 다음 예제의 제네릭 형식(<T>)은 값을 렌더링 IReadOnlyList<T> 하는 데 사용됩니다. 이 경우 애완 동물 세부 구성 요소에 대한 링크가 있는 탐색 모음을 표시하는 구성 요소의 애완 동물 목록입니다.

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!;
}

템플릿 기반 구성 요소를 사용하는 경우, 매개 변수 이름과 일치하는 자식 요소를 사용하여 템플릿 매개 변수를 지정할 수 있습니다. 다음 예제에서는 <StartContent>...</StartContent> 및 <ItemTemplate>...</ItemTemplate>이 TemplatedNavBar 구성 요소의 StartContent 및 ItemTemplate용 RenderFragment<TValue> 템플릿을 제공합니다.

래핑 자식 요소 없이 암시적 자식 콘텐츠의 콘텐츠 매개 변수 이름을 지정하려는 경우 구성 요소에서 Context 특성을 지정합니다. 다음 예제에서 Context 특성은 TemplatedNavBar 요소에 표시되고 모든 RenderFragment<TValue> 템플릿 매개 변수에 적용됩니다.

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; }
    }
}

또는 RenderFragment<TValue> 자식 요소의 Context 특성을 사용하여 매개 변수 이름을 변경할 수 있습니다. 다음 예제에서는 이 설정이 Context 아니라 TemplatedNavBar설정 ItemTemplate 됩니다.

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; }
    }
}

RenderFragment<TValue> 형식의 구성 요소 인수에 context라는 암시적 매개 변수가 있는데, 이것을 사용할 수 있습니다. 다음 예제에서는 Context가 설정되어 있지 않습니다. @context.{PROPERTY}는 템플릿에 애완동물 값을 제공합니다. 여기서 {PROPERTY}는 Pet 속성입니다.

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; }
    }
}

제네릭 형식 구성 요소를 사용할 때 가능한 경우 형식 매개 변수가 유추됩니다. 그러나 형식 매개 변수와 일치하는 이름이 있는 특성을 사용하여 형식을 명시적으로 지정할 수 있습니다(이전 예제의 TItem).

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; }
    }
}

구성 요소()에 TemplatedNavBar 제공된 예제에서는 컬렉션이 Items 초기 렌더링 후에 변경되지 않거나 컬렉션이 변경될 경우 사용된 ItemTemplate 구성 요소/요소의 상태를 유지할 필요가 없다고 가정TemplatedNavBar.razor합니다. 이러한 사용을 예상할 수 없는 템플릿 구성 요소는 섹션과의 @key 관계 유지를 참조하세요.

과의 관계 유지 @key

템플릿 구성 요소는 테이블 또는 목록과 같은 항목 컬렉션을 렌더링하는 데 자주 사용됩니다. 이러한 일반적인 시나리오에서는 사용자가 항목 템플릿 정의에서 상태 저장 구성 요소/요소를 방지하거나 컬렉션에 대한 추가 변경 내용이 없다고 가정할 Items 수 없습니다. 이러한 템플릿 구성 요소의 경우 지시문 특성과의 @key 관계를 유지해야 합니다.

참고 항목

지시문 특성에 대한 @key 자세한 내용은 ASP.NET Core의 Retain 요소, 구성 요소 및 모델 관계를 참조하세요Blazor.

다음 TableTemplate 구성 요소(TableTemplate.razor)는 @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!;
}

모델 관계를 유지하기 위해 키 지정 데이터의 중요성을 보여 주는 다음 Pets5 구성 요소(Pets5.razor)를 고려합니다. 구성 요소에서 애완 동물을 추가하는 각 반복은 OnAfterRenderAsync Blazor 구성 요소를 다시 렌더링합니다 TableTemplate .

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; }
    }
}

이 데모에서는 다음을 수행할 수 있습니다.

• 렌더링된 <input> 여러 테이블 행 중에서 선택합니다.
• 애완 동물 컬렉션이 자동으로 커짐에 따라 페이지의 포커스 동작을 연구합니다.

구성 요소에서 @key TableTemplate 지시문 특성을 사용하지 않으면 페이지의 포커스가 테이블의 동일한 인덱스 위치(행)에 유지되므로 애완 동물이 추가 될 때마다 포커스가 이동합니다. 이를 보여 주려면 지시문 특성 및 값을 제거하고 @key , 앱을 다시 시작하고, 항목이 추가되면 필드 값을 수정하려고 시도합니다.

추가 리소스

• ASP.NET Core Blazor 성능 모범 사례
• ASP.NET Core에서 요소, 구성 요소 및 모델 관계 유지 Blazor
• Blazor샘플 GitHub 리포지토리()(dotnet/blazor-samples다운로드 방법)