ListView.js

/**
 * Copyright 2004-present Facebook. All Rights Reserved.
 *
 * @providesModule ListView
 */
'use strict';

var ListViewDataSource = require('ListViewDataSource');
var React = require('React');
var RKUIManager = require('NativeModules').RKUIManager;
var ScrollView = require('ScrollView');
var ScrollResponder = require('ScrollResponder');
var StaticRenderer = require('StaticRenderer');
var TimerMixin = require('TimerMixin');

var logError = require('logError');
var merge = require('merge');
var isEmpty = require('isEmpty');

var PropTypes = React.PropTypes;

/**
 * ListView - A core component designed for efficient display of vertically
 * scrolling lists of changing data.  The minimal API is to create a
 * `ListViewDataSource`, populate it with a simple array of data blobs, and
 * instantiate a `ListView` component with that data source and a `renderRow`
 * callback which takes a blob from the data array and returns a renderable
 * component. Minimal example:
 *
 *   getInitialState: function() {
 *     var ds = new ListViewDataSource({rowHasChanged: (r1, r2) => r1 !== r2});
 *     return {
 *       dataSource: ds.cloneWithRows(['row 1', 'row 2']),
 *     };
 *   },
 *
 *   render: function() {
 *     return (
 *       <ListView
 *         dataSource={this.state.dataSource}
 *         renderRow={(rowData) => <Text>{rowData}</Text>}
 *       />
 *     );
 *   },
 *
 * ListView also supports more advanced features, including sections with sticky
 * section headers, header and footer support, callbacks on reaching the end of
 * the available data (`onEndReached`) and on the set of rows that are visible
 * in the device viewport change (`onChangeVisibleRows`), and several
 * performance optimizations.
 *
 * There are a few performance operations designed to make ListView scroll
 * smoothly while dynamically loading potentially very large (or conceptually
 * infinite) data sets:
 *
 *  * Only re-render changed rows - the hasRowChanged function provided to the
 *    data source tells the ListView if it needs to re-render a row because the
 *    source data has changed - see ListViewDataSource for more details.
 *
 *  * Rate-limited row rendering - By default, only one row is rendered per
 *    event-loop (customizable with the `pageSize` prop).  This breaks up the
 *    work into smaller chunks to reduce the chance of dropping frames while
 *    rendering rows.
 *
 * Check out `ListViewSimpleExample.js`, `ListViewDataSource.js`, and the Movies
 * app for more info and example usage.
 */

var DEFAULT_PAGE_SIZE = 1;
var DEFAULT_INITIAL_ROWS = 10;
var DEFAULT_SCROLL_RENDER_AHEAD = 1000;
var DEFAULT_END_REACHED_THRESHOLD = 1000;
var DEFAULT_SCROLL_CALLBACK_THROTTLE = 50;
var RENDER_INTERVAL = 20;
var SCROLLVIEW_REF = 'listviewscroll';

var ListView = React.createClass({
  mixins: [ScrollResponder.Mixin, TimerMixin],

  /**
   * You must provide a renderRow function. If you omit any of the other render
   * functions, ListView will simply skip rendering them.
   *
   * - renderRow(rowData, sectionID, rowID);
   * - renderSectionHeader(sectionData, sectionID);
   */
  propTypes:
    merge(
      ScrollView.PropTypes, {
      dataSource: PropTypes.instanceOf(ListViewDataSource).isRequired,
      /**
       * (rowData, sectionID, rowID) => renderable
       * Takes a data entry from the data source and its ids and should return
       * a renderable component to be rendered as the row.  By default the data
       * is exactly what was put into the data source, but it's also possible to
       * provide custom extractors.
       */
      renderRow: PropTypes.func.isRequired,
      /**
       * How many rows to render on initial component mount.  Use this to make
       * it so that the first screen worth of data apears at one time instead of
       * over the course of multiple frames.
       */
      initialListSize: PropTypes.number,
      /**
       * Called when all rows have been rendered and the list has been scrolled
       * to within onEndReachedThreshold of the bottom.  The native scroll
       * event is provided.
       */
      onEndReached: PropTypes.func,
      /**
       * Threshold in pixels for onEndReached.
       */
      onEndReachedThreshold: PropTypes.number,
      /**
       * Number of rows to render per event loop.
       */
      pageSize: PropTypes.number,
      /**
       * () => renderable
       *
       * The header and footer are always rendered (if these props are provided)
       * on every render pass.  If they are expensive to re-render, wrap them
       * in StaticContainer or other mechanism as appropriate.  Footer is always
       * at the bottom of the list, and header at the top, on every render pass.
       */
      renderFooter: PropTypes.func,
      renderHeader: PropTypes.func,
      /**
       * (sectionData, sectionID) => renderable
       *
       * If provided, a sticky header is rendered for this section.  The sticky
       * behavior means that it will scroll with the content at the top of the
       * section until it reaches the top of the screen, at which point it will
       * stick to the top until it is pushed off the screen by the next section
       * header.
       */
      renderSectionHeader: PropTypes.func,
      /**
       * How early to start rendering rows before they come on screen, in
       * pixels.
       */
      scrollRenderAheadDistance: React.PropTypes.number,
      /**
       * (visibleRows, changedRows) => void
       *
       * Called when the set of visible rows changes.  `visibleRows` maps
       * { sectionID: { rowID: true }} for all the visible rows, and
       * `changedRows` maps { sectionID: { rowID: true | false }} for the rows
       * that have changed their visibility, with true indicating visible, and
       * false indicating the view has moved out of view.
       */
      onChangeVisibleRows: React.PropTypes.func,
      /**
       * An experimental performance optimization for improving scroll perf of
       * large lists, used in conjunction with overflow: 'hidden' on the row
       * containers.  Use at your own risk.
       */
      removeClippedSubviews: React.PropTypes.bool,
  }),

  /**
   * Exports some data, e.g. for perf investigations or analytics.
   */
  getMetrics: function() {
    return {
      contentHeight: this.scrollProperties.contentHeight,
      totalRows: this.props.dataSource.getRowCount(),
      renderedRows: this.state.curRenderedRowsCount,
      visibleRows: Object.keys(this._visibleRows).length,
    };
  },

  /**
   * Provides a handle to the underlying scroll responder to support operations
   * such as scrollTo.
   */
  getScrollResponder: function() {
    return this.refs[SCROLLVIEW_REF];
  },

  setNativeProps: function(props) {
    this.refs[SCROLLVIEW_REF].setNativeProps(props);
  },

  /**
   * React life cycle hooks.
   */

  getDefaultProps: function() {
    return {
      initialListSize: DEFAULT_INITIAL_ROWS,
      pageSize: DEFAULT_PAGE_SIZE,
      scrollRenderAheadDistance: DEFAULT_SCROLL_RENDER_AHEAD,
      onEndReachedThreshold: DEFAULT_END_REACHED_THRESHOLD,
    };
  },

  getInitialState: function() {
    return {
      curRenderedRowsCount: this.props.initialListSize,
      prevRenderedRowsCount: 0,
    };
  },

  componentWillMount: function() {
    // this data should never trigger a render pass, so don't put in state
    this.scrollProperties = {
      visibleHeight: null,
      contentHeight: null,
      offsetY: 0
    };
    this._childFrames = [];
    this._visibleRows = {};
  },

  componentDidMount: function() {
    // do this in animation frame until componentDidMount actually runs after
    // the component is laid out
    this.requestAnimationFrame(() => {
      this._measureAndUpdateScrollProps();
      this.setInterval(this._renderMoreRowsIfNeeded, RENDER_INTERVAL);
    });
  },

  componentWillReceiveProps: function(nextProps) {
    if (this.props.dataSource !== nextProps.dataSource) {
      this.setState({prevRenderedRowsCount: 0});
    }
  },

  render: function() {
    var bodyComponents = [];

    var dataSource = this.props.dataSource;
    var allRowIDs = dataSource.rowIdentities;
    var rowCount = 0;
    var sectionHeaderIndices = [];

    var header = this.props.renderHeader && this.props.renderHeader();
    var footer = this.props.renderFooter && this.props.renderFooter();
    var totalIndex = header ? 1 : 0;

    for (var sectionIdx = 0; sectionIdx < allRowIDs.length; sectionIdx++) {
      var sectionID = dataSource.sectionIdentities[sectionIdx];
      var rowIDs = allRowIDs[sectionIdx];
      if (rowIDs.length === 0) {
        continue;
      }

      if (this.props.renderSectionHeader) {
        var shouldUpdateHeader = rowCount >= this.state.prevRenderedRowsCount &&
          dataSource.sectionHeaderShouldUpdate(sectionIdx);
        bodyComponents.push(
          <StaticRenderer
            key={'s_' + sectionID}
            shouldUpdate={!!shouldUpdateHeader}
            render={this.props.renderSectionHeader.bind(
              null,
              dataSource.getSectionHeaderData(sectionIdx),
              sectionID
            )}
          />
        );
        sectionHeaderIndices.push(totalIndex++);
      }

      for (var rowIdx = 0; rowIdx < rowIDs.length; rowIdx++) {
        var rowID = rowIDs[rowIdx];
        var comboID = sectionID + rowID;
        var shouldUpdateRow = rowCount >= this.state.prevRenderedRowsCount &&
          dataSource.rowShouldUpdate(sectionIdx, rowIdx);
        var row =
          <StaticRenderer
            key={'r_' + comboID}
            shouldUpdate={!!shouldUpdateRow}
            render={this.props.renderRow.bind(
              null,
              dataSource.getRowData(sectionIdx, rowIdx),
              sectionID,
              rowID
            )}
          />;
        bodyComponents.push(row);
        totalIndex++;
        if (++rowCount === this.state.curRenderedRowsCount) {
          break;
        }
      }
      if (rowCount >= this.state.curRenderedRowsCount) {
        break;
      }
    }

    var props = merge(
      this.props, {
        onScroll: this._onScroll,
        stickyHeaderIndices: sectionHeaderIndices,
      }
    );
    if (!props.throttleScrollCallbackMS) {
      props.throttleScrollCallbackMS = DEFAULT_SCROLL_CALLBACK_THROTTLE;
    }

    return (
      <ScrollView {...props}
        ref={SCROLLVIEW_REF}>
        {header}
        {bodyComponents}
        {footer}
      </ScrollView>
    );
  },

  /**
   * Private methods
   */

  _measureAndUpdateScrollProps: function() {
    RKUIManager.measureLayout(
      this.refs[SCROLLVIEW_REF].getInnerViewNode(),
      this.refs[SCROLLVIEW_REF].getNodeHandle(),
      logError,
      this._setScrollContentHeight
    );
    RKUIManager.measureLayoutRelativeToParent(
      this.refs[SCROLLVIEW_REF].getNodeHandle(),
      logError,
      this._setScrollVisibleHeight
    );
  },

  _setScrollContentHeight: function(left, top, width, height) {
    this.scrollProperties.contentHeight = height;
  },

  _setScrollVisibleHeight: function(left, top, width, height) {
    this.scrollProperties.visibleHeight = height;
    this._updateVisibleRows();
  },

  _renderMoreRowsIfNeeded: function() {
    if (this.scrollProperties.contentHeight === null ||
      this.scrollProperties.visibleHeight === null ||
      this.state.curRenderedRowsCount === this.props.dataSource.getRowCount()) {
      return;
    }

    var distanceFromEnd = this._getDistanceFromEnd(this.scrollProperties);
    if (distanceFromEnd < this.props.scrollRenderAheadDistance) {
      this._pageInNewRows();
    }
  },

  _pageInNewRows: function() {
    var rowsToRender = Math.min(
      this.state.curRenderedRowsCount + this.props.pageSize,
      this.props.dataSource.getRowCount()
    );
    this.setState(
      {
        prevRenderedRowsCount: this.state.curRenderedRowsCount,
        curRenderedRowsCount: rowsToRender
      },
      () => {
        this._measureAndUpdateScrollProps();
        this.setState({
          prevRenderedRowsCount: this.state.curRenderedRowsCount,
        });
      }
    );
  },

  _getDistanceFromEnd: function(scrollProperties) {
    return scrollProperties.contentHeight -
      scrollProperties.visibleHeight -
      scrollProperties.offsetY;
  },

  _updateVisibleRows: function(e) {
    if (!this.props.onChangeVisibleRows) {
      return; // No need to compute visible rows if there is no callback
    }
    var updatedFrames = e && e.nativeEvent.updatedChildFrames;
    if (updatedFrames) {
      updatedFrames.forEach((frame) => {
        this._childFrames[frame.index] = merge(frame);
      });
    }
    var dataSource = this.props.dataSource;
    var visibleTop = this.scrollProperties.offsetY;
    var visibleBottom = visibleTop + this.scrollProperties.visibleHeight;
    var allRowIDs = dataSource.rowIdentities;

    var header = this.props.renderHeader && this.props.renderHeader();
    var totalIndex = header ? 1 : 0;
    var visibilityChanged = false;
      var changedRows = {};
      for (var sectionIdx = 0; sectionIdx < allRowIDs.length; sectionIdx++) {
      var rowIDs = allRowIDs[sectionIdx];
      if (rowIDs.length === 0) {
        continue;
      }
      var sectionID = dataSource.sectionIdentities[sectionIdx];
      if (this.props.renderSectionHeader) {
        totalIndex++;
      }
      var visibleSection = this._visibleRows[sectionID];
      if (!visibleSection) {
        visibleSection = {};
      }
      for (var rowIdx = 0; rowIdx < rowIDs.length; rowIdx++) {
        var rowID = rowIDs[rowIdx];
        var frame = this._childFrames[totalIndex];
        totalIndex++;
        if (!frame) {
          break;
        }
        var rowVisible = visibleSection[rowID];
        var top = frame.y;
        var bottom = top + frame.height;
        if (top > visibleBottom || bottom < visibleTop) {
          if (rowVisible) {
            visibilityChanged = true;
            delete visibleSection[rowID];
            if (!changedRows[sectionID]) {
              changedRows[sectionID] = {};
            }
            changedRows[sectionID][rowID] = false;
          }
        } else if (!rowVisible) {
          visibilityChanged = true;
          visibleSection[rowID] = true;
          if (!changedRows[sectionID]) {
            changedRows[sectionID] = {};
          }
          changedRows[sectionID][rowID] = true;
        }
      }
      if (!isEmpty(visibleSection)) {
        this._visibleRows[sectionID] = visibleSection;
      } else if (this._visibleRows[sectionID]) {
        delete this._visibleRows[sectionID];
      }
    }
    visibilityChanged && this.props.onChangeVisibleRows(this._visibleRows, changedRows);
  },

  _onScroll: function(e) {
    this.scrollProperties.visibleHeight = e.nativeEvent.layoutMeasurement.height;
    this.scrollProperties.contentHeight = e.nativeEvent.contentSize.height;
    this.scrollProperties.offsetY = e.nativeEvent.contentOffset.y;
    this._updateVisibleRows(e);
    var nearEnd = this._getDistanceFromEnd(this.scrollProperties) < this.props.onEndReachedThreshold;
    if (nearEnd &&
        this.props.onEndReached &&
        this.scrollProperties.contentHeight !== this._sentEndForContentHeight &&
        this.state.curRenderedRowsCount === this.props.dataSource.getRowCount()) {
      this._sentEndForContentHeight = this.scrollProperties.contentHeight;
      this.props.onEndReached(e);
    } else {
      this._renderMoreRowsIfNeeded();
    }

    this.props.onScroll && this.props.onScroll(e);
  },
});

module.exports = ListView;