diff --git a/docs/Grid.md b/docs/Grid.md index f681d6937..1151c655c 100644 --- a/docs/Grid.md +++ b/docs/Grid.md @@ -22,6 +22,7 @@ A windowed grid of elements. `Grid` only renders cells necessary to fill itself | onSectionRendered | Function | | Callback invoked with information about the section of the Grid that was just rendered. This callback is only invoked when visible rows have changed: `({ columnOverscanStartIndex: number, columnOverscanStopIndex: number, columnStartIndex: number, columnStopIndex: number, rowOverscanStartIndex: number, rowOverscanStopIndex: number, rowStartIndex: number, rowStopIndex: number }): void` | | onScroll | Function | | Callback invoked whenever the scroll offset changes within the inner scrollable region: `({ clientHeight: number, clientWidth: number, scrollHeight: number, scrollLeft: number, scrollTop: number, scrollWidth: number }): void` | | overscanColumnCount | Number | | Number of columns to render before/after the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices. | +| overscanIndicesGetter | Function | | Responsible for calculating the number of cells to overscan before and after a specified range [Learn more](#overscanIndicesGetter) | | overscanRowCount | Number | | Number of rows to render above/below the visible slice of the grid. This can help reduce flickering during scrolling on certain browsers/devices. | | rowCount | Number | ✓ | Number of rows in grid. | | rowHeight | Number or Function | ✓ | Either a fixed row height (number) or a function that returns the height of a row given its index: `({ index: number }): number` | @@ -147,6 +148,10 @@ function cellRangeRenderer ({ } ``` +### overscanIndicesGetter +This is an advanced property. +This function is responsible for calculating the number of cells to overscan before and after a specified range. By default, React Virtualized optimizes the number of cells to overscan based on scroll direction. If you'd like to customize this behavior, you may want to fork the [`defaultOverscanIndicesGetter`](https://github.com/bvaughn/react-virtualized/blob/master/source/Grid/utils/defaultOverscanIndicesGetter.js) function. + ### cellRenderer Responsible for rendering a single cell, given its row and column index. @@ -173,15 +178,15 @@ function cellRenderer ({ // Style is required since it specifies how the cell is to be sized and positioned, // and React Virtualized depends on this sizing/positioning for proper scrolling behavior. // By default, the grid component specifies, calculates, and initializes the following style properties: - // height - // width + // height + // width // left // top // position // You can add additional class names or style properties as you would like. // Key is also required by React to more efficiently manage the array of cells. return ( -
diff --git a/source/Grid/Grid.jest.js b/source/Grid/Grid.jest.js index 5ee3085ce..304c390b0 100644 --- a/source/Grid/Grid.jest.js +++ b/source/Grid/Grid.jest.js @@ -5,7 +5,7 @@ import { Simulate } from 'react-addons-test-utils' import { render } from '../TestUtils' import shallowCompare from 'react-addons-shallow-compare' import Grid, { DEFAULT_SCROLLING_RESET_TIME_INTERVAL } from './Grid' -import { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/getOverscanIndices' +import { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/defaultOverscanIndicesGetter' import { DEFAULT_MAX_SCROLL_SIZE } from './utils/ScalingCellSizeAndPositionManager' const DEFAULT_COLUMN_WIDTH = 50 diff --git a/source/Grid/Grid.js b/source/Grid/Grid.js index 364fecaac..e85b9f4af 100644 --- a/source/Grid/Grid.js +++ b/source/Grid/Grid.js @@ -4,7 +4,7 @@ import cn from 'classnames' import calculateSizeAndPositionDataAndUpdateScrollOffset from './utils/calculateSizeAndPositionDataAndUpdateScrollOffset' import ScalingCellSizeAndPositionManager from './utils/ScalingCellSizeAndPositionManager' import createCallbackMemoizer from '../utils/createCallbackMemoizer' -import getOverscanIndices, { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/getOverscanIndices' +import defaultOverscanIndicesGetter, { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD } from './utils/defaultOverscanIndicesGetter' import getScrollbarSize from 'dom-helpers/util/scrollbarSize' import shallowCompare from 'react-addons-shallow-compare' import updateScrollIndexHelper from './utils/updateScrollIndexHelper' @@ -134,6 +134,19 @@ export default class Grid extends Component { */ overscanColumnCount: PropTypes.number.isRequired, + /** + * Calculates the number of cells to overscan before and after a specified range. + * This function ensures that overscanning doesn't exceed the available cells. + * Should implement the following interface: ({ + * cellCount: number, + * overscanCellsCount: number, + * scrollDirection: number, + * startIndex: number, + * stopIndex: number + * }): {overscanStartIndex: number, overscanStopIndex: number} + */ + overscanIndicesGetter: PropTypes.func.isRequired, + /** * Number of rows to render above/below the visible section of the grid. * These rows can help for smoother scrolling on touch devices or browsers that send scroll events infrequently. @@ -198,6 +211,7 @@ export default class Grid extends Component { onScroll: () => null, onSectionRendered: () => null, overscanColumnCount: 0, + overscanIndicesGetter: defaultOverscanIndicesGetter, overscanRowCount: 10, scrollingResetTimeInterval: DEFAULT_SCROLLING_RESET_TIME_INTERVAL, scrollToAlignment: 'auto', @@ -629,6 +643,7 @@ export default class Grid extends Component { columnCount, height, overscanColumnCount, + overscanIndicesGetter, overscanRowCount, rowCount, width @@ -670,7 +685,7 @@ export default class Grid extends Component { this._renderedRowStartIndex = visibleRowIndices.start this._renderedRowStopIndex = visibleRowIndices.stop - const overscanColumnIndices = getOverscanIndices({ + const overscanColumnIndices = overscanIndicesGetter({ cellCount: columnCount, overscanCellsCount: overscanColumnCount, scrollDirection: scrollDirectionHorizontal, @@ -678,7 +693,7 @@ export default class Grid extends Component { stopIndex: this._renderedColumnStopIndex }) - const overscanRowIndices = getOverscanIndices({ + const overscanRowIndices = overscanIndicesGetter({ cellCount: rowCount, overscanCellsCount: overscanRowCount, scrollDirection: scrollDirectionVertical, diff --git a/source/Grid/utils/getOverscanIndices.jest.js b/source/Grid/utils/defaultOverscanIndicesGetter.jest.js similarity index 93% rename from source/Grid/utils/getOverscanIndices.jest.js rename to source/Grid/utils/defaultOverscanIndicesGetter.jest.js index cb7124448..3d18e6860 100644 --- a/source/Grid/utils/getOverscanIndices.jest.js +++ b/source/Grid/utils/defaultOverscanIndicesGetter.jest.js @@ -1,9 +1,9 @@ -import getOverscanIndices, { +import overscanIndicesGetter, { SCROLL_DIRECTION_BACKWARD, SCROLL_DIRECTION_FORWARD -} from './getOverscanIndices' +} from './defaultOverscanIndicesGetter' -describe('getOverscanIndices', () => { +describe('overscanIndicesGetter', () => { function testHelper ({ cellCount, startIndex, @@ -11,7 +11,7 @@ describe('getOverscanIndices', () => { overscanCellsCount, scrollDirection }) { - return getOverscanIndices({ + return overscanIndicesGetter({ cellCount, overscanCellsCount, scrollDirection, diff --git a/source/Grid/utils/getOverscanIndices.js b/source/Grid/utils/defaultOverscanIndicesGetter.js similarity index 82% rename from source/Grid/utils/getOverscanIndices.js rename to source/Grid/utils/defaultOverscanIndicesGetter.js index 203513b93..370e44590 100644 --- a/source/Grid/utils/getOverscanIndices.js +++ b/source/Grid/utils/defaultOverscanIndicesGetter.js @@ -6,12 +6,12 @@ export const SCROLL_DIRECTION_FORWARD = 1 * This function ensures that overscanning doesn't exceed the available cells. * * @param cellCount Number of rows or columns in the current axis - * @param scrollDirection One of SCROLL_DIRECTION_BACKWARD + * @param scrollDirection One of SCROLL_DIRECTION_BACKWARD or SCROLL_DIRECTION_FORWARD * @param overscanCellsCount Maximum number of cells to over-render in either direction * @param startIndex Begin of range of visible cells * @param stopIndex End of range of visible cells */ -export default function getOverscanIndices ({ cellCount, overscanCellsCount, scrollDirection, startIndex, stopIndex }) { +export default function defaultOverscanIndicesGetter ({ cellCount, overscanCellsCount, scrollDirection, startIndex, stopIndex }) { let overscanStartIndex let overscanStopIndex