VirtualScrollerVirtualScroller is an efficient way of rendering lists by displaying a small subset of data in the viewport at any time.

VirtualScroller - 图1

Documentation

CDK

VirtualScrolling depends on @angular/cdk's ScrollingModule so begin with installing CDK if not already installed.

  2. npm install @angular/cdk --save
  3.  

Import

  2. import {VirtualScrollerModule} from 'primeng/virtualscroller';
  3.  

Getting Started

VirtualScroller requires a collection of items as its value, height of an item size, height of the scrollable viewport and a ng-template to display where each item can be accessed using the implicit variable.

Throughout the samples, a car interface having vin, brand, year and color properties are used to define an object to be displayed by the VirtualScroller. Cars are loaded by a CarService that connects to a server to fetch the cars with a Promise. Note that this is for demo purposes only, any data source such as an Observable can be used as an alternative as well.

  2. export interface Car {
  3.     vin;
  4.     year;
  5.     brand;
  6.     color;
  7. }
  8.  
  2. import { HttpClient } from '@angular/common/http';
  3. import { Injectable } from '@angular/core';
  5. import { Car } from '../domain/car';
  7. @Injectable()
  8. export class CarService {
  10.     constructor(private http: HttpClient) {}
  12.     getCarsSmall() {
  13.         return this.http.get('/showcase/resources/data/cars-small.json')
  14.                     .toPromise()
  15.                     .then(res => <Car[]> res.data)
  16.                     .then(data => { return data; });
  17.     }
  18. }
  19.  

Here is a sample VirtualScroller that displays a list of cars loaded from a remote datasource.

  2. export class VirtualScrollerDemo implements OnInit {
  4.     cars: Car[];
  6.     constructor(private carService: CarService) { }
  8.     ngOnInit() {
  9.         this.carService.getCarsLarge().then(cars => this.cars = cars);
  10.     }
  11. }
  12.  
  2. <p-virtualScroller [value]="cars" scrollHeight="500px" [itemSize]="150">
  3.     <ng-template pTemplate="item" let-car>
  4.         Car content
  5.     </ng-template>
  6. </p-virtualScroller>
  7.  

Sections

Header and Footer are the two sections that are capable of displaying custom content.

  2. <p-virtualScroller [value]="cars" scrollHeight="500px" [itemSize]="150">
  3.     <p-header>Header Content</p-header>
  4.     <p-footer>Footer Content</p-footer>
  5.     <ng-template pTemplate="item" let-car>
  6.         Car content
  7.     </ng-template>
  8. </p-virtualScroller>
  9.  

Lazy Loading

Lazy mode is handy to deal with large datasets where instead of loading the entire data, small chunks of data are loaded on demand by invoking onLazyLoad callback everytime scrolling requires a new chunk. To implement lazy loading, enable lazy attribute, initialize the number of logical rows with a query and finally implement a method callback using onLazyLoad that actually loads a chunk from a datasource. onLazyLoad gets an event object that contains information about the chunk of data to load such as the index and number of items to load. Notice that a new template called loadingItem is also required to display as a placeholder while the new items are being loaded.

  2. <p-virtualScroller [value]="lazyCars" scrollHeight="500px" [itemSize]="150" [rows]="100" [cache]="false" 
  3.     [lazy]="true" (onLazyLoad)="loadCarsLazy($event)" [totalRecords]="totalLazyCarsLength">
  4.     <ng-template let-car pTemplate="item">
  5.         Car content
  6.     </ng-template>
  7.     <ng-template let-car pTemplate="loadingItem">
  8.         Loading...
  9.     </ng-template>
  10. </p-virtualScroller>
  11.  
  2. loadData(event) {
  3.     //event.first = First row offset
  4.     //event.rows = Number of rows per page
  5.     //this.lazyCars = load new chunk between first index and (first + rows) last index
  6. }
  7.  

Properties

NameTypeDefaultDescription
valuearraynullAn array of objects to display.
itemSizenumbernullHeight of an item in the list.
rowsnumbernullNumber of rows to display per page.
firstnumber0Index of the first row to be displayed.
totalRecordsnumbernullNumber of total records, defaults to length of value when not defined.
lazybooleanfalseDefines if data is loaded and interacted with in lazy manner.
scrollHeightanynullMax height of the content area in inline mode.
stylestringnullInline style of the component.
styleClassstringnullStyle class of the component.
trackByFunctionnullFunction to optimize the dom operations by delegating to ngForTrackBy, default algoritm checks for object identity.

Events

NameParametersDescription
onLazyLoadevent.first = First row offset event.rows = Number of rows per page Callback to invoke in lazy mode to load new data.

Methods

NameParametersDescription
scrollToindex: Index of the itemScrolls to the item with the given index.

Styling

Following is the list of structural style classes, for theming classes visit theming page.

NameElement
ui-virtualscrollerContainer element.
ui-virtualscroller-headerHeader section.
ui-virtualscroller-footerFooter section.
ui-virtualscroller-contentContent section.
ui-virtualscroller-listList element.

Dependencies

Angular CDK.

Source

View on GitHub

  2. <h3 class="first">Lazy Loading</h3>
  3. <p-virtualScroller [value]="lazyCars" scrollHeight="500px" [itemSize]="150" [rows]="100" [cache]="false" 
  4.         [lazy]="true" (onLazyLoad)="loadCarsLazy($event)" [totalRecords]="totalLazyCarsLength">
  5.     <p-header>
  6.         List of Cars
  7.     </p-header>
  8.     <ng-template let-car pTemplate="item" let-i="index">
  9.         <div class="ui-g car-item">
  10.             <div class="ui-g-12 ui-md-2">
  11.                 <div style="font-size: 24px; text-align: center; padding-top: 48px">{{i}}</div>
  12.             </div>
  13.             <div class="ui-g-12 ui-md-2">
  14.                 <img src="assets/showcase/images/demo/car/{{car?.brand}}.png">
  15.             </div>
  16.             <div class="ui-g-12 ui-md-8">
  17.                 <div class="ui-g">
  18.                     <div class="ui-g-2 ui-sm-6">Vin: </div>
  19.                     <div class="ui-g-10 ui-sm-6">{{car?.vin}}</div>
  21.                     <div class="ui-g-2 ui-sm-6">Year: </div>
  22.                     <div class="ui-g-10 ui-sm-6">{{car?.year}}</div>
  24.                     <div class="ui-g-2 ui-sm-6">Brand: </div>
  25.                     <div class="ui-g-10 ui-sm-6">{{car?.brand}}</div>
  27.                     <div class="ui-g-2 ui-sm-6">Color: </div>
  28.                     <div class="ui-g-10 ui-sm-6">{{car?.color}}</div>
  29.                 </div>
  30.             </div>
  31.         </div>
  32.     </ng-template>
  33.     <ng-template let-car pTemplate="loadingItem">
  34.         <div class="ui-g car-item empty-car-item">
  35.             <div class="ui-g-12 ui-md-2">
  36.                 <div class="empty-car-item-index"></div>
  37.             </div>
  38.             <div class="ui-g-12 ui-md-2">
  39.                 <div class="empty-car-item-image"></div>
  40.             </div>
  41.             <div class="ui-g-12 ui-md-8">
  42.                 <div class="ui-g">
  43.                     <div class="ui-g-12"><div class="empty-car-item-text"></div></div>
  44.                     <div class="ui-g-12"><div class="empty-car-item-text"></div></div>
  45.                     <div class="ui-g-12"><div class="empty-car-item-text"></div></div>
  46.                     <div class="ui-g-12"><div class="empty-car-item-text"></div></div>
  47.                 </div>
  48.             </div>
  49.         </div>
  50.     </ng-template>
  51. </p-virtualScroller>
  53. <h3>Prepopulated List</h3>
  54. <p-virtualScroller [value]="cars" scrollHeight="500px" [itemSize]="150">
  55.     <p-header>
  56.         <div class="ui-g">
  57.             <div class="ui-g-6 sort-container">
  58.                 <p-dropdown [options]="sortOptions" [(ngModel)]="sortKey" placeholder="Sort By" (onChange)="onSortChange()" [style]="{'min-width':'140px'}"></p-dropdown>
  59.             </div>
  60.             <div class="ui-g-6 title-container">
  61.                 List of Cars
  62.             </div>
  63.         </div>
  64.     </p-header>
  65.     <ng-template let-car pTemplate="item" let-i="index">
  66.         <div class="ui-g car-item">
  67.             <div class="ui-g-12 ui-md-2">
  68.                 <div style="font-size: 24px; text-align: center; padding-top: 48px">{{i}}</div>
  69.             </div>
  70.             <div class="ui-g-12 ui-md-2">
  71.                 <img src="assets/showcase/images/demo/car/{{car?.brand}}.png">
  72.             </div>
  73.             <div class="ui-g-12 ui-md-8">
  74.                 <div class="ui-g">
  75.                     <div class="ui-g-2 ui-sm-6">Vin: </div>
  76.                     <div class="ui-g-10 ui-sm-6">{{car?.vin}}</div>
  78.                     <div class="ui-g-2 ui-sm-6">Year: </div>
  79.                     <div class="ui-g-10 ui-sm-6">{{car?.year}}</div>
  81.                     <div class="ui-g-2 ui-sm-6">Brand: </div>
  82.                     <div class="ui-g-10 ui-sm-6">{{car?.brand}}</div>
  84.                     <div class="ui-g-2 ui-sm-6">Color: </div>
  85.                     <div class="ui-g-10 ui-sm-6">{{car?.color}}</div>
  86.                 </div>
  87.             </div>
  88.         </div>
  89.     </ng-template>
  90. </p-virtualScroller>
  91.  
  2. @Component({
  3.     templateUrl: './virtualscrollerdemo.html',
  4.     styles: [`
  5.         .car-item .ui-md-3 {
  6.             text-align: center;
  7.         }
  9.         .car-item .ui-g-10 {
  10.             font-weight: bold;
  11.         }
  13.         .empty-car-item-index {
  14.             background-color: #f1f1f1;
  15.             width: 60px;
  16.             height: 60px;
  17.             margin: 36px auto 0 auto;
  18.             animation: pulse 1s infinite ease-in-out;
  19.         }
  21.         .empty-car-item-image {
  22.             background-color: #f1f1f1;
  23.             width: 120px;
  24.             height: 120px;
  25.             animation: pulse 1s infinite ease-in-out;
  26.         }
  28.         .empty-car-item-text {
  29.             background-color: #f1f1f1;
  30.             height: 18px;
  31.             animation: pulse 1s infinite ease-in-out;
  32.         }
  34.         .title-container {
  35.             padding: 1em;
  36.             text-align: right;
  37.         }
  39.         .sort-container {
  40.             text-align: left;
  41.         }
  43.         @media (max-width: 40em) {
  44.             .car-item {
  45.                 text-align: center;
  46.             }
  47.         }
  48.     `]
  49. })
  50. export class VirtualScrollerDemo implements OnInit {
  52.     cars: Car[] = [];
  54.     lazyCars: Car[];
  56.     brands: string[];
  58.     colors: string[];
  60.     totalLazyCarsLength: number;
  62.     timeout: any;
  64.     sortKey: string;
  66.     sortOptions: SelectItem[];
  68.     constructor(private carService: CarService) { }
  70.     ngOnInit() {
  71.         this.brands = [
  72.             'Audi', 'BMW', 'Fiat', 'Ford', 'Honda', 'Jaguar', 'Mercedes', 'Renault', 'Volvo', 'VW'
  73.         ];
  75.         this.colors = [
  76.             'Black', 'White', 'Red', 'Blue', 'Silver', 'Green', 'Yellow'
  77.         ];
  79.         for (let i = 0; i < 10000; i++) {
  80.             this.cars.push(this.generateCar());
  81.         }
  83.         //in a real application, make a remote request to retrieve the number of records only, not the actual records
  84.         this.totalLazyCarsLength = 10000;
  86.         this.sortOptions = [
  87.             {label: 'Newest First', value: '!year'},
  88.             {label: 'Oldest First', value: 'year'}
  89.         ];
  90.     }
  92.     generateCar(): Car {
  93.         return {
  94.             vin: this.generateVin(),
  95.             brand: this.generateBrand(),
  96.             color: this.generateColor(),
  97.             year: this.generateYear()
  98.         }
  99.     }
  101.     generateVin() {
  102.         let text = "";
  103.         let possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  105.         for (var i = 0; i < 5; i++) {
  106.             text += possible.charAt(Math.floor(Math.random() * possible.length));
  107.         }
  109.         return text;
  110.     }
  112.     generateBrand() {
  113.         return this.brands[Math.floor(Math.random() * Math.floor(10))];
  114.     }
  116.     generateColor() {
  117.         return this.colors[Math.floor(Math.random() * Math.floor(7))];
  118.     }
  120.     generateYear() {
  121.         return 2000 + Math.floor(Math.random() * Math.floor(19));
  122.     }
  124.     loadCarsLazy(event: LazyLoadEvent) {
  125.         //in a real application, make a remote request to load data using state metadata from event
  126.         //event.first = First row offset
  127.         //event.rows = Number of rows per page
  129.         //imitate db connection over a network
  130.         if (this.timeout) {
  131.             clearTimeout(this.timeout);
  132.         }
  134.         this.timeout = setTimeout(() => {
  135.             this.lazyCars = [];
  136.             if (this.cars) {
  137.                 this.lazyCars = this.cars.slice(event.first, (event.first + event.rows));
  138.             }
  139.         }, 1000);
  140.     }
  142.     onSortChange() {
  143.         if (this.sortKey.indexOf('!') === 0)
  144.             this.sort(-1);
  145.         else
  146.             this.sort(1);
  147.     }
  149.     sort(order: number): void {
  150.         let cars = [...this.cars];
  151.         cars.sort((data1, data2) => {
  152.             let value1 = data1.year;
  153.             let value2 = data2.year;
  154.             let result = (value1 < value2) ? -1 : (value1 > value2) ? 1 : 0;
  156.             return (order * result);
  157.         });
  159.         this.cars = cars;
  160.     }
  161. }
  162.