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

前置条件

Node.js (latest LTS) installed.
Ionic CLI installed globally (
```
npm install -g @ionic/cli
```
).
An existing Ionic project. For creating a new Ionic app, use the ionic-app-creation
skill.

已安装Node.js（最新LTS版本）。
已全局安装Ionic CLI（
```
npm install -g @ionic/cli
```
）。
已有一个现成的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

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:

Event	Description
`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.

Category	Reference File	Components 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

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

核心命令

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

选项

Option	Description
`--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:

Breakpoint	Min Width	CSS 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变量

Variable	Description
`--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:

Platform	Default Mode	Style
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

?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

(

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

（

）、

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:

Priority	Handler
100	Overlays
99	Menu
0	Navigation

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路由，则不会触发该事件。

ionic-app-development

Original

Translation

Ionic App Development

Ionic应用开发

Prerequisites

前置条件

Agent Behavior

Agent行为规范

Core Concepts

核心概念

How Ionic Works

Ionic工作原理

Page Lifecycle

页面生命周期

Component Reference

组件参考

Ionic CLI

Ionic CLI

Installation

安装

Key Commands

核心命令

ionic serve Options

ionic serve 选项

Layout

布局

Grid System

网格系统

CSS Utility Classes

CSS工具类

Theming

主题定制

Colors

颜色

Global CSS Variables

全局CSS变量

Dark Mode

暗黑模式

1. System Preference (Default)

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

2. Always Dark

2. 始终暗黑

3. CSS Class Toggle

3. CSS类切换

Platform Styles

平台样式

Developing

开发相关

Previewing in the Browser

浏览器预览

Testing on Devices

真机测试

Debugging Tips

调试技巧

Utilities

工具函数

Animations

动画

Gestures

手势

Hardware Back Button (Android)

硬件返回按钮（Android）

Error Handling

错误处理

Related Skills

相关技能

`ionic serve`
Options

`ionic serve`
选项