or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-better-scroll--mouse-wheel

A TypeScript plugin for BetterScroll that provides enhanced mouse wheel scrolling capabilities with configurable speed, direction, easing, and boundary damping on PC platforms.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@better-scroll/mouse-wheel@2.5.x

To install, run

npx @tessl/cli install tessl/npm-better-scroll--mouse-wheel@2.5.0

index.mddocs/

Mouse Wheel Plugin for BetterScroll

A TypeScript plugin for the BetterScroll library that provides enhanced mouse wheel scrolling capabilities on PC platforms. It handles various wheel events with configurable options including scroll speed, direction inversion, easing animations, and boundary damping.

Package Information

  • Package Name: @better-scroll/mouse-wheel
  • Package Type: npm
  • Language: TypeScript
  • Version: 2.5.1
  • Installation: npm install @better-scroll/mouse-wheel
  • Compatibility: Requires @better-scroll/core ^2.0.0

Core Imports

import BScroll from '@better-scroll/core';
import MouseWheel from '@better-scroll/mouse-wheel';

For CommonJS:

const BScroll = require('@better-scroll/core');
const MouseWheel = require('@better-scroll/mouse-wheel');

Required Dependencies:

  • @better-scroll/core - Core BScroll functionality
  • @better-scroll/shared-utils - Shared utilities and types (peer dependency)

Basic Usage

import BScroll from '@better-scroll/core';
import MouseWheel from '@better-scroll/mouse-wheel';

// Register the plugin
BScroll.use(MouseWheel);

// Create BScroll instance with mouse wheel support
const bs = new BScroll('.wrapper', {
  mouseWheel: {
    speed: 20,
    invert: false,
    easeTime: 300,
    discreteTime: 400,
    throttleTime: 0,
    dampingFactor: 0.1
  }
});

// Or enable with default options
const bsDefault = new BScroll('.wrapper', {
  mouseWheel: true
});

Architecture

The Mouse Wheel plugin integrates seamlessly with BetterScroll through:

  • Event Registration: Handles cross-browser wheel events (wheel, mousewheel, DOMMouseScroll)
  • Delta Processing: Normalizes wheel event deltas across different browsers and input devices
  • Throttling & Timing: Provides configurable throttling and end-detection for smooth scrolling
  • Damping Algorithm: Applies boundary damping when scrolling exceeds scroll limits
  • BScroll Integration: Triggers BScroll events and respects scroll constraints

Capabilities

Plugin Registration

Register the MouseWheel plugin with BScroll before creating instances.

import BScroll from '@better-scroll/core';
import MouseWheel from '@better-scroll/mouse-wheel';

BScroll.use(MouseWheel);

MouseWheel Class

Main plugin class that handles mouse wheel functionality.

import { ApplyOrder } from '@better-scroll/shared-utils';
import BScroll from '@better-scroll/core';

class MouseWheel {
  static pluginName: string; // Always 'mouseWheel'
  static applyOrder: ApplyOrder; // ApplyOrder.Pre
  mouseWheelOpt: MouseWheelConfig;
  
  constructor(scroll: BScroll);
  destroy(): void;
}

The MouseWheel class is automatically instantiated by BScroll when the mouseWheel option is provided. The plugin initializes by calling the private init() method which:

  1. Registers custom BScroll event types (alterOptions, mousewheelStart, mousewheelMove, mousewheelEnd)
  2. Processes and merges user options with defaults
  3. Sets up hook handlers for cleanup
  4. Registers cross-browser wheel event listeners (wheel, mousewheel, DOMMouseScroll)

Configuration Options

Configure mouse wheel behavior through the mouseWheel option.

type MouseWheelOptions = Partial<MouseWheelConfig> | true;

interface MouseWheelConfig {
  /** Scroll speed multiplier (default: 20) */
  speed: number;
  /** Whether to invert scroll direction (default: false) */
  invert: boolean;
  /** Animation easing time in milliseconds (default: 300, minimum: 100) */
  easeTime: number;
  /** Time to detect wheel end event in milliseconds (default: 400) */
  discreteTime: number;
  /** Throttle time for wheel events in milliseconds (default: 0) */
  throttleTime: number;
  /** Damping factor for boundary scrolling (default: 0.1) */
  dampingFactor: number;
}

Usage Examples:

// Use default configuration
const bs1 = new BScroll('.wrapper', {
  mouseWheel: true
});

// Custom configuration
const bs2 = new BScroll('.wrapper', {
  mouseWheel: {
    speed: 30,
    invert: true,
    easeTime: 500,
    dampingFactor: 0.2
  }
});

// Partial configuration (merges with defaults)
const bs3 = new BScroll('.wrapper', {
  mouseWheel: {
    speed: 50,
    throttleTime: 100
  }
});

// Note: easeTime values below 100ms will trigger a warning
// and be automatically adjusted to 100ms minimum

Event Handling

The plugin registers and manages mouse wheel events automatically.

interface CompatibleWheelEvent extends WheelEvent {
  pageX: number;
  pageY: number;
  readonly wheelDeltaX: number;
  readonly wheelDeltaY: number;
  readonly wheelDelta: number;
}

interface WheelDelta {
  x: number;
  y: number;
  directionX: Direction;
  directionY: Direction;
}

Supported Events:

  • wheel - Standard wheel event
  • mousewheel - Legacy mousewheel event
  • DOMMouseScroll - Firefox-specific event

BScroll Event Integration

The plugin triggers custom events on the BScroll instance.

// Event types registered with BScroll
type MouseWheelEventTypes = 
  | 'alterOptions'     // Triggered when plugin options are applied
  | 'mousewheelStart'  // Triggered at the start of wheel interaction  
  | 'mousewheelMove'   // Triggered during wheel scrolling
  | 'mousewheelEnd';   // Triggered when wheel interaction ends

Event Usage:

import BScroll from '@better-scroll/core';
import MouseWheel from '@better-scroll/mouse-wheel';

BScroll.use(MouseWheel);

const bs = new BScroll('.wrapper', {
  mouseWheel: {
    speed: 20,
    easeTime: 300
  }
});

// Listen for wheel interaction events
bs.on('mousewheelStart', () => {
  console.log('Mouse wheel interaction started');
});

bs.on('mousewheelMove', (position: { x: number; y: number }) => {
  console.log('Mouse wheel move:', position);
});

bs.on('mousewheelEnd', (delta: WheelDelta) => {
  console.log('Mouse wheel interaction ended:', delta);
});

bs.on('alterOptions', (options: MouseWheelConfig) => {
  console.log('Mouse wheel options applied:', options);
});

// Example: Disable mouse wheel during specific operations
function temporarilyDisableWheel() {
  bs.disable();
  setTimeout(() => {
    bs.enable();
  }, 2000);
}

Module Augmentation

The plugin extends BScroll's type definitions to include mouse wheel options.

declare module '@better-scroll/core' {
  interface CustomOptions {
    mouseWheel?: MouseWheelOptions;
  }
}

This allows TypeScript to recognize the mouseWheel option in BScroll constructor options.

Cross-Browser Compatibility

The plugin handles various wheel event properties for cross-browser compatibility:

  • deltaX/deltaY: Standard wheel event deltas
  • wheelDeltaX/wheelDeltaY: Legacy wheel deltas
  • wheelDelta: Single wheel delta value
  • detail: Firefox-specific delta property
  • deltaMode: Handles both pixel (0) and line (1) scroll modes

Cleanup and Destruction

Properly clean up event listeners and timers when no longer needed.

// Automatic cleanup when BScroll is destroyed
bs.destroy();

// Manual plugin cleanup (called automatically)
mouseWheelInstance.destroy();

The destroy() method:

  • Removes all wheel event listeners
  • Clears timeout timers
  • Unhooks from BScroll events

Types

import { Direction, ApplyOrder } from '@better-scroll/shared-utils';
import BScroll from '@better-scroll/core';

type MouseWheelOptions = Partial<MouseWheelConfig> | true;

interface MouseWheelConfig {
  /** Scroll speed multiplier (default: 20) */
  speed: number;
  /** Whether to invert scroll direction (default: false) */
  invert: boolean;
  /** Animation easing time in milliseconds (default: 300, minimum: 100) */
  easeTime: number;
  /** Time to detect wheel end event in milliseconds (default: 400) */
  discreteTime: number;
  /** Throttle time for wheel events in milliseconds (default: 0) */
  throttleTime: number;
  /** Damping factor for boundary scrolling (default: 0.1) */
  dampingFactor: number;
}

interface CompatibleWheelEvent extends WheelEvent {
  pageX: number;
  pageY: number;
  readonly wheelDeltaX: number;
  readonly wheelDeltaY: number;
  readonly wheelDelta: number;
}

interface WheelDelta {
  x: number;
  y: number;
  directionX: Direction;
  directionY: Direction;
}

class MouseWheel {
  /** Plugin identifier (always 'mouseWheel') */
  static pluginName: string;
  /** Plugin application order (ApplyOrder.Pre) */
  static applyOrder: ApplyOrder;
  /** Current mouse wheel configuration */
  mouseWheelOpt: MouseWheelConfig;
  
  /** Create new MouseWheel plugin instance */
  constructor(scroll: BScroll);
  /** Clean up event listeners and timers */
  destroy(): void;
}