Dialog

Dialog

[toc]

概述

OVERVIEW

使用MatDialog服务,可以打开包含Material Design样式与动画的对话框。

The MatDialog service can be used to open modal dialogs with Material Design styling and animations.

传入一个需要加载的组件和可选配置对象,调用open方法可以打开对话框。open方法将返回一个MatDialogRef实例。

A dialog is opened by calling the open method with a component to be loaded and an optional config object. The open method will return an instance of MatDialogRef:

let dialogRef = dialog.open(UserProfileComponent, {
  height: '400px',
  width: '600px',
});

MatDialogRef提供了对已打开对话框的操作。可以用来关闭对话框,并在关闭后接收通知。

The MatDialogRef provides a handle on the opened dialog. It can be used to close the dialog and to receive notification when the dialog has been closed.

dialogRef.afterClosed().subscribe(result => {
  console.log(`Dialog result: ${result}`); // Pizza!
});

dialogRef.close('Pizza!');

MatDialog创建的组件可以注入MatDialogRef,并使用MatDialogRef关闭其包含的对话框。当对话框关闭时,可以提供一个可选结果值。这个结果值被转发为afterClosed promise的结果。

Components created via MatDialog can inject MatDialogRef and use it to close the dialog in which they are contained. When closing, an optional result value can be provided. This result value is forwarded as the result of the afterClosed promise.

@Component({/* ... */})
export class YourDialog {
  constructor(public dialogRef: MatDialogRef<YourDialog>) { }

  closeDialog() {
    this.dialogRef.close('Pizza!');
  }
}

用对话框组件共享数据

Sharing data with the Dialog component.

如果你想使用对话框共享数据,你可以使用data选项向对话框组件传入信息。

If you want to share data with your dialog, you can use the data option to pass information to the dialog component.

let dialogRef = dialog.open(YourDialog, {
  data: { name: 'austin' },
});

使用MAT_DIALOG_DATA注入token来访问对话框组件中的数据。

To access the data in your dialog component, you have to use the MAT_DIALOG_DATA injection token:

import {Component, Inject} from '@angular/core';
import {MAT_DIALOG_DATA} from '@angular/material';

@Component({
  selector: 'your-dialog',
  template: 'passed in {{ data.name }}',
})
export class YourDialog {
  constructor(@Inject(MAT_DIALOG_DATA) public data: any) { }
}

对话框内容

Dialog content

使用一些指令可以使你更容易地结构化对话框的内容。

Several directives are available to make it easier to structure your dialog content:

指令名 描述 Description
mat-dialog-title [属性]对话框标题设置为标题元素(例如<h1>, <h2>) [Attr] Dialog title, applied to a heading element (e.g., <h1>, <h2>)
<mat-dialog-content> 对话框的主体可滚动内容 Primary scrollable content of the dialog
<md-dialog-actions> 对话框底部的操作按钮容器 Container for action buttons at the bottom of the dialog
mat-dialog-close [属性]在<button>中添加,使按钮使用绑定的可选结果值来关闭对话框 [Attr] Added to a <button>, makes the button close the dialog with an optional result from the bound value.

例如:

For example:

<h2 mat-dialog-title>Delete all</h2>
<mat-dialog-content>Are you sure?</mat-dialog-content>
<mat-dialog-actions>
  <button mat-button mat-dialog-close>No</button>
  <!-- Can optionally provide a result for the closing dialog. -->
  <button mat-button [mat-dialog-close]="true">Yes</button>
</mat-dialog-actions>

当对话框打开时,焦点将会自动放在第一个可选择的元素上。

Once a dialog opens, the dialog will automatically focus the first tabbable element.

你可以通过设置tabindex属性,来控制元素在按tab时是否停下。

You can control which elements are tab stops with the tabindex attribute

<button mat-button tabindex="-1">Not Tabbable</button>

通过entryComponents设置对话框内容

Configuring dialog content via entryComponents

因为MatDialog在运行时实例化,Angular编译器需要更多信息来为你对话框内容组件创建必须的ComponentFactory

Because MatDialog instantiates components at run-time, the Angular compiler needs extra information to create the necessary ComponentFactory for your dialog content component.

对于对话框中加载的组件,必须先在NgModule定义的entryComponents列表中引入你的组件类,Angular编译器才会为其创建ComponentFactory

For any component loaded into a dialog, you must include your component class in the list of entryComponents in your NgModule definition so that the Angular compiler knows to create the ComponentFactory for it.

@NgModule({
  imports: [
    // ...
    MatDialogModule
  ],

  declarations: [
    AppComponent,
    ExampleDialogComponent
  ],

  entryComponents: [
    ExampleDialogComponent
  ],

  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule() {}

无障碍

Accessibility

默认每个对话框在其根元素中有role="dialog"。可在打开对话框时通过MatDialogConfig将role改为alertdialog

By default, each dialog has role="dialog" on the root element. The role can be changed to alertdialog via the MatDialogConfig when opening.

通过MatDialogConfig可以将aria-label, aria-labelledbyaria-describedby属性设置为对话框元素。每个对话框通常都应通过aria-labelaria-labelledby设置一个标签。

The aria-label, aria-labelledby, and aria-describedby attributes can all be set to the dialog element via the MatDialogConfig as well. Each dialog should typically have a label set via aria-label or aria-labelledby.

当对话框为打开状态时,可找到的第一个可获得焦点的元素,将获得焦点。为防止用户在后台改变焦点,Material对话框使用了一个焦点限制来保证焦点在其内部。当对话框关闭时,焦点将退回到打开对话框前的有焦点的元素上。

When a dialog is opened, it will move focus to the first focusable element that it can find. In order to prevent users from tabbing into elements in the background, the Material dialog uses a focus trap to contain focus within itself. Once a dialog is closed, it will return focus to the element that was focused before the dialog was opened.

焦点管理

Focus management

默认在对话框打开时,第一个可制表的元素可将获取焦点。

By default, the first tabbable element within the dialog will receive focus upon open.

在对话框元素中按tab可使焦点保持在其中,到达最后一个元素后,将跳转第一个元素。

Tabbing through the elements of the dialog will keep focus inside of the dialog element, wrapping back to the first tabbable element when reaching the end of the tab sequence.

键盘交互

Keyboard interaction

默认按Esc将关闭对话框。也可以通过disableClose选项触发此交互,用户通常应避免使用此方法,因为会打断屏幕阅读使用者的预期操作模式。

By default pressing the escape key will close the dialog. While this behavior can be turned off via the disableClose option, users should generally avoid doing so as it breaks the expected interaction pattern for screen-reader users.

API

对话框(dialog)的API参考

API reference for Angular Material dialog

import {MatDialogModule} from '@angular/material/dialog';

服务

Services

MatDialog

打开Material Design模态对话框的服务。

Service to open Material Design modal dialogs.

属性

Properties

属性名 描述 Description
afterAllClosed: Observable 当所有对话框都关闭后传递出的流。如果没有可打开的窗口时,将传递subscribe。 Stream that emits when all open dialog have finished closing. Will emit on subscribe if there are no open dialogs to begin with.
afterOpen: Subject<MatDialogRef> 当对话框打开时传递出的流。 Stream that emits when a dialog has been opened.
openDialogs: MatDialogRef[] 跟踪当前打开的对话框。 Keeps track of the currently-open dialogs.

方法

Methods

closeAll

  • 描述
    • 关闭所有当前已打开的对话框。
    • Closes all of the currently-open dialogs.

getDialogById

  • 描述
    • 根据id获取已打开的对话框。
    • Finds an open dialog by its id.
  • 参数
    • id: 用来查询对话框的ID
    • ID to use when looking up the dialog.
  • 返回
    • MatDialogRef | undefined

open

  • 描述
    • 打开包含指定组件的对话框。
    • Opens a modal dialog containing the given component.
  • 参数
    • componentOrTemplateRef:加载进对话框的组件类型,或者是作为对话框内容实例化的TemplateRef
    • Type of the component to load into the dialog, or a TemplateRef to instantiate as the dialog content.
    • config:附加设置。
    • Extra configuration options.
  • 返回
    • MatDialogRef:新打开的对话框参考。
    • Reference to the newly-opened dialog.

指令

Directives

MatDialogClose

关闭当前对话框的按钮。

Button that will close the current dialog.

Selector: button[mat-dialog-close] button[matDialogClose]

Exported as: matDialogClose

属性

Properties

属性名 描述 Description
@Input(‘aria-label’)
ariaLabel: string
按钮的屏幕阅读者标签。 Screenreader label for the button.
@Input(‘mat-dialog-close’)
dialogResult: any
对话框关闭输入。 Dialog close input.
dialogRef: MatDialogRef

MatDialogTitle

对话框元素的标题。当滚动时会固定在对话框顶部。

Title of a dialog element. Stays fixed to the top of the dialog when scrolling.

Selector: [mat-dialog-title] [matDialogTitle]

Exported as: matDialogTitle

属性

Properties

属性名 描述 Description
@Input()
id: mat-dialog-title-${dialogElementUid++}

MatDialogContent

对话框可滚动内容的容器。

Scrollable content container of a dialog.

Selector: [mat-dialog-content] mat-dialog-content [matDialogContent]

MatDialogActions

对话框底部交互按钮的容器。滚动时会固定在底部。

Container for the bottom action buttons in a dialog. Stays fixed to the bottom when scrolling.

Selector: [mat-dialog-actions] mat-dialog-actions [matDialogActions]

附加类

Additional classes

MatDialogConfig

使用MatDialog服务打开一个模态对话框的配置。

Configuration for opening a modal dialog with the MatDialog service.

属性

Properties

属性名 描述 Description
ariaDescribedBy: string | null 描述对话框的元素的id。 ID of the element that describes the dialog.
ariaLabel: string | null 指定对话框元素的Aria标签。 Aria label to assign to the dialog element
autoFocus: boolean 对话框打开的时候其中的元素是否自动获取焦点。 Whether the dialog should focus the first focusable element on open.
backdropClass: string 自定义背景类。 Custom class for the backdrop,
data: D | null 注入子组件的数据。 Data being injected into the child component.
direction: Direction 对话框内容的布局方向。 Layout direction for the dialog’s content.
disableClose: boolean 用户是否可以按Esc或者点击对话框外部来关闭一个对话框。 Whether the user can use escape or clicking outside to close a modal.
hasBackdrop: boolean 对话框是否有背景。 Whether the dialog has a backdrop.
height: string 对话框高度。 Height of the dialog.
id: string 对话框的ID,若省略,会自动生成唯一的id。 ID for the dialog. If omitted, a unique one will be generated.
maxHeight: number | string 对话框最大高度。默认单位是px。 Max-height of the dialog. If a number is provided, pixel units are assumed.
maxWidth: number | string 对话框最大宽度。单位是px。默认为80vw。 Max-width of the dialog. If a number is provided, pixel units are assumed. Defaults to 80vw
minHeight: number | string 对话框最小高度。默认单位是px。 Min-height of the dialog. If a number is provided, pixel units are assumed.
minWidth: number | string 对话框最小宽度。默认单位是px。 Min-width of the dialog. If a number is provided, pixel units are assumed.
panelClass: string string[] 遮盖面板的自定义类。|Custom class for the overlay pane.
position: DialogPosition 位置重载。 Position overrides.
role: DialogRole 对话框元素的ARIA角色。 The ARIA role the dialog element.
viewContainerRef: ViewContainerRef 定义所属的组件在Angular逻辑组件树的位置。将影响注入的那些可以使用,并改变对话框中已实例化组件的监测顺序。不影响对话框内容在哪里渲染。 Where the attached component should live in Angular’s logical component tree. This affects what is available for injection and the change detection order for the component instantiated inside of the dialog. This does not affect where the dialog content will be rendered.
width: string 对话框宽度。 Width of the dialog.

MatDialogRef

通过使用MatDialog服务打开的对话框的参考。

Reference to a dialog opened via the MatDialog service.

属性

Properties

属性名 描述 Description
componentInstance: T 对话框中的组件实例。 The instance of component opened into the dialog.
disableClose: this._containerInstance._config.disableClose 是否允许用户关闭对话框。 Whether the user is allowed to close the dialog.
id: string

方法

Methods

afterClosed

  • 描述
    • 当对话框完成关闭后,获取已通知的observable。
    • Gets an observable that is notified when the dialog is finished closing.
  • 返回
    • Observable

afterOpen

  • 描述
    • 当对话框打开完毕后,获取已通知的observable。
    • Gets an observable that is notified when the dialog is finished opening.
  • 返回
    • Observable

backdropClick

  • 描述
    • 当点击浮动背景时,获取传递的observable。
    • Gets an observable that emits when the overlay’s backdrop has been clicked.
  • 返回
    • Observable

beforeClose

  • 描述
    • 当对话框开始关闭是,获取已通知的observable。
    • Gets an observable that is notified when the dialog has started closing.
  • 返回
    • Observable

close

  • 描述
    • 关闭对话框。
    • Close the dialog.
  • 参数
    • dialogResult: 返回的可选择的结果。
    • Optional result to return to the dialog opener.

keydownEvents

  • 描述
    • 当针对浮动背景的按键事件触发时,获取传递的observable。
    • Gets an observable that emits when keydown events are targeted on the overlay.
  • 返回
    • Observable

updatePosition

  • 描述
    • 更新对话框位置。
    • Updates the dialog’s position.
  • 参数
    • position: 新对话框位置。
    • New dialog position.
  • 返回
    • this

updateSize

  • 描述
    • 更新对话框的宽度和高度。
    • Updates the dialog’s width and height.
  • 参数
    • width: 对话框的新宽度。
    • New width of the dialog.
    • height: 对话框的新高度。
    • New height of the dialog.
  • 返回
    • this

附加接口

Additional interfaces

DialogPosition

可以复写对话框的位置。

Possible overrides for a dialog’s position.

属性

Properties

属性名 描述 Description
bottom: string 复写对话框的底部位置。 Override for the dialog’s bottom position.
left: string 复写对话框的左边位置。 Override for the dialog’s left position.
right: string 复写对话框的右边位置。 Override for the dialog’s right position.
top: string 复写对话框的顶部位置。 Override for the dialog’s top position.

翻译部分版权归YahaCode团队所有。仅供学习研究之用,任何组织或个人不得私自以此用于任何形式的商业目的

你可能还想看看下面的内容?

发表评论