Ionic React 快速入门

欢迎！本指南将带你了解 Ionic React 开发的基础知识。你将学习如何设置开发环境、生成一个简单的项目、探索项目结构，并了解 Ionic 组件的工作原理。这对于在构建你的第一个真实应用之前熟悉 Ionic React 非常适合。

🌐 Welcome! This guide will walk you through the basics of Ionic React development. You'll learn how to set up your development environment, generate a simple project, explore the project structure, and understand how Ionic components work. This is perfect for getting familiar with Ionic React before building your first real app.

如果你想要了解 Ionic React 是什么以及它如何融入 React 生态系统的高级概述，请参见 Ionic React 概述。

🌐 If you're looking for a high-level overview of what Ionic React is and how it fits into the React ecosystem, see the Ionic React Overview.

先决条件

🌐 Prerequisites

在开始之前，确保你的计算机上已安装 Node.js 和 npm。你可以通过运行以下命令来检查：

🌐 Before you begin, make sure you have Node.js and npm installed on your machine. You can check by running:

node -v
npm -v

如果你没有 Node.js 和 npm，请在此下载 Node.js（其中包含 npm）。

🌐 If you don't have Node.js and npm, download Node.js here (which includes npm).

使用 Ionic CLI 创建项目

🌐 Create a Project with the Ionic CLI

首先，安装最新的 Ionic CLI ：

🌐 First, install the latest Ionic CLI:

npm install -g @ionic/cli

然后，运行以下命令来创建并运行一个新项目：

🌐 Then, run the following commands to create and run a new project:

ionic start myApp blank --type react

cd myApp
ionic serve

运行 ionic serve 后，你的项目将在浏览器中打开。

🌐 After running ionic serve, your project will open in the browser.

探索项目结构

🌐 Explore the Project Structure

你的新应用的目录将如下所示：

🌐 Your new app's directory will look like this:

└── src/
    ├── App.tsx
    ├── components
    │   ├── ExploreContainer.css
    │   └── ExploreContainer.tsx
    ├── main.tsx
    └── pages
        ├── Home.css
        └── Home.tsx

info

下面示例中的所有文件路径都是相对于项目根目录的。

让我们浏览这些文件来了解应用的结构。

🌐 Let's walk through these files to understand the app's structure.

查看应用组件

🌐 View the App Component

你的应用的根目录定义在 App.tsx 中：

🌐 The root of your app is defined in App.tsx:

src/App.tsx

import { Redirect, Route } from 'react-router-dom';
import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
import Home from './pages/Home';

// ..CSS imports...

setupIonicReact();

const App: React.FC = () => (
  <IonApp>
    <IonReactRouter>
      <IonRouterOutlet>
        <Route exact path="/home">
          <Home />
        </Route>
        <Route exact path="/">
          <Redirect to="/home" />
        </Route>
      </IonRouterOutlet>
    </IonReactRouter>
  </IonApp>
);

export default App;

这设置了你的应用的根，使用了 Ionic 的 IonApp 和 IonReactRouter 组件。IonRouterOutlet 是你的页面将显示的地方。

🌐 This sets up the root of your application, using Ionic's IonApp and IonReactRouter components. The IonRouterOutlet is where your pages will be displayed.

查看路由

🌐 View Routes

路由在 App.tsx 的 IonRouterOutlet 中定义：

🌐 Routes are defined within the IonRouterOutlet in App.tsx:

src/App.tsx

<IonRouterOutlet>
  <Route exact path="/home">
    <Home />
  </Route>
  <Route exact path="/">
    <Redirect to="/home" />
  </Route>
</IonRouterOutlet>

当你访问根 URL (/) 时，Home 组件将被加载。

🌐 When you visit the root URL (/), the Home component will be loaded.

查看主页

🌐 View the Home Page

在 Home.tsx 中定义的主页组件，导入了 Ionic 组件并定义了页面模板：

🌐 The Home page component, defined in Home.tsx, imports the Ionic components and defines the page template:

src/pages/Home.tsx

import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';
import ExploreContainer from '../components/ExploreContainer';
import './Home.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Blank</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        <IonHeader collapse="condense">
          <IonToolbar>
            <IonTitle size="large">Blank</IonTitle>
          </IonToolbar>
        </IonHeader>
        <ExploreContainer />
      </IonContent>
    </IonPage>
  );
};

export default Home;

这会创建一个带有标题和可滚动内容区域的页面。IonPage 组件提供了基本的页面结构，必须在每个页面上使用。第二个标题显示一个可折叠的大标题，当内容在顶部时显示该大标题，向下滚动时则会收缩，在第一个标题中显示较小的标题。

🌐 This creates a page with a header and scrollable content area. The IonPage component provides the basic page structure and must be used on every page. The second header shows a collapsible large title that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.

了解更多

有关 Ionic 布局组件的详细信息，请参阅 Header、Toolbar、Title 和 Content 文档。

添加一个 Ionic 组件

🌐 Add an Ionic Component

你可以通过更多的 Ionic UI 组件来增强你的首页。例如，在 Home.tsx 中的 IonContent 末尾导入并添加一个 按钮 ：

🌐 You can enhance your Home page with more Ionic UI components. For example, import and add a Button at the end of the IonContent in Home.tsx:

src/pages/Home.tsx

import { IonButton, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';
// ...existing imports...

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Blank</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        {/* ...existing content... */}

        <IonButton>Navigate</IonButton>
      </IonContent>
    </IonPage>
  );
};

export default Home;

添加新页面

🌐 Add a New Page

在 New.tsx 创建一个新页面：

🌐 Create a new page at New.tsx:

src/pages/New.tsx

import { IonBackButton, IonButtons, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';

const New: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonButtons slot="start">
            <IonBackButton defaultHref="/"></IonBackButton>
          </IonButtons>
          <IonTitle>New</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        <IonHeader collapse="condense">
          <IonToolbar>
            <IonTitle size="large">New</IonTitle>
          </IonToolbar>
        </IonHeader>
      </IonContent>
    </IonPage>
  );
};

export default New;

这将创建一个带有 返回按钮 的页面，该按钮位于 工具栏 中。返回按钮将自动处理返回到上一页的导航，如果没有历史记录，则返回到 /。

🌐 This creates a page with a Back Button in the Toolbar. The back button will automatically handle navigation back to the previous page, or to / if there is no history.

warning

在创建自己的页面时，始终使用 IonPage 作为根组件。这对于页面之间的正确过渡、Ionic 组件依赖的基础 CSS 样式以及应用内一致的布局行为都是必不可少的。

导航到新页面

🌐 Navigate to the New Page

要导航到新页面，请为其创建一个路由，首先在 Home 导入之后，在 App.tsx 顶部导入它：

🌐 To navigate to the new page, create a route for it by first importing it at the top of App.tsx after the Home import:

src/App.tsx

import New from './pages/New';

然后，在 IonRouterOutlet 中添加它的路由：

🌐 Then, add its route in IonRouterOutlet:

src/App.tsx

<IonRouterOutlet>
  <Route exact path="/home">
    <Home />
  </Route>
  <Route exact path="/new">
    <New />
  </Route>
  <Route exact path="/">
    <Redirect to="/home" />
  </Route>
</IonRouterOutlet>

完成后，更新 Home.tsx 中的按钮：

🌐 Once that is done, update the button in Home.tsx:

src/pages/Home.tsx

<IonButton routerLink="/new">Navigate</IonButton>

info

导航也可以使用 React Router 的 history 属性以编程方式执行。有关更多信息，请参阅 React 导航文档。

将图标添加到新页面

🌐 Add Icons to the New Page

Ionic React 自带 Ionicons。你可以通过设置 IonIcon 组件的 icon 属性来使用任何图标。

🌐 Ionic React comes with Ionicons pre-installed. You can use any icon by setting the icon property of the IonIcon component.

更新 New.tsx 中的导入，以导入 IonIcon 以及 heart 和 logoIonic 图标：

🌐 Update the imports in New.tsx to import IonIcon and the heart and logoIonic icons:

src/pages/New.tsx

import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonPage, IonTitle, IonToolbar } from '@ionic/react';
import { heart, logoIonic } from 'ionicons/icons';

然后，将它们包含在 IonContent 内：

🌐 Then, include them inside of the IonContent:

src/pages/New.tsx

<IonIcon icon={heart} />
<IonIcon icon={logoIonic} />

请注意，我们传递的是导入的 SVG 引用，而不是作为字符串的图标名称。

🌐 Note that we are passing the imported SVG reference, not the icon name as a string.

欲了解更多信息，请参阅 Icon 文档 和 Ionicons 文档。

🌐 For more information, see the Icon documentation and the Ionicons documentation.

调用组件方法

🌐 Call Component Methods

让我们添加一个可以将内容区域滚动到底部的按钮。

🌐 Let's add a button that can scroll the content area to the bottom.

更新 New.tsx，在 IonContent 上添加一个 ref，并在现有图标之后添加一个按钮和一些项目：

🌐 Update New.tsx to add a ref on IonContent and a button and some items after the existing icons:

src/pages/New.tsx

<IonContent ref={content}>
  <IonIcon icon={heart} />
  <IonIcon icon={logoIonic} />

  <IonButton onClick={scrollToBottom}>Scroll to Bottom</IonButton>

  {/* Add lots of content to make scrolling possible */}
  {Array.from({ length: 50 }, (_, i) => (
    <IonItem key={i}>
      <IonLabel>Item {i + 1}</IonLabel>
    </IonItem>
  ))}
</IonContent>

然后，为其他组件添加导入并定义 scrollToBottom 函数：

🌐 Then, add the imports for the additional components and define the scrollToBottom function:

src/pages/New.tsx

import { useRef } from 'react';
import { IonButton, IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonItem, IonLabel, IonPage, IonTitle, IonToolbar } from '@ionic/react';
import { heart, logoIonic } from 'ionicons/icons';

const New: React.FC = () => {
  const content = useRef<HTMLIonContentElement>(null);

  const scrollToBottom = () => {
    content.current?.scrollToBottom(300);
  };

  return (
    // ...existing template...
  );
};

export default New;

调用 Ionic 组件的方法：

🌐 To call methods on Ionic components:

1. 为组件创建一个 ref
2. 直接在 ref.current 上调用方法

这种模式是必要的，因为 React refs 将组件实例存储在 .current 属性中。

🌐 This pattern is necessary because React refs store the component instance in the .current property.

你可以在它们的 API 文档的 方法 部分找到每个组件的可用方法。

🌐 You can find available methods for each component in the Methods section of their API documentation.

在设备上运行

🌐 Run on a Device

Ionic 的组件无处不在：在 iOS、Android 和 PWA 上都能使用。要部署到移动端，请使用 Capacitor：

🌐 Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use Capacitor:

ionic build
ionic cap add ios
ionic cap add android

在它们的 IDE 中打开本地项目：

🌐 Open the native projects in their IDEs:

ionic cap open ios
ionic cap open android

更多信息请参阅 电容器入门指南。

🌐 See Capacitor's Getting Started guide for more.

探索更多

🌐 Explore More

本指南涵盖了创建 Ionic React 应用、添加导航以及引入 Capacitor 进行原生构建的基础知识。要深入了解，请查看：

🌐 This guide covered the basics of creating an Ionic React app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:

构建你的第一个应用

使用 Ionic React 和原生设备功能构建一个真正的照片图库应用。

React 文档

从官方 React 文档了解更多关于 React 核心概念、工具和最佳实践的信息。

导航

了解如何在 Ionic React 应用中使用 React Router 处理路由和导航。

组件

探索 Ionic 丰富的 UI 组件库，用于构建美观的应用。

主题化

了解如何使用 Ionic 强大的主题系统自定义应用的外观和感觉。

电容器文档

探索如何访问本地设备功能，并使用 Capacitor 将你的应用部署到 iOS、Android 和网络。