Lenis 平滑滚动实现原理深度解析

// Lenis 虚拟滚动的基本流程
class Lenis {
  constructor(options = {}) {
    this.targetScroll = 0;     // 目标滚动位置
    this.animatedScroll = 0;   // 当前动画位置
    this.velocity = 0;         // 滚动速度
    
    // 监听滚动事件
    this.addWheelListener();
    this.addTouchListener();
  }
  
  // 核心动画循环
  raf(time) {
    const deltaTime = time - this.lastTime;
    this.lastTime = time;
    
    // 计算平滑插值
    this.animate(deltaTime);
  }
  
  animate(deltaTime) {
    // 使用缓动函数进行插值
    const delta = this.targetScroll - this.animatedScroll;
    const lerp = 1 - Math.pow(1 - this.lerp, deltaTime / 16);
    
    this.animatedScroll += delta * lerp;
    this.velocity = delta * lerp;
    
    // 更新页面滚动位置
    this.updateScroll(this.animatedScroll);
  }
}

// 初始化 Lenis
const lenis = new Lenis({
  duration: 1.2,      // 动画持续时间
  easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)), // 缓动函数
  orientation: 'vertical',  // 滚动方向
  smoothWheel: true,  // 平滑鼠标滚轮
});

// 使用 RAF 驱动动画循环
function raf(time) {
  lenis.raf(time);
  requestAnimationFrame(raf);
}

requestAnimationFrame(raf);

// LERP 线性插值
function lerp(start, end, factor) {
  return start + (end - start) * factor;
}

// Lenis 默认使用的缓动函数
function easeOutExpo(t) {
  return t === 1 ? 1 : 1 - Math.pow(2, -10 * t);
}

// 在动画循环中应用
animate(deltaTime) {
  // 计算插值系数（基于时间）
  const lerpFactor = 1 - Math.pow(1 - this.lerp, deltaTime / 16);
  
  // 计算当前帧的滚动增量
  const delta = this.targetScroll - this.animatedScroll;
  
  // 应用缓动
  this.animatedScroll += delta * lerpFactor;
}

// 监听鼠标滚轮事件
addWheelListener() {
  window.addEventListener('wheel', (e) => {
    e.preventDefault(); // 阻止原生滚动
    
    // 计算滚动增量
    const delta = e.deltaY || e.deltaX;
    
    // 更新目标滚动位置
    this.targetScroll += delta;
    this.targetScroll = Math.max(0, Math.min(this.limit, this.targetScroll));
  }, { passive: false }); // 注意：必须设置 passive: false 才能 preventDefault
}

// 监听触摸事件
addTouchListener() {
  let startY = 0;
  
  window.addEventListener('touchstart', (e) => {
    startY = e.touches[0].clientY;
  }, { passive: true });
  
  window.addEventListener('touchmove', (e) => {
    const deltaY = startY - e.touches[0].clientY;
    this.targetScroll += deltaY;
    startY = e.touches[0].clientY;
  }, { passive: true });
}

class Lenis {
  constructor() {
    this.velocity = 0;        // 当前速度
    this.direction = 0;       // 滚动方向 (1 向下, -1 向上)
    this.isStopped = false;   // 是否已停止
  }
  
  animate(deltaTime) {
    const delta = this.targetScroll - this.animatedScroll;
    
    // 计算速度
    const currentVelocity = delta * this.lerp;
    this.velocity = currentVelocity;
    
    // 判断滚动方向
    this.direction = Math.sign(currentVelocity);
    
    // 应用滚动
    this.animatedScroll += currentVelocity;
    
    // 检查是否已停止（速度接近 0）
    if (Math.abs(currentVelocity) < 0.001) {
      this.isStopped = true;
      this.animatedScroll = this.targetScroll; // 对齐到目标位置
    }
  }
}

// 1. 引入 Lenis
import Lenis from 'lenis';

// 2. 初始化
const lenis = new Lenis({
  duration: 1.2,
  easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
  orientation: 'vertical',
  gestureOrientation: 'vertical',
  smoothWheel: true,
  wheelMultiplier: 1,
  smoothTouch: false,
  touchMultiplier: 2,
  infinite: false,
});

// 3. 监听滚动事件
lenis.on('scroll', (e) => {
  console.log('滚动位置:', e.scroll);
  console.log('滚动速度:', e.velocity);
  console.log('滚动方向:', e.direction);
});

// 4. RAF 动画循环
function raf(time) {
  lenis.raf(time);
  requestAnimationFrame(raf);
}

requestAnimationFrame(raf);

// 滚动到指定位置
lenis.scrollTo(500); // 滚动到 500px

// 滚动到指定元素
lenis.scrollTo('#section-2', {
  offset: 0,       // 偏移量
  duration: 1.5,   // 动画时长
  easing: (t) => 1 - Math.pow(1 - t, 3), // 自定义缓动
});

// 停止滚动
lenis.stop();

// 恢复滚动
lenis.start();

// 销毁实例
lenis.destroy();

import Lenis from 'lenis';
import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

const lenis = new Lenis();

// 同步 Lenis 和 ScrollTrigger
lenis.on('scroll', ScrollTrigger.update);

gsap.ticker.add((time) => {
  lenis.raf(time * 1000);
});

gsap.ticker.lagSmoothing(0);

// 创建滚动触发动画
gsap.to('.box', {
  scrollTrigger: {
    trigger: '.box',
    start: 'top center',
    end: 'bottom center',
    scrub: true,
  },
  x: 500,
  rotation: 360,
});

[data-lenis-wrapper] {
  will-change: transform;
}

// ❌ 错误：在 scroll 回调中读取布局属性
lenis.on('scroll', () => {
  const height = element.offsetHeight; // 触发强制重排
  element.style.transform = `translateY(${height}px)`;
});

// ✅ 正确：缓存布局值
const height = element.offsetHeight;
lenis.on('scroll', () => {
  element.style.transform = `translateY(${height}px)`;
});

// Lenis 内部已正确处理，但如果你添加自定义监听器：
lenis.on('scroll', handler); // Lenis 事件不需要 passive

// 你自己的监听器：
window.addEventListener('scroll', handler, { passive: true });

let rafId = null;

lenis.on('scroll', (e) => {
  if (rafId) return;
  
  rafId = requestAnimationFrame(() => {
    updateParallaxElements(e.scroll);
    rafId = null;
  });
});

document.querySelectorAll('a[href^="#"]').forEach(anchor => {
  anchor.addEventListener('click', function (e) {
    e.preventDefault();
    const target = document.querySelector(this.getAttribute('href'));
    lenis.scrollTo(target);
  });
});

<!-- 将固定元素放在 wrapper 外部 -->
<body>
  <header class="fixed-header">固定头部</header>
  <div data-lenis-wrapper>
    <!-- 滚动内容 -->
  </div>
</body>

const lenis = new Lenis({
  smoothTouch: false, // 移动端禁用平滑触摸
  touchMultiplier: 2, // 调整触摸灵敏度
});

用户操作（滚轮/触摸）
         ↓
    监听输入事件
         ↓
  计算目标滚动位置 (targetScroll)
         ↓
    RAF 动画循环
         ↓
  缓动插值计算 (LERP + Easing)
         ↓
 更新当前位置 (animatedScroll)
         ↓
  应用到页面 (transform/scrollTo)
         ↓
   触发 scroll 事件回调
         ↓
   浏览器渲染更新