Ionic React 快速入門簡介

什麼是 Ionic Framework？

首先，如果您是第一次來到這裡，歡迎！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 本身。這允許我們使用類似 HTML 的語法（稱為 JSX）撰寫元件。我們稍後會討論一下 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 導覽文件中提供了更深入的指南，介紹了這些差異。

最後一個重要的匯入是 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 並沒有太多需要修改的地方。這是一個容器元件的基本範例。在設定 Router 邏輯後，它的責任只是呈現符合給定 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.dev.org.tw/docs/">
            docs
          </a>{' '}
          will be your guide.
        </p>
      </IonContent>
    </IonPage>
  );
};

與我們開始使用的 App 元件非常類似，我們有一些針對特定 Ionic 元件的匯入、針對 React 的匯入，然後是我們自己的 React 元件。

IonPage 是所有頁面的基本元件（具有路由/URL 的元件），並且包含完整畫面元件的一些常見建構區塊，例如標頭、標題和內容元件。

注意

在建立您自己的頁面時，請別忘記讓 IonPage 成為它們的根元件。讓 IonPage 成為根元件非常重要，因為它可以協助確保轉換正確運作，並提供 Ionic 元件所依賴的基本 CSS。

IonHeader 具有不言自明的性質。它是一個旨在存在於頁面頂部的元件。IonHeader 本身除了處理一些基於彈性盒的佈局之外，本身沒有做太多事情。它旨在容納其他元件，例如 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 Framework 元件中使用。（有關 slot 的更多資訊，請參閱 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 的 history 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 prop 將其傳遞給 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。有一些很棒的東西，包括 相機 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 文件。

祝您應用程式建置愉快！🎉