更新记录

1.0.1（2026-04-01） 下载此版本

一款高性能、跨平台的图片对比滑块组件，专为 uni-app 开发设计。支持原图与效果图的滑动对比展示，广泛适用于前后效果对比、滤镜对比、修图前后对比等场景。组件采用 rpx 单位与 SCSS 样式，完美适配小程序、App 端及 H5 端，提供流畅的触摸拖拽体验。

平台兼容性

uni-app(5.05)

ImageCompareSlider 组件说明

ImageCompareSlider 是一个支持手指/鼠标拖拽对比滑块的图片比较组件，支持 H5 和 UniApp 多端使用。

特性包括：

• 可设置初始滑块位置
• 支持自定义滤镜效果
• 支持圆角、宽度自定义
• 拖拽节流控制
• 自动适配移动端尺寸

示例用法

<ImageCompareSlider
  :before-image="beforeImgUrl"
  :after-image="afterImgUrl"
  :init-position="50"
  :width="'100%'"
  :border-radius="'24rpx'"
  :enable-filter="true"
  :custom-filter="'grayscale(80%)'"
  :throttle-delay="16"
  @change="onSliderChange"
  @dragStart="Start"
  @dragEnd="End"
/>
Props
参数名           类型       默认值       说明
beforeImage     String     必填         原图地址
afterImage      String     ''           对比图地址，不传则使用原图+滤镜
initPosition    Number     50           初始滑块百分比位置（0~100）
enableFilter    Boolean    true         未传 afterImage 时是否应用滤镜
customFilter    String     ''           自定义 CSS filter
width           String     '100%'       容器宽度，支持 rpx/px/%
borderRadius    String     '24rpx'      容器圆角大小
throttleDelay   Number     16           拖拽节流延迟（ms）
Data（数据）
sliderPercent       当前滑块百分比位置
containerRect       容器尺寸及左偏移
isDragging          是否正在拖拽
startPercent        拖拽起始百分比
startClientX        拖拽起始横坐标
throttleTimer       拖拽节流定时器
beforeImageRect     原图尺寸信息
imageLoadError      图片加载错误状态
Computed（计算属性）
containerStyle      容器样式
imageStyle          原图样式（绝对定位覆盖）
computedAfterImage  上层对比图地址
afterFilterStyle    上层滤镜样式，支持自定义或默认灰度/对比度/亮度滤镜
Methods（方法）
图片尺寸与容器
beforeImageRectFn()      获取原图显示尺寸
getContainerRect()       获取容器尺寸（拖拽计算用）
()               窗口尺寸变化时更新容器信息
onPlaceholderLoad()      占位图加载完成时更新容器信息
onPlaceholderError()     原图加载失败处理
滑块计算与控制
calcPercentByClientX(clientX)    根据横坐标计算百分比
setSliderPercent(percent, emit)  更新滑块位置
setPosition(percent)             对外手动设置滑块位置
reset()                          重置滑块到初始位置
拖拽事件
onHandleStart(e)        拖拽开始
startDrag(clientX)      初始化拖拽状态
onHandleMove(e)         拖拽移动
updateDragPosition(x)   拖拽位置更新（节流控制）
doUpdatePosition(x)     执行实际位置更新
onHandleEnd()           拖拽结束
onGlobalMouseMove(e)    全局鼠标移动事件
onGlobalMouseUp()       全局鼠标释放事件
removeGlobalEvents()    移除全局事件监听
Events（事件）
事件名      参数             说明
change      sliderPercent    滑块位置变化
dragStart   sliderPercent    开始拖拽
dragEnd     sliderPercent    拖拽结束
样式（SCSS）
.compare-slider {
  position: relative;
  width: 100%;
  overflow: hidden;

  .placeholder-img {
    display: block;
    width: 100%;
    height: auto;
    visibility: hidden;
    pointer-events: none;
  }

  .compare-img {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: #f0f0f0;
  }

  .after-wrapper {
    position: absolute;
    top: 0;
    left: 0;
    height: 100%;
    overflow: hidden;
    z-index: 2;

    .after-img {
      width: 100%;
      height: 100%;
    }
  }

  .compare-handle {
    position: absolute;
    top: 0;
    bottom: 0;
    width: 6rpx;
    background: #ffffff;
    z-index: 10;
    transform: translateX(-50%);
    box-shadow: 0 0 12rpx rgba(0, 0, 0, 0.5), 0 0 0 4rpx rgba(255, 255, 255, 0.8);
    border-radius: 6rpx;
    touch-action: none;

    .handle-circle {
      position: absolute;
      top: 50%;
      left: 50%;
      width: 56rpx;
      height: 56rpx;
      background: white;
      border-radius: 50%;
      transform: translate(-50%, -50%);
      box-shadow: 0 6rpx 20rpx rgba(0, 0, 0, 0.3);
      display: flex;
      align-items: center;
      justify-content: center;
      transition: transform 0.1s ease;

      &::before {
        content: "⇄";
        font-family: monospace;
        font-size: 32rpx;
        font-weight: bold;
        color: #2c3e66;
      }
    }

    &:active .handle-circle {
      transform: translate(-50%, -50%) scale(1.08);
    }
  }
}

@media (max-width: 750rpx) {
  .compare-handle .handle-circle {
    width: 68rpx;
    height: 68rpx;
    &::before {
      font-size: 40rpx;
    }
  }
}
功能特点
占位图撑高容器：避免容器高度塌陷
上层对比图动态宽度：通过 sliderPercent 控制显示
拖拽节流：减少频繁渲染，提升性能
移动端优化：手指拖拽适配，滑块大小自适应
滤镜支持：默认灰度/亮度/对比度，支持自定义 CSS filter
可编程控制：通过 setPosition 和 reset 方法控制滑块位置