ionic-vue

Ionic Vue

使用 Vue 开发 Ionic 应用——涵盖项目结构、组件、导航、生命周期钩子、组合式函数和 Vue 专属模式。

前提条件

1. Ionic Framework 7 或 8，并安装 @ionic/vue。
2. Vue 3。
3. 已安装 Node.js 和 npm。
4. iOS：已安装 Xcode。
5. Android：已安装 Android Studio。

Agent 行为

• 先自动检测，再提问。 检查项目中的 package.json 依赖（@ionic/vue、vue、@capacitor/core）、平台目录（android/、ios/）、构建工具（vite.config.ts）和 TypeScript 使用情况。只有在无法检测时才询问用户。
• 分步引导。 每次引导用户完成一个步骤。不要一次提出多个无关问题。
• 适应项目。 检测项目使用的是 <script setup>（组合式 API）还是选项式 API，并生成符合现有风格的代码。除非项目使用其他模式，否则新文件默认使用 <script setup lang="ts">。

操作步骤

第 1 步：分析项目

通过读取项目文件自动检测以下内容：

1. Ionic 版本：从 package.json 中读取 @ionic/vue 的版本。
2. Vue 版本：从 package.json 中读取 vue 的版本。
3. Capacitor 版本：从 package.json 中读取 @capacitor/core 的版本（如果存在）。
4. TypeScript：检查是否存在 tsconfig.json，以及 .vue 文件是否使用 <script setup lang="ts">。
5. 平台：检查存在哪些目录（android/、ios/）。
6. 路由配置：定位路由文件（通常为 src/router/index.ts）。
7. 项目模板：通过检查路由配置和 App.vue，判断项目使用的是标签页、侧边菜单还是空白模板。

第 2 步：项目结构

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

project-root/
├── android/                  # Android native project (generated by Capacitor)
├── ios/                      # iOS native project (generated by Capacitor)
├── public/
├── src/
│   ├── components/           # Reusable Vue components
│   ├── composables/          # Custom composables
│   ├── router/
│   │   └── index.ts          # Vue Router configuration (uses @ionic/vue-router)
│   ├── theme/
│   │   └── variables.css     # Ionic CSS custom properties
│   ├── views/                # Page components (routed views)
│   ├── App.vue               # Root component (contains IonApp + IonRouterOutlet)
│   └── main.ts               # Entry point (installs IonicVue plugin)
├── capacitor.config.ts       # Capacitor configuration
├── package.json
├── tsconfig.json
└── vite.config.ts

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

第 3 步：应用入口和根组件

入口文件 src/main.ts 会安装 IonicVue 插件并挂载应用：

import { createApp } from 'vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';

/* Ionic CSS */
import '@ionic/vue/css/core.css';
import '@ionic/vue/css/normalize.css';
import '@ionic/vue/css/structure.css';
import '@ionic/vue/css/typography.css';
import '@ionic/vue/css/padding.css';
import '@ionic/vue/css/float-elements.css';
import '@ionic/vue/css/text-alignment.css';
import '@ionic/vue/css/text-transformation.css';
import '@ionic/vue/css/flex-utils.css';
import '@ionic/vue/css/display.css';

/* Theme */
import './theme/variables.css';

const app = createApp(App).use(IonicVue).use(router);

router.isReady().then(() => {
  app.mount('#app');
});

根组件 App.vue 包含 IonApp 和 IonRouterOutlet：

<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

<script setup lang="ts">
import { IonApp, IonRouterOutlet } from '@ionic/vue';
</script>

第 4 步：组件和 IonPage

详细的组件模式请参阅 references/components.md。

关键规则：

1. 从 @ionic/vue 导入所有 Ionic 组件，例如 import { IonButton, IonContent, IonPage } from '@ionic/vue'。
2. 所有路由页面都必须将 IonPage 用作根模板元素。 否则页面切换会失效，Ionic 生命周期钩子也不会触发。
3. 通过 $el 访问 Web Component 方法，例如 contentRef.value.$el.scrollToBottom(300)。
4. 从 ionicons/icons 导入图标的 SVG 引用，不要将图标名称作为字符串传入。
5. 在 Ionic 表单组件上使用 v-model（IonInput、IonToggle、IonSelect、IonCheckbox、IonRange）。
6. 在模板中为 Ionic 事件名使用 kebab-case，例如 @ion-change、@ion-infinite。

第 5 步：导航和路由

详细的路由模式请参阅 references/navigation.md。

关键原则：

1. 从 @ionic/vue-router 导入 createRouter，而不是从 vue-router 导入。Ionic 版本对 Vue Router 进行了封装，以启用页面切换效果。
2. 声明式导航：在 Ionic 组件上使用 router-link 属性，并可选用 router-direction 和 router-animation。
3. 编程式导航：使用 useIonRouter 组合式函数实现 Ionic 专属切换，或使用 vue-router 中的 useRouter 执行标准导航。
4. 懒加载路由，使用 component: () => import('@/views/DetailPage.vue')。
5. 标签页路由：使用嵌套路由配合 IonTabs 和 IonRouterOutlet。每个标签页都维护自己的导航堆栈。
6. 不要在不同标签页之间跨路由——只有标签栏按钮应切换标签页。对于跨标签页共享的视图，请使用 IonModal。

步骤 6：生命周期钩子

阅读 references/lifecycle.md，了解详细的生命周期模式。

关键原则：

1. IonRouterOutlet 会将页面保留在 DOM 中。Vue 的 onMounted 只会在每个页面上触发一次，而不是每次访问时都触发。
2. 使用 Ionic 生命周期钩子，在每次访问页面时运行逻辑：
   • onIonViewWillEnter — 每次页面显示时刷新数据。
   • onIonViewDidEnter — 页面切换结束后启动动画或聚焦输入框。
   • onIonViewWillLeave — 保存状态或取消订阅。
   • onIonViewDidLeave — 清理屏幕外资源。
3. Ionic 生命周期钩子要求 IonPage 是根元素。
4. 只有映射到路由的组件才会接收生命周期钩子——子组件不会。

步骤 7：组合式函数和工具

阅读 references/composables.md，了解组合式函数的详细文档。

@ionic/vue 提供的组合式函数和工具：

函数	用途
useIonRouter()	控制页面切换效果的编程式导航
useBackButton(priority, handler)	处理 Android 硬件返回按钮
useKeyboard()	响应式键盘可见状态和高度
onIonViewWillEnter(cb)	生命周期：页面即将显示
onIonViewDidEnter(cb)	生命周期：页面已完全显示
onIonViewWillLeave(cb)	生命周期：页面即将隐藏
onIonViewDidLeave(cb)	生命周期：页面已完全隐藏
isPlatform(name)	检查当前平台（ios、android、hybrid 等）
getPlatforms()	获取所有匹配平台标识符的数组

步骤 8：平台检测

使用 @ionic/vue 中的 isPlatform，有条件地执行特定平台的逻辑：

<script setup lang="ts">
import { isPlatform } from '@ionic/vue';

const isIOS = isPlatform('ios');
const isAndroid = isPlatform('android');
const isNative = isPlatform('hybrid');
const isMobileWeb = isPlatform('mobileweb');
</script>

<template>
  <div>
    <p v-if="isNative">Running as a native app</p>
    <p v-else>Running in a browser</p>
  </div>
</template>

支持的标识符：android、capacitor、cordova、desktop、electron、hybrid、ios、ipad、iphone、mobile、mobileweb、phablet、pwa、tablet。

步骤 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

错误处理

• Failed to resolve component: ion-*：未导入 Ionic 组件。在 <script> 部分从 @ionic/vue 添加缺少的导入（例如，import { IonButton } from '@ionic/vue'）。
• 页面切换效果不起作用：确认页面组件将 IonPage 用作根模板元素。缺少 IonPage 时，页面切换效果和生命周期钩子会静默失效。
• Ionic 生命周期钩子未触发：确保 IonPage 是根元素，并且组件在路由器配置中直接映射到某个路由。子组件不会触发生命周期钩子。
• Method on component is not a function：通过 $el 访问底层 Web Component，例如 ref.value.$el.scrollToBottom()，而不是 ref.value.scrollToBottom()。
• Slot 属性弃用警告：Ionic 使用 Web Component 插槽，代码检查器会误将其识别为已弃用的 Vue 2 插槽。请禁用 ESLint 规则：'vue/no-deprecated-slot-attribute': 'off'。
• 事件监听器未触发：在模板和 addEventListener 调用中使用 kebab-case 事件名称（ion-modal-did-present）。不要使用 camelCase。
• useIonRouter 或 useBackButton 失败：这些组合式函数在内部使用 Vue 的 inject()，必须在 setup() 或 <script setup> 中调用，不能在独立函数或回调中调用。
• 标签页导航丢失状态：每个标签页都维护自己的堆栈。使用非线性（基于标签页）的路由时，不要调用 router.go()。请改用 useIonRouter().push() 或 router-link。
• Vue 的 onMounted 只触发一次：IonRouterOutlet 会将页面缓存在 DOM 中。对于每次页面显示时都必须运行的逻辑，请使用 onIonViewWillEnter，而不是 onMounted。
• 内容与标签栏或标题栏重叠：页面组件缺少作为根元素的 IonPage。IonPage 会设置正确的弹性盒布局。

相关技能

• ionic-app-development — Ionic 开发通用指南：组件、主题设置和 CLI 用法。
• ionic-app-creation — 从头创建新的 Ionic 应用。
• capacitor-vue — 不使用 Ionic Framework 的 Capacitor 专用 Vue 模式（插件、钩子、服务）。
• ionic-app-upgrades — 将 Ionic Framework 升级到较新版本。