ドキュメント/API

センサー

入力をドラッグに変換するもの。組み込みのポインターセンサーとキーボードセンサー、そして独自のセンサーを書くための API。

このページを編集

このページは AI によって翻訳されており、不正確な箇所が含まれている可能性があります。 英語の原文を読む

import { defineSensor, useSensor, pointerSensor, keyboardSensor } from '@vue-dnd-kit/core';
Sensor

Pointer Events によるマウス、タッチ、ペン。デフォルトで sensors に含まれます。

Sensor

Space/Enter、矢印キー、Escape(プロバイダーの keyboard オプションで割り当てを変更できます)。デフォルトで sensors に含まれます。keyboard: false でも、Escape でポインターとカスタムのドラッグをキャンセルします。

(sensor: Sensor) => Sensor

センサーを定義します(Sensor を参照):型の補助をするだけで、引数をそのまま返します。

(sensor: Sensor) => void

上にあるプロバイダーで、プロバイダーの sensors と並んでセンサーを動かします。呼び出したコンポーネント(またはエフェクトスコープ)が存在する間、有効です。アンマウントされると、そのドラッグはキャンセルされます。

センサーが伝えるのは「このアイテムをここからドラッグする」ということと、その後どこへ動いたか、ドロップしたかキャンセルされたかだけです。それ以外(何をドラッグできるか、アクティベーション、ドラッグは一度に 1 つ)はプロバイダーがチェックします。センサーとプログラムによるドラッグを参照してください。

下では、小さな独自のセンサー(useSensor で動かします)が、プロバイダー自身のセンサーと並んで、ミニマップからボードの駒をドラッグします。

Live

デモを読み込み中…

<script setup lang="ts">
import { DnDProvider } from '@vue-dnd-kit/core';
import SensorDesk from './SensorDesk.vue';
</script>

<template>
  <DnDProvider>
    <SensorDesk />
  </DnDProvider>
</template>

Sensor

ドラッグを始める入力:ポインター、キーボード、または独自のもの(ゲームパッド、画面上のジョイスティック、音声、スクリプトによるドラッグ)。setup はプロバイダーごとに 1 回、ブラウザーでのみ、プロバイダーとともに終わるエフェクトスコープの中で実行されます(センサーが sensors から外れたとき、または useSensor を呼んだコンポーネントがアンマウントされたときにも終わります)。リスナーは useEventListener で登録するか、クリーンアップ関数を返してください。そのときまだ実行中のドラッグはキャンセルされます。

センサーをラップするには、独自のコンテキストでその setup を実行します。Object.create(context, { activate: { value: … } }) はライブなゲッター(status、drag、props)を保ちます:スプレッド構文ではそれらが固定されてしまいます。

string

デバッグ用。

(context: SensorContext) => void | (() => void)

入力の監視を始めます。プロバイダーごとに 1 回です:ドラッグしたいときに context.activate() を呼びます。クリーンアップ関数を返すことができ、センサーの停止時に実行されます。

センサーが、実行されているプロバイダーから受け取るもの。

Readonly<DnDProviderProps>

プロバイダーの props(たとえば activation、keyboard)。変わる可能性があるため、必要なときに読み取ってください。

DnDStatus

プロバイダーのドラッグの状態。どのセンサーがドラッグを実行していても同じです。

SensorDrag | null

プロバイダーのドラッグ(保留中またはドラッグ中)。どのセンサーが始めたかは問いません。ない場合は null。センサーは互いのドラッグを操作できます:キーボードセンサーはすべてのキーボードドラッグを動かし、ドロップします。たとえば「移動」ボタンが持ち上げたもの(@vue-dnd-kit/actions)です。

(activation: SensorActivation) => SensorDrag | null

アイテムのドラッグを要求します。プロバイダーは、自分がアイドルであること(ドラッグは一度に 1 つ、ドロップの着地中はなし)、ターゲットが自分の管理する無効でないドラッグ可能な要素であること、入力が着地した場所(target を参照)、ドラッグ可能な要素の canDrag をチェックし、それからアクティベーション制約を待ってドラッグを開始します。ドラッグ(保留中、または待つものがなければすでにドラッグ中)を返し、ドラッグを始められない場合は null を返します。

() => void

プロバイダーのドラッグ、または保留中のアクティベーションをキャンセルします。どのセンサーが実行していても同じです(Escape、非表示のタブ)。

アクティベーション

入力がドラッグしようとしたときにセンサーが要求する内容(SensorContext.activate())。

Element | Key

入力が着地した場所:ドラッグ可能な要素の中の要素、またはドラッグ可能な要素の id。要素はこのプロバイダーに属している必要があります。'pointer' のドラッグでは、ハンドルがあればハンドル上にあり、インタラクティブな子要素(ボタン、入力欄)の上にないこと。'keyboard' のドラッグでは、ドラッグ可能な要素のフォーカス対象(ハンドル、なければドラッグ可能な要素自体)であり、編集可能なフィールドではないこと。id ではこれらのチェックがスキップされ、入力がどこにあってもそのアイテムからドラッグが始まります。

SensorType

ドラッグがどう動くか。'pointer'(デフォルト):move() に渡された座標を追い、そこでターゲットをヒットテストし、コンテナーは端で自動スクロールし、ページは掴んだカーソルを表示します。'keyboard':矢印キーと同じように step() と place() でアイテム単位に動き、ターゲットは自動スクロールではなくスクロールして表示され、終了時にフォーカスがアイテムに戻ります。どちらかは Active.sensor で分かります。

Coordinates

ドラッグが始まる位置(ビューポート座標)。デフォルト:ドラッグ可能な要素の中心。

PointerEvent | KeyboardEvent

入力イベント。ドラッグ可能な要素の canDrag に渡されます:イベントがない場合(ゲームパッド、プログラムによるドラッグ)は、canDrag に問い合わせません。pointerType が 'touch' の場合、そのドラッグはタッチドラッグ(haptics)になります。

PointerKind | ActivationConstraint

ドラッグが始まる前に何を待つか(それまで useDnD().status は 'activating' で、進捗を持ちます)。ポインターの種類を指定すると、ドラッグ可能な要素の activation オプションのその種類の設定を読み、次にプロバイダーのもの、次にデフォルト(マウスは 4px、ハンドル上では即座。ペンは 4px。タッチは 5px の許容範囲で 200ms の長押し)を使います。制約はそのまま使われます。デフォルト:なし。ドラッグはすぐに始まります。

(drag: SensorDrag) => void

アクティベーションの後、ドラッグが始まった:たとえばポインターをキャプチャします。

(drag: SensorDrag) => void

ドラッグが終わった:アクティベーションが中断された、またはドロップされた、キャンセルされた(誰によるものでも)。

(drag: SensorDrag) => void

センサーが要求したドロップは起きず、ドラッグが続きます(onBeforeDrop が 'continue' を返した):move、drop、cancel が再び有効になります。ポインターセンサーは、次に離すまでアイテムをポインターに追従させます。

ポインターの種類ごと。デフォルト:マウスは { distance: 4 }(ハンドル上では即座)、ペンは { distance: 4 }、タッチは { delay: 200, tolerance: 5 }。

type ActivationOptions = Partial< Record<PointerKind, ActivationConstraint> >

押下がドラッグになる前に満たすべき条件:distance だけ移動するか、delay の間押し続けるか、どちらか早いほう。何も設定しなければ、ドラッグはすぐに始まります。

number

ドラッグが始まる前にポインターが移動しなければならないピクセル数。

number

ドラッグが始まる前にポインターを押し続けなければならないミリ秒数。

number

delay と組み合わせて:アクティベーションを中断する移動量(px)。これによりページはスクロールできます。

ドラッグ

センサーによる 1 回のドラッグ。activate() から終了まで。もう適用されなくなった呼び出しはすべて無視されます:開始前や終了後の移動、2 回目の drop()。

Key

ドラッグ中のアイテムの id。

SensorType

ドラッグの動き方。activate() で指定されたとおりです(SensorActivation.type)。

SensorDragState

ドラッグの段階:アクティベーション待ち、ドラッグ中、または終了。

boolean

ドラッグが始まった(その後終わっていても)。ポインターセンサーは、ドラッグに続くクリックを握りつぶします。

(point: Coordinates) => void

入力が動いた。保留中はアクティベーション制約をチェックし(許容範囲を超えて動くと中断されます)、ドラッグ中はドラッグをそこへ動かします。ポインタードラッグは 1 フレームに 1 つの位置を取り、キーボードドラッグはそれより前のステップの後にすぐ動きます。

(direction: SensorDirection, options?: SensorStepOptions) => Promise<void>

キーボードドラッグ:矢印キー 1 回分のステップ。キーボードセンサーの矢印キーと同じです(リストの次のアイテム、'droppables' モードでは次の受け入れるターゲット、または keyboard.step ピクセル)。ステップはキューに入ります:それぞれ前のステップが描画されてから実行され、まだ解決していないステップがある間、キーリピート(event.repeat)はスキップされます。ポインタードラッグでは無視されます。

(position: SortablePosition) => Promise<boolean>

キーボードでの移動と同じように、アイテムを並べ替え可能なリストの位置に置き(ほかのリストは受け入れる場合にだけ受け取ります)、ドラッグを新しい場所へ動かします。そこで受け入れるリストがない場合は false で resolve します。キーボードドラッグでは step() と同じようにキューに入ります。

() => Promise<boolean>

ドロップします:アクティベーションが保留中なら、代わりにそれを中断します。ドラッグが終わって着地してから resolve します:ドロップが成立した場合は true、拒否された(ターゲット、onBeforeDrop)か、ドロップするものがなかった場合は false。

() => void

ドラッグをキャンセルする(元の位置に戻ります)か、保留中のアクティベーションを中断します。

  • 'pending':アクティベーション制約を待っています。
  • 'dragging':開始から、ドロップが決まるかドラッグがキャンセルされるまで。
  • 'ended':アクティベーションが中断された、またはドラッグがドロップされた、キャンセルされた。センサーによるものでも、それ以外(Escape、非表示のタブ、useDnD().cancel()、プロバイダーのアンマウント)によるものでも同じです。
type SensorDragState = 'pending' | 'dragging' | 'ended'

SensorDrag.step() のオプション。

KeyboardEvent

キーの押下。モニターの getKeyboardCoordinates に渡されます。デフォルト:その矢印キーの keydown。

boolean

自由なドラッグでの大きなステップ(Shift と同じ)。デフォルト:event.shiftKey。

キーボードのステップの矢印。

type SensorDirection = 'up' | 'down' | 'left' | 'right'

並べ替え可能なリスト内の位置。SensorDrag.place()(と @vue-dnd-kit/actions の moveItem)用です。リストのみ:ツリーは独自のキーでアイテムを配置します。

Key

リストの id(SortableListOptions.id)。デフォルト:アイテムが今あるリスト。

number

アイテムが最終的に置かれるインデックス。アイテム自身を除いて数えます(マルチドラッグのブロックは 1 つとして数えます)。リストの範囲内に収められます。デフォルト:末尾。