ionic-vue
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseIonic Vue
Ionic Vue
Develop Ionic apps with Vue — project structure, components, navigation, lifecycle hooks, composables, and Vue-specific patterns.
使用Vue开发Ionic应用——涵盖项目结构、组件、导航、生命周期钩子、组合式函数及Vue专属开发模式。
Prerequisites
前置条件
- Ionic Framework 7 or 8 with .
@ionic/vue - Vue 3.
- Node.js and npm installed.
- For iOS: Xcode installed.
- For Android: Android Studio installed.
- Ionic Framework 7或8,并安装。
@ionic/vue - Vue 3。
- 已安装Node.js和npm。
- 针对iOS:需安装Xcode。
- 针对Android:需安装Android Studio。
Agent Behavior
Agent行为规范
- Auto-detect before asking. Check the project for dependencies (
package.json,@ionic/vue,vue), platforms (@capacitor/core,android/), build tools (ios/), and TypeScript usage. Only ask the user when something cannot be detected.vite.config.ts - Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
- Adapt to the project. Detect whether the project uses (Composition API) or Options API and generate code that matches the existing style. Default to
<script setup>for new files unless the project uses a different pattern.<script setup lang="ts">
- 先自动检测再询问:检查项目的依赖(
package.json、@ionic/vue、vue)、平台目录(@capacitor/core、android/)、构建工具(ios/)及TypeScript使用情况。仅在无法自动检测时才询问用户。vite.config.ts - 分步引导:逐步引导用户完成流程,切勿同时提出多个无关问题。
- 适配现有项目:检测项目是否使用(组合式API)或选项式API,并生成与现有代码风格匹配的代码。默认使用
<script setup>创建新文件,除非项目采用其他模式。<script setup lang="ts">
Procedures
操作流程
Step 1: Analyze the Project
步骤1:分析项目
Auto-detect the following by reading project files:
- Ionic version: Read version from
@ionic/vue.package.json - Vue version: Read version from
vue.package.json - Capacitor version: Read version from
@capacitor/core(if present).package.json - TypeScript: Check if exists and if
tsconfig.jsonfiles use.vue.<script setup lang="ts"> - Platforms: Check which directories exist (,
android/).ios/ - Router config: Locate the router file (typically ).
src/router/index.ts - Project template: Determine if the project uses tabs, side-menu, or blank template by examining the router configuration and .
App.vue
通过读取项目文件自动检测以下内容:
- Ionic版本:从读取
package.json版本。@ionic/vue - Vue版本:从读取
package.json版本。vue - Capacitor版本:从读取
package.json版本(若存在)。@capacitor/core - TypeScript:检查是否存在,以及
tsconfig.json文件是否使用.vue。<script setup lang="ts"> - 平台支持:检查存在哪些目录(、
android/)。ios/ - 路由配置:定位路由文件(通常为)。
src/router/index.ts - 项目模板:通过检查路由配置和,确定项目使用标签栏、侧边菜单还是空白模板。
App.vue
Step 2: Project Structure
步骤2:项目结构
A standard Ionic Vue project follows this structure:
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.tsIf the project does not follow this structure, adapt all guidance to the project's actual directory layout. Do not restructure the project unless the user explicitly asks.
标准Ionic Vue项目遵循以下结构:
project-root/
├── android/ # Capacitor生成的Android原生项目
├── ios/ # Capacitor生成的iOS原生项目
├── public/
├── src/
│ ├── components/ # 可复用Vue组件
│ ├── composables/ # 自定义组合式函数
│ ├── router/
│ │ └── index.ts # Vue Router配置(使用@ionic/vue-router)
│ ├── theme/
│ │ └── variables.css # Ionic CSS自定义属性
│ ├── views/ # 页面组件(路由视图)
│ ├── App.vue # 根组件(包含IonApp + IonRouterOutlet)
│ └── main.ts # 入口文件(安装IonicVue插件)
├── capacitor.config.ts # Capacitor配置文件
├── package.json
├── tsconfig.json
└── vite.config.ts若项目未遵循此结构,所有指导内容需适配项目实际目录布局。除非用户明确要求,否则不得重构项目。
Step 3: App Entry Point and Root Component
步骤3:应用入口与根组件
The entry point installs the IonicVue plugin and mounts the app:
src/main.tstypescript
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');
});The root contains and :
App.vueIonAppIonRouterOutletvue
<template>
<ion-app>
<ion-router-outlet />
</ion-app>
</template>
<script setup lang="ts">
import { IonApp, IonRouterOutlet } from '@ionic/vue';
</script>入口文件负责安装IonicVue插件并挂载应用:
src/main.tstypescript
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.vueIonAppIonRouterOutletvue
<template>
<ion-app>
<ion-router-outlet />
</ion-app>
</template>
<script setup lang="ts">
import { IonApp, IonRouterOutlet } from '@ionic/vue';
</script>Step 4: Components and IonPage
步骤4:组件与IonPage
Read for detailed component patterns.
references/components.mdKey rules:
- Import all Ionic components from — e.g.,
@ionic/vue.import { IonButton, IonContent, IonPage } from '@ionic/vue' - Every routed page must use as its root template element. Without it, page transitions break and Ionic lifecycle hooks do not fire.
IonPage - Access Web Component methods via — e.g.,
$el.contentRef.value.$el.scrollToBottom(300) - Import icons as SVG references from — never pass icon names as strings.
ionicons/icons - Use on Ionic form components (
v-model,IonInput,IonToggle,IonSelect,IonCheckbox).IonRange - Use kebab-case for Ionic event names in templates — e.g., ,
@ion-change.@ion-infinite
详细组件模式请查阅。
references/components.md核心规则:
- 从导入所有Ionic组件——例如:
@ionic/vue。import { IonButton, IonContent, IonPage } from '@ionic/vue' - 所有路由页面必须以作为根模板元素。否则页面过渡会失效,Ionic生命周期钩子也无法触发。
IonPage - 通过访问Web组件方法——例如:
$el。contentRef.value.$el.scrollToBottom(300) - 从导入SVG格式图标——切勿将图标名称作为字符串传入。
ionicons/icons - 在Ionic表单组件上使用(
v-model、IonInput、IonToggle、IonSelect、IonCheckbox)。IonRange - 模板中Ionic事件名称使用短横线命名法——例如:、
@ion-change。@ion-infinite
Step 5: Navigation and Routing
步骤5:导航与路由
Read for detailed routing patterns.
references/navigation.mdKey principles:
- Import from
createRouter, not from@ionic/vue-router. The Ionic version wraps Vue Router to enable page transitions.vue-router - Declarative navigation: Use attribute on Ionic components with optional
router-linkandrouter-direction.router-animation - Programmatic navigation: Use the composable for Ionic-specific transitions, or
useIonRouterfromuseRouterfor standard navigation.vue-router - Lazy load routes with .
component: () => import('@/views/DetailPage.vue') - Tab routing: Use nested routes with and
IonTabs. Each tab maintains its own navigation stack.IonRouterOutlet - Never cross-route between tabs — only tab bar buttons should switch tabs. Use for views shared across tabs.
IonModal
详细路由模式请查阅。
references/navigation.md核心原则:
- 从导入
@ionic/vue-router,而非createRouter。Ionic版本封装了Vue Router以支持页面过渡效果。vue-router - 声明式导航:在Ionic组件上使用属性,可搭配可选的
router-link和router-direction。router-animation - 编程式导航:使用组合式函数实现Ionic专属过渡效果,或使用
useIonRouter的vue-router进行标准导航。useRouter - 懒加载路由:使用。
component: () => import('@/views/DetailPage.vue') - 标签栏路由:使用嵌套路由搭配和
IonTabs。每个标签栏维护独立的导航栈。IonRouterOutlet - 切勿跨标签栏路由——仅标签栏按钮可切换标签。跨标签共享视图请使用。
IonModal
Step 6: Lifecycle Hooks
步骤6:生命周期钩子
Read for detailed lifecycle patterns.
references/lifecycle.mdKey principles:
- keeps pages in the DOM. Vue's
IonRouterOutletfires only once per page, not on every visit.onMounted - Use Ionic lifecycle hooks to run logic on every page visit:
- — Refresh data every time the page appears.
onIonViewWillEnter - — Start animations or focus inputs after the page transition finishes.
onIonViewDidEnter - — Save state or unsubscribe.
onIonViewWillLeave - — Clean up off-screen resources.
onIonViewDidLeave
- Ionic lifecycle hooks require as the root element.
IonPage - Only router-mapped components receive lifecycle hooks — child components do not.
详细生命周期模式请查阅。
references/lifecycle.md核心原则:
- 会将页面保存在DOM中。Vue的
IonRouterOutlet仅在页面首次加载时触发,而非每次访问时触发。onMounted - 使用Ionic生命周期钩子在每次页面访问时执行逻辑:
- —— 每次页面显示时刷新数据。
onIonViewWillEnter - —— 页面过渡完成后启动动画或聚焦输入框。
onIonViewDidEnter - —— 保存状态或取消订阅。
onIonViewWillLeave - —— 清理后台资源。
onIonViewDidLeave
- Ionic生命周期钩子要求页面以作为根元素。
IonPage - 仅路由映射的组件会收到生命周期钩子——子组件不会触发。
Step 7: Composables and Utilities
步骤7:组合式函数与工具
Read for detailed composable documentation.
references/composables.mdAvailable composables and utilities from :
@ionic/vue| Function | Purpose |
|---|---|
| Programmatic navigation with transition control |
| Handle Android hardware back button |
| Reactive keyboard visibility and height |
| Lifecycle: page about to show |
| Lifecycle: page fully visible |
| Lifecycle: page about to hide |
| Lifecycle: page fully hidden |
| Check current platform ( |
| Get array of all matching platform identifiers |
详细组合式函数文档请查阅。
references/composables.md@ionic/vue| 函数 | 用途 |
|---|---|
| 带过渡控制的编程式导航 |
| 处理Android硬件返回按钮 |
| 响应式键盘可见性与高度 |
| 生命周期:页面即将显示 |
| 生命周期:页面完全可见 |
| 生命周期:页面即将隐藏 |
| 生命周期:页面完全隐藏 |
| 检查当前平台( |
| 获取所有匹配的平台标识符数组 |
Step 8: Platform Detection
步骤8:平台检测
Use from to conditionally execute platform-specific logic:
isPlatform@ionic/vuevue
<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>Supported identifiers: , , , , , , , , , , , , , .
androidcapacitorcordovadesktopelectronhybridiosipadiphonemobilemobilewebphabletpwatablet使用的有条件地执行平台专属逻辑:
@ionic/vueisPlatformvue
<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">以原生应用运行</p>
<p v-else>在浏览器中运行</p>
</div>
</template>支持的标识符:、、、、、、、、、、、、、。
androidcapacitorcordovadesktopelectronhybridiosipadiphonemobilemobilewebphabletpwatabletStep 9: Build and Run
步骤9:构建与运行
After implementing changes:
bash
npm run build
npx cap sync
npx cap run android
npx cap run iosFor development with live reload:
bash
ionic serveFor native live reload:
bash
ionic cap run android --livereload --external
ionic cap run ios --livereload --external完成修改后执行以下命令:
bash
npm run build
npx cap sync
npx cap run android
npx cap run ios启用热重载的开发模式:
bash
ionic serve原生应用热重载:
bash
ionic cap run android --livereload --external
ionic cap run ios --livereload --externalError Handling
错误处理
- : The Ionic component is not imported. Add the missing import from
Failed to resolve component: ion-*in the@ionic/vuesection (e.g.,<script>).import { IonButton } from '@ionic/vue' - Page transitions not working: Verify that the page component uses as its root template element. Without
IonPage, transitions and lifecycle hooks silently fail.IonPage - Ionic lifecycle hooks not firing: Ensure is the root element and the component is directly mapped to a route in the router configuration. Lifecycle hooks do not fire on child components.
IonPage - : Access the underlying Web Component via
Method on component is not a function— e.g.,$el, notref.value.$el.scrollToBottom().ref.value.scrollToBottom() - Slot attribute deprecation warning: Ionic uses Web Component slots, which linters misidentify as deprecated Vue 2 slots. Disable the ESLint rule: .
'vue/no-deprecated-slot-attribute': 'off' - Event listeners not firing: Use kebab-case event names in templates () and in
ion-modal-did-presentcalls. Do not use camelCase.addEventListener - or
useIonRouterfails: These composables use Vue'suseBackButtoninternally and must be called insideinject()orsetup(), not in standalone functions or callbacks.<script setup> - Tab navigation loses state: Each tab maintains its own stack. Do not use with non-linear (tab-based) routing. Use
router.go()oruseIonRouter().push()instead.router-link - Vue fires only once:
onMountedcaches pages in the DOM. UseIonRouterOutletinstead ofonIonViewWillEnterfor logic that must run every time the page is shown.onMounted - Content overlaps tab bar or header: The page component is missing as the root element.
IonPagesets up the proper flexbox layout.IonPage
- :未导入Ionic组件。在
Failed to resolve component: ion-*部分添加缺失的<script>导入(例如:@ionic/vue)。import { IonButton } from '@ionic/vue' - 页面过渡失效:验证页面组件是否以作为根模板元素。若无
IonPage,过渡效果和生命周期钩子会静默失效。IonPage - Ionic生命周期钩子未触发:确保页面以为根元素,且组件直接映射到路由配置中的路由。子组件不会触发生命周期钩子。
IonPage - :通过
Method on component is not a function访问底层Web组件——例如:$el,而非ref.value.$el.scrollToBottom()。ref.value.scrollToBottom() - 插槽属性弃用警告:Ionic使用Web组件插槽,而代码检查工具会误判为Vue 2弃用插槽。禁用ESLint规则:。
'vue/no-deprecated-slot-attribute': 'off' - 事件监听器未触发:模板中使用短横线命名法的事件名称(),
ion-modal-did-present调用中也需使用短横线命名法,请勿使用驼峰命名法。addEventListener - 或
useIonRouter调用失败:这些组合式函数内部使用Vue的useBackButton,必须在inject()或setup()中调用,不可在独立函数或回调中调用。<script setup> - 标签栏导航丢失状态:每个标签栏维护独立的导航栈。请勿在非线性(基于标签栏的)路由中使用,应使用
router.go()或useIonRouter().push()替代。router-link - Vue 仅触发一次:
onMounted会在DOM中缓存页面。若需每次页面显示时执行逻辑,请使用IonRouterOutlet替代onIonViewWillEnter。onMounted - 内容覆盖标签栏或页眉:页面组件缺失作为根元素。
IonPage会设置正确的Flexbox布局。IonPage
Related Skills
相关技能
- — General Ionic development guidance: components, theming, CLI usage.
ionic-app-development - — Create a new Ionic app from scratch.
ionic-app-creation - — Capacitor-specific Vue patterns (plugins, hooks, services) without Ionic Framework.
capacitor-vue - — Upgrade Ionic Framework to a newer version.
ionic-app-upgrades
- —— 通用Ionic开发指导:组件、主题定制、CLI使用。
ionic-app-development - —— 从零创建新Ionic应用。
ionic-app-creation - —— 无Ionic Framework的Capacitor专属Vue模式(插件、钩子、服务)。
capacitor-vue - —— 将Ionic Framework升级至新版本。
ionic-app-upgrades