Handling Scroll Conflicts in Mini-Program Modal Overlays

When implementing modal dialogs in mini-programs, a common issue arises where both parent and child containers feature scrlolable areas, leading to conflicting scroll behaviors. This can result in an undesirable user experience where scrolling affects multiple layers simultaneously.

The solution involves controlling scroll behavior through dynamic state management and proper element structuring. Below is the implementation approach:

JavaScript Logic

const application = getApp()

Page({
  data: {
    enableScroll: true,
    modalVisible: false,
    viewportHeight: 0
  },
  
  onLoad:function(options){
    const that = this;
    
    // Calculate adaptive height
    wx.getSystemInfo({
      success: function (result) {
        const screenHeight = result.windowHeight
        const screenWidth = result.windowWidth
        const ratio = 750 / screenWidth
        
        // Adjust height accounting for bottom navigation
        const adjustedHeight = screenHeight * ratio - 100
        
        that.setData({
          viewportHeight: adjustedHeight
        })
      }
    })
  },
  
  openDialog:function () {
    this.setData({
      modalVisible: true,
      enableScroll: false
    })
  },
  
  closeDialog:function(){
    this.setData({
      modalVisible: false,
      enableScroll: true
    })
  }
})

CSS Styling

::-webkit-scrollbar{
  width: 0;
  height: 0;
  color: transparent;
}

.invisible{
  display: none
}

.visible{
  display: block;
}

scroll-view{
  width:100%;
  height:100%;
}

.modal-container{
  position: fixed;
  width: 750rpx;
  height: 100vh;
  overflow: auto;
  padding: 0 20rpx;
  top: 0;
  left: 0;
  background:#fff;
  z-index: 999;
}

WXML Structure

<view class="container">
 <scroll-view scroll-y="{{enableScroll}}" style="height:{{viewportHeight}}rpx">  
     <view class="form-section">
         <ul class="data-list">
            <li data-type="text">
                <view class="item-wrapper">
                    <span class="label">Name</span> 
                    <span class="value">
                      <input name="customerName" placeholder="Enter name" type="text"></input>
                    </span>
                </view>
            </li>
            <li data-type="text">
                <view class="item-wrapper">
                    <span class="label">Priority Level</span> 
                    <span class="value">
                      <button bindtap='openDialog'>Select</button>
                    </span>
                </view>
            </li>
        </ul>
     </view>
 </scroll-view>  
  
 <!-- Modal overlay content -->
 <scroll-view>  
    <view class="modal-container invisible{{modalVisible?'visible':''}}">
      <!-- Modal content goes here -->
    </view>
 </scroll-view>
</view>

Implementation Strategy

  1. Parent Scroll Control: Wrap the main content within a <scroll-view> element and dynamically control its scroll behavior via the scroll-y attribute. The height is calculated based on device dimensions, with adjustments made for interface elements like bottom navigation bars.
  2. Modal Interaction: When triggering the modal dialog through button interaction, set the scroll control flag to false to disable parent scrolling. Upon closing the modal, restore the flag to true to re-enable scrolling functionality.

This approach ensures that only one scrollable area remains active at any given time, preventing the dual-scrolling conflict commonly encountered in layered mini-program interfaces.

Tags: mini-program scroll-view modal-dialog wechat-miniprogram ui-interaction

Posted on Thu, 06 Aug 2026 16:06:45 +0000 by joshmmo