понедельник, 1 июня 2009 г.

JavaScript: Drag and Drop - библиотека

В данной статье я представлю свою небольшую JavaScript-библиотечку для работы с Drag&Drop (Скачать).

Введение

Для начала немного теории. Drag&Drop предполагает, что вы, как разработчик, даёте возможность пользователю перемещать те или иные графические объекты (будем по старинке называть их слоями) по странице, нажав на них левой кнопкой мыши и, не отжимая её, передвигая курсор мыши до пункта назначения.
В более сложном варианте нам необходимо вносить те или иные ограничения на этот процесс, по-этому API библиотеки должно позволять гибко настраивать перенос в соответствии с задачей. Сразу обратим внимание на три фазы перемещения:
  • Нажатие левой кнопки мыши на элементе
  • Перетаскивание элемента с помощью перемещения курсора при нажатой левой кнопке мыши
  • Отжатие левой кнопки мыши после перемещения
На уровне кода данная библиотека представляет собой один объект DnD с двумя методами.

Подключение библиотеки

Архив содержит библиотеку DragAndDrop в 2-х вариантах.
  • Оптимизированный код - в файлах "./lib/common.js" и "./build/dnd.js".
  • Комплексный оптимизированный код - в файле "./dnd.js"
Библиотека "common.js" необходима для ряда операций сравнения, по-этому её обязательно нужно подгружать до подгрузки библиотеки "dnd.js".

Эта библиотека довольно простая и может оказаться полезной вам и для других ваших сценариев - если вы будете её использовать ещё для чего-то (как это делаю я), то имеет смысл её загрузить один раз и больше не загружать - тогда удобно отделить её от других файлов библиотек и загружать отдельно - один раз, что бы потом грузить другие библиотеки, которые её используют (исходный код данной библиотеки лежит там же, в директории "./lib"). Для тестирования (файлы в директории "./test/") выбран именно этот способ, для такой сборки в Ant предназначен target по-умолчанию "build".

Если же вы не собираетесь использовать библиотеку "commons.js" где-либо ещё, то имеет смысл для сокращения количества загружаемых файлов, объединить её с библиотекой dnd в один оптимизированный файл. Такой объединённый файл и лежит в корне архива (он собирается с помощью действия "build-complex" в Ant).

Что ещё есть в архиве

  • "./doc/" - документация
  • "./test/" - демонстрационные тесты
  • "build.xml" - сценарий сборки Ant

Первый пример

Если у Вас на странице есть некоторый объект, который Вам хотелось бы сделать передвигаемым по ней, то Вам достаточно зарегистрировать его в объекте DnD:
var /** @type {HTMLElement} */ layer = document.createElement('div');
layer.appendChild(document.createElement('img')).setAttribute('src', 'pic.gif');
document.body.appendChild(layer);
DnD.register(layer);
В результате выполнения этого кода картинка "pic.gif" появится на экране и станет возможным её передвижение по окну браузера.

Второй метод объекта DnD служит обратной задаче - отмены регистрации. Например, если после пердыдущего участка кода вставить следующий:
setTimeout('DnD.unregister(layer)', 6000);
, то передвижение слоя будет доступно только в течении 6 секунд - затем он зафиксируется и больше не будет доступен для перемещений.

В этом примере мы видим работу двух методов объекта DnD - это методы register и unregister. Как нетрудно догадаться из их названий, один регистрирует объект как DragAndDrop, второй - отменяет эту регистрацию, возвращая его в нормальное состояние (но не отменяя его перемещения, которое уже совершено, а так же текущего перемещения - если метод unregister был вызван в момент перемещения. Если быть более точным, метод unregister блокирует у слоя возможность начать его новое перемещение пользователем). Оба эти метода возвращают ссылки на объект DnD, так что их вызовы можно выстраивать в цепочки любой длинны:
DnD.register(layer1).register(layer2).unregister(layer3).register(layer4);//...
Перемещать можно только слои, у которых свойство 'position' установлено в значение 'absolute' или 'relative'. По-этому при регистрации слоя происходит проверка на то, какое значение выставлено у него в этом css-свойстве. Если оно не выставлено в одно из этих двух - библиотека сама выставляет для него значение 'absolute'.

Установка ограничений

Однако, читатель наверняка согласится с тем, что в реальных задачах редко нужны просто свободно перемещаемые по окну браузера мышкой элементы. Как правило, нужно как-либо ограничить возможности производить перемещения - например, оставить перемещения лишь по заданным траекториям или ограничить те места в браузере, где перемещения можно было бы завершить.

Для этого предусмотрен простой API, регламентирующий Drag&Drop-перемещения для элемента страницы. В основе его лежит событийная модель - для элемента, регистрируемого в объекте DnD, можно определить обработчиков трёх событий. Для каждого из событий в объекте DnD определено поведение по-умолчанию, но если обработчик данного события вернёт булево значение false, то это поведение не будет выполнено. Значение true можно и не возвращать - всё, что угодно, кроме значения false будет командой выполнить действие по-умолчанию (обратите внимание на то, что значение false должно быть иименно примитивным, объект new Boolean(false) будет интерпретирован как true, так же будет интерпретированы и значения null и undefined - только примитив false заблокирует поведение для объекта по-умолчанию).
Таблица №1: Обработчики событий Drag&Drop
СобытиеСигнатура обработчикаОписание параметровПоведение по-умолчанию
Нажатие пользователем левой кнопки мыши в момент нахождения курсора над слоем - инициализация перемещения элемента.function mouseDown(/*Object*/ offset)В качестве парамметра принимает объект offset, содержащий информацию о начале перетаскивания - поля 'x' и 'y' этого объекта содержат разницу между позицией курсора мыши и левым верхним краем элемента, а поле 'startPos' содержит объект с полями 'x' и 'y', содержащими координаты левого верхнего угла элемента.Перемещение стартует. Форма курсора мыши по всему документу выставляется в значение 'move'.
Изменение координат курсора мыши при нажатой левой кнопке мыши.mouseMove(/*number*/ x, /*number*/ y)/*number*/ x - координата по горизонтали, /*number*/ y - координата по вертикали левого верхнего края курсора мыши.Передвижение элемента, по вертикали и горизонтали соответствующее перемещению курсора.
Отпускание левой кнопки мыши после перетаскивания элемента.mouseUp(/*number*/ x, /*number*/ y)/*number*/ x - координата по горизонтали, /*number*/ y - координата по вертикали левого верхнего края курсора мыши.Фиксация слоя в текущей позиции в окне браузера и изменение формы курсора мыши на всём документе на значение 'auto'. В случае отмены данного действия производится возврат слоя к координатам, с которых началось его передвижение.

Можно переопределить любой из обработчиков, все вместе или любые их комбинации - каждый из них будет вызываться только в том случае, если будет присутствовать.

Подробности

Начинается перетаскивание для нас с того, что вызывается метод mouseDown и ему передаётся параметр offset - смещение. Дело в том, что координатой элемента у нас считается координата его верхнего левого угла, а мышка может быть нажата, находясь не только в левой верхней точке, но и в любой другой точке элемента, по-этому для того, что бы корректно перемещать объект в зависимости от будущих координат мыши, нам нужно знать, на сколько пикселов правее и ниже "взялся мышкой" за элемент пользователь, когда начал его перетаскивание, что бы потом корректировать координаты так, что бы курсор мышки при перетаскивании был именно над этой самой точкой, а не над левым верхним углом, как это было бы, если бы мы не учитывали смещения. Именно эту информацию и несёт объект offset. Так же в нём содержится информация о стартовом положении элемента в момент до начала перетаскивания, по-этому может быть удобно запомнить этот объект и использовать эту информацию в дальнейшем - при обработке других событий.

Все три метода могут возвращать значения типа boolean (обратите внимание - с маленькой буквы, т.е. речь идёт о примитиве, а не об обёртке Boolean). Любое другое значение, а так же отсутствие возвращаемого значения интерпретируется как возвращение значения true.

В общем случае возвращение true означает разрешение на проделывание действий по-умолчанию, false - отказ от этих действий. Действия по-умолчанию для событий приведены в таблице №1.

Пример: Перетаскивание только по горизонтали

Допустим, перед нами стоит задача создать интерфейс, управляющий какой-либо количественной величиной, скажем, уровнем громкости в динамике или задержкой по времени при автодозвоне. Тогда нам нужно создать некоторый бегунок, который бы перемещался только по горизонтали, по нужной нам шкале, а мы бы отслеживали это перемещение и, в соответствии с ним, меняли бы ту величину, за изменение которой был бы ответственнен наш компонент.

На уровне API это означает, что нам нужно заблокировать поведение по-умолчанию при возникновении события mouseMove и заменить его на перемещение по горизонтали, не трогая вертикальной координаты объекта.

Делается это примерно так:
(function() {
    var /** @type {number} */ offsetX;

    layer.mouseDown = function(offset) {
        offsetX = offset.x;
    }

    layer.mouseMove = function(x) {
        this.style.left = (x - offsetX) + 'px';
        return false;
    }

    layer.mouseUp = function() {
        offsetX = null;
    }
})();
Вставьте этот код перед регистрацией слоя в объекте DnD в первом примере (в начале статьи) - и он придаст слою нужную функциональность. Послоностью пример можно увидеть, посмотре исходные коды тестов (директория "./test/") - там этот пример соответствует примеру №3. Запустите файл "./test/test.html" и проверьте его работу в своём браузере.

Пример: перетаскивание в заданную область

Допустим, у нас есть интернет-магазин и мы хотим сделать возможность перемещения товаров в корзину. Тогда мы имеем задачу обеспечить перетаскивание элемента в ограниченную область экрана (корзину) и нас не устроит, если пользователь переместит слой, соответствуюдий товару, куда-либо ещё.

Значит, нам нужно перегрузить обработчик события окончания передвижения элемента с тем, что бы проверять, находится ли курсор над областью, в которую разрешено перемещение и, в случае, если нет - возвращать false с тем, что бы вернуть элемент назад, отменив результат перемещения.

Кроме того, было бы полезно в процессе перемещения сразу показывать пользователю, что в данный момент элемент находится не над приемлемой для помещения в неё зоной. Традиционно это делается путём присвоения курсору такого значения, которое выглядит как знак запрета. К сожалению, такое значение для CSS-свойства 'cursor' на сегодняшний момент не стандартизовано, однако, несмотря на это, поддерживается последними версиями всех достаточно популярных браузеров, за исключением, разве что, Opera`ы (будем надеяться, что это временно). Это значение - 'no-drop'.

Допустим, что область карзины представлена объектом SquareArea, которому в конструкторе передаются её координаты и размеры, и у неё есть один метод - isInside(/*number*/ x, /*number*/ y), который возвращает результат типа boolean, говорящий, соответственно, входит или не входит точка с переданными ему координатами в его область. Тогда наш код для этой ситуации может быть примерно таким:
(function() {

    var /** @type {Object} */ offset,
        /** @type{SquareArea} */ toArea = new SquareArea(450, 450, 100, 100);

    layer.mouseDown = function(_offset) {
        offset = _offset;
    }

    layer.mouseMove = function(x, y) {

        this.style.cursor =
        document.body.style.cursor = toArea.isInside(x, y) ? 'move' : 'no-drop';
    }

    layer.mouseUp = function(x, y) {

        offset = null;
        this.style.cursor = 'move';

        return toArea.isInside(x, y);
    }
})();
Наверное, нужно особо остановиться на том, почему в обработчике mouseMove значение курсора присваивается сразу же двум стилям элементов - и самого элемента и документа. Дело в том, что при перемещении, резко дёрнув мышь, можно на долю секунды поймать момент, когда элемент ещё не успел перерисоваться и подтянуться к курсору мыши - и тогда, если документу не присвоен тот же курсор, что и элементу, курсор изменит форму, а потом вернёт старую форму обратно. Это может смотреться довольно раздражающе - именно для того, что бы избежать этого эффекта, рекомендуется в процессе DragAndDrop-передвижения выставлять необходимую форму курсора не только над элементом, но и на всём документе.

Вставьте этот код перед регистрацией слоя в объекте DnD в первом примере (в начале статьи) - и он придаст слою нужную функциональность. Полоностью пример можно увидеть, посмотре исходные коды тестов (директория "./test/") - там этот пример соответствует примеру №4. Запустите файл "./test/test.html" и проверьте его работу в своём браузере.