# recycle-view

Mini Program long list component

Using this component requires a dependency on the Mini Program base library 2.2.2 Version, while relying on the developer tool s npm Build. Details can be found atOfficial npm file。

# background

At present, there will be a lot of application scenarios in the use of infinite long list of interaction, when a page shows a lot ofinformation, will cause the Mini Program page of the Carton and white screen. The reasons are as follows:

List data is large, for the first time setData It is time consuming.
Render the list HOUSE Structure more, each time setData Need to create a new virtual tree, and the old tree diff Operation time is relatively high
Render the list HOUSE The structure is much, the memory occupied is high, the probability that the page is recovered by the system becomes large.

Hence the long list component to solve these problems.

# Realization train

The core idea is to render only the data displayed on the screen, the basic implementation is to monitor scroll Event, and recalculates the data that needs to be rendered, leaving an empty div Placeholder element.

Suppose the list data is 100 Item, know the location of the scroll, how to know which item Must be displayed on the page? because item It's not rendered yet. Can't pass. getComputedStyle etc. HOUSE Operation gets each item So there's no way to know which ones item Need to render. To solve this problem, each item Fixed width and height. item For the definition of width and height, see the following API ofcreateRecycleContext()Parameter itemSize The introduction.

While you are scrolling, you need to set the pre- and post-data values of the current data. div Placeholder height, also within the same render cycle. The page is rendered by setData Triggered, list data and div Occupancy height in 2 components setData In order to put these two setData In the same render cycle with a hack Method, so define the recycle-view of batch Attribute is fixed to batch=""。

In the scrolling process, to avoid frequent white screen, will be more than the current screen before and after the content of the rendering.

# Package structure

The long list component consists of 2 custom components recycle-view、recycle-item And a group API Consists of the following code structure

 miniprogram-recycle-view/
     recycle-view assembly
     recycle-item assembly
     index.js

The package structure is described in detail as follows:

catalog/file	describe
recycle-view assembly	Long list component
recycle-item assembly	Long list each item item assembly
index.js	API for manipulating long list data

# Methods of Use

Installation components

npm install --Save. miniprogram-recycle-view

On the page json Add in configuration file recycle-view and recycle-item Configuration of custom components

{
  "usingComponents": {
    "recycle-view": "miniprogram-recycle-view/recycle-view",
    "recycle-item": "miniprogram-recycle-view/recycle-item"
  }
}

WXML Reference in file recycle-view

<recycle-view batch="{{batchSetRecycleData}}" id="recycleId">
  <view slot="before">Contents at the front of the long list</view>
  <recycle-item wx:for="{{recycleList}}" wx:key="id">
    <view>
        <image style='width:80pxheight:80pxfloat:left' src="{{item.image_url}}"></image>
      {{item.idx+1}}. {{item.title}}
    </view>
  </recycle-item>
  <view slot="after">What follows a long list</view>
</recycle-view>

recycle-view The properties are described as follows:

Field name	type	Required	describe
id	String	yes	ID must be a unique string for the page
batch	Boolean	yes	Must be set toTo take effect
height	Number	no	Sets the height of the recycle-view, which defaults to the page height
width	Number	no	Set the width of the recycle-view, which defaults to the page width
enable-back-to-top	Boolean	no	The default is false, with the same name as the scroll-view field
scroll-top	Number	no	The default is false, with the same name as the scroll-view field
scroll-y	Number	no	Default to true, same name as scroll-view field
scroll-to-index	Number	no	Set items that scroll to a long list
placeholder-image	String	no	Default placeholder background image, when the rendering is not timely, it is not recommended to use large images as placeholder. We recommend passing in the Base64 format for SVG, using thetoolConvert SVG code to Base64 format. Supports setting rpx in SVG.
scroll-with-animation	Boolean	no	The default is false, with the same name as the scroll-view field
lower-threshold	Number	no	The default is false, with the same name as the scroll-view field
upper-threshold	Number	no	The default is false, with the same name as the scroll-view field
bindscroll	event	no	Same scroll-view Same-name paragraph
bindscrolltolower	event	no	Same scroll-view Same-name paragraph
bindscrolltoupper	event	no	Same scroll-view Same-name paragraph

recycle-view Includes 3 Slot, as follows:

Name	describe
before	default slot The non - recycle area in front of
default slot	Long list display area, recycle-item Must be defined by default slot in
after	default slot The non-recycling area behind

The contents of a long list are actually in a scroll-view In the scrolling area, when the long list is not just a single list, for example, we have a list at the bottom of the page. copyright We can put this part of the content in the before and after These two slot Inside.

recycle-item The following is a description of the

Note that the recycle-item Must be defined in wx:for The list loop should not pass the setData To set up wx:for Instead of binding variables, thecreateRecycleContextMethod creationRecycleContextObject to manage data,createRecycleContextin index.js Defined in the file. Recommend simultaneous setting Wx: key to improve the rendering performance of lists.

page JS Administration recycle-view Data

const createRecycleContext = require('miniprogram-recycle-view')
Page({
    onReady: function() {
        where ctx = createRecycleContext({
          id: 'recycleId',
          dataKey: 'recycleList',
          page: this,
          itemSize: { // This parameter can also be passed directly to the this.itemSizeFunc function defined below
            width: 162,
            height: 182
          }
        })
        ctx.append(newList)
        // ctx.update(beginIndex, list)
        // ctx.destroy()
    },
    itemSizeFunc: function (item, idx) {
        return {
            width: 162,
            height: 182
        }
    }
})

The page must pass Component Constructor definition, the page introduces theminiprogram-recycle-viewAfter the bag, it will be wx New interface under objectcreateRecycleContextFunction creationRecycleContextObject to manage recycle-view Defined data,createRecycleContextReceive type 1 Object Parameter, Object Parameter for each of the key The following is a description of the

Parameter name	type	describe
id	String	Corresponding recycle-view of id The value of the property
dataKey	String	Corresponding recycle-item of wx:for Binding variable name for property setting
page	Page/Component	recycle-view An instance of the page or component in which the this
itemSize	Object/Function	This parameter is used to generate the width and height of the recycle-item. As mentioned earlier, to know which items are currently being rendered, you must know the height and width of an item in order to calculate it Object must contain {width, Height} Two properties, Function receives item, Index returns a list containing {width, height}的Object ItemSize If it is a function, the function inside`this`Point to RecycleContext If the style uses rpx, it can be converted to px via transformRpx. As an Object, there is another use, described in the itemSize section below.
useInPage	Boolean	Whether the entire page has only a recycle-view. The definition of Page must have at least an empty onPageScroll function. This is used for long lists at the page level, and the onPull Down Refresh effect is used. And must be set`root`Parameter is the current page object
root	Page	The current page object, which can be retrieved by getCurrentPages, Must be supplied when useInPage is true

RecycleContext Object provides methods such as

method	parameter	Introductions
append	list, callback	Appends list data to the current long list data. Callback is a callback function for rendering
splice	begin, count, list, callback	insert/Deletes a long list of data, with arguments identical to Array'sspliceFunction, callback is the callback function for rendering completion
update	begin, list, callback	Update the long list of data, starting with the index parameter begin, update to the parameter list, the parameter callback with splice.
destroy	nothing	Destroy the RecycleContext object and call this method when the recycle-view is destroyed
forceUpdate	callback, reinitSlot	Re-render recycle-view. Callback is the render completion callback, called when the height of before and after slots changes, and the reinit slot is set to true. This method is also called when the width and height of the item changes.
getBoundingClientRect	index	Gets the position of a data item in a long list, returning {left, top, width, height}的Object。
getScrollTop	nothing	Gets the current scroll position for a long list.
transformRpx	rpx	Converts rpx to px and returns the converted px integer. ItemSize returns the unit of width and height in px. You can call this function here to convert rpx to px with a Number parameter, such as ctx.transformRpx(140)Returns 70. Note that transformRpx is rounded, so(20) + transformRpx(90)Not necessarily equal to transformRpx(110)
getViewportItems	inViewportPx	Gets the data items in the window to determine whether an item is present in a window. Reported for exposure data, dishes and category linkage effect. The parameter inViewportPx indicates how many pixels from the screen to appear in the screen and can be negative.

among itemSize Use of

ItemSize can be a list containing {width, All data have only one width and height information. If there are more than one, you can provide a function that the long list component calls to generate the width and height information for each piece of data, as follows

function(item, index) {
    return {
        width: 195,
        height: item.azFirst  130 : 120
    }
}

# Tips

The value of the batch property must be set to。
The width of the recycle-item must be the same as the width and height of the itemSize setting, otherwise there will be a jumping bug.
The height of the recycle-view setting must match the style set in its style.
createRecycleContext(options)The id parameter of the recycle-view must match the id attribute of the recycle-view, and the dataKey parameter must be the same as the variable name for the wx: for binding of the recycling -item.
If you cannot use the index variable of wx: for as an index value in a recycle-item, use {{item.__index__Alternative.
Instead of setting the variable value of the wx: for of the recycle-item via setData, it is recommended that the recycle-item set the property wx; key.
If the long list contains images, you must ensure that the image resource is HTTP cached, otherwise a lot of image requests will be made during scrolling.
Some data may not be rendered and may be invalidated when using wx.createSelectorQuery, instead use the getBoundingClientRect of Recycle Context.
When the useInPage parameter is used, the onPageScroll event must be defined in the Page.
TransformRpx rounds, sotransformRpx(20) + transformRpx(90)Not necessarily equal totransformRpx(110)
If there are more than one long list on a page, the batch-key attribute must be set more than once, and the value of each batch must differ from the variable of the batch attribute. for example

<recycle-view batch="{{batchSetRecycleData}}" batch-key="batchSetRecycleData"></recycle-view>
<recycle-view batch="{{batchSetRecycleData1}}" batch-key="batchSetRecycleData1"></recycle-view>