☰

Smooth Scroll

Universal smooth scrolling with improved performance and compatibility. (Exceptions on large sites)

2024-11-18 या दिनांकाला. सर्वात नवीन आवृत्ती पाहा.

लेखक
DXRK1E
रेटिंग
0 0 0
आवृत्ती
2.0
बनवली
2024-07-23
अपडेट केली
2024-11-18
आकार
8 KB
License
MIT
यांवर लागू होते:
सर्व संकेतस्थळे

Technical Details

Architecture Overview

The smooth scroll implementation uses a class-based architecture with three main components:

  1. State Management

    • Uses WeakMap for garbage-collection-friendly state storage
    • Tracks active scroll animations
    • Maintains frame timing information
    • Manages scroll accumulation data

  2. Event System

    • Wheel event handling with passive: false for prevention
    • Click/touch handling for scroll interruption
    • Visibility change detection for cleanup
    • Event delegation for better performance

  3. Animation System

    • RequestAnimationFrame-based animation loop
    • Subpixel accumulation for smooth motion
    • Dynamic refresh rate adaptation
    • Acceleration and smoothness calculations

How It Works

Initialization Process

  1. Script loads and creates a new SmoothScroll instance
  2. Checks for frame in top window context
  3. Sets up event listeners and polyfills
  4. Initializes state management system

Scroll Detection

  1. Wheel event captured with preventDefault capability
  2. Determines scrollable parent elements
  3. Checks scroll direction and capability
  4. Calculates initial scroll delta

Delta Processing

// Example of delta calculation
let delta = event.deltaY;
if (event.deltaMode === 1) { // LINE mode
    delta *= lineHeight;
} else if (event.deltaMode === 2) { // PAGE mode
    delta *= viewportHeight;
}

Animation Flow

  1. Initial Calculation

    const scrollAmount = pixels * (1 - smoothness);
const integerPart = Math.trunc(scrollAmount);
const fractionalPart = scrollAmount - integerPart;

  2. Subpixel Accumulation

    subpixels += fractionalPart;
let additionalPixels = Math.trunc(subpixels);
subpixels -= additionalPixels;

  3. Actual Scroll Application

    element.scrollTop += (integerPart + additionalPixels);

Performance Considerations

  1. Frame Rate Management

    • Dynamically adjusts to display refresh rate
    • Maintains minimum and maximum FPS limits
    • Smooths out frame time variations

  2. Memory Management

    • Uses WeakMap to allow garbage collection
    • Cleans up scroll state when elements are removed
    • Prevents circular references

  3. CPU Usage

    • Only runs animation frames when necessary
    • Batches scroll calculations
    • Optimizes DOM access

Configuration Options

{
    smoothness: 0.5,        // Scroll smoothness (lower = smoother)
    acceleration: 0.5,      // Scroll acceleration factor
    minDelta: 0.1,         // Minimum scroll delta to process
    maxRefreshRate: 240,    // Maximum FPS limit
    minRefreshRate: 30,     // Minimum FPS limit
    defaultRefreshRate: 60, // Default FPS when undetectable
    debug: false           // Enable debug logging
}

Browser Compatibility

  • Modern Browsers: Full support

    • Chrome 61+
    • Firefox 55+
    • Safari 12.1+
    • Edge 79+

  • Partial Support:

    • IE11 (with polyfills)
    • Older mobile browsers

Known Limitations

  1. Cannot override native smooth scroll in some browsers
  2. May conflict with some page-specific scroll implementations
  3. Performance may vary on low-end devices
  4. Some browsers may limit background tab performance

Best Practices

  1. Installation

    // Install via userscript manager (e.g., Tampermonkey)
// Enable script in browser extension

  2. Configuration

    // Adjust settings for specific needs
smoothScroll.config.smoothness = 0.3; // Smoother
smoothScroll.config.acceleration = 0.7; // Faster

  3. Debugging

    // Enable debug mode
smoothScroll.config.debug = true;
// Check console for detailed logs

Integration Tips

  1. Custom Scroll Containers

    // Add data-smooth-scroll attribute
<div data-smooth-scroll="true">
 <!-- Scrollable content -->
</div>

  2. Scroll Prevention

    // Add no-smooth-scroll class
<div class="no-smooth-scroll">
 <!-- Content with normal scrolling -->
</div>

Troubleshooting

  1. Smooth Scroll Not Working

    • Check browser compatibility
    • Verify script installation
    • Check for conflicts with other scripts

  2. Performance Issues

    • Reduce maxRefreshRate
    • Increase minDelta
    • Disable debug mode

  3. Scrolling Conflicts

    • Check for native smooth scroll
    • Look for competing scroll listeners
    • Verify CSS overflow properties