ionic-expert

Ionic 专家

Ionic Framework 开发综合参考——核心概念、组件、主题、生命周期、导航、框架专属模式（Angular、React、Vue）、升级以及 Capawesome Cloud 集成。

MCP 服务

有两个托管的 MCP 服务提供当前文档，因此它们的内容始终比本技能附带的指南更新：

• Capawesome MCP server — Capawesome 插件、Capawesome CLI 和 Capawesome Cloud。
• Ionic Framework MCP server（非官方）— Ionic Framework UI 组件、API 参考以及各框架的官方用法示例。

两者都提供 search_docs 和 get_doc_page，因此调用前请根据主题选择对应的服务。

• 如果 MCP 工具可用，请在负责该主题的服务上调用 search_docs，并使用 get_doc_page 阅读匹配的页面，然后再参考下方指南。如果两者内容不一致，请以文档为准。
• 如果 MCP 工具不可用，请提及一次可以通过下方命令添加这些服务，然后继续使用本技能。切勿因此中断。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http ionic-framework "https://ionic-framework-mcp.capawesome.io/mcp"

文档服务均不需要账户或令牌。完整设置说明（包括 Capawesome Cloud 工具）请参阅 capawesome-mcp 和 ionic-framework-mcp 技能。

核心概念

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）集成。

创建新应用

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 --help 查看完整且始终保持最新的命令列表。

命令	描述
ionic start	搭建新的 Ionic 项目。
ionic serve	启动支持实时重载的本地开发服务（端口 8100）。
ionic build	构建用于生产环境的 Web 应用。
ionic generate	生成页面、组件、服务（取决于框架）。
ionic info	输出系统/环境信息。
ionic repair	移除并重新创建依赖项和平台文件。

常用的 ionic serve 标志：--external（所有网络接口）、--port=<port>、--prod、--no-open。

组件概览

Ionic 提供 80 多个按类别组织的 UI 组件。完整 API 参考（属性、事件、方法、插槽、CSS 自定义属性）请参阅链接的参考文件。

布局

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。

主要用法：

<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>
  
</ion-content>

详情请参阅 components-layout.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。

表单

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）。

<ion-input label="Email" labelPlacement="floating" fill="outline"
           type="email" placeholder="[email protected]"
           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>

详情请参阅 components-form.md。

覆层

ion-modal、ion-alert、ion-toast、ion-action-sheet、ion-loading、ion-popover。

所有覆层共用：用于声明式控制的 isOpen 属性、用于通过按钮 ID 打开的 trigger 属性、backdropDismiss、animated，以及生命周期事件（didPresent、didDismiss、willPresent、willDismiss）。

底部弹出式模态框（底部面板）：

<ion-modal [isOpen]="isOpen" [breakpoints]="[0, 0.5, 1]" [initialBreakpoint]="0.5" [handle]="true">
  <ion-content>Sheet content</ion-content>
</ion-modal>

详情请参阅 components-overlay.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。

滚动

ion-refresher/ion-refresher-content（下拉刷新）、ion-infinite-scroll/ion-infinite-scroll-content、ion-reorder-group/ion-reorder。

详情请参阅 components-scroll.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。

主题

颜色

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

<ion-button color="primary">Save</ion-button>
<ion-button color="danger">Delete</ion-button>

通过在 :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;
}

全局 CSS 变量

关键变量：--ion-background-color、--ion-text-color、--ion-font-family、--ion-safe-area-top/right/bottom/left、--ion-margin、--ion-padding。

深色模式

有三种方式（从 @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';，然后将 .ion-palette-dark 添加到 <html>。

平台样式

使用 <html> 上的模式类，在 CSS 中设置针对特定平台的样式：

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

在浏览器中预览特定模式：http://localhost:8100/?ionic:mode=ios

布局

网格系统

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 实用类

• 内边距：.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
• 弹性布局：.ion-justify-content-center、.ion-align-items-center、.ion-flex-row、.ion-flex-column

所有实用类都支持响应式后缀：.ion-text-md-center（在 768px 及以上时生效）。

页面生命周期

Ionic 提供四个在页面切换期间触发的生命周期钩子。这些钩子之所以存在，是因为 ion-router-outlet 会在 DOM 中缓存页面——框架原生生命周期钩子（ngOnInit、useEffect、onMounted）仅在首次创建时触发一次，而不会在每次访问页面时触发。

钩子	触发时机	用途
ionViewWillEnter	页面即将进入（动画前）	每次访问时刷新数据
ionViewDidEnter	页面已完全进入（动画后）	启动动画、聚焦输入框
ionViewWillLeave	页面即将离开（动画前）	保存状态、暂停订阅
ionViewDidLeave	页面已完全离开（动画后）	清理屏幕外的资源

重要规则：

• 仅直接通过 ion-router-outlet 映射到路由的组件会触发这些钩子。
• 子组件不会收到这些事件。
• 组件必须使用框架特定的页面包装器（见下文的框架章节）。

框架特定模式

Angular

完整详情请参阅 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：

import { ViewWillEnter } from '@ionic/angular';

@Component({ /* ... */ })
export class HomePage implements ViewWillEnter {
  ionViewWillEnter() {
    this.loadData(); // Runs on every page visit
  }
}

有关导航的详情，请参阅 angular/navigation.md。有关生命周期的详情，请参阅 angular/lifecycle.md。

React

完整详情请参阅 ionic-react。

主要配置差异：

• 在 src/main.tsx 中渲染前调用 setupIonicReact()。
• 使用 IonReactRouter（来自 @ionic/react-router）代替 BrowserRouter。
• 使用 IonRouterOutlet 包含路由，并使用 component 属性（而非 render 或 children）。
• 每个页面都必须以 IonPage 作为根节点渲染——这是实现过渡效果和生命周期钩子所必需的。

导航：使用 useIonRouter 钩子进行程序化导航：

import { useIonRouter } from '@ionic/react';

const router = useIonRouter();
router.push('/detail/123', 'forward', 'push');
router.goBack();

生命周期钩子（来自 @ionic/react）：

import { useIonViewWillEnter } from '@ionic/react';

useIonViewWillEnter(() => {
  fetchData(); // Runs on every page visit
});

覆盖层钩子：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

完整详情请参阅 ionic-vue。

主要设置差异：

• 在 src/main.ts 中安装 IonicVue 插件：createApp(App).use(IonicVue).use(router)。
• 从 @ionic/vue-router 导入 createRouter（而不是从 vue-router 导入）。
• 每个页面都必须将 IonPage 用作根模板元素——否则，转场和生命周期钩子会静默失效。
• 从 @ionic/vue 导入所有 Ionic 组件。
• 在模板中使用 kebab-case 形式的事件名称（@ion-change、@ion-input）。
• 将图标作为 SVG 引用从 ionicons/icons 导入——不要将其作为字符串使用。

导航：使用 useIonRouter 组合式函数：

<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）：

<script setup lang="ts">
import { onIonViewWillEnter } from '@ionic/vue';

onIonViewWillEnter(() => {
  fetchData(); // Runs on every page visit
});
</script>

组合式函数：useIonRouter()、useBackButton(priority, handler)、useKeyboard()、isPlatform(name)、getPlatforms()。

通过 $el 访问 Web Component 方法：contentRef.value.$el.scrollToBottom(300)。

导航详情请参阅 vue/navigation.md。组合式函数详情请参阅 vue/composables.md。

导航模式

标签页导航

每个框架都使用 ion-tabs 和 ion-tab-bar，并为每个标签页配置子路由。每个标签页都维护自己的导航栈。

规则：

• ion-tab-button 上的 tab 属性必须与子路由路径一致。
• 切勿以编程方式在标签页之间导航——只能通过标签栏按钮切换标签页。
• 对于跨标签页共享的视图，请使用 ion-modal，而不是跨标签页路由。

侧边菜单

使用 ion-menu，并使 contentId 与 ion-router-outlet 上的 id 相匹配。将菜单项包在 ion-menu-toggle 中，以便选择后自动关闭菜单。对于顶层菜单导航，请使用 routerDirection="root"。

线性与非线性路由

• 线性：按顺序向前或向后导航（列表 -> 详情 -> 编辑）。返回按钮会回到上一页。
• 非线性：多个相互独立的导航栈（标签页）。返回导航会停留在当前标签页的导航栈中。

标签页或分栏布局请使用非线性路由。简单的页面流程请使用线性路由。

升级

Ionic 支持从版本 4 升级到版本 8。每次跨主版本升级都必须按顺序进行——不要跳过中间版本。

完整升级指南请参阅 ionic-app-upgrades。

Capacitor 集成

Ionic 应用使用 Capacitor 实现原生设备功能（相机、文件系统、推送通知等）。标准工作流：

npm run build
npx cap sync
npx cap run android
npx cap run ios

在设备上进行实时重新加载：

ionic cap run android --livereload --external
ionic cap run ios --livereload --external

Capacitor 使用指南请参阅 capacitor-app-development 技能。

Capawesome Cloud

Capawesome Cloud 为 Ionic/Capacitor 应用提供 CI/CD 服务：

• 实时更新 — 即时向 Ionic/Capacitor 应用部署 OTA 更新，无需经过应用商店审核。
• 原生构建 — 在云端构建 iOS 和 Android 二进制文件，无需本地安装 Xcode 或 Android Studio。
• 应用商店发布 — 自动向 Apple App Store 和 Google Play Store 提交应用。

访问 capawesome.io 了解完整的 Capawesome 生态系统。设置指南请参阅 capawesome-cloud 技能。

常见问题排查

• 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 standalone）：使用所需图标调用 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 访问值。
• Slot 属性弃用警告（Vue）：Ionic 使用 Web Component 插槽。请禁用 ESLint 规则：'vue/no-deprecated-slot-attribute': 'off'。

相关技能

• ionic-app-creation — 从头创建新的 Ionic 应用。
• ionic-app-development — Ionic 开发通用指南及完整的组件 API 参考。
• ionic-angular — Angular 专属模式（standalone 与 NgModule、导航、表单、测试）。
• ionic-react — React 专属模式（IonReactRouter、钩子、状态管理）。
• ionic-vue — Vue 专属模式（组合式函数、导航、IonPage 要求）。
• ionic-app-upgrades — 将 Ionic 升级到较新的主版本。
• capacitor-app-development — Capacitor 开发通用指南。
• capawesome-cloud — 实时更新、原生构建和应用商店发布。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。
• ionic-framework-mcp — 将 MCP 客户端连接到托管的 Ionic Framework MCP 服务，以获取最新的组件 API 参考和用法示例。