A cross-browser/event abstraction that handles mouse and touch drag sequences
Перейти к файлу
Yanislav Ivanov c17defab22
feat: add cancel drag method (#56)
2023-10-30 13:11:38 +02:00
.github/workflows chore: read secrets from Akeyeless 2023-05-18 18:01:52 +03:00
e2e fix: bump version (#38) 2020-04-29 13:29:10 +03:00
src feat: add cancel drag method (#56) 2023-10-30 13:11:38 +02:00
.eslintrc.js fix: change package scope to @progress 2022-06-06 15:19:02 +03:00
.gitignore feat: add support for Pointer Events 2017-11-24 13:47:18 +02:00
CODEOWNERS Rename CODEOWNERS.md to CODEOWNERS 2022-01-13 14:12:07 +02:00
CONTRIBUTING.md docs: add CONTRIBUTING.md 2017-05-29 11:12:02 +03:00
LICENSE.md fix: update license 2022-06-06 15:33:04 +03:00
NOTICE.txt docs: update notice && change year 2022 2022-01-14 10:09:04 +02:00
README.md fix: change package scope to @progress 2022-06-06 15:19:02 +03:00
gulpfile.js chore: upgrade package tasks (#25) 2019-02-01 18:19:32 +02:00
package.json chore: bump tasks 2022-06-06 15:19:02 +03:00
tsconfig.json chore: test type definitions 2019-01-31 10:03:43 +02:00

README.md

Commitizen friendly

Kendo UI Draggable

A repository for the cross-platform abstraction for drag sequences.

Overview

The Kendo UI Draggable component handles mouse drags and touch sequences on mobile devices.

A drag sequence means:

  • Mouse click, drag, release for desktop devices.
  • Touch press, drag, release for mobile devices.

Installation

The library is published as a scoped NPM package in the NPMJS Telerik account.

npm install --save '@progress/kendo-draggable';

Basic Usage

The draggable class constructor accepts an object with three optional event handler callbacks—press, drag, and release.

import Draggable from '@progress/kendo-draggable';

const draggable = new Draggable({
    press: function(e) {
        console.log("pressed", e.pageX, e.pageY);
    },
    drag: function(e) {
        console.log("drag", e.pageX, e.pageY);
    },
    release: function(e) {
        console.log("release", e.pageX, e.pageY);
    }
});

draggable.bindTo(document.getElementById("my-element"));

The Draggable may be re-bound to another element—the event handlers will be automatically unbound from the previous one.

draggable.bindTo(document.getElementById("another-element"));

The draggable object persists a reference to the currently bound element. That is why it should be destroyed when or if the corresponding element is removed from the document.

draggable.destroy();

Features

The Kendo UI Draggable supports:

  • Mouse events
  • Touch events
  • Pointer events
  • Handling of multiple touches. Rather, not getting confused by them.

Dragging on iOS/Android

Handling the drag sequence on mobile devices may require the disabling of the touch-based scrolling. The Draggable will not do that out of the box. The recommended way to handle this issue is by setting a touch-action CSS property. Depending on the type of drags that are handled, you may need touch-action: none, touch-action: pan-y, or touch-action: pan-x.

The touch-action setting does not work for iOS yet. While the iOS 9.3 version, which has been released recently, provides limited support, pan-x and pan-y do not work. To disable the touch-based scrolling in iOS, prevent the touchstart event:

    <div ontouchstart="return false">
        <div id="my-draggable-element"></div>
    </div>

Preventing Selection

The dragging of elements that contain text activates the browser text selection, which, in most cases, is not desirable. To avoid this behavior, use the user-select: none CSS property with its respective browser prefixes.

Mouse-Only mode

To ignore all touch and pointer events, set mouseOnly to true. This is useful when you want to keep the default touch-drag behavior, e.g. horizontal scroll.

import Draggable from '@progress/kendo-draggable';

const draggable = new Draggable({
    mouseOnly: true,
    press: function(e) {
        console.log("pressed", e.pageX, e.pageY);
    },
    drag: function(e) {
        console.log("drag", e.pageX, e.pageY);
    },
    release: function(e) {
        console.log("release", e.pageX, e.pageY);
    }
});

draggable.bindTo(document.getElementById("my-element"));

Browser Support

  • Google Chrome
  • Firefox
  • Safari (OS X)
  • Safari (iOS)
  • Chrome (Android)
  • IE/Edge