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

Template	Description
`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

Run

ionic --help

for the full and always up-to-date command list.

Command	Description
`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/

System preference (default):

@import '@ionic/<framework>/css/palettes/dark.system.css';

Always dark:

@import '@ionic/<framework>/css/palettes/dark.always.css';

CSS class toggle:

@import '@ionic/<framework>/css/palettes/dark.class.css';

then add

.ion-palette-dark

<html>

三种实现方式（从

@ionic/angular/css/

、

@ionic/react/css/

或

@ionic/vue/css/

导入对应文件）：

跟随系统设置（默认）：

@import '@ionic/<framework>/css/palettes/dark.system.css';

始终深色：

@import '@ionic/<framework>/css/palettes/dark.always.css';

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.

Breakpoint	Min Width	Property 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.

Hook	Fires When	Use 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

For full details, see ionic-angular.

Detect architecture: Check

src/main.ts

for

bootstrapApplication

(standalone) vs

platformBrowserDynamic().bootstrapModule

(NgModule).

Aspect	Standalone	NgModule
Ionic setup	`provideIonicAngular({})` in `app.config.ts`	`IonicModule.forRoot()` in `app.module.ts`
Component imports	Each 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

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

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

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 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'
```

ionic-expert

Original

Translation

Ionic Expert

Ionic 专家

Core Concepts

核心概念

Creating a New App

创建新应用

Ionic CLI

Ionic CLI

Components Overview

组件概览

Layout

布局类

Navigation

导航类

Form

表单类

Overlays

浮层类

Data Display

数据展示类

Scroll

滚动相关

Actions & Media

操作与媒体类

Theming

主题定制

Colors

颜色

Global CSS Variables

全局CSS变量

Dark Mode

深色模式

Platform Styles

平台专属样式

Layout

布局

Grid System

栅格系统

CSS Utility Classes

CSS工具类

Page Lifecycle

页面生命周期

Framework-Specific Patterns

框架专属模式

Angular

Angular

React

React

Vue

Vue

Navigation Patterns

导航模式

Tab Navigation

标签栏导航

Side Menu

侧边菜单

Linear vs. Non-Linear Routing

线性 vs 非线性路由

Upgrading

版本升级

Capacitor Integration

Capacitor集成

Capawesome Cloud

Capawesome Cloud

Common Troubleshooting

常见问题排查

Related Skills

相关技能