介绍 Ionic React 快速入门

什么是 Ionic 框架？

首先，如果您是新手，欢迎！Ionic 是一个免费的开源组件库，用于构建在 iOS、Android、Electron 和 Web 上运行的应用程序。您可以使用熟悉的技术（HTML、CSS、JavaScript）编写应用程序一次，然后部署到任何平台。

除了 UI 组件外，Ionic 还提供了一个命令行工具，用于创建新应用程序以及部署到我们支持的各种平台。

在本指南中，我们将介绍 React 和 Ionic 的基础知识，包括任何特定于 Ionic 的功能。如果您熟悉 React，请享受本指南并学习有关 Ionic 的新知识。如果您不熟悉两者，不用担心！本指南将介绍基础知识并提供足够的知识来启动和运行应用程序。

使用 Ionic CLI 创建项目

要开始使用，让我们安装最新版本的 Ionic CLI。

npm install -g @ionic/cli

从这里开始，全局命令 ionic 将允许使用 Ionic 创建 React 项目以及任何其他依赖项。要创建一个新项目，请运行以下命令

ionic start myApp blank --type=react
cd myApp

从这里开始，我们运行 ionic serve 并让项目在浏览器中运行。

查看 React 组件

我们应用程序的基础将位于 src 目录中，主要入口点将是我们的 index.tsx。如果我们在代码编辑器中打开我们的项目并打开 src/index.tsx，我们应该看到以下内容

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

这里发生了什么？好吧，前三行正在拉入一些依赖项。第一个是 React 本身。这使我们能够以称为 JSX 的类似 HTML 的语法编写组件。我们将在稍后讨论 JSX。

第二个导入是用于 ReactDOM 的。ReactDOM.render 方法是浏览器/DOM 特定方法，用于获取我们的组件并将其渲染到指定的 DOM 节点。

最后一个导入是应用程序的根组件，简单命名为 App。这是我们的第一个 React 组件，将在我们的 React 应用程序的引导过程中使用。

如果我们打开 App.tsx，我们应该看到以下内容。

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

/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';

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

乍一看，似乎有很多事情正在发生，所以让我们分解一下，从第一组导入开始。

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

与 index.tsx 类似，我们首先必须导入 React 以使用 JSX。

下一个导入来自 react-router-dom。我们正在导入 Route，这是我们将应用程序的 URL 与要渲染的组件匹配的方式

在 ReactRouter 之后，接下来是我们的第一个 Ionic 导入。要在 React 中使用组件，您必须首先导入它。因此对于 Ionic，这意味着无论何时我们想要使用 Button 或 Card，都必须将其添加到我们的导入中。在 App 组件的情况下，我们只使用 IonApp、IonRouterOutlet 和 IonReactRouter。

IonReactRouter 是一个组件，它包装了 ReactRouter 的 BrowserRouter 组件。它或多或少的行为与 BrowserRouter 相同，但也有一些差异。我们在我们的 React Navigation 文档 中有一个更深入的指南，介绍了这些差异。

最后一个重要的导入是 Home 组件导入。这是一个我们可以在应用程序中导航到的组件。我们将在稍后讨论导航部分。

CSS 导入正在拉入 Ionic 的实用程序样式，用于填充、排版等。

在查看完所有导入后，我们现在开始查看第一个 React 组件

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

此 React 组件为我们的应用程序设置初始路由，以及包含一些用于动画和布局的 Ionic 核心组件（IonRouterOutlet 和 IonApp）。值得注意的一点是，在 React 中，要进行数据绑定，值是在花括号（{}）中传递的。因此，在 Route 组件中，我们可以将 component 的值设置为之前的 Home 组件。这就是 React 如何知道该值不是字符串，而是对组件的引用。

注意

这里需要注意的是，这些都是标准的 React DOM 库，这意味着没有自定义集成层或转译步骤。

带样式的组件

现在，App 实际上没有太多需要修改的地方。这是一个容器组件的基本示例。在路由逻辑设置后，它只负责渲染与给定 URL 路由匹配的组件。由于我们已经有一个组件/路由设置，所以让我们继续修改 Home 组件。

当前，Home 组件如下所示

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Ionic Blank</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        The world is your oyster.
        <p>
          If you get lost, the{' '}
          <a target="_blank" rel="noopener" href="https://ionic.js.cn/docs/">
            docs
          </a>{' '}
          will be your guide.
        </p>
      </IonContent>
    </IonPage>
  );
};

与我们开始使用的 App 组件非常相似，我们有一些特定于 Ionic 组件的导入，一个用于 React 的导入，然后是我们的 React 组件本身。

IonPage 是所有页面的基本组件（带路由/URL 的组件），它包含全屏组件的一些通用构建块，如标题、标题和内容组件。

注意

在创建您自己的页面时，请不要忘记让 IonPage 成为它们的根组件。让 IonPage 成为根组件非常重要，因为它有助于确保过渡正常工作，并提供 Ionic 组件依赖的基础 CSS。

IonHeader 顾名思义，它是一个旨在存在于页面顶部的组件。IonHeader 本身并没有做太多事情，除了处理一些基于 Flexbox 的布局。它旨在容纳其他组件，如 IonToolbar 或 IonSearchbar。

IonContent 正如其名称所示，是我们页面的主要内容区域。它负责提供用户将与之交互的可滚动内容，以及可用于应用程序的任何滚动事件。

我们当前的内容相对简单，但没有包含任何可以在真实应用程序中使用的内容，所以让我们更改它。

注意

为了简洁起见，我们排除了组件重复的部分，如函数声明或其他组件的导入语句。

<IonPage>
  ...
  <IonContent>
    <IonList>
      <IonItem>
        <IonCheckbox labelPlacement="end" justify="start">
          <h1>Create Idea</h1>
          <IonNote>Run Idea by Brandy</IonNote>
        </IonCheckbox>
        <IonBadge color="success" slot="end">
          5 Days
        </IonBadge>
      </IonItem>
    </IonList>
  </IonContent>
</IonPage>

这里，在我们的 IonContent 中，我们添加了一个 IonList 和一个更复杂的 IonItem 组件。让我们看看 IonItem，因为它在这里是核心。

<IonItem>
  <IonCheckbox labelPlacement="end" justify="start">
    <h1>Create Idea</h1>
    <IonNote>Run Idea by Brandy</IonNote>
  </IonCheckbox>
  <IonBadge color="success" slot="end">
    5 Days
  </IonBadge>
</IonItem>

查看我们的代码，我们有一个特殊的属性叫做 slot。这是让 IonItem 知道在渲染时将 IonBadge 放置在何处。这不是 React API，而是一个 Web 标准 API，它在许多 Ionic 框架组件中使用。（有关插槽的更多信息，请查看这里的 MDN 文档。）

让我们看看 Ionic 的另一个组件，FAB。浮动操作按钮是一种提供从应用程序其余部分中升起的操作的好方法。对于此 FAB，我们需要三个组件：FAB、FAB 按钮和图标。

import { add } from ‘ionicons/icons’;
…

<IonContent>
  <IonList>
  ...
  </IonList>

  <IonFab vertical="bottom" horizontal="end" slot="fixed">
    <IonFabButton>
      <IonIcon icon={add} />
    </IonFabButton>
  </IonFab>

</IonContent>

在我们主要的 IonFab 上，我们使用 vertical 和 horizontal 属性设置其定位。我们还使用 slot 属性将渲染位置设置为“fixed”。这将告诉 IonFab 在 IonContent 中的可滚动内容之外进行渲染。

现在让我们为它连接一个点击处理程序。我们想要做的是，当我们点击按钮时，我们将导航到一个新页面（我们将在稍后创建它）。为此，我们需要访问 React Router 的 useHistory hook API。值得庆幸的是，useHistory hook 使此操作变得容易，因为它可以从 react-router 包中导入。

import { add } from 'ionicons/icons';
import { useHistory } from 'react-router';
...
const Home: React.FC<RouteComponentProps> = () => {
  const history = useHistory();
  return (
    <IonPage>
      <IonHeader>...</IonHeader>
      <IonContent>
        <IonList>...</IonList>
        <IonFab vertical="bottom" horizontal="end" slot="fixed">
          <IonFabButton onClick={() => history.push('/new')}>
            <IonIcon icon={add} />
          </IonFabButton>
        </IonFab>
      </IonContent>
    </IonPage>
  );
}
export default Home;

在我们的组件声明中，我们传递了 props，其类型为 RouteComponentProps（从 react-router 导入）。此 props 对象使我们能够访问 React Router 的历史 API，从而使我们能够将新的路由推送到导航堆栈。在我们的 IonFabButton 上，我们可以添加一个点击处理程序，只需调用 props.history.push 并传递新路由即可。在本例中，我们将导航到 new。

<IonFabButton onClick={() => props.history.push('/new')} >

创建新的路由

现在我们已经准备好进行导航，我们需要创建一个新的组件并将新的路由添加到我们的路由声明中。让我们打开我们的 App.tsx 文件并添加新的路由。

...
import Home from './pages/Home';

import NewItem from './pages/NewItem';
...
const App: React.FC = () => {
  const isAuthed = true;
  return (
    <IonApp>
      <IonReactRouter>
        <IonRouterOutlet>
          <Route path="/home" component={Home} />
          <Route path="/new" component={NewItem} />
          <Redirect exact from="/" to="/home" />
        </IonRouterOutlet>
      </IonReactRouter>
    </IonApp>
  );
}
export default App;

现在我们的路由有了 /new 路由的条目，我们将创建所需的组件 NewItem。它将位于 src/pages/NewItem.tsx 中。

让我们用一些占位符内容填充 NewItem.tsx。

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

const NewItem: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonButtons slot="start">
            <IonBackButton />
          </IonButtons>
          <IonTitle>New Item</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent></IonContent>
    </IonPage>
  );
};
export default NewItem;

注意

每个视图必须包含一个 IonPage 组件。没有它，页面过渡将无法正常工作。有关更多信息，请参阅 IonPage 文档。

这里的内容非常简单，应该类似于 Home 组件。新的内容是 IonBackButton 组件。它用于导航回前一个路由。很简单吧？好的，但是如果我们重新加载页面呢？

在这种情况下，内存中的历史记录会丢失，因此后退按钮会消失。为了解决这个问题，我们可以将 defaultHref 属性值设置为我们想要在没有历史记录的情况下导航到的 URL。

return (
  <IonPage>
    <IonHeader>
      <IonToolbar>
        <IonButtons slot="start">
          <IonBackButton defaultHref="/home" />
        </IonButtons>
        <IonTitle>New Item</IonTitle>
      </IonToolbar>
    </IonHeader>
    <IonContent />
  </IonPage>
);

这里，当我们重新加载时，如果不存在应用程序历史记录，我们将能够导航回我们的主页路由。

添加图标

Ionic React 预装了 (https://ionic.io/ionicons/)。您只需要从 ionicons 包中导入您选择的图标，并通过 icon 道具将其传递给 IonIcon 组件。

import React from 'react';
import { IonButton, IonContent, IonIcon } from '@ionic/react';
import { camera } from 'ionicons/icons';

export const IconExample: React.FC = () => {
  <IonContent>
    <IonButton>
      <IonIcon icon={camera} />
      Take Picture
    </IonButton>
  </IonContent>;
};

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

开发人员还可以选择根据模式设置不同的图标。

import React from 'react';
import { IonButton, IonContent, IonIcon } from '@ionic/react';
import { logoAndroid, logoApple } from 'ionicons/icons';

export const IconExample: React.FC = () => {
  <IonContent>
    <IonButton>
      <IonIcon ios={logoApple} md={logoAndroid} />
    </IonButton>
  </IonContent>;
};

构建原生应用

现在我们已经拥有 Ionic React 应用程序的基本知识，包括一些 UI 组件和导航。Ionic 组件的优点是它们可以在任何地方工作，包括 iOS、Android 和 PWA。为了部署到移动设备和其他地方，我们使用 Ionic 的跨平台应用程序运行时 Capacitor。它提供了一套一致的、以 Web 为中心的 API，使应用程序能够尽可能地接近 Web 标准，同时访问支持它们的平台上的丰富原生设备功能。

添加原生功能很容易。首先，将 Capacitor 添加到您的项目中。

ionic integrations enable capacitor

接下来，构建项目，然后添加您选择的平台。

ionic build
ionic cap add ios
ionic cap add android

我们使用标准的原生 IDE（Xcode 和 Android Studio）来打开、构建和运行 iOS 和 Android 项目。

ionic cap open ios
ionic cap open android

更多详细信息可以 在这里 找到。

接下来，查看 所有可用的 API。有一些很棒的东西，包括 Camera API。我们可以在几行代码中实现照片捕获功能。

import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar, IonButton } from '@ionic/react';
import React, { useState } from 'react';
import { Plugins, CameraResultType } from '@capacitor/core';

const Home: React.FC = () => {
  const { Camera } = Plugins;
  const [photo, setPhoto] = useState();
  const takePhoto = async () => {
    const image = await Camera.getPhoto({
      quality: 90,
      allowEditing: true,
      resultType: CameraResultType.Uri,
    });
    setPhoto(image.webPath);
  };
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Ionic Blank</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        <img src={photo} />
        <IonButton onClick={takePhoto}>Take Photo</IonButton>
      </IonContent>
    </IonPage>
  );
};

export default Home;

下一步

本指南介绍了创建 Ionic React 应用程序、添加一些基本导航以及将 Capacitor 作为构建原生应用程序的方式的基本知识。要更深入地了解如何使用 React 和 Capacitor 构建完整的 Ionic 应用程序，请遵循我们的 第一个应用程序指南。

要更详细地了解 Ionic 的组件，请查看 组件 API 页面。有关 React 的更多详细信息，请查看 React 文档。要继续构建原生功能，请查看 Capacitor 文档。

祝您应用程序构建愉快！🎉