Back to Details

ionic-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ionic Expert

Ionic 专家

Comprehensive reference for Ionic Framework development — core concepts, components, theming, lifecycle, navigation, framework-specific patterns (Angular, React, Vue), upgrading, and Capawesome Cloud integration.
Ionic Framework开发的全面参考指南，涵盖核心概念、组件、主题定制、生命周期、导航、框架专属模式（Angular、React、Vue）、版本升级以及Capawesome Cloud集成。

Core Concepts

核心概念

Ionic Framework is a UI toolkit for building cross-platform apps with web technologies. It provides 80+ pre-built UI components as Web Components prefixed with 
ion-
(e.g., 
<ion-button>
, 
<ion-content>
).
  • Platform modes: Components adapt styling to the platform. iOS devices use 
    ios
    mode; Android and all other platforms use 
    md
    (Material Design). The 
    <html>
    element receives a class (
    ios
    or 
    md
    ).
  • Capacitor integration: Ionic handles the UI; Capacitor handles native device APIs. See the 
    capacitor-app-development
    skill for Capacitor guidance.
  • Framework support: Ionic integrates with Angular (
    @ionic/angular
    ), React (
    @ionic/react
    ), and Vue (
    @ionic/vue
    ).
Ionic Framework是使用Web技术构建跨平台应用的UI工具集，提供80+开箱即用的UI组件，均为带
ion-
前缀的Web Components（例如
<ion-button>
、
<ion-content>
）。
  • 平台模式：组件会根据运行平台自动适配样式。iOS设备使用
    ios
    模式；Android及其他所有平台使用
    md
    （Material Design）模式，
    <html>
    元素会自动添加对应的类（
    ios
    或
    md
    ）。
  • Capacitor集成：Ionic负责UI层，Capacitor负责原生设备API调用。Capacitor相关使用指南可参考
    capacitor-app-development
    技能文档。
  • 框架支持：Ionic可与Angular（
    @ionic/angular
    ）、React（
    @ionic/react
    ）、Vue（
    @ionic/vue
    ）集成。

Creating a New App

创建新应用

bash
npm install -g @ionic/cli
ionic start <name> <template> --type=<framework> --capacitor --package-id=<id>
--type
value		Framework
angular
Angular (NgModules)
angular-standalone
Angular (Standalone Components)
react
React
vue
Vue
TemplateDescription
blank
Empty project, single page
tabs
Tab-based layout
sidemenu
Side menu layout
For details, see ionic-app-creation.
bash
npm install -g @ionic/cli
ionic start <name> <template> --type=<framework> --capacitor --package-id=<id>
--type
取值		对应框架
angular
Angular（NgModules模式）
angular-standalone
Angular（独立组件模式）
react
React
vue
Vue
模板名说明
blank
空项目，仅包含单个页面
tabs
基于标签栏的布局
sidemenu
侧边菜单布局
详情请参考ionic-app-creation。

Ionic CLI

Ionic CLI

Run 
ionic --help
for the full and always up-to-date command list.
CommandDescription
ionic start
Scaffold a new Ionic project.
ionic serve
Start a local dev server with live reload (port 8100).
ionic build
Build the web app for production.
ionic generate
Generate pages, components, services (framework-dependent).
ionic info
Print system/environment info.
ionic repair
Remove and recreate dependencies and platform files.
Useful 
ionic serve
flags: 
--external
(all network interfaces), 
--port=<port>
, 
--prod
, 
--no-open
.
运行
ionic --help
可查看完整的、最新的命令列表。
命令说明
ionic start
脚手架生成新的Ionic项目
ionic serve
启动带热重载的本地开发服务器（默认端口8100）
ionic build
构建生产环境的Web应用
ionic generate
生成页面、组件、服务（依赖所使用的框架）
ionic info
打印系统/环境信息
ionic repair
移除并重建依赖和平台相关文件
常用的
ionic serve
参数：
--external
（监听所有网络接口）、
--port=<port>
（指定端口）、
--prod
、
--no-open
（启动后不自动打开浏览器）。

Components Overview

组件概览

Ionic provides 80+ UI components organized by category. For full API reference (properties, events, methods, slots, CSS custom properties), see the linked reference files.
Ionic提供80+按类别整理的UI组件，完整的API参考（属性、事件、方法、插槽、CSS自定义属性）可查看对应的参考文档。

Layout

布局类

ion-app
(root container), 
ion-content
(scrollable area), 
ion-header
, 
ion-footer
, 
ion-toolbar
, 
ion-title
, 
ion-buttons
, 
ion-back-button
, 
ion-grid
/
ion-row
/
ion-col
, 
ion-split-pane
.
Key usage:
html
<ion-header>
  <ion-toolbar>
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/home"></ion-back-button>
    </ion-buttons>
    <ion-title>Page Title</ion-title>
  </ion-toolbar>
</ion-header>
<ion-content>
  <!-- Scrollable content -->
</ion-content>
For details, see components-layout.md.
ion-app
（根容器）、
ion-content
（可滚动区域）、
ion-header
、
ion-footer
、
ion-toolbar
、
ion-title
、
ion-buttons
、
ion-back-button
、
ion-grid
/
ion-row
/
ion-col
、
ion-split-pane
。
核心用法：
html
<ion-header>
  <ion-toolbar>
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/home"></ion-back-button>
    </ion-buttons>
    <ion-title>页面标题</ion-title>
  </ion-toolbar>
</ion-header>
<ion-content>
  <!-- 可滚动内容 -->
</ion-content>
详情请参考components-layout.md。

Navigation

导航类

ion-tabs
, 
ion-tab-bar
, 
ion-tab-button
, 
ion-menu
, 
ion-menu-button
, 
ion-menu-toggle
, 
ion-router-outlet
, 
ion-nav
, 
ion-breadcrumbs
.
For details, see components-navigation.md.
ion-tabs
、
ion-tab-bar
、
ion-tab-button
、
ion-menu
、
ion-menu-button
、
ion-menu-toggle
、
ion-router-outlet
、
ion-nav
、
ion-breadcrumbs
。
详情请参考components-navigation.md。

Form

表单类

ion-input
, 
ion-textarea
, 
ion-select
/
ion-select-option
, 
ion-checkbox
, 
ion-toggle
, 
ion-radio
/
ion-radio-group
, 
ion-range
, 
ion-datetime
/
ion-datetime-button
, 
ion-searchbar
, 
ion-segment
/
ion-segment-button
, 
ion-input-otp
.
Key properties shared by most form components: 
label
, 
labelPlacement
(
floating
, 
stacked
, 
fixed
, 
start
), 
fill
(
outline
, 
solid
), 
errorText
, 
helperText
, 
disabled
, 
value
, 
placeholder
.
Key events:
  • ionInput
    — fires on each keystroke (use for 
    ion-input
    /
    ion-textarea
    ).
  • ionChange
    — fires when value is committed (use for 
    ion-select
    , 
    ion-toggle
    , 
    ion-checkbox
    , 
    ion-range
    ).
html
<ion-input label="Email" labelPlacement="floating" fill="outline"
           type="email" placeholder="you@example.com"
           errorText="Invalid email" helperText="Enter your email">
</ion-input>

<ion-select label="Country" labelPlacement="floating" fill="outline" interface="popover">
  <ion-select-option value="us">United States</ion-select-option>
  <ion-select-option value="de">Germany</ion-select-option>
</ion-select>
For details, see components-form.md.
ion-input
、
ion-textarea
、
ion-select
/
ion-select-option
、
ion-checkbox
、
ion-toggle
、
ion-radio
/
ion-radio-group
、
ion-range
、
ion-datetime
/
ion-datetime-button
、
ion-searchbar
、
ion-segment
/
ion-segment-button
、
ion-input-otp
。
大多数表单组件共享的核心属性：
label
、
labelPlacement
（
floating
、
stacked
、
fixed
、
start
）、
fill
（
outline
、
solid
）、
errorText
、
helperText
、
disabled
、
value
、
placeholder
。
核心事件：
  • ionInput
    — 每次按键时触发（适用于
    ion-input
    /
    ion-textarea
    ）
  • ionChange
    — 值确认修改时触发（适用于
    ion-select
    、
    ion-toggle
    、
    ion-checkbox
    、
    ion-range
    ）
html
<ion-input label="邮箱" labelPlacement="floating" fill="outline"
           type="email" placeholder="you@example.com"
           errorText="邮箱格式无效" helperText="请输入你的邮箱">
</ion-input>

<ion-select label="国家" labelPlacement="floating" fill="outline" interface="popover">
  <ion-select-option value="us">美国</ion-select-option>
  <ion-select-option value="de">德国</ion-select-option>
</ion-select>
详情请参考components-form.md。

Overlays

浮层类

ion-modal
, 
ion-alert
, 
ion-toast
, 
ion-action-sheet
, 
ion-loading
, 
ion-popover
.
All overlays share: 
isOpen
prop for declarative control, 
trigger
prop to open from a button ID, 
backdropDismiss
, 
animated
, and lifecycle events (
didPresent
, 
didDismiss
, 
willPresent
, 
willDismiss
).
Sheet modal (bottom sheet):
html
<ion-modal [isOpen]="isOpen" [breakpoints]="[0, 0.5, 1]" [initialBreakpoint]="0.5" [handle]="true">
  <ion-content>Sheet content</ion-content>
</ion-modal>
For details, see components-overlay.md.
ion-modal
、
ion-alert
、
ion-toast
、
ion-action-sheet
、
ion-loading
、
ion-popover
。
所有浮层共享的特性：
isOpen
属性用于声明式控制显隐、
trigger
属性绑定按钮ID实现点击打开、
backdropDismiss
、
animated
，以及生命周期事件（
didPresent
、
didDismiss
、
willPresent
、
willDismiss
）。
底部弹窗（Sheet modal）：
html
<ion-modal [isOpen]="isOpen" [breakpoints]="[0, 0.5, 1]" [initialBreakpoint]="0.5" [handle]="true">
  <ion-content>弹窗内容</ion-content>
</ion-modal>
详情请参考components-overlay.md。

Data Display

数据展示类

ion-list
, 
ion-item
, 
ion-item-sliding
/
ion-item-options
/
ion-item-option
, 
ion-card
/
ion-card-header
/
ion-card-content
, 
ion-accordion
/
ion-accordion-group
, 
ion-chip
, 
ion-badge
, 
ion-label
, 
ion-note
.
For details, see components-data-display.md.
ion-list
、
ion-item
、
ion-item-sliding
/
ion-item-options
/
ion-item-option
、
ion-card
/
ion-card-header
/
ion-card-content
、
ion-accordion
/
ion-accordion-group
、
ion-chip
、
ion-badge
、
ion-label
、
ion-note
。
详情请参考components-data-display.md。

Scroll

滚动相关

ion-refresher
/
ion-refresher-content
(pull-to-refresh), 
ion-infinite-scroll
/
ion-infinite-scroll-content
, 
ion-reorder-group
/
ion-reorder
.
For details, see components-scroll.md.
ion-refresher
/
ion-refresher-content
（下拉刷新）、
ion-infinite-scroll
/
ion-infinite-scroll-content
（上拉加载更多）、
ion-reorder-group
/
ion-reorder
（拖拽排序）。
详情请参考components-scroll.md。

Actions & Media

操作与媒体类

ion-button
, 
ion-fab
/
ion-fab-button
, 
ion-icon
, 
ion-avatar
, 
ion-thumbnail
, 
ion-spinner
, 
ion-skeleton-text
, 
ion-progress-bar
.
For details, see components-action.md and components-media.md.
ion-button
、
ion-fab
/
ion-fab-button
、
ion-icon
、
ion-avatar
、
ion-thumbnail
、
ion-spinner
、
ion-skeleton-text
、
ion-progress-bar
。
详情请参考components-action.md和components-media.md。

Theming

主题定制

Colors

颜色

Nine default colors: 
primary
, 
secondary
, 
tertiary
, 
success
, 
warning
, 
danger
, 
light
, 
medium
, 
dark
. Apply via the 
color
attribute:
html
<ion-button color="primary">Save</ion-button>
<ion-button color="danger">Delete</ion-button>
Customize a color by overriding all six CSS variables in 
:root
:
css
:root {
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3171e0;
  --ion-color-primary-tint: #4c8dff;
}
默认提供9种颜色：
primary
、
secondary
、
tertiary
、
success
、
warning
、
danger
、
light
、
medium
、
dark
，通过
color
属性使用：
html
<ion-button color="primary">保存</ion-button>
<ion-button color="danger">删除</ion-button>
可通过在
:root
中覆盖对应的6个CSS变量来自定义颜色：
css
:root {
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3171e0;
  --ion-color-primary-tint: #4c8dff;
}

Global CSS Variables

全局CSS变量

Key variables: 
--ion-background-color
, 
--ion-text-color
, 
--ion-font-family
, 
--ion-safe-area-top/right/bottom/left
, 
--ion-margin
, 
--ion-padding
.
核心变量：
--ion-background-color
、
--ion-text-color
、
--ion-font-family
、
--ion-safe-area-top/right/bottom/left
、
--ion-margin
、
--ion-padding
。

Dark Mode

深色模式

Three approaches (import from 
@ionic/angular/css/
, 
@ionic/react/css/
, or 
@ionic/vue/css/
):
  1. System preference (default): 
    @import '@ionic/<framework>/css/palettes/dark.system.css';
  2. Always dark: 
    @import '@ionic/<framework>/css/palettes/dark.always.css';
  3. CSS class toggle: 
    @import '@ionic/<framework>/css/palettes/dark.class.css';
    then add 
    .ion-palette-dark
    to 
    <html>
    .
三种实现方式（从
@ionic/angular/css/
、
@ionic/react/css/
或
@ionic/vue/css/
导入对应文件）：
  1. 跟随系统设置（默认）：
    @import '@ionic/<framework>/css/palettes/dark.system.css';
  2. 始终深色：
    @import '@ionic/<framework>/css/palettes/dark.always.css';
  3. CSS类切换：
    @import '@ionic/<framework>/css/palettes/dark.class.css';
    ，之后给
    <html>
    添加
    .ion-palette-dark
    类即可开启深色模式。

Platform Styles

平台专属样式

Target platform-specific styles in CSS using the mode class on 
<html>
:
css
.ios ion-toolbar { --background: #f8f8f8; }
.md ion-toolbar { --background: #ffffff; }
Preview a specific mode in the browser: 
http://localhost:8100/?ionic:mode=ios
可通过
<html>
上的模式类在CSS中针对不同平台写专属样式：
css
.ios ion-toolbar { --background: #f8f8f8; }
.md ion-toolbar { --background: #ffffff; }
在浏览器中预览指定模式：
http://localhost:8100/?ionic:mode=ios

Layout

布局

Grid System

栅格系统

12-column flexbox grid: 
ion-grid
, 
ion-row
, 
ion-col
. Columns expand evenly unless 
size
(1-12) is specified.
BreakpointMin WidthProperty Suffix
xs
0
Xs
sm
576px
Sm
md
768px
Md
lg
992px
Lg
xl
1200px
Xl
基于flexbox的12列栅格系统：
ion-grid
、
ion-row
、
ion-col
。未指定
size
（1-12）时列会均匀分配宽度。
断点最小宽度属性后缀
xs
0
Xs
sm
576px
Sm
md
768px
Md
lg
992px
Lg
xl
1200px
Xl

CSS Utility Classes

CSS工具类

  • Padding: 
    .ion-padding
    , 
    .ion-padding-top/bottom/start/end
    , 
    .ion-no-padding
  • Margin: 
    .ion-margin
    , 
    .ion-margin-top/bottom/start/end
    , 
    .ion-no-margin
  • Text: 
    .ion-text-center
    , 
    .ion-text-start
    , 
    .ion-text-end
    , 
    .ion-text-wrap
    , 
    .ion-text-nowrap
  • Display: 
    .ion-display-none
    , 
    .ion-display-block
    , 
    .ion-display-flex
  • Flex: 
    .ion-justify-content-center
    , 
    .ion-align-items-center
    , 
    .ion-flex-row
    , 
    .ion-flex-column
All utility classes support responsive suffixes: 
.ion-text-md-center
(applies at 768px+).
  • 内边距：
    .ion-padding
    、
    .ion-padding-top/bottom/start/end
    、
    .ion-no-padding
  • 外边距：
    .ion-margin
    、
    .ion-margin-top/bottom/start/end
    、
    .ion-no-margin
  • 文本：
    .ion-text-center
    、
    .ion-text-start
    、
    .ion-text-end
    、
    .ion-text-wrap
    、
    .ion-text-nowrap
  • 显示：
    .ion-display-none
    、
    .ion-display-block
    、
    .ion-display-flex
  • Flex：
    .ion-justify-content-center
    、
    .ion-align-items-center
    、
    .ion-flex-row
    、
    .ion-flex-column
所有工具类都支持响应式后缀：例如
.ion-text-md-center
仅在768px以上宽度生效。

Page Lifecycle

页面生命周期

Ionic provides four lifecycle hooks that fire during page transitions. These exist because 
ion-router-outlet
caches pages in the DOM — framework-native lifecycle hooks (
ngOnInit
, 
useEffect
, 
onMounted
) only fire once on first creation, not on every page visit.
HookFires WhenUse For
ionViewWillEnter
Page about to enter (pre-animation)Refresh data on every visit
ionViewDidEnter
Page fully entered (post-animation)Start animations, focus inputs
ionViewWillLeave
Page about to leave (pre-animation)Save state, pause subscriptions
ionViewDidLeave
Page fully left (post-animation)Clean up off-screen resources
Critical rules:
  • Only fire on components directly mapped to a route via 
    ion-router-outlet
    .
  • Child components do not receive these events.
  • The component must use the framework-specific page wrapper (see framework sections below).
Ionic提供4个页面转场时触发的生命周期钩子。这些钩子存在的原因是
ion-router-outlet
会在DOM中缓存页面——框架原生的生命周期钩子（
ngOnInit
、
useEffect
、
onMounted
）仅在页面首次创建时触发一次，不会在每次进入页面时触发。
钩子触发时机适用场景
ionViewWillEnter
页面即将进入（动画开始前）每次进入页面时刷新数据
ionViewDidEnter
页面完全进入（动画结束后）启动动画、聚焦输入框
ionViewWillLeave
页面即将离开（动画开始前）保存状态、暂停订阅
ionViewDidLeave
页面完全离开（动画结束后）清理页外资源
重要规则：
  • 仅直接通过
    ion-router-outlet
    映射到路由的组件才会触发这些钩子
  • 子组件不会收到这些生命周期事件
  • 组件必须使用对应框架的页面包装器（参考下文框架专属模式章节）

Framework-Specific Patterns

框架专属模式

Angular

Angular

For full details, see ionic-angular.
Detect architecture: Check 
src/main.ts
for 
bootstrapApplication
(standalone) vs 
platformBrowserDynamic().bootstrapModule
(NgModule).
AspectStandaloneNgModule
Ionic setup
provideIonicAngular({})
in 
app.config.ts
IonicModule.forRoot()
in 
app.module.ts
Component importsEach from 
@ionic/angular/standalone
IonicModule
provides all globally
Lazy loading
loadComponent
in routes
loadChildren
in routes
Icons
addIcons()
from 
ionicons
required		Automatic
Navigation: Use 
NavController
from 
@ionic/angular
for animated navigation (
navigateForward
, 
navigateBack
, 
navigateRoot
, 
back
). Use 
routerLink
with 
routerDirection
in templates.
Lifecycle: Implement interfaces 
ViewWillEnter
, 
ViewDidEnter
, 
ViewWillLeave
, 
ViewDidLeave
from 
@ionic/angular
:
typescript
import { ViewWillEnter } from '@ionic/angular';

@Component({ /* ... */ })
export class HomePage implements ViewWillEnter {
  ionViewWillEnter() {
    this.loadData(); // Runs on every page visit
  }
}
For navigation details, see angular/navigation.md. For lifecycle details, see angular/lifecycle.md.
完整详情请参考ionic-angular。
判断架构模式：查看
src/main.ts
，如果有
bootstrapApplication
则是独立组件模式，如果是
platformBrowserDynamic().bootstrapModule
则是NgModule模式。
维度独立组件模式NgModule模式
Ionic初始化在
app.config.ts
中配置
provideIonicAngular({})
在
app.module.ts
中配置
IonicModule.forRoot()
组件导入每个组件都从
@ionic/angular/standalone
单独导入
IonicModule
全局提供所有组件
懒加载路由中使用
loadComponent
路由中使用
loadChildren
图标需要从
ionicons
调用
addIcons()
注册所需图标		自动加载
导航：使用
@ionic/angular
提供的
NavController
实现带动画的导航（
navigateForward
、
navigateBack
、
navigateRoot
、
back
），模板中可搭配
routerDirection
使用
routerLink
。
生命周期：实现
@ionic/angular
提供的
ViewWillEnter
、
ViewDidEnter
、
ViewWillLeave
、
ViewDidLeave
接口：
typescript
import { ViewWillEnter } from '@ionic/angular';

@Component({ /* ... */ })
export class HomePage implements ViewWillEnter {
  ionViewWillEnter() {
    this.loadData(); // 每次进入页面都会执行
  }
}
导航详情请参考angular/navigation.md，生命周期详情请参考angular/lifecycle.md。

React

React

For full details, see ionic-react.
Key setup differences:
  • Call 
    setupIonicReact()
    before rendering in 
    src/main.tsx
    .
  • Use 
    IonReactRouter
    (from 
    @ionic/react-router
    ) instead of 
    BrowserRouter
    .
  • Use 
    IonRouterOutlet
    to contain routes with the 
    component
    prop (not 
    render
    or 
    children
    ).
  • Every page must render 
    IonPage
    as root     — required for transitions and lifecycle hooks.
Navigation: Use 
useIonRouter
hook for programmatic navigation:
typescript
import { useIonRouter } from '@ionic/react';

const router = useIonRouter();
router.push('/detail/123', 'forward', 'push');
router.goBack();
Lifecycle hooks (from 
@ionic/react
):
typescript
import { useIonViewWillEnter } from '@ionic/react';

useIonViewWillEnter(() => {
  fetchData(); // Runs on every page visit
});
Overlay hooks: 
useIonAlert
, 
useIonToast
, 
useIonActionSheet
, 
useIonLoading
, 
useIonModal
, 
useIonPopover
, 
useIonPicker
.
Form events: Use 
onIonInput
for 
IonInput
/
IonTextarea
, 
onIonChange
for 
IonSelect
/
IonToggle
/
IonCheckbox
/
IonRange
. Access values via 
e.detail.value
.
For routing details, see react/routing.md. For hooks, see react/hooks.md.
完整详情请参考ionic-react。
核心初始化差异：
  • 在
    src/main.tsx
    中渲染应用前调用
    setupIonicReact()
  • 使用
    @ionic/react-router
    提供的
    IonReactRouter
    代替原生的
    BrowserRouter
  • 使用
    IonRouterOutlet
    容纳路由，必须使用
    component
    属性（不能用
    render
    或
    children
    ）
  • 每个页面的根组件必须是
    IonPage
    ——这是转场动画和生命周期钩子生效的必要条件
导航：使用
useIonRouter
钩子实现编程式导航：
typescript
import { useIonRouter } from '@ionic/react';

const router = useIonRouter();
router.push('/detail/123', 'forward', 'push');
router.goBack();
生命周期钩子（来自
@ionic/react
）：
typescript
import { useIonViewWillEnter } from '@ionic/react';

useIonViewWillEnter(() => {
  fetchData(); // 每次进入页面都会执行
});
浮层钩子：
useIonAlert
、
useIonToast
、
useIonActionSheet
、
useIonLoading
、
useIonModal
、
useIonPopover
、
useIonPicker
。
表单事件：
IonInput
/
IonTextarea
使用
onIonInput
，
IonSelect
/
IonToggle
/
IonCheckbox
/
IonRange
使用
onIonChange
，通过
e.detail.value
获取值。
路由详情请参考react/routing.md，钩子详情请参考react/hooks.md。

Vue

Vue

For full details, see ionic-vue.
Key setup differences:
  • Install 
    IonicVue
    plugin in 
    src/main.ts
    : 
    createApp(App).use(IonicVue).use(router)
    .
  • Import 
    createRouter
    from 
    @ionic/vue-router
    (not from 
    vue-router
    ).
  • Every page must use 
    IonPage
    as root template element     — without it, transitions and lifecycle hooks silently fail.
  • Import all Ionic components from 
    @ionic/vue
    .
  • Use kebab-case for event names in templates (
    @ion-change
    , 
    @ion-input
    ).
  • Import icons as SVG references from 
    ionicons/icons
    — never as strings.
Navigation: Use 
useIonRouter
composable:
vue
<script setup lang="ts">
import { useIonRouter } from '@ionic/vue';

const ionRouter = useIonRouter();
ionRouter.push('/detail/123');
ionRouter.back();
</script>
Declarative: 
<ion-button router-link="/detail" router-direction="forward">Go</ion-button>
Lifecycle hooks (from 
@ionic/vue
):
vue
<script setup lang="ts">
import { onIonViewWillEnter } from '@ionic/vue';

onIonViewWillEnter(() => {
  fetchData(); // Runs on every page visit
});
</script>
Composables: 
useIonRouter()
, 
useBackButton(priority, handler)
, 
useKeyboard()
, 
isPlatform(name)
, 
getPlatforms()
.
Access Web Component methods via 
$el
: 
contentRef.value.$el.scrollToBottom(300)
.
For navigation details, see vue/navigation.md. For composables, see vue/composables.md.
完整详情请参考ionic-vue。
核心初始化差异：
  • 在
    src/main.ts
    中安装
    IonicVue
    插件：
    createApp(App).use(IonicVue).use(router)
  • 从
    @ionic/vue-router
    导入
    createRouter
    （不要从
    vue-router
    导入）
  • 每个页面的模板根元素必须是
    IonPage
    ——缺少的话转场动画和生命周期钩子会静默失效
  • 所有Ionic组件都从
    @ionic/vue
    导入
  • 模板中事件名使用短横线命名（
    @ion-change
    、
    @ion-input
    ）
  • 图标从
    ionicons/icons
    导入为SVG引用，不要用字符串形式
导航：使用
useIonRouter
组合式函数：
vue
<script setup lang="ts">
import { useIonRouter } from '@ionic/vue';

const ionRouter = useIonRouter();
ionRouter.push('/detail/123');
ionRouter.back();
</script>
声明式导航：
<ion-button router-link="/detail" router-direction="forward">跳转</ion-button>
生命周期钩子（来自
@ionic/vue
）：
vue
<script setup lang="ts">
import { onIonViewWillEnter } from '@ionic/vue';

onIonViewWillEnter(() => {
  fetchData(); // 每次进入页面都会执行
});
</script>
组合式函数：
useIonRouter()
、
useBackButton(priority, handler)
、
useKeyboard()
、
isPlatform(name)
、
getPlatforms()
。
通过
$el
访问Web Component方法：
contentRef.value.$el.scrollToBottom(300)
。
导航详情请参考vue/navigation.md，组合式函数详情请参考vue/composables.md。

Navigation Patterns

导航模式

Tab Navigation

标签栏导航

Each framework uses 
ion-tabs
with 
ion-tab-bar
and child routes per tab. Each tab maintains its own navigation stack.
Rules:
  • The 
    tab
    attribute on 
    ion-tab-button
    must match the child route path.
  • Never navigate between tabs programmatically — only the tab bar buttons should switch tabs.
  • For shared views across tabs, use 
    ion-modal
    instead of cross-tab routing.
所有框架都使用
ion-tabs
搭配
ion-tab-bar
，每个标签对应子路由，每个标签维护独立的导航栈。
规则：
  • ion-tab-button
    的
    tab
    属性必须和子路由路径匹配
  • 不要通过编程方式在标签之间跳转，仅通过标签栏按钮切换标签
  • 标签间共享的页面使用
    ion-modal
    实现，不要跨标签路由

Side Menu

侧边菜单

Use 
ion-menu
with 
contentId
matching the 
id
on 
ion-router-outlet
. Wrap menu items in 
ion-menu-toggle
to auto-close after selection. Use 
routerDirection="root"
for top-level menu navigation.
使用
ion-menu
，其
contentId
要和
ion-router-outlet
的
id
匹配。菜单项用
ion-menu-toggle
包裹，实现点击后自动关闭菜单。顶层菜单导航使用
routerDirection="root"
。

Linear vs. Non-Linear Routing

线性 vs 非线性路由

  • Linear: Sequential forward/back navigation (list -> detail -> edit). Back button returns to the previous page.
  • Non-linear: Multiple independent stacks (tabs). Back navigation stays within the current tab's stack.
Use non-linear routing for tabs or split-pane layouts. Use linear routing for simple page flows.
  • 线性：顺序前进/后退导航（列表 -> 详情 -> 编辑），返回按钮回到上一个页面
  • 非线性：多个独立的导航栈（标签栏），返回操作仅在当前标签的栈内生效
标签栏或分栏布局使用非线性路由，简单页面流使用线性路由。

Upgrading

版本升级

Ionic supports upgrades from version 4 through 8. Each major version jump must be applied sequentially — do not skip intermediate versions.
For full upgrade guides, see ionic-app-upgrades.
Ionic支持从4版本升级到8版本，大版本升级必须依次执行，不要跳过中间版本。
完整的升级指南请参考ionic-app-upgrades。

Capacitor Integration

Capacitor集成

Ionic apps use Capacitor for native device features (camera, filesystem, push notifications, etc.). The standard workflow:
bash
npm run build
npx cap sync
npx cap run android
npx cap run ios
For live reload on a device:
bash
ionic cap run android --livereload --external
ionic cap run ios --livereload --external
For Capacitor guidance, see the 
capacitor-app-development
skill.
Ionic应用使用Capacitor调用原生设备功能（相机、文件系统、推送通知等），标准工作流：
bash
npm run build
npx cap sync
npx cap run android
npx cap run ios
设备上热重载开发：
bash
ionic cap run android --livereload --external
ionic cap run ios --livereload --external
Capacitor使用指南请参考
capacitor-app-development
技能文档。

Capawesome Cloud

Capawesome Cloud

Capawesome Cloud provides CI/CD services for Ionic/Capacitor apps:
  • Live Updates — Deploy OTA updates to Ionic/Capacitor apps instantly, without app store review.
  • Native Builds — Build iOS and Android binaries in the cloud without local Xcode or Android Studio.
  • App Store Publishing — Automate submissions to the Apple App Store and Google Play Store.
Visit capawesome.io for the full Capawesome ecosystem. For setup, see the 
capawesome-cloud
skill.
Capawesome Cloud为Ionic/Capacitor应用提供CI/CD服务：
  • 热更新：无需应用商店审核，即时向Ionic/Capacitor应用推送OTA更新
  • 云端原生构建：无需本地安装Xcode或Android Studio，云端构建iOS和Android安装包
  • 应用商店发布：自动提交应用到苹果App Store和谷歌Play商店
访问capawesome.io了解完整的Capawesome生态，配置指南请参考
capawesome-cloud
技能文档。

Common Troubleshooting

常见问题排查

  • ionic: command not found
    : Run 
    npm install -g @ionic/cli
    .
  • Components not rendering: Verify Ionic CSS files are imported in the global stylesheet. For standalone Angular, verify each component is imported from 
    @ionic/angular/standalone
    .
  • ionViewWillEnter
    not firing    : The component must be directly routed via 
    ion-router-outlet
    . Child components do not receive lifecycle events. For React/Vue, verify 
    IonPage
    is the root element.
  • Page data not refreshing on back navigation: Use Ionic lifecycle hooks (
    ionViewWillEnter
    ) instead of framework-native lifecycle hooks (
    ngOnInit
    , 
    useEffect
    , 
    onMounted
    ). Ionic caches pages in the DOM.
  • Page transitions not animating: Use the framework's Ionic router integration (
    NavController
    for Angular, 
    IonReactRouter
    for React, 
    createRouter
    from 
    @ionic/vue-router
    for Vue). Standard framework routers do not trigger Ionic animations.
  • CSS custom properties not applying: Ionic components use Shadow DOM. Use documented CSS custom properties (
    --background
    , 
    --color
    ) instead of targeting internal elements.
  • Icons not showing (Angular standalone): Call 
    addIcons()
    from 
    ionicons
    with the required icons and import 
    IonIcon
    from 
    @ionic/angular/standalone
    .
  • Failed to resolve component: ion-*
    (Vue)    : The Ionic component is not imported. Add the import from 
    @ionic/vue
    .
  • Tab bar disappears on sub-page (React): All routes (including detail routes) must be inside the 
    IonRouterOutlet
    within 
    IonTabs
    .
  • Form input values not updating (React): Use 
    onIonInput
    for 
    IonInput
    /
    IonTextarea
    , not 
    onChange
    . Access values via 
    e.detail.value
    .
  • Slot attribute deprecation warning (Vue): Ionic uses Web Component slots. Disable the ESLint rule: 
    'vue/no-deprecated-slot-attribute': 'off'
    .
  • ionic: command not found
    ：运行
    npm install -g @ionic/cli
  • 组件不渲染：确认全局样式表中已导入Ionic的CSS文件。Angular独立组件模式下，确认每个组件都从
    @ionic/angular/standalone
    导入
  • ionViewWillEnter
    不触发    ：组件必须是直接通过
    ion-router-outlet
    路由的页面，子组件不会收到生命周期事件。React/Vue项目确认页面根元素是
    IonPage
  • 返回页面时数据不刷新：使用Ionic的生命周期钩子（
    ionViewWillEnter
    ）代替框架原生的生命周期钩子（
    ngOnInit
    、
    useEffect
    、
    onMounted
    ），因为Ionic会在DOM中缓存页面
  • 页面转场没有动画：使用框架对应的Ionic路由集成（Angular用
    NavController
    ，React用
    IonReactRouter
    ，Vue用
    @ionic/vue-router
    的
    createRouter
    ），标准框架路由不会触发Ionic的动画
  • CSS自定义属性不生效：Ionic组件使用Shadow DOM，使用官方文档提供的CSS自定义属性（
    --background
    、
    --color
    ），不要直接修改内部元素
  • 图标不显示（Angular独立组件模式）：调用
    ionicons
    的
    addIcons()
    注册所需图标，并且从
    @ionic/angular/standalone
    导入
    IonIcon
  • Failed to resolve component: ion-*
    （Vue）    ：未导入对应的Ionic组件，从
    @ionic/vue
    导入即可
  • 进入子页面后标签栏消失（React）：所有路由（包括详情页路由）都必须放在
    IonTabs
    内部的
    IonRouterOutlet
    中
  • 表单输入值不更新（React）：
    IonInput
    /
    IonTextarea
    使用
    onIonInput
    而不是
    onChange
    ，通过
    e.detail.value
    获取值
  • 插槽属性弃用警告（Vue）：Ionic使用Web Component插槽，关闭ESLint规则：
    'vue/no-deprecated-slot-attribute': 'off'

Related Skills

相关技能