|
| 1 | +/** |
| 2 | + * @license |
| 3 | + * Copyright Google LLC All Rights Reserved. |
| 4 | + * |
| 5 | + * Use of this source code is governed by an MIT-style license that can be |
| 6 | + * found in the LICENSE file at https://angular.io/license |
| 7 | + */ |
| 8 | + |
| 9 | +import {ListRange} from '@angular/cdk/collections'; |
| 10 | +import {Directive, forwardRef, Input, OnChanges} from '@angular/core'; |
| 11 | +import {VIRTUAL_SCROLL_STRATEGY, VirtualScrollStrategy} from './virtual-scroll-strategy'; |
| 12 | +import {CdkVirtualScrollViewport} from './virtual-scroll-viewport'; |
| 13 | + |
| 14 | + |
| 15 | +/** |
| 16 | + * A class that tracks the size of items that have been seen and uses it to estimate the average |
| 17 | + * item size. |
| 18 | + */ |
| 19 | +export class ItemSizeAverager { |
| 20 | + /** The total amount of weight behind the current average. */ |
| 21 | + private _totalWeight = 0; |
| 22 | + |
| 23 | + /** The current average item size. */ |
| 24 | + private _averageItemSize: number; |
| 25 | + |
| 26 | + /** @param defaultItemSize The default size to use for items when no data is available. */ |
| 27 | + constructor(defaultItemSize = 50) { |
| 28 | + this._averageItemSize = defaultItemSize; |
| 29 | + } |
| 30 | + |
| 31 | + /** Returns the average item size. */ |
| 32 | + getAverageItemSize(): number { |
| 33 | + return this._averageItemSize; |
| 34 | + } |
| 35 | + |
| 36 | + /** |
| 37 | + * Adds a measurement sample for the estimator to consider. |
| 38 | + * @param range The measured range. |
| 39 | + * @param size The measured size of the given range in pixels. |
| 40 | + */ |
| 41 | + addSample(range: ListRange, size: number) { |
| 42 | + const weight = range.end - range.start; |
| 43 | + const newTotalWeight = this._totalWeight + weight; |
| 44 | + if (newTotalWeight) { |
| 45 | + const newAverageItemSize = |
| 46 | + (size * weight + this._averageItemSize * this._totalWeight) / newTotalWeight; |
| 47 | + if (newAverageItemSize) { |
| 48 | + this._averageItemSize = newAverageItemSize; |
| 49 | + this._totalWeight = newTotalWeight; |
| 50 | + } |
| 51 | + } |
| 52 | + } |
| 53 | +} |
| 54 | + |
| 55 | + |
| 56 | +/** Virtual scrolling strategy for lists with items of unknown or dynamic size. */ |
| 57 | +export class AutoSizeVirtualScrollStrategy implements VirtualScrollStrategy { |
| 58 | + /** The attached viewport. */ |
| 59 | + private _viewport: CdkVirtualScrollViewport | null = null; |
| 60 | + |
| 61 | + /** The minimum amount of buffer rendered beyond the viewport (in pixels). */ |
| 62 | + private _minBufferPx: number; |
| 63 | + |
| 64 | + /** The number of buffer items to render beyond the edge of the viewport (in pixels). */ |
| 65 | + private _addBufferPx: number; |
| 66 | + |
| 67 | + /** The estimator used to estimate the size of unseen items. */ |
| 68 | + private _averager: ItemSizeAverager; |
| 69 | + |
| 70 | + /** |
| 71 | + * @param minBufferPx The minimum amount of buffer rendered beyond the viewport (in pixels). |
| 72 | + * If the amount of buffer dips below this number, more items will be rendered. |
| 73 | + * @param addBufferPx The number of pixels worth of buffer to shoot for when rendering new items. |
| 74 | + * If the actual amount turns out to be less it will not necessarily trigger an additional |
| 75 | + * rendering cycle (as long as the amount of buffer is still greater than `minBufferPx`). |
| 76 | + * @param averager The averager used to estimate the size of unseen items. |
| 77 | + */ |
| 78 | + constructor(minBufferPx: number, addBufferPx: number, averager = new ItemSizeAverager()) { |
| 79 | + this._minBufferPx = minBufferPx; |
| 80 | + this._addBufferPx = addBufferPx; |
| 81 | + this._averager = averager; |
| 82 | + } |
| 83 | + |
| 84 | + /** |
| 85 | + * Attaches this scroll strategy to a viewport. |
| 86 | + * @param viewport The viewport to attach this strategy to. |
| 87 | + */ |
| 88 | + attach(viewport: CdkVirtualScrollViewport) { |
| 89 | + this._viewport = viewport; |
| 90 | + this._updateTotalContentSize(); |
| 91 | + this._renderContentForOffset(this._viewport.measureScrollOffset()); |
| 92 | + } |
| 93 | + |
| 94 | + /** Detaches this scroll strategy from the currently attached viewport. */ |
| 95 | + detach() { |
| 96 | + this._viewport = null; |
| 97 | + } |
| 98 | + |
| 99 | + /** Called when the viewport is scrolled. */ |
| 100 | + onContentScrolled() { |
| 101 | + if (this._viewport) { |
| 102 | + this._renderContentForOffset(this._viewport.measureScrollOffset()); |
| 103 | + } |
| 104 | + } |
| 105 | + |
| 106 | + /** Called when the length of the data changes. */ |
| 107 | + onDataLengthChanged() { |
| 108 | + if (this._viewport) { |
| 109 | + this._updateTotalContentSize(); |
| 110 | + this._renderContentForOffset(this._viewport.measureScrollOffset()); |
| 111 | + } |
| 112 | + } |
| 113 | + |
| 114 | + /** |
| 115 | + * Update the buffer parameters. |
| 116 | + * @param minBufferPx The minimum amount of buffer rendered beyond the viewport (in pixels). |
| 117 | + * @param addBufferPx The number of buffer items to render beyond the edge of the viewport (in |
| 118 | + * pixels). |
| 119 | + */ |
| 120 | + updateBufferSize(minBufferPx: number, addBufferPx: number) { |
| 121 | + this._minBufferPx = minBufferPx; |
| 122 | + this._addBufferPx = addBufferPx; |
| 123 | + } |
| 124 | + |
| 125 | + /** |
| 126 | + * Render the content that we estimate should be shown for the given scroll offset. |
| 127 | + * Note: must not be called if `this._viewport` is null |
| 128 | + */ |
| 129 | + private _renderContentForOffset(scrollOffset: number) { |
| 130 | + const viewport = this._viewport!; |
| 131 | + const itemSize = this._averager.getAverageItemSize(); |
| 132 | + const firstVisibleIndex = |
| 133 | + Math.min(viewport.getDataLength() - 1, Math.floor(scrollOffset / itemSize)); |
| 134 | + const bufferSize = Math.ceil(this._addBufferPx / itemSize); |
| 135 | + const range = this._expandRange( |
| 136 | + this._getVisibleRangeForIndex(firstVisibleIndex), bufferSize, bufferSize); |
| 137 | + |
| 138 | + viewport.setRenderedRange(range); |
| 139 | + viewport.setRenderedContentOffset(itemSize * range.start); |
| 140 | + } |
| 141 | + |
| 142 | + // TODO: maybe move to base class, can probably share with fixed size strategy. |
| 143 | + /** |
| 144 | + * Gets the visible range of data for the given start index. If the start index is too close to |
| 145 | + * the end of the list it may be backed up to ensure the estimated size of the range is enough to |
| 146 | + * fill the viewport. |
| 147 | + * Note: must not be called if `this._viewport` is null |
| 148 | + * @param startIndex The index to start the range at |
| 149 | + * @return a range estimated to be large enough to fill the viewport when rendered. |
| 150 | + */ |
| 151 | + private _getVisibleRangeForIndex(startIndex: number): ListRange { |
| 152 | + const viewport = this._viewport!; |
| 153 | + const range: ListRange = { |
| 154 | + start: startIndex, |
| 155 | + end: startIndex + |
| 156 | + Math.ceil(viewport.getViewportSize() / this._averager.getAverageItemSize()) |
| 157 | + }; |
| 158 | + const extra = range.end - viewport.getDataLength(); |
| 159 | + if (extra > 0) { |
| 160 | + range.start = Math.max(0, range.start - extra); |
| 161 | + } |
| 162 | + return range; |
| 163 | + } |
| 164 | + |
| 165 | + // TODO: maybe move to base class, can probably share with fixed size strategy. |
| 166 | + /** |
| 167 | + * Expand the given range by the given amount in either direction. |
| 168 | + * Note: must not be called if `this._viewport` is null |
| 169 | + * @param range The range to expand |
| 170 | + * @param expandStart The number of items to expand the start of the range by. |
| 171 | + * @param expandEnd The number of items to expand the end of the range by. |
| 172 | + * @return The expanded range. |
| 173 | + */ |
| 174 | + private _expandRange(range: ListRange, expandStart: number, expandEnd: number): ListRange { |
| 175 | + const viewport = this._viewport!; |
| 176 | + const start = Math.max(0, range.start - expandStart); |
| 177 | + const end = Math.min(viewport.getDataLength(), range.end + expandEnd); |
| 178 | + return {start, end}; |
| 179 | + } |
| 180 | + |
| 181 | + /** Update the viewport's total content size. */ |
| 182 | + private _updateTotalContentSize() { |
| 183 | + const viewport = this._viewport!; |
| 184 | + viewport.setTotalContentSize(viewport.getDataLength() * this._averager.getAverageItemSize()); |
| 185 | + } |
| 186 | +} |
| 187 | + |
| 188 | +/** |
| 189 | + * Provider factory for `AutoSizeVirtualScrollStrategy` that simply extracts the already created |
| 190 | + * `AutoSizeVirtualScrollStrategy` from the given directive. |
| 191 | + * @param autoSizeDir The instance of `CdkAutoSizeVirtualScroll` to extract the |
| 192 | + * `AutoSizeVirtualScrollStrategy` from. |
| 193 | + */ |
| 194 | +export function _autoSizeVirtualScrollStrategyFactory(autoSizeDir: CdkAutoSizeVirtualScroll) { |
| 195 | + return autoSizeDir._scrollStrategy; |
| 196 | +} |
| 197 | + |
| 198 | + |
| 199 | +/** A virtual scroll strategy that supports unknown or dynamic size items. */ |
| 200 | +@Directive({ |
| 201 | + selector: 'cdk-virtual-scroll-viewport[autosize]', |
| 202 | + providers: [{ |
| 203 | + provide: VIRTUAL_SCROLL_STRATEGY, |
| 204 | + useFactory: _autoSizeVirtualScrollStrategyFactory, |
| 205 | + deps: [forwardRef(() => CdkAutoSizeVirtualScroll)], |
| 206 | + }], |
| 207 | +}) |
| 208 | +export class CdkAutoSizeVirtualScroll implements OnChanges { |
| 209 | + /** |
| 210 | + * The minimum amount of buffer rendered beyond the viewport (in pixels). |
| 211 | + * If the amount of buffer dips below this number, more items will be rendered. |
| 212 | + */ |
| 213 | + @Input() minBufferPx: number = 100; |
| 214 | + |
| 215 | + /** |
| 216 | + * The number of pixels worth of buffer to shoot for when rendering new items. |
| 217 | + * If the actual amount turns out to be less it will not necessarily trigger an additional |
| 218 | + * rendering cycle (as long as the amount of buffer is still greater than `minBufferPx`). |
| 219 | + */ |
| 220 | + @Input() addBufferPx: number = 200; |
| 221 | + |
| 222 | + /** The scroll strategy used by this directive. */ |
| 223 | + _scrollStrategy = new AutoSizeVirtualScrollStrategy(this.minBufferPx, this.addBufferPx); |
| 224 | + |
| 225 | + ngOnChanges() { |
| 226 | + this._scrollStrategy.updateBufferSize(this.minBufferPx, this.addBufferPx); |
| 227 | + } |
| 228 | +} |
0 commit comments