Angular Material

Angular CDK drag-drop API 参考文档

import {DragDropModule} from '@angular/cdk/drag-drop';

服务

`DragDrop`

允许把拖放功能附加到 DOM 元素上的服务。

Service that allows for drag-and-drop functionality to be attached to DOM elements.

方法

createDrag
把一个元素变成一个可拖动的条目。 Turns an element into a draggable item. 要附加拖动功能的元素。 @param element Element to which to attach the dragging functionality. 用于配置拖动行为的对象。 @param config Object used to configure the dragging behavior.
参数 Parameters
element `HTMLElement \| ElementRef<HTMLElement>`
config `DragRefConfig = DEFAULT_CONFIG`
返回值 Returns
`DragRef<T>`

createDropList
把一个元素转成一个拖放列表。 Turns an element into a drop list. 要附加投放列表功能的元素。 @param element Element to which to attach the drop list functionality.
参数 Parameters
element `HTMLElement \| ElementRef<HTMLElement>`
返回值 Returns
`DropListRef<T>`

指令

`CdkDropList`

包装一组可拖动条目的容器。

Container that wraps a set of draggable items.

选择器： [cdkDropList] cdk-drop-list

导出为： cdkDropList

属性

名称	描述
@Input('cdkDropListAutoScrollDisabled') `autoScrollDisabled: boolean`	用户将指针移到边缘附近时是否自动滚动视图。 Whether to auto-scroll the view when the user moves their pointer close to the edges.
@Input('cdkDropListAutoScrollStep') `autoScrollStep: number`	当自动滚动元素时，这是每一帧滚动的像素数。 Number of pixels to scroll for each frame when auto-scrolling an element.
@Input('cdkDropListConnectedTo') `connectedTo: (CdkDropList \| string)[] \| CdkDropList \| string`	此容器连接到的其他可拖动容器，此容器中的条目可以转移到其中。可以是到其他投放容器的引用，也可以是其唯一 ID。 Other draggable containers that this container is connected to and into which the container's items can be transferred. Can either be references to other drop containers, or their unique IDs.
@Input('cdkDropListData') `data: T`	附加到此容器的任意数据。 Arbitrary data to attach to this container.
@Input('cdkDropListDisabled') `disabled: boolean`	是否禁用了从此容器启动拖曳序列的方法。 Whether starting a dragging sequence from this container is disabled.
@Input('cdkDropListEnterPredicate') `enterPredicate: (drag: CdkDrag, drop: CdkDropList) => boolean`	此函数用于确定是否允许将条目移入投放容器。 Function that is used to determine whether an item is allowed to be moved into a drop container.
@Input() `id: string`	投放区的唯一 ID。可以在 `connectedTo` 中用作另一个 `CdkDropList` 的引用。 Unique ID for the drop zone. Can be used as a reference in the `connectedTo` of another `CdkDropList`.
@Input('cdkDropListLockAxis') `lockAxis: DragAxis`	沿着指定的轴锁定容器内可拖动元素的位置。 Locks the position of the draggable elements inside the container along the specified axis.
@Input('cdkDropListOrientation') `orientation: DropListOrientation`	列表的方向。 Direction in which the list is oriented.
@Input('cdkDropListSortPredicate') `sortPredicate: (index: number, drag: CdkDrag, drop: CdkDropList) => boolean`	一个函数，用来判断某个条目是否可以被排序到特定索引。 Functions that is used to determine whether an item can be sorted into a particular index.
@Input('cdkDropListSortingDisabled') `sortingDisabled: boolean`	是否禁用此投放列表中的排序。 Whether sorting within this drop list is disabled.
@Output('cdkDropListDropped') `dropped: EventEmitter<CdkDragDrop<T, any>>`	当用户把一个条目投放进该容器时就会触发。 Emits when the user drops an item inside the container.
@Output('cdkDropListEntered') `entered: EventEmitter<CdkDragEnter<T>>`	当用户把一个新的拖动条目移到这个容器中时，就会触发。 Emits when the user has moved a new drag item into this container.
@Output('cdkDropListExited') `exited: EventEmitter<CdkDragExit<T>>`	当用户通过将条目拖到另一个容器中来将其从容器中移除时发出。 Emits when the user removes an item from the container by dragging it into another container.
@Output('cdkDropListSorted') `sorted: EventEmitter<CdkDragSortEvent<T>>`	当用户正在主动拖动以交换条目时，就会触发。 Emits as the user is swapping items while actively dragging.
`element: ElementRef<HTMLElement>`	Element that the drop list is attached to.

方法

addItem

addItem
在投放列表中注册一个条目。 Registers an items with the drop list.
item `CdkDrag<any>`

在投放列表中注册一个条目。

Registers an items with the drop list.

参数

Parameters

item

CdkDrag<any>

getSortedItems

getSortedItems
获取列表中的已注册条目，按其在 DOM 中的位置排序。 Gets the registered items in the list, sorted by their position in the DOM.
`CdkDrag[]`

获取列表中的已注册条目，按其在 DOM 中的位置排序。

Gets the registered items in the list, sorted by their position in the DOM.

返回值

Returns

CdkDrag[]

removeItem

removeItem
从投放列表中删除一个条目。 Removes an item from the drop list.
item `CdkDrag<any>`

从投放列表中删除一个条目。

Removes an item from the drop list.

参数

Parameters

item

CdkDrag<any>

`CdkDropListGroup`

声明性地将同级 cdkDropList 实例连接在一起。放置在 cdkDropListGroup 内的所有 cdkDropList 元素将自动互连。可作为 cdkDropList 的输入属性 cdkDropListConnectedTo 的替代品。

Declaratively connects sibling cdkDropList instances together. All of the cdkDropList elements that are placed inside a cdkDropListGroup will be connected to each other automatically. Can be used as an alternative to the cdkDropListConnectedTo input from cdkDropList.

选择器： [cdkDropListGroup]

导出为： cdkDropListGroup

属性

名称描述

名称	描述
@Input('cdkDropListGroupDisabled') `disabled: boolean`	是否禁止从该组内部开始拖动序列。 Whether starting a dragging sequence from inside this group is disabled.

@Input('cdkDropListGroupDisabled')

disabled: boolean

是否禁止从该组内部开始拖动序列。

Whether starting a dragging sequence from inside this group is disabled.

`CdkDrag`

可以在 CdkDropList 容器内移动的元素。

Element that can be moved inside a CdkDropList container.

选择器： [cdkDrag]

导出为： cdkDrag

属性

名称	描述
@Input('cdkDragBoundary') `boundaryElement: string \| ElementRef<HTMLElement> \| HTMLElement`	本节点或选择器将用于确定用来限制可拖动对象位置的元素。如果传入了一个字符串，它将用作选择器，该选择器将从元素的父级开始一直沿 DOM 进行匹配，直到找到匹配项为止。 Node or selector that will be used to determine the element to which the draggable's position will be constrained. If a string is passed in, it'll be used as a selector that will be matched starting from the element's parent and going up the DOM until a match has been found.
@Input('cdkDragConstrainPosition') `constrainPosition: (point: Point, dragRef: DragRef) => Point`	本函数用于自定义在拖动条目时如何限制其位置的逻辑。使用用户指针在页面上的当前位置进行调用，并且要返回描述该条目应该出现在哪里的点。 Function that can be used to customize the logic of how the position of the drag item is limited while it's being dragged. Gets called with a point containing the current position of the user's pointer on the page and should return a point describing where the item should be rendered.
@Input('cdkDragData') `data: T`	要附加到此拖动实例的任意数据。 Arbitrary data to attach to this drag instance.
@Input('cdkDragDisabled') `disabled: boolean`	是否已禁止拖动此元素。 Whether starting to drag this element is disabled.
@Input('cdkDragStartDelay') `dragStartDelay: DragStartDelay`	用户放下指针后到开始拖动元素之前要等待的毫秒数。 Amount of milliseconds to wait after the user has put their pointer down before starting to drag the element.
@Input('cdkDragFreeDragPosition') `freeDragPosition: { x: number; y: number; }`	设置投放容器外部的 `CdkDrag` 的位置。可用于为返回的用户恢复元素的位置。 Sets the position of a `CdkDrag` that is outside of a drop container. Can be used to restore the element's position for a returning user.
@Input('cdkDragLockAxis') `lockAxis: DragAxis`	锁定所拖动元素沿指定轴的位置。 Locks the position of the dragged element along the specified axis.
@Input('cdkDragPreviewClass') `previewClass: string \| string[]`	要添加到预览元素中的类。 Class to be added to the preview element.
@Input('cdkDragPreviewContainer') `previewContainer: PreviewContainer`	Configures the place into which the preview of the item will be inserted. Can be configured globally through `CDK_DROP_LIST`. Possible values: `global` - Preview will be inserted at the bottom of the `<body>`. The advantage is that you don't have to worry about `overflow: hidden` or `z-index`, but the item won't retain its inherited styles. `parent` - Preview will be inserted into the parent of the drag item. The advantage is that inherited styles will be preserved, but it may be clipped by `overflow: hidden` or not be visible due to `z-index`. Furthermore, the preview is going to have an effect over selectors like `:nth-child` and some flexbox configurations. `ElementRef<HTMLElement> \| HTMLElement` - Preview will be inserted into a specific element. Same advantages and disadvantages as `parent`.
@Input('cdkDragRootElement') `rootElementSelector: string`	本选择器用于在 DOM 树中从本 `cdkDrag` 元素往上找，以确定其根级可拖动元素。当尝试在可能无法访问的元素上启动拖动时，传递一个备用根元素是很有用的。 Selector that will be used to determine the root draggable element, starting from the `cdkDrag` element and going up the DOM. Passing an alternate root element is useful when trying to enable dragging on an element that you might not have access to.
@Output('cdkDragDropped') `dropped: EventEmitter<CdkDragDrop<any>>`	当用户把条目放到容器中时，就会触发。 Emits when the user drops the item inside a container.
@Output('cdkDragEnded') `ended: EventEmitter<CdkDragEnd>`	当用户停止拖动容器中的某个条目时，会发出本通知。 Emits when the user stops dragging an item in the container.
@Output('cdkDragEntered') `entered: EventEmitter<CdkDragEnter<any>>`	当用户把本条目移到新容器中时发出通知。 Emits when the user has moved the item into a new container.
@Output('cdkDragExited') `exited: EventEmitter<CdkDragExit<any>>`	当用户通过把拖动条目从所在的容器移到另一个容器中时，就会触发。 Emits when the user removes the item its container by dragging it into another container.
@Output('cdkDragMoved') `moved: Observable<CdkDragMove<T>>`	当用户拖动条目时触发。慎用，因为此事件将针对用户拖过的每个像素触发。 Emits as the user is dragging the item. Use with caution, because this event will fire for every pixel that the user has dragged.
@Output('cdkDragReleased') `released: EventEmitter<CdkDragRelease>`	当用户释放了一个拖动条目时触发。位于任何动画开始之前。 Emits when the user has released a drag item, before any animations have started.
@Output('cdkDragStarted') `started: EventEmitter<CdkDragStart>`	当用户开始拖动该条目时会触发。 Emits when the user starts dragging the item.
`dropContainer: CdkDropList`	Droppable container that the draggable is a part of.
`element: ElementRef<HTMLElement>`	Element that the draggable is attached to.

方法

getFreeDragPosition

getFreeDragPosition
获取可拖动对象在投放容器外的像素坐标。 Gets the pixel coordinates of the draggable outside of a drop container.
`{ readonly x: number; readonly y: number; }`

获取可拖动对象在投放容器外的像素坐标。

Gets the pixel coordinates of the draggable outside of a drop container.

返回值

Returns

{
    readonly x: number;
    readonly y: number;
}

getPlaceholderElement

getPlaceholderElement
返回在拖动当前元素时要用作占位符的元素。 Returns the element that is being used as a placeholder while the current element is being dragged.
`HTMLElement`

返回在拖动当前元素时要用作占位符的元素。

Returns the element that is being used as a placeholder while the current element is being dragged.

返回值

Returns

HTMLElement

getRootElement

getRootElement
返回可拖动条目的根元素。 Returns the root draggable element.
`HTMLElement`

返回可拖动条目的根元素。

Returns the root draggable element.

返回值

Returns

HTMLElement

reset
将一个独立的拖动条目重置到初始位置。 Resets a standalone drag item to its initial position.

reset

将一个独立的拖动条目重置到初始位置。

Resets a standalone drag item to its initial position.

`CdkDragHandle`

可用于拖动 CdkDrag 实例的手柄。

Handle that can be used to drag a CdkDrag instance.

选择器： [cdkDragHandle]

属性

名称描述

名称	描述
@Input('cdkDragHandleDisabled') `disabled: boolean`	是否要禁用通过该手柄开始拖动的功能。 Whether starting to drag through this handle is disabled.
`element: ElementRef<HTMLElement>`

@Input('cdkDragHandleDisabled')

disabled: boolean

是否要禁用通过该手柄开始拖动的功能。

Whether starting to drag through this handle is disabled.

element: ElementRef<HTMLElement>

`CdkDragPreview`

拖动时将用作预览 CdkDrag 的模板的元素。

Element that will be used as a template for the preview of a CdkDrag when it is being dragged.

选择器： ng-template[cdkDragPreview]

属性

名称描述

名称	描述
@Input() `data: T`	要添加到预览模板实例的上下文数据。 Context data to be added to the preview template instance.
@Input() `matchSize: boolean`	预览是否应保持与要拖动的条目相同的大小。 Whether the preview should preserve the same size as the item that is being dragged.
`templateRef: TemplateRef<T>`

@Input()

data: T

要添加到预览模板实例的上下文数据。

Context data to be added to the preview template instance.

@Input()

matchSize: boolean

预览是否应保持与要拖动的条目相同的大小。

Whether the preview should preserve the same size as the item that is being dragged.

templateRef: TemplateRef<T>

`CdkDragPlaceholder`

拖动时将用作 CdkDrag 占位符模板的元素。该占位符会用来代替要拖动的元素。

Element that will be used as a template for the placeholder of a CdkDrag when it is being dragged. The placeholder is displayed in place of the element being dragged.

选择器： ng-template[cdkDragPlaceholder]

属性

名称描述

名称	描述
@Input() `data: T`	要添加到占位符模板实例的上下文数据。 Context data to be added to the placeholder template instance.
`templateRef: TemplateRef<T>`

@Input()

data: T

要添加到占位符模板实例的上下文数据。

Context data to be added to the placeholder template instance.

templateRef: TemplateRef<T>

类

`DragRef`

可拖动条目的引用。用来操纵或丢弃条目。

Reference to a draggable item. Used to manipulate or dispose of the item.

属性

名称	描述
`beforeStarted: Subject<void>`	当拖曳序列准备就绪时触发。 Emits as the drag sequence is being prepared.
`constrainPosition: (point: Point, dragRef: DragRef) => Point`	一个函数，可以用来自定义拖动条目的位置限制逻辑。通过一个包含该用户指针在页面上的当前位置进行调用，并返回一个描述该条目应该渲染在哪个位置的点。 Function that can be used to customize the logic of how the position of the drag item is limited while it's being dragged. Gets called with a point containing the current position of the user's pointer on the page and should return a point describing where the item should be rendered.
`data: T`	可以附加在拖动条目上的任意数据。 Arbitrary data that can be attached to the drag item.
`disabled: boolean`	是否已禁止拖动此元素。 Whether starting to drag this element is disabled.
`dragStartDelay: number \| { touch: number; mouse: number; }`	用户在开始拖动元素之前把指针放下之后要等待的毫秒数。 Amount of milliseconds to wait after the user has put their pointer down before starting to drag the element.
`dropped: Subject<{ previousIndex: number; currentIndex: number; item: DragRef; container: DropListRef; previousContainer: DropListRef; distance: Point; dropPoint: Point; isPointerOverContainer: boolean; }>`	当用户把条目放到容器中时，就会触发。 Emits when the user drops the item inside a container.
`ended: Subject<{ source: DragRef; distance: Point; dropPoint: Point; }>`	当用户停止拖动容器中的某个条目时，会发出本通知。 Emits when the user stops dragging an item in the container.
`entered: Subject<{ container: DropListRef; item: DragRef; currentIndex: number; }>`	当用户把本条目移到新容器中时发出通知。 Emits when the user has moved the item into a new container.
`exited: Subject<{ container: DropListRef; item: DragRef; }>`	当用户通过把拖动条目从所在的容器移到另一个容器中时，就会触发。 Emits when the user removes the item its container by dragging it into another container.
`lockAxis: 'x' \| 'y'`	拖动时锁定的轴。 Axis along which dragging is locked.
`moved: Observable<{ source: DragRef; pointerPosition: { x: number; y: number; }; event: MouseEvent \| TouchEvent; distance: Point; delta: { x: -1 \| 0 \| 1; y: -1 \| 0 \| 1; }; }>`	当用户正在拖动该条目时会触发。请谨慎使用，因为此事件会在用户拖动每一个像素时触发。 Emits as the user is dragging the item. Use with caution, because this event will fire for every pixel that the user has dragged.
`previewClass: string \| string[] \| undefined`	要添加到预览元素中的类。 Class to be added to the preview element.
`released: Subject<{ source: DragRef; }>`	当用户释放了一个拖动条目时触发。位于任何动画开始之前。 Emits when the user has released a drag item, before any animations have started.
`started: Subject<{ source: DragRef; }>`	当用户开始拖动该条目时会触发。 Emits when the user starts dragging the item.

方法

disableHandle

disableHandle
禁用拖动手柄。当手柄被禁用时，它会捕获并中止拖动操作。 Sets a handle as disabled. While a handle is disabled, it'll capture and interrupt dragging. 要被禁用的手柄元素。 @param handle Handle element that should be disabled.
handle `HTMLElement`

禁用拖动手柄。当手柄被禁用时，它会捕获并中止拖动操作。

Sets a handle as disabled. While a handle is disabled, it'll capture and interrupt dragging.

要被禁用的手柄元素。

@param handle Handle element that should be disabled.

参数

Parameters

handle

HTMLElement

dispose
从 DOM 元素中移除拖动功能。 Removes the dragging functionality from the DOM element.

dispose

从 DOM 元素中移除拖动功能。

Removes the dragging functionality from the DOM element.

enableHandle

enableHandle
启用一个已被禁用的手柄。 Enables a handle, if it has been disabled. 要启用的手柄。 @param handle Handle element to be enabled.
handle `HTMLElement`

启用一个已被禁用的手柄。

Enables a handle, if it has been disabled.

要启用的手柄。

@param handle Handle element to be enabled.

参数

Parameters

handle

HTMLElement

getFreeDragPosition

getFreeDragPosition
获取可拖动元素在投放容器外部的当前位置（以像素为单位）。 Gets the current position in pixels the draggable outside of a drop container.
`Readonly<Point>`

获取可拖动元素在投放容器外部的当前位置（以像素为单位）。

Gets the current position in pixels the draggable outside of a drop container.

返回值

Returns

Readonly<Point>

getPlaceholderElement

getPlaceholderElement
在拖动当前元素的同时，返回当前占位符所在的元素。 Returns the element that is being used as a placeholder while the current element is being dragged.
`HTMLElement`

在拖动当前元素的同时，返回当前占位符所在的元素。

Returns the element that is being used as a placeholder while the current element is being dragged.

返回值

Returns

HTMLElement

getRootElement

getRootElement
返回可拖动条目的根元素。 Returns the root draggable element.
`HTMLElement`

返回可拖动条目的根元素。

Returns the root draggable element.

返回值

Returns

HTMLElement

getVisibleElement

getVisibleElement
获取代表该拖动条目的当前可见元素。拖动期间是其占位符，其它时候是其根元素。 Gets the currently-visible element that represents the drag item. While dragging this is the placeholder, otherwise it's the root element.
`HTMLElement`

获取代表该拖动条目的当前可见元素。拖动期间是其占位符，其它时候是其根元素。

Gets the currently-visible element that represents the drag item. While dragging this is the placeholder, otherwise it's the root element.

返回值

Returns

HTMLElement

isDragging

isDragging
检查当前是否正在拖动该元素。 Checks whether the element is currently being dragged.
`boolean`

检查当前是否正在拖动该元素。

Checks whether the element is currently being dragged.

返回值

Returns

boolean

reset
将一个独立的拖动条目重置到初始位置。 Resets a standalone drag item to its initial position.

reset

将一个独立的拖动条目重置到初始位置。

Resets a standalone drag item to its initial position.

setFreeDragPosition
设置可拖动元素在投放容器外部的当前位置（以像素为单位）。 Sets the current position in pixels the draggable outside of a drop container. 要设置的新位置。 @param value New position to be set.
参数 Parameters
value `Point`
返回值 Returns
`this`

withBoundaryElement
用于进行可拖动位置限制的元素。 Element to which the draggable's position will be constrained.
参数 Parameters
boundaryElement `HTMLElement \| ElementRef<HTMLElement>`
返回值 Returns
`this`

withDirection
设置可拖动条目的布局方向。 Sets the layout direction of the draggable item.
参数 Parameters
direction `Direction`
返回值 Returns
`this`

withHandles
注册可以用来拖动元素的手柄。 Registers the handles that can be used to drag the element.
参数 Parameters
handles `(HTMLElement \| ElementRef<HTMLElement>)[]`
返回值 Returns
`this`

withParent
Sets the parent ref that the ref is nested in.
参数 Parameters
parent `DragRef<unknown>`
返回值 Returns
`this`

withPlaceholderTemplate
注册要用作拖动占位符的模板。 Registers the template that should be used for the drag placeholder. 用来生成占位符的模板。 @param template Template that from which to stamp out the placeholder.
参数 Parameters
template `DragHelperTemplate<any>`
返回值 Returns
`this`

withPreviewContainer
Sets the container into which to insert the preview element. @param value Container into which to insert the preview.
参数 Parameters
value `PreviewContainer`
返回值 Returns
`this`

withPreviewTemplate
注册要用作拖动预览的模板。 Registers the template that should be used for the drag preview. 用来生成预览图的模板。 @param template Template that from which to stamp out the preview.
参数 Parameters
template `DragPreviewTemplate<any>`
返回值 Returns
`this`

withRootElement
设置备用的拖动根元素。根元素是用户拖动时会被移动的元素。当你尝试在你可能无权访问的元素上启用拖曳时，传入一个备用的根元素是很有用的。 Sets an alternate drag root element. The root element is the element that will be moved as the user is dragging. Passing an alternate root element is useful when trying to enable dragging on an element that you might not have access to.
参数 Parameters
rootElement `HTMLElement \| ElementRef<HTMLElement>`
返回值 Returns
`this`

`DropListRef`

投放列表的引用。用来操纵或丢弃容器。

Reference to a drop list. Used to manipulate or dispose of the container.

属性

名称	描述
`autoScrollDisabled: boolean`	当用户把指针移到边缘附近时是否禁止自动滚动视图。 Whether auto-scrolling the view when the user moves their pointer close to the edges is disabled.
`autoScrollStep: number`	当自动滚动元素时，这是每一帧滚动的像素数。 Number of pixels to scroll for each frame when auto-scrolling an element.
`beforeStarted: Subject<void>`	在拖动开始之前触发。 Emits right before dragging has started.
`data: T`	任意数据都可以附加到投放列表中。 Arbitrary data that can be attached to the drop list.
`disabled: boolean`	是否禁用了从此容器启动拖曳序列的方法。 Whether starting a dragging sequence from this container is disabled.
`dropped: Subject<{ item: DragRef; currentIndex: number; previousIndex: number; container: DropListRef; previousContainer: DropListRef; isPointerOverContainer: boolean; distance: Point; dropPoint: Point; }>`	当用户把一个条目投放进该容器时就会触发。 Emits when the user drops an item inside the container.
`element: HTMLElement \| ElementRef<HTMLElement>`	投放表附加到的元素 Element that the drop list is attached to.
`enterPredicate: (drag: DragRef, drop: DropListRef) => boolean`	该函数用于判断是否允许某个条目移入投放容器。 Function that is used to determine whether an item is allowed to be moved into a drop container.
`entered: Subject<{ item: DragRef; container: DropListRef; currentIndex: number; }>`	当用户把一个新的拖动条目移到这个容器中时，就会触发。 Emits when the user has moved a new drag item into this container.
`exited: Subject<{ item: DragRef; container: DropListRef; }>`	当用户把条目拖到另一个容器中并从当前容器中删除该条目时触发。 Emits when the user removes an item from the container by dragging it into another container.
`lockAxis: 'x' \| 'y'`	沿着指定的轴锁定容器内可拖动元素的位置。 Locks the position of the draggable elements inside the container along the specified axis.
`sortPredicate: (index: number, drag: DragRef, drop: DropListRef) => boolean`	一个函数，用来判断某个条目是否可以被排序到特定索引。 Functions that is used to determine whether an item can be sorted into a particular index.
`sorted: Subject<{ previousIndex: number; currentIndex: number; container: DropListRef; item: DragRef; }>`	当用户正在主动拖动以交换条目时，就会触发。 Emits as the user is swapping items while actively dragging.
`sortingDisabled: boolean`	是否禁用了列表中的条目排序。 Whether sorting items within the list is disabled.

方法

connectedTo
设置连接到这个容器的容器。当有两个或多个容器相连时，系统会允许用户在它们之间传输条目。 Sets the containers that are connected to this one. When two or more containers are connected, the user will be allowed to transfer items between them. 当前容器应该连接到的其他容器。 @param connectedTo Other containers that the current containers should be connected to.
参数 Parameters
connectedTo `DropListRef<any>[]`
返回值 Returns
`this`

dispose
从 DOM 元素中移除投放列表的功能。 Removes the drop list functionality from the DOM element.

dispose

从 DOM 元素中移除投放列表的功能。

Removes the drop list functionality from the DOM element.

drop
把条目投放到这个容器里 Drops an item into this container. 要被投放进此容器的条目。 @param item Item being dropped into the container. 该条目应该插入到的索引。 @param currentIndex Index at which the item should be inserted. 拖动开始时该条目的索引。 @param previousIndex Index of the item when dragging started. 该条目被拖入的容器。 @param previousContainer Container from which the item got dragged in. 当条目被删除时，用户的指针是否在此容器上。 @param isPointerOverContainer Whether the user's pointer was over the container when the item was dropped. 自拖曳序列开始以来用户拖动过的距离。 @param distance Distance the user has dragged since the start of the dragging sequence.
参数 Parameters
item `DragRefInternal`
currentIndex `number`
previousIndex `number`
previousContainer `DropListRef<any>`
isPointerOverContainer `boolean`
distance `Point`
dropPoint `Point`

enter
发出一个事件，表明用户已经把某个条目移到了容器中。 Emits an event to indicate that the user moved an item into the container. 被移入容器中的条目。 @param item Item that was moved into the container. 该条目沿 X 轴的位置。 @param pointerX Position of the item along the X axis. 该条目沿 Y 轴的位置。 @param pointerY Position of the item along the Y axis. 条目进来后的索引。如果省略，容器会自动尝试定位。 @param index Index at which the item entered. If omitted, the container will try to figure it out automatically.
参数 Parameters
item `DragRefInternal`
pointerX `number`
pointerY `number`
index? `number`

exit

exit
用户将一个条目拖入另一个容器并从当前容器删除该条目。 Removes an item from the container after it was dragged into another container by the user. 被拖走的条目 @param item Item that was dragged out.
item `DragRefInternal`

用户将一个条目拖入另一个容器并从当前容器删除该条目。

Removes an item from the container after it was dragged into another container by the user.

被拖走的条目

@param item Item that was dragged out.

参数

Parameters

item

DragRefInternal

getItemIndex
找出容器中某个条目的索引。 Figures out the index of an item in the container. 应该确定索引的条目。 @param item Item whose index should be determined.
参数 Parameters
item `DragRefInternal`
返回值 Returns
`number`

getScrollableParents

getScrollableParents
获取在这个投放容器中注册的可滚动父类。 Gets the scrollable parents that are registered with this drop container.
`readonly HTMLElement[]`

获取在这个投放容器中注册的可滚动父类。

Gets the scrollable parents that are registered with this drop container.

返回值

Returns

readonly HTMLElement[]

isDragging
当前是否正在拖动此列表中的某个条目。 Whether an item from this list is currently being dragged.

isDragging

当前是否正在拖动此列表中的某个条目。

Whether an item from this list is currently being dragged.

isReceiving

isReceiving
列表是否能够接收当前被拖入的已连接投放列表中的条目。 Whether the list is able to receive the item that is currently being dragged inside a connected drop list.
`boolean`

列表是否能够接收当前被拖入的已连接投放列表中的条目。

Whether the list is able to receive the item that is currently being dragged inside a connected drop list.

返回值

Returns

boolean

start
开始拖动一个条目。 Starts dragging an item.

start

开始拖动一个条目。

Starts dragging an item.

withDirection
设置投放列表的布局方向。 Sets the layout direction of the drop list.
参数 Parameters
direction `Direction`
返回值 Returns
`this`

withItems
设置属于该列表的可拖动条目。 Sets the draggable items that are a part of this list. 属于这个列表的条目。 @param items Items that are a part of this list.
参数 Parameters
items `DragRefInternal[]`
返回值 Returns
`this`

withOrientation
设置容器的方向。 Sets the orientation of the container. 容器的新方向。 @param orientation New orientation for the container.
参数 Parameters
orientation `"vertical" \| "horizontal"`
返回值 Returns
`this`

withScrollableParents
当用户在拖动时，设置哪些父元素可以滚动。 Sets which parent elements are can be scrolled while the user is dragging. 那些可以滚动的元素。 @param elements Elements that can be scrolled.
参数 Parameters
elements `HTMLElement[]`
返回值 Returns
`this`

接口

`DragRefConfig`

可以用来配置 DragRef 行为的对象。

Object that can be used to configure the behavior of DragRef.

属性

名称	描述
`dragStartThreshold: number`	在 CDK 启动拖曳序列之前，用户应该拖动的最小像素数。 Minimum amount of pixels that the user should drag, before the CDK initiates a drag sequence.
`parentDragRef: DragRef`	当前拖动条目所嵌套在的父拖动的引用。 Ref that the current drag item is nested in.
`pointerDirectionChangeThreshold: number`	在 CDK 认为改变了拖动方向之前，用户应该拖动的像素数量。 Amount the pixels the user should drag before the CDK considers them to have changed the drag direction.
`zIndex: number`	`z-index` 用于为拖动条目创建的绝对定位元素。 `z-index` for the absolutely-positioned elements that are created by the drag item.

`Point`

页面上或元素中的点坐标。

Point on the page or within an element.

属性

名称	描述
`x: number`
`y: number`

`CdkDragStart`

当用户开始拖动拖动时会发出本事件。

Event emitted when the user starts dragging a draggable.

属性

名称描述

source: CdkDrag<T>

发出了本事件的可拖动对象。

Draggable that emitted the event.

`CdkDragRelease`

用户在释放条目时发出的事件，发生在开始任何动画之前。

Event emitted when the user releases an item, before any animations have started.

属性

名称描述

source: CdkDrag<T>

发出了本事件的可拖动对象。

Draggable that emitted the event.

`CdkDragEnd`

当用户停止拖动时会发出本事件。

Event emitted when the user stops dragging a draggable.

属性

名称描述

distance: { x: number; y: number; }

自拖曳序列启动以来用户拖动过的像素距离。

Distance in pixels that the user has dragged since the drag sequence started.

dropPoint: { x: number; y: number; }

Position where the pointer was when the item was dropped

source: CdkDrag<T>

发出了本事件的可拖动对象。

Draggable that emitted the event.

`CdkDragEnter`

当用户把条目移到新的投送容器中时，就会发出本事件。

Event emitted when the user moves an item into a new drop container.

属性

名称描述

container: CdkDropList<T>

用户移入了该条目的容器。

Container into which the user has moved the item.

currentIndex: number

该条目已进入该容器中的索引。

Index at which the item has entered the container.

item: CdkDrag<I>

被移入容器中的条目。

Item that was moved into the container.

`CdkDragExit`

当用户把一个条目移到另一个投放容器，并从当前容器中移除时，就会触发本事件。

Event emitted when the user removes an item from a drop container by moving it into another one.

属性

名称描述

container: CdkDropList<T>

用户已移除本条目的容器。

Container from which the user has a removed an item.

item: CdkDrag<I>

已从容器中移除的条目

Item that was removed from the container.

`CdkDragDrop`

当用户在投送容器中放入一个可拖动条目时，就会发出本事件。

Event emitted when the user drops a draggable item inside a drop container.

属性

名称	描述
`container: CdkDropList<T>`	该条目投送到的容器。 Container in which the item was dropped.
`currentIndex: number`	此条目的当前索引。 Current index of the item.
`distance: { x: number; y: number; }`	自拖曳序列启动以来用户拖动的像素距离。 Distance in pixels that the user has dragged since the drag sequence started.
`dropPoint: { x: number; y: number; }`	Position where the pointer was when the item was dropped
`isPointerOverContainer: boolean`	当条目被移除时，用户的指针是否还在容器上。 Whether the user's pointer was over the container when the item was dropped.
`item: CdkDrag`	被投放的条目 Item that is being dropped.
`previousContainer: CdkDropList<O>`	从中拿出条目的容器。可以和 `container` 属性是同一个。 Container from which the item was picked up. Can be the same as the `container`.
`previousIndex: number`	该条目被拿起时的条目索引。 Index of the item when it was picked up.

`CdkDragMove`

当用户正在拖动一个条目时，就会发出一个事件。

Event emitted as the user is dragging a draggable item.

属性

名称	描述
`delta: { x: -1 \| 0 \| 1; y: -1 \| 0 \| 1; }`	指示用户沿每个轴拖动元素的方向。 `1` 表示位置在增加（例如，用户向右或向下移动），而 `-1` 表示它正在减少（它们向左或向上移动）。 `0` 意味着该位置没有变化。 Indicates the direction in which the user is dragging the element along each axis. `1` means that the position is increasing (e.g. the user is moving to the right or downwards), whereas `-1` means that it's decreasing (they're moving to the left or upwards). `0` means that the position hasn't changed.
`distance: { x: number; y: number; }`	自拖曳序列启动以来用户已拖动的像素距离。 Distance in pixels that the user has dragged since the drag sequence started.
`event: MouseEvent \| TouchEvent`	导致拖曳的原生事件 Native event that is causing the dragging.
`pointerPosition: { x: number; y: number; }`	用户指针在页面上的位置。 Position of the user's pointer on the page.
`source: CdkDrag<T>`	被拖动的条目 Item that is being dragged.

`CdkDragSortEvent`

当用户交换两个拖动条目的位置时，会发出一个事件。

Event emitted when the user swaps the position of two drag items.

属性

名称	描述
`container: CdkDropList<T>`	该条目所属的容器。 Container that the item belongs to.
`currentIndex: number`	该条目在当前排序中的索引 Index that the item is currently in.
`item: CdkDrag<I>`	正在排序的条目 Item that is being sorted.
`previousIndex: number`	该条目在先前排序中的索引。 Index from which the item was sorted previously.

`DragDropConfig`

可用于配置模块或组件中的拖动条目和拖放列表的对象。

Object that can be used to configure the drag items and drop lists within a module or a component.

属性

名称	描述
`boundaryElement: string`
`constrainPosition: DragConstrainPosition`
`dragStartDelay: DragStartDelay`
`draggingDisabled: boolean`
`listAutoScrollDisabled: boolean`
`listOrientation: DropListOrientation`
`lockAxis: DragAxis`
`previewClass: string \| string[]`
`previewContainer: 'global' \| 'parent'`
`rootElementSelector: string`
`sortingDisabled: boolean`
`zIndex: number`

函数

moveItemInArray
把某个条目从数组中的一个索引号移到另一个索引号。 Moves an item one index in an array to another. 要移动此条目的数组。 @param array Array in which to move the item. 此条目的起始索引。 @param fromIndex Starting index of the item. 此条目应该移到的索引。 @param toIndex Index to which the item should be moved.
参数 Parameters
array `T[]`
fromIndex `number`
toIndex `number`

transferArrayItem
把一个条目从一个数组移动到另一个数组。 Moves an item from one array to another. 要从中传输该条目的数组。 @param currentArray Array from which to transfer the item. 要放入该条目的数组。 @param targetArray Array into which to put the item. 当前数组中该条目的索引。 @param currentIndex Index of the item in its current array. 该条目要插入到的索引。 @param targetIndex Index at which to insert the item.
参数 Parameters
currentArray `T[]`
targetArray `T[]`
currentIndex `number`
targetIndex `number`

copyArrayItem
将一个条目从一个数组复制到另一个数组，并把它放在当前数组的原始位置。 Copies an item from one array to another, leaving it in its original position in current array. 要从中复制条目的数组。 @param currentArray Array from which to copy the item. 要把该条目复制到的数组。 @param targetArray Array into which is copy the item. 该条目在当前数组中的索引。 @param currentIndex Index of the item in its current array. 该条目在目标数组中要插入的索引。 @param targetIndex Index at which to insert the item.
参数 Parameters
currentArray `T[]`
targetArray `T[]`
currentIndex `number`
targetIndex `number`

类型别名

`PreviewContainer`

Possible places into which the preview of a drag item can be inserted.

global - Preview will be inserted at the bottom of the <body>. The advantage is that you don't have to worry about overflow: hidden or z-index, but the item won't retain its inherited styles.
parent - Preview will be inserted into the parent of the drag item. The advantage is that inherited styles will be preserved, but it may be clipped by overflow: hidden or not be visible due to z-index. Furthermore, the preview is going to have an effect over selectors like :nth-child and some flexbox configurations.
ElementRef<HTMLElement> | HTMLElement - Preview will be inserted into a specific element. Same advantages and disadvantages as parent.

type PreviewContainer = 'global' | 'parent' | ElementRef<HTMLElement> | HTMLElement;

`DragStartDelay`

可用于配置拖动开始延迟的可能值。

Possible values that can be used to configure the drag start delay.

type DragStartDelay = number | {
    touch: number;
    mouse: number;
};

`DragAxis`

可以锁定可能的拖动轴。

Possible axis along which dragging can be locked.

type DragAxis = 'x' | 'y';

`DragConstrainPosition`

可用于约束元素拖动位置的函数。

Function that can be used to constrain the position of a dragged element.

type DragConstrainPosition = (point: Point, dragRef: DragRef) => Point;

`DropListOrientation`

下拉列表的可能方向。

Possible orientations for a drop list.

type DropListOrientation = 'horizontal' | 'vertical';

常量

`CDK_DROP_LIST`

用来引用 CdkDropList 实例的注入令牌。它用作实际 CdkDropList 类的备用令牌，这可能导致不必要地保留该类及其指令元数据。

Injection token that can be used to reference instances of CdkDropList. It serves as alternative token to the actual CdkDropList class which could cause unnecessary retention of the class and its directive metadata.

const CDK_DROP_LIST: InjectionToken<CdkDropList<any>>;

`CDK_DRAG_CONFIG`

注入令牌，可用于配置与拖放相关的组件的行为。

Injection token that can be used to configure the behavior of the drag&drop-related components.

const CDK_DRAG_CONFIG: InjectionToken<DragDropConfig>;

`CDK_DROP_LIST_GROUP`

用来引用 CdkDropListGroup 实例的注入令牌。它用作实际 CdkDropListGroup 类的备用令牌，直接使用该类可能导致该类及其指令的元数据无法被优化掉。

Injection token that can be used to reference instances of CdkDropListGroup. It serves as alternative token to the actual CdkDropListGroup class which could cause unnecessary retention of the class and its directive metadata.

const CDK_DROP_LIST_GROUP: InjectionToken<CdkDropListGroup<unknown>>;

`CDK_DRAG_HANDLE`

用来引用 CdkDragHandle 实例的注入令牌。它用作实际 CdkDragHandle 类的备用令牌，直接使用该类可能导致该类及其指令的元数据无法被优化掉。

Injection token that can be used to reference instances of CdkDragHandle. It serves as alternative token to the actual CdkDragHandle class which could cause unnecessary retention of the class and its directive metadata.

const CDK_DRAG_HANDLE: InjectionToken<CdkDragHandle>;

`CDK_DRAG_PREVIEW`

用来引用 CdkDragPreview 实例的注入令牌。它用作实际 CdkDragPreview 类的备用令牌，直接使用该类可能导致该类及其指令的元数据无法被优化掉。

Injection token that can be used to reference instances of CdkDragPreview. It serves as alternative token to the actual CdkDragPreview class which could cause unnecessary retention of the class and its directive metadata.

const CDK_DRAG_PREVIEW: InjectionToken<CdkDragPreview<any>>;

`CDK_DRAG_PLACEHOLDER`

用来引用 CdkDragPlaceholder 实例的注入令牌。它用作实际 CdkDragPlaceholder 类的备用令牌，直接使用该类可能导致该类及其指令的元数据无法被优化掉。

Injection token that can be used to reference instances of CdkDragPlaceholder. It serves as alternative token to the actual CdkDragPlaceholder class which could cause unnecessary retention of the class and its directive metadata.

const CDK_DRAG_PLACEHOLDER: InjectionToken<CdkDragPlaceholder<any>>;

Angular CDK drag-drop API 参考文档

link 服务

link DragDrop

方法

link 指令

link CdkDropList

属性

方法

link CdkDropListGroup

属性

link CdkDrag

属性

方法

link CdkDragHandle

属性

link CdkDragPreview

属性

link CdkDragPlaceholder

属性

link 类

link DragRef

属性

方法

link DropListRef

属性

方法

link 接口

link DragRefConfig

属性

link Point

属性

link CdkDragStart

属性

link CdkDragRelease

属性

link CdkDragEnd

属性

link CdkDragEnter

属性

link CdkDragExit

属性

link CdkDragDrop

属性

link CdkDragMove

属性

link CdkDragSortEvent

属性

link DragDropConfig

属性

link 函数

link 类型别名

link PreviewContainer

link DragStartDelay

link DragAxis

link DragConstrainPosition

link DropListOrientation

link 常量

link CDK_DROP_LIST

link CDK_DRAG_CONFIG

link CDK_DROP_LIST_GROUP

link CDK_DRAG_HANDLE

link CDK_DRAG_PREVIEW

link CDK_DRAG_PLACEHOLDER

服务

`DragDrop`

指令

`CdkDropList`

`CdkDropListGroup`

`CdkDrag`

`CdkDragHandle`

`CdkDragPreview`

`CdkDragPlaceholder`

类

`DragRef`

`DropListRef`

接口

`DragRefConfig`

`Point`

`CdkDragStart`

`CdkDragRelease`

`CdkDragEnd`

`CdkDragEnter`

`CdkDragExit`

`CdkDragDrop`

`CdkDragMove`

`CdkDragSortEvent`

`DragDropConfig`

函数

类型别名

`PreviewContainer`

`DragStartDelay`

`DragAxis`

`DragConstrainPosition`

`DropListOrientation`

常量

`CDK_DROP_LIST`

`CDK_DRAG_CONFIG`

`CDK_DROP_LIST_GROUP`

`CDK_DRAG_HANDLE`

`CDK_DRAG_PREVIEW`

`CDK_DRAG_PLACEHOLDER`