Перетаскивание в HTML

Adobe AIR 1.0 и более новых версий

Поведение по умолчанию при перетаскивании
События перетаскивания в HTML
Типы MIME при перетаскивании в HTML
Эффекты перетаскивания в HTML

Для перетаскивания данных в HTML-приложение и из него (или в HTML-файл, отображаемый в HTMLLoader, и из него), могут использоваться события drag HTML. API-интерфейс перетаскивания в HTML позволяет осуществлять перетаскивание в элементы модели DOM и обратно в HTML-содержимом.

Примечание. Также могут использоваться API-интерфейсы классов AIR NativeDragEvent и NativeDragManager. Для этого нужно прослушивать события на объекте HTMLLoader, в котором содержится HTML-файл. Тем не менее API-интерфейс HTML больше подходит для работы с HTML-моделью DOM и позволяет контролировать поведение по умолчанию.

Поведение по умолчанию при перетаскивании

В среде HTML задано поведение по умолчанию для жестов перетаскивания текста, изображений и URL-адресов. С помощью поведения по умолчанию всегда можно перетащить эти типы данных из одного элемента в другой. Однако текст можно перетаскивать только между редактируемыми областями страницы. При перетаскивании текста из одной редактируемой области в другую по умолчанию выполняется перемещение. При перетаскивании текста в редактируемую область страницы из нередактируемой или из другого приложения по умолчанию выполняется копирование.

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

По умолчанию пользователь может выделить и перетащить любой текст, изображение или ссылку. Для управления поведением при выделении HTML-элемента можно использовать свойство CSS WebKit -webkit-user-select. Например, если значение свойства -webkit-user-select равно none, то содержимое элемента нельзя выбрать и перетащить. Также для указания того, можно ли перетащить элемент целиком, может использоваться свойство CSS -webkit-user-drag. Однако разные компоненты элемента будут обрабатываться по-разному. Пользователь по-прежнему сможет перетащить отдельный фрагмент текста. Дополнительную информацию см. в разделе CSS в AIR.

События перетаскивания в HTML

Ниже перечислены события, отправляемые элементом-инициатором, начинающим перетаскивание:

Событие	Описание
dragstart	Отправляется, когда пользователь начинает перетаскивание. Обработчик этого события при необходимости может предотвратить перетаскивание, вызвав метод preventDefault() объекта события. Для управления возможностью копирования, создания ссылки или перемещения перетаскиваемого объекта необходимо задать свойство effectAllowed. Выделенный текст, изображения и ссылки по умолчанию помещаются в буфер обмена, но для жеста перетаскивания можно задать разные данные с помощью свойства dataTransfer объекта события.
drag	Непрерывно отправляется при выполнении перетаскивания.
dragend	Отправляется, когда пользователь отпускает кнопку мыши для завершения перетаскивания.

Целевой элемент перетаскивания отправляет следующие события:

Событие	Описание
dragover	Отправляется непрерывно, пока перетаскивание осуществляется в границах элемента. Обработчик этого события должен задавать свойство dataTransfer.dropEffect для указания действия, которое необходимо выполнить по окончании перетаскивания: копирование, создание ссылки или перемещение.
dragenter	Отправляется, когда указатель мыши, перетаскивающий данные, входит в границы элемента. Если изменить какие-либо из свойств объекта dataTransfer в обработчике события dragenter, эти изменения будут отменены следующим же событием dragover. С другой стороны, между событиями dragenter и первым событием dragover, которое может заставить курсор мигать, если заданы разные свойства, существует небольшая задержка. Часто для обоих событий может использоваться один и тот же обработчик.
dragleave	Отправляется, когда указатель мыши, перетаскивающий данные, покидает границы элемента.
drop	Отправляется, когда пользователь отпускает данные над элементом. Доступ к перетаскиваемым данным возможен только в рамках обработчика этого события.

Объект события, отправляемый в ответ на эти события, похож на событие mouse. Свойства события mouse, такие как (clientX, clientY) и (screenX, screenY), могут использоваться для определения положения мыши.

Самое важное свойство объекта события drag — это dataTransfer: в нем содержатся перетаскиваемые данные. Сам объект dataTransfer включает ряд свойств и методов:

Свойство или метод	Описание
effectAllowed	Эффект, поддерживаемый целевым элементом перетаскивания. Как правило, это значение задается обработчиком события dragstart. См. раздел Эффекты перетаскивания в HTML.
dropEffect	Эффект, выбранный пользователем или целевым элементом. Если задать свойство `dropEffect` в обработчике событий `dragover` или `dragenter`, то AIR обновляет вид курсора мыши, указывая, что произойдет после отпускания кнопки мыши. Если свойство `dropEffect` не соответствует ни одному из поддерживаемых эффектов, то завершить перетаскивание данных невозможно и курсор мыши приобретает вид unavailable. Если в ответ на последнее событие `dragover` или `dragenter` не задано свойство `dropEffect`, то пользователь может выбрать один из поддерживаемых эффектов с помощью стандартных системных клавиш-модификаторов. Конечный эффект записывается в свойстве `dropEffect` объекта, отправляемого в ответ на `dragend`. Если пользователь отменяет перетаскивание, отпустив кнопку мыши вне границ целевого элемента, свойство `dropEffect` принимает значение `none`.
types	Массив, содержащий строковые значения типов MIME для каждого формата данных в объекте `dataTransfer`.
getData(mimeType)	Получает данные в формате, заданном параметром `mimeType`. Метод `getData()` может быть вызван только в ответ на событие `drop`.
setData(mimeType)	Добавляет данные в `dataTransfer` в формате, заданном параметром mimeType. Могут быть добавлены данные в разных форматах. Для этого для каждого типа MIME вызывается метод `setData()`. Любые данные, помещенные в объект `dataTransfer` в результате поведения перетаскивания по умолчанию, стираются. Метод `setData()` может быть вызван только в ответ на событие `dragstart`.
clearData(mimeType)	Стирает все данные в формате, заданном параметром `mimeType`.
setDragImage(image, offsetX, offsetY)	Задает заказное изображение для перетаскивания. Метод `setDragImage()` может быть вызван только в ответ на событие dragstart, и только когда весь элемент HTML перетаскивается путем задания значения `element` для его стиля CSS `-webkit-user-drag`. Параметр `image` может быть элементом сценария JavaScript или объектом Image.

Типы MIME при перетаскивании в HTML

С объектом dataTransfer события перетаскивания в HTML может использоваться ряд типов MIME:

Формат данных	Тип MIME
Текст	"text/plain"
HTML	"text/html"
URL-адрес	"text/uri-list"
Растровое изображение	"image/x-vnd.adobe.air.bitmap"
Список файлов	"application/x-vnd.adobe.air.file-list"

Также можно использовать и другие строки MIME, включая строки, определенные приложением. Однако другие приложения могут не распознать или не суметь использовать эти данные. Следите, чтобы данные, добавляемые к объекту dataTransfer, были нужного формата.

Важная информация. Доступ к отпущенным файлам имеет только код, выполняемый в изолированной программной среде. Попытка чтения или задания любого свойства объекта File вне изолированной программной среды приложения приводит к ошибке безопасности. Дополнительную информацию см. в разделе Обработка перемещения файлов в изолированной программной среде HTML вне приложений.

Эффекты перетаскивания в HTML

Инициатор жеста перетаскивания может ограничивать эффекты путем задания свойства dataTransfer.effectAllowed в обработчике события dragstart. Ниже перечислены используемые строковые значения:

Строковое значение	Описание
"none"	Операция перетаскивания запрещена.
"copy"	Данные копируются в целевой элемент, оригинал остается на месте.
"link"	Данные совместно используются исходным и целевым элементами, для чего применяется ссылка на оригинал.
"move"	Данные копируются в целевое место и удаляются из исходного.
"copyLink"	Данные можно копировать или создавать ссылку на них.
"copyMove"	Данные можно открывать или перемещать.
"linkMove"	Данные можно перемещать или создавать на них ссылку.
"all"	Данные можно копировать, перемещать или создавать на них ссылку. Эффект All выставляется автоматически, если отменяется поведение по умолчанию.

Целевой элемент перетаскивания может задавать свойство dataTransfer.dropEffect, чтобы указать действие, выполняемое по завершении перетаскивания. Если одним из разрешенных действий является отпускание, то система отображает соответствующий курсор, означающий копирование, перемещение или создание ссылки. В противном случае отображается курсор unavailable. Если эффект отпускания не задан целевым элементом, пользователь может выбрать любое из разрешенных действий с помощью клавиш-модификаторов.

Значение dropEffect может быть задано в обработчиках событий dragover и dragenter:

function doDragStart(event) { 
    event.dataTransfer.setData("text/plain","Text to drag"); 
    event.dataTransfer.effectAllowed = "copyMove"; 
} 
 
function doDragOver(event) { 
    event.dataTransfer.dropEffect = "copy"; 
} 
 
function doDragEnter(event) { 
    event.dataTransfer.dropEffect = "copy"; 
}

Примечание. Хотя свойство dropEffect всегда должно задаваться в обработчике события dragenter, помните, что следующее событие dragover сбрасывает значения свойства до исходных (по умолчанию). В ответ на оба событие необходимо задать dropEffect.