ionic-react

Ionic React

使用 React 开发 Ionic Framework 应用——项目结构、IonReactRouter、React 专用组件、生命周期钩子、状态管理和最佳实践。

前提条件

1. Ionic Framework 7 或 8，并安装 @ionic/react。
2. React 18 或更高版本。
3. 已安装 Node.js 和 npm。
4. iOS：已安装 Xcode。
5. Android：已安装 Android Studio。

Agent 行为

• 先自动检测，再提问。 检查项目中的 package.json 依赖项（@ionic/react、@ionic/react-router、react、@capacitor/core）、平台目录（android/、ios/）、构建工具和 TypeScript 使用情况。只有在无法检测到某项信息时才询问用户。
• 逐步引导。 一次引导用户完成一个步骤。不要一次提出多个无关问题。
• 适应项目。 检测现有代码风格（TypeScript 或 JavaScript、状态管理库、路由设置），并生成风格一致的代码。

操作步骤

步骤 1：分析项目

通过读取项目文件自动检测以下信息：

1. Ionic 版本：从 package.json 读取 @ionic/react 版本。
2. React 版本：从 package.json 读取 react 版本。
3. Capacitor 版本：从 package.json 读取 @capacitor/core 版本（如果存在）。
4. TypeScript：检查是否存在 tsconfig.json，以及是否使用 .tsx 文件。
5. 路由器：检查 package.json 中是否包含 @ionic/react-router 和 react-router-dom。
6. 状态管理：检查 package.json 中是否包含 redux、@reduxjs/toolkit、zustand、jotai、@tanstack/react-query 或类似依赖项。
7. 平台：检查存在哪些目录（android/、ios/）。
8. 构建工具：检查是否存在 vite.config.ts、angular.json、webpack.config.js 等文件。

步骤 2：项目结构

标准的 Ionic React 项目采用以下结构：

project-root/
├── android/                  # Android native project (Capacitor)
├── ios/                      # iOS native project (Capacitor)
├── public/
├── src/
│   ├── components/           # Reusable UI components
│   ├── hooks/                # Custom React hooks
│   ├── pages/                # Page components (one per route)
│   ├── services/             # Service modules for API and native calls
│   ├── context/              # React context providers
│   ├── theme/
│   │   └── variables.css     # Ionic CSS custom properties
│   ├── App.tsx               # Root component with IonReactRouter
│   └── main.tsx              # Entry point with setupIonicReact()
├── capacitor.config.ts       # Capacitor configuration
├── ionic.config.json         # Ionic CLI configuration
├── package.json
├── tsconfig.json
└── vite.config.ts            # Or other bundler config

如果项目不符合此结构，请根据项目的实际目录布局调整所有指导。除非用户明确要求，否则不要重构项目。

步骤 3：应用初始化

入口点必须在渲染应用之前调用 setupIonicReact()。此函数会为 React 初始化 Ionic Framework。

确认 src/main.tsx（或 src/index.tsx）包含：

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

setupIonicReact();

setupIonicReact() 接受一个可选的配置对象，用于设置全局选项：

setupIonicReact({
  mode: 'ios',          // Force iOS mode on all platforms ('ios' | 'md')
  rippleEffect: false,  // Disable Material Design ripple effect
  animated: true,       // Enable/disable all animations
});

如果缺少 setupIonicReact()，或在渲染后才调用它，Ionic 组件将无法正常工作。

步骤 4：路由与导航

阅读 references/routing.md，了解完整的路由模式，包括：

• IonReactRouter 设置
• 使用 IonRouterOutlet 管理页面
• 使用 IonTabs 实现基于标签页的导航
• 使用 IonMenu 实现侧边菜单导航
• 使用 useIonRouter 进行编程式导航
• 路由守卫和路由参数

关键原则：

1. 使用 IonReactRouter，不要使用 React Router 的 BrowserRouter。Ionic 页面过渡需要它。
2. 使用 IonRouterOutlet 容纳路由。它负责管理页面堆栈和过渡动画。
3. 向 Route 传入 component 属性——不要在 IonRouterOutlet 内使用 render 或 children。
4. 使用 useIonRouter 进行编程式导航——它提供支持 Ionic 的导航和过渡动画。

步骤 5：Ionic 生命周期钩子

阅读 references/lifecycle.md，了解生命周期钩子的详细用法。

导航后，Ionic React 页面仍会挂载在 DOM 中。标准 React useEffect 只会在初次挂载时触发，而不会在每次访问页面时触发。对于每次访问页面时都要执行的逻辑，请使用 Ionic 生命周期钩子：

钩子	用途
useIonViewWillEnter	在页面变为可见之前刷新数据
useIonViewDidEnter	页面可见后启动动画或聚焦输入框
useIonViewWillLeave	暂停媒体、保存草稿状态
useIonViewDidLeave	页面完全隐藏后执行清理操作

这些钩子仅适用于满足以下条件的组件：

• 在 IonRouterOutlet 内的 Route 中作为 component 渲染。
• 将 IonPage 渲染为根元素。

步骤 6：React 专用 Ionic 钩子

阅读 references/hooks.md，了解所有可用钩子及其用法示例。

Ionic React 提供了用于显示覆盖层和控制导航的钩子，无需手动管理状态：

钩子	用途
useIonAlert	显示警告对话框
useIonToast	显示 Toast 通知
useIonActionSheet	显示操作表
useIonLoading	显示/关闭加载指示器
useIonModal	以编程方式显示模态框
useIonPopover	以编程方式显示弹出框
useIonPicker	显示选择器对话框
useIonRouter	使用 Ionic 动画进行导航

步骤 7：React 专用组件模式

阅读 references/components.md，了解详细的组件模式，包括：

• 使用 IonPage 的页面结构
• 使用 isOpen 绑定的内联覆盖层（模态框、弹出框）
• 使用 IonRefresher 实现下拉刷新
• 使用 IonInfiniteScroll 实现无限滚动
• 使用 Ionic 输入组件构建表单

关键原则：

1. 每个页面都必须将 IonPage 渲染为根元素。 这是页面过渡和生命周期钩子的必要条件。
2. 文本输入使用 onIonInput，选择器、切换开关、复选框和范围组件使用 onIonChange。
3. 通过 e.detail.value 获取值（切换开关/复选框则使用 e.detail.checked）。
4. 使用 isOpen 控制内联覆盖层，以简化状态管理；也可以使用覆盖层钩子（useIonModal、useIonAlert 等）进行命令式操作。

步骤 8：状态管理

阅读 references/state-management.md，了解 React Context、Redux Toolkit、Zustand 和 TanStack Query 的模式。

关键原则：

1. 页面缓存会影响状态。 由于 Ionic 会让页面保持挂载，状态会在导航过程中保留。使用 useIonViewWillEnter 刷新过时数据。
2. 将提供程序放在 IonReactRouter 外部。 Context 提供程序、Redux Provider 和 QueryClientProvider 应包裹路由，以便所有页面都能访问。
3. 非必要时不要添加状态库。 对于简单应用，React Context 和 useState/useReducer 已足够。

步骤 9：构建并运行

完成更改后：

npm run build
npx cap sync
npx cap run android
npx cap run ios

开发时启用实时重载：

ionic serve

进行原生开发时启用实时重载：

ionic cap run android --livereload --external
ionic cap run ios --livereload --external

错误处理

• Ionic 生命周期钩子未触发：确认组件将 IonPage 作为根元素渲染，并且是 IonRouterOutlet 内某个 Route 的 component。生命周期钩子不会在子组件中触发，也不会在通过 render/children 属性渲染的组件中触发。
• 页面转场没有动画：确保使用 IonReactRouter，而不是 BrowserRouter。确保路由使用 component 属性，而不是 render 或 children。确认 IonRouterOutlet 是 IonReactRouter 或 IonTabs 的直接子元素。
• 返回导航后数据过时：Ionic 会让页面继续挂载在 DOM 中。使用 useIonViewWillEnter 在每次访问页面时刷新数据，而不是使用 [] 依赖项的 useEffect。
• 子页面上标签栏消失：所有路由（包括详情路由）都必须位于 IonTabs 内的 IonRouterOutlet 中。不要在标签页中再嵌套单独的 IonRouterOutlet。
• setupIonicReact 出错或组件未渲染：确保在入口文件中，于 ReactDOM.createRoot() 或 ReactDOM.render() 之前调用 setupIonicReact()。确保已导入所有 Ionic CSS 文件（参见 src/App.tsx 或 src/main.tsx 中的 Ionic CSS 导入）。
• IonBackButton 未显示：只有存在导航历史时，IonBackButton 才会渲染。设置 defaultHref 属性，为直接访问页面时提供备用路由。
• 表单输入值未更新：对于 IonInput/IonTextarea，使用 onIonInput（不要使用 onChange）。对于 IonSelect、IonToggle、IonCheckbox、IonRange，使用 onIonChange。通过 e.detail.value 获取值。
• 模态框或弹出框内容未应用样式：确保覆盖层内容由 IonContent 包裹。对于模态框，如果需要工具栏，请包含 IonHeader 和 IonToolbar。
• React 严格模式导致组件重复挂载：在开发环境中，React 18 严格模式会将组件挂载两次。这可能导致 Ionic 事件监听器重复。确保清理函数能正确移除监听器。
• useIonRouter 返回 undefined：必须在 IonReactRouter 的后代组件中使用此钩子。确认组件树中有 IonReactRouter 作为祖先。
• CSS 自定义属性未生效：确保在 src/App.tsx 或 src/main.tsx 中按正确顺序导入 Ionic CSS 文件。主题 variables.css 文件必须在 Ionic 核心 CSS 之后导入。

相关技能

• ionic-app-development — 涵盖组件、主题和 CLI 用法的一般 Ionic 开发。
• ionic-app-creation — 从头开始创建新的 Ionic 应用。
• capacitor-react — 用于访问原生设备功能的 Capacitor 专用 React 模式（不使用 Ionic Framework）。
• ionic-app-upgrades — 将 Ionic Framework 升级到较新版本。
• capacitor-plugins — 从官方和社区来源安装、配置和使用 Capacitor 插件。