or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@better-scroll/wheel

@better-scroll/wheel is a plugin for BetterScroll that implements an iOS Picker-like wheel component for mobile and web applications. It provides smooth scrolling functionality with 3D rotation effects, configurable wheel items, and support for disabled states.

Package Information

Package Name: @better-scroll/wheel
Package Type: npm
Language: TypeScript
Installation: npm install @better-scroll/wheel

Core Imports

import BScroll from '@better-scroll/core';
import Wheel, { WheelOptions, WheelConfig } from '@better-scroll/wheel';

For CommonJS:

const BScroll = require('@better-scroll/core');
const { default: Wheel, WheelOptions, WheelConfig } = require('@better-scroll/wheel');

Basic Usage

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

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

// Initialize with wheel options
const bs = new BScroll('.wheel-wrapper', {
  wheel: {
    selectedIndex: 0,
    rotate: 25,
    adjustTime: 400,
    wheelWrapperClass: 'wheel-scroll',
    wheelItemClass: 'wheel-item',
    wheelDisabledItemClass: 'wheel-disabled-item'
  },
  probeType: 3
});

// Use wheel methods
bs.wheelTo(2, 300); // Scroll to index 2 with 300ms animation
const currentIndex = bs.getSelectedIndex(); // Get current selected index
bs.restorePosition(); // Restore position if needed

// Listen for index changes
bs.on('wheelIndexChanged', (index) => {
  console.log('Selected index:', index);
});

Architecture

The wheel plugin integrates with BetterScroll through:

Plugin Registration: Uses BScroll.use(Wheel) to register the plugin
Module Augmentation: Extends BetterScroll's TypeScript interfaces to add wheel options and methods
Hook System: Integrates deeply with BetterScroll's internal hooks for scrolling, animation, and boundary calculation
Proxy Methods: Exposes plugin methods (wheelTo, getSelectedIndex, restorePosition) directly on BScroll instances

Capabilities

Plugin Registration

export default class Wheel implements PluginAPI {
  static pluginName: string;
  constructor(scroll: BScroll);
}

// Named exports available
export type WheelOptions = Partial<WheelConfig> | true;
export interface WheelConfig;

// External types from dependencies
type BScroll = import('@better-scroll/core').default;

// Easing function type from @better-scroll/shared-utils  
type EaseItem = {
  style: string;
  fn: (t: number) => number;
};

Wheel Navigation

Navigate to specific wheel positions with optional animation timing and easing.

/**
 * Scroll wheel to specified index position
 * @param index - Target index (defaults to 0)
 * @param time - Animation duration in milliseconds (defaults to 0)
 * @param ease - Easing function for animation
 */
wheelTo(index?: number, time?: number, ease?: EaseItem): void;

Index Retrieval

Get the currently selected wheel index.

/**
 * Get the currently selected index
 * @returns Current selected index number
 */
getSelectedIndex(): number;

Position Restoration

Restore wheel to correct position when interrupted during scrolling.

/**
 * Restore wheel to correct position if scrolling is interrupted
 * Clears any pending animations and snaps to nearest valid position
 */
restorePosition(): void;

Event Handling

The wheel plugin emits events when the selected index changes.

// Event name constant
const WHEEL_INDEX_CHANGED_EVENT_NAME = 'wheelIndexChanged';

// Listen for index changes
bs.on('wheelIndexChanged', (index: number) => {
  // Handle index change
});

Configuration

Wheel Options

Configure wheel behavior through the wheel options object.

type WheelOptions = Partial<WheelConfig> | true;

interface WheelConfig {
  /** Initial selected index (default: 0) */
  selectedIndex: number;
  /** Rotation angle in degrees for 3D effect (default: 25) */
  rotate: number;
  /** Animation duration for position adjustments in ms (default: 400) */
  adjustTime: number;
  /** CSS class name for wheel wrapper element (default: 'wheel-scroll') */
  wheelWrapperClass: string;
  /** CSS class name for wheel item elements (default: 'wheel-item') */
  wheelItemClass: string;
  /** CSS class name for disabled wheel items (default: 'wheel-disabled-item') */
  wheelDisabledItemClass: string;
}

Configuration Examples:

// Enable with default options
const bs = new BScroll('.wrapper', {
  wheel: true
});

// Custom configuration
const bs = new BScroll('.wrapper', {
  wheel: {
    selectedIndex: 2,        // Start at index 2
    rotate: 45,              // Stronger 3D rotation
    adjustTime: 600,         // Slower animations
    wheelWrapperClass: 'my-wheel',
    wheelItemClass: 'my-item',
    wheelDisabledItemClass: 'disabled'
  }
});

TypeScript Integration

The plugin extends BetterScroll's TypeScript interfaces through module augmentation.

declare module '@better-scroll/core' {
  interface CustomOptions {
    wheel?: WheelOptions;
  }
  interface CustomAPI {
    wheel: PluginAPI;
  }
}

interface PluginAPI {
  wheelTo(index?: number, time?: number, ease?: EaseItem): void;
  getSelectedIndex(): number;
  restorePosition(): void;
}

HTML Structure

The plugin requires a specific HTML structure with appropriate CSS classes:

<div class="wheel-wrapper">
  <div class="wheel-scroll">
    <div class="wheel-item">Option 1</div>
    <div class="wheel-item">Option 2</div>
    <div class="wheel-item wheel-disabled-item">Disabled Option</div>
    <div class="wheel-item">Option 4</div>
  </div>
</div>

Error Handling

The plugin handles several edge cases automatically:

All Items Disabled: When all wheel items have the disabled class, getSelectedIndex() returns -1
Invalid Index: wheelTo() automatically finds the nearest valid (non-disabled) item
Interrupted Scrolling: restorePosition() handles cases where scrolling is interrupted
Missing Elements: Plugin gracefully handles missing DOM elements during initialization