--- title: "プロバイダー" description: "DnDProvider は配下のすべてのドラッグを管理します。ターゲットを見つけ、ドラッグを開始し、スクロールし、起きたことをすべて useDnD と useDnDMonitor に伝えます。" canonical_url: "https://zizigy.github.io/vue-dnd-kit/ja/docs/guides/provider" --- > Index of every page on this site: [llms.txt](https://zizigy.github.io/vue-dnd-kit/llms.txt) ## アプリにプロバイダーを 1 つ ```vue [App.vue] ``` `DnDProvider` を `App.vue` やレイアウトなど上位の階層に 1 つ置けば、あとは気にする必要はありません。すべてのコンポーザブル（`makeSortableList`、`makeDraggable`、`useDnD`…）は、自分が実行されるコンポーネントより上にある最も近いプロバイダーを探します。 コンポーザブルは、プロバイダーの**内側に描画される**コンポーネントで実行する必要があります。自身のテンプレートに `` を含むコンポーネントで呼び出すと、`No found above this component` がスローされます。Vue の `inject` は祖先しか参照できないためです。 ## プロバイダーが管理するもの
パーツ プロバイダーの役割
入力 ポインター・タッチ・キーボードの入力をドラッグに変換します（ sensors 、 activation ）。ドラッグは一度に 1 つだけです。
ターゲットの検出 ドラッグの下にあるドロップターゲットをヒットテストし（ collision ）、それらに通知します。
オーバーレイ ポインターに追従するボックスを body にテレポートして描画し、ドロップ時に着地させます。
選択 選択中の id の集合を 1 つ持ち、配下のすべてのリストとドラッグ可能な要素で共有します。
自動スクロール ドラッグが端に近づくと、コンテナーやウィンドウをスクロールします。
ライブリージョン 持ち上げ、移動、ドロップ、キャンセルをスクリーンリーダーに読み上げます。
それ以外は何も描画しません。マークアップはそのままです。 ## オプションの概要 どのオプションにもそのまま使えるデフォルトがあるので、プロバイダーには通常何も渡しません。プロバイダーは props を必要になった時点で読み取ります。下のデモでは `collision`、`activation`、`autoScroll` をその場で切り替えています。
Prop デフォルト 設定する内容
collision pointerFirst ドラッグの下のターゲットをどう選ぶか。 後述 。
activation マウス 4 px、タッチ 200 ms 押下がいつドラッグになるか。ポインターの種類ごと。 後述 。
autoScroll オン 端でのスクロール： { threshold, maxSpeed, acceleration } または false 。 後述 。
haptics タッチで持ち上げたときの短い振動 タッチドラッグの振動、または false 。 後述 。
copyModifier 'Alt' ドラッグ中に押していると、移動がコピーになるキー。
modifiers [] すべてのドラッグに適用する移動のルール： 制約 を参照。
animation / dropAnimation オン 並べ替え中にアイテムがスライドする動き / オーバーレイの着地： アニメーション を参照。
animateChanges オフ リストとツリーのデフォルト：ドラッグ以外によるデータの変化をアニメーションします。
keyboard Space / Enter、Escape キーボードのキーとステップ。 false でキーボードドラッグをオフにします。 アクセシビリティ を参照。
sensors ポインター + キーボード 入力をドラッグに変換するもの： センサー を参照。
overlayTo 'body' オーバーレイのテレポート先。
overlayFit 'slot' オーバーレイのサイズ：着地する枠のサイズか、元の要素のサイズか。 オーバーレイ を参照。
overlayTransition クロスフェード ドラッグ中にオーバーレイがあるコンポーネントから別のコンポーネントへ変わる仕方： false 、または の props。 オーバーレイを変えるターゲット を参照。
overlayClass — オーバーレイのコンテンツ（ [data-dnd-overlay-content] ）に付けるクラス。全体としてアニメーションさせる要素です：ドラッグで持ち上げるときに浮かせ、着地するときに落ち着かせます。 オーバーレイ：持ち上げ、傾け、落ち着かせる を参照。
overlayPreviews 5 マルチドラッグ：持ち上げた時点でクローンを作る、ドラッグ中のアイテムの数、または 'all' 。 デフォルトのオーバーレイ を参照。
announcements 組み込み スクリーンリーダー向けのテキスト、または false 。
screenReaderInstructions 組み込み すべてのドラッグ可能な要素が aria-describedby で参照するテキスト。
defaultStyles true ドラッグの状態用に詳細度ゼロの CSS を挿入します： スタイリング を参照。
すべての型を含む完全な一覧は [DnDProvider API](https://zizigy.github.io/docs/api/dnd-provider) にあります。プロバイダーは `drag-start`、`drag-move`、`drag-over`、`drag-end`、`drag-cancel`、`drag-resume`、`drag-settle` も発行します。`useDnDMonitor` が受け取るのと同じイベントです。 ## ドラッグを読み取る：`useDnD()` `useDnD()` はドラッグをリアクティブな状態として返します。プロバイダー配下のどのコンポーネントでも使えます。 ```ts import { useDnD } from '@vue-dnd-kit/core'; const { status, active, over, pointer, activation, isAutoScrolling, selection, cancel } = useDnD(); ```
フィールド 内容
status 'idle' 、 'activating' （押下がアクティベーションを待っている）、 'dragging' 、 'dropping' （ドラッグは実行されていないが、オーバーレイがまだ着地中、または非同期の onBeforeDrop が判断中）、 'selecting' （範囲選択中）。
active ドラッグされているもの： id 、 ids （ドラッグ中のすべての id。掴んだものが先頭）、 items 、 data 、 type 、 element 、 rect 、 sensor 。アイドル時は null 。
over ドラッグの下にあるターゲット： id 、 data 、 element 、 rect 、 accepted 。何もない上では null 。
pointer ビューポート座標でのポインター位置。モディファイア適用後の値です。
activation.progress 押下がアクティベーションを待っている間、 0 から 1 まで進みます。リングを描くのに使えます。
isAutoScrolling 自動スクロールが何かを動かしています。
selection プロバイダーの選択： ids 、 has 、 add 、 delete 、 toggle 、 set 、 clear 。 マルチドラッグ を参照。
cancel() 実行中のドラッグ（アイテムは元の位置に戻ります）、チャージ中の押下、または範囲選択をキャンセルします。
```vue [DropHint.vue] ``` ドロップが確定した時点で、オーバーレイがまだ着地中でも（`status` は `'dropping'`）、`active`、`over`、`pointer` は `null` になります。これらから派生した UI が、古いドラッグを新しいデータと並べて表示することはありません。非同期の `onBeforeDrop` を待っている間は、状態は離した時点のまま保たれます。 次のドラッグは着地を待ちません：すぐに始まり、直前のオーバーレイがその周りで着地している間、`status` は `'dragging'` です。着地中のオーバーレイを押すと、飛んでいる途中で捕まえられます：ドラッグはオーバーレイのいる位置から続きます。ドラッグのオーバーレイが落ち着いたことは `onDragSettle` が知らせます。 ## すべてのドラッグを監視する：`useDnDMonitor()` ```ts import { useDnDMonitor } from '@vue-dnd-kit/core'; useDnDMonitor({ onDragStart: ({ active }) => {}, onDragMove: ({ pointer, delta }) => {}, onDragOver: ({ over }) => {}, // the target changed onBeforeDrop: (e) => 'accept', // or 'reject', 'continue', some ids; may be async onDragEnd: ({ active, over, dropped, accepted, position }) => {}, onDragCancel: ({ active }) => {}, onDragResume: ({ active }) => {}, // onBeforeDrop answered 'continue' onDragSettle: ({ active, over }) => {}, // its overlay has landed }); ``` モニターは、どこで始まったかに関係なく、プロバイダー配下のすべてのドラッグを受け取ります。上のパネルはリストをインポートせずに、そのリストのドラッグを記録しています。モニターは、呼び出したコンポーネントがアンマウントされると停止します。
イベント タイミング
onDragStart ドラッグが始まったとき。
onDragMove ドラッグが動いたとき。
onDragOver ドラッグの下のターゲットが変わったとき。
onBeforeDrop ドラッグが離されたとき。その答えがドロップを決めます： ドロップの判断 を参照。
onDragEnd ドロップが成立したとき。並べ替え可能なリストはすでに自身の onDrop を実行し、新しい順序を書き込んでいます。どのターゲットの上でもなく終わった場合、 dropped は false です。
onDragCancel Escape、受け入れないターゲットへのドロップ、または onBeforeDrop が 'reject' を返したとき。
onDragResume onBeforeDrop が 'continue' を返したとき：何もドロップされず、ドラッグが続きます。
onDragSettle ドラッグのオーバーレイが着地したとき（または元の位置に戻ったとき、次のドラッグに捕まえられたとき）。 onDragEnd または onDragCancel が受け取ったイベントが渡されます。その間にほかのドラッグが始まっていることもあります。
どのイベントも `active`、`over`、`pointer`、`delta`（開始位置からのオフセット）、`position`（ドラッグ中のボックスが `over` の中のどこにあるか。[ドラッグ＆ドロップ](https://zizigy.github.io/docs/guides/drag-and-drop#leave-it-where-it-was-dropped)を参照）を持ち、並べ替え可能なリストのアイテムなら `source` も持ちます。完全な型は [イベント API](https://zizigy.github.io/docs/api/events) にあります。 「ドロップの後」の処理は `onDragEnd` で行います：保存、選択の解除、アナリティクスなど。リスト自身の `onDrop` は書き込みの**前**に実行されるので、まだ古い順序が見えます。 ## ターゲットの検出 関数を選び、ピンやカードをターゲットの上へドラッグしてみましょう。バッジはそのフレームで関数がターゲットをどう順位付けしたかを示し、緑のものがターゲットです。 ドラッグの各フレームで、プロバイダーは対象となるドロップターゲットを `collision` に渡し、`collision` はそれらの id を良い順に返します。ライブラリには 5 つの関数が付属しています。
関数 順位付けの対象 向いている用途
pointerFirst ポインターの下にあるもの。何もなければ、ドラッグ中のボックスが重なっているもの。 デフォルト：ポインターの下では正確で、隙間では寛容です。
pointerWithin ポインターの下にあるものだけ。最も内側のものが先頭。 正確なターゲット：隙間ではどこにもドロップされません。
rectIntersection ドラッグ中のボックスが重なっているすべてのターゲット： priority が高い順、次にネストが深い順、次に重なりが大きい順。 小さなターゲットの上の大きなアイテムで、ポインターがアイテムの端にある場合。
closestCenter すべてのターゲット。ボックスの中心からターゲットの中心までの距離順。 遠くても必ずどれかが選ばれます：グリッドや同じサイズのアイテムのリスト。
closestCorners すべてのターゲット。4 つの角の間の距離順。 横に並んだ列（カンバン）や、高さが大きく異なるターゲット。
ポインターの下では、ヒットテストはユーザーに見えているものに従います。重なったターゲットのうちヒットするのは一番上のものだけで（重なった部分では `front` であり、`back` にはなりません）、入れ子のターゲットでは最も内側のものが先頭になります（`subfolder`、次に `folder`）。 ### 独自の関数 ```ts [magnet.ts] import type { CollisionDetection, Coordinates, Rect } from '@vue-dnd-kit/core'; /** How far the point is from the rect: 0 inside it. */ const gap = (rect: Rect, point: Coordinates) => Math.hypot( Math.max(rect.left - point.x, 0, point.x - rect.right), Math.max(rect.top - point.y, 0, point.y - rect.bottom), ); /** What is under the pointer; in a gap, the nearest target within 40px. */ export const magnet: CollisionDetection = ({ hits, pointer, candidates }) => { if (hits.length) return hits; return candidates .filter((candidate) => gap(candidate.rect, pointer) <= 40) .sort((a, b) => gap(a.rect, pointer) - gap(b.rect, pointer)) .map((candidate) => candidate.id); }; ```
引数 内容
pointer ポインター。モディファイア適用後の値です。
overlayRect 表示されている状態のドラッグ中のボックス。オーバーレイがなければ null 。
candidates 対象となるすべてのターゲット： id 、 rect （スクロールコンテナーで切り取られた、見えている部分）、 priority 、 depth （最上位で 0 、ネストが深いほど大きい）。
hits ヒットテストで得られた、ポインターの下にあるターゲット。良い順。
「ターゲットなし」にするには空の配列を返します。無効なターゲット、ドラッグ中のアイテムの内側にあるターゲット、スクロールコンテナーに隠れているターゲットは、関数に渡されません。ドラッグを受け入れないターゲットも候補には残ります。その上では `over.accepted` が `false` になり、ドロップは拒否されます（並べ替え可能なアイテムの内側にあるターゲットは代わりに道を譲り、リストがその上で並べ替えられます）。デモでは選んだ関数をラップして順位を記録しています：`(args) => (ranked.value = detect(args))`。 プロバイダーは、関数が求める切り替えを抑制します。ドラッグが離れたばかりのターゲットは、ポインターが 10 px 動くまで再び選ばれないため、境界でちらつきません。同じ親の中に入れ子になったターゲットの間（カードの列の隙間）では、直前のターゲットが維持されます。 ## 押下がドラッグになるとき 押してもすぐにはドラッグになりません。`activation` は、ポインターの種類（`mouse`、`touch`、`pen`）ごとに何を待つかを設定します：px 単位の `distance`、ms 単位の `delay`（`tolerance` を超えると押下は中止され、ページをスクロールできます）、またはその両方のうち先に満たされたほうです。 ```vue ```
ポインター デフォルト
mouse 、 pen { distance: 4 } ：クリックはクリックのままです。 handle 上でのマウスの押下はすぐに始まり、動かさなければクリックのままです。
touch { delay: 200, tolerance: 5 } ：長押しです。指の下のリストはスクロールできたままになります。
指定しなかった種類はデフォルトのままです。ドラッグ可能な要素自身の `activation` は[ドラッグエリア](https://zizigy.github.io/docs/guides/constraints)のものより優先され、ドラッグエリアのものはプロバイダーのものより優先されます。押下が待っている間、`useDnD().status` は `'activating'` で、`activation.progress` は `0` から `1` まで進みます。Escape または `useDnD().cancel()` で中止できます。制約をその場で試したり、進捗から長押しのリングを描いたりする方法は[センサー](https://zizigy.github.io/docs/guides/sensors#activation-constraints)にあります。 ## 自動スクロール チャンネルをリストの上端や下端に向かってドラッグしてみましょう。緑の帯が端のゾーンで、奥に入るほどリストが速くスクロールします。 `overflow: auto` または `scroll` の要素はすべて自動でスクロールし、ウィンドウも同様です。プロバイダーはまずポインターの下のコンテナーをスクロールし、次にその祖先、最後にウィンドウをスクロールします。
オプション デフォルト 設定する内容
threshold 0.2 端のゾーン。コンテナーのサイズに対する割合で、24〜96 px の範囲です。
acceleration 10 一番端での速度（px/フレーム）。ゾーンに入った深さの 2 乗で大きくなるので、出だしはゆっくりで正確です。
maxSpeed 25 最高速度。端を越えても（ポインターがコンテナーの外にあっても）、速度はこの値まで上がり続けます。
`:auto-scroll="false"` でオフになります。ある方向へのスクロールは、ポインターがその方向に動いてから始まるので、端の近くで持ち上げたアイテムが勝手にスクロールすることはありません。リスト、ツリー、[ドラッグエリア](https://zizigy.github.io/docs/guides/constraints)は、自身のコンテナー用に独自の `autoScroll` を受け取ります。 ```ts makeSortableList(list, { items: channels, autoScroll: { maxSpeed: 10 } }); ``` キーボードドラッグは自動スクロールしません。代わりにアイテムが見える位置までスクロールします。何かがスクロールしている間、`isAutoScrolling`（`useDnD()` またはドラッグエリアから取得）は `true` です。 ## 触覚フィードバックとコピーキー タッチドラッグは開始時に短く振動します。`:haptics="false"` でオフになり、オブジェクトを渡すと振動ごとに設定できます。 ```vue ```
キー 振動するタイミング デフォルト
start 長押しがドラッグになったとき。 true （10 ms）
enter ドラッグを受け入れるターゲットに入ったとき。 オフ
drop ドロップが成立したとき。 オフ
refuse ドロップが拒否され、アイテムが元の位置に戻るとき。 オフ
それぞれ `true`（デフォルトのパターン）、ms 単位の長さ、オン/オフのパターン、または `false` を受け取ります。振動するのはタッチで始まったドラッグだけで、iOS Safari はまったく振動できません。 `copyModifier` は、リスト間のドラッグ中に押していると移動がコピーになるキーです。デフォルトは `'Alt'` で、任意の `KeyboardEvent.key`、またはなしにする `null` を指定できます。アイテムの移動元のリストには `clone` 関数が必要です。[アイテムを共有するリスト](https://zizigy.github.io/docs/guides/shared-lists)を参照してください。 ## 複数のプロバイダー ほとんどのアプリに必要なのはちょうど 1 つです。ウィッシュリストを専用のプロバイダーの下に置いてから、本を向こうへ移動してみましょう。本は自分のプロバイダーから出られず、外側のモニターにはウィッシュリストのドラッグが届かなくなります。 ```vue ``` - プロバイダーは互いに独立しています。ドラッグが一方から他方へ渡ることはありません。 - プロバイダーのネストは可能です。**最も近い所有者が優先されます**：アイテムはその上にある最も近いプロバイダーに属し、外側のプロバイダーはそれを無視します。 - 各プロバイダーは独自の選択、オーバーレイ、ライブリージョン、モニターを持ちます。 2 つ目のプロバイダーが意味を持つのは、ページの一部がプロバイダー全体に関わる独自の設定（衝突判定、キーボードのキー、読み上げ）を必要とし、かつそのアイテムがそこから出ない場合だけです。ページの 2 つの部分の間でアイテムを移動できないときは、それらが 2 つのプロバイダーの下にないか確認してください。 ページの一部に対するルール（スナップするボード、タッチの押下が長いフィード、何もドラッグできないパネル）には、専用のプロバイダーは必要ありません。 ```ts makeDragArea(board, { modifiers: [snapToGrid(20)], activation: { touch: { delay: 400 } } }); ``` そのアイテムはアプリのプロバイダーに属したままで、どこへでも移動できます。[制約](https://zizigy.github.io/docs/guides/constraints)を参照してください。 別の場所にマウントされたアプリ（shadow root の中や、別の Vue アプリ）も、既存のプロバイダーに参加できます。マウントする前に `useDnDContext()` を `provideDnDContext(app, context)` に渡してください。ヒットテストとオーバーレイは shadow root をまたいで動作します。 ## SSR と Nuxt プロバイダーは SSR で安全に使えます。リストとアイテムは、ほかのマークアップと同じようにサーバーで描画されます。オーバーレイとライブリージョンはテレポートされ、クライアントでのみマウントされるため、ハイドレーションミスマッチを起こしません。デフォルトの id は Vue の `useId()` から生成され、サーバーとクライアントで一致します。 Nuxt では、モジュールが `DnDProvider` をグローバルに登録し、コンポーザブルを自動インポートします。[インストール](https://zizigy.github.io/docs/getting-started/installation#nuxt)を参照してください。 ## Sitemap See the full [sitemap](https://zizigy.github.io/vue-dnd-kit/sitemap.md) for all pages.