# 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:

  1. List data is large, for the first time setData It is time consuming.
  2. 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
  3. 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

     recycle-view assembly
     recycle-item assembly

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

  1. Installation components

    npm install --Save. miniprogram-recycle-view
  2. 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"
  3. 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">
            <image style='width:80pxheight:80pxfloat:left' src="{{item.image_url}}"></image>
          {{item.idx+1}}. {{item.title}}
      <view slot="after">What follows a long list</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.

  4. page JS Administration recycle-view Data

    const createRecycleContext = require('miniprogram-recycle-view')
        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.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 insidethisPoint 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 setrootParameter 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

  1. The value of the batch property must be set to
  2. 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.
  3. The height of the recycle-view setting must match the style set in its style.
  4. 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.
  5. If you cannot use the index variable of wx: for as an index value in a recycle-item, use {{item.__index__Alternative.
  6. 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.
  7. 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.
  8. Some data may not be rendered and may be invalidated when using wx.createSelectorQuery, instead use the getBoundingClientRect of Recycle Context.
  9. When the useInPage parameter is used, the onPageScroll event must be defined in the Page.
  10. TransformRpx rounds, sotransformRpx(20) + transformRpx(90)Not necessarily equal totransformRpx(110)
  11. 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>