Przeciąganie i upuszczanie w HTML

Adobe AIR 1.0 i starsze wersje

Aby przeciągnąć dane do i z aplikacji opartej na HTML (lub do i z treści HTML wyświetlanej w obiekcie HTMLLoader), można użyć zdarzeń przeciągania i upuszczania w treści HTML. Interfejs API przeciągania i upuszczania HTML umożliwia przeciąganie do i z elementów DOM w treści HTML.

Uwaga: Można użyć także interfejsów API NativeDragEvent i NativeDragManager środowiska AIR, wykrywając zdarzenia obiektu HTMLLoader zawierającego treść HTML. Jednak interfejs API HTML jest bardziej zintegrowany z modelem DOM HTML i umożliwia sterowanie domyślnym zachowaniem.

Domyślne zachowanie przeciągania i upuszczania

Środowisko HTML zapewnia domyślne zachowanie dla gestów przeciągania i upuszczania dotyczących tekstu, obrazów i adresów URL. Za pomocą domyślnego zachowania te typy danych można zawsze przeciągnąć poza element. Jednak do elementu można przeciągnąć tylko tekst i tylko do elementów edytowalnego obszaru strony. Przeciągając tekst między lub wewnątrz edytowalnych obszarów strony, zachowanie domyślne wykonuje operację przenoszenia. Jeśli tekst jest przeciągany do obszaru edytowalnego z obszaru nieedytowalnego lub spoza aplikacji, wówczas zachowanie domyślne wykonuje operację kopiowania.

Zachowanie domyślne można przesłonić, samodzielnie obsługując zdarzenia przeciągania i upuszczania. Aby anulować zachowanie domyślne, należy wywołać metody preventDefault() obiektów wywołanych dla zdarzeń przeciągania i upuszczania. Można wówczas wstawić dane do celu upuszczania i usunąć dane ze źródła przeciągania, jeśli jest to konieczne do wykonania wybranej operacji.

Domyślnie użytkownik może wybrać i przeciągnąć dowolny tekst oraz przeciągnąć obrazy i łącza. Właściwości CSS WebKit ( -webkit-user-select ) można używać do sterowania sposobem zaznaczania dowolnego elementu HTML. Na przykład, jeśli właściwość -webkit-user-select ustawiona zostanie na wartość none , wówczas treści elementu nie można zaznaczyć, dlatego też nie można jej przeciągnąć. Można użyć także właściwości CSS -webkit-user-drag , aby decydować, czy element można przeciągnąć jako całość. Jednak treść elementu jest traktowana oddzielnie. Użytkownik może nadal przeciągać wybrany fragment tekstu. Więcej informacji można znaleźć w rozdziale Dokument CSS w środowisku AIR .

Zdarzenia przeciągania i upuszczania w HTML

Zdarzenia wywoływane przez element inicjatora, z którego rozpoczynane jest przeciąganie:

Zdarzenie

Opis

dragstart

Wywoływane, gdy użytkownik rozpoczyna gest przeciągania. Moduł obsługi tego zdarzenia może zapobiec przeciąganiu (w razie konieczności), wywołując metodę preventDefault() obiektu zdarzenia. Aby decydować, czy przeciągane dane mogą być kopiowane, powiązane lub przenoszone, należy ustawić właściwość effectAllowed. Zaznaczony tekst, obrazy i łącza wstawiane są do schowka przez zachowanie domyślne, ale możliwe jest ustawienie innych danych dla gestu przeciągania za pomocą właściwości dataTransfer obiektu zdarzenia.

drag

Wywoływane w sposób ciągły podczas gestu przeciągania.

dragend

Wywoływane w chwili zwolnienia przycisku myszy przez użytkownika w celu zakończenia gestu przeciągania.

Zdarzenia wywoływane przez cel przeciągania:

Zdarzenie

Opis

dragover

Wywoływane w sposób ciągły w czasie przytrzymania gestu przeciągania w granicach elementu. Moduł obsługi dla tego zdarzenia powinien ustawić właściwość dataTransfer.dropEffect, aby wskazywała, czy wynikiem przeciągania w chwili zwolnienia przycisku myszy będzie operacja kopiowania, przenoszenia czy połączenia.

dragenter

Wywoływane, gdy gest przeciągania znajdzie się w granicach elementu.

Jeśli dowolne właściwości obiektu dataTransfer w module obsługi zdarzenia dragenter zostaną zmienione, zmiany te zostaną szybko przysłonięte przez kolejne zdarzenie dragover. Z drugiej strony istnieje niewielkie opóźnienie między zdarzeniem dragenter i pierwszym zdarzeniem dragover, które może spowodować migotanie kursora, jeśli ustawione zostały różne właściwości. W wielu przypadkach można użyć tego samego modułu obsługi zdarzenia dla obu zdarzeń.

dragleave

Wywoływane w momencie opuszczenia gestu przeciągania granic elementu.

drop

Wywoływane w momencie upuszczenia przez użytkownika danych na element. Dostęp do przeciąganych danych można uzyskać tylko w module obsługi dla tego zdarzenia.

Obiekt zdarzenia wywoływany w odpowiedzi na te zdarzenia podobny jest do zdarzenia myszy. Właściwości zdarzenia myszy np. clientX , clientY i screenX , screenY można używać do określania położenia myszy.

Najważniejszą właściwością obiektu zdarzenia drag jest dataTransfer , która zawiera przeciągane dane. Sam obiekt dataTransfer zawiera następujące właściwości i metody:

Właściwość lub metoda

Opis

effectAllowed

Efekt dozwolony przez źródło przeciągania. Wartość tę ustawia zazwyczaj moduł obsługi dla zdarzenia dragstart. Patrz Efekty przeciągania w HTML .

dropEffect

Efekt wybrany przez cel lub użytkownika. Jeśli właściwość dropEffect ustawiona zostanie w module obsługi zdarzenia dragover lub dragenter , wówczas środowisko AIR aktualizuje kursor myszy, aby wskazywany był efekt, który występuje w chwili zwolnienia przycisku myszy. Jeśli ustawienie właściwości dropEffect nie będzie zgodne z jednym z dozwolonych efektów, nie będzie możliwe żadne upuszczenie i wyświetlony zostanie niedostępny kursor. Jeśli właściwość dropEffect nie zostanie ustawiona w odpowiedzi na ostatnie zdarzenie dragover lub dragenter , wówczas użytkownik może wybierać z dozwolonych efektów za pomocą standardowych klawiszy modyfikatorów systemu operacyjnego.

Efekt końcowy zgłaszany jest przez właściwość dropEffect obiektu wywołanego przez zdarzenie dragend . Jeśli użytkownik zaniecha upuszczania, zwalniając przycisk myszy poza odpowiednim celem, wówczas właściwość dropEffect ustawiana jest na wartość none .

types

Tablica zawierająca ciągi znaków typu MIME dla każdego formatu danych obecnego w obiekcie dataTransfer .

getData(mimeType)

Pobiera dane w formacie określonym przez parametr mimeType .

Metoda getData() może być wywoływana tylko w odpowiedzi na zdarzenie drop .

setData(mimeType)

Dodaje dane do właściwości dataTransfer w formacie określonym przez parametr mimeType. Dane można dodać w wielu formatach przez wywołanie metody setData() dla każdego typu MIME. Wszystkie dane umieszczone przez domyślne zachowanie przeciągania w obiekcie dataTransfer zostaną usunięte.

Metoda setData() może być wywoływana tylko w odpowiedzi na zdarzenie dragstart .

clearData(mimeType)

Usuwa wszystkie dane w formacie określonym przez parametr mimeType .

setDragImage(image, offsetX, offsetY)

Ustawia niestandardowy obraz przeciągania. Metoda setDragImage() może być wywoływana tylko w odpowiedzi na zdarzenie dragstart i tylko wtedy, gdy przeciągany jest cały element HTML, co uzyskuje się, ustawiając jego styl CSS -webkit-user-drag na element . Parametr image może być elementem JavaScript lub obiektem Image.

Typy MIME dla przeciągania i upuszczania HTML

Typy MIME do użytku w obiekcie dataTransfer zdarzenia przeciągania i upuszczania HTML:

Format danych

Typ MIME

Tekst

"text/plain"

HTML

"text/html"

URL

"text/uri-list"

Bitmapa

"image/x-vnd.adobe.air.bitmap"

Lista plików

"application/x-vnd.adobe.air.file-list"

Można również użyć innych ciągów znaków MIME, łącznie z ciągami znaków zdefiniowanymi przez aplikację. Jednak inne aplikacje mogą nie być w stanie rozpoznać lub użyć przesyłanych danych. Obowiązkiem programisty jest dodawanie danych do obiektu dataTransfer w oczekiwanym formacie.

Ważne: Tylko kod działający w obszarze izolowanym aplikacji może uzyskać dostęp do upuszczanych plików. Próba odczytu lub ustawienia dowolnej właściwości obiektu File w nieaplikacyjnym obszarze izolowanym powoduje wygenerowanie błędu zabezpieczeń. Więcej informacji zawiera sekcja Obsługa upuszczania plików w nieaplikacyjnym obszarze izolowanym HTML .

Efekty przeciągania w HTML

Inicjator gestu przeciągania może ograniczyć dozwolone efekty przeciągania, ustawiając właściwość dataTransfer.effectAllowed w module obsługi dla zdarzenia dragstart . Można użyć następujących ciągów znaków:

Ciąg znaków

Opis

"none"

Żadna operacja przeciągania nie jest dozwolona.

"copy"

Dane zostaną skopiowane do celu, pozostawiając oryginalne dane na miejscu.

"link"

Dane będą współużytkowane z celem upuszczania za pomocą połączenia z oryginałem.

"move”

Dane zostaną skopiowane do celu i usunięte z oryginalnej lokalizacji.

"copyLink"

Dane mogą być kopiowane lub łączone.

"copyMove"

Dane mogą być kopiowane lub przenoszone.

"linkMove"

Dane mogą być łączone lub przenoszone.

"all"

Dane mogą być kopiowane, przenoszone lub łączone. All jest efektem domyślnym w przypadku zablokowania i zapobiega użyciu zachowania domyślnego.

Cel gestu przeciągania może ustawić właściwość dataTransfer.dropEffect , aby wskazywana była operacja podejmowana w momencie zakończenia upuszczania. Jeśli efektem upuszczania jest jedna z dozwolonych operacji, wówczas system wyświetla odpowiedni kursor kopiowania, przesuwania lub łączenia. W przeciwnym razie system wyświetla niedostępny kursor. Jeśli żaden efekt upuszczania nie został ustawiony przez cel, użytkownik może wybierać z dozwolonych efektów za pomocą klawiszy modyfikatorów.

Wartość właściwości dropEffect należy ustawić w modułach obsługi dla obu zdarzeń dragover i 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"; 
}
Uwaga: Mimo że zawsze należy ustawić właściwość dropEffect w module obsługi zdarzenia dragenter , programista powinien być świadomy tego, że kolejne zdarzenie dragover ponownie ustawia właściwość na jej wartość domyślną. Właściwość dropEffect należy ustawić w odpowiedzi na oba zdarzenia.