添加到现有的 React 项目
本指南介绍了如何将 Ionic React 添加到现有的 React 项目中。如果你想从头开始创建新项目，请参阅 Ionic React 快速入门 指南。有关 Ionic React 如何与 React 配合工作，包括版本支持和工具的概述，请参阅 Ionic React 概览。
🌐 This guide covers how to add Ionic React to an existing React project. If you're looking to start a new project from scratch, check out the Ionic React Quickstart guide. For an overview of how Ionic React works with React, including version support and tooling, check out the Ionic React Overview.
本指南使用 TypeScript 示例。如果你使用的是 JavaScript，设置过程相同，但你将使用 .jsx 文件扩展名而不是 .tsx。
🌐 This guide uses TypeScript examples. If you're using JavaScript, the setup process is the same, but you'll use .jsx file extensions instead of .tsx.
设置
🌐 Setup
本指南遵循使用 Vite 创建的 React 应用的结构。如果你使用其他工具（例如 Create React App）启动你的 React 应用，你的文件结构和设置可能会有所不同。
🌐 This guide follows the structure of a React app created with Vite. If you started your React app using a different tool (such as Create React App), your file structure and setup may differ.
按照以下步骤将 Ionic React 添加到你现有的 React 项目中：
🌐 Follow these steps to add Ionic React to your existing React project:
1. 安装软件包
🌐 1. Install the Package
npm install @ionic/react
2. 配置 Ionic React
🌐 2. Configure Ionic React
更新 src/App.tsx 以包含 setupIonicReact 并导入所需的 Ionic Framework 样式表：
🌐 Update src/App.tsx to include setupIonicReact and import the required Ionic Framework stylesheets:
// ...existing imports...
import { setupIonicReact } from '@ionic/react';
/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import '@ionic/react/css/typography.css';
setupIonicReact();
// ...existing app function and export...
setupIonicReact 是一个函数，用于设置 Ionic React 组件以在你的应用中工作。在使用任何 Ionic React 组件之前，必须调用它。
虽然需要使用 core.css，但 normalize.css、structure.css 和 typography.css 是推荐使用的，但不是必需的。它们可以统一不同浏览器的差异，确保正确的滚动行为，并提供一致的排版和表单样式。如果不使用它们，你可能需要自己处理这些问题。更多详情，请参阅 全局样式表。
🌐 While core.css is required, normalize.css, structure.css, and typography.css are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, refer to Global Stylesheets.
使用单个组件
🌐 Using Individual Components
完成上述设置后，你可以在现有的 React 应用中开始使用 Ionic 组件。以下是如何使用它们的示例：
🌐 After completing the setup above, you can start using Ionic components in your existing React app. Here's an example of how to use them:
将 src/App.tsx 更新为以下内容：
🌐 Update src/App.tsx to the following:
import { IonButton, IonDatetime, setupIonicReact } from '@ionic/react';
import './App.css';
/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import '@ionic/react/css/typography.css';
setupIonicReact();
const App: React.FC = () => (
<>
<IonButton>Button</IonButton>
<IonDatetime></IonDatetime>
</>
);
export default App;
访问 components 页面以获取所有可用的 Ionic 组件。
🌐 Visit the components page for all of the available Ionic components.
如果你现有的 React 应用在 src/main.tsx 中导入了全局样式表（例如 index.css），你可能需要将其移除或更新任何与 Ionic Framework 组件冲突的样式。Ionic Framework 自带自己的 CSS 重置和规范化，这可能会与现有的全局样式发生冲突。
🌐 If your existing React app imports a global stylesheet (such as index.css) in src/main.tsx, you may want to remove it or update any styles that conflict with Ionic Framework components. Ionic Framework includes its own CSS reset and normalization, which may conflict with existing global styles.
使用 Ionic 页面
🌐 Using Ionic Pages
如果你想使用带有完整导航和页面过渡效果的 Ionic 页面，请按照以下额外的设置步骤操作。
🌐 If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
1. 添加额外的 Ionic 框架样式表
🌐 1. Add Additional Ionic Framework Stylesheets
更新 src/App.tsx 中导入的样式表：
🌐 Update the imported stylesheets in src/App.tsx:
/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import '@ionic/react/css/typography.css';
/* Optional CSS utils that can be commented out */
import '@ionic/react/css/padding.css';
import '@ionic/react/css/float-elements.css';
import '@ionic/react/css/text-alignment.css';
import '@ionic/react/css/text-transformation.css';
import '@ionic/react/css/flex-utils.css';
import '@ionic/react/css/display.css';
这些样式表设置了整体页面结构，并提供了用于更快速开发的 CSS 工具。有些样式表是可选的。有关哪些样式表是必需的详细信息，请查看 全局样式表。
🌐 These stylesheets set up the overall page structure and provide CSS utilities for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out Global Stylesheets.
2. 设置主题
🌐 2. Set up Theming
创建一个包含以下内容的 src/theme/variables.css 文件：
🌐 Create a src/theme/variables.css file with the following content:
/* For information on how to create your own theme, please refer to:
https://ionic.nodejs.cn/theming/ */
然后，在 src/App.tsx 中导入该文件和深色调色板样式表：
🌐 Then, import the file and the dark palette stylesheet in src/App.tsx:
// ...existing imports...
// ...existing stylesheets...
/**
* Ionic Dark Mode
* -----------------------------------------------------
* For more info, please refer to:
* https://ionic.nodejs.cn/theming/dark-mode
*/
/* @import '@ionic/react/css/palettes/dark.always.css'; */
/* @import '@ionic/react/css/palettes/dark.class.css'; */
import '@ionic/react/css/palettes/dark.system.css';
/* Theme variables */
import './theme/variables.css';
setupIonicReact();
// ...existing app function and export...
variables.css 文件可用于创建自定义 Ionic Framework 主题。dark.system.css 导入在系统设置为偏好深色外观时，为你的 Ionic 应用启用夜间模式支持。你可以通过取消注释不同的深色调色板导入或向 theme/variables.css 添加自定义 CSS 变量来定制主题行为。
🌐 The variables.css file can be used to create custom Ionic Framework themes. The dark.system.css import enables dark mode support for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables to theme/variables.css.
3. 更新应用组件
🌐 3. Update the App Component
将 src/App.tsx 更新为以下内容：
🌐 Update src/App.tsx to the following:
import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import '@ionic/react/css/typography.css';
/* Optional CSS utils that can be commented out */
import '@ionic/react/css/padding.css';
import '@ionic/react/css/float-elements.css';
import '@ionic/react/css/text-alignment.css';
import '@ionic/react/css/text-transformation.css';
import '@ionic/react/css/flex-utils.css';
import '@ionic/react/css/display.css';
/**
* Ionic Dark Mode
* -----------------------------------------------------
* For more info, please refer to:
* https://ionic.nodejs.cn/theming/dark-mode
*/
/* @import '@ionic/react/css/palettes/dark.always.css'; */
/* @import '@ionic/react/css/palettes/dark.class.css'; */
import '@ionic/react/css/palettes/dark.system.css';
/* Theme variables */
import './theme/variables.css';
setupIonicReact();
const App = () => {
return (
<IonApp>
<IonReactRouter>
<IonRouterOutlet>{/* Routes will be added here */}</IonRouterOutlet>
</IonReactRouter>
</IonApp>
);
};
export default App;
4. 创建首页
🌐 4. Create a Home Page
在 src/pages/Home.tsx 创建一个新文件，内容如下：
🌐 Create a new file at src/pages/Home.tsx with the following:
import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';
import './Home.css';
const Home = () => {
return (
<IonPage>
<IonHeader translucent={true}>
<IonToolbar>
<IonTitle>Home</IonTitle>
</IonToolbar>
</IonHeader>
<IonContent fullscreen={true}>
<IonHeader collapse="condense">
<IonToolbar>
<IonTitle size="large">Home</IonTitle>
</IonToolbar>
</IonHeader>
<div id="container">
<strong>Ready to create an app?</strong>
<p>
Start with Ionic{' '}
<a target="_blank" rel="noopener noreferrer" href="https://ionic.nodejs.cn/components">
UI Components
</a>
</p>
</div>
</IonContent>
</IonPage>
);
};
export default Home;
然后，创建 src/pages/Home.css：
🌐 Then, create src/pages/Home.css:
#container {
text-align: center;
position: absolute;
left: 0;
right: 0;
top: 50%;
transform: translateY(-50%);
}
#container strong {
font-size: 20px;
line-height: 26px;
}
#container p {
font-size: 16px;
line-height: 22px;
color: #8c8c8c;
margin: 0;
}
#container a {
text-decoration: none;
}
5. 设置路由
🌐 5. Set up Routing
Ionic React Router 目前仅支持 React Router v5。你必须安装以下特定版本的路由包才能在 Ionic React 中设置路由。
🌐 Ionic React Router currently only supports React Router v5. You must install the following specific versions of the router packages to set up routing with Ionic React.
安装路由软件包：
🌐 Install the router packages:
npm install @ionic/react-router react-router@5 react-router-dom@5
npm install @types/react-router-dom --save-dev
然后，更新 src/App.tsx 以添加主页的路由：
🌐 Then, update src/App.tsx to add the routes for the Home page:
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';
// ...existing Ionic Framework stylesheet 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 React 应用现在已配置了完整的 Ionic 页面支持。运行 npm run dev 来启动你的开发服务器并查看你的应用。
🌐 You're all set! Your Ionic React app is now configured with full Ionic page support. Run npm run dev to start your development server and view your app.
下一步
🌐 Next Steps
既然你已经将 Ionic React 集成到你的项目中，请查看：
🌐 Now that you have Ionic React integrated into your project, check out:
了解如何在 Ionic React 应用中使用 React Router 处理路由和导航。
探索 Ionic 丰富的 UI 组件库，用于构建美观的应用。
了解如何使用 Ionic 强大的主题系统自定义应用的外观和感觉。
探索如何访问本地设备功能，并使用 Capacitor 将你的应用部署到 iOS、Android 和网络。