ionic-app-development

Ionic 应用开发

Ionic Framework 通用开发——核心概念、组件参考、CLI 用法、布局、主题、实用工具、开发工作流和故障排除。

前置条件

1. 已安装 Node.js（最新 LTS 版本）。
2. 已全局安装 Ionic CLI（npm install -g @ionic/cli）。
3. 已有一个 Ionic 项目。若要创建新的 Ionic 应用，请使用 ionic-app-creation 技能。

Agent 行为

• 自动检测框架。 检查 package.json 中是否包含 @ionic/angular、@ionic/react 或 @ionic/vue，以确定正在使用的框架。相应调整代码示例。
• 跳转到参考文件。 此技能为概览，会将 Agent 引导至特定参考文件，以获取详细的组件 API 和针对具体主题的指南。
• 不要重复框架专属技能的内容。 有关 Angular、React 或 Vue 的特定模式，请参阅相应的框架技能。

核心概念

Ionic 的工作原理

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 技能。

页面生命周期

Ionic 在框架自身的生命周期钩子之外，还提供生命周期事件。这些事件会在页面导航进入或离开时触发：

事件	说明
ionViewWillEnter	页面即将进入并变为活动状态时触发。
ionViewDidEnter	页面完全进入并变为活动状态时触发。
ionViewWillLeave	页面即将离开并变为非活动状态时触发。
ionViewDidLeave	页面完全离开并变为非活动状态时触发。

这些事件补充了框架专属的生命周期钩子（例如，Angular 的 ngOnInit、React 的 useEffect、Vue 的 onMounted）。对于每次页面变为可见时都应执行的任务（例如，刷新数据），请使用 Ionic 生命周期事件，因为某些导航策略会缓存页面。

组件参考

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 是开发 Ionic 应用的主要工具。以下是最常用的命令。运行 ionic --help 查看完整且始终保持最新的命令列表。

安装

npm install -g @ionic/cli

如果要从旧版 ionic 包升级：

npm uninstall -g ionic
npm install -g @ionic/cli

主要命令

命令	说明
ionic serve	启动本地开发服务器并启用实时重新加载。
ionic serve --external	在所有网络接口上提供服务（用于在设备上测试）。
ionic serve --port=<port>	在自定义端口上提供服务（默认值：8100）。
ionic serve --prod	使用生产构建配置提供服务。
ionic build	为生产环境构建 Web 应用。
ionic generate	生成页面、组件和服务（取决于框架）。
ionic doctor check	检查项目是否存在常见问题。
ionic info	输出系统和环境信息，以便提交错误报告。
ionic repair	移除并重新创建依赖项和平台文件。

ionic serve 选项

选项	说明
--ssl	启用 HTTPS（实验性）。
--no-livereload	提供服务时不自动重新加载。
--no-open	不自动打开浏览器窗口。
--consolelogs	在终端中输出应用的控制台内容。
--browser=<browser>	在指定浏览器中打开（safari、firefox、google chrome）。
--browseroption=<path>	打开指定的 URL 路径（例如，/#/tab/dash）。

如需使用特定于框架的 CLI 选项，请在 -- 后传入：

ionic serve -- --proxy-config proxy.conf.json

布局

阅读 references/components-layout.md，查看布局组件的完整 API 参考。

网格系统

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 工具类

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 及以上的屏幕宽度生效）。

主题

颜色

Ionic 提供九种默认颜色：primary、secondary、tertiary、success、warning、danger、light、medium、dark。通过组件的 color 属性应用：

<ion-button color="primary">Primary</ion-button>
<ion-button color="danger">Danger</ion-button>

每种颜色都有六个 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 中覆盖全部六个变量：

: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 变量并创建一个类：

: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);
}

全局 CSS 变量

变量	描述
--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	输入框中占位文本的不透明度

深色模式

Ionic 支持三种深色模式方案：

1. 系统偏好（默认）

根据用户的操作系统设置自动应用深色调色板：

@import '@ionic/angular/css/palettes/dark.system.css';
/* or @ionic/react, @ionic/vue */

2. 始终启用深色模式

无论系统设置如何，始终启用深色模式：

@import '@ionic/angular/css/palettes/dark.always.css';

3. CSS 类切换

通过 CSS 类手动控制深色模式：

@import '@ionic/angular/css/palettes/dark.class.css';

将 .ion-palette-dark 添加到 <html> 元素以启用深色模式：

<html class="ion-palette-dark">

添加此 meta 标签以调整系统界面元素（滚动条等）：

<meta name="color-scheme" content="light dark" />

平台样式

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 中使用针对特定模式的样式：

.ios ion-toolbar {
  --background: #f8f8f8;
}

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

开发

在浏览器中预览

主要的开发工作流基于浏览器：

ionic serve

这会在 http://localhost:8100 启动开发服务器，并启用实时重新加载。

使用浏览器开发者工具模拟移动设备：

• Chrome：Cmd+Opt+I（Mac）/ Ctrl+Shift+I（Windows/Linux），然后切换设备工具栏
• Safari：Cmd+Opt+R 进入响应式设计模式
• Firefox：Cmd+Opt+M（Mac）/ Ctrl+Shift+M（Windows/Linux）

在设备上测试

对于需要真实设备的原生功能：

npx cap run android
npx cap run ios

要在设备上启用实时重新加载：

npx cap run android --livereload --external
npx cap run ios --livereload --external

调试提示

• 使用 debugger 关键字在代码中设置断点。
• 在 URL 中添加 ?ionic:mode=ios，以在浏览器中预览 iOS 样式。
• 使用 ionic info 收集环境信息，以便排查问题。

实用工具

动画

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。

手势

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。

硬件返回按钮（Android）

按下 Android 硬件返回按钮时，Ionic 会触发 ionBackButton 事件。处理程序按优先级执行：

优先级	处理程序
100	覆盖层
99	菜单
0	导航

对于 Capacitor 应用，安装 @capacitor/app 以启用硬件返回按钮支持。实现模式请参阅特定框架的技能。

错误处理

• ionic: command not found：未安装 Ionic CLI。运行 npm install -g @ionic/cli。
• 端口 8100 已被占用：另一个进程正在使用默认端口。运行 ionic serve --port=<other-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-creation — 创建新的 Ionic 应用。
• ionic-angular — 使用 Angular 的 Ionic（特定框架模式）。
• ionic-react — 使用 React 的 Ionic（特定框架模式）。
• ionic-vue — 使用 Vue 的 Ionic（特定框架模式）。
• ionic-app-upgrades — 将 Ionic 升级到较新的主版本。
• capacitor-app-development — Capacitor 常规开发。
• capacitor-plugins — Capacitor 插件的安装和配置。
• ionic-framework-mcp — 将 MCP 客户端连接到当前的 Ionic Framework 文档。