ドキュメント/API

makeSortableTree

コンテナーを、深さ付きのフラットな形で描画される並べ替え可能なツリーにします。横方向へのドラッグやノードへのホバーでネストします。

このページを編集

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

function makeSortableTree<T>(  target: MaybeElementRef,  options: SortableTreeOptions<T>,): SortableTreeReturn<T>;

コンテナーを並べ替え可能なツリーにします。返される items(ドラフトの順序の表示中のノード。depth に応じてインデント)を、makeSortableItem を呼ぶ行コンポーネントで描画してください。ドロップ時、onDrop の後で、移動したノード(サブツリーごと)が options.items に書き込まれます。ただし event.preventDefault() で event.result を自分で扱う場合を除きます。

const root = useTemplateRef<HTMLElement>('root');
const { items } = makeSortableTree(root, { items: files, indentation: 20, collapsed });

各行は id: () => node.key を指定して makeSortableItem を呼び出します。ツリーを参照してください。

Live

デモを読み込み中…

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

<template>
  <DnDProvider>
    <FileTree />
  </DnDProvider>
</template>

オプション

makeSortableTree のオプション。マルチドラッグでは、選択中のノードを、それぞれサブツリーを伴った 1 つのブロックとして、同じ位置と深さへ(ドキュメント順で)移動します。選択中のノードの中にある選択中のノードは、そのサブツリーに乗って一緒に移動します。掴んだノードも同様です(VS Code と同じ):掴んだノードは、それが入っている選択中のノードの中に留まり、そのノードがサブツリーとともに移動します。オーバーレイは掴んだ行のままです。canNest と maxDepth はブロック全体に適用されます。

ほかのオプションは makeSortableList でのものと同じ意味を持ちます。値、ref、ゲッター(overlay、overOverlay、animation、dropAnimation、overDropAnimation:値または ref)を受け付け、ツリーが必要とするときに読み取られるため、変更は遅くとも次のドラッグから反映されます。例外:id と group はツリーの作成時に一度だけ読み取られます。items はモデルそのものです。関数(getKey、getChildren、setChildren、canNest、clone、createItem、コールバック)はそのまま渡されます。

SortableItems<T>

ルートノード。書き込み可能な ref:ドロップ時、ライブラリは変更されたノードに新しい子を設定し(setChildren)、新しいルート配列を書き込みます。読み取り専用のソース(ゲッター、readonly な ref、computed):event.preventDefault() を呼んで、event.result を自分で適用してください(SortableListOptions.items と同様)。

(node: T) => Key

デフォルト:node.id。makeSortableItem({ item })、コピー、作成されたノードのキーにも使われます。

(node: T) => T[]

ノードの子。デフォルト:node.children。

(node: T, children: T[]) => void

デフォルトの書き込みが、ノードに新しい子をどう設定するか。デフォルト:node.children = children。

(node: T, children: T[]) => T

children を持つ node のコピー。event.result 用です:あなたのノードをそのまま残す新しいツリーになります(デフォルトの書き込みは引き続き setChildren を通ります)。デフォルト:setChildren で子を設定した { ...node }(setChildren がない場合は { ...node, children })。クラスのインスタンスや、浅いコピー以上のものが必要なノードには、これを渡してください。

Key

デフォルト:useId()。サーバーとクライアントの描画間で安定しています。一度だけ読み取られます。

string値 · ref · ゲッター

人がツリーを呼ぶ名前:スクリーンリーダー向けのテキストは id の代わりにこれを読み上げます。

unknown値 · ref · ゲッター

ドロップターゲットとしてのツリーについて伝えたい任意のデータ:ドラッグが上にある間、イベントは over.data として運びます。

ActivationOptions値 · ref · ゲッター

このツリーの行を押下したときのドラッグの始まり方。プロバイダーの activation の代わりに使われます(行自身のものが優先)。

Component値 · ref

このツリーの行用のオーバーレイコンポーネント(行自身の overlay が優先)。ドラッグ中に切り替えた ref は、すぐにそれを入れ替えます。

Component値 · ref

このツリーが受け入れるドラッグが上にある間、オーバーレイに表示するもの(SortableListOptions.overOverlay を参照)。その to prop は、ドロップがどこにネストされるかを示します。

DropAnimation値 · ref

このツリーの行のドラッグが終わったときのオーバーレイの着地の仕方(SortableListOptions.dropAnimation を参照)。

DropAnimation値 · ref

このツリーにドロップされたときのオーバーレイの着地の仕方(SortableListOptions.overDropAnimation を参照)。

Modifier[]値 · ref · ゲッター

このツリーの行のドラッグに使うモディファイア。プロバイダーの modifiers の後に適用されます(行自身の modifiers が優先):たとえば [restrictToVerticalAxis]。ドラッグの開始時に読み取られます。軸を固定してもネストできます:その場合、深さは行の中央へのホバーで決まります。

'x' | 'y'値 · ref · ゲッター

モディファイアの後に、このツリーの行のドラッグを 1 つの軸に固定します(行自身の axis が優先)。'y' でも行はネストできます:その場合、深さは行の中央へのホバーで決まります。ドラッグの開始時に読み取られます。

string | SortableGroupOptions<T>

グループ名が同じリストとツリーはアイテムをやり取りします。デフォルト:独自のグループ。一度だけ読み取られます。

AcceptMode値 · ref · ゲッター

複数の型のアイテムのマルチドラッグ:すべて('all'、デフォルト)と一部('some')のどちらが受け入れられる(group.put)必要があるか。

number値 · ref · ゲッター

深さ 1 階層あたりの横方向のオフセット(ピクセル)。デフォルトは 24。

TreeNesting値 · ref · ゲッター

深さをどう選ぶか:横方向のオフセット、行の中央へのホバー、またはその両方(デフォルト)。

SortablePlaceholder値 · ref · ゲッター

'item'(デフォルト):ドラッグ中のノードが、予測された深さで行の間を移動します。'indicator':ツリーは動かず、indicator(ツリーと各行の makeSortableItem にある)がドロップ先をその depth と parentKey とともに示し、ラインはあなたが描きます。このとき、外へのドロップはキャンセルされます。

number値 · ref · ゲッター

許可される最大の深さ(ルートは 0)。ドラッグ中のノード自身の子孫も数えます。

(node: T, parent: T) => boolean

node を parent の下に置けるかどうか。マルチドラッグでは、ドラッグ中のすべてのノードについて問い合わせます。

ReadonlySet<Key>値 · ref · ゲッター

子が非表示になっているノードのキー。

(node: T) => T

コピーを作成します(group.pull: 'clone'、コピー用の修飾キー)。コピーには必須です。サブツリー全体を含むコピーを返してください:コピーしたフォルダーは子を保ちます。コピーとそのすべての子孫には、ツリーのすべてのノードと同じく、それぞれ独自のキー(getKey で読み取られる)が必要です。

(active: Active) => T

外部からの通常のドラッグ可能な要素を受け入れます:予測された位置と深さに挿入するノードを作成します(canNest と maxDepth が適用されます)。キーボードでは、ツリーの方向への矢印キーでドラッグ可能な要素を、その前に入る行と同じ高さに取り込み、その後は矢印キーでほかのノードと同じように動かせます。ページの外からのドラッグ(external)では、ドラッグ中とドロップ時の 2 回呼ばれます(リストの createItem を参照)。ファイルごとに子を持つフォルダーノードなら、複数のファイルを保持できます。

ExternalAccept値 · ref · ゲッター

ページの外からのドラッグを createItem とともに受け取ります:ファイル、リンク、テキスト(ExternalAccept を参照)。アプリの別のウィンドウからドラッグされてきた同じグループのノードは、ノードそのものとして入ってきます。値、ref、ゲッターで、ライブで読み取られます。

DropOutside値 · ref · ゲッター

すべてのターゲットの外へのドロップ:ノードをプレースホルダーのある場所に置く、キャンセルする、または取り除く。デフォルトは 'placeholder'(placeholder: 'indicator' では 'cancel')。ドロップ時に読み取られます。

LayoutAnimation値 · ref

このツリーの FLIP アニメーション。デフォルト:プロバイダーの animation。値または ref(関数はカスタムアニメーション)。

AutoAnimation値 · ref · ゲッター

SortableListOptions と同じく、表示されている行が対象です:追加、削除、移動されたノードと、ノードの展開・折りたたみ(collapsed)で表示・非表示になる行。

boolean値 · ref · ゲッター

ツリー自身のサイズは、リストと同じように行に追従します(animateSize)。デフォルトは true。

boolean | AutoScrollOptions値 · ref · ゲッター

このツリーのスクロールコンテナーについて、プロバイダーの autoScroll を上書きします。ドラッグの開始時に読み取られます。

MaybeElementRef

SortableListOptions と同じ:ツリーの代わりにドロップを受け付ける要素。デフォルトはツリー自身の要素です。

boolean値 · ref · ゲッター

true:行をドラッグできず、アイテムを受け入れもしません。

( event: SortableTreeDropEvent<T>, ) => MaybePromise<BeforeDropResult>

SortableListOptions と同じ。

(event: SortableTreeDropEvent<T>) => void

SortableListOptions と同じ:書き込みの前に呼ばれ、event.preventDefault() で書き込みをスキップします。

返り値

makeSortableTree が返すもの。

Key

ツリーの id:id オプション、または自動で作られた id。

ComputedRef<FlatNode<T>[]>

ドラフトの順序で並んだ表示中のノード。アクティブなノードは予測された深さを持ちます。

ComputedRef<TreeProjection | null>

アクティブなノードが着地する場所。このツリーにない場合は null。

ComputedRef<SortableIndicator | null>

インジケーターモード:ドロップ先を、その depth と parentKey とともに。ここにない場合は null。

ComputedRef<boolean>

ドラッグがツリーの上にあります。

ComputedRef<boolean>

何かがドラッグされていて、このツリーがそれを受け入れます。

ComputedRef<Key | null>

仮想化ライブラリがマウントし続けるべき行:着地位置がこのツリーにある間はその行(ドラッグ中のノード、掴んだノードが乗っている選択中のノード、コピー、作成されたノード)、それ以外はドラッグ中のノード。

ComputedRef<number>

items における activeKey のインデックス。ここにない場合は -1。

ComputedRef<Size | null>

ドラッグ開始時の、ドラッグ中の行のサイズ。

() => void

ライブラリが起こしたのではないレイアウトの変化をアニメーションさせます(たとえば仮想化ライブラリの再測定)。

フラットなノード

ツリーの表示中のノード。ツリーの items に並ぶとおりです:順番に描画し、depth に応じてインデントしてください。

Key

ノードのキー(getKey)。

T

あなたのノード。

number

深さ:ルートは 0。ドラッグ中のノードは予測された深さを持ちます。

Key | null

親のキー。ルートでは null。

number

兄弟の中でのインデックス。

boolean

子を持っています(表示されているかどうかは問いません)。

boolean

子が非表示です(キーが collapsed に含まれています)。

投影

ドラッグ中のノードがツリーのどこに着地するか。

number

ノードが得る深さ(ルートは 0)。

Key | null

ノードが入る先の親ノード。ルートでは null。

ツリーのドラッグが深さを決める方法:'offset' は横方向にどれだけ動いたか(1 レベルあたり indentation)で、'hover' は行の中央にホバーすることで決め、その行がドラッグを子として受け取ります。'both' は両方です。

type TreeNesting = 'offset' | 'hover' | 'both'

ドロップイベント

ツリーのドロップイベント。index は parentKey の下の兄弟の中での位置です(from:移動前。to:移動後で、ノードはすでに元の場所から取り除かれています)。ルートノードと、ほかのリストからのアイテムでは、from.parentKey は null です。マルチドラッグでは keys(それぞれサブツリーを伴う)を並べて移動します:from はドラッグを先導するノード(掴んだノード、またはそれが乗っている選択中のノード)があった場所、to はそのうち最初のものが着地する場所です。コピー(mode: 'copy')はノードをその場に残し、そのコピーである items を挿入します。通常のドラッグ可能な要素(mode: 'insert')では、createItem が作ったノードを挿入します。

{ list: Key | null; index: number; parentKey: Key | null }

ドラッグを先導するノードがあった場所:そのツリー、兄弟の中でのインデックス、親。

{ list: Key; index: number; parentKey: Key | null }

最初にドロップされたノードが着地する場所:そのツリー、新しい兄弟の中でのインデックス、新しい親。