ion-modal
模态框是一种出现在应用内容之上的对话框，必须由应用关闭后才能恢复交互。当选项很多需要选择，或在列表中筛选项目时，它作为选择组件非常有用，同时也适用于许多其他使用场景。
🌐 A Modal is a dialog that appears on top of the app's content, and must be dismissed by the app before interaction can resume. It is useful as a select component when there are a lot of options to choose from, or when filtering items in a list, as well as many other use cases.
内嵌模态框（推荐）
🌐 Inline Modals (Recommended)
ion-modal 可以通过在模板中直接 编写组件来使用。这减少了你需要连接的处理程序数量，从而渲染模态框。
在将 ion-modal 与 Angular、React 或 Vue 一起使用时，传入的组件在模态框关闭时会被销毁。由于此功能由 JavaScript 框架提供，因此在没有 JavaScript 框架的情况下使用 ion-modal 不会销毁你传入的组件。如果这是所需的功能，我们建议使用 modalController。
🌐 When using ion-modal with Angular, React, or Vue, the component you pass in will be destroyed when the modal is dismissed. As this functionality is provided by the JavaScript framework, using ion-modal without a JavaScript framework will not destroy the component you passed in. If this is a needed functionality, we recommend using the modalController instead.
使用 isOpen
🌐 Using isOpen
ion-modal 上的 isOpen 属性允许开发者从他们的应用状态控制模态的显示状态。这意味着当 isOpen 被设置为 true 时，模态将被显示，而当 isOpen 被设置为 false 时，模态将被关闭。
🌐 The isOpen property on ion-modal allows developers to control the presentation state of the modal from their application state. This means when isOpen is set to true the modal will be presented and when isOpen is set to false the modal will be dismissed.
isOpen 使用单向数据绑定，这意味着在模态框关闭时它不会自动设置为 false。开发者应监听 ionModalDidDismiss 或 didDismiss 事件，并将 isOpen 设置为 false。这样做的原因是它可以防止 ion-modal 的内部实现与应用状态紧密耦合。使用单向数据绑定时，模态框只需要关心响应式变量提供的布尔值。使用双向数据绑定时，模态框不仅需要关心布尔值，还需要关心响应式变量本身的存在。这可能导致不可预测的行为，并使应用更难调试。
控制器模态
🌐 Controller Modals
使用 modalController，开发者可以以编程方式渲染 ion-modal。开发者将完全控制模态的显示和关闭时间。
🌐 With the modalController developers can present an ion-modal programmatically. Developers will have complete control over when a modal is presented and dismissed.
防止模态窗口关闭
🌐 Preventing a Modal from Dismissing
在向模态框输入数据时，通常希望有一种方式来防止意外的数据丢失。ion-modal 上的 canDismiss 属性使开发者能够控制何时允许模态框关闭。
🌐 When entering data into a modal, it is often desirable to have a way of preventing accidental data loss. The canDismiss property on ion-modal gives developers control over when a modal is allowed to dismiss.
有两种不同的使用 canDismiss 属性的方式：设置布尔值或设置回调函数。
🌐 There are two different ways of using the canDismiss property: setting a boolean value or setting a callback function.
注意：使用底部弹出模态时，如果没有设置 0 断点，滑动 时不会检查 canDismiss。但是，当按下 Esc 或硬件返回按钮时，它仍然会被检查。
设置布尔值
🌐 Setting a boolean value
开发者可以将 canDismiss 设置为布尔值。如果 canDismiss 为 true，则当用户尝试关闭模态框时，模态框将关闭。如果 canDismiss 为 false，则当用户尝试关闭模态框时，模态框将不会关闭。
🌐 Developers can set canDismiss to a boolean value. If canDismiss is true, then the modal will close when users attempt to dismiss the modal. If canDismiss is false, then the modal will not close when users attempt to dismiss the modal.
在需要在模态框被关闭之前强制执行特定操作时，应使用设置布尔值。例如，如果开发者希望在关闭模态框之前必须勾选“使用条款”复选框，他们可以最初将 canDismiss 设置为 false，并在复选框被选中时将其更新为 true。
🌐 Setting a boolean value should be used when you need to require a particular action to be taken prior to a modal being dismissed. For example, if developers want to require that a "Terms of Use" checkbox is checked prior to closing the modal, they could set canDismiss to false initially and update it to true when the checkbox is checked.
设置回调函数
🌐 Setting a callback function
开发者可以将 canDismiss 设置为一个函数。该函数必须返回一个 Promise，该 Promise 解析后结果为 true 或 false。如果 Promise 解析为 true，则模态框将关闭。如果 Promise 解析为 false，则模态框不会关闭。
🌐 Developers can set canDismiss to be a function. This function must return a Promise that resolves to either true or false. If the promise resolves to true, then the modal will dismiss. If the promise resolves to false, then the modal will not dismiss.
当你有复杂的关闭条件时，例如在关闭模态框之前显示确认对话框，应使用设置回调函数。用户在此对话框中选择的选项可以用来决定模态框是否应继续关闭。
🌐 Setting a callback function should be used when you have complex dismissing criteria such as showing a confirmation dialog prior to dismissing the modal. The option that users select in this dialog can then be used to determine whether or not the modal should proceed with dismissing.
请注意，设置回调函数会导致在使用卡片或表单模态时滑动手势被中断。这是因为 Ionic 无法提前知道你的回调函数将返回什么结果。
🌐 Note that setting a callback function will cause the swipe gesture to be interrupted when using a card or sheet modal. This is because Ionic does not know what your callback function will resolve to ahead of time.
防止滑动关闭
🌐 Prevent swipe to close
开发者可能希望防止用户通过滑动来关闭卡片或底部弹窗模态。可以通过为 canDismiss 设置回调函数，并检查 role 是否不是 gesture 来实现此功能。
🌐 Developers may want to prevent users from swiping to close a card or sheet modal. This can be done by setting a callback function for canDismiss and checking if the role is not gesture.
修改子组件中的关闭行为
🌐 Modifying dismiss behavior in child components
在某些情况下，开发者可能需要根据所展示的模态框的状态自定义 canDismiss 回调的行为。例如，当开发者希望如果模态框中的表单无效时防止模态框被关闭，这种自定义就特别有用。
🌐 In certain scenarios, developers may need to customize the behavior of the canDismiss callback based on the state of a presented modal. This customization can be particularly useful, for instance, when developers want to prevent the modal from being dismissed if a form within it is invalid.
为了实现这种自定义，子组件可以使用各种技术，例如函数回调、事件触发或其他响应机制，与父组件进行通信并更新控制 canDismiss 回调的条件。
🌐 To achieve this customization, child components can employ various techniques such as function callbacks, event emission, or other reactivity mechanisms to communicate with the parent component and update the conditions governing the canDismiss callback.
这是一个简化的示例，说明子组件如何与父组件交互以修改 canDismiss 回调：
🌐 Here's a simplified example illustrating how a child component can interact with a parent component to modify the canDismiss callback:
卡模态
🌐 Card Modal
开发者可以创建一个卡片模态效果，其中模态显示为堆叠在应用主内容上的卡片。要创建卡片模态，开发者需要在 ion-modal 上设置 presentingElement 属性。
🌐 Developers can create a card modal effect where the modal appears as a card stacked on top of your app's main content. To create a card modal, developers need to set the presentingElement property on ion-modal.
presentingElement 属性接受一个指向应在模态下显示的元素的引用。这通常是指向 ion-router-outlet 的引用。
🌐 The presentingElement property accepts a reference to the element that should display under your modal. This is typically a reference to ion-router-outlet.
canDismiss 属性可以用来控制卡片弹窗是否可以通过滑动来关闭。
🌐 The canDismiss property can be used to control whether or not the card modal can be swiped to close.
卡片显示样式仅在 iOS 上可用。
薄模态
🌐 Sheet Modal
如果你希望模态内容可滚动，Content 应在底片模态内使用。
开发者可以创建类似于地图应用中可用的抽屉组件的底部弹出模态效果。要创建底部弹出模态，开发者需要在 ion-modal 上设置 breakpoints 和 initialBreakpoint 属性。
🌐 Developers can create a sheet modal effect similar to the drawer components available in maps applications. To create a sheet modal, developers need to set the breakpoints and initialBreakpoint properties on ion-modal.
breakpoints 属性接受一个数组，用于指定滑动时表单可以停靠的每个断点。breakpoints 属性为 [0, 0.5, 1] 表示该表单可以滑动以显示模态框的 0%、50% 和 100%。当模态框滑动到 0% 时，模态框会自动关闭。请注意，如果未包含 0 断点，模态框无法通过滑动关闭，但仍可以通过按 Esc 或硬件返回按钮来关闭。
🌐 The breakpoints property accepts an array which states each breakpoint that the sheet can snap to when swiped. A breakpoints property of [0, 0.5, 1] would indicate that the sheet can be swiped to show 0% of the modal, 50% of the modal, and 100% of the modal. When the modal is swiped to 0%, the modal will be automatically dismissed. Note that the modal cannot be dismissed on swipe if no 0 breakpoint is included, but it can still be dismissed by pressing Esc or the hardware back button.
initialBreakpoint 属性是必需的，以便表单模态在渲染时知道从哪个断点开始。initialBreakpoint 值也必须存在于 breakpoints 数组中。给定 breakpoints 为 [0, 0.5, 1]，initialBreakpoint 为 0.5 的值是有效的，因为 0.5 存在于 breakpoints 数组中。initialBreakpoint 为 0.25 的值则无效，因为 0.25 不存在于 breakpoints 数组中。
🌐 The initialBreakpoint property is required so that the sheet modal knows which breakpoint to start at when presenting. The initialBreakpoint value must also exist in the breakpoints array. Given a breakpoints value of [0, 0.5, 1], an initialBreakpoint value of 0.5 would be valid as 0.5 is in the breakpoints array. An initialBreakpoint value of 0.25 would not be valid as 0.25 does not exist in the breakpoints array.
backdropBreakpoint 属性可用于自定义 ion-backdrop 开始淡入的时机。这在创建底部有可交互内容的界面时非常有用。一个常见的用例是覆盖地图的表单模态窗口，在表单完全展开之前，地图仍然可以交互。
🌐 The backdropBreakpoint property can be used to customize the point at which the ion-backdrop will begin to fade in. This is useful when creating interfaces that have content underneath the sheet that should remain interactive. A common use case is a sheet modal that overlays a map where the map is interactive until the sheet is fully expanded.
与背景内容交互
🌐 Interacting with background content
自定义板材高度
🌐 Custom Sheet Height
开发者应使用 --height CSS 变量来更改表单模态框的高度，而不是更改 breakpoints 数组中的最后一个断点。原因是将 breakpoints 数组中的最后一个断点改为小于 1 的值会导致模态框的部分内容在视口之外无法访问。
🌐 Developers should use the --height CSS Variable to change the height of the sheet modal instead of changing the last breakpoint in the breakpoints array. The reason for this is changing the last breakpoint in the breakpoints array to a value less than 1 will cause some of the modal to be inaccessible outside of the viewport.
以下示例展示了如何获取一个根据其内容自动调整大小的弹出层。请注意，通过将最大断点保持在 1，我们可以确保整个弹出层在视口中可访问。
🌐 The following example shows how to get a sheet modal that is automatically sized based on its content. Note that by keeping the maximum breakpoint at 1 we ensure that the entire modal is accessible in the viewport.
处理行为
🌐 Handle Behavior
表单模态可以选择性地显示一个句柄指示器，用于在断点之间拖动表单。handleBehavior 属性可用于配置用户激活句柄时的行为。
🌐 Sheet modals can optionally render a handle indicator used for dragging the sheet between breakpoints. The handleBehavior property can be used to configure the behavior of when the handle is activated by the user.
在所有断点处滚动内容
🌐 Scrolling content at all breakpoints
表单模态可以配置为在所有断点允许滚动内容，这使其非常适合显示大于视口的内容。通过将 expandToScroll 属性设置为 false，内容在每个断点都保持可滚动。否则，默认情况下，只有在表单模态完全展开时才启用滚动。
🌐 Sheet modals can be configured to allow scrolling content at all breakpoints, making them ideal for displaying content larger than the viewport. By setting the expandToScroll property to false, the content remains scrollable at every breakpoint. Otherwise, by default, scrolling is only enabled when the sheet modal is fully expanded.
样式
🌐 Styling
模态框在应用的根部渲染，因此它们会覆盖整个应用。此行为适用于内联模态框以及从控制器渲染的模态框。因此，自定义模态框样式无法限定于特定组件，因为它们不会应用于模态框。相反，样式必须全局应用。对于大多数开发者而言，将自定义样式放置在 global.css 中即可。
🌐 Modals are presented at the root of your application so they overlay your entire app. This behavior applies to both inline modals and modals presented from a controller. As a result, custom modal styles can not be scoped to a particular component as they will not apply to the modal. Instead, styles must be applied globally. For most developers, placing the custom styles in global.css is sufficient.
如果你正在构建一个 Ionic Angular 应用，样式需要添加到全局样式表文件中。有关更多信息，请参阅下面 Angular 部分的 样式放置。
ion-modal 假设堆叠的模态框大小相同。因此，每个后续的模态框将不会有盒子阴影，并且背景的不透明度为 0。这是为了避免随着每个新增模态框，阴影和背景变得更暗的效果。可以通过设置 --box-shadow 和 --backdrop-opacity CSS 变量来更改此设置：
ion-modal.stack-modal {
--box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
--backdrop-opacity: var(--ion-backdrop-opacity, 0.32);
}
动画
🌐 Animations
可以使用我们的动画构建器自定义进入和离开动画，并将动画分配给 enterAnimation 和 leaveAnimation。
🌐 The enter and leave animations can be customized by using our animation builder and assigning animations to enterAnimation and leaveAnimation.
自定义对话框
🌐 Custom Dialogs
虽然 ion-modal 最常用于全页视图、卡片或表单，但也可以将其用于自定义对话框。如果开发者需要比 ion-alert 或 ion-loading 提供的组件更复杂的界面，这会很有用。
🌐 While ion-modal is most often used for full-page views, cards, or sheets, it is also possible to use it for custom dialogs. This is useful if developers need an interface that is more complex than what components such as ion-alert or ion-loading provide.
创建自定义对话框时需要记住以下几点：
🌐 A few things to keep in mind when creating custom dialogs:
ion-content旨在用于全页模态、卡片和表单。如果你的自定义对话框大小是动态的或未知的，则不应使用ion-content。- 创建自定义对话框提供了一种脱离默认模式体验的方法。因此，自定义对话框不应与卡片或表单模态一起使用。
事件处理
🌐 Event Handling
使用 ionDragStart 和 ionDragEnd
🌐 Using ionDragStart and ionDragEnd
ionDragStart 事件在用户开始在模态框上进行拖动操作时立即触发。该事件在用户接触拖动句柄或模态框表面时触发，此时尚未产生任何实际位移。它尤其适用于为界面过渡做准备，例如隐藏某些交互元素（如标题或按钮），以确保拖动体验顺畅。
🌐 The ionDragStart event is emitted as soon as the user begins a dragging gesture on the modal. This event fires at the moment the user initiates contact with the handle or modal surface, before any actual displacement occurs. It is particularly useful for preparing the interface for a transition, such as hiding certain interactive elements (like headers or buttons) to ensure a smooth dragging experience.
ionDragEnd 事件在用户通过释放模态框完成拖拽手势时触发。与移动事件类似，它包含最终的 ModalDragEventDetail 对象。此事件通常用于在模态框停止后完成状态更改。
🌐 The ionDragEnd event is emitted when the user completes the dragging gesture by releasing the modal. Like the move event, it includes the final ModalDragEventDetail object. This event is commonly used to finalize state changes once the modal has come to a rest.
ConsoleConsole messages will appear here when logged from the example above.使用 ionDragMove
🌐 Using ionDragMove
ionDragMove 事件在用户主动拖动模态框时会持续触发。该事件提供一个 ModalDragEventDetail 对象，包含实时数据，这对于创建能够即时响应用户触摸的高响应 UI 更新至关重要。例如，progress 值可以在模态框向上拖动时，用于动态地加深标题的透明度。
🌐 The ionDragMove event is emitted continuously while the user is actively dragging the modal. This event provides a ModalDragEventDetail object containing real-time data, essential for creating highly responsive UI updates that react instantly to the user's touch. For example, the progress value can be used to dynamically darken a header's opacity as the modal is dragged upward.
ConsoleConsole messages will appear here when logged from the example above.接口
🌐 Interfaces
ModalOptions
下面你将找到使用 modalController 时可用的所有选项。这些选项应在调用 modalController.create() 时提供。
🌐 Below you will find all of the options available to you when using the modalController. These options should be supplied when calling modalController.create().
interface ModalOptions {
component: any;
componentProps?: { [key: string]: any };
presentingElement?: HTMLElement;
showBackdrop?: boolean;
backdropDismiss?: boolean;
cssClass?: string | string[];
animated?: boolean;
canDismiss?: boolean | ((data?: any, role?: string) => Promise<boolean>);
mode?: 'ios' | 'md';
keyboardClose?: boolean;
id?: string;
htmlAttributes?: { [key: string]: any };
enterAnimation?: AnimationBuilder;
leaveAnimation?: AnimationBuilder;
breakpoints?: number[];
initialBreakpoint?: number;
backdropBreakpoint?: number;
handle?: boolean;
}
ModalCustomEvent
虽然不是必需的，但可以使用此接口替代 CustomEvent 接口，以便对从此组件发出的 Ionic 事件进行更强类型的处理。
🌐 While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.
interface ModalCustomEvent extends CustomEvent {
target: HTMLIonModalElement;
}
ModalDragEventDetail
在使用 ionDragMove 和 ionDragEnd 事件时，事件详细信息包含以下属性：
🌐 When using the ionDragMove and ionDragEnd events, the event detail contains the following properties:
interface ModalDragEventDetail {
/**
* The current Y position of the modal.
*
* This can be used to determine how far the modal has been dragged.
*/
currentY: number;
/**
* The change in Y position since the gesture started.
*
* This can be used to determine the direction of the drag.
*/
deltaY: number;
/**
* The velocity of the drag in the Y direction.
*
* This can be used to determine how fast the modal is being dragged.
*/
velocityY: number;
/**
* A number between 0 and 1.
*
* In a sheet modal, progress represents the relative position between
* the lowest and highest defined breakpoints.
*
* In a card modal, it measures the relative position between the
* bottom of the screen and the top of the modal when it is fully
* open.
*
* This can be used to style content based on how far the modal has
* been dragged.
*/
progress: number;
/**
* If the modal is a sheet modal, this will be the breakpoint that
* the modal will snap to if the user lets go of the modal at the
* current moment.
*
* If it's a card modal, this property will not be included in the
* event payload.
*
* This can be used to style content based on where the modal will
* snap to upon release.
*/
snapBreakpoint?: number;
}
无障碍
🌐 Accessibility
键盘交互
🌐 Keyboard Interactions
| 键 | 描述 |
|---|---|
| Esc | 关闭模态窗口 |
标签
🌐 Labels
模态框具有 dialog 的作用。因此，开发者 必须 正确标记他们的模态框。如果模态框使用 ion-title，内部的文本可以通过在 ion-modal 上设置 aria-labelledby 来用于标记模态框本身。如果模态框包含额外的描述性文本，则可以使用 aria-describedby 将这些文本与模态框关联。
🌐 Modals have a dialog role. As a result, developers must properly label their modals. If the modal is using ion-title, the text inside can be used to label the modal itself by setting aria-labelledby on ion-modal. If the modal contains additional descriptive text, this text can be associated with the modal by using aria-describedby.
屏幕阅读器
🌐 Screen Readers
模态框已应用 aria-modal 属性。此属性可能导致辅助技术将导航限制在模态框元素的内容中。因此，使用移动到下一个或上一个项目的手势可能无法聚焦模态框外的元素。即使在使用 backdropBreakpoint 属性禁用表单模态框的背景时，这也同样适用。
🌐 Modals have the aria-modal attribute applied. This attribute can cause assistive technologies to limit navigation to the modal element's contents. As a result, using gestures that move to the next or previous items may not focus elements outside of the modal. This applies even when the backdrop is disabled in sheet modals using the backdropBreakpoint property.
如果开发者手动移动焦点，辅助技术不会将导航限制在模态元素的内容中。然而，对于启用了焦点锁定的模态，在 Ionic 中不支持手动将焦点移出模态之外。
🌐 Assistive technologies will not limit navigation to the modal element's contents if developers manually move focus. However, manually moving focus outside of a modal is not supported in Ionic for modals that have focus trapping enabled.
有关更多信息，请参阅 https://w3c.github.io/aria/#aria-modal。
🌐 See https://w3c.github.io/aria/#aria-modal for more information.
焦点捕捉
🌐 Focus Trapping
当一个模态框被展示时，焦点将被锁定在所展示的模态框内。用户可以在模态框内聚焦其他交互元素，但在模态框展示期间，永远无法聚焦模态框外的交互元素。对于渲染多个堆叠模态框的应用，焦点将被锁定在最后展示的模态框上。
🌐 When a modal is presented, focus will be trapped inside of the presented modal. Users can focus other interactive elements inside the modal but will never be able to focus interactive elements outside the modal while the modal is presented. For applications that present multiple stacked modals, focus will be trapped on the modal that was presented last.
通过 backdropBreakpoint 属性禁用背景的抽屉式模态框不受焦点限制的约束。
🌐 Sheet modals that have had their backdrop disabled by the backdropBreakpoint property are not subject to focus trapping.
薄模态
🌐 Sheet Modals
当使用 backdropBreakpoint 属性时，Sheet 模态允许用户与模态背后的内容进行交互。背景遮罩将在指定的 backdropBreakpoint 及之前被禁用，并在之后启用。
🌐 Sheet modals allow users to interact with content behind the modal when the backdropBreakpoint property is used. The backdrop will be disabled up to and including the specified backdropBreakpoint and will be enabled after it.
当背景被禁用时，用户将能够使用指针或键盘与表单模态之外的元素进行交互。由于使用了 aria-modal，辅助技术默认可能无法聚焦表单模态之外的内容。我们建议避免在此处使用自动聚焦等功能，因为它可能导致辅助技术在两个交互上下文之间跳转，而不会警告用户。
🌐 When the backdrop is disabled, users will be able to interact with elements outside the sheet modal using a pointer or keyboard. Assistive technologies may not focus outside the sheet modal by default due to the usage of aria-modal. We recommend avoiding features such as autofocus here as it can cause assistive technologies to jump between two interactive contexts without warning the user.
性能
🌐 Performance
挂载内部内容
🌐 Mounting Inner Contents
当关闭时，内联的 ion-modal 内容会被卸载。如果这些内容渲染成本高，开发者可以使用 keepContentsMounted 属性在模态框挂载时立即挂载内容。这可以帮助优化应用的响应速度，因为当模态框打开时，内部内容已经被挂载。
🌐 The content of an inline ion-modal is unmounted when closed. If this content is expensive to render, developers can use the keepContentsMounted property to mount the content as soon as the modal is mounted. This can help optimize the responsiveness of your application as the inner contents will have already been mounted when the modal opens.
开发者在使用 keepContentsMounted 时应记住以下几点：
🌐 Developers should keep the following in mind when using keepContentsMounted:
- 此功能应作为应对现有性能问题的最后手段。在使用此功能之前，尝试识别并解决性能瓶颈。此外，不要使用此功能来预判性能问题。
- 此功能仅在使用 JavaScript 框架时需要。不使用框架的开发者可以将要渲染的内容传递到模态框中，内容将自动渲染。
- 此功能仅适用于内联模态。使用
modalController创建的模态不会提前创建，因此内部内容也不会被创建。 - 内部组件上的任何 JavaScript 框架生命周期钩子都会在模式安装后立即运行，而不是在模式渲染时运行。
属性
🌐 Properties
animated
| Description | If true, the modal will animate. |
| Attribute | animated |
| Type | boolean |
| Default | true |
backdropBreakpoint
| Description | A decimal value between 0 and 1 that indicates the point after which the backdrop will begin to fade in when using a sheet modal. Prior to this point, the backdrop will be hidden and the content underneath the sheet can be interacted with. This value is exclusive meaning the backdrop will become active after the value specified. |
| Attribute | backdrop-breakpoint |
| Type | number |
| Default | 0 |
backdropDismiss
| Description | If true, the modal will be dismissed when the backdrop is clicked. |
| Attribute | backdrop-dismiss |
| Type | boolean |
| Default | true |
breakpoints
| Description | The breakpoints to use when creating a sheet modal. Each value in the array must be a decimal between 0 and 1 where 0 indicates the modal is fully closed and 1 indicates the modal is fully open. Values are relative to the height of the modal, not the height of the screen. One of the values in this array must be the value of the initialBreakpoint property. For example: [0, .25, .5, 1] |
| Attribute | undefined |
| Type | number[] ｜ undefined |
| Default | undefined |
canDismiss
| Description | Determines whether or not a modal can dismiss when calling the dismiss method.If the value is true or the value's function returns true, the modal will close when trying to dismiss. If the value is false or the value's function returns false, the modal will not close when trying to dismiss.See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access this from within the callback. |
| Attribute | can-dismiss |
| Type | ((data?: any, role?: string ｜ undefined) => Promise<boolean>) ｜ boolean |
| Default | true |
enterAnimation
| Description | Animation to use when the modal is presented. |
| Attribute | undefined |
| Type | ((baseEl: any, opts?: any) => Animation) ｜ undefined |
| Default | undefined |
expandToScroll
| Description | Controls whether scrolling or dragging within the sheet modal expands it to a larger breakpoint. This only takes effect when breakpoints and initialBreakpoint are set.If true, scrolling or dragging anywhere in the modal will first expand it to the next breakpoint. Once fully expanded, scrolling will affect the content. If false, scrolling will always affect the content. The modal will only expand when dragging the header or handle. The modal will close when dragging the header or handle. It can also be closed when dragging the content, but only if the content is scrolled to the top. |
| Attribute | expand-to-scroll |
| Type | boolean |
| Default | true |
focusTrap
| Description | If true, focus will not be allowed to move outside of this overlay. If false, focus will be allowed to move outside of the overlay.In most scenarios this property should remain set to true. Setting this property to false can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to false when absolutely necessary.Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay. |
| Attribute | focus-trap |
| Type | boolean |
| Default | true |
handle
| Description | The horizontal line that displays at the top of a sheet modal. It is true by default when setting the breakpoints and initialBreakpoint properties. |
| Attribute | handle |
| Type | boolean ｜ undefined |
| Default | undefined |
handleBehavior
| Description | The interaction behavior for the sheet modal when the handle is pressed. Defaults to "none", which means the modal will not change size or position when the handle is pressed. Set to "cycle" to let the modal cycle between available breakpoints when pressed.Handle behavior is unavailable when the handle property is set to false or when the breakpoints property is not set (using a fullscreen or card modal). |
| Attribute | handle-behavior |
| Type | "cycle" ｜ "none" ｜ undefined |
| Default | 'none' |
htmlAttributes
| Description | Additional attributes to pass to the modal. |
| Attribute | undefined |
| Type | undefined ｜ { [key: string]: any; } |
| Default | undefined |
initialBreakpoint
| Description | A decimal value between 0 and 1 that indicates the initial point the modal will open at when creating a sheet modal. This value must also be listed in the breakpoints array. |
| Attribute | initial-breakpoint |
| Type | number ｜ undefined |
| Default | undefined |
isOpen
| Description | If true, the modal will open. If false, the modal will close. Use this if you need finer grained control over presentation, otherwise just use the modalController or the trigger property. Note: isOpen will not automatically be set back to false when the modal dismisses. You will need to do that in your code. |
| Attribute | is-open |
| Type | boolean |
| Default | false |
keepContentsMounted
| Description | If true, the component passed into ion-modal will automatically be mounted when the modal is created. The component will remain mounted even when the modal is dismissed. However, the component will be destroyed when the modal is destroyed. This property is not reactive and should only be used when initially creating a modal.Note: This feature only applies to inline modals in JavaScript frameworks such as Angular, React, and Vue. |
| Attribute | keep-contents-mounted |
| Type | boolean |
| Default | false |
keyboardClose
| Description | If true, the keyboard will be automatically dismissed when the overlay is presented. |
| Attribute | keyboard-close |
| Type | boolean |
| Default | true |
leaveAnimation
| Description | Animation to use when the modal is dismissed. |
| Attribute | undefined |
| Type | ((baseEl: any, opts?: any) => Animation) ｜ undefined |
| Default | undefined |
mode
| Description | The mode determines which platform styles to use. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render. |
| Attribute | mode |
| Type | "ios" ｜ "md" |
| Default | undefined |
presentingElement
| Description | The element that presented the modal. This is used for card presentation effects and for stacking multiple modals on top of each other. Only applies in iOS mode. |
| Attribute | undefined |
| Type | HTMLElement ｜ undefined |
| Default | undefined |
showBackdrop
| Description | If true, a backdrop will be displayed behind the modal. This property controls whether or not the backdrop darkens the screen when the modal is presented. It does not control whether or not the backdrop is active or present in the DOM. |
| Attribute | show-backdrop |
| Type | boolean |
| Default | true |
trigger
| Description | An ID corresponding to the trigger element that causes the modal to open when clicked. |
| Attribute | trigger |
| Type | string ｜ undefined |
| Default | undefined |
事件
🌐 Events
| Name | Description | Bubbles |
|---|---|---|
didDismiss | Emitted after the modal has dismissed. Shorthand for ionModalDidDismiss. | true |
didPresent | Emitted after the modal has presented. Shorthand for ionModalDidPresent. | true |
ionBreakpointDidChange | Emitted after the modal breakpoint has changed. | true |
ionDragEnd | Event that is emitted when the sheet modal or card modal gesture ends. | true |
ionDragMove | Event that is emitted when the sheet modal or card modal gesture moves. | true |
ionDragStart | Event that is emitted when the sheet modal or card modal gesture starts. | true |
ionModalDidDismiss | Emitted after the modal has dismissed. | true |
ionModalDidPresent | Emitted after the modal has presented. | true |
ionModalWillDismiss | Emitted before the modal has dismissed. | true |
ionModalWillPresent | Emitted before the modal has presented. | true |
willDismiss | Emitted before the modal has dismissed. Shorthand for ionModalWillDismiss. | true |
willPresent | Emitted before the modal has presented. Shorthand for ionModalWillPresent. | true |
方法
🌐 Methods
dismiss
| Description | Dismiss the modal overlay after it has been presented. This is a no-op if the overlay has not been presented yet. If you want to remove an overlay from the DOM that was never presented, use the remove method. |
| Signature | dismiss(data?: any, role?: string) => Promise<boolean> |
| Parameters | data: Any data to emit in the dismiss events. role: The role of the element that is dismissing the modal. For example, cancel or backdrop. |
getCurrentBreakpoint
| Description | Returns the current breakpoint of a sheet style modal |
| Signature | getCurrentBreakpoint() => Promise<number ｜ undefined> |
onDidDismiss
| Description | Returns a promise that resolves when the modal did dismiss. |
| Signature | onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
onWillDismiss
| Description | Returns a promise that resolves when the modal will dismiss. |
| Signature | onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
present
| Description | Present the modal overlay after it has been created. |
| Signature | present() => Promise<void> |
setCurrentBreakpoint
| Description | Move a sheet style modal to a specific breakpoint. |
| Signature | setCurrentBreakpoint(breakpoint: number) => Promise<void> |
| Parameters | breakpoint: The breakpoint value to move the sheet modal to. Must be a value defined in your breakpoints array. |
CSS 阴影部分
🌐 CSS Shadow Parts
| Name | Description |
|---|---|
backdrop | The ion-backdrop element. |
content | The wrapper element for the default slot. |
handle | The handle that is displayed at the top of the sheet modal when handle="true". |
CSS 自定义属性
🌐 CSS Custom Properties
- iOS
- MD
| Name | Description |
|---|---|
--backdrop-opacity | Opacity of the backdrop |
--background | Background of the modal content |
--border-color | Border color of the modal content |
--border-radius | Border radius of the modal content |
--border-style | Border style of the modal content |
--border-width | Border width of the modal content |
--height | Height of the modal |
--max-height | Maximum height of the modal |
--max-width | Maximum width of the modal |
--min-height | Minimum height of the modal |
--min-width | Minimum width of the modal |
--width | Width of the modal |
| Name | Description |
|---|---|
--backdrop-opacity | Opacity of the backdrop |
--background | Background of the modal content |
--border-color | Border color of the modal content |
--border-radius | Border radius of the modal content |
--border-style | Border style of the modal content |
--border-width | Border width of the modal content |
--height | Height of the modal |
--max-height | Maximum height of the modal |
--max-width | Maximum width of the modal |
--min-height | Minimum height of the modal |
--min-width | Minimum width of the modal |
--width | Width of the modal |
插槽
🌐 Slots
| Name | Description |
|---|---|
| `` | Content is placed inside of the .modal-content element. |