Using VirtualList, VirtualGridList and Scroller
This document describes VirtualList, VirtualGridList, and Scroller.
VirtualList/VirtualGridList
Basic usage of VirtualList and VirtualGridList
-
At least four props below are required to show a list properly.
-
data
: Data for passing through to thecomponent
prop. For performance reason, changing this prop does NOT always cause the list to redraw its items. -
dataSize
: Size of the data. A list does not check the size ofdata
prop. dataSize prop is the only value to count items in a list. -
itemSize
: Size of an item for the list. You will get an error when you build an app in dev mode without it. For the VirtualList, valid value is a number. For the VirtualGridList, valid value is an object that hasminWidth
andminHeight
as properties. -
component
: The render function for an item of the list. The list does NOT always render a component whenever its render function is called due to performance optimization.data
is for accessing the supplieddata
property of the list. In most cases, it is recommended to use data from redux store instead of using this parameter due to performance optimizations.data-index
is required for Spotlight 5-way navigation. Pass to the root element in the component.index
is the index number of the component to renderkey
MUST be passed as a prop to the root element in the component for DOM recycling.
-
Example
<VirtualList component={this.renderItem} data={data} dataSize={data.length} itemSize={ri.scale(72)} /> <VirtualGridList component={this.renderItem} data={data} dataSize={data.length} itemSize={{minWidth: ri.scale(90), minHeight: ri.scale(135)}} />
-
-
If you want to provide spacing or other numeric properties, you have to specify them as a number surrounded by braces, not as a string by quotes.
<VirtualList component={this.renderItem} data={data} dataSize={data.length} //<-- numeric property itemSize={ri.scale(72)} //<-- numeric property spacing={ri.scale(10)} //<-- numeric property />
Common rules of Items for VirtualList/VirtualGridList
-
A renderer for an item should be specified in
component
prop in VirtualList as a function. -
VirtualList passes
data
,index
,data-index
, andkey
to thecomponent
function. -
Be sure you are passing
{...rest}
to the item component for reusing DOM. -
VirtualList will automatically give proper className for items.
-
Be sure to compose
className
prop when you make customized item component. -
Make sure you are not using an inline function for
component
. -
If you want to scroll the list via 5-way navigation on the certain component in an item, you should pass
data-index
prop. -
Example:
//.js renderItem = ({data, index, ...rest}) => { return ( <div {...rest}> {data[index].name} </div> ); } ... render = () => { return ( <VirtualList component={this.renderItem} data={data} dataSize={data.length} itemSize={this.itemSize} /> ); }
-
If you create a custom item, make sure you are passing props from parents (render function) to the child.
//MyListItem.js const MyListItem = kind({ ..... render = (props) => { //<-- should pass props return ( <div {...props}> ... </div> ); } }); //app.js renderItem = ({data, index, ...rest}) => { return ( <MyListItem index={index} {...rest} /> ); }
Items for VirtualGridList
-
GridListImageItem
components can be used as items ofVirtualGridList
. They have Moonstone styling applied and have a placeholder image as a background. -
caption
andsubCaption
are supported. -
For showing Moonstone’s selection overlay, set
selectionOverlayShowing
totrue
. (default isfalse
) -
selected
prop shows item’s status of selection. -
source
prop should be set to URL path. (e.g.source="http://XXXX/image.png"
,source="../assets/image.png"
) -
Example:
renderItem = ({data, index, ...rest}) => { const {text, subText, source} = data[index]; return ( <GridListImageItem {...rest} caption={text} className={css.item} source={source} subCaption={subText} /> ); };
Scroller
Basic usage of Scroller
-
Make sure you specify width and height of Scroller.
-
You can specify the scrollable direction with
direction
props. Valid values areboth
,horizontal
, andvertical
. -
Example:
//.less .scroller { height: 550px; width: 480px; } //.js <Scroller className={css.scroller} direction="both" > <div className={css.content}> Lorem ipsum dolor sit amet, consectetur adipiscing elit.<br /> </div> </Scroller>
Using scrollTo()
method in VirtualList/VirtualGridList and Scroller
-
Prop
cbScrollTo
is a callback function.VirtualList
,VirtualGridList
, andScroller
providecbScrollTo
prop which can be set to a callback function that will receive thescrollTo()
method.- The callback function is called just once when a list or a scroller is created to prevent repeated calls when a list or a scroller is updated.
- Do not change
cbScrollTo
prop after a list or a scroller is mounted. It does not have any effect.
-
The binding of a callback function
- Please make sure the context of a callback function is properly bound. In general, your app component instance would be the right one.
- We recommend to use ECMAScript 2015 (a.k.a ECMAScript 6 or ES6) arrow functions to handle binding.
-
Example:
class SampleApp extends React.Component { constructor (props) { super(props); this.y = 0; } ... getScrollTo = (scrollTo) => { // callback function to get scrollTo method; arrow function (ES6) is recommended to make sure `this` binding. this.scrollTo = scrollTo; } ... doSomething = () => { ... this.scrollTo({position: {y: this.y + offset}, animate: true}); // call the function of SampleApp, not a list. } ... render = () => { return ( <VirtualList cbScrollTo={this.getScrollTo} // pass callback function component={this.renderItem} data={data} dataSize={data.length} itemSize={this.itemSize} /> ); } }
-
Example:
this.scrollTo({position: {y: 100}, animate: false}); // scroll y position to 100px without animation this.scrollTo({position: {x: 100, y: 200}); // scroll to (100px, 200px) position; animation is enabled if omitted this.scrollTo({align: 'bottom'}); // scroll to the bottom this.scrollTo({align: 'lefttop'}); // scroll to the left top position; identical to {position: {x: 0, y:0}} this.scrollTo({index: 20}); // VirtualList/VirtualGridList only; scroll to the 21st item; index is counting from 0 this.scrollTo({index: 20, focus: true}); // VirtualList/VirtualGridList only; scroll to the 21st item and focus on the item this.scrollTo({node: childNode}); // Scroller only; scroll to the child node. this.scrollTo({node: childNode, focus: true}); // Scroller only; scroll to the child node and focus on the node.
Event Callbacks for VirtualList, VirtualGridList, and Scroller
-
You can specify callback functions for scroll events.
-
When you scroll on a list or a scroller,
onScrollStart
,onScroll
, andonScrollStop
events fire. -
Each event sends an object with
scrollLeft
,scrollTop
, andmoreInfo
properties in it. -
For VirtualList/VirtualGridList,
moreInfo
hasfirstVisibleIndex
andlastVisibleIndex
. -
It is recommended not to call
setState()
inonScroll
event callback. -
Example:
//app.js ... handlerOnScrollStart = () => { this.setState({message: 'startScroll'}); } handlerOnScroll = ({scrollTop}) => { this.y = scrollTop; } handlerOnScrollStop = ({scrollTop}) => { this.y = scrollTop; this.setState({message: 'scrollStopped'}); } ... render = () => { return ( <VirtualList ... onScrollStart={this.handlerOnScrollStart} onScroll={this.handlerOnScroll} onScrollStop={this.handlerOnScrollStop} /> ); }