tessl/npm-better-scroll--wheel
A BetterScroll plugin to imitate iOS Picker components with smooth scrolling functionality
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Pending
The risk profile of this skill
@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
Register the wheel plugin with BetterScroll to enable wheel functionality.
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
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
- Publish Source
- CLI
- Badge
