Back to Details

ionic-app-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ionic App Development

Ionic应用开发

General Ionic Framework development — core concepts, component reference, CLI usage, layout, theming, utilities, development workflow, and troubleshooting.
通用Ionic Framework开发指南——包含核心概念、组件参考、CLI用法、布局、主题定制、工具函数、开发工作流以及问题排查。

Prerequisites

前置条件

  1. Node.js (latest LTS) installed.
  2. Ionic CLI installed globally (
    npm install -g @ionic/cli
    ).
  3. An existing Ionic project. For creating a new Ionic app, use the 
    ionic-app-creation
     skill.
  1. 已安装Node.js（最新LTS版本）。
  2. 已全局安装Ionic CLI（
    npm install -g @ionic/cli
    ）。
  3. 已有一个现成的Ionic项目。如需创建新Ionic应用，请使用**
    ionic-app-creation
    **技能。

Agent Behavior

Agent行为规范

  • Auto-detect the framework. Check 
    package.json
    for 
    @ionic/angular
    , 
    @ionic/react
    , or 
    @ionic/vue
    to determine the framework in use. Adapt code examples accordingly.
  • Route to reference files. This skill is an overview that routes agents to specific reference files for detailed component APIs and topic-specific guidance.
  • Do not duplicate framework-specific skills. For Angular, React, or Vue specific patterns, refer to the respective framework skill.
  • 自动识别框架：检查
    package.json
    中的
    @ionic/angular
    、
    @ionic/react
    或
    @ionic/vue
    依赖，判断当前使用的框架，对应调整代码示例。
  • 跳转至参考文件：本技能为概述性内容，会引导Agent跳转至特定参考文件，获取详细的组件API和特定主题指导。
  • 不要重复框架专属技能内容：如需Angular、React或Vue特定的开发模式，请参考对应框架的专属技能。

Core Concepts

核心概念

How Ionic Works

Ionic工作原理

Ionic Framework is a UI toolkit for building cross-platform apps using web technologies (HTML, CSS, JavaScript/TypeScript). It provides a library of pre-built UI components that adapt their styling to the platform (
ios
or 
md
mode).
  • Components are custom HTML elements (Web Components) prefixed with 
    ion-
    (e.g., 
    <ion-button>
    , 
    <ion-content>
    ).
  • Platform modes: Ionic renders components differently based on the platform. iOS devices use the 
    ios
    mode; Android and all other platforms use the 
    md
    (Material Design) mode. The 
    <html>
    element receives a class (
    ios
    or 
    md
    ) that enables platform-specific styles.
  • Capacitor integration: Ionic apps use Capacitor to access native device features. Ionic handles the UI; Capacitor handles native APIs. See the 
    capacitor-app-development
     skill for Capacitor-specific guidance.
Ionic Framework是一款UI工具集，用于使用Web技术（HTML、CSS、JavaScript/TypeScript）构建跨平台应用。它提供了一套预构建的UI组件库，可根据平台（
ios
或
md
模式）自适应样式。
  • 组件是带
    ion-
    前缀的自定义HTML元素（Web Components），例如
    <ion-button>
    、
    <ion-content>
    。
  • 平台模式：Ionic会根据运行平台不同渲染不同样式的组件。iOS设备使用
    ios
    模式；Android和其他所有平台使用
    md
    （Material Design）模式。
    <html>
    元素会添加对应的
    ios
    或
    md
    类，以启用平台专属样式。
  • Capacitor集成：Ionic应用使用Capacitor访问原生设备功能。Ionic负责UI层，Capacitor负责原生API调用。如需Capacitor专属指导，请查看**
    capacitor-app-development
    **技能。

Page Lifecycle

页面生命周期

Ionic provides lifecycle events on top of the framework's own lifecycle hooks. These fire when a page is navigated to or from:
EventDescription
ionViewWillEnter
Fires when the page is about to enter and become active.
ionViewDidEnter
Fires when the page has fully entered and is now active.
ionViewWillLeave
Fires when the page is about to leave and become inactive.
ionViewDidLeave
Fires when the page has fully left and is now inactive.
These are in addition to the framework-specific lifecycle hooks (e.g., Angular's 
ngOnInit
, React's 
useEffect
, Vue's 
onMounted
). Use Ionic lifecycle events for tasks that should run each time a page becomes visible (e.g., refreshing data), since some navigation strategies cache pages.
Ionic在框架自带的生命周期钩子之上，额外提供了生命周期事件，会在页面进出导航时触发：
事件名称说明
ionViewWillEnter
页面即将进入并激活时触发。
ionViewDidEnter
页面完全进入并处于激活状态时触发。
ionViewWillLeave
页面即将离开并变为非激活状态时触发。
ionViewDidLeave
页面完全离开并处于非激活状态时触发。
上述事件是框架专属生命周期钩子（例如Angular的
ngOnInit
、React的
useEffect
、Vue的
onMounted
）之外的补充。对于每次页面可见时都需要运行的任务（例如刷新数据），建议使用Ionic生命周期事件，因为部分导航策略会缓存页面。

Component Reference

组件参考

Ionic provides 80+ UI components. Detailed API documentation for each component is organized into reference files by category. Each reference file covers properties, events, methods, slots, CSS shadow parts, and CSS custom properties.
When the user needs help with a specific component, read the corresponding reference file.
CategoryReference FileComponents Covered
Action & Buttons
references/components-action.md
action-sheet, button, fab, fab-button, fab-list, ripple-effect
Data Display
references/components-data-display.md
accordion, accordion-group, badge, card, card-content, card-header, card-subtitle, card-title, chip, item, item-divider, item-group, item-sliding, item-options, item-option, label, list, list-header, note, text
Form
references/components-form.md
checkbox, datetime, datetime-button, input, input-otp, input-password-toggle, picker, radio, radio-group, range, searchbar, select, select-option, segment, segment-button, segment-content, segment-view, textarea, toggle
Layout
references/components-layout.md
app, content, grid, col, row, header, footer, toolbar, title, buttons, back-button, split-pane
Media
references/components-media.md
avatar, icon, img, thumbnail
Navigation
references/components-navigation.md
breadcrumb, breadcrumbs, menu, menu-button, menu-toggle, nav, nav-link, router, router-link, router-outlet, route, route-redirect, tabs, tab, tab-bar, tab-button
Overlay
references/components-overlay.md
alert, loading, modal, popover, toast, backdrop
Scroll & Virtual
references/components-scroll.md
infinite-scroll, infinite-scroll-content, refresher, refresher-content, reorder, reorder-group
Progress
references/components-progress.md
progress-bar, skeleton-text, spinner
Ionic提供80+个UI组件，每个组件的详细API文档按类别整理在参考文件中，每个参考文件包含属性、事件、方法、插槽、CSS shadow parts和CSS自定义属性说明。
当用户需要特定组件的相关帮助时，请读取对应的参考文件。
类别参考文件路径覆盖组件
操作与按钮
references/components-action.md
action-sheet、button、fab、fab-button、fab-list、ripple-effect
数据展示
references/components-data-display.md
accordion、accordion-group、badge、card、card-content、card-header、card-subtitle、card-title、chip、item、item-divider、item-group、item-sliding、item-options、item-option、label、list、list-header、note、text
表单
references/components-form.md
checkbox、datetime、datetime-button、input、input-otp、input-password-toggle、picker、radio、radio-group、range、searchbar、select、select-option、segment、segment-button、segment-content、segment-view、textarea、toggle
布局
references/components-layout.md
app、content、grid、col、row、header、footer、toolbar、title、buttons、back-button、split-pane
媒体
references/components-media.md
avatar、icon、img、thumbnail
导航
references/components-navigation.md
breadcrumb、breadcrumbs、menu、menu-button、menu-toggle、nav、nav-link、router、router-link、router-outlet、route、route-redirect、tabs、tab、tab-bar、tab-button
浮层
references/components-overlay.md
alert、loading、modal、popover、toast、backdrop
滚动与虚拟滚动
references/components-scroll.md
infinite-scroll、infinite-scroll-content、refresher、refresher-content、reorder、reorder-group
进度
references/components-progress.md
progress-bar、skeleton-text、spinner

Ionic CLI

Ionic CLI

The Ionic CLI is the primary tool for developing Ionic apps. Below are the most commonly used commands. Run 
ionic --help
for the full and always up-to-date command list.
Ionic CLI是开发Ionic应用的核心工具，以下是最常用的命令。运行
ionic --help
可获取完整的、始终保持最新的命令列表。

Installation

安装

bash
npm install -g @ionic/cli
If upgrading from the legacy 
ionic
package:
bash
npm uninstall -g ionic
npm install -g @ionic/cli
bash
npm install -g @ionic/cli
如果是从旧版
ionic
包升级：
bash
npm uninstall -g ionic
npm install -g @ionic/cli

Key Commands

核心命令

CommandDescription
ionic serve
Start a local dev server with live reload.
ionic serve --external
Serve on all network interfaces (for testing on devices).
ionic serve --port=<port>
Serve on a custom port (default: 8100).
ionic serve --prod
Serve with production build configuration.
ionic build
Build the web app for production.
ionic generate
Generate pages, components, services (framework-dependent).
ionic doctor check
Check the project for common issues.
ionic info
Print system/environment info for bug reports.
ionic repair
Remove and recreate dependencies and platform files.
命令说明
ionic serve
启动带热重载的本地开发服务器。
ionic serve --external
绑定所有网络接口启动服务（用于真机测试）。
ionic serve --port=<port>
自定义端口启动服务（默认端口：8100）。
ionic serve --prod
使用生产环境构建配置启动服务。
ionic build
构建生产环境可用的Web应用。
ionic generate
生成页面、组件、服务（依赖使用的框架）。
ionic doctor check
检查项目常见问题。
ionic info
打印系统/环境信息，用于提交Bug报告。
ionic repair
删除并重新安装依赖、重建平台文件。

ionic serve
Options

ionic serve
选项

OptionDescription
--ssl
Enable HTTPS (experimental).
--no-livereload
Serve without automatic reloading.
--no-open
Do not open a browser window automatically.
--consolelogs
Print app console output in terminal.
--browser=<browser>
Open in a specific browser (safari, firefox, google chrome).
--browseroption=<path>
Open a specific URL path (e.g., 
/#/tab/dash
).
For framework-specific CLI options, pass them after 
--
:
bash
ionic serve -- --proxy-config proxy.conf.json
选项说明
--ssl
启用HTTPS（实验性功能）。
--no-livereload
关闭自动重载启动服务。
--no-open
启动服务后不自动打开浏览器窗口。
--consolelogs
在终端打印应用控制台输出。
--browser=<browser>
使用指定浏览器打开（safari、firefox、google chrome）。
--browseroption=<path>
打开指定的URL路径，例如
/#/tab/dash
。
如需传递框架专属的CLI选项，请在
--
之后添加参数：
bash
ionic serve -- --proxy-config proxy.conf.json

Layout

布局

Read 
references/components-layout.md
for the full API reference for layout components.
读取
references/components-layout.md
可获取布局组件的完整API参考。

Grid System

网格系统

Ionic uses a 12-column flexbox grid system (
ion-grid
, 
ion-row
, 
ion-col
). Columns expand to fill the row evenly unless a 
size
attribute is specified (1-12).
Responsive breakpoints:
BreakpointMin WidthCSS Class Prefix
xs
0(default)
sm
576px
sizeSm
md
768px
sizeMd
lg
992px
sizeLg
xl
1200px
sizeXl
Ionic使用12列flexbox网格系统（
ion-grid
、
ion-row
、
ion-col
）。列会自动均匀填充行空间，除非指定了
size
属性（取值1-12）。
响应式断点：
断点名称最小宽度CSS类前缀
xs
0（默认）
sm
576px
sizeSm
md
768px
sizeMd
lg
992px
sizeLg
xl
1200px
sizeXl

CSS Utility Classes

CSS工具类

Ionic provides responsive CSS utility classes for common styling needs:
  • Text: 
    .ion-text-center
    , 
    .ion-text-start
    , 
    .ion-text-end
    , 
    .ion-text-wrap
    , 
    .ion-text-nowrap
    , 
    .ion-text-uppercase
    , 
    .ion-text-lowercase
    , 
    .ion-text-capitalize
  • Padding: 
    .ion-padding
    , 
    .ion-padding-top
    , 
    .ion-padding-bottom
    , 
    .ion-padding-start
    , 
    .ion-padding-end
    , 
    .ion-padding-vertical
    , 
    .ion-padding-horizontal
    , 
    .ion-no-padding
  • Margin: 
    .ion-margin
    , 
    .ion-margin-top
    , 
    .ion-margin-bottom
    , 
    .ion-margin-start
    , 
    .ion-margin-end
    , 
    .ion-margin-vertical
    , 
    .ion-margin-horizontal
    , 
    .ion-no-margin
  • Display: 
    .ion-display-none
    , 
    .ion-display-block
    , 
    .ion-display-flex
    , 
    .ion-display-inline
    , 
    .ion-display-grid
  • Float: 
    .ion-float-left
    , 
    .ion-float-right
    , 
    .ion-float-start
    , 
    .ion-float-end
  • Flex: 
    .ion-justify-content-center
    , 
    .ion-align-items-center
    , 
    .ion-flex-row
    , 
    .ion-flex-column
    , 
    .ion-flex-wrap
    , 
    .ion-flex-nowrap
  • Border: 
    .ion-no-border
All utility classes support responsive breakpoint suffixes: 
ion-text-{breakpoint}-center
(e.g., 
.ion-text-md-center
applies at 768px+).
Ionic提供响应式CSS工具类，可满足常见样式需求：
  • 文本：
    .ion-text-center
    、
    .ion-text-start
    、
    .ion-text-end
    、
    .ion-text-wrap
    、
    .ion-text-nowrap
    、
    .ion-text-uppercase
    、
    .ion-text-lowercase
    、
    .ion-text-capitalize
  • 内边距：
    .ion-padding
    、
    .ion-padding-top
    、
    .ion-padding-bottom
    、
    .ion-padding-start
    、
    .ion-padding-end
    、
    .ion-padding-vertical
    、
    .ion-padding-horizontal
    、
    .ion-no-padding
  • 外边距：
    .ion-margin
    、
    .ion-margin-top
    、
    .ion-margin-bottom
    、
    .ion-margin-start
    、
    .ion-margin-end
    、
    .ion-margin-vertical
    、
    .ion-margin-horizontal
    、
    .ion-no-margin
  • 展示：
    .ion-display-none
    、
    .ion-display-block
    、
    .ion-display-flex
    、
    .ion-display-inline
    、
    .ion-display-grid
  • 浮动：
    .ion-float-left
    、
    .ion-float-right
    、
    .ion-float-start
    、
    .ion-float-end
  • Flex：
    .ion-justify-content-center
    、
    .ion-align-items-center
    、
    .ion-flex-row
    、
    .ion-flex-column
    、
    .ion-flex-wrap
    、
    .ion-flex-nowrap
  • 边框：
    .ion-no-border
所有工具类都支持响应式断点后缀：
ion-text-{breakpoint}-center
（例如
.ion-text-md-center
仅在宽度≥768px时生效）。

Theming

主题定制

Colors

颜色

Ionic provides nine default colors: 
primary
, 
secondary
, 
tertiary
, 
success
, 
warning
, 
danger
, 
light
, 
medium
, 
dark
. Apply via the 
color
attribute on components:
html
<ion-button color="primary">Primary</ion-button>
<ion-button color="danger">Danger</ion-button>
Each color has six CSS custom properties:
  • --ion-color-{name}
    — Base color value
  • --ion-color-{name}-rgb
    — Base color in RGB format
  • --ion-color-{name}-contrast
    — Text color for readability
  • --ion-color-{name}-contrast-rgb
    — Contrast color in RGB format
  • --ion-color-{name}-shade
    — Darker variant (active/pressed states)
  • --ion-color-{name}-tint
    — Lighter variant (hover states)
To customize a color, override all six 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;
}
To add a custom color, define the CSS variables and create a class:
css
:root {
  --ion-color-favorite: #69bb7b;
  --ion-color-favorite-rgb: 105, 187, 123;
  --ion-color-favorite-contrast: #ffffff;
  --ion-color-favorite-contrast-rgb: 255, 255, 255;
  --ion-color-favorite-shade: #5ca56c;
  --ion-color-favorite-tint: #78c288;
}

.ion-color-favorite {
  --ion-color-base: var(--ion-color-favorite);
  --ion-color-base-rgb: var(--ion-color-favorite-rgb);
  --ion-color-contrast: var(--ion-color-favorite-contrast);
  --ion-color-contrast-rgb: var(--ion-color-favorite-contrast-rgb);
  --ion-color-shade: var(--ion-color-favorite-shade);
  --ion-color-tint: var(--ion-color-favorite-tint);
}
Ionic默认提供9种颜色：
primary
、
secondary
、
tertiary
、
success
、
warning
、
danger
、
light
、
medium
、
dark
。可通过组件的
color
属性应用：
html
<ion-button color="primary">Primary</ion-button>
<ion-button color="danger">Danger</ion-button>
每种颜色对应6个CSS自定义属性：
  • --ion-color-{name}
    — 基础颜色值
  • --ion-color-{name}-rgb
    — RGB格式的基础颜色
  • --ion-color-{name}-contrast
    — 保证可读性的文本对比色
  • --ion-color-{name}-contrast-rgb
    — RGB格式的对比色
  • --ion-color-{name}-shade
    — 更深的变体（用于激活/按下状态）
  • --ion-color-{name}-tint
    — 更浅的变体（用于悬停状态）
如需自定义颜色，在
:root
中覆盖全部6个变量即可：
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;
}
如需新增自定义颜色，先定义CSS变量再创建对应类：
css
:root {
  --ion-color-favorite: #69bb7b;
  --ion-color-favorite-rgb: 105, 187, 123;
  --ion-color-favorite-contrast: #ffffff;
  --ion-color-favorite-contrast-rgb: 255, 255, 255;
  --ion-color-favorite-shade: #5ca56c;
  --ion-color-favorite-tint: #78c288;
}

.ion-color-favorite {
  --ion-color-base: var(--ion-color-favorite);
  --ion-color-base-rgb: var(--ion-color-favorite-rgb);
  --ion-color-contrast: var(--ion-color-favorite-contrast);
  --ion-color-contrast-rgb: var(--ion-color-favorite-contrast-rgb);
  --ion-color-shade: var(--ion-color-favorite-shade);
  --ion-color-tint: var(--ion-color-favorite-tint);
}

Global CSS Variables

全局CSS变量

VariableDescription
--ion-background-color
Background color of the app
--ion-text-color
Text color of the app
--ion-font-family
Font family of the app
--ion-statusbar-padding
Statusbar padding top of the app
--ion-safe-area-top
Adjust safe area inset top
--ion-safe-area-right
Adjust safe area inset right
--ion-safe-area-bottom
Adjust safe area inset bottom
--ion-safe-area-left
Adjust safe area inset left
--ion-margin
Default margin for margin utility classes
--ion-padding
Default padding for padding utility classes
--ion-placeholder-opacity
Opacity of placeholder text in inputs
变量名说明
--ion-background-color
应用背景色
--ion-text-color
应用文本颜色
--ion-font-family
应用字体
--ion-statusbar-padding
应用状态栏顶部内边距
--ion-safe-area-top
调整顶部安全区边距
--ion-safe-area-right
调整右侧安全区边距
--ion-safe-area-bottom
调整底部安全区边距
--ion-safe-area-left
调整左侧安全区边距
--ion-margin
外边距工具类的默认外边距值
--ion-padding
内边距工具类的默认内边距值
--ion-placeholder-opacity
输入框占位符文本透明度

Dark Mode

暗黑模式

Ionic supports three dark mode approaches:
Ionic支持三种暗黑模式实现方案：

1. System Preference (Default)

1. 跟随系统偏好（默认）

Automatically applies dark palette based on the user's OS setting:
css
@import '@ionic/angular/css/palettes/dark.system.css';
/* or @ionic/react, @ionic/vue */
根据用户的操作系统设置自动应用暗黑配色：
css
@import '@ionic/angular/css/palettes/dark.system.css';
/* 或 @ionic/react, @ionic/vue */

2. Always Dark

2. 始终暗黑

Forces dark mode regardless of system settings:
css
@import '@ionic/angular/css/palettes/dark.always.css';
强制启用暗黑模式，忽略系统设置：
css
@import '@ionic/angular/css/palettes/dark.always.css';

3. CSS Class Toggle

3. CSS类切换

Enables manual dark mode control via a CSS class:
css
@import '@ionic/angular/css/palettes/dark.class.css';
Add 
.ion-palette-dark
to the 
<html>
element to activate:
html
<html class="ion-palette-dark">
Add this meta tag to adjust system UI elements (scrollbars, etc.):
html
<meta name="color-scheme" content="light dark" />
通过CSS类手动控制暗黑模式开关：
css
@import '@ionic/angular/css/palettes/dark.class.css';
给
<html>
元素添加
.ion-palette-dark
类即可启用暗黑模式：
html
<html class="ion-palette-dark">
添加以下meta标签可调整系统UI元素（滚动条等）的适配：
html
<meta name="color-scheme" content="light dark" />

Platform Styles

平台样式

Ionic uses two modes for platform-specific styling:
PlatformDefault ModeStyle
iOS
ios
Apple iOS design
Android
md
Material Design
Other / Web
md
Material Design
To preview a specific mode in the browser, add 
?ionic:mode=ios
or 
?ionic:mode=md
to the URL:
http://localhost:8100/?ionic:mode=ios
Target mode-specific styles in CSS:
css
.ios ion-toolbar {
  --background: #f8f8f8;
}

.md ion-toolbar {
  --background: #ffffff;
}
Ionic使用两种模式实现平台专属样式：
平台默认模式样式
iOS
ios
Apple iOS设计
Android
md
Material Design
其他/ Web
md
Material Design
如需在浏览器中预览特定模式，在URL中添加
?ionic:mode=ios
或
?ionic:mode=md
即可：
http://localhost:8100/?ionic:mode=ios
在CSS中针对特定模式编写样式：
css
.ios ion-toolbar {
  --background: #f8f8f8;
}

.md ion-toolbar {
  --background: #ffffff;
}

Developing

开发相关

Previewing in the Browser

浏览器预览

The primary development workflow is browser-based:
bash
ionic serve
This starts a development server at 
http://localhost:8100
with live reload.
Use browser DevTools to simulate mobile devices:
  • Chrome: 
    Cmd+Opt+I
    (Mac) / 
    Ctrl+Shift+I
    (Windows/Linux), then toggle device toolbar
  • Safari: 
    Cmd+Opt+R
    for Responsive Design Mode
  • Firefox: 
    Cmd+Opt+M
    (Mac) / 
    Ctrl+Shift+M
    (Windows/Linux)
主流开发工作流基于浏览器：
bash
ionic serve
该命令会在
http://localhost:8100
启动带热重载的开发服务器。
使用浏览器开发者工具模拟移动设备：
  • Chrome：Mac按
    Cmd+Opt+I
    / Windows/Linux按
    Ctrl+Shift+I
    ，然后切换设备工具栏
  • Safari：按
    Cmd+Opt+R
    进入响应式设计模式
  • Firefox：Mac按
    Cmd+Opt+M
    / Windows/Linux按
    Ctrl+Shift+M

Testing on Devices

真机测试

For native functionality that requires a real device:
bash
npx cap run android
npx cap run ios
For live reload on a device:
bash
npx cap run android --livereload --external
npx cap run ios --livereload --external
如果需要测试依赖真机的原生功能：
bash
npx cap run android
npx cap run ios
如需在真机上使用热重载：
bash
npx cap run android --livereload --external
npx cap run ios --livereload --external

Debugging Tips

调试技巧

  • Use the 
    debugger
    keyword to set breakpoints in code.
  • Add 
    ?ionic:mode=ios
    to the URL to preview iOS styles in the browser.
  • Use 
    ionic info
    to collect environment info for troubleshooting.
  • 使用
    debugger
    关键字在代码中设置断点。
  • 在URL中添加
    ?ionic:mode=ios
    可在浏览器中预览iOS样式。
  • 使用
    ionic info
    收集环境信息，辅助排查问题。

Utilities

工具函数

Animations

动画

Ionic provides a framework-agnostic animation utility built on the Web Animations API. Import:
  • JavaScript/TypeScript: 
    import { createAnimation } from '@ionic/core';
  • Angular: Inject 
    AnimationController
    from 
    @ionic/angular
  • React: Use 
    CreateAnimation
    component from 
    @ionic/react
  • Vue: 
    import { createAnimation } from '@ionic/vue';
Key methods: 
addElement()
, 
duration()
, 
easing()
, 
fromTo()
, 
keyframes()
, 
play()
, 
pause()
, 
stop()
, 
onFinish()
.
Animations support grouping (parent-child), chaining (via 
play()
promises), and integration with gestures.
For performance, prefer animating 
transform
and 
opacity
over 
height
and 
width
.
Ionic提供了基于Web Animations API的框架无关动画工具，导入方式：
  • JavaScript/TypeScript：
    import { createAnimation } from '@ionic/core';
  • Angular：从
    @ionic/angular
    注入
    AnimationController
  • React：使用
    @ionic/react
    的
    CreateAnimation
    组件
  • Vue：
    import { createAnimation } from '@ionic/vue';
核心方法：
addElement()
、
duration()
、
easing()
、
fromTo()
、
keyframes()
、
play()
、
pause()
、
stop()
、
onFinish()
。
动画支持分组（父子关系）、链式调用（通过
play()
返回的Promise），以及与手势集成。
为保证性能，建议优先使用
transform
和
opacity
做动画，避免修改
height
和
width
。

Gestures

手势

Ionic provides a framework-agnostic gesture utility. Import:
  • JavaScript/TypeScript: 
    import { createGesture } from '@ionic/core';
  • Angular: Inject 
    GestureController
    from 
    @ionic/angular
  • React: 
    import { createGesture } from '@ionic/react';
  • Vue: 
    import { createGesture } from '@ionic/vue';
Configuration options: 
el
, 
gestureName
, 
threshold
, 
direction
(
x
/
y
), 
maxAngle
, 
gesturePriority
, 
disableScroll
, 
passive
.
Callbacks: 
canStart
, 
onWillStart
, 
onStart
, 
onMove
, 
onEnd
, 
notCaptured
.
The 
GestureDetail
object provides 
startX
/
startY
, 
currentX
/
currentY
, 
deltaX
/
deltaY
, and 
velocityX
/
velocityY
.
Ionic提供了框架无关的手势工具，导入方式：
  • JavaScript/TypeScript：
    import { createGesture } from '@ionic/core';
  • Angular：从
    @ionic/angular
    注入
    GestureController
  • React：
    import { createGesture } from '@ionic/react';
  • Vue：
    import { createGesture } from '@ionic/vue';
配置选项：
el
、
gestureName
、
threshold
、
direction
（
x
/
y
）、
maxAngle
、
gesturePriority
、
disableScroll
、
passive
。
回调函数：
canStart
、
onWillStart
、
onStart
、
onMove
、
onEnd
、
notCaptured
。
GestureDetail
对象提供
startX
/
startY
、
currentX
/
currentY
、
deltaX
/
deltaY
以及
velocityX
/
velocityY
属性。

Hardware Back Button (Android)

硬件返回按钮（Android）

Ionic emits an 
ionBackButton
event when the Android hardware back button is pressed. Handlers are priority-based:
PriorityHandler
100Overlays
99Menu
0Navigation
For Capacitor apps, install 
@capacitor/app
to enable hardware back button support. See the framework-specific skills for implementation patterns.
当按下Android硬件返回按钮时，Ionic会触发
ionBackButton
事件，处理函数按优先级执行：
优先级处理对象
100浮层组件
99菜单
0导航
对于Capacitor应用，需要安装
@capacitor/app
以启用硬件返回按钮支持。实现模式请参考对应框架的专属技能。

Error Handling

错误处理

  • ionic: command not found
    : The Ionic CLI is not installed. Run 
    npm install -g @ionic/cli
    .
  • Port 8100 in use: Another process is using the default port. Run 
    ionic serve --port=<other-port>
    .
  • Components not rendering: Verify the Ionic CSS files are imported in the global stylesheet. For Angular: 
    @import '@ionic/angular/css/core.css';
    . For React/Vue: check the framework-specific import.
  • Platform styles not applied: Ensure 
    @ionic/angular
    , 
    @ionic/react
    , or 
    @ionic/vue
    is installed and configured. The 
    <html>
    element should have an 
    ios
    or 
    md
    class.
  • Dark mode not working: Verify the correct dark palette CSS import is present. For the class method, ensure 
    .ion-palette-dark
    is applied to the 
    <html>
    element.
  • CSS custom properties not applying: Ionic components use Shadow DOM. Use the component's documented CSS custom properties (e.g., 
    --background
    , 
    --color
    ) rather than targeting internal elements directly. Check the component reference file for available properties.
  • Live reload not working on device: Ensure the device and development machine are on the same network. Use the 
    --external
    flag with 
    npx cap run
    .
  • ionViewWillEnter
    not firing    : This lifecycle event only fires with Ionic's routing components (
    ion-router-outlet
    ). It does not fire with standard framework routers unless Ionic's routing integration is used.
  • ionic: command not found
    ：未安装Ionic CLI，运行
    npm install -g @ionic/cli
    即可。
  • 端口8100被占用：其他进程正在使用默认端口，运行
    ionic serve --port=<其他端口>
    即可。
  • 组件不渲染：确认全局样式表中已导入Ionic CSS文件。Angular项目需导入
    @import '@ionic/angular/css/core.css';
    ；React/Vue项目请检查框架专属的导入配置。
  • 平台样式未生效：确认已安装并正确配置
    @ionic/angular
    、
    @ionic/react
    或
    @ionic/vue
    ，
    <html>
    元素应带有
    ios
    或
    md
    类。
  • 暗黑模式不生效：确认已导入正确的暗黑配色CSS文件；如果使用类切换方案，确认
    .ion-palette-dark
    类已添加到
    <html>
    元素上。
  • CSS自定义属性不生效：Ionic组件使用Shadow DOM，需要使用组件文档中提供的CSS自定义属性（例如
    --background
    、
    --color
    ），而不是直接针对内部元素编写样式。可查看组件参考文件获取可用属性列表。
  • 真机热重载不生效：确认设备和开发机器在同一个网络下，给
    npx cap run
    命令添加
    --external
    参数。
  • ionViewWillEnter
    不触发    ：该生命周期事件仅配合Ionic的路由组件（
    ion-router-outlet
    ）使用，如果使用标准框架路由且未集成Ionic路由，则不会触发该事件。

Related Skills

相关技能

  • ionic-app-creation
     — Create a new Ionic app.
  • ionic-angular
     — Ionic with Angular (framework-specific patterns).
  • ionic-react
     — Ionic with React (framework-specific patterns).
  • ionic-vue
     — Ionic with Vue (framework-specific patterns).
  • ionic-app-upgrades
     — Upgrade Ionic to a newer major version.
  • capacitor-app-development
     — General Capacitor development.
  • capacitor-plugins
     — Capacitor plugins installation and configuration.
  • ionic-app-creation
     — 创建新Ionic应用。
  • ionic-angular
     — Ionic配合Angular使用（框架专属开发模式）。
  • ionic-react
     — Ionic配合React使用（框架专属开发模式）。
  • ionic-vue
     — Ionic配合Vue使用（框架专属开发模式）。
  • ionic-app-upgrades
     — 升级Ionic到新的主版本。
  • capacitor-app-development
     — 通用Capacitor开发指南。
  • capacitor-plugins
     — Capacitor插件安装与配置。