Angular CDK 覆盖层 API 参考

import {OverlayModule} from '@angular/cdk/overlay';

用来创建浮层的服务。浮层是指动态添加的一些浮动用户界面，用来作为其它组件的底层构建块。像对话框、工具提示、菜单、选择器等等都可以用浮层来构建。该服务主要应该由可复用组件的作者使用，而不是供开发者构建最终用户应用。

浮层是一个 PortalOutlet，任何类型的传送点都可以加载到其中。

属性
名称 描述

scrollStrategies: ScrollStrategyOptions

创建浮层时要用到的滚动策略。
方法
create

创建一个浮层。
参数

配置 ?

OverlayConfig

应用于浮层的配置。
返回值
OverlayRef

所创建浮层的引用。
position

获取一个位置构建器，可以通过流式 API 来构建和配置定位策略。
返回值
OverlayPositionBuilder

浮层位置构建器。

所有浮层都会渲染到其中的容器。

方法
getContainerElement

该方法返回浮层的容器元素。它会在第一次调用时惰性创建该元素，以便在非浏览器环境中使用该容器。
返回值
HTMLElement

容器元素

覆盖容器的替代方案，支持在全屏模式下正确显示覆盖元素 https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen

应该在根组件中提供。

方法
getContainerElement

该方法返回浮层的容器元素。它会在第一次调用时惰性创建该元素，以便在非浏览器环境中使用该容器。
返回值
HTMLElement

容器元素
getFullscreenElement

当页面进入全屏模式时，会指定一个元素。在全屏模式下，只能看到该元素及其子元素。
返回值
Element

浮层定位策略生成器。

方法
flexibleConnectedTo

创建灵活定位策略。
参数

origin

FlexibleConnectedPositionStrategyOrigin

浮层定位相对的原点。
返回值
FlexibleConnectedPositionStrategy

global

创建全局定位策略。
返回值
GlobalPositionStrategy

规定浮层该如何处理滚动的选项。

用户可以为 ScrollStrategyOptions 提供自定义值，以替换默认行为。此类主要充当 ScrollStrategy 实例的工厂。

属性
名称 描述

block: () => new BlockScrollStrategy(this._viewportRuler, this._document)

阻止滚动。

close: (config?: CloseScrollStrategyConfig) => new CloseScrollStrategy(this._scrollDispatcher, this._ngZone, this._viewportRuler, config)

用户滚动后立即关闭浮层。

noop: () => new NoopScrollStrategy()

滚动时不执行任何操作。

reposition: (config?: RepositionScrollStrategyConfig) => new RepositionScrollStrategy(this._scrollDispatcher, this._viewportRuler, this._ngZone, config)

更新浮层在滚动条上的位置。

用于将鼠标单击事件落到适当的浮层引用（如果有）上的服务。它维护一个已附加的浮层列表，以便根据事件目标和浮层打开顺序确定最适合的浮层。

方法
add

将新的浮层添加到已附加的浮层引用列表中。
参数

overlayRef

OverlayRef

detach

拆除全局键盘事件侦听器。
remove

从已附加的浮层引用列表中删除浮层。
参数

overlayRef

OverlayRef

本服务用于将落在 body 上的键盘事件派发到适当的浮层引用（如果有）。它维护一个已附加的浮层列表，以便根据事件目标和浮层打开顺序确定最适合的浮层。

方法
add

将新的浮层添加到已附加的浮层引用列表中。
参数

overlayRef

OverlayRef

detach

拆除全局键盘事件侦听器。
remove

从已附加的浮层引用列表中删除浮层。
参数

overlayRef

OverlayRef

该指令应用于某个元素，以便在使用 ConnectedPositionStrategy 时可以作为 Overlay 的原点。

选择器： [cdk-overlay-origin] [overlay-origin] [cdkOverlayOrigin]

Exported as: cdkOverlayOrigin
属性
名称 描述

elementRef: ElementRef

对此指令要应用到的元素的引用。

该指令旨在帮助用 FlexibleConnectedPositionStrategy 声明式的创建一个浮层。

选择器： [cdk-connected-overlay] [connected-overlay] [cdkConnectedOverlay]

Exported as: cdkConnectedOverlay
属性
名称 描述
@Input('cdkConnectedOverlayBackdropClass')

backdropClass: string | string[]

在背景板元素上设置的自定义类。
@Input('cdkConnectedOverlayDisableClose')

disableClose: boolean

浮层是否可以通过用户交互来关闭。
@Input({ alias: 'cdkConnectedOverlayDisposeOnNavigation', transform: booleanAttribute })

disposeOnNavigation: boolean

当用户在历史记录中后退/前进时，是否应该销毁覆盖层。
@Input({ alias: 'cdkConnectedOverlayFlexibleDimensions', transform: booleanAttribute })

flexibleDimensions: boolean

浮层的宽度和高度是否可以约束在当前视口中。
@Input({ alias: 'cdkConnectedOverlayGrowAfterOpen', transform: booleanAttribute })

growAfterOpen: boolean

当弹性定位打开时，浮层是否能在首次打开后扩大。
@Input({ alias: 'cdkConnectedOverlayHasBackdrop', transform: booleanAttribute })

hasBackdrop: boolean

浮层是否应带有背景板。
@Input('cdkConnectedOverlayHeight')

height: number | string

浮层面板的高度。
@Input({ alias: 'cdkConnectedOverlayLockPosition', transform: booleanAttribute })

lockPosition: boolean

滚动时是否应该锁定浮层。
@Input('cdkConnectedOverlayMinHeight')

minHeight: number | string

浮层面板的最小高度。
@Input('cdkConnectedOverlayMinWidth')

minWidth: number | string

浮层面板的最小宽度。
@Input('cdkConnectedOverlayOffsetX')

offsetX: number

浮层连接点在 x 轴上的像素偏移量
@Input('cdkConnectedOverlayOffsetY')

offsetY: number

浮层连接点在 y 轴上的像素偏移量
@Input('cdkConnectedOverlayOpen')

open: boolean

浮层是否已打开。
@Input('cdkConnectedOverlayOrigin')

origin: CdkOverlayOrigin | FlexibleConnectedPositionStrategyOrigin

已连接浮层的原点。
@Input('cdkConnectedOverlayPanelClass')

panelClass: string | string[]

要添加到浮层面板元素中的自定义类。
@Input('cdkConnectedOverlayPositionStrategy')

positionStrategy: FlexibleConnectedPositionStrategy

如果指定，该输入会改写输入属性 positions。它可以让用户传入任意的定位策略。
@Input('cdkConnectedOverlayPositions')

positions: ConnectedPosition[]

已注册的连接位置对。
@Input({ alias: 'cdkConnectedOverlayPush', transform: booleanAttribute })

push: boolean

如果所提供的位置都不合适，是否可以在屏幕上往下压浮层。
@Input('cdkConnectedOverlayScrollStrategy')

scrollStrategy: ScrollStrategy

在浮层完成时，处理 scroll 事件时要使用的策略。
@Input('cdkConnectedOverlayTransformOriginOn')

transformOriginSelector: string

用于设置变换原点的 CSS 选择器。
@Input('cdkConnectedOverlayViewportMargin')

viewportMargin: number

浮层与视口边缘之间的边距。
@Input('cdkConnectedOverlayWidth')

width: number | string

浮层面板的宽度。
@Output()

attach: EventEmitter<void>

连接浮层时会发出本事件。
@Output()

backdropClick: EventEmitter<MouseEvent>

单击背景板时发出的事件。
@Output()

detach: EventEmitter<void>

解除浮层时会发出本事件。
@Output()

overlayKeydown: EventEmitter<KeyboardEvent>

键盘事件的目标是本浮层会触发。
@Output()

overlayOutsideClick: EventEmitter<MouseEvent>

当本浮层的外部发生鼠标点击事件时会触发。
@Output()

positionChange: EventEmitter<ConnectedOverlayPositionChange>

当定位发生变化时会发出本事件。

dir: Direction

元素的布局方向。

overlayRef: OverlayRef

到关联的浮层引用。

到使用浮层服务创建的浮层的引用。用来操纵或清除此浮层。

属性
名称 描述

backdropElement: HTMLElement | null

浮层的背景板 HTML 元素。

hostElement: HTMLElement

面板元素周围的包装器。可用于高级定位，在这里，需要在浮层面板周围使用具有特定样式的包装器。

overlayElement: HTMLElement

浮层的 HTML 元素
方法
addPanelClass

把一个或一组 CSS 类添加到浮层面板中。
参数

classes

string | string[]

attach
参数

portal

ComponentPortal<T>

返回值
ComponentRef<T>

attach
参数

portal

TemplatePortal<T>

返回值
EmbeddedViewRef<T>

attach
参数

portal

any

返回值
any

attachments

获取一个在附着浮层时会发出通知的可观察对象。
返回值
Observable<void>

backdropClick

获取一个当单击背景时会发出通知的可观察对象。
返回值
Observable<MouseEvent>

detach

从浮层中拆除传送点。
返回值
any

拆除传送点的结果。
detachBackdrop

拆除与本浮层关联的背景板（如果有的话）。
detachments

获取一个当浮层已被拆除时会发出的可观察对象。
返回值
Observable<void>

dispose

清理 DOM 中的浮层。
getConfig

获取当前的浮层配置，它是不可变对象。
返回值
OverlayConfig

getDirection

返回浮层面板的布局方向。
返回值
Direction

hasAttached

浮层是否附着着内容。
返回值
boolean

keydownEvents

获取一个以此浮层为目标的 keydown 事件的可观察对象。
返回值
Observable<KeyboardEvent>

outsidePointerEvents

获取一个此浮层之外的指针事件的可观察对象。
返回值
Observable<MouseEvent>

removePanelClass

从浮层面板中删除一个或一组 CSS 类。
参数

classes

string | string[]

setDirection

设置浮层的 LTR/RTL 方向。
参数

dir

Directionality | Direction

updatePosition

根据定位策略更新浮层的位置。
updatePositionStrategy

切换到新的定位策略并更新浮层的位置。
参数

strategy

PositionStrategy

updateScrollStrategy

切换到新的滚动策略。
参数

strategy

ScrollStrategy

updateSize

更新浮层的大小属性。
参数

sizeConfig

OverlaySizeConfig

放置浮层的策略。使用此策略，可以为浮层赋予相对于浏览器视口的显式位置。为了避免亚像素渲染可能导致元素变得模糊的问题，我们使用 flexbox 而不是变换。

方法
attach
参数

overlayRef

OverlayRef

bottom

设置浮层的底部位置。清除任何先前设置的垂直位置。
参数

value

string = ''

新的底部偏移量。
返回值
this

centerHorizontally

使浮层水平居中，并具有可选的偏移量。清除任何先前设置的水平位置。
参数

offset

string = ''

相对于水平中心的浮层偏移量。
返回值
this

centerVertically

使浮层垂直居中，并带有可选的偏移量。清除任何先前设置的垂直位置。
参数

offset

string = ''

相对于垂直中心的浮层偏移量。
返回值
this

end

将此浮层设置到视口的末端，具体取决于浮层的方向。这在 LTR 布局中位于右侧，在 RTL 中位于左侧。
参数

offset

从屏幕边缘偏移。

value

string = ''

返回值
this

left

设置浮层的左侧位置。清除任何先前设置的水平位置。
参数

value

string = ''

新的左侧偏移量。
返回值
this

right

设置浮层的正确位置。清除任何先前设置的水平位置。
参数

value

string = ''

新的右侧偏移量。
返回值
this

start

将此浮层设置为视口的始端，具体取决于浮层的方向。这在 LTR 布局中位于左侧，在 RTL 中位于右侧。
参数

offset

从屏幕边缘偏移。

value

string = ''

返回值
this

top

设置浮层的顶部位置。清除任何先前设置的垂直位置。
参数

value

string = ''

新的顶部偏移量。
返回值
this

已弃用
高度

设置浮层高度并清除任何先前设置的高度。
参数

value

string = ''

浮层的新高度
返回值
this

已弃用
宽度

设置浮层宽度并清除任何先前设置的宽度。
参数

value

string = ''

浮层的新宽度
返回值
this

放置浮层的策略。使用此策略，可以为浮层提供相对于某些原点元素的隐式位置。相对位置是根据与浮层元素上的点连接的原点元素上的点定义的。例如，一个基本的下拉列表将原点的左下角连接到浮层的左上角。

属性
名称 描述

positionChanges: Observable<ConnectedOverlayPositionChange>

位置变化的可观察序列。

positions: ConnectionPositionPair[]

首选位置的有序列表，从最高到最低。
方法
attach

将此定位策略附加到浮层。
参数

overlayRef

OverlayRef

detach
dispose

元素销毁后进行清理。
reapplyLastPosition

这将使浮层元素与触发器在其最后计算的位置处重新对齐，即使现在“首选位置”列表中的位置优先级较高也是如此。这样一来，无需更改面板方向即可重新对齐面板。
setOrigin

设置相对于此浮层位置的原点。使用元素原点可用于构建需要相对于触发器定位的组件（例如，下拉菜单或工具提示），从而让这个点可用于诸如上下文菜单等需要相对于用户指针处打开的情况。
参数

origin

FlexibleConnectedPositionStrategyOrigin

新原点的引用。
返回值
this

withDefaultOffsetX

设置浮层在 x 轴上的连接点的默认偏移量。
参数

offset

number

X 轴上的新偏移量。
返回值
this

withDefaultOffsetY

设置浮层在 y 轴上的连接点的默认偏移量。
参数

offset

number

Y 轴上的新偏移量。
返回值
this

withFlexibleDimensions

设置是否可以将浮层的宽度和高度限制为适合视口。
参数

flexibleDimensions

boolean = true

返回值
this

withGrowAfterOpen

设置浮层在初始打开后是否可以灵活的增加宽度/高度。
参数

growAfterOpen

boolean = true

返回值
this

withLockedPosition

设置浮层的位置在最初放置后是否应锁定。当浮层被锁定时，在重新应用位置时（例如，当用户滚动时），它不会尝试重新定位自身。
参数

isLocked

boolean = true

浮层是否应锁定。
返回值
this

withPositions

添加新的首选位置。
参数

positions

ConnectedPosition[]

此浮层的定位选项列表。
返回值
this

withPush

设置如果提供的位置都不适合，则是否可以在屏幕上推动浮层。
参数

canPush

boolean = true

返回值
this

withScrollableContainers

设置承载原点元素的可滚动容器列表，以便在重新定位时可以评估该元素或浮层是否已被裁剪或在外部视图。每个可滚动对象必须是此策略的原点元素的祖先。
参数

scrollables

CdkScrollable[]

返回值
this

withTransformOriginOn

配置定位策略应该把 transform-origin 设置为此浮层内的某些元素，具体取决于所要应用的当前位置。对于动画的原点要根据浮层的对齐方式而改变的情况，这很有用。
参数

selector

string

CSS 选择器，将用于查找要设置为形变原点的目标元素。
返回值
this

withViewportMargin

设置浮层可以放置到视口边缘的最小距离。
参数

margin

number

浮层和视口边缘之间的必要边距（以像素为单位）。
返回值
this

创建浮层时使用的初始配置。

属性
名称 描述

backdropClass: string | string[]

要添加到背景板的自定义类

direction: Direction | Directionality

浮层面板中文本的方向。如果 Directionality 实例，该浮层也会自动处理对其值的更改。

disposeOnNavigation: boolean

当用户在历史记录中往后退时，是否应该处理浮层。请注意，这通常不包括单击链接（除非用户正在使用 HashLocationStrategy ）。

hasBackdrop: boolean

浮层是否有背景板。

height: number | string

浮层面板的高度。如果提供了数字，则假定单位是像素。

maxHeight: number | string

浮层面板的最大高度。如果提供了数字，则假定单位是像素。

maxWidth: number | string

浮层面板的最大宽度。如果提供了数字，则假定单位是像素。

minHeight: number | string

浮层面板的最小高度。如果提供了数字，则假定单位是像素。

minWidth: number | string

浮层面板的最小宽度。如果提供了数字，则假定单位是像素。

panelClass: string | string[]

要添加到浮层面板的自定义类。

positionStrategy: PositionStrategy

用于定位浮层的策略。

scrollStrategy: ScrollStrategy

在浮层完成时，处理 scroll 事件时要使用的策略。

width: number | string

浮层面板的宽度。如果提供了数字，则假定单位是像素。

要连接的原点元素和浮层元素上的点。

属性
名称 描述

offsetX: number

X 轴上的偏移量。

offsetY: number

Y 轴上的偏移量。

originX: HorizontalConnectionPos

已连接浮层原点的 X 轴连接点。可以是 'start'、'end' 或 'center'。

originY: VerticalConnectionPos

已连接浮层原点的 Y 轴连接点。可以是 'top'、'bottom' 或 'center'。

overlayX: HorizontalConnectionPos

已连接浮层原点的 X 轴连接点。可以是 'start'、'end' 或 'center'。

overlayY: VerticalConnectionPos

已连接浮层原点的 Y 轴连接点。可以是 'top'、'bottom' 或 'center'。

panelClass: string | string[]

此位置处于活动状态时应用于面板的类。

使用回退位置时，本策略发出的更改事件。

属性
名称 描述

connectionPair: ConnectionPositionPair

本次更改的结果位置。

在用户滚动时更新元素位置的策略。

方法
attach

将此滚动策略附加到浮层。
参数

overlayRef

OverlayRef

detach
disable

禁止在滚动时重新定位浮层。
enable

允许在滚动时重新定位浮层。

用户开始滚动时关闭浮层的策略。

方法
attach

将此滚动策略附加到浮层。
参数

overlayRef

OverlayRef

detach
disable

禁用“滚动时关闭已附加浮层”。
enable

启用“滚动时关闭已附加浮层”。

什么也不做的滚动策略。

方法
attach

什么也不做，因为这个滚动策略就是如此。
disable

什么也不做，因为这个滚动策略就是如此。
enable

什么也不做，因为这个滚动策略就是如此。

可以在浮层可见时阻止用户滚动的策略。

方法
attach

将此滚动策略附加到浮层。
disable

打开已附加的浮层时，取消阻止页面级滚动。
enable

打开已附加的浮层时阻止页面级滚动。

浮层的大小属性。

属性
名称 描述

height: number | string

maxHeight: number | string

maxWidth: number | string

minHeight: number | string

minWidth: number | string

width: number | string

在浮层上设置位置的策略。

方法
apply

更新浮层元素的位置。
attach

将此定位策略附加到浮层。
参数

overlayRef

OverlayRef

detach

拆除浮层时调用。
dispose

如有必要，清除定位策略进行的所有 DOM 修改。

用户指定的连接位置。

属性
名称 描述

offsetX: number

offsetY: number

originX: 'start' | 'center' | 'end'

originY: 'top' | 'center' | 'bottom'

overlayX: 'start' | 'center' | 'end'

overlayY: 'top' | 'center' | 'bottom'

panelClass: string | string[]

weight: number

原点元素上的连接点。

属性
名称 描述

originX: HorizontalConnectionPos

originY: VerticalConnectionPos

浮层元素上的连接点。

属性
名称 描述

overlayX: HorizontalConnectionPos

overlayY: VerticalConnectionPos

描述一种策略，浮层在打开时将用它处理滚动事件。

属性
名称 描述

attach: (overlayRef: OverlayRef) => void

将此 ScrollStrategy 附加到浮层。

detach: () => void

从当前浮层拆除滚动策略。

disable: () => void

禁用此滚动策略（当已附加的浮层从传送点 Portal 拆除时调用）。

enable: () => void

启用此滚动策略（将已附加的浮层附加到传送点 Portal 时调用）。

RepositionScrollStrategy 的配置选项。

属性
名称 描述

autoClose: boolean

用户完全滚动离开后是否关闭浮层。

scrollThrottle: number

滚动事件的限流时间（以毫秒为单位）。

可以设置为 FlexibleConnectedPositionStrategy 原点的可能值。

type FlexibleConnectedPositionStrategyOrigin = ElementRef | Element | (Point & {
    width?: number;
    height?: number;
});

原点或浮层元素周边连接点的水平尺寸。

type HorizontalConnectionPos = 'start' | 'center' | 'end';

在原点周边或浮层元素上的连接点的垂直规格。

type VerticalConnectionPos = 'top' | 'center' | 'bottom';

const STANDARD_DROPDOWN_ADJACENT_POSITIONS: ConnectedPosition[];

const STANDARD_DROPDOWN_BELOW_POSITIONS: ConnectedPosition[];