javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-08-15 17:42:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(virtual-scroll): adds headerHeight and footerHeight (#18851)

Browse Source 
Currently, if you have an ion-virtual-scroll with a list of items and a search bar for filtering them, when you change the list of items, the items disappear until rendered again, causing a flicker. This could be solved for the items using the itemHeight function to provide the exact height size and bypass some calculations and be more performant etc.

However, if you had a header or footer, they would still flicker. This commit adds two more optional functions named headerHeight and footerHeight that return the exact size of the header and footer respectively and resolve the flicker.
This commit is contained in:
Stefanos Anagnostou
2019-07-24 19:29:16 +03:00
committed by Manu MA
parent c91819c94f
commit 00891119f7
8 changed files with 72 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
angular/src/directives/virtual-scroll/virtual-scroll.ts
View File

@ -1,5 +1,5 @@
import { ChangeDetectionStrategy, Component, ContentChild, ElementRef, EmbeddedViewRef, IterableDiffer, IterableDiffers, NgZone, SimpleChanges, TrackByFunction } from '@angular/core';
import { Cell, CellType, HeaderFn, ItemHeightFn } from '@ionic/core';
import { Cell, CellType, FooterHeightFn, HeaderFn, HeaderHeightFn, ItemHeightFn } from '@ionic/core';
import { proxyInputs, proxyMethods } from '../proxies-utils';
@ -75,7 +75,7 @@ export declare interface IonVirtualScroll {
/**
* An optional function that maps each item within their height.
* When this function is provides, heavy optimizations and fast path can be taked by
* When this function is provided, heavy optimizations and fast path can be taked by
* `ion-virtual-scroll` leading to massive performance improvements.
*
* This function allows to skip all DOM reads, which can be Doing so leads
@ -83,6 +83,16 @@ export declare interface IonVirtualScroll {
*/
itemHeight?: ItemHeightFn;
/**
* An optional function that maps each item header within their height.
*/
headerHeight?: HeaderHeightFn;
/**
* An optional function that maps each item footer within their height.
*/
footerHeight?: FooterHeightFn;
/**
* Same as `ngForTrackBy` which can be used on `ngFor`.
*/
@ -114,6 +124,8 @@ export declare interface IonVirtualScroll {
'footerFn',
'items',
'itemHeight',
'headerHeight',
'footerHeight',
'trackBy'
]
})
@ -211,7 +223,9 @@ proxyInputs(IonVirtualScroll, [
'headerFn',
'footerFn',
'items',
'itemHeight'
'itemHeight',
'headerHeight',
'footerHeight'
]);
proxyMethods(IonVirtualScroll, [

2
core/api.txt
View File

@ -1280,7 +1280,9 @@ ion-virtual-scroll,prop,approxFooterHeight,number,30,false,false
ion-virtual-scroll,prop,approxHeaderHeight,number,30,false,false
ion-virtual-scroll,prop,approxItemHeight,number,45,false,false
ion-virtual-scroll,prop,footerFn,((item: any, index: number, items: any[]) => string | null | undefined) | undefined,undefined,false,false
ion-virtual-scroll,prop,footerHeight,((item: any, index: number) => number) | undefined,undefined,false,false
ion-virtual-scroll,prop,headerFn,((item: any, index: number, items: any[]) => string | null | undefined) | undefined,undefined,false,false
ion-virtual-scroll,prop,headerHeight,((item: any, index: number) => number) | undefined,undefined,false,false
ion-virtual-scroll,prop,itemHeight,((item: any, index: number) => number) | undefined,undefined,false,false
ion-virtual-scroll,prop,items,any[] | undefined,undefined,false,false
ion-virtual-scroll,prop,nodeRender,((el: HTMLElement | null, cell: Cell, domIndex: number) => HTMLElement) | undefined,undefined,false,false

18
core/src/components.d.ts vendored
View File

@ -20,8 +20,10 @@ import {
DatetimeChangeEventDetail,
DatetimeOptions,
DomRenderFn,
FooterHeightFn,
FrameworkDelegate,
HeaderFn,
HeaderHeightFn,
InputChangeEventDetail,
ItemHeightFn,
ItemRenderFn,
@ -2835,10 +2837,18 @@ export namespace Components {
*/
'footerFn'?: HeaderFn;
/**
* An optional function that maps each item footer within their height.
*/
'footerHeight'?: FooterHeightFn;
/**
* Section headers and the data used within its given template can be dynamically created by passing a function to `headerFn`. For example, a large list of contacts usually has dividers between each letter in the alphabet. App's can provide their own custom `headerFn` which is called with each record within the dataset. The logic within the header function can decide if the header template should be used, and what data to give to the header template. The function must return `null` if a header cell shouldn't be created.
*/
'headerFn'?: HeaderFn;
/**
* An optional function that maps each item header within their height.
*/
'headerHeight'?: HeaderHeightFn;
/**
* An optional function that maps each item within their height. When this function is provides, heavy optimizations and fast path can be taked by `ion-virtual-scroll` leading to massive performance improvements. This function allows to skip all DOM reads, which can be Doing so leads to massive performance
*/
'itemHeight'?: ItemHeightFn;
@ -6101,10 +6111,18 @@ declare namespace LocalJSX {
*/
'footerFn'?: HeaderFn;
/**
* An optional function that maps each item footer within their height.
*/
'footerHeight'?: FooterHeightFn;
/**
* Section headers and the data used within its given template can be dynamically created by passing a function to `headerFn`. For example, a large list of contacts usually has dividers between each letter in the alphabet. App's can provide their own custom `headerFn` which is called with each record within the dataset. The logic within the header function can decide if the header template should be used, and what data to give to the header template. The function must return `null` if a header cell shouldn't be created.
*/
'headerFn'?: HeaderFn;
/**
* An optional function that maps each item header within their height.
*/
'headerHeight'?: HeaderHeightFn;
/**
* An optional function that maps each item within their height. When this function is provides, heavy optimizations and fast path can be taked by `ion-virtual-scroll` leading to massive performance improvements. This function allows to skip all DOM reads, which can be Doing so leads to massive performance
*/
'itemHeight'?: ItemHeightFn;

2
core/src/components/virtual-scroll/readme.md
View File

@ -252,7 +252,9 @@ within a `<div>` is a safe way to make sure dimensions are measured correctly.
| `approxHeaderHeight` | `approx-header-height` | The approximate height of each header template's cell. This dimension is used to help determine how many cells should be created when initialized, and to help calculate the height of the scrollable area. This height value can only use `px` units. Note that the actual rendered size of each cell comes from the app's CSS, whereas this approximation is used to help calculate initial dimensions before the item has been rendered. | `number` | `30` |
| `approxItemHeight` | `approx-item-height` | It is important to provide this if virtual item height will be significantly larger than the default The approximate height of each virtual item template's cell. This dimension is used to help determine how many cells should be created when initialized, and to help calculate the height of the scrollable area. This height value can only use `px` units. Note that the actual rendered size of each cell comes from the app's CSS, whereas this approximation is used to help calculate initial dimensions before the item has been rendered. | `number` | `45` |
| `footerFn` | -- | Section footers and the data used within its given template can be dynamically created by passing a function to `footerFn`. The logic within the footer function can decide if the footer template should be used, and what data to give to the footer template. The function must return `null` if a footer cell shouldn't be created. | `((item: any, index: number, items: any[]) => string \| null \| undefined) \| undefined` | `undefined` |
| `footerHeight` | -- | An optional function that maps each item footer within their height. | `((item: any, index: number) => number) \| undefined` | `undefined` |
| `headerFn` | -- | Section headers and the data used within its given template can be dynamically created by passing a function to `headerFn`. For example, a large list of contacts usually has dividers between each letter in the alphabet. App's can provide their own custom `headerFn` which is called with each record within the dataset. The logic within the header function can decide if the header template should be used, and what data to give to the header template. The function must return `null` if a header cell shouldn't be created. | `((item: any, index: number, items: any[]) => string \| null \| undefined) \| undefined` | `undefined` |
| `headerHeight` | -- | An optional function that maps each item header within their height. | `((item: any, index: number) => number) \| undefined` | `undefined` |
| `itemHeight` | -- | An optional function that maps each item within their height. When this function is provides, heavy optimizations and fast path can be taked by `ion-virtual-scroll` leading to massive performance improvements. This function allows to skip all DOM reads, which can be Doing so leads to massive performance | `((item: any, index: number) => number) \| undefined` | `undefined` |
| `items` | -- | The data that builds the templates within the virtual scroll. It's important to note that when this data has changed, then the entire virtual scroll is reset, which is an expensive operation and should be avoided if possible. | `any[] \| undefined` | `undefined` |
| `nodeRender` | -- | NOTE: only Vanilla JS API. | `((el: HTMLElement \| null, cell: Cell, domIndex: number) => HTMLElement) \| undefined` | `undefined` |

10
core/src/components/virtual-scroll/test/virtual-scroll-utils.spec.ts
View File

@ -146,7 +146,7 @@ describe('resizeBuffer', () => {
describe('calcCells', () => {
it('should calculate cells without headers and itemHeight', () => {
const items = ['0', 2, 'hola', { data: 'hello' }];
const cells = calcCells(items, undefined, undefined, undefined, 10, 20, 30, 0, 0, items.length);
const cells = calcCells(items, undefined, undefined, undefined, undefined, undefined, 10, 20, 30, 0, 0, items.length);
expect(cells).toEqual([
{
type: CELL_TYPE_ITEM,
@ -195,7 +195,7 @@ describe('calcCells', () => {
called++;
return index * 20 + 20;
};
const cells = calcCells(items, itemHeight, undefined, undefined, 10, 20, 30, 0, 0, items.length);
const cells = calcCells(items, itemHeight, undefined, undefined, undefined, undefined, 10, 20, 30, 0, 0, items.length);
expect(called).toEqual(3);
expect(cells).toEqual([
@ -251,7 +251,7 @@ describe('calcCells', () => {
called++;
return index * 20 + 20;
};
const cells = calcCells(items, itemHeight, headerFn, footerFn, 10, 20, 30, 0, 0, items.length);
const cells = calcCells(items, itemHeight, undefined, undefined, headerFn, footerFn, 10, 20, 30, 0, 0, items.length);
expect(cells).toHaveLength(5);
expect(called).toEqual(3);
expect(headerCalled).toEqual(3);
@ -315,7 +315,7 @@ describe('calcHeightIndex', () => {
const footerFn: HeaderFn = (_, index) => {
return (index === 2) ? 'my footer' : null;
};
const cells = calcCells(items, undefined, headerFn, footerFn, 10, 20, 50, 0, 0, items.length);
const cells = calcCells(items, undefined, undefined, undefined, headerFn, footerFn, 10, 20, 50, 0, 0, items.length);
const buf = resizeBuffer(undefined, cells.length);
const totalHeight = calcHeightIndex(buf, cells, 0);
expect(buf.length).toEqual(7);
@ -508,7 +508,7 @@ function mockVirtualScroll(
headerFn?: HeaderFn,
footerFn?: HeaderFn
) {
const cells = calcCells(items, itemHeight, headerFn, footerFn, 10, 10, 30, 0, 0, items.length);
const cells = calcCells(items, itemHeight, undefined, undefined, headerFn, footerFn, 10, 10, 30, 0, 0, items.length);
const heightIndex = resizeBuffer(undefined, cells.length);
calcHeightIndex(heightIndex, cells, 0);
return { items, heightIndex, cells };

2
core/src/components/virtual-scroll/virtual-scroll-interface.ts
View File

@ -21,5 +21,7 @@ export type CellType = 'item' | 'header' | 'footer';
export type NodeChange = number;
export type HeaderFn = (item: any, index: number, items: any[]) => string | null | undefined;
export type ItemHeightFn = (item: any, index: number) => number;
export type HeaderHeightFn = (item: any, index: number) => number;
export type FooterHeightFn = (item: any, index: number) => number;
export type ItemRenderFn = (el: HTMLElement | null, cell: Cell, domIndex: number) => HTMLElement;
export type DomRenderFn = (dom: VirtualNode[]) => void;

16
core/src/components/virtual-scroll/virtual-scroll-utils.ts
View File

@ -1,7 +1,7 @@
import { Cell, HeaderFn, ItemHeightFn, ItemRenderFn, VirtualNode } from '../../interface';
import { CELL_TYPE_FOOTER, CELL_TYPE_HEADER, CELL_TYPE_ITEM, NODE_CHANGE_CELL, NODE_CHANGE_NONE, NODE_CHANGE_POSITION } from './constants';
import { CellType } from './virtual-scroll-interface';
import { CellType, FooterHeightFn, HeaderHeightFn } from './virtual-scroll-interface';
export interface Viewport {
top: number;
@ -205,6 +205,8 @@ export const calcCells = (
items: any[],
itemHeight: ItemHeightFn | undefined,
headerHeight: HeaderHeightFn | undefined,
footerHeight: FooterHeightFn | undefined,
headerFn: HeaderFn | undefined,
footerFn: HeaderFn | undefined,
@ -228,9 +230,9 @@ export const calcCells = (
type: CELL_TYPE_HEADER,
value,
index: i,
height: approxHeaderHeight,
reads: MIN_READS,
visible: false,
height: headerHeight ? headerHeight(value, i) : approxHeaderHeight,
reads: headerHeight ? 0 : MIN_READS,
visible: !!headerHeight,
});
}
}
@ -253,9 +255,9 @@ export const calcCells = (
type: CELL_TYPE_FOOTER,
value,
index: i,
height: approxFooterHeight,
reads: 2,
visible: false,
height: footerHeight ? footerHeight(value, i) : approxFooterHeight,
reads: footerHeight ? 0 : MIN_READS,
visible: !!footerHeight,
});
}
}

18
core/src/components/virtual-scroll/virtual-scroll.tsx
View File

@ -1,6 +1,6 @@
import { Component, ComponentInterface, Element, FunctionalComponent, Listen, Method, Prop, State, Watch, h, readTask, writeTask } from '@stencil/core';
import { Cell, DomRenderFn, HeaderFn, ItemHeightFn, ItemRenderFn, VirtualNode } from '../../interface';
import { Cell, DomRenderFn, FooterHeightFn, HeaderFn, HeaderHeightFn, ItemHeightFn, ItemRenderFn, VirtualNode } from '../../interface';
import { CELL_TYPE_FOOTER, CELL_TYPE_HEADER, CELL_TYPE_ITEM } from './constants';
import { Range, calcCells, calcHeightIndex, doRender, findCellIndex, getRange, getShouldUpdate, getViewport, inplaceUpdate, positionForIndex, resizeBuffer, updateVDom } from './virtual-scroll-utils';
@ -104,6 +104,16 @@ export class VirtualScroll implements ComponentInterface {
*/
@Prop() itemHeight?: ItemHeightFn;
/**
* An optional function that maps each item header within their height.
*/
@Prop() headerHeight?: HeaderHeightFn;
/**
* An optional function that maps each item footer within their height.
*/
@Prop() footerHeight?: FooterHeightFn;
/**
* NOTE: only JSX API for stencil.
*
@ -134,6 +144,8 @@ export class VirtualScroll implements ComponentInterface {
@Prop() domRender?: DomRenderFn;
@Watch('itemHeight')
@Watch('headerHeight')
@Watch('footerHeight')
@Watch('items')
itemsChanged() {
this.calcCells();
@ -197,6 +209,8 @@ export class VirtualScroll implements ComponentInterface {
const cells = calcCells(
this.items,
this.itemHeight,
this.headerHeight,
this.footerHeight,
this.headerFn,
this.footerFn,
this.approxHeaderHeight,
@ -357,6 +371,8 @@ export class VirtualScroll implements ComponentInterface {
this.cells = calcCells(
this.items,
this.itemHeight,
this.headerHeight,
this.footerHeight,
this.headerFn,
this.footerFn,
this.approxHeaderHeight,