vue-dnd-kit

문서/API

makeDraggable

요소를 드래그할 수 있게 만듭니다. 자유롭게 드래그하거나, 그 요소를 받아들이는 드롭 대상으로 드래그할 수 있습니다.

이 페이지 편집

이 페이지는 AI가 번역했으며 부정확한 내용이 있을 수 있습니다. 영어 원문 읽기

function makeDraggable<TData = unknown>(  target: MaybeElementRef,  options?: DraggableOptions<TData>,): DraggableReturn;

요소를 드래그할 수 있게 만듭니다. 기본은 자유 드래그이며, 정렬 가능한 리스트는 이 위에 만들어집니다.

const el = useTemplateRef<HTMLElement>('el');
const { isDragging } = makeDraggable(el, { id: 'card', type: 'card', data: { title } });

드래그 앤 드롭을 참고하세요. 정렬 가능한 항목도 draggable입니다. makeSortableItem은 같은 옵션에 몇 가지를 더 받습니다.

Live

데모 불러오는 중…

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

<template>
  <!-- No drop target here: let go, and each card goes back where it was. -->
  <DnDProvider>
    <div class="cards">
      <DragCard title="Grab it anywhere" code="makeDraggable(el)" />
      <DragCard title="Grab the handle" code="{ handle: grip }" handle />
      <DragCard title="It moves itself" code="{ overlay: false }" self />
      <DragCard title="Not now" code="{ disabled: true }" disabled />
    </div>
  </DnDProvider>
</template>

<style scoped>
.cards {
  display: grid;
  grid-template-columns: repeat(2, minmax(0, 220px));
  gap: 14px;
}

@media (max-width: 480px) {
  .cards {
    grid-template-columns: minmax(0, 1fr);
  }
}
</style>

옵션

makeDraggable의 옵션. canDrag를 제외한 모든 옵션은 값, ref, getter를 받으며(overlay, dropAnimation: 값 또는 ref) 필요할 때 읽으므로, 변경은 늦어도 다음 드래그부터 적용됩니다.

id?
Key값 · ref · getter

안정적인 id. 요소가 재활용되는 가상 리스트에서는 getter를 넘기세요. 기본값: useId(). 서버 렌더링과 클라이언트 렌더링 사이에서는 안정적이지만, 컴포넌트 인스턴스마다 새로 만들어집니다.

data?
TData값 · ref · getter

드래그가 담아 갈 아무 데이터. 이벤트와 드롭 대상은 이것을 active.data로 읽습니다.

label?
string값 · ref · getter

사람이 부르는 이름. 스크린 리더용 문구가 id 대신 이 이름을 읽습니다(Picked up Tomato). 이벤트에서는 active.label과 items에 담겨 전달됩니다.

type?
string | string[]값 · ref · getter

이 요소의 타입(하나 또는 여러 개). 드롭 대상의 accept 규칙과 대조됩니다. 없으면 어떤 대상에도 맞습니다.

disabled?
boolean값 · ref · getter

true: 드래그할 수 없습니다(aria-disabled를 알립니다).

handle?
MaybeElement | string값 · ref · getter

draggable 안에서 드래그를 시작하는(그리고 속성을 받는) 요소 또는 선택자.

activation?
ActivationOptions값 · ref · getter

프로바이더의 activation을 재정의합니다. 누르기가 시작될 때 읽습니다.

canDrag?
(event: PointerEvent | KeyboardEvent) => boolean

추가 관문. 예: 키를 누르고 있을 때만 드래그.

overlay?
boolean | Component값 · ref

true(기본값): 프로바이더의 #overlay 슬롯이나 요소의 클론으로 렌더링한 오버레이가 포인터를 따라다닙니다. 컴포넌트: 오버레이가 슬롯보다 먼저 이 컴포넌트를 OverlayProps와 함께 렌더링합니다. false: 오버레이 없이, 반환된 transform으로 요소 자체가 움직입니다. 값 또는 ref(함수는 함수형 컴포넌트이므로 (props) => <Card {...props} />도 됩니다). 오버레이가 있는지는 드래그가 시작될 때 정해지며, 드래그 중에 바꾼 ref는 컴포넌트를 바로 교체합니다(프로바이더의 overlayTransition 참고). 드래그가 드롭 대상 위에 있는 동안에는 그 대상의 overOverlay가 우선합니다. 클론에서는 UI 키트의 누르기 효과(리플)와, 안쪽에서 data-dnd-no-clone이 표시된 요소가 제외됩니다.

dropAnimation?
DropAnimation값 · ref

이 요소의 드래그가 끝날 때 오버레이가 안착하는 방식으로, 프로바이더의 dropAnimation 대신 쓰입니다. 드롭 대상의 overDropAnimation이 우선합니다. 값 또는 ref(함수는 애니메이션입니다)이며, 드롭할 때 읽습니다.

modifiers?
Modifier[]값 · ref · getter

여기서 시작하는 드래그에 적용할 모디파이어. 프로바이더의 modifiers 다음에 적용됩니다. 예: 다른 드래그는 자유롭게 움직이는 페이지에서 요소 하나에만 [restrictToVerticalAxis]. 드래그가 시작될 때 읽습니다.

axis?
'x' | 'y'값 · ref · getter

여기서 시작하는 드래그를 한 축에 고정합니다. 'x'는 가로로만, 'y'는 세로로만 움직입니다. 고정은 modifiers 다음에 적용되므로(마지막에 적용되는 restrictToHorizontalAxis / restrictToVerticalAxis처럼) 모디파이어가 무엇을 하든 유지됩니다. 드래그가 시작될 때 읽습니다.

keyboardMode?
'pixels' | 'droppables'값 · ref · getter

자유 드래그에서의 화살표 키: 픽셀 단위로 이동(기본값)하거나, 항목을 받아들이는 드롭 대상 사이를 건너뜁니다. 화살표 키를 누를 때마다 읽습니다.

attributes?
boolean값 · ref · getter

role/tabindex/aria-* 속성을 설정합니다(기본값 true). 사용자가 직접 지정한 속성은 덮어쓰지 않습니다. 프로바이더 안내 지침의 id는 기존 aria-describedby에 토큰 하나로 추가되며(같은 요소에 있는 UI 키트 툴팁의 id는 유지됩니다), 제거할 때도 그 토큰만 제거합니다. 실시간: 끄면 라이브러리가 설정한 것을 제거합니다.

native?
boolean | NativeDragOptions값 · ref · getter

이 요소의 마우스 드래그가 브라우저 자체의 드래그가 되어 페이지를 떠날 수 있습니다. 데스크톱으로, 다른 앱이나 탭으로, 앱의 다른 창으로. 페이지 위에서는 평소처럼 동작하지만(대상, 자리를 만드는 리스트), 오버레이 대신 브라우저가 드래그되는 이미지를 그립니다. 터치와 키보드 드래그는 라이브러리의 드래그로 남습니다. true는 label을 텍스트로 담습니다. 누르기가 시작될 때 읽습니다. canDrag는 누를 때 확인합니다. 마우스가 얼마나 움직여야 드래그가 시작되는지는 브라우저가 정합니다(activation은 적용되지 않습니다).

반환값

makeDraggable이 반환하는 것.

id
ComputedRef<Key>

draggable의 id: id 옵션, 또는 자동으로 만들어진 id.

isDragging
ComputedRef<boolean>

드래그되는 중이거나(멀티 드래그의 다른 항목으로서도), 오버레이가 아직 안착하는 중입니다.

transform
ComputedRef<Coordinates | null>

overlay: false일 때 적용할 오프셋. 드래그의 오프셋에서 요소가 들어 있는 내용이 시작 이후 움직인 만큼(페이지나 컨테이너가 스크롤됨)을 뺀 값이므로, 요소가 포인터 아래에 머뭅니다.

selected
WritableComputedRef<boolean>

프로바이더의 선택에 들어 있습니다. 선택된 항목 하나를 드래그하면 모두 함께 옮겨집니다. 값을 설정해 선택하거나 선택 해제하세요.

페이지 밖으로

native 드래그가 페이지 밖으로 가지고 나가는 것. 파일과 다른 앱을 참고하세요.

마우스로 페이지 밖으로 드래그할 수 있는 draggable이나 정렬 가능한 항목(native). 데스크톱으로, 다른 앱으로, 다른 탭으로, 앱의 다른 창으로.

data?
(active: Active) => Record<string, string>

다른 앱과 페이지가 받는 것. MIME 타입별 텍스트로, { 'text/plain': title, 'text/uri-list': url } 형태입니다. 드래그가 시작될 때 읽습니다. 정렬 가능한 항목은 앱의 다른 창에 있는 같은 그룹의 리스트를 위해 자기 자신도 담아 갑니다.

effect?
'copy' | 'move' | 'link' | 'copyMove' | 'copyLink' | 'linkMove' | 'all'

드래그가 드롭되는 곳에 허용하는 것(effectAllowed). 기본값 'copyMove'. 이동이면 이쪽 리스트에서 항목이 빠지고, 복사면 그대로 남습니다.