ASP.NET 핵심 BlazorQuickGrid 구성 요소

구성 QuickGrid 요소는 데이터를 테이블 형식으로 Razor 빠르고 효율적으로 표시하기 위한 구성 요소입니다. QuickGrid는 공통 그리드 렌더링 시나리오를 위한 간단하고 편리한 데이터 그리드 구성 요소를 제공하며, 데이터 그리드 구성 요소를 빌드하기 위한 참조 아키텍처 및 성능 기준 역할을 합니다. QuickGrid는 고도로 최적화되었으며 고급 기술을 사용하여 최적의 렌더링 성능을 달성합니다.

Package(패키지)

패키지에 대한 패키지 참조를 추가합니다 Microsoft.AspNetCore.Components.QuickGrid .

참고 항목

.NET 앱에 패키지를 추가하는 방법에 대한 지침은 패키지 사용 워크플로에서 패키지 설치 및 관리의 문서(NuGet 설명서)를 참조하세요. NuGet.org에서 올바른 패키지 버전을 확인합니다.

샘플 앱

다양한 QuickGrid 데모는 샘플 앱에 대한 QuickGrid를 Blazor 참조하세요. 데모 사이트는 GitHub Pages에서 호스트됩니다. 사이트는 커뮤니티에서 유지 관리하는 BlazorWasmPrerendering.Build GitHub 프로젝트를 사용하는 정적 미리 렌더링 덕분에 빠르게 로드됩니다.

QuickGrid 구현

구성 요소를 구현하려면 다음을 수행 QuickGrid 합니다.

• 태그(<QuickGrid>...</QuickGrid>)에서 구성 요소에 RazorQuickGrid 대한 태그를 지정합니다.
• 그리드에 대한 쿼리 가능한 데이터 원본의 이름을 지정합니다. 다음 데이터 원본 중 하나를 사용합니다.
  • Items: nullable IQueryable<TGridItem>입니다. 여기에서 TGridItem 표의 각 행이 나타내는 데이터 형식입니다.
  • ItemsProvider: 그리드에 대한 데이터를 제공하는 콜백입니다.
• Class: 선택적 CSS 클래스 이름입니다. 제공된 경우 클래스 이름은 렌더링된 테이블의 특성에 포함 class 됩니다.
• Theme: 테마 이름(기본값: default)입니다. 이는 테이블과 일치하는 스타일 지정 규칙에 영향을 줍니다.
• Virtualize: true이면 그리드가 가상화로 렌더링됩니다. 일반적으로 스크롤과 함께 사용되며 그리드가 현재 스크롤 뷰포트 주위의 데이터만 가져오고 렌더링합니다. 이렇게 하면 큰 데이터 집합을 스크롤할 때 성능이 크게 향상될 수 있습니다. 사용하는 Virtualize경우 값을 ItemSize 제공해야 하며 모든 행이 일정한 높이로 렌더링되도록 해야 합니다. 일반적으로 렌더링된 데이터의 양이 작거나 페이지 매김을 사용하는 경우 사용하지 Virtualize 않는 것이 좋습니다.
• ItemSize: 를 사용하는 Virtualize경우에만 적용됩니다. ItemSize 는 각 행에 대해 예상 높이를 픽셀 단위로 정의하여 가상화 메커니즘이 표시 크기와 일치하고 정확한 스크롤을 보장하기 위해 올바른 개수의 항목을 가져올 수 있도록 합니다.
• ItemKey: 필요에 따라 렌더링된 각 행에 대한 @key 값을 정의합니다. 일반적으로 각 데이터 항목에 대해 기본 키 값과 같은 고유 식별자를 지정하는 데 사용됩니다. 이렇게 하면 기본 데이터 저장소에 대한 새 쿼리 후와 같이 인스턴스가 새 복사본으로 대체되는 경우에도 TGridItem 고유 식별자를 기반으로 행 요소와 데이터 항목 간의 연결을 유지할 수 있습니다. 설정 @key 하지 않으면 인스턴스입니다 TGridItem .
• Pagination: 필요에 따라 이 TGridItem 인스턴스를 PaginationState 모델과 연결하여 그리드가 현재 데이터 페이지만 가져오고 렌더링합니다. 일반적으로 제공된 PaginationState 인스턴스를 Paginator 표시하고 업데이트하는 구성 요소 또는 다른 UI 논리와 함께 사용됩니다.
• QuickGrid 자식 콘텐츠(RenderFragment)에서 셀에 값이 표시되는 열을 나타내는 TGridItem s를 지정PropertyColumn<TGridItem,TProp>합니다.
  • Property: 이 열의 셀에 표시할 값을 정의합니다.
  • Format: 필요에 따라 값의 형식 문자열을 지정합니다. 를 사용 Format 하려면 형식을 TProp 구현 IFormattable해야 합니다.
  • Sortable: 이 열을 기준으로 데이터를 정렬할 수 있는지 여부를 나타냅니다. 기본값은 열 형식에 따라 달라질 수 있습니다. 예를 들어 매개 변수가 TemplateColumn<TGridItem> 지정된 경우 SortBy 기본적으로 정렬할 수 있습니다.
  • InitialSortDirection: 정렬 방향을 나타냅니다(있는 경우 IsDefaultSortColumntrue).
  • IsDefaultSortColumn: 이 열을 기본적으로 정렬해야 하는지 여부를 나타냅니다.
  • PlaceholderTemplate: 지정된 경우 가상화된 그리드는 이 템플릿을 사용하여 데이터가 로드되지 않은 셀을 렌더링합니다.

예를 들어 다음 구성 요소를 추가하여 그리드를 렌더링합니다.

구성 요소는 대화형 서버 렌더링 모드(InteractiveServer)가 부모 구성 요소에서 상속되거나 앱에 전역적으로 적용되어 대화형 기능을 사용하도록 설정된다고 가정합니다. 다음 예제에서 유일한 대화형 기능은 정렬 가능한 열입니다.

PromotionGrid.razor:

@page "/promotion-grid"
@using Microsoft.AspNetCore.Components.QuickGrid

<PageTitle>Promotion Grid</PageTitle>

<h1>Promotion Grid Example</h1>

<QuickGrid Items="@people">
    <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
    private record Person(int PersonId, string Name, DateOnly PromotionDate);

    private IQueryable<Person> people = new[]
    {
        new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
        new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
        new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
        new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
        new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
        new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
    }.AsQueryable();
}

상대 경로 /promotion-grid에서 브라우저의 구성 요소에 액세스합니다.

본격적인 상용 그리드가 제공하는 기능(예: 계층 구조 행, 순서를 다시 정렬하는 열 또는 Excel과 유사한 범위 선택)으로 QuickGrid을 확장할 계획은 현재 없습니다. 직접 개발하지 않을 고급 기능이 필요한, 경우 타사 그리드를 계속 사용합니다.

사용자 지정 특성 및 스타일

QuickGrid는 또한 사용자 지정 특성 및 스타일 클래스를 렌더링된 테이블 요소에 전달하도록 지원합니다.

<QuickGrid Items="..." custom-attribute="value" class="custom-class">

Entity Framework Core(EF Core) 데이터 원본

EF Core'는 데이터베이스의 DbContextDbSet<TEntity> 각 테이블에 대한 속성을 제공합니다. 매개 변수에 속성을 Items 제공합니다.

다음 예제에서는 (테이블)를 PeopleDbSet<TEntity> 데이터 원본으로 사용합니다.

@inject ApplicationDbContext AppDbContext

<QuickGrid Items="@AppDbContext.People">
    ...
</QuickGrid>

EF 지원 LINQ 연산자를 사용하여 데이터를 매개 변수에 전달하기 전에 필터링할 Items 수도 있습니다.

다음 예제에서는 범주 ID로 문서를 필터링합니다.

<QuickGrid Items="@AppDbContext.Documents.Where(d => d.CategoryId == categoryId)">
    ...
</QuickGrid>

QuickGrid는 EF 제공 IQueryable 인스턴스를 인식하고 효율성을 위해 쿼리를 비동기적으로 해결하는 방법을 알고 있습니다.

먼저 NuGet 패키지에 대한 패키지 참조를 Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter 추가합니다.

참고 항목

.NET 앱에 패키지를 추가하는 방법에 대한 지침은 패키지 사용 워크플로에서 패키지 설치 및 관리의 문서(NuGet 설명서)를 참조하세요. NuGet.org에서 올바른 패키지 버전을 확인합니다.

파일의 서비스 컬렉션을 Program 호출 AddQuickGridEntityFrameworkAdapter 하여 EF 인식 IAsyncQueryExecutor 구현을 등록합니다.

builder.Services.AddQuickGridEntityFrameworkAdapter();

원격 데이터

앱에서 Blazor WebAssembly 서버의 JSON 기반 웹 API에서 데이터를 가져오는 것이 일반적인 요구 사항입니다. 데이터의 현재 페이지/뷰포트에 필요한 데이터만 가져오고 서버에서 정렬 또는 필터링 규칙을 적용하려면 매개 변수를 ItemsProvider 사용합니다.

ItemsProvider외부 엔드포인트를 쿼리하는 데 앱이 필요한 경우 또는 요구 사항이 적용되지 IQueryable않는 다른 경우 서버 쪽 Blazor 앱에서도 사용할 수 있습니다.

대리자 형식과 GridItemsProvider<TGridItem> 일치하는 콜백을 제공합니다. 여기에서 TGridItem 표에 표시되는 데이터 형식입니다. 콜백에는 반환할 데이터의 시작 인덱스, 최대 행 수 및 정렬 순서를 지정하는 형식 GridItemsProviderRequest<TGridItem>의 매개 변수가 지정됩니다. 일치하는 항목을 반환하는 것 외에도 페이징 및 가상화가 올바르게 작동하려면 총 항목 수(totalItemCount)가 필요합니다.

다음 예제에서는 공용 OpenFDA 식품 적용 데이터베이스에서 데이터를 가져옵니다.

OpenFDA GridItemsProvider<TGridItem> 데이터베이스에 대한 쿼리로 변환합니다 GridItemsProviderRequest<TGridItem> . 쿼리 매개 변수는 외부 JSON API에서 지원하는 특정 URL 형식으로 변환됩니다. 외부 API에서 지원하는 정렬 및 필터링을 통해서만 정렬 및 필터링을 수행할 수 있습니다. OpenFDA 엔드포인트는 정렬을 지원하지 않으므로 정렬 가능한 것으로 표시된 열이 없습니다. 그러나 레코드(skip 매개 변수)를 건너뛰고 레코드limit (매개 변수)의 반환을 제한하도록 지원하므로 구성 요소는 가상화를 사용하도록 설정하고 수만 개 레코드를 빠르게 스크롤할 수 있습니다.

FoodRecalls.razor:

@page "/food-recalls"
@inject HttpClient Http
@inject NavigationManager NavManager

<PageTitle>Food Recalls</PageTitle>

<h1>OpenFDA Food Recalls</h1>

<div class="grid" tabindex="-1">
    <QuickGrid ItemsProvider="@foodRecallProvider" Virtualize="true">
        <PropertyColumn Title="ID" Property="@(c => c.Event_Id)" />
        <PropertyColumn Property="@(c => c.State)" />
        <PropertyColumn Property="@(c => c.City)" />
        <PropertyColumn Title="Company" Property="@(c => c.Recalling_Firm)" />
        <PropertyColumn Property="@(c => c.Status)" />
    </QuickGrid>
</div>

<p>Total: <strong>@numResults results found</strong></p>

@code {
    GridItemsProvider<FoodRecall>? foodRecallProvider;
    int numResults;

    protected override async Task OnInitializedAsync()
    {
        foodRecallProvider = async req =>
        {
            var url = NavManager.GetUriWithQueryParameters(
                "https://api.fda.gov/food/enforcement.json", 
                new Dictionary<string, object?>
            {
                { "skip", req.StartIndex },
                { "limit", req.Count },
            });

            var response = await Http.GetFromJsonAsync<FoodRecallQueryResult>(
                url, req.CancellationToken);

            return GridItemsProviderResult.From(
                items: response!.Results,
                totalItemCount: response!.Meta.Results.Total);
        };

        numResults = (await Http.GetFromJsonAsync<FoodRecallQueryResult>(
            "https://api.fda.gov/food/enforcement.json"))!.Meta.Results.Total;
    }
}

웹 API 호출에 대한 자세한 내용은 ASP.NET Core Blazor 앱에서 웹 API 호출을 참조하세요.

QuickGrid 스캐폴더

Visual Studio의 QuickGrid 스캐폴더는 구성 요소를 QuickGrid 스캐폴드 Razor 하여 데이터베이스의 데이터를 표시합니다.

스캐폴더를 사용하려면 솔루션 탐색기 프로젝트를 마우스 오른쪽 단추로 클릭하고 새 스캐폴드 항목 추가>를 선택합니다. 설치된>공통>Razor 구성 요소를 엽니다. CRUD(Entity Framework)를 사용하여 구성 요소를 선택합니다.Razor

스캐폴더는 Entity Framework Core 데이터 모델을 기반으로 CRUD(기본 만들기, 읽기, 업데이트 및 삭제) 페이지를 생성합니다. 개별 페이지 또는 모든 CRUD 페이지를 스캐폴드할 수 있습니다. 모델 클래스를 DbContext선택하고 필요에 따라 새 DbContext 클래스를 만듭니다.

스캐폴드된 Razor 구성 요소는 모델 클래스의 이름을 따서 명명된 생성된 폴더의 Pages 프로젝트 폴더에 추가됩니다. 생성된 Index 구성 요소는 데이터를 표시하는 데 사용합니다 QuickGrid . 필요에 따라 생성된 구성 요소를 사용자 지정하고 대화형 작업을 통해 정렬 및 필터링과 같은 대화형 기능을 활용할 수 있습니다.

스캐폴더에서 생성된 구성 요소에는 SSR(서버 쪽 렌더링)이 필요하므로 WebAssembly에서 실행할 때 지원되지 않습니다.