useDraggable

Tags:

一个 React 钩子,用于让元素可拖动。

演示

尝试拖动浮动元素。

源码
Drag to move
X: 320, Y: 320
Drag to move (inner)
X: 10, Y: 10

用法

请查看 API。

源码

点击下方链接跳转 GitHub 查看源代码。

API

const draggable = useDraggable(elementTarget, options)

元素目标 ElementTarget

ElementTarget 是一个联合类型,代表可以被定位的各种元素。

更多详情,请参见 ElementTargetElementTarget 类型

选项 Options

export type UseDraggableOptions = {
  /**
   * 是否只有当指针精确地在目标元素上时才能拖动元素。
   *
   * @defaultValue false
   */
  exact?: boolean
  /**
   * 是否阻止指针事件的默认行为。
   *
   * @defaultValue false
   */
  preventDefault?: boolean
  /**
   * 是否停止指针事件的传播。
   *
   * @defaultValue false
   */
  stopPropagation?: boolean
  /**
   * 是否捕获指针事件。
   *
   * @defaultValue true
   */
  capture?: boolean
  /**
   * 应被拖动的元素。
   *
   * @defaultValue target
   */
  handle?: ElementTarget
  /**
   * 应被拖动的元素。
   *
   * @defaultValue window
   */
  draggingElement?: ElementTarget | GlobalTarget
  /**
   * 应包含可拖动元素的容器元素。
   *
   * @defaultValue undefined
   */
  containerElement?: ElementTarget
  /**
   * 应处理的指针事件类型。
   *
   * @defaultValue ['mouse', 'touch', 'pen']
   */
  pointerTypes?: PointerType[]
  /**
   * 可拖动元素的初始位置。
   *
   * @defaultValue { x: 0; y: 0 }
   */
  initialValue?: Position
  /**
   * 开始拖动时调用的回调函数。
   */
  onStart?: (position: Position, event: PointerEvent) => void | false
  /**
   * 拖动移动时调用的回调函数。
   */
  onMove?: (position: Position, event: PointerEvent) => void
  /**
   * 拖动结束时调用的回调函数。
   */
  onEnd?: (position: Position, event: PointerEvent) => void
  /**
   * 可拖动元素可沿其移动的轴。
   * 
   * @defaultValue 'both'
   */
  axis?: 'x' | 'y' | 'both'
  /**
   * 是否禁用可拖动元素。
   * 
   * @defaultValue false
   */
  disabled?: boolean
}

返回值

export type UseDraggableReturns = {
  /**
   * 可拖动元素的 x 坐标。
   */
  x: number
  /**
   * 可拖动元素的 y 坐标。
   */
  y: number
  /**
   * 应用于可拖动元素的样式。
   */
  style: CSSProperties
  /**
   * 可拖动元素的位置。
   */
  position: Position
  /**
   * 可拖动元素是否正在被拖动。
   */
  isDragging: boolean
}