Angular CDK 滚动 API 参考

import {ScrollingModule} from '@angular/cdk/scrolling';

本服务包含所有已注册的可滚动对象的引用，并在任何一个可滚动对象的引用发出滚动事件时触发事件。

属性
名称 描述

scrollContainers: Map<CdkScrollable, Subscription>

所有可滚动对象引用的映射表，由可滚动对象及其对滚动事件的订阅组成。
方法
ancestorScrolled

返回一个可观察对象，它只在元素的任何可滚动祖先发生滚动时才会触发。
参数

elementOrElementRef

HTMLElement | ElementRef<any>

祖先要监听的元素。

auditTimeInMs ?

number

要对滚动事件进行限流的毫秒数。
返回值
Observable<CdkScrollable | void>

deregister

注销一个可滚动对象的引用，并从它的 scroll 事件的可观察对象中取消订阅。
参数

scrollable

CdkScrollable

要注销的可滚动实例。
getAncestorScrollContainers

返回所有包含所指定元素的已注册可滚动对象。
参数

elementOrElementRef

HTMLElement | ElementRef<any>

返回值
CdkScrollable[]

register

使用该服务注册一个可滚动的实例，并侦听其滚动的事件。当可滚动对象发生滚动时，此服务会把事件发送到记录其滚动的可观察对象中。
参数

scrollable

CdkScrollable

要注册的可滚动对象实例。
scrolled

返回一个可观察对象，它会在任何已注册的可滚动对象引用（或 window, document, body）中发生滚动事件时发出一个事件。可以提供一个毫秒数来来改写默认的“限流”时间。

注意：为了避免每次滚动事件都发生变更检测，从这个流发出的所有事件都会在 Angular Zone 之外运行。如果你要在滚动事件中更新任何数据绑定，就必须使用 NgZone.run 来运行回调。
参数

auditTimeInMs

number = DEFAULT_SCROLL_TIME

返回值
Observable<CdkScrollable | void>

该指令的元素发生滚动时发送一个事件。使用 ScrollDispatcher 服务注册自己，以便把自己包含在滚动事件集合中，并通过该服务来监听。

选择器： [cdk-scrollable] [cdkScrollable]

属性
名称 描述

dir: Directionality

elementRef: ElementRef<HTMLElement>

ngZone: NgZone

scrollDispatcher: ScrollDispatcher

方法
elementScrolled

返回在宿主元素上发生 scroll 事件时会触发的可观察对象。
返回值
Observable<Event>

getElementRef

获取视口的 ElementRef。
返回值
ElementRef<HTMLElement>

measureScrollOffset

测量相对于视口指定边缘的滚动偏移量。这个方法可以用来代替对 scrollLeft 或 scrollTop 的直接检查，因为各浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 该方法返回的值是标准化的，左右都总是指向滚动容器的左侧和右侧，与布局方向无关。start 和 end 在 LTR 上下文中指向左右，在 RTL 上下文则相反。
参数

from

"top" | "bottom" | "start" | "end" | "left" | "right"

要测量的边缘。
返回值
number

scrollTo

滚动到指定的偏移量。这是浏览器原生 scrollTo 方法的标准化版本，因为各个浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 对于此方法，无论布局方向如何，左右都总是指向滚动容器的左侧和右侧。start 和 end 在 LTR 上下文中分别指向左右，在 RTL 上下文中则相反。
参数

options

ExtendedScrollToOptions

指定要滚动到的偏移量。

支持固定大小的虚拟滚动策略。

选择器： cdk-virtual-scroll-viewport[itemSize]

属性
名称 描述
@Input()

itemSize: number

列表中条目的大小（以像素为单位）。
@Input()

maxBufferPx: number

渲染新条目时要渲染的缓冲区的像素数。默认为 200px。
@Input()

minBufferPx: number

缓存在视口之外的最小缓冲区数（以像素为单位）。当缓冲区的数量低于这个数时，就会渲染出更多的条目。默认为 100px。

类似于 ngForOf 的指令，用于渲染虚拟滚动容器中的数据。

选择器： [cdkVirtualFor][cdkVirtualForOf]

属性
名称 描述
@Input()

cdkVirtualForOf: DataSource<T> | Observable<T[]> | NgIterable<T> | null | undefined

要显示的 DataSource。
@Input()

cdkVirtualForTemplate: TemplateRef<CdkVirtualForOfContext<T>>

用来生成新元素的模板。
@Input()

cdkVirtualForTemplateCacheSize: number

缓存的大小，用于存放那些以前没有用过的模板。如果将缓存大小设置为 0 将禁用缓存。默认为 20 个模板。
@Input()

cdkVirtualForTrackBy: TrackByFunction<T> | undefined

TrackByFunction 用于跟踪变更。TrackByFunction 接受索引和条目，并在跟踪更改时产生一个值作为此条目的标识。

dataStream: Observable<readonly T[]>

只要当前 DataSource 中的数据发生变化，就会发出通知。

viewChange: Subject<ListRange>

当渲染的数据视图发生变化时触发。
方法
measureRangeSize

测量指定范围内所有条目的组合大小（水平方向的宽度，垂直方向的高度）。如果该范围包含当前尚未渲染过的条目，则会引发错误。
参数

range

ListRange

orientation

"vertical" | "horizontal"

返回值
number

借助 CdkVirtualForOf 虚拟化滚动行为的视口。

选择器： cdk-virtual-scroll-viewport

属性
名称 描述
@Input({ transform: booleanAttribute })

appendOnly: boolean

滚动出视图后，渲染的条目是否应该保留在 DOM 中。默认情况下，条目将被删除。
@Input()

orientation: "vertical" | "horizontal"

视口滚动的方向。
@Output()

scrolledIndexChange: Observable<number>

当视口中可见的第一个元素的索引发生变化时触发。

elementRef: ElementRef<HTMLElement>

renderedRangeStream: Observable<ListRange>

每当渲染范围发生变化时都会发出通知的流。

scrollable: CdkVirtualScrollable

方法
attach

把 CdkVirtualScrollRepeater 附着到这个视口。
参数

forOf

CdkVirtualScrollRepeater<any>

checkViewportSize

更新视口规格并重新渲染。
detach

拆除当前的 CdkVirtualForOf。
elementScrolled

返回在宿主元素上发生 scroll 事件时会触发的可观察对象。
返回值
Observable<Event>

getDataLength

获取绑定到该视口的数据的长度（以条目数表示）。
返回值
number

getElementRef

获取视口的 ElementRef。
返回值
ElementRef<HTMLElement>

getOffsetToRenderedContentStart

获取从视口起点到渲染数据起始位置的偏移量（以像素为单位）。
返回值
number | null

getRenderedRange

获取当前渲染的条目范围。
返回值
ListRange

getViewportSize

获取视口的大小（以像素为单位）。
返回值
number

measureBoundingClientRectWithScrollOffset
参数

from

"top" | "bottom" | "left" | "right"

返回值
number

measureRangeSize

测量指定范围的总组合大小。如果该范围包含未渲染的条目，则抛出此异常。
参数

range

ListRange

返回值
number

measureRenderedContentSize

测量所有渲染条目的组合大小。
返回值
number

measureScrollOffset

从可滚动区的开头得到当前的滚动偏移量（以像素为单位）。
参数

from ?

"top" | "bottom" | "start" | "end" | "left" | "right"

测量到边缘的偏移。在垂直模式下默认为 “top”，在水平模式下默认为 “start”。
返回值
number

measureViewportOffset

测量视口相对于滚动容器的偏移量
参数

from ?

"top" | "bottom" | "start" | "end" | "left" | "right"

要测量的边缘。
measureViewportSize

测量给定方向的视口大小。
参数

orientation

"vertical" | "horizontal"

测量尺寸的方向。
scrollTo

滚动到指定的偏移量。这是浏览器原生 scrollTo 方法的标准化版本，因为各个浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 对于此方法，无论布局方向如何，左右都总是指向滚动容器的左侧和右侧。start 和 end 在 LTR 上下文中分别指向左右，在 RTL 上下文中则相反。
参数

options

ExtendedScrollToOptions

指定要滚动到的偏移量。
scrollToIndex

滚动到指定索引处的偏移量。
参数

index

number

要滚动的元素的索引。

behavior

ScrollBehavior = 'auto'

滚动时要使用的 ScrollBehavior。行为默认是 auto。
scrollToOffset

从视口开始处滚动到指定的偏移量。请注意，这并不会总是与设置 scrollTop 或 scrollLeft 一致。在水平视口中，视图是从右向左的方向，这相当于设置了一个虚构的 scrollRight 属性。
参数

offset

number

要滚动到的偏移量。

behavior

ScrollBehavior = 'auto'

滚动时要使用的 ScrollBehavior。行为默认是 auto。
setRenderedContentOffset

设置从视口起点到渲染数据起点或终点的偏移量（以像素为单位）。
参数

offset

number

to

"to-start" | "to-end" = 'to-start'

setRenderedRange

设置当前渲染的索引范围。
参数

range

ListRange

setTotalContentSize

设置所有内容的总大小（以像素为单位），包括当前未渲染的内容。
参数

size

number

为附着到的元素提供一个虚拟可滚动。

选择器： [cdkVirtualScrollingElement]

方法
elementScrolled

返回在宿主元素上发生 scroll 事件时会触发的可观察对象。
返回值
Observable<Event>

getElementRef

获取视口的 ElementRef。
返回值
ElementRef<HTMLElement>

measureBoundingClientRectWithScrollOffset
参数

from

"top" | "bottom" | "left" | "right"

返回值
number

measureScrollOffset

测量相对于视口指定边缘的滚动偏移量。这个方法可以用来代替对 scrollLeft 或 scrollTop 的直接检查，因为各浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 该方法返回的值是标准化的，左右都总是指向滚动容器的左侧和右侧，与布局方向无关。start 和 end 在 LTR 上下文中指向左右，在 RTL 上下文则相反。
参数

from

"top" | "bottom" | "start" | "end" | "left" | "right"

要测量的边缘。
返回值
number

measureViewportSize

测量给定方向的视口大小。
参数

orientation

"vertical" | "horizontal"

测量尺寸的方向。
scrollTo

滚动到指定的偏移量。这是浏览器原生 scrollTo 方法的标准化版本，因为各个浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 对于此方法，无论布局方向如何，左右都总是指向滚动容器的左侧和右侧。start 和 end 在 LTR 上下文中分别指向左右，在 RTL 上下文中则相反。
参数

options

ExtendedScrollToOptions

指定要滚动到的偏移量。

为全局/窗口滚动条提供虚拟可滚动。

选择器： cdk-virtual-scroll-viewport[scrollWindow]

方法
elementScrolled

返回在宿主元素上发生 scroll 事件时会触发的可观察对象。
返回值
Observable<Event>

getElementRef

获取视口的 ElementRef。
返回值
ElementRef<HTMLElement>

measureBoundingClientRectWithScrollOffset
参数

from

"top" | "bottom" | "left" | "right"

返回值
number

measureScrollOffset

测量相对于视口指定边缘的滚动偏移量。这个方法可以用来代替对 scrollLeft 或 scrollTop 的直接检查，因为各浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 该方法返回的值是标准化的，左右都总是指向滚动容器的左侧和右侧，与布局方向无关。start 和 end 在 LTR 上下文中指向左右，在 RTL 上下文则相反。
参数

from

"top" | "bottom" | "start" | "end" | "left" | "right"

要测量的边缘。
返回值
number

measureViewportSize

测量给定方向的视口大小。
参数

orientation

"vertical" | "horizontal"

测量尺寸的方向。
scrollTo

滚动到指定的偏移量。这是浏览器原生 scrollTo 方法的标准化版本，因为各个浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 对于此方法，无论布局方向如何，左右都总是指向滚动容器的左侧和右侧。start 和 end 在 LTR 上下文中分别指向左右，在 RTL 上下文中则相反。
参数

options

ExtendedScrollToOptions

指定要滚动到的偏移量。

具有固定大小已知条目列表的虚拟滚动策略。

方法
attach

把这个滚动策略附着到视口中。
参数

viewport

CdkVirtualScrollViewport

要把此策略附着到的视口。
detach

这个滚动策略是从当前连接的视口中拆除出来的。
scrollToIndex

滚动到指定索引的偏移量。
参数

index

number

要滚动的元素的索引。

behavior

ScrollBehavior

滚动时要使用的 ScrollBehavior。
updateItemAndBufferSize

更新条目大小和缓冲区大小。
参数

itemSize

number

虚拟滚动列表中各条目的大小。

minBufferPx

number

在需要渲染更多内容之前，缓冲区的最小量（以像素为单位）

maxBufferPx

number

渲染时要渲染的缓冲区（以像素为单位）。

扩展 {@link CdkScrollable} 以用作虚拟滚动的滚动容器。

方法
elementScrolled

返回在宿主元素上发生 scroll 事件时会触发的可观察对象。
返回值
Observable<Event>

getElementRef

获取视口的 ElementRef。
返回值
ElementRef<HTMLElement>

measureBoundingClientRectWithScrollOffset

测量包含滚动偏移量的边界 DOMRect 大小。
参数

from

"top" | "bottom" | "left" | "right"

要测量的边缘。
返回值
number

measureScrollOffset

测量相对于视口指定边缘的滚动偏移量。这个方法可以用来代替对 scrollLeft 或 scrollTop 的直接检查，因为各浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 该方法返回的值是标准化的，左右都总是指向滚动容器的左侧和右侧，与布局方向无关。start 和 end 在 LTR 上下文中指向左右，在 RTL 上下文则相反。
参数

from

"top" | "bottom" | "start" | "end" | "left" | "right"

要测量的边缘。
返回值
number

measureViewportSize

测量给定方向的视口大小。
参数

orientation

"vertical" | "horizontal"

测量尺寸的方向。
scrollTo

滚动到指定的偏移量。这是浏览器原生 scrollTo 方法的标准化版本，因为各个浏览器对于 scrollLeft 在 RTL 中的理解并不一致。 对于此方法，无论布局方向如何，左右都总是指向滚动容器的左侧和右侧。start 和 end 在 LTR 上下文中分别指向左右，在 RTL 上下文中则相反。
参数

options

ExtendedScrollToOptions

指定要滚动到的偏移量。

在每个方向上保存视口滚动位置的对象。

属性
名称 描述

left: number

top: number

该策略决定了应该在视口中渲染哪些条目。

属性
名称 描述

scrolledIndexChange: Observable<number>

当视口中可见的第一个元素的索引发生变化时触发。
方法
attach

把这个滚动策略附着到视口中。
参数

viewport

CdkVirtualScrollViewport

要把此策略附着到的视口。
detach

这个滚动策略是从当前连接的视口中拆除出来的。
onContentRendered

当 DOM 中渲染的条目范围发生变化时调用。
onContentScrolled

在视口发生滚动时调用（使用 requestAnimationFrame 来防抖）。
onDataLengthChanged

当数据长度发生变化时调用。
onRenderedOffsetChanged

当渲染条目的偏移量发生变化时调用。
scrollToIndex

滚动到指定索引的偏移量。
参数

index

number

要滚动的元素的索引。

behavior

ScrollBehavior

滚动时要使用的 ScrollBehavior。

要被 VirtualScrollViewport 重复的条目

属性
名称 描述

dataStream: Observable<readonly T[]>

方法
measureRangeSize
参数

range

ListRange

orientation

"vertical" | "horizontal"

返回值
number

ScrollToOptions 的扩展版本，允许表达相对于视口顶部、底部、左侧、右侧、开头或结尾的滚动偏移量，而不仅仅是顶部和左侧。 请注意：top 和 bottom 属性是互斥的，left 和 right、start 和 end 属性也是如此。

type ExtendedScrollToOptions = _XAxis & _YAxis & ScrollOptions;

CdkVirtualForOf 渲染的条目的上下文

type CdkVirtualForOfContext = {
    $implicit: T;
    cdkVirtualForOf: DataSource<T> | Observable<T[]> | NgIterable<T>;
    index: number;
    count: number;
    first: boolean;
    last: boolean;
    even: boolean;
    odd: boolean;
};

默认情况下以毫秒为单位的时间来限制滚动事件的频度。

const DEFAULT_SCROLL_TIME: 20;

resize 事件的默认节流时间（毫秒数）。

const DEFAULT_RESIZE_TIME: 20;

这个注入令牌用来指定虚拟滚动策略。

const VIRTUAL_SCROLL_STRATEGY: InjectionToken<VirtualScrollStrategy>;

const VIRTUAL_SCROLLABLE: InjectionToken<CdkVirtualScrollable>;