Skip to main content

在 React 中使用 Overlay 组件

🌐 Using Overlay Components in React

对于 Ionic React，你可以使用两种技术来显示叠加组件，例如模式、警报、操作表等。在本指南中，我们将介绍这两种技术。

🌐 For Ionic React, there are two techniques you can use to display overlay components like modals, alerts, action sheets, etc. In this guide, we will go over both of them.

覆盖钩子​

🌐 Overlay Hooks

从 Ionic React 5.6 开始，我们引入了新的 React Hooks，你可以使用它们来控制覆盖层的显示和消失。这些 Hooks 提供了一种以编程方式控制覆盖层的方法，以及一种在不需要状态管理系统的情况下在 Ionic 页面之外使用覆盖层的方法。

🌐 Starting in Ionic React 5.6, we introduced new React hooks you can use to control displaying and dismissing overlays. These hooks provide a programmatic way of controlling the overlays, as well as a way to use overlays outside of your Ionic Page without the need of a state management system.

要使用其中一个覆盖钩子，你需要从 @ionic/react 导入你想使用的覆盖的钩子。例如，如果我们想使用 Alert 覆盖，我们导入 useIonAlert：

🌐 To use one of the overlay hooks, you import the hook for the overlay you want to use from @ionic/react. For example, if we want to use the Alert overlay, we import useIonAlert:

import { useIonAlert } from '@ionic/react';

钩子返回一个数组，其中数组中的第一项是渲染钩子的方法，第二项是解除钩子的方法：

🌐 The hooks return an array, where the first item in the array is the method to present the hook, and the second is the method to dismiss the hook:

const [showAlert, hideAlert] = useIonAlert();
note

当用户完成与叠加层的交互后，叠加层通常会自行消失，因此你可能不需要使用消除/隐藏方法。

要显示覆盖层，你使用 present 方法，我们将其解构为名为 showAlert。该方法接受一组参数，这些参数根据每个覆盖层的不同而有所变化，但一般来说，它们可以接受一组简单的常用参数，或者一个对象以指定附加选项。

🌐 To display the overlay, you use the present method, which we destructured to the name showAlert. The method takes in a set of parameters that vary depending on each overlay, but generally, they can either take in a simple set of common parameters or an object to specify additional options.

showAlert('Hello!', [{ text: 'Ok' }]);

对于 useIonAlert，第一个参数是要显示的消息，第二个参数是一个 AlertButtons 数组，用于自定义警报将显示的按钮。

🌐 For useIonAlert, the first parameter is the message to display, and the second is an array of AlertButtons to customize the buttons the alert will show.

或者，你可以传入 AlertOptions 配置对象来提供其他参数，例如要添加到标记的 CSS 类、警报的标头以及警报解除时调用的回调：

🌐 Alternatively, you can pass in an AlertOptions config object to provide additional parameters, such as a CSS class to add to the markup, a header for the alert, and a callback that gets called when the alert is dismissed:

showAlert({
  cssClass: 'my-css',
  header: 'Alert',
  message: 'Hello!',
  buttons: ['Cancel', { text: 'Ok', handler: (d) => console.log('ok pressed') }],
  onDidDismiss: (e) => console.log('alert dismiss'),
});

覆盖钩子（Overlay hooks）在其标记中显示额外的自定义组件，例如 模态框 和 弹出框，在初始化它们的钩子时会接受几个额外的参数。第一个参数是你希望覆盖层显示的组件，第二个是一个对象，包含你希望在组件构建时传入的额外属性：

🌐 Overlay hooks that display additional custom components as part of their markup, such as modals and popovers, take in a couple of additional parameters when initializing their hooks. The first parameter is the component you want your overlay to display, and the second is an object of additional props you want to pass into the component when it gets constructed:

const [present, dismiss] = useIonModal(({ name }) => <div>Hello {name}.</div>, {
  name: 'Dave',
});

覆盖组件​

🌐 Overlay Components

还可以使用 @ionic/react 的组件来显示覆盖层。这些组件需要一个 isOpen 属性，由你提供以控制覆盖层当前是否显示。当 isOpen 从 true 切换为 false（反之亦然）时，Ionic 会使用适当的动画打开/关闭覆盖层。你还可以将任何其他额外的配置选项作为属性传递给覆盖层：

🌐 Overlays can also be displayed by using components from @ionic/react. The components take a isOpen prop that you provide to control if the overlay is currently being displayed or not. When isOpen switches from true to false (and vise versa), Ionic will open/close the overlay with the appropriate animation. You can also supply any other additional config options as props to the overlay:

<IonAlert isOpen={showAlert} message="Hello!" buttons={[{ text: 'Ok' }]} onDidDismiss={() => setShowAlert(false)} />

上面，showAlert 布尔值是由你的应用提供的一部分状态。

🌐 Above, the showAlert boolean is a piece of state provided from your application.

当覆盖层被关闭时，重要的是要连接到 onDidDismiss 回调并设置你的状态变量，以表明覆盖层不再显示。Ionic React 会观察 isOpen 属性的变化，以确定覆盖层是否应该显示。

🌐 When the overlay is dismissed, it is important to tie into the onDidDismiss callback and set your state variable to indicate that the overlay is no longer presenting. Ionic React looks for changes to the isOpen prop to determine if the overlay should be displayed or not.

对于显示自定义组件的覆盖层，例如 模态框 和 弹出框，你可以将组件作为子组件提供给覆盖层组件：

🌐 For overlays that display custom components, such as modals and popovers, you provide the component as a child to the overlay component:

<IonModal isOpen={showModal}>
  <div>Hello!</div>
</IonModal>
note

覆盖组件仍然是显示覆盖层的有效方式，并且绝不是已废弃的方法。请使用最适合你应用的方法。

Ionic 中的叠加层文档​

🌐 Docs for Overlays in Ionic

如需完整文档并查看钩子和组件方法的使用示例，请访问 Ionic 中每个覆盖层的文档页面：

🌐 For full docs and to see usage examples for both the hook and component approach, visit the docs page for each of the overlays in Ionic:

目录