Angular Material

Angular CDK overlay API 参考文档

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

服务

`Overlay`

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

Service to create Overlays. Overlays are dynamically added pieces of floating UI, meant to be used as a low-level building block for other components. Dialogs, tooltips, menus, selects, etc. can all be built using overlays. The service should primarily be used by authors of re-usable components rather than developers building end-user applications.

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

An overlay is a PortalOutlet, so any kind of Portal can be loaded into one.

属性

名称	描述
`scrollStrategies: ScrollStrategyOptions`	Scrolling strategies that can be used when creating an overlay.

方法

create
创建一个浮层。 Creates an overlay.
参数 Parameters
config? `OverlayConfig`	应用于浮层的配置。 Configuration applied to the overlay.
返回值 Returns
`OverlayRef`	所创建浮层的引用。 Reference to the created overlay.

position

position
获取一个位置构建器，可以通过流式 API 来构建和配置定位策略。 Gets a position builder that can be used, via fluent API, to construct and configure a position strategy.
`OverlayPositionBuilder`	浮层位置构建器。 An overlay position builder.

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

Gets a position builder that can be used, via fluent API, to construct and configure a position strategy.

返回值

Returns

OverlayPositionBuilder

浮层位置构建器。

An overlay position builder.

`OverlayContainer`

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

Container inside which all overlays will render.

方法

getContainerElement

getContainerElement
该方法返回浮层的容器元素。它会在第一次调用时惰性创建该元素，以便在非浏览器环境中使用该容器。 This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.
`HTMLElement`	容器元素 the container element

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

This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.

返回值

Returns

HTMLElement

容器元素

the container element

`FullscreenOverlayContainer` extends OverlayContainer

OverlayContainer 的替代品，支持在全屏模式（https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen）下正确显示浮层元素

Alternative to OverlayContainer that supports correct displaying of overlay elements in Fullscreen mode https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullScreen

应该在根组件中提供。

Should be provided in the root component.

方法

getContainerElement

getContainerElement
该方法返回浮层的容器元素。它会在第一次调用时惰性创建该元素，以便在非浏览器环境中使用该容器。 This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.
`HTMLElement`	容器元素 the container element

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

This method returns the overlay container element. It will lazily create the element the first time it is called to facilitate using the container in non-browser environments.

返回值

Returns

HTMLElement

容器元素

the container element

getFullscreenElement

getFullscreenElement
当页面进入全屏模式时，会指定一个元素。在全屏模式下，只能看到该元素及其子元素。 When the page is put into fullscreen mode, a specific element is specified. Only that element and its children are visible when in fullscreen mode.
`Element`

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

When the page is put into fullscreen mode, a specific element is specified. Only that element and its children are visible when in fullscreen mode.

返回值

Returns

Element

`OverlayPositionBuilder`

浮层定位策略生成器。

Builder for overlay position strategy.

方法

flexibleConnectedTo
创建灵活定位策略。 Creates a flexible position strategy.
参数 Parameters
origin `FlexibleConnectedPositionStrategyOrigin`	浮层定位相对的原点。 Origin relative to which to position the overlay.
返回值 Returns
`FlexibleConnectedPositionStrategy`

global

global
创建全局定位策略。 Creates a global position strategy.
`GlobalPositionStrategy`

创建全局定位策略。

Creates a global position strategy.

返回值

Returns

GlobalPositionStrategy

已弃用 connectedTo
创建相对定位策略。 Creates a relative position strategy.
参数 Parameters
elementRef `ElementRef<any>`
originPos `OriginConnectionPosition`
overlayPos `OverlayConnectionPosition`
返回值 Returns
`ConnectedPositionStrategy`

`ScrollStrategyOptions`

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

Options for how an overlay will handle scrolling.

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

Users can provide a custom value for ScrollStrategyOptions to replace the default behaviors. This class primarily acts as a factory for ScrollStrategy instances.

属性

名称	描述
`block: () => new BlockScrollStrategy(this._viewportRuler, this._document)`	块滚动。 Block scrolling.
`close: (config?: CloseScrollStrategyConfig) => new CloseScrollStrategy(this._scrollDispatcher, this._ngZone, this._viewportRuler, config)`	用户滚动后立即关闭浮层。 Close the overlay as soon as the user scrolls.
`noop: () => new NoopScrollStrategy()`	滚动时不执行任何操作。 Do nothing on scroll.
`reposition: (config?: RepositionScrollStrategyConfig) => new RepositionScrollStrategy(this._scrollDispatcher, this._viewportRuler, this._ngZone, config)`	更新浮层在滚动条上的位置。 Update the overlay's position on scroll.

`OverlayOutsideClickDispatcher`

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

Service for dispatching mouse click events that land on the body to appropriate overlay ref, if any. It maintains a list of attached overlays to determine best suited overlay based on event target and order of overlay opens.

方法

add

add
将新的浮层添加到已附加的浮层引用列表中。 Add a new overlay to the list of attached overlay refs.
overlayRef `OverlayReference`

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

Add a new overlay to the list of attached overlay refs.

参数

Parameters

overlayRef

OverlayReference

detach
拆除全局键盘事件侦听器。 Detaches the global keyboard event listener.

detach

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

Detaches the global keyboard event listener.

remove

remove
overlayRef `OverlayReference`

参数

Parameters

overlayRef

OverlayReference

`OverlayKeyboardDispatcher`

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

Service for dispatching keyboard events that land on the body to appropriate overlay ref, if any. It maintains a list of attached overlays to determine best suited overlay based on event target and order of overlay opens.

方法

add

add
将新的浮层添加到已附加的浮层引用列表中。 Add a new overlay to the list of attached overlay refs.
overlayRef `OverlayReference`

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

Add a new overlay to the list of attached overlay refs.

参数

Parameters

overlayRef

OverlayReference

detach
拆除全局键盘事件侦听器。 Detaches the global keyboard event listener.

detach

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

Detaches the global keyboard event listener.

remove

remove
overlayRef `OverlayReference`

参数

Parameters

overlayRef

OverlayReference

指令

`CdkOverlayOrigin`

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

Directive applied to an element to make it usable as an origin for an Overlay using a ConnectedPositionStrategy.

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

导出为： cdkOverlayOrigin

属性

名称	描述
`elementRef: ElementRef`	Reference to the element on which the directive is applied.

`CdkConnectedOverlay`

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

Directive to facilitate declarative creation of an Overlay using a FlexibleConnectedPositionStrategy.

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

导出为： cdkConnectedOverlay

属性

名称	描述
@Input('cdkConnectedOverlayBackdropClass') `backdropClass: string`	在背景板元素上设置的自定义类。 The custom class to be set on the backdrop element.
@Input('cdkConnectedOverlayDisableClose') `disableClose: boolean`	浮层是否可以通过用户交互来关闭。 Whether the overlay can be closed by user interaction.
@Input('cdkConnectedOverlayFlexibleDimensions') `flexibleDimensions: boolean`	浮层的宽度和高度是否可以约束在当前视口中。 Whether the overlay's width and height can be constrained to fit within the viewport.
@Input('cdkConnectedOverlayGrowAfterOpen') `growAfterOpen: boolean`	当弹性定位打开时，浮层是否能在首次打开后扩大。 Whether the overlay can grow after the initial open when flexible positioning is turned on.
@Input('cdkConnectedOverlayHasBackdrop') `hasBackdrop: any`	浮层是否应带有背景板。 Whether or not the overlay should attach a backdrop.
@Input('cdkConnectedOverlayHeight') `height: number \| string`	浮层面板的高度。 The height of the overlay panel.
@Input('cdkConnectedOverlayLockPosition') `lockPosition: any`	滚动时是否应该锁定浮层。 Whether or not the overlay should be locked when scrolling.
@Input('cdkConnectedOverlayMinHeight') `minHeight: number \| string`	浮层面板的最小高度。 The min height of the overlay panel.
@Input('cdkConnectedOverlayMinWidth') `minWidth: number \| string`	浮层面板的最小宽度。 The min width of the overlay panel.
@Input('cdkConnectedOverlayOffsetX') `offsetX: number`	浮层连接点在 x 轴上的像素偏移量 The offset in pixels for the overlay connection point on the x-axis
@Input('cdkConnectedOverlayOffsetY') `offsetY: number`	浮层连接点在 y 轴上的像素偏移量 The offset in pixels for the overlay connection point on the y-axis
@Input('cdkConnectedOverlayOpen') `open: boolean`	浮层是否已打开。 Whether the overlay is open.
@Input('cdkConnectedOverlayOrigin') `origin: CdkOverlayOrigin`	已连接浮层的原点。 Origin for the connected overlay.
@Input('cdkConnectedOverlayPanelClass') `panelClass: string \| string[]`	要添加到浮层面板元素中的自定义类。 The custom class to add to the overlay pane element.
@Input('cdkConnectedOverlayPositionStrategy') `positionStrategy: FlexibleConnectedPositionStrategy`	如果指定，该输入会改写输入属性 positions。它可以让用户传入任意的定位策略。 This input overrides the positions input if specified. It lets users pass in arbitrary positioning strategies.
@Input('cdkConnectedOverlayPositions') `positions: ConnectedPosition[]`	已注册的连接位置对。 Registered connected position pairs.
@Input('cdkConnectedOverlayPush') `push: boolean`	如果所提供的位置都不合适，是否可以在屏幕上往下压浮层。 Whether the overlay can be pushed on-screen if none of the provided positions fit.
@Input('cdkConnectedOverlayScrollStrategy') `scrollStrategy: ScrollStrategy`	在浮层完成时，处理 scroll 事件时要使用的策略。 Strategy to be used when handling scroll events while the overlay is open.
@Input('cdkConnectedOverlayTransformOriginOn') `transformOriginSelector: string`	用于设置变换原点的 CSS 选择器。 CSS selector which to set the transform origin.
@Input('cdkConnectedOverlayViewportMargin') `viewportMargin: number`	浮层与视口边缘之间的边距。 Margin between the overlay and the viewport edges.
@Input('cdkConnectedOverlayWidth') `width: number \| string`	浮层面板的宽度。 The width of the overlay panel.
@Output() `attach: EventEmitter<void>`	连接浮层时会发出本事件。 Event emitted when the overlay has been attached.
@Output() `backdropClick: EventEmitter<MouseEvent>`	单击背景板时发出的事件。 Event emitted when the backdrop is clicked.
@Output() `detach: EventEmitter<void>`	解除浮层时会发出本事件。 Event emitted when the overlay has been detached.
@Output() `overlayKeydown: EventEmitter<KeyboardEvent>`	键盘事件的目标是本浮层会触发。 Emits when there are keyboard events that are targeted at the overlay.
@Output() `overlayOutsideClick: EventEmitter<MouseEvent>`	当本浮层的外部发生鼠标点击事件时会触发。 Emits when there are mouse outside click events that are targeted at the overlay.
@Output() `positionChange: EventEmitter<ConnectedOverlayPositionChange>`	当定位发生变化时会发出本事件。 Event emitted when the position has changed.
`dir: Direction`	元素的布局方向。 The element's layout direction.
`overlayRef: OverlayRef`	到关联的浮层引用。 The associated overlay reference.

类

`OverlayRef`

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

Reference to an overlay that has been created with the Overlay service. Used to manipulate or dispose of said overlay.

属性

名称描述

名称	描述
`backdropElement: HTMLElement \| null`	浮层的背景板 HTML 元素。 The overlay's backdrop HTML element.
`hostElement: HTMLElement`	面板元素周围的包装器。可用于高级定位，在这里，需要在浮层面板周围使用具有特定样式的包装器。 Wrapper around the panel element. Can be used for advanced positioning where a wrapper with specific styling is required around the overlay pane.
`overlayElement: HTMLElement`	浮层的 HTML 元素 The overlay's HTML element

backdropElement: HTMLElement | null

浮层的背景板 HTML 元素。

The overlay's backdrop HTML element.

hostElement: HTMLElement

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

Wrapper around the panel element. Can be used for advanced positioning where a wrapper with specific styling is required around the overlay pane.

overlayElement: HTMLElement

浮层的 HTML 元素

The overlay's HTML element

方法

addPanelClass

addPanelClass
把一个或一组 CSS 类添加到浮层面板中。 Add a CSS class or an array of classes to the overlay pane.
classes `string \| string[]`

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

Add a CSS class or an array of classes to the overlay pane.

参数

Parameters

classes

string | string[]

attach
参数 Parameters
portal `ComponentPortal<T>`
返回值 Returns
`ComponentRef<T>`

attach
参数 Parameters
portal `TemplatePortal<T>`
返回值 Returns
`EmbeddedViewRef<T>`

attach
参数 Parameters
portal `any`
返回值 Returns
`any`

attachments

attachments
获取一个在附加浮层时会发出通知的可观察对象。 Gets an observable that emits when the overlay has been attached.
`Observable<void>`

获取一个在附加浮层时会发出通知的可观察对象。

Gets an observable that emits when the overlay has been attached.

返回值

Returns

Observable<void>

backdropClick

backdropClick
获取一个当单击背景时会发出通知的可观察对象。 Gets an observable that emits when the backdrop has been clicked.
`Observable<MouseEvent>`

获取一个当单击背景时会发出通知的可观察对象。

Gets an observable that emits when the backdrop has been clicked.

返回值

Returns

Observable<MouseEvent>

detach

detach
从浮层中拆除传送点。 Detaches an overlay from a portal.
`any`	拆除传送点的结果。 The portal detachment result.

从浮层中拆除传送点。

Detaches an overlay from a portal.

返回值

Returns

any

拆除传送点的结果。

The portal detachment result.

detachBackdrop
拆除与本浮层关联的背景板（如果有的话）。 Detaches the backdrop (if any) associated with the overlay.

detachBackdrop

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

Detaches the backdrop (if any) associated with the overlay.

detachments

detachments
获取一个当浮层已被拆除时会发出的可观察对象。 Gets an observable that emits when the overlay has been detached.
`Observable<void>`

获取一个当浮层已被拆除时会发出的可观察对象。

Gets an observable that emits when the overlay has been detached.

返回值

Returns

Observable<void>

dispose
清理 DOM 中的浮层。 Cleans up the overlay from the DOM.

dispose

清理 DOM 中的浮层。

Cleans up the overlay from the DOM.

getConfig

getConfig
获取当前的浮层配置，它是不可变对象。 Gets the current overlay configuration, which is immutable.
`OverlayConfig`

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

Gets the current overlay configuration, which is immutable.

返回值

Returns

OverlayConfig

getDirection

getDirection
返回浮层面板的布局方向。 Returns the layout direction of the overlay panel.
`Direction`

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

Returns the layout direction of the overlay panel.

返回值

Returns

Direction

hasAttached

hasAttached
浮层是否附加着内容。 Whether the overlay has attached content.
`boolean`

浮层是否附加着内容。

Whether the overlay has attached content.

返回值

Returns

boolean

keydownEvents

keydownEvents
获取一个以此浮层为目标的 keydown 事件的可观察对象。 Gets an observable of keydown events targeted to this overlay.
`Observable<KeyboardEvent>`

获取一个以此浮层为目标的 keydown 事件的可观察对象。

Gets an observable of keydown events targeted to this overlay.

返回值

Returns

Observable<KeyboardEvent>

outsidePointerEvents

outsidePointerEvents
获取一个此浮层之外的指针事件的可观察对象。 Gets an observable of pointer events targeted outside this overlay.
`Observable<MouseEvent>`

获取一个此浮层之外的指针事件的可观察对象。

Gets an observable of pointer events targeted outside this overlay.

返回值

Returns

Observable<MouseEvent>

removePanelClass

removePanelClass
从浮层面板中删除一个或一组 CSS 类。 Remove a CSS class or an array of classes from the overlay pane.
classes `string \| string[]`

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

Remove a CSS class or an array of classes from the overlay pane.

参数

Parameters

classes

string | string[]

setDirection

setDirection
设置浮层的 LTR/RTL 方向。 Sets the LTR/RTL direction for the overlay.
dir `"ltr" \| "rtl" \| Directionality`

设置浮层的 LTR/RTL 方向。

Sets the LTR/RTL direction for the overlay.

参数

Parameters

dir

"ltr" | "rtl" | Directionality

updatePosition
根据定位策略更新浮层的位置。 Updates the position of the overlay based on the position strategy.

updatePosition

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

Updates the position of the overlay based on the position strategy.

updatePositionStrategy

updatePositionStrategy
切换到新的定位策略并更新浮层的位置。 Switches to a new position strategy and updates the overlay position.
strategy `PositionStrategy`

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

Switches to a new position strategy and updates the overlay position.

参数

Parameters

strategy

PositionStrategy

updateScrollStrategy

updateScrollStrategy
切换到新的滚动策略。 Switches to a new scroll strategy.
strategy `ScrollStrategy`

切换到新的滚动策略。

Switches to a new scroll strategy.

参数

Parameters

strategy

ScrollStrategy

updateSize

updateSize
更新浮层的大小属性。 Update the size properties of the overlay.
sizeConfig `OverlaySizeConfig`

更新浮层的大小属性。

Update the size properties of the overlay.

参数

Parameters

sizeConfig

OverlaySizeConfig

`GlobalPositionStrategy`

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

A strategy for positioning overlays. Using this strategy, an overlay is given an explicit position relative to the browser's viewport. We use flexbox, instead of transforms, in order to avoid issues with subpixel rendering which can cause the element to become blurry.

方法

attach

attach
overlayRef `OverlayReference`

参数

Parameters

overlayRef

OverlayReference

bottom
设置浮层的底部位置。清除任何先前设置的垂直位置。 Sets the bottom position of the overlay. Clears any previously set vertical position.
参数 Parameters
value `string = ''`	新的底部偏移量。 New bottom offset.
返回值 Returns
`this`

centerHorizontally
使浮层水平居中，并具有可选的偏移量。清除任何先前设置的水平位置。 Centers the overlay horizontally with an optional offset. Clears any previously set horizontal position.
参数 Parameters
offset `string = ''`	相对于水平中心的浮层偏移量。 Overlay offset from the horizontal center.
返回值 Returns
`this`

centerVertically
使浮层垂直居中，并带有可选的偏移量。清除任何先前设置的垂直位置。 Centers the overlay vertically with an optional offset. Clears any previously set vertical position.
参数 Parameters
offset `string = ''`	相对于垂直中心的浮层偏移量。 Overlay offset from the vertical center.
返回值 Returns
`this`

left
设置浮层的左侧位置。清除任何先前设置的水平位置。 Sets the left position of the overlay. Clears any previously set horizontal position.
参数 Parameters
value `string = ''`	新的左侧偏移量。 New left offset.
返回值 Returns
`this`

right
设置浮层的正确位置。清除任何先前设置的水平位置。 Sets the right position of the overlay. Clears any previously set horizontal position.
参数 Parameters
value `string = ''`	新的右侧偏移量。 New right offset.
返回值 Returns
`this`

top
设置浮层的顶部位置。清除任何先前设置的垂直位置。 Sets the top position of the overlay. Clears any previously set vertical position.
参数 Parameters
value `string = ''`	新的顶部偏移量。 New top offset.
返回值 Returns
`this`

已弃用 height
设置浮层高度并清除任何先前设置的高度。 Sets the overlay height and clears any previously set height.
参数 Parameters
value `string = ''`	浮层的新高度 New height for the overlay
返回值 Returns
`this`

已弃用 width
设置浮层宽度并清除任何先前设置的宽度。 Sets the overlay width and clears any previously set width.
参数 Parameters
value `string = ''`	浮层的新宽度 New width for the overlay
返回值 Returns
`this`

`ConnectedPositionStrategy`

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

A strategy for positioning overlays. Using this strategy, an overlay is given an implicit position relative to some origin element. The relative position is defined in terms of a point on the origin element that is connected to a point on the overlay element. For example, a basic dropdown is connecting the bottom-left corner of the origin to the top-left corner of the overlay.

已弃用

属性

名称描述

名称	描述
`onPositionChange: Observable<ConnectedOverlayPositionChange>`	连接点更改时发出事件。 Emits an event when the connection point changes.
`positions: ConnectionPositionPair[]`	首选位置的有序列表，从最高到最低。 Ordered list of preferred positions, from most to least desirable.

onPositionChange: Observable<ConnectedOverlayPositionChange>

连接点更改时发出事件。

Emits an event when the connection point changes.

positions: ConnectionPositionPair[]

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

Ordered list of preferred positions, from most to least desirable.

方法

attach

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

Attach this position strategy to an overlay.

参数

Parameters

overlayRef

OverlayReference

dispose

释放此定位策略使用的所有资源。

Disposes all resources used by the position strategy.

recalculateLastPosition

即使触发器在“首选位置”列表中更高的位置，也可以将带有触发器的浮层元素重定位到其最后计算出的位置。这样一来，无需更改面板方向即可重新对齐面板。

Re-positions the overlay element with the trigger in its last calculated position, even if a position higher in the "preferred positions" list would now fit. This allows one to re-align the panel without changing the orientation of the panel.

setOrigin
设置浮层的原点元素。 Sets the origin element, relative to which to position the overlay.
参数 Parameters
origin `ElementRef<any>`	到新原点元素的引用。 Reference to the new origin element.
返回值 Returns
`this`

withDirection
设置布局方向，以便可以调整浮层的位置以匹配它。 Sets the layout direction so the overlay's position can be adjusted to match.
参数 Parameters
dir `"ltr" \| "rtl"`	新的布局方向。 New layout direction.
返回值 Returns
`this`

withFallbackPosition
添加新的首选后备排名。 Adds a new preferred fallback position.
参数 Parameters
originPos `OriginConnectionPosition`
overlayPos `OverlayConnectionPosition`
offsetX? `number`
offsetY? `number`
返回值 Returns
`this`

withLockedPosition
设置浮层的位置在最初放置后是否应锁定。当浮层被锁定时，在重新应用位置时（例如，当用户滚动离开时），它不会尝试重新定位自身。 Sets whether the overlay's position should be locked in after it is positioned initially. When an overlay is locked in, it won't attempt to reposition itself when the position is re-applied (e.g. when the user scrolls away).
参数 Parameters
isLocked `boolean`	浮层是否应锁定。 Whether the overlay should locked in.
返回值 Returns
`this`

withOffsetX
设置浮层在 x 轴上的连接点的偏移量 Sets an offset for the overlay's connection point on the x-axis
参数 Parameters
offset `number`	X 轴上的新偏移量。 New offset in the X axis.
返回值 Returns
`this`

withOffsetY
设置浮层在 y 轴上的连接点的偏移量 Sets an offset for the overlay's connection point on the y-axis
参数 Parameters
offset `number`	New offset in the Y axis.
返回值 Returns
`this`

withPositions
用一组新的位置覆盖当前位置。 Overwrites the current set of positions with an array of new ones.
参数 Parameters
positions `ConnectionPositionPair[]`	要设置在本策略上的位置对。 Position pairs to be set on the strategy.
返回值 Returns
`this`

withScrollableContainers

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

Sets the list of Scrollable containers that host the origin element so that on reposition we can evaluate if it or the overlay has been clipped or outside view. Every Scrollable must be an ancestor element of the strategy's origin element.

参数

Parameters

scrollables

CdkScrollable[]

`FlexibleConnectedPositionStrategy`

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

A strategy for positioning overlays. Using this strategy, an overlay is given an implicit position relative some origin element. The relative position is defined in terms of a point on the origin element that is connected to a point on the overlay element. For example, a basic dropdown is connecting the bottom-left corner of the origin to the top-left corner of the overlay.

属性

名称描述

positionChanges: Observable<ConnectedOverlayPositionChange>

位置变化的可观察序列。

Observable sequence of position changes.

positions: ConnectionPositionPair[]

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

Ordered list of preferred positions, from most to least desirable.

方法

attach

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

Attaches this position strategy to an overlay.

参数

Parameters

overlayRef

OverlayReference

detach

dispose

元素销毁后进行清理。

Cleanup after the element gets destroyed.

reapplyLastPosition

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

This re-aligns the overlay element with the trigger in its last calculated position, even if a position higher in the "preferred positions" list would now fit. This allows one to re-align the panel without changing the orientation of the panel.

setOrigin
设置相对于此浮层位置的原点。使用元素原点可用于构建需要相对于触发器定位的组件（例如，下拉菜单或工具提示），从而让这个点可用于诸如上下文菜单等需要相对于用户指针处打开的情况。 Sets the origin, relative to which to position the overlay. Using an element origin is useful for building components that need to be positioned relatively to a trigger (e.g. dropdown menus or tooltips), whereas using a point can be used for cases like contextual menus which open relative to the user's pointer.
参数 Parameters
origin `FlexibleConnectedPositionStrategyOrigin`	新原点的引用。 Reference to the new origin.
返回值 Returns
`this`

withDefaultOffsetX
设置浮层在 x 轴上的连接点的默认偏移量。 Sets the default offset for the overlay's connection point on the x-axis.
参数 Parameters
offset `number`	X 轴上的新偏移量。 New offset in the X axis.
返回值 Returns
`this`

withDefaultOffsetY
设置浮层在 y 轴上的连接点的默认偏移量。 Sets the default offset for the overlay's connection point on the y-axis.
参数 Parameters
offset `number`	Y 轴上的新偏移量。 New offset in the Y axis.
返回值 Returns
`this`

withFlexibleDimensions
设置是否可以将浮层的宽度和高度限制为适合视口。 Sets whether the overlay's width and height can be constrained to fit within the viewport.
参数 Parameters
flexibleDimensions `boolean = true`
返回值 Returns
`this`

withGrowAfterOpen
设置浮层在初始打开后是否可以灵活的增加宽度/高度。 Sets whether the overlay can grow after the initial open via flexible width/height.
参数 Parameters
growAfterOpen `boolean = true`
返回值 Returns
`this`

withLockedPosition
设置浮层的位置在最初放置后是否应锁定。当浮层被锁定时，在重新应用位置时（例如，当用户滚动时），它不会尝试重新定位自身。 Sets whether the overlay's position should be locked in after it is positioned initially. When an overlay is locked in, it won't attempt to reposition itself when the position is re-applied (e.g. when the user scrolls away).
参数 Parameters
isLocked `boolean = true`	浮层是否应锁定。 Whether the overlay should locked in.
返回值 Returns
`this`

withPositions
添加新的首选位置。 Adds new preferred positions.
参数 Parameters
positions `ConnectedPosition[]`	此浮层的定位选项列表。 List of positions options for this overlay.
返回值 Returns
`this`

withPush
设置如果提供的位置都不适合，则是否可以在屏幕上推动浮层。 Sets whether the overlay can be pushed on-screen if none of the provided positions fit.
参数 Parameters
canPush `boolean = true`
返回值 Returns
`this`

withScrollableContainers
设置承载原点元素的可滚动容器列表，以便在重新定位时可以评估该元素或浮层是否已被裁剪或在外部视图。每个可滚动对象必须是此策略的原点元素的祖先。 Sets the list of Scrollable containers that host the origin element so that on reposition we can evaluate if it or the overlay has been clipped or outside view. Every Scrollable must be an ancestor element of the strategy's origin element.
参数 Parameters
scrollables `CdkScrollable[]`
返回值 Returns
`this`

withTransformOriginOn
配置定位策略应该把 `transform-origin` 设置为此浮层内的某些元素，具体取决于所要应用的当前位置。对于动画的原点要根据浮层的对齐方式而改变的情况，这很有用。 Configures that the position strategy should set a `transform-origin` on some elements inside the overlay, depending on the current position that is being applied. This is useful for the cases where the origin of an animation can change depending on the alignment of the overlay.
参数 Parameters
selector `string`	CSS 选择器，将用于查找要设置为形变原点的目标元素。 CSS selector that will be used to find the target elements onto which to set the transform origin.
返回值 Returns
`this`

withViewportMargin
设置浮层可以放置到视口边缘的最小距离。 Sets a minimum distance the overlay may be positioned to the edge of the viewport.
参数 Parameters
margin `number`	浮层和视口边缘之间的必要边距（以像素为单位）。 Required margin between the overlay and the viewport edge in pixels.
返回值 Returns
`this`

`OverlayConfig`

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

Initial configuration used when creating an overlay.

属性

名称	描述
`backdropClass: string \| string[]`	要添加到背景板的自定义类 Custom class to add to the backdrop
`direction: Direction \| Directionality`	浮层面板中文本的方向。如果 `Directionality` 实例，该浮层也会自动处理对其值的更改。 Direction of the text in the overlay panel. If a `Directionality` instance is passed in, the overlay will handle changes to its value automatically.
`disposeOnNavigation: boolean`	当用户在历史记录中往后退时，是否应该处理浮层。请注意，这通常不包括单击链接（除非用户正在使用 `HashLocationStrategy` ）。 Whether the overlay should be disposed of when the user goes backwards/forwards in history. Note that this usually doesn't include clicking on links (unless the user is using the `HashLocationStrategy`).
`hasBackdrop: boolean`	浮层是否有背景板。 Whether the overlay has a backdrop.
`height: number \| string`	浮层面板的高度。如果提供了数字，则假定单位是像素。 The height of the overlay panel. If a number is provided, pixel units are assumed.
`maxHeight: number \| string`	浮层面板的最大高度。如果提供了数字，则假定单位是像素。 The max-height of the overlay panel. If a number is provided, pixel units are assumed.
`maxWidth: number \| string`	浮层面板的最大宽度。如果提供了数字，则假定单位是像素。 The max-width of the overlay panel. If a number is provided, pixel units are assumed.
`minHeight: number \| string`	浮层面板的最小高度。如果提供了数字，则假定单位是像素。 The min-height of the overlay panel. If a number is provided, pixel units are assumed.
`minWidth: number \| string`	浮层面板的最小宽度。如果提供了数字，则假定单位是像素。 The min-width of the overlay panel. If a number is provided, pixel units are assumed.
`panelClass: string \| string[]`	要添加到浮层面板的自定义类。 Custom class to add to the overlay pane.
`positionStrategy: PositionStrategy`	用于定位浮层的策略。 Strategy with which to position the overlay.
`scrollStrategy: ScrollStrategy`	在浮层完成时，处理 scroll 事件时要使用的策略。 Strategy to be used when handling scroll events while the overlay is open.
`width: number \| string`	浮层面板的宽度。如果提供了数字，则假定单位是像素。 The width of the overlay panel. If a number is provided, pixel units are assumed.

`ConnectionPositionPair`

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

The points of the origin element and the overlay element to connect.

属性

名称	描述
`offsetX: number`	Offset along the X axis.
`offsetY: number`	Offset along the Y axis.
`originX: HorizontalConnectionPos`	已连接浮层原点的 X 轴连接点。可以是 'start'、'end' 或 'center'。 X-axis attachment point for connected overlay origin. Can be 'start', 'end', or 'center'.
`originY: VerticalConnectionPos`	已连接浮层原点的 Y 轴连接点。可以是 'top'、'bottom' 或 'center'。 Y-axis attachment point for connected overlay origin. Can be 'top', 'bottom', or 'center'.
`overlayX: HorizontalConnectionPos`	已连接浮层原点的 X 轴连接点。可以是 'start'、'end' 或 'center'。 X-axis attachment point for connected overlay. Can be 'start', 'end', or 'center'.
`overlayY: VerticalConnectionPos`	已连接浮层原点的 Y 轴连接点。可以是 'top'、'bottom' 或 'center'。 Y-axis attachment point for connected overlay. Can be 'top', 'bottom', or 'center'.
`panelClass: string \| string[]`	Class(es) to be applied to the panel while this position is active.

`ConnectedOverlayPositionChange`

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

The change event emitted by the strategy when a fallback position is used.

属性

名称	描述
`connectionPair: ConnectionPositionPair`	The position used as a result of this change.

`RepositionScrollStrategy`

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

Strategy that will update the element position as the user is scrolling.

方法

attach

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

Attaches this scroll strategy to an overlay.

参数

Parameters

overlayRef

OverlayReference

detach

disable

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

Disables repositioning of the attached overlay on scroll.

enable

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

Enables repositioning of the attached overlay on scroll.

`CloseScrollStrategy`

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

Strategy that will close the overlay as soon as the user starts scrolling.

方法

attach

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

Attaches this scroll strategy to an overlay.

参数

Parameters

overlayRef

OverlayReference

detach

disable

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

Disables the closing the attached overlay on scroll.

enable

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

Enables the closing of the attached overlay on scroll.

`NoopScrollStrategy`

什么也不做的滚动策略。

Scroll strategy that doesn't do anything.

方法

attach

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

Does nothing, as this scroll strategy is a no-op.

disable

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

Does nothing, as this scroll strategy is a no-op.

enable

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

Does nothing, as this scroll strategy is a no-op.

`BlockScrollStrategy`

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

Strategy that will prevent the user from scrolling while the overlay is visible.

方法

attach

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

Attaches this scroll strategy to an overlay.

disable

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

Unblocks page-level scroll while the attached overlay is open.

enable

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

Blocks page-level scroll while the attached overlay is open.

接口

`OverlaySizeConfig`

浮层的大小属性。

Size properties for an overlay.

属性

名称	描述
`height: number \| string`
`maxHeight: number \| string`
`maxWidth: number \| string`
`minHeight: number \| string`
`minWidth: number \| string`
`width: number \| string`

`PositionStrategy`

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

Strategy for setting the position on an overlay.

方法

apply

更新浮层元素的位置。

Updates the position of the overlay element.

attach

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

Attaches this position strategy to an overlay.

参数

Parameters

overlayRef

OverlayReference

detach

拆除浮层时调用。

Called when the overlay is detached.

dispose

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

Cleans up any DOM modifications made by the position strategy, if necessary.

`ConnectedPosition`

用户指定的连接位置。

A connected position as specified by the user.

属性

名称	描述
`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`

`OriginConnectionPosition`

原点元素上的连接点。

A connection point on the origin element.

属性

名称	描述
`originX: HorizontalConnectionPos`
`originY: VerticalConnectionPos`

`OverlayConnectionPosition`

浮层元素上的连接点。

A connection point on the overlay element.

属性

名称	描述
`overlayX: HorizontalConnectionPos`
`overlayY: VerticalConnectionPos`

`ScrollStrategy`

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

Describes a strategy that will be used by an overlay to handle scroll events while it is open.

属性

名称	描述
`attach: (overlayRef: OverlayReference) => void`	将此 `ScrollStrategy` 附加到浮层。 Attaches this `ScrollStrategy` to an overlay.
`detach: () => void`	从当前浮层拆除滚动策略。 Detaches the scroll strategy from the current overlay.
`disable: () => void`	禁用此滚动策略（当已附加的浮层从传送点 Portal 拆除时调用）。 Disable this scroll strategy (called when the attached overlay is detached from a portal).
`enable: () => void`	启用此滚动策略（将已附加的浮层附加到传送点 Portal 时调用）。 Enable this scroll strategy (called when the attached overlay is attached to a portal).

`RepositionScrollStrategyConfig`

RepositionScrollStrategy 的配置选项。

Config options for the RepositionScrollStrategy.

属性

名称描述

autoClose: boolean

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

Whether to close the overlay once the user has scrolled away completely.

scrollThrottle: number

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

Time in milliseconds to throttle the scroll events.

类型别名

`FlexibleConnectedPositionStrategyOrigin`

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

Possible values that can be set as the origin of a FlexibleConnectedPositionStrategy.

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

`HorizontalConnectionPos`

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

`VerticalConnectionPos`

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

Vertical dimension of a connection point on the perimeter of the origin or overlay element.

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

名称	描述
`height: number \| string`
`maxHeight: number \| string`
`maxWidth: number \| string`
`minHeight: number \| string`
`minWidth: number \| string`
`width: number \| string`

Angular CDK overlay API 参考文档

link 服务

link Overlay

属性

方法

link OverlayContainer

方法

link FullscreenOverlayContainer extends OverlayContainer

方法

link OverlayPositionBuilder

方法

link ScrollStrategyOptions

属性

link OverlayOutsideClickDispatcher

方法

link OverlayKeyboardDispatcher

方法

link 指令

link CdkOverlayOrigin

属性

link CdkConnectedOverlay

属性

link 类

link OverlayRef

属性

方法

link GlobalPositionStrategy

方法

link ConnectedPositionStrategy

属性

方法

link FlexibleConnectedPositionStrategy

属性

方法

link OverlayConfig

属性

link ConnectionPositionPair

属性

link ConnectedOverlayPositionChange

属性

link RepositionScrollStrategy

方法

link CloseScrollStrategy

方法

link NoopScrollStrategy

方法

link BlockScrollStrategy

方法

link 接口

link OverlaySizeConfig

属性

link PositionStrategy

方法

link ConnectedPosition

属性

link OriginConnectionPosition

属性

link OverlayConnectionPosition

属性

link ScrollStrategy

属性

link RepositionScrollStrategyConfig

属性

link 类型别名

link FlexibleConnectedPositionStrategyOrigin

link HorizontalConnectionPos

link VerticalConnectionPos

服务

`Overlay`

`OverlayContainer`

`FullscreenOverlayContainer` extends OverlayContainer

`OverlayPositionBuilder`

`ScrollStrategyOptions`

`OverlayOutsideClickDispatcher`

`OverlayKeyboardDispatcher`

指令

`CdkOverlayOrigin`

`CdkConnectedOverlay`

类

`OverlayRef`

`GlobalPositionStrategy`

`ConnectedPositionStrategy`

`FlexibleConnectedPositionStrategy`

`OverlayConfig`

`ConnectionPositionPair`

`ConnectedOverlayPositionChange`

`RepositionScrollStrategy`

`CloseScrollStrategy`

`NoopScrollStrategy`

`BlockScrollStrategy`

接口

`OverlaySizeConfig`

`PositionStrategy`

`ConnectedPosition`

`OriginConnectionPosition`

`OverlayConnectionPosition`

`ScrollStrategy`

`RepositionScrollStrategyConfig`

类型别名

`FlexibleConnectedPositionStrategyOrigin`

`HorizontalConnectionPos`

`VerticalConnectionPos`