ionic-vue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ionic Vue

Ionic Vue

Develop Ionic apps with Vue — project structure, components, navigation, lifecycle hooks, composables, and Vue-specific patterns.
使用Vue开发Ionic应用——涵盖项目结构、组件、导航、生命周期钩子、组合式函数及Vue专属开发模式。

Prerequisites

前置条件

  1. Ionic Framework 7 or 8 with
    @ionic/vue
    .
  2. Vue 3.
  3. Node.js and npm installed.
  4. For iOS: Xcode installed.
  5. For Android: Android Studio installed.
  1. Ionic Framework 7或8,并安装
    @ionic/vue
    。
  2. Vue 3。
  3. 已安装Node.js和npm。
  4. 针对iOS:需安装Xcode。
  5. 针对Android:需安装Android Studio。

Agent Behavior

Agent行为规范

  • Auto-detect before asking. Check the project for
    package.json
    dependencies (
    @ionic/vue
    ,
    vue
    ,
    @capacitor/core
    ), platforms (
    android/
    ,
    ios/
    ), build tools (
    vite.config.ts
    ), and TypeScript usage. Only ask the user when something cannot be detected.
  • 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
    <script setup>
    (Composition API) or Options API and generate code that matches the existing style. Default to
    <script setup lang="ts">
    for new files unless the project uses a different pattern.
  • 先自动检测再询问:检查项目的
    package.json
    依赖(
    @ionic/vue
    、
    vue
    、
    @capacitor/core
    )、平台目录(
    android/
    、
    ios/
    )、构建工具(
    vite.config.ts
    )及TypeScript使用情况。仅在无法自动检测时才询问用户。
  • 分步引导:逐步引导用户完成流程,切勿同时提出多个无关问题。
  • 适配现有项目:检测项目是否使用
    <script setup>
    (组合式API)或选项式API,并生成与现有代码风格匹配的代码。默认使用
    <script setup lang="ts">
    创建新文件,除非项目采用其他模式。

Procedures

操作流程

Step 1: Analyze the Project

步骤1:分析项目

Auto-detect the following by reading project files:
  1. Ionic version: Read
    @ionic/vue
    version from
    package.json
    .
  2. Vue version: Read
    vue
    version from
    package.json
    .
  3. Capacitor version: Read
    @capacitor/core
    version from
    package.json
    (if present).
  4. TypeScript: Check if
    tsconfig.json
    exists and if
    .vue
    files use
    <script setup lang="ts">
    .
  5. Platforms: Check which directories exist (
    android/
    ,
    ios/
    ).
  6. Router config: Locate the router file (typically
    src/router/index.ts
    ).
  7. Project template: Determine if the project uses tabs, side-menu, or blank template by examining the router configuration and
    App.vue
    .
通过读取项目文件自动检测以下内容:
  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
    ,确定项目使用标签栏、侧边菜单还是空白模板。

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.ts
If 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
src/main.ts
installs the IonicVue plugin and mounts the app:
typescript
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
App.vue
contains
IonApp
and
IonRouterOutlet
:
vue
<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>

<script setup lang="ts">
import { IonApp, IonRouterOutlet } from '@ionic/vue';
</script>
入口文件
src/main.ts
负责安装IonicVue插件并挂载应用:
typescript
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
:
vue
<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
references/components.md
for detailed component patterns.
Key rules:
  1. Import all Ionic components from
    @ionic/vue
    — e.g.,
    import { IonButton, IonContent, IonPage } from '@ionic/vue'
    .
  2. Every routed page must use
    IonPage
    as its root template element. Without it, page transitions break and Ionic lifecycle hooks do not fire.
  3. Access Web Component methods via
    $el
    — e.g.,
    contentRef.value.$el.scrollToBottom(300)
    .
  4. Import icons as SVG references from
    ionicons/icons
    — never pass icon names as strings.
  5. Use
    v-model
    on Ionic form components (
    IonInput
    ,
    IonToggle
    ,
    IonSelect
    ,
    IonCheckbox
    ,
    IonRange
    ).
  6. Use kebab-case for Ionic event names in templates — e.g.,
    @ion-change
    ,
    @ion-infinite
    .
详细组件模式请查阅
references/components.md
。
核心规则:
  1. 从
    @ionic/vue
    导入所有Ionic组件
    ——例如:
    import { IonButton, IonContent, IonPage } from '@ionic/vue'
    。
  2. 所有路由页面必须以
    IonPage
    作为根模板元素
    。否则页面过渡会失效,Ionic生命周期钩子也无法触发。
  3. 通过
    $el
    访问Web组件方法
    ——例如:
    contentRef.value.$el.scrollToBottom(300)
    。
  4. 从
    ionicons/icons
    导入SVG格式图标
    ——切勿将图标名称作为字符串传入。
  5. 在Ionic表单组件上使用
    v-model
    (
    IonInput
    、
    IonToggle
    、
    IonSelect
    、
    IonCheckbox
    、
    IonRange
    )。
  6. 模板中Ionic事件名称使用短横线命名法——例如:
    @ion-change
    、
    @ion-infinite
    。

Step 5: Navigation and Routing

步骤5:导航与路由

Read
references/navigation.md
for detailed routing patterns.
Key principles:
  1. Import
    createRouter
    from
    @ionic/vue-router
    , not from
    vue-router
    . The Ionic version wraps Vue Router to enable page transitions.
  2. Declarative navigation: Use
    router-link
    attribute on Ionic components with optional
    router-direction
    and
    router-animation
    .
  3. Programmatic navigation: Use the
    useIonRouter
    composable for Ionic-specific transitions, or
    useRouter
    from
    vue-router
    for standard navigation.
  4. Lazy load routes with
    component: () => import('@/views/DetailPage.vue')
    .
  5. Tab routing: Use nested routes with
    IonTabs
    and
    IonRouterOutlet
    . Each tab maintains its own navigation stack.
  6. Never cross-route between tabs — only tab bar buttons should switch tabs. Use
    IonModal
    for views shared across tabs.
详细路由模式请查阅
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
    。

Step 6: Lifecycle Hooks

步骤6:生命周期钩子

Read
references/lifecycle.md
for detailed lifecycle patterns.
Key principles:
  1. IonRouterOutlet
    keeps pages in the DOM. Vue's
    onMounted
    fires only once per page, not on every visit.
  2. Use Ionic lifecycle hooks to run logic on every page visit:
    • onIonViewWillEnter
      — Refresh data every time the page appears.
    • onIonViewDidEnter
      — Start animations or focus inputs after the page transition finishes.
    • onIonViewWillLeave
      — Save state or unsubscribe.
    • onIonViewDidLeave
      — Clean up off-screen resources.
  3. Ionic lifecycle hooks require
    IonPage
    as the root element.
  4. Only router-mapped components receive lifecycle hooks — child components do not.
详细生命周期模式请查阅
references/lifecycle.md
。
核心原则:
  1. IonRouterOutlet
    会将页面保存在DOM中。Vue的
    onMounted
    仅在页面首次加载时触发,而非每次访问时触发。
  2. 使用Ionic生命周期钩子在每次页面访问时执行逻辑:
    • onIonViewWillEnter
      —— 每次页面显示时刷新数据。
    • onIonViewDidEnter
      —— 页面过渡完成后启动动画或聚焦输入框。
    • onIonViewWillLeave
      —— 保存状态或取消订阅。
    • onIonViewDidLeave
      —— 清理后台资源。
  3. Ionic生命周期钩子要求页面以
    IonPage
    作为根元素。
  4. 仅路由映射的组件会收到生命周期钩子——子组件不会触发。

Step 7: Composables and Utilities

步骤7:组合式函数与工具

Read
references/composables.md
for detailed composable documentation.
Available composables and utilities from
@ionic/vue
:
FunctionPurpose
useIonRouter()
Programmatic navigation with transition control
useBackButton(priority, handler)
Handle Android hardware back button
useKeyboard()
Reactive keyboard visibility and height
onIonViewWillEnter(cb)
Lifecycle: page about to show
onIonViewDidEnter(cb)
Lifecycle: page fully visible
onIonViewWillLeave(cb)
Lifecycle: page about to hide
onIonViewDidLeave(cb)
Lifecycle: page fully hidden
isPlatform(name)
Check current platform (
ios
,
android
,
hybrid
, etc.)
getPlatforms()
Get array of all matching platform identifiers
详细组合式函数文档请查阅
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()
获取所有匹配的平台标识符数组

Step 8: Platform Detection

步骤8:平台检测

Use
isPlatform
from
@ionic/vue
to conditionally execute platform-specific logic:
vue
<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:
android
,
capacitor
,
cordova
,
desktop
,
electron
,
hybrid
,
ios
,
ipad
,
iphone
,
mobile
,
mobileweb
,
phablet
,
pwa
,
tablet
.
使用
@ionic/vue
的
isPlatform
有条件地执行平台专属逻辑:
vue
<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>
支持的标识符:
android
、
capacitor
、
cordova
、
desktop
、
electron
、
hybrid
、
ios
、
ipad
、
iphone
、
mobile
、
mobileweb
、
phablet
、
pwa
、
tablet
。

Step 9: Build and Run

步骤9:构建与运行

After implementing changes:
bash
npm run build
npx cap sync
npx cap run android
npx cap run ios
For development with live reload:
bash
ionic serve
For 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 --external

Error Handling

错误处理

  • Failed to resolve component: ion-*
    : The Ionic component is not imported. Add the missing import from
    @ionic/vue
    in the
    <script>
    section (e.g.,
    import { IonButton } from '@ionic/vue'
    ).
  • Page transitions not working: Verify that the page component uses
    IonPage
    as its root template element. Without
    IonPage
    , transitions and lifecycle hooks silently fail.
  • Ionic lifecycle hooks not firing: Ensure
    IonPage
    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.
  • Method on component is not a function
    : Access the underlying Web Component via
    $el
    — e.g.,
    ref.value.$el.scrollToBottom()
    , not
    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 (
    ion-modal-did-present
    ) and in
    addEventListener
    calls. Do not use camelCase.
  • useIonRouter
    or
    useBackButton
    fails
    : These composables use Vue's
    inject()
    internally and must be called inside
    setup()
    or
    <script setup>
    , not in standalone functions or callbacks.
  • Tab navigation loses state: Each tab maintains its own stack. Do not use
    router.go()
    with non-linear (tab-based) routing. Use
    useIonRouter().push()
    or
    router-link
    instead.
  • Vue
    onMounted
    fires only once
    :
    IonRouterOutlet
    caches pages in the DOM. Use
    onIonViewWillEnter
    instead of
    onMounted
    for logic that must run every time the page is shown.
  • Content overlaps tab bar or header: The page component is missing
    IonPage
    as the root element.
    IonPage
    sets up the proper flexbox layout.
  • 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组件——例如:
    ref.value.$el.scrollToBottom()
    ,而非
    ref.value.scrollToBottom()
    。
  • 插槽属性弃用警告:Ionic使用Web组件插槽,而代码检查工具会误判为Vue 2弃用插槽。禁用ESLint规则:
    'vue/no-deprecated-slot-attribute': 'off'
    。
  • 事件监听器未触发:模板中使用短横线命名法的事件名称(
    ion-modal-did-present
    ),
    addEventListener
    调用中也需使用短横线命名法,请勿使用驼峰命名法。
  • useIonRouter
    或
    useBackButton
    调用失败
    :这些组合式函数内部使用Vue的
    inject()
    ,必须在
    setup()
    或
    <script setup>
    中调用,不可在独立函数或回调中调用。
  • 标签栏导航丢失状态:每个标签栏维护独立的导航栈。请勿在非线性(基于标签栏的)路由中使用
    router.go()
    ,应使用
    useIonRouter().push()
    或
    router-link
    替代。
  • Vue
    onMounted
    仅触发一次
    :
    IonRouterOutlet
    会在DOM中缓存页面。若需每次页面显示时执行逻辑,请使用
    onIonViewWillEnter
    替代
    onMounted
    。
  • 内容覆盖标签栏或页眉:页面组件缺失
    IonPage
    作为根元素。
    IonPage
    会设置正确的Flexbox布局。

Related Skills

相关技能

  • ionic-app-development
    — General Ionic development guidance: components, theming, CLI usage.
  • ionic-app-creation
    — Create a new Ionic app from scratch.
  • capacitor-vue
    — Capacitor-specific Vue patterns (plugins, hooks, services) without Ionic Framework.
  • ionic-app-upgrades
    — Upgrade Ionic Framework to a newer version.
  • ionic-app-development
    —— 通用Ionic开发指导:组件、主题定制、CLI使用。
  • ionic-app-creation
    —— 从零创建新Ionic应用。
  • capacitor-vue
    —— 无Ionic Framework的Capacitor专属Vue模式(插件、钩子、服务)。
  • ionic-app-upgrades
    —— 将Ionic Framework升级至新版本。