HTML: The Living Standard

Edition for Web Developers — Last Updated 19 April 2024

1. 1. 6.11 Drag and drop
      1. 6.11.1 Introduction
      2. 6.11.2 The drag data store
      3. 6.11.3 The DataTransfer interface
         1. 6.11.3.1 The DataTransferItemList interface
         2. 6.11.3.2 The DataTransferItem interface
      4. 6.11.4 The DragEvent interface
      5. 6.11.5 Events summary
      6. 6.11.6 The draggable attribute

6.11 Drag and drop

このセクションは、イベントベースのドラッグアンドドロップのメカニズムを定義する。

この仕様は、ドラッグアンドドロップ操作が実際に何であるかを正確に定義しない。

ポインティングデバイスをもつ視覚メディア上に、ドラッグ操作は一連のmousemoveイベントが続くmousedownイベントのデフォルトアクションであるかもしれず、ドロップは解放されているマウスによって引き起こされるかもしれない。

ポインティングデバイス以外の入力モダリティを使用する場合、ユーザーはおそらくドラッグアンドドロップ操作を実行するために明示的に意思表示する必要があり、それらがドラッグを望み、ドロップを望む場所を、それぞれ主張する。

6.11.1 Introduction

要素をドラッグ可能にするためには、要素にdraggable属性を与え、ドラッグされているデータを格納するdragstartドラッグに対してイベントリスナーを設定する。

イベントハンドラーは典型的に、それがドラッグされているテキスト選択でないことをチェックする必要があり、次にDataTransferオブジェクトにデータを格納し、許可される効果（コピー、移動、リンク、またはいくつかの組み合わせ）を設定する必要がある。

たとえば：

<p>What fruits do you like?</p>
<ol ondragstart="dragStartHandler(event)">
 <li draggable="true" data-value="fruit-apple">Apples</li>
 <li draggable="true" data-value="fruit-orange">Oranges</li>
 <li draggable="true" data-value="fruit-pear">Pears</li>
</ol>
<script>
  var internalDNDType = 'text/x-example'; // set this to something specific to your site
  function dragStartHandler(event) {
    if (event.target instanceof HTMLLIElement) {
      // use the element's data-value="" attribute as the value to be moving:
      event.dataTransfer.setData(internalDNDType, event.target.dataset.value);
      event.dataTransfer.effectAllowed = 'move'; // only allow moves
    } else {
      event.preventDefault(); // don't allow selection to be dragged
    }
  }
</script>

ドロップを受け入れるために、次のイベントをリッスンする必要がある：

1. dragenterイベントハンドラーは、イベントをキャンセルすることによって、ドロップターゲットが潜在的にドロップを受け入れる可能性があるかどうかを報告する。
2. dragoverイベントハンドラーは、イベントに関連付けられたDataTransferのdropEffect属性を設定することによって、ユーザーに表示されるフィードバックを指定する。このイベントはまたキャンセルする必要がある。
3. dropイベントハンドラーは、ドロップを受け入れるまたは拒否する最終選択を持つ。ドロップが受け入れられる場合、イベントハンドラーはターゲットに対してドロップ操作を実行しなければならない。このイベントはキャンセルする必要があるため、dropEffect属性の値をソースによって使用できるようにする。そうでなければ、ドロップ操作は拒否される。

たとえば：

<p>Drop your favorite fruits below:</p>
<ol ondragenter="dragEnterHandler(event)" ondragover="dragOverHandler(event)"
    ondrop="dropHandler(event)">
</ol>
<script>
  var internalDNDType = 'text/x-example'; // set this to something specific to your site
  function dragEnterHandler(event) {
    var items = event.dataTransfer.items;
    for (var i = 0; i < items.length; ++i) {
      var item = items[i];
      if (item.kind == 'string' && item.type == internalDNDType) {
        event.preventDefault();
        return;
      }
    }
  }
  function dragOverHandler(event) {
    event.dataTransfer.dropEffect = 'move';
    event.preventDefault();
  }
  function dropHandler(event) {
    var li = document.createElement('li');
    var data = event.dataTransfer.getData(internalDNDType);
    if (data == 'fruit-apple') {
      li.textContent = 'Apples';
    } else if (data == 'fruit-orange') {
      li.textContent = 'Oranges';
    } else if (data == 'fruit-pear') {
      li.textContent = 'Pears';
    } else {
      li.textContent = 'Unknown Fruit';
    }
    event.target.appendChild(li);
  }
</script>

ディスプレイからオリジナルの要素（ドラッグされたもの）を削除するために、dragendイベントを使用できる。

ここで私たちの例のために、それはそのイベントを処理するために元のマークアップを更新することを意味する：

<p>What fruits do you like?</p>
<ol ondragstart="dragStartHandler(event)" ondragend="dragEndHandler(event)">
 ...as before...
</ol>
<script>
  function dragStartHandler(event) {
    // ...as before...
  }
  function dragEndHandler(event) {
    if (event.dataTransfer.dropEffect == 'move') {
      // remove the dragged element
      event.target.parentNode.removeChild(event.target);
    }
  }
</script>

6.11.2 The drag data store

ドラッグデータストアとして知られる、ドラッグアンドドロップ操作を支えるデータは次の情報で構成される：

• ドラッグされたデータを表すアイテムのリストであるドラッグデータストアアイテムリストは、次の情報で構成される：

  ドラッグデータアイテムの種類

  データの種類：

  テキスト

  テキスト。

  File

  ファイル名をもつバイナリーデータ。

  ドラッグデータ項目型文字列

  一般にMIMEタイプで指定される、データ型やフォーマットを与えるユニコード文字列。MIMEタイプでない一部の値は、レガシー理由により特別扱いされる。APIはMIMEタイプの使用を強制しない。他の値も同様に使用できる。しかし、すべての場合において値は、APIによってすべてASCII小文字に変換される。

  項目型文字列ごとに1つのアイテム型文字列の制限が存在する。

  実際のデータ

  ファイル名（それ自体Unicode文字列）をもつ一部の場合において、ドラッグデータアイテムの種類ごとのように、Unicodeまたはバイナリー文字列。

  ドラッグデータストア項目リストは、項目がリストに追加された順序で並べられ、最近では最後に追加された。

• ドラッグ中のUIフィードバックを生成するために使用される、以下の情報：

  • ドラッグデータストアのデフォルトフィードバックとして知られる、ユーザーエージェント定義のデフォルトフィードバック情報。
  • 任意で、ドラッグデータストアビットマップおよびドラッグデータストアホットスポット座標として知られる、そのイメージ内にあるビットマップ画像とポイント座標。

• 次のいずれかであるドラッグデータストアモード：

  読み書きモード

  dragstartイベントに対して。新しいデータはドラッグデータストアに追加できる。

  読み取り専用モード

  dropイベントに対して。ドラッグされたデータを表す項目のリストは、データも含めて、読み取り可能である。新たなデータは追加できない。

  保護モード

  他のすべてのイベントに対して。ドラッグされたデータを表す項目のドラッグデータストアリストでフォーマットおよび種類は列挙されるが、データ自体が使用できず、新たなデータは追加できない。

• 文字列である、ドラッグデータストアの許可された効果の状態。

ドラッグデータストアが作成された場合、それはそのドラッグデータストアアイテムリストが空であるように初期化されなければならず、それはドラッグデータストアのデフォルトフィードバックを持たず、ドラッグデータストアのビットマップおよびドラッグデータストアのホットスポット座標を持たず、そのドラッグデータストアモードは保護モードであり、そのドラッグデータストアの許可された効果の状態は文字列"uninitialized"である。

6.11.3 The DataTransfer interface

DataTransferオブジェクトは、ドラッグアンドドロップ操作を支えるドラッグデータストアを公開するために使用される。

dataTransfer = new DataTransfer()

空のドラッグデータストアをもつ新しいDataTransferオブジェクトを作成する。

dataTransfer.dropEffect [ = value ]

現在選択されている操作の種類を返す。操作の種類がeffectAllowed属性によって許可されるものの1つでない場合、操作は失敗する。

選択した操作を変更す設定が可能である。

可能な値は、"none"、"copy"、"link"、および"move"である。

dataTransfer.effectAllowed [ = value ]

許可される操作の種類を返す。

許可される操作を変更するために、（dragstartイベント中に）設定可能である。

可能な値は、"none"、"copy"、"copyLink"、"copyMove"、"link"、"linkMove"、"move"、"all"、および"uninitialized"である。

dataTransfer.items

ドラッグデータとともに、DataTransferItemListオブジェクトを返す。

dataTransfer.setDragImage(element, x, y)

以前に指定されたフィードバックを置換し、ドラッグフィードバックを更新するために指定された要素を使用する。

dataTransfer.types

dragstartイベントで設定されたフォーマットを列挙する凍結された配列を返す。さらに、任意のファイルがドラッグされている場合、型の1つは文字列"Files"となる。

data = dataTransfer.getData(format)

指定されたデータを返す。そのようなデータが存在しない場合、空の文字列を返す。

dataTransfer.setData(format, data)

指定されたデータを追加する。

dataTransfer.clearData([ format ])

指定したフォーマットのデータを削除する。引数が省略された場合、すべてのデータを削除する。

dataTransfer.files

もしあれば、ドラッグされているファイルのFileListを返す。

ドラッグアンドドロップイベントの一部として作成されるDataTransferオブジェクトは、そのイベントが発生している間のみ有効である。

6.11.3.1 The DataTransferItemList interface

各DataTransferオブジェクトはDataTransferItemListオブジェクトに関連付けられる。

items.length

ドラッグデータストア内のアイテムの数を返す。

items[index]

ドラッグデータストア内のindex番目のエントリーを表すDataTransferItemオブジェクトを返す。

items.remove(index)

ドラッグデータストア内のindex番目のエントリーを削除する。

items.clear()

ドラッグデータストア内のすべてのエントリーを削除する。

items.add(data)

items.add(data, type)

ドラッグデータストアに指定されたデータに対する新しいエントリーを追加する。データがプレーンテキストである場合、type文字列も提供される必要がある。

6.11.3.2 The DataTransferItem interface

各DataTransferItemオブジェクトはDataTransferオブジェクトに関連付けられる。

item.kind

ドラッグデータ項目の種類、"string"、"file"のいずれかを返す。

item.type

ドラッグデータ項目型文字列を返す。

item.getAsString(callback)

ドラッグデータ項目の種類がtext.である場合、引数として文字列データをもつコールバックを呼び出す。

file = item.getAsFile()

ドラッグデータアイテムの種類がFileである場合、Fileオブジェクトを返す。

6.11.4 The DragEvent interface

ドラッグアンドドロップ処理モデルは、複数のイベントを含む。これらはすべてDragEventインターフェイスを使用する。

event.dataTransfer

イベントのDataTransferオブジェクトを返す。

他のイベントインターフェイスとの整合性を保つため、DragEventインターフェイスはコンストラクターを持つけれども、特に有用ではない。DataTransferオブジェクトは、ドラッグアンドドロップの間にブラウザーによって調整される処理およびセキュリティモデルを持つので、特に、スクリプトから有用なDataTransferオブジェクトを作成する方法はない。

6.11.5 Events summary

次のイベントは、ドラッグアンドドロップモデルに関与する。

これらのイベントバブルのすべては、構成され、effectAllowed属性は常に、dragstartイベント後に持っていた値を持ち、dragstartイベントで"uninitialized"をデフォルトとする。

6.11.6 The draggable attribute

すべてのHTML要素はdraggableコンテンツ属性設定を持ってもよい。The draggable attribute is an enumerated attribute with the following keywords and states:

この属性の欠損値のデフォルトと不正値のデフォルトは両方ともauto状態である。The auto state uses the default behavior of the user agent.

draggable属性を持つ要素はまた、非視覚的な相互作用の目的のために要素を名付けるtitle属性を持つべきである。

element.draggable [ = value ]

要素がドラッグ可能である場合にtrueを返す。そうでなければfalseを返す。

デフォルトを上書きしdraggableコンテンツの属性を設定するための、設定が可能である。