DataTransfer

DataTransferオブジェクトは、ドラッグ＆ドロップ操作の実行中、ドラッグされているデータを保持するために使われます。データトランスファーは1つ以上の項目を保持し、それぞれの項目は1つ以上のデータ型を保持します。ドラッグ＆ドロップについての詳しい情報はドラッグ＆ドロップを参照してください。

このオブジェクトはすべてのドラッグイベントのdataTransferプロパティからアクセスすることができます。単独で生成することはできません。

プロパティ一覧

メソッド一覧

プロパティ

dropEffect

ドロップによって起こる実際の結果の種類を示します。値は常にeffectAllowedに挙げられた取り得る値のうちの1つとなります。

dragenterおよびdragoverイベントでは、dropEffectをユーザが要求している操作に基づいて初期化されます。操作の種類がどのように判別されるかはプラットフォームごとに異なりますが、 通常、ユーザは望んでいる操作の種類を示すためにモディファイアキーを使うことができます。dragenterおよびdragoverイベントのリスナにおいて、ユーザが行っている操作が望まれたものでなかった場合には、dropEffectの値を変更するべきです。

dragstart、drag、およｂdragleaveイベントでは、dropEffectはnoneに初期化されます。dropEffectが取り得るどんな値もこの時点で設定できますが、この時点で設定した値は何にも使われません。

dropおよびdragendイベントでは、dropEffectは望まれている動作に初期化されます。この時の値は、最後のdragenterまたはdragoverイベントで設定された値となります。

取り得る値:

• copy: ドラッグされた項目の複製が新しい場所に作られることを表します。
• move: 項目が新しい場所に移動されることを表します。
• link: 項目へのリンクが新しい場所に作られることを表します。
• none: 項目をその場所にドロップできないことを表します。

これら以外の値を設定した場合は、何も起こらず、以前の値が保たれます。

effectAllowed

そのドラッグ操作において許可されている操作の種類を示します。dragstartイベントの中ではこのプロパティにドラッグ元の項目に対して望まれている操作の種類を設定でき、dragenterおよびdragoverイベントの中ではそのドロップ先に対して望まれている操作の種類を設定できます。値はその他のイベントでは使われません。

取り得る値:

• copy: ドラッグ元の項目の複製を新しい場所に作成できる事を表します。
• move: 項目を新しい場所に移動できることを表します。
• link: ドラッグ元の項目へのリンクを新しい場所に作成できる事を表します。
• copyLink: 複製またはリンクの作成の両方が許可されている事を表します。
• copyMove: 複製または移動の両方が許可されている事を表します。
• linkMove: リンクの作成または移動の両方が許可されている事を表します。
• all: すべての操作が許可されている事を表します。
• none: その場所にはドロップできない事を表します。
• uninitialized: 値が設定されていない事を表し、allに等しく扱われます。

これら以外の値を設定した場合は、何も起こらず、以前の値が保たれます。

files

データトランスファーが保持していて利用可能なすべてのローカルファイルのリストを保持します。ドラッグ操作がファイルのドラッグによるものではない場合、このプロパティは空のリストになります。このプロパティに対して無効なインデックスを指定してアクセスした場合はnullが返されます。

例

以下は、ブラウザウィンドウにドラッグされたファイルのリストを出力する例です。

ファイル「 filednd.html 」が見つかりません。

types

最初の項目が保持しているデータの形式を、データが追加された時と同じ順番で保持したリスト（文字列の配列）を返します。データが何も追加されていない時は、空のリストを返します。

ドラッグ中のカーソルの状態を返します。これは当初、タブをドラッグしている間のカーソルを変更するために導入されました。

取り得る値

auto

システムの規定の挙動を使用します。

default

Geckoの規定の挙動として、ドラッグ操作の間、矢印だけのカーソルを使用します。

mozItemCount

ドラッグされている項目の個数を返します。

mozSourceNode

ドラッグ操作を開始するためにボタンを押下した位置のNodeを返します。外部アプリケーションからのドラッグの場合や、ドラッグを開始したノードが呼び出し元からアクセスできない物であった場合は、値はnullとなります。

mozUserCancelled

このプロパティはdragendイベントに対してのみ適用され、ユーザがEscapeキーを押下してドラッグ操作を取り消した場合は値がtrueとなります。不正な場所でドロップした場合など、その他の理由でドラッグ操作に失敗した場合には、値はfalseとなります。このプロパティは現時点ではLinuxでは実装されていません。

メソッド

addElement()

ドラッグ元の要素を指定します。通常、ドラッグ元の要素を手動で追加する必要はありませんが、追加した場合、dragイベントとdragendイベントがそれらの要素においても発行されます。このメソッドを実行しない場合でも、ドラッグされた要素自身は初期状態でドラッグ元の要素となります。

 void addElement(
   in Element element
 );

パラメータ

element

ドラッグ元として追加する要素。

clearData()

指定された型のデータを削除します。型の指定は省略可能です。型として空の文字列を指定した場合、もしくは型を指定しなかった場合、すべての型のデータが削除されます。指定された型のデータが存在しない場合、またはデータトランスファーが何もデータを持っていない場合、このメソッドは何もしません。

 void clearData(
   [optional] in String type
 );

パラメータ

type

削除するデータの型。

getData()

指定された型のデータを取得します。指定された型のデータが存在しない場合、またはデータトランスファーが何もデータを保持していない場合、空文字を返します。

異なるドメインにおいて追加されたデータを取得しようとした場合、またはアクセス権を持たない呼び出し元からデータを取得しようとした場合、セキュリティエラーが起こります。このデータは、dropイベントが発生した時の1度だけ利用できます。

 void getData(
   in String type
 );

パラメータ

type

取得するデータの型。

setData()

指定された型のデータを設定します。その型のデータが存在しない場合、データはリストの最後に追加されるため、データ型のリストの最後の項目は、最後に追加された新しいデータ型となります。その型のデータがすでに存在している場合、データ型のリストにおける元と同じ位置で、古いデータが新しいデータと置き換わります。つまり、データ型のリストの順番は、同じ型のデータを置き換える事によっては変化しません。

 void setData(
   in String type,
   in String data
 );

パラメータ

type

追加するデータの型。

data

追加するデータ。

setDragImage()

ドラッグ中に表示されるフィードバックイメージについて、独自の物を使用したい場合に、それをセットします。ほとんどの場合、ドラッグ元のノードから生成された既定のフィードバックイメージが設定されるので、ドラッグフィードバックイメージを手動で指定する必要はありません。

ノードがHTMLのimg要素、canvas要素、またはXULのimage要素である場合、その画像そのものが使われます。それ以外の場合、目に見えるノードがフィードバックイメージに指定されるべきで、ドラッグフィードバックイメージはそのノードから生成されます。フィードバックイメージとしてnullを指定した場合、すでに設定されたフィードバックイメージがすべて消去され、代わりに既定のフィードバックイメージが使われます。

画像をマウスカーソルの下のどこに表示するかは、座標のオフセット値で示します。例えば画像の中央にマウスカーソルがくるようにするには、画像の幅と高さの半分の値を指定します。

 void setDragImage(
   in Element image,
   in long x,
   in long y
 );

パラメータ

image

ドラッグフィードバックイメージとして使用する要素。

x

画像の水平方向のオフセット。

y

画像の垂直方向のオフセット。

mozClearDataAt

指定されたインデックスの項目について、指定された形式に関連付けられたデータを削除します。インデックスは0〜(項目の数-1）の範囲です。

項目の最後の形式のデータが削除された場合、項目自体が削除され、mozItemCountの値が1減少します。

形式を指定しなかった場合、すべての形式のデータが削除されます。指定された形式のデータが登録されていない場合、このメソッドは何もしません。

 void mozClearDataAt(
   [optional] in String type,
   in unsigned long index
 );

パラメータ

type

削除するデータの型。

index

データを削除する項目のインデックス。

mozGetDataAt()

指定されたインデックスの項目の、指定された形式のデータを取得します。存在しない項目またはデータ形式を指定した場合はnullを返します。インデックスは0〜(項目の数-1）の範囲です。

 nsIVariant mozGetDataAt(
   [optional] in String type,
   in unsigned long index
 );

パラメータ

type

取得するデータの形式。

index

データを取得する項目のインデックス。

mozSetDataAt()

データトランスファーは複数の項目を保持する事ができ、それぞれの項目には0から始まるインデックスが付けられます。mozSetDataAt()は、すでに存在する項目を変更する場合にはmozItemCountより小さい値をインデックスとして指定し、新しい項目を追加する場合はmozItemCountに等しい値をインデックスとして指定します。また、mozItemCountは項目を追加する度に増加します。

データは、最も適切な形式を最初に追加し、フォールバック先となる形式を最後に追加する、という順で、任意の順番で追加する事ができます。指定された形式のデータがすでに存在している場合、元と同じ位置で古いデータが新しいデータに置き換わります。

データは文字列、プリミティブの真偽値、数値（文字列に変換されます）、またはnsISupports形式のオブジェクトを指定できます。

 void mozSetDataAt(
   [optional] in String type,
   in nsIVariant data,
   in unsigned long index
 );

パラメータ

type

追加するデータの形式。

data

追加するデータ。

index

データを追加する項目のインデックス。

mozTypesAt()

指定されたインデックスの項目が保持しているデータの形式のリスト（文字列の配列）を返します。0〜(項目の数-1）の範囲外のインデックスを指定した場合は、空のリストを返します。

 nsIVariant mozTypesAt(
   in unsigned long index
 );

パラメータ

index

データの形式のリストを取得する項目のインデックス。

See also

Drag and Drop