ionic-design

Ionic 框架设计

适用场景

在以下情况使用：

• 在 Capacitor 应用中编写或审查 Ion* / ion-* 组件
• 设置主题：--ion-color-*、深色模式、高对比度、平台专属样式
• iOS 与 Material Design 模式显示异常，或 mode 覆盖行为不正常
• 从 Ionic 7/8 升级到 9，或执行 npm i @ionic/*@latest 后出现错误
• 为新的 Capacitor 应用选择 Ionic 或其他 UI 套件

以下情况不要使用：

• Konsta UI 组件：konsta-ui
• Tailwind v4 安装 / 配置：tailwind-capacitor
• Ionic 之外的刘海屏 / 系统栏内边距：safe-area-handling
• 键盘遮挡输入框：capacitor-keyboard（Ionic 应用使用 resize: 'ionic'）
• 迁出 Appflow / Ionic Enterprise 插件：ionic-appflow-migration、ionic-enterprise-sdk-migration

版本（2026 年 10 月）

Package	当前版本	备注
@ionic/core、@ionic/react、@ionic/vue、@ionic/angular	9.x（latest）	v8-lts 标签上的 8.x
ionicons	8.x
Ionic 9 最低要求	Capacitor 7+、iOS 16+、Android Chromium 89+、Angular 18-22、React 18/19 + React Router 6.4+、Vue 3.5 + vue-router 5、TypeScript 5.4+

先检查已安装的版本：npm ls @ionic/core @ionic/react @ionic/vue @ionic/angular。根据已安装的主版本编写代码；不要混用 v8 和 v9 API。

工作流

1. 检查框架、Ionic 主版本、路由器版本、全局 CSS 导入、setupIonicReact / IonicVue / provideIonicAngular 配置，以及 capacitor.config 中的 Keyboard.resize。
2. **升级？**加载 references/ionic-9-migration.md；先以预览模式运行 npx @ionic/migrate，报告发现的问题，然后再应用更改。
3. 组件：references/components.md，了解页面外壳、列表、表单、覆盖层和标签页。
4. 主题：references/theming.md，了解颜色、深色 / 高对比度调色板、模式专属 CSS 和阴影部件。
5. 在两种模式下以及设备上进行验证（见下文）。

仅在涉及相应主题时加载参考资料。

避免大多数 Ionic 错误的规则

• 每个路由页面都应为 IonPage > IonHeader + IonContent（+ 可选的 IonFooter）。缺少 IonPage 会导致过渡和生命周期钩子失效。
• 滚动区域应为 ion-content。不要让 body 或包装用的 div 滚动；使用 IonContent 的 scrollToTop() / getScrollElement()。
• URL 路由使用 ion-router-outlet（IonRouterOutlet、IonTabs）。在 Ionic 9 中，ion-nav 不再与 ion-router 集成；仅在页面内用于无 URL 的本地栈。
• 安全区域通过 --ion-safe-area-top|right|bottom|left 处理（默认使用 env()）；不要额外给 body 添加内边距。需要 viewport-fit=cover。
• 表单：在控件本身设置 label + labelPlacement（<IonInput label="Email" labelPlacement="floating" />）。旧式 <IonItem><IonLabel/><IonInput/></IonItem> 标签写法已在 Ionic 8 中移除。
• 覆盖层：统一使用内联 <IonModal isOpen> / trigger 或钩子（useIonModal、modalController）；始终处理 didDismiss 以重置状态。
• 平台：通过 html 上的 .ios / .md 类或 mode CSS 选择器设置样式；isPlatform('ios') 仅用于行为判断，绝不要使用 navigator.userAgent。
• 图标：仅导入用到的图标（import { heart } from 'ionicons/icons'），并传入 icon={heart}；在独立 / 打包构建中，字符串名称需要通过 addIcons 注册。

验证

1. 构建并同步：npm run build && npx cap sync。
2. 在浏览器中运行两种模式：在开发 URL 后追加 ?ionic:mode=ios 和 ?ionic:mode=md；检查页眉、工具栏、列表和按钮。
3. 切换操作系统的深色模式（如果使用类调色板，也可以将 ion-palette-dark 添加到 <html>）；检查自定义颜色的对比度。
4. 设备检查：使用带灵动岛的 iPhone，以及启用手势导航的 Android 15/16，检查页眉 / 标签栏内边距；在表单页面打开键盘。
5. 升级后：grep -rn "ion-picker-legacy\|pickerController\|useIonPicker\|@ionic/angular/standalone\|autocorrect=\"off\"" src/ 应无匹配结果；npx tsc --noEmit 应通过。

错误处理

错误／症状	原因	解决方法
Package path ./dist/... is not exported from package（webpack）／ERR_PACKAGE_PATH_NOT_EXPORTED（Node）适用于 @ionic/core	Ionic 9 的 exports 映射；深层导入	从 @ionic/core、@ionic/core/components、@ionic/core/components/ion-*.js、@ionic/core/loader、@ionic/core/css/*.css 导入
@ionic/angular/standalone（Ionic 9）的导入错误或迁移警告	独立导入已迁移	从 @ionic/angular 导入；惰性 API 从 @ionic/angular/lazy 导入
React：Route／IonRoute 上出现 Property 'component' does not exist	Ionic 9 要求使用 React Router 6	使用 element={<Page />}，用 Navigate 替代 Redirect，用 useNavigate 替代 useHistory
升级后自动更正已开启	在 Ionic 9 中，autocorrect="off" 字符串的值为真	移除该属性或绑定 false
重新选择相同选项时不再触发 ionChange	Ionic 9 仅在值发生变化时触发	使用 ionDismiss 处理关闭
Sheet 模态框的手柄现在可聚焦／断点循环异常	Ionic 9 的 handleBehavior 默认值为 cycle	设置 handle-behavior="none" 以恢复原状
样式缺失，组件未应用样式	未导入核心 CSS	在入口处导入一次 @ionic/<fw>/css/core.css（以及结构／排版样式）
深色模式始终未启用	未导入调色板	导入 css/palettes/dark.system.css（或 .class.css，并添加 ion-palette-dark 类）
Angular 21 异步操作后视图未更新	Ionic 9 和 Angular 21 默认启用 Zoneless	使用信号／markForCheck()，或添加 provideZoneChangeDetection()

资源

• Ionic 文档：https://ionicframework.com/docs
• Ionic 9 重大变更：https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md
• 主题设置：https://ionicframework.com/docs/theming/basics
• 深色模式：https://ionicframework.com/docs/theming/dark-mode