用 Ionic Framework…

已有 Ionic 项目、需要查阅组件用法、CLI 命令、布局/主题/动画/手势或排查常见错误时使用。

适用场景

解决思路

1. 先自动检测框架：查看 package.json 中是否存在 @ionic/angular、@ionic/react 或 @ionic/vue，据此调整代码示例。
2. 按需读取 references 下的分类参考文件获取组件 API：action 用 references/components-action.md；data display 用 references/components-data-display.md；form 用 references/components-form.md；layout 用 references/components-layout.md；media 用 references/components-media.md；navigation 用 references/components-navigation.md；overlay 用 references/components-overlay.md；scroll 用 references/components-scroll.md；progress 用 references/components-progress.md。
3. 理解核心概念：组件是 ion- 前缀的 Web Component；平台模式分 ios 与 md，<html> 元素会带上 ios 或 md 类；原生能力由 Capacitor 负责，UI 由 Ionic 负责。
4. 使用 Ionic 页面生命周期事件：ionViewWillEnter、ionViewDidEnter、ionViewWillLeave、ionViewDidLeave，用于每次页面可见时执行的任务（如刷新数据），因为它们与框架自身生命周期钩子并存且页面可能被缓存。
5. 安装 Ionic CLI：npm install -g @ionic/cli；若从旧包升级，先 npm uninstall -g ionic 再 npm install -g @ionic/cli。
6. 使用常用 CLI 命令：ionic serve 启动带 live reload 的本地开发服务器；ionic serve --external 在所有网络接口上服务以便真机测试；ionic serve --port=<port> 指定端口（默认 8100）；ionic serve --prod 使用生产构建配置；ionic build 构建生产 Web 应用；ionic generate 生成页面/组件/服务；ionic doctor check 检查项目常见问题；ionic info 打印环境信息；ionic repair 删除并重建依赖与平台文件。
7. 使用 ionic serve 选项：--ssl 启用 HTTPS（实验性）；--no-livereload 关闭自动刷新；--no-open 不自动打开浏览器；--consolelogs 在终端打印应用控制台输出；--browser=<browser> 指定浏览器（safari、firefox、google chrome）；--browseroption=<path> 打开指定 URL 路径（如 /#/tab/dash）。
8. 传递框架特定 CLI 选项时放在 -- 之后，例如：ionic serve -- --proxy-config proxy.conf.json。
9. 使用 12 列 flexbox 网格（ion-grid、ion-row、ion-col），列默认均分，可用 size 属性（1-12）指定；响应式断点为 xs(0)、sm(576px)、md(768px)、lg(992px)、xl(1200px)，对应类前缀 sizeSm、sizeMd、sizeLg、sizeXl。
10. 使用 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-no-padding；外边距 .ion-margin 系列与 .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-md-center 在 768px+ 生效。
11. 使用九种默认颜色 primary、secondary、tertiary、success、warning、danger、light、medium、dark，通过组件的 color 属性应用，如 <ion-button color="primary">。
12. 自定义颜色时在 :root 覆盖全部六个 CSS 变量：--ion-color-{name}、--ion-color-{name}-rgb、--ion-color-{name}-contrast、--ion-color-{name}-contrast-rgb、--ion-color-{name}-shade、--ion-color-{name}-tint。
13. 新增自定义颜色时定义上述六个变量，并创建 .ion-color-{name} 类，在其中设置 --ion-color-base、--ion-color-base-rgb、--ion-color-contrast、--ion-color-contrast-rgb、--ion-color-shade、--ion-color-tint。
14. 使用全局 CSS 变量：--ion-background-color、--ion-text-color、--ion-font-family、--ion-statusbar-padding、--ion-safe-area-top/right/bottom/left、--ion-margin、--ion-padding、--ion-placeholder-opacity。
15. 实现暗色模式三种方式：系统偏好（@import '@ionic/angular/css/palettes/dark.system.css'，React/Vue 同理）；始终暗色（dark.always.css）；CSS 类切换（dark.class.css，并在 <html> 上加 .ion-palette-dark）；同时添加 <meta name="color-scheme" content="light dark" /> 以调整系统 UI 元素。
16. 预览指定平台模式：在 URL 加 ?ionic:mode=ios 或 ?ionic:mode=md，例如 http://localhost:8100/?ionic:mode=ios；在 CSS 中用 .ios ion-toolbar 或 .md ion-toolbar 定位模式专属样式。
17. 在浏览器中开发预览：运行 ionic serve 后访问 http://localhost:8100，用 DevTools 模拟移动设备（Chrome Cmd+Opt+I / Ctrl+Shift+I 后切换设备工具栏；Safari Cmd+Opt+R；Firefox Cmd+Opt+M / Ctrl+Shift+M）。
18. 真机测试：npx cap run android 或 npx cap run ios；真机 live reload 用 npx cap run android --livereload --external 或 npx cap run ios --livereload --external。
19. 调试技巧：用 debugger 关键字设断点；URL 加 ?ionic:mode=ios 预览 iOS 样式；用 ionic info 收集环境信息。
20. 使用动画工具：JavaScript/TypeScript 用 import { createAnimation } from '@ionic/core'；Angular 注入 AnimationController；React 用 CreateAnimation 组件；Vue 用 import { createAnimation } from '@ionic/vue'；关键方法有 addElement()、duration()、easing()、fromTo()、keyframes()、play()、pause()、stop()、onFinish()；支持分组、链式（通过 play() promise）与手势集成；性能上优先动画 transform 和 opacity 而非 height 和 width。
21. 使用手势工具：JavaScript/TypeScript 用 import { createGesture } from '@ionic/core'；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。
22. 处理 Android 硬件返回键：Ionic 触发 ionBackButton 事件，处理器按优先级执行（100 覆盖层、99 菜单、0 导航）；Capacitor 应用需安装 @capacitor/app。
23. 排查常见错误：ionic: command not found 时运行 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 类；暗色模式不工作时检查暗色 palette CSS 导入，类方式需在 <html> 上加 .ion-palette-dark；CSS 自定义属性不生效时注意 Shadow DOM，应使用组件文档中的 CSS 自定义属性（如 --background、--color）而非直接定位内部元素；真机 live reload 失效时确保设备与开发机在同一网络并使用 --external；ionViewWillEnter 不触发时注意该事件仅在 Ionic 路由组件（ion-router-outlet）下生效。
24. 需要框架特定模式时转用对应技能：Angular 用 ionic-angular，React 用 ionic-react，Vue 用 ionic-vue；创建新应用用 ionic-app-creation；升级版本用 ionic-app-upgrades；Capacitor 相关用 capacitor-app-development 与 capacitor-plugins。

适用边界 · 注意事项

• 不要用于创建新的 Ionic 应用（应使用 ionic-app-creation 技能）。
• 不要用于 Angular/React/Vue 框架特定模式（应使用 ionic-angular、ionic-react、ionic-vue 技能）。
• 不要用于升级 Ionic 版本（应使用 ionic-app-upgrades 技能）。