--- name: material-design description: > Google Material Design 3 (M3) 跨平台设计系统技能。覆盖色彩系统、Typography、Shape、 Elevation、Icons、Animation、组件规范（Buttons、Cards、Navigation 等）及 Flutter/Compose/Android/Web 四平台实现。当用户提到 Material Design、MD3、M3、 Material You、动态配色、Material Icon、设计系统、Android UI、Flutter Material 时触发。 trigger: Material Design|Material Design 3|MD3|M3|material you|Android UI|Android 设计|Compose|Flutter Material|Material 3|色板|配色方案|Typography|组件规范|Elevation|阴影|Material Icon|设计系统|Google 设计|移动端设计|跨平台 UI|卡片设计|按钮样式|输入框|导航栏|Bottom Navigation|FAB|AppBar|动态配色|Material You tags: - material-design - android - flutter - web - ui-design - design-system hermes: platform: hermes version: "2.0" last_updated: "2026-04-24" source: | https://m3.material.io/ https://m3.material.io/styles/color/overview https://m3.material.io/styles/typography/overview https://m3.material.io/styles/shape/overview https://m3.material.io/styles/motion/overview/how-it-works https://m3.material.io/foundations https://m3.material.io/components https://m3.material.io/develop --- # 色彩系统 ## 色彩角色 M3 定义了 26+ 色彩角色，分为五大类： | 类别 | 角色 | 说明 | |------|------|------| | Primary | Primary, Primary Container, On Primary, On Primary Container | 主品牌色 | | Secondary | Secondary, Secondary Container, On Secondary, On Secondary Container | 辅助色 | | Tertiary | Tertiary, Tertiary Container, On Tertiary, On Tertiary Container | 强调色 | | Error | Error, Error Container, On Error, On Error Container | 错误/警告 | | Neutral | Surface, On Surface, Surface Variant, Outline, Outline Variant | 中性色 | | Neutral Special | Inverse Surface, Inverse On Surface, Inverse Primary, Surface Tint | 特殊中性 | | Scrim | Scrim | 遮罩层 | ### 动态配色（Material You）用户可通过壁纸生成主题色（User-generated color scheme）： - Android 12+：从壁纸提取主色，自动应用到整个系统 - Flutter：`ColorScheme.fromSeed(seedColor: color, brightness: Brightness.light)` - Compose：`dynamicColor = DynamicColor.getOrCreate(context)` ### 主题构建 | 平台 | 代码 | |------|------| | Flutter | `ColorScheme.fromSeed(seedColor: Colors.blue, brightness: Brightness.light)` | | Compose | `lightColorScheme(primary = ...)` | | Android XML | `Theme.Material3.DayNight.NoActionBar` | | CSS | `--md-sys-color-primary: #...;` | 详细参考：[color-system.md](references/color-system.md) --- # Typography ## Type Scale（5 角色 × 3 尺寸 = 15 种样式） | 角色 | 大（Large） | 中（Medium） | 小（Small） | |------|-----------|------------|-----------| | Display | Display Large (57sp) | Display Medium (45sp) | Display Small (36sp) | | Headline | Headline Large (32sp) | Headline Medium (28sp) | Headline Small (24sp) | | Title | Title Large (22sp) | Title Medium (16sp) | Title Small (14sp) | | Body | Body Large (16sp) | Body Medium (14sp) | Body Small (12sp) | | Label | Label Large (14sp) | Label Medium (12sp) | Label Small (11sp) | ## 字体 - **默认字体**：Roboto - **等宽字体**：Roboto Mono - **表达性字体**：Roboto Serif、Bagel Fat One、Anton（用于 Display 样式） ## 平台实现 | 平台 | API | |------|-----| | Flutter | `TextTheme(displayLarge: TextStyle(...), ...)` | | Compose | `Typography(displayLarge: TextStyle(...), ...)` | | Android | `TextAppearance.Material3.DisplayLarge` | | CSS | `font-size: 57px; font-weight: 400;` | 详细参考：[typography.md](references/typography.md) --- # Shape、Elevation、Icons ## Shape 系统 35 种形状，corner radius 分为 10 级： | 级别 | Small | Medium | Large | |------|-------|--------|-------| | 0 | 0dp | 0dp | 0dp | | 1 | 2dp | 4dp | 0dp | | 2 | 4dp | 8dp | 0dp | | 3 | 6dp | 12dp | 0dp | | 4 | 8dp | 16dp | 0dp | | 5 | 12dp | 20dp | 0dp | M3 Expressive 新增：Large Increased (20dp)、Extra Large Increased (32dp)、Extra Extra Large (48dp) ## Elevation 6 级（Level 0-5），通过 tonal surface color 或 shadow 显示高度： | Level | 用途 | 叠加高度 | |-------|------|---------| | 0 | 平面 | 0dp | | 1 | 表面 | 1dp | | 2 | 导航 | 3dp | | 3 | FAB | 6dp | | 4 | 模态 | 8dp | | 5 | 导航 + FAB | 12dp | ## Icons Material Symbols variable font，支持 4 个可变轴： - **Weight**：100-700 - **Fill**：0（Outlined）到 1（Filled） - **Optical size**：20px-48px - **Grade**：0（Regular）到 -25（more visible on small sizes）样式：Outlined、Rounded、Sharp 详细参考：[shape-elevation-icons.md](references/shape-elevation-icons.md) --- # Motion（动效系统） ## Motion Scheme | 方案 | 特点 | 适用场景 | |------|------|---------| | **Expressive** | overshoot（弹性超出） | 英雄时刻、关键交互 | | **Standard** | ease into（缓入到达） | 功能性产品 | ## Spring Physics 三个参数控制弹簧动画： | 参数 | 说明 | 典型值 | |------|------|-------| | Stiffness | 刚度，越高越快 | 100-1000 | | Damping | 阻尼，越高越少弹跳 | 10-30 | | Mass | 质量，越低响应越快 | 0.5-2 | ## 过渡动画 | 模式 | 说明 | 平台可用性 | |------|------|---------| | Container Transform | 共享元素变换 | Flutter 需自定义实现（Hero + flightShuttleBuilder）| | Fade Through | 淡入淡出 | 全平台 | | Shared Axis | 共享轴位移 | 全平台 | **注意**：Flutter 有物理弹簧动画（`SpringSimulation`）和 Hero/Staggered 动画，可实现类似 Expressive 效果，但官方 M3 Motion 库封装暂不可用。详细参考：[motion.md](references/motion.md) --- # Foundations（设计基础） ## 自适应布局 Window Size Classes： | Class | 宽度 | 布局 | |-------|------|------| | Compact | < 600dp | 单列 | | Medium | 600-840dp | 自适应列 | | Expanded | > 840dp | 多列+侧边导航 | 详细参考：[foundations.md](references/foundations.md) --- # 组件库 ## 8 大组件类别 | 类别 | 组件 | 平台可用性 | |------|------|---------| | **Buttons** | Buttons, FABs, Icon buttons, Button groups | Flutter ✅ Compose ✅ Android ✅ Web ✅ | | **Date & Time** | Date pickers, Time pickers | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Loading** | Loading indicators, Progress indicators | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Navigation** | Navigation bar, Navigation rail, Navigation drawer | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Sheets** | Bottom sheets, Side sheets | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Selection** | Checkboxes, Chips, Radio buttons, Switches | Flutter ✅ Compose ✅ Android ✅ Web ✅ | | **Text Input** | Text fields | Flutter ✅ Compose ✅ Android ✅ Web ✅ | | **Containment** | App bars, Cards, Dialogs, Lists | Flutter ✅ Compose ✅ Android ✅ Web ✅ | 详细参考： - [components-overview.md](references/components-overview.md) - [navigation-components.md](references/navigation-components.md) - [input-components.md](references/input-components.md) - [display-components.md](references/display-components.md) --- # 跨平台实现 ## Flutter ```dart MaterialApp( theme: ThemeData( useMaterial3: true, colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ), ); ``` Flutter 有物理弹簧动画（`SpringSimulation`）和 Hero/Staggered 动画，可部分实现 Expressive 效果，但官方 M3 Motion 库封装暂不可用。 ## Jetpack Compose ```kotlin MaterialTheme( colorScheme = lightColorScheme( primary = Color(0xFF6750A4), // ... ) ) { /* content */ } ``` Compose 支持完整的 M3 Expressive。 ## Android View ```xml ``` ## Web Material Web Components 处于**维护模式**，不再开发新功能。详细参考：[platform-implementation.md](references/platform-implementation.md) --- # Material Design 3 (M3) 跨平台设计系统 > 来源：Google Material Design 3 官方文档 > URL: https://m3.material.io/ > 版本：M3 Expressive（2025 年 5 月更新） > 更新日期：2026-04-24 Material Design 3（MD3/M3）是 Google 发布的最新设计系统，通过 Material You（动态配色）实现跨平台一致的视觉体验。支持 Flutter、Jetpack Compose、Android View、Web 四平台。 --- ## 设计原则 ### 核心三原则 | 原则 | 说明 | 应用场景 | |------|------|---------| | **Material Expressive** | 表达品牌个性，通过颜色、形状、动画体现 | 自定义主题色、圆角半径 | | **Responsive** | 适配不同屏幕尺寸和输入方式 | 断点布局、触摸/鼠标适配 | | **Accessible** | 为所有用户设计，包含视觉/运动/认知障碍 | 对比度要求、最小触摸区域 | ### M3 Expressive 更新（2025 年 5 月） | M3 Expressive 是 M3 的重大升级，引入了更丰富的动画系统、物理弹簧动效和组件变体。以下组件已在 M3 Expressive（May 2025）中被标记为**不再推荐**： | - Navigation Drawer → 推荐使用 Expanded Navigation Rail - Segmented Buttons → 推荐使用 Connected Button Group - **Neutral text button** → 不再推荐，使用 Filled/Outlined/Text 变体之一 - Baseline Navigation Bar/Rail → 推荐使用 Flexible/Collapsed/Expanded 变体 - Baseline Extended FAB → 推荐使用 Surface FAB --- > 📌 色彩系统完整内容见上方 [#色彩系统](#色彩系统) 章节。 > > 详细参考：[color-system.md](references/color-system.md) --- ## Typography ### Type Scale（5 角色 × 3 尺寸 = 15 种样式） | 角色 | 大（Large） | 中（Medium） | 小（Small） | |------|-----------|------------|-----------| | Display | Display Large (57sp) | Display Medium (45sp) | Display Small (36sp) | | Headline | Headline Large (32sp) | Headline Medium (28sp) | Headline Small (24sp) | | Title | Title Large (22sp) | Title Medium (16sp) | Title Small (14sp) | | Body | Body Large (16sp) | Body Medium (14sp) | Body Small (12sp) | | Label | Label Large (14sp) | Label Medium (12sp) | Label Small (11sp) | ### 字体 - **默认字体**：Roboto - **等宽字体**：Roboto Mono - **表达性字体**：Roboto Serif、Bagel Fat One、Anton（用于 Display 样式） ### 平台实现 | 平台 | API | |------|-----| | Flutter | `TextTheme(displayLarge: TextStyle(...), ...)` | | Compose | `Typography(displayLarge: TextStyle(...), ...)` | | Android | `TextAppearance.Material3.DisplayLarge` | | CSS | `font-size: 57px; font-weight: 400;` | 详细参考：[typography.md](references/typography.md) --- ## Shape、Elevation、Icons ### Shape 系统 35 种形状，corner radius 分为 10 级： | 级别 | Small | Medium | Large | |------|-------|--------|-------| | 0 | 0dp | 0dp | 0dp | | 1 | 2dp | 4dp | 0dp | | 2 | 4dp | 8dp | 0dp | | 3 | 6dp | 12dp | 0dp | | 4 | 8dp | 16dp | 0dp | | 5 | 12dp | 20dp | 0dp | M3 Expressive 新增：Large Increased (20dp)、Extra Large Increased (32dp)、Extra Extra Large (48dp) ### Elevation 6 级（Level 0-5），通过 tonal surface color 或 shadow 显示高度： | Level | 用途 | 叠加高度 | |-------|------|---------| | 0 | 平面 | 0dp | | 1 | 表面 | 1dp | | 2 | 导航 | 3dp | | 3 | FAB | 6dp | | 4 | 模态 | 8dp | | 5 | 导航 + FAB | 12dp | ### Icons Material Symbols variable font，支持 4 个可变轴： - **Weight**：100-700 - **Fill**：0（Outlined）到 1（Filled） - **Optical size**：20px-48px - **Grade**：0（Regular）到 -25（more visible on small sizes）样式：Outlined、Rounded、Sharp 详细参考：[shape-elevation-icons.md](references/shape-elevation-icons.md) --- ## Motion（动效系统） ### Motion Scheme | 方案 | 特点 | 适用场景 | |------|------|---------| | **Expressive** | overshoot（弹性超出） | 英雄时刻、关键交互 | | **Standard** | ease into（缓入到达） | 功能性产品 | ### Spring Physics 三个参数控制弹簧动画： | 参数 | 说明 | 典型值 | |------|------|-------| | Stiffness | 刚度，越高越快 | 100-1000 | | Damping | 阻尼，越高越少弹跳 | 10-30 | | Mass | 质量，越低响应越快 | 0.5-2 | ### 过渡动画 | 模式 | 说明 | 平台可用性 | |------|------|---------| | Container Transform | 共享元素变换 | Flutter 需自定义实现（Hero + flightShuttleBuilder）| | Fade Through | 淡入淡出 | 全平台 | | Shared Axis | 共享轴位移 | 全平台 | **注意**：Flutter 有物理弹簧动画（`SpringSimulation`）和 Hero/Staggered 动画，可实现类似 Expressive 效果，但官方 M3 Motion 库封装暂不可用。详细参考：[motion.md](references/motion.md) --- ## Foundations（设计基础） ### 自适应布局 Window Size Classes： | Class | 宽度 | 布局 | |-------|------|------| | Compact | < 600dp | 单列 | | Medium | 600-840dp | 自适应列 | | Expanded | > 840dp | 多列+侧边导航 | 详细参考：[foundations.md](references/foundations.md) --- ## 组件库 ### 8 大组件类别 | 类别 | 组件 | 平台可用性 | |------|------|---------| | **Buttons** | Buttons, FABs, Icon buttons, Button groups | Flutter ✅ Compose ✅ Android ✅ Web ✅ | | **Date & Time** | Date pickers, Time pickers | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Loading** | Loading indicators, Progress indicators | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Navigation** | Navigation bar, Navigation rail, Navigation drawer | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Sheets** | Bottom sheets, Side sheets | Flutter ✅ Compose ✅ Android ✅ Web ❌ | | **Selection** | Checkboxes, Chips, Radio buttons, Switches | Flutter ✅ Compose ✅ Android ✅ Web ✅ | | **Text Input** | Text fields | Flutter ✅ Compose ✅ Android ✅ Web ✅ | | **Containment** | App bars, Cards, Dialogs, Lists | Flutter ✅ Compose ✅ Android ✅ Web ✅ | 详细参考： - [components-overview.md](references/components-overview.md) - [navigation-components.md](references/navigation-components.md) - [input-components.md](references/input-components.md) - [display-components.md](references/display-components.md) --- ## 跨平台实现 ### Flutter ```dart MaterialApp( theme: ThemeData( useMaterial3: true, colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ), ); ``` Flutter 有物理弹簧动画（`SpringSimulation`）和 Hero/Staggered 动画，可部分实现 Expressive 效果，但官方 M3 Motion 库封装暂不可用。 ### Jetpack Compose ```kotlin MaterialTheme( colorScheme = lightColorScheme( primary = Color(0xFF6750A4), // ... ) ) { /* content */ } ``` Compose 支持完整的 M3 Expressive。 ### Android View ```xml ``` ### Web Material Web Components 处于**维护模式**，不再开发新功能。详细参考：[platform-implementation.md](references/platform-implementation.md) --- ## 避坑指南 ### M3 Expressive 兼容性 | 平台 | M3 Expressive 支持 | |------|-------------------| | Jetpack Compose | ✅ 完整支持 | | Android View | ✅ 完整支持 | | Flutter | ⚠️ 官方库不可用，可通过 Hero/Staggered/`SpringSimulation` 自定义实现 | | Web | ❌ 不可用 | ### 动态配色 - Android 12+ 设备自动支持 - 旧版 Android 需回退到 baseline color scheme - Web 端不支持动态配色 ### 组件废弃以下组件在 M3 Expressive（May 2025）中不再推荐： - Navigation Drawer → 使用 Navigation Rail - Segmented Buttons → 使用 Connected Button Group - **Neutral text button** → 不再推荐，使用 Filled/Outlined/Text 变体之一 ### Flutter Platform.adaptive Flutter 3.22+ 引入了 `Platform.adaptive` 系列组件，自动在 iOS（Cupertino）和 Android（Material）间切换： | 组件 | 说明 | 自动适配 | |------|------|---------| | `PlatformNavigationBar` | 底部导航栏 | iOS → CupertinoTabBar / Android → NavigationBar | | `PlatformIconButton` | 图标按钮 | iOS → CupertinoButton / Android → IconButton | | `PlatformTextButton` | 文字按钮 | iOS → CupertinoButton / Android → TextButton | | `PlatformSwitch` | 开关 | iOS → CupertinoSwitch / Android → Switch | ```dart // 最常用的 PlatformNavigationBar PlatformNavigationBar( selectedIndex: currentIndex, onDestinationSelected: (i) => setState(() => currentIndex = i), destinations: const [ NavigationDestination( icon: Icon(Icons.explore_outlined), selectedIcon: Icon(Icons.explore), label: 'Explore', ), NavigationDestination( icon: Icon(Icons.bookmark_border), selectedIcon: Icon(Icons.bookmark), label: 'Saved', ), ], ) // PlatformIconButton 示例 PlatformIconButton( icon: Icon(Icons.settings), onPressed: () => openSettings(), ) ``` --- ## 快速参考 ### 色彩角色速查 | Token | 说明 | |-------|------| | `primary` | 主品牌色 | | `onPrimary` | 主色上的文字色 | | `primaryContainer` | 主色容器 | | `surface` | 表面色 | | `surfaceVariant` | 表面变体 | | `outline` | 边框色 | | `error` | 错误色 | ### Type Scale 速查 | 角色-尺寸 | 字重 | 大小 | |---------|------|------| | Display Large | 400 | 57sp | | Headline Medium | 400 | 28sp | | Title Medium | 500 | 16sp | | Body Large | 400 | 16sp | | Label Small | 500 | 11sp | ### Corner Radius 速查 | 级别 | 值 | |------|-----| | Small | 4-8dp | | Medium | 8-16dp | | Large | 12-20dp | | Extra Large | 32dp+ | ### Elevation 速查 | Level | 叠加高度 | 典型用途 | |-------|---------|---------| | 0 | 0dp | 平面 | | 1 | 1dp | 表面 | | 3 | 6dp | FAB | | 5 | 12dp | 模态 | ### 触摸目标 | 元素 | 最小尺寸 | |------|---------| | 触摸目标 | 48dp × 48dp | | 按钮内图标 | 24dp | | List item | 48dp 高 | ### 平台支持矩阵 | 功能 | Flutter | Compose | Android | Web | |------|---------|---------|---------|-----| | M3 基础 | ✅ | ✅ | ✅ | ✅ | | M3 Expressive | ❌ | ✅ | ✅ | ❌ | | 动态配色 | ✅ | ✅ | ✅ 12+ | ❌ | | 物理弹簧动效 | ❌ | ✅ | ✅ | ❌ | | Web Components | N/A | N/A | N/A | ✅ 维护中 | --- ## 输出格式规范 ### 回复结构 1. **直接回答** — 一段简洁的话给出核心答案 2. **代码示例** — 提供完整的平台代码（如需） 3. **实现要点** — 关键步骤和注意事项 4. **避坑提醒** — 常见错误 + 正确做法 ### 示例回复 > M3 的动态配色通过 `ColorScheme.fromSeed()` 实现。Flutter 中只需传入一个种子色，系统会自动生成完整的 26 色色板，支持亮色/暗色自动切换。 > M3 Expressive 更新后，Compose 已支持物理弹簧动效，但 Flutter 仍不原生支持。 ```dart // Flutter 动态配色 MaterialApp( theme: ThemeData( useMaterial3: true, colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ), ); ``` ### 禁用格式 - ❌ 不要显式分层（避免"第一层/第二层/框架分析"等字眼） - ❌ 不要长篇解释概念，要直接给出实现 - ❌ 不要只给代码片段，要给完整可运行的示例 - ✅ 输出应是一段干净的话 + 完整代码 --- ## 来源 > 文档版本：Material Design 3 M3 Expressive（2025 年 5月更新） > URL: https://m3.material.io/ > 抓取时间：2026-04-24 > 官方文档涵盖：Color, Typography, Shape, Elevation, Icons, Motion, Foundations, Components, Develop --- ## 参考文档 | 文件 | 行数 | 覆盖内容 | |------|------|---------| | color-system.md | 427 | 色彩系统完整参考 | | typography.md | 316 | Typography 完整参考 | | shape-elevation-icons.md | 213 | Shape、Elevation、Icons | | motion.md | 507 | 动效系统完整参考 | | foundations.md | 231 | 设计原则与自适应布局 | | components-overview.md | 210 | 组件库总览 | | navigation-components.md | 137 | 导航组件详解 | | input-components.md | 252 | 输入组件详解 | | display-components.md | 221 | 展示组件详解 | | platform-implementation.md | 573 | 跨平台实现 | | color-scheme-roles.md | 293 | 色彩角色详解 | | components.md | 517 | 组件完整参考 | | components-quickref.md | 462 | 组件速查 | | m3-migration-guide.md | 520 | M2→M3 迁移指南 | | md3-api-changes.md | 379 | API 变更 | | motion-animation.md | 448 | 动效动画 | | layout-constraints.md | 103 | 布局约束 | FILE:README.md # Material Design 3 设计系统技能 Google Material Design 3 (M3) 跨平台设计系统技能，覆盖色彩、Typography、Shape、Elevation、Icons、动效及四平台实现。当用户提到 Material Design、MD3、M3、Material You、设计系统时触发。 ## 概述本 skill 覆盖 Material Design 3 完整知识体系： - **色彩系统** — 色彩角色、动态配色（Material You）、Token 映射 - **Typography** — Type Scale、品牌定制、三平台实现 - **Shape 与 Elevation** — 形状系统、阴影层级、光照模型 - **Icons** — Material Symbols、图标规格 - **Motion** — Motion Scheme、Spring 物理、过渡动画 - **Foundations** — 设计原则、自适应布局 - **组件库** — 按钮、卡片、导航、输入等 8 大组件类别 - **跨平台实现** — Flutter / Jetpack Compose / Android View / Web 四平台 ## 核心章节 ### 设计基础 | 章节 | 内容 | |------|------| | [色彩系统](SKILL.md#色彩系统) | 色彩角色、动态配色、ColorScheme.fromSeed | | [Typography](SKILL.md#Typography) | Type Scale、品牌定制、三平台字体实现 | | [Shape、Elevation、Icons](SKILL.md#Shape、Elevation、Icons) | 形状系统、阴影层级、图标规格 | ### 动效系统 | 章节 | 内容 | |------|------| | [Motion（动效系统）](SKILL.md#Motion动效系统) | Motion Scheme、Spring 物理、过渡动画 | | [快速参考](SKILL.md#快速参考) | M3 Expressive 动效一览 | ### 设计基础与组件 | 章节 | 内容 | |------|------| | [Foundations（设计基础）](SKILL.md#Foundations设计基础) | 设计原则、自适应布局 | | [组件库](SKILL.md#组件库) | 8 大组件类别、状态、废弃信息 | | [跨平台实现](SKILL.md#跨平台实现) | Flutter/Jetpack Compose/Android/Web 四平台对照 | ### 参考文档 | 文件 | 行数 | 内容 | |------|------|------| | color-system.md | 427 | 色彩系统完整参考 | | typography.md | 316 | Typography 完整参考 | | shape-elevation-icons.md | 213 | Shape、Elevation、Icons | | motion.md | 507 | 动效系统完整参考 | | foundations.md | 231 | 设计原则与自适应布局 | | components-overview.md | 210 | 组件库总览 | | navigation-components.md | 137 | 导航组件详解 | | input-components.md | 252 | 输入组件详解 | | display-components.md | 221 | 展示组件详解 | | platform-implementation.md | 573 | 跨平台实现 | | color-scheme-roles.md | 293 | 色彩角色详解 | | components.md | 517 | 组件完整参考 | | components-quickref.md | 462 | 组件速查 | | m3-migration-guide.md | 520 | M2→M3 迁移指南 | | md3-api-changes.md | 379 | API 变更 | | motion-animation.md | 448 | 动效动画 | | layout-constraints.md | 103 | 布局约束 | ## 快速参考 ### 色彩角色 | 类别 | 角色 | 说明 | |------|------|------| | Primary | Primary, Primary Container, On Primary | 主品牌色 | | Secondary | Secondary, Secondary Container | 辅助色 | | Tertiary | Tertiary, Tertiary Container | 强调色 | | Error | Error, Error Container | 错误/警告 | | Neutral | Surface, On Surface, Surface Variant, Outline | 中性色 | ### 动态配色（Material You） ```kotlin // Android Compose val dynamicColor = DynamicColor(context = LocalContext.current) val colorScheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { dynamicColor.getColorSchemeByRole(userColor) } else { ColorScheme.fromSeed(seed = userColor) } ``` ```dart // Flutter final colorScheme = ColorScheme.fromSeed( seedColor: userWallpaperColor, brightness: Brightness.light, ); ``` ### Typography Type Scale | 角色 | 用途 | 示例 | |------|------|------| | Display Large | Hero 标题 | 57sp / 64sp | | Headline Large | 章节标题 | 32sp | | Title Large | 卡片标题 | 22sp | | Body Large | 正文 | 16sp | | Label Small | 按钮文字 | 11sp | ### M3 按钮对照 | 类型 | Flutter | Android Compose | Web (H5) | |------|---------|-----------------|-----------| | Filled | `FilledButton()` | `Button()` | `.md-button--filled` | | Filled Tonal | `FilledButton.tonal()` | `FilledTonalButton()` | `.md-button--tonal` | | Outlined | `OutlinedButton()` | `OutlinedButton()` | `.md-button--outlined` | | Text | `TextButton()` | `TextButton()` | `.md-button--text` | | FAB | `FloatingActionButton()` | `FloatingActionButton()` | `.md-fab` | ### Motion Spring 配置 | 参数 | 说明 | 默认值 | |------|------|--------| | mass | 质量 | 1 | | stiffness | 刚度 | 500 | | damping | 阻尼 | 25 | | duration | 持续时间（fallback） | 300ms | ### 组件状态 | 状态 | 说明 | |------|------| | **Available** | 正常可用 | | **Expressive** | M3 Expressive 变体（2025年5月更新） | | **No longer recommended** | 废弃，不建议使用 | ### 种子色配置 ```kotlin // Android val colorScheme = ColorScheme.fromSeed( seedColor = Color(0xFF6750A4), brightness = Brightness.LIGHT, ) ``` ```swift // SwiftUI ColorScheme.from(.init(red: 0.41, green: 0.33, blue: 0.65)) ``` ```dart // Flutter MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Color(0xFF6750A4)), useMaterial3: true, ), ) ``` ## 避坑指南 ### 色彩 | 错误做法 | 正确做法 | |---------|---------| | ❌ 硬编码 HEX 颜色值 | ✅ 使用 ColorScheme 色彩角色 | | ❌ 浅色主题用深色 Primary | ✅ Primary 应同时适配浅/深色主题 | | ❌ 动态配色降级处理不一致 | ✅ 降级时统一回退到种子色方案 | ### Typography | 错误做法 | 正确做法 | |---------|---------| | ❌ 混用多个字体族 | ✅ 保持品牌字体一致性 | | ❌ 标题正文字号相同 | ✅ 按 Type Scale 层级区分 | | ❌ 在 Body 中使用 Display 字号 | ✅ 遵循 8dp 基准网格 | ### 动效 | 错误做法 | 正确做法 | |---------|---------| | ❌ 所有动画时长相同 | ✅ 按移动距离和复杂度调整（150~500ms） | | ❌ 禁用减弱动画偏好 | ✅ 检测 `prefers-reduced-motion` 并提供替代方案 | | ❌ 缺少入场/退场配对动画 | ✅ 遵循 M3 Motion 的进入/退出/禁用的语义 | ### 组件 | 错误做法 | 正确做法 | |---------|---------| | ❌ 使用已废弃组件（如 Neutral text button） | ✅ 使用对应 Expressive 变体或替代方案 | | ❌ 混用 M2 和 M3 组件 | ✅ 统一使用 useMaterial3: true | | ❌ 触摸目标小于 48dp | ✅ 最小触摸目标 48 × 48 dp | ## 来源 > Google Material Design 3（2026-04-24 访问） > - 官方文档：https://m3.material.io/ > - 色彩系统：https://m3.material.io/styles/color/overview > - Typography：https://m3.material.io/styles/typography/overview > - Shape：https://m3.material.io/styles/shape/overview > - Motion：https://m3.material.io/styles/motion/overview/how-it-works > - 组件库：https://m3.material.io/components > > 版本：Material Design 3 M3 Expressive（2025 年 5 月更新） FILE:references/color-scheme-roles.md # ColorScheme 颜色体系详解 > 来源：Flutter 中文网 / GitHub cfug/flutter.cn > URL: https://github.com/cfug/flutter.cn/blob/main/src/content/release/breaking-changes/new-color-scheme-roles.md > 版本：Flutter 3.22+ (ColorScheme 角色更新) > 抓取时间：2026-04-24 --- ## 概述 Material Design 3 的 ColorScheme 经历了多次演进： - **Flutter 3.16+：** `ColorScheme.fromSeed` 引入，动态配色基础建立 - **Flutter 3.22+：** 新增 tone-based surface 颜色角色，12 个新增 accent 颜色 --- ## ColorScheme.fromSeed（核心 API） ### 基本用法 ```dart // 从种子色生成完整配色方案 ColorScheme.fromSeed(seedColor: Colors.blue) // 指定 brightness ColorScheme.fromSeed( seedColor: Colors.blue, brightness: Brightness.dark, ) ``` ### DynamicSchemeVariant（3.22+ 新增）当种子色过亮时，`ColorScheme.fromSeed` 会生成偏暗的结果。指定 `fidelity` 变体可强制保持亮度： ```dart // ❌ 默认：亮色种子可能生成暗的 ColorScheme ColorScheme.fromSeed(seedColor: Color(0xFF0000FF)) // 亮蓝 // ✅ fidelity：保持原始亮度 ColorScheme.fromSeed( seedColor: Color(0xFF0000FF), dynamicSchemeVariant: DynamicSchemeVariant.fidelity, ) // ✅ comfortable：生成舒适的配色 ColorScheme.fromSeed( seedColor: Color(0xFF0000FF), dynamicSchemeVariant: DynamicSchemeVariant.comfortable, ) // ✅ vibrant：生成鲜艳配色 ColorScheme.fromSeed( seedColor: Color(0xFF0000FF), dynamicSchemeVariant: DynamicSchemeVariant.vibrant, ) ``` --- ## MD3 颜色角色完整列表 ### Primary（主要色） | 角色 | 说明 | 默认值 | |------|------|--------| | `primary` | 主要品牌色 | 从 seed 生成 | | `onPrimary` | primary 上的文字色 | 白色/深色 | | `primaryContainer` | 主要容器色 | 浅 primary | | `onPrimaryContainer` | primaryContainer 上的文字 | 深 primary | ### Secondary（次要色） | 角色 | 说明 | |------|------| | `secondary` | 次要品牌色 | | `onSecondary` | secondary 上的文字色 | | `secondaryContainer` | 次要容器色 | | `onSecondaryContainer` | secondaryContainer 上文字色 | ### Tertiary（第三色） | 角色 | 说明 | |------|------| | `tertiary` | 第三强调色 | | `onTertiary` | tertiary 上文字色 | | `tertiaryContainer` | 第三容器色 | | `onTertiaryContainer` | tertiaryContainer 上文字色 | ### Error（错误色） | 角色 | 说明 | |------|------| | `error` | 错误色 | | `onError` | error 上文字色 | | `errorContainer` | 错误容器色 | | `onErrorContainer` | errorContainer 上文字色 | ### Surface（表面色） | 角色 | 说明 | 引入版本 | |------|------|---------| | `surface` | 主表面色 | M2 | | `onSurface` | surface 上文字色 | M2 | | `surfaceVariant` | 表面变体 | M2 → 3.22+ 重新定义 | | `onSurfaceVariant` | surfaceVariant 上文字色 | M2 | | `surfaceBright` | 最亮表面 | 3.22+ | | `surfaceDim` | 最暗表面 | 3.22+ | | `surfaceContainer` | 标准容器色 | 3.22+ | | `surfaceContainerLow` | 低 elevation 容器 | 3.22+ | | `surfaceContainerLowest` | 最低容器色 | 3.22+ | | `surfaceContainerHigh` | 高 elevation 容器 | 3.22+ | | `surfaceContainerHighest` | 最高容器色 | 3.22+ | | `surfaceTint` | 表面色调（elevation 指示） | M2 | ### Outline（边框色） | 角色 | 说明 | |------|------| | `outline` | 边框色 | | `outlineVariant` | 边框变体 | | `inverseSurface` | 反转表面色 | | `onInverseSurface` | inverseSurface 上文字色 | | `inversePrimary` | 反转主要色 | ### Shadow / Scrim | 角色 | 说明 | |------|------| | `shadow` | 阴影色 | | `scrim` | 幕布色（对话框背景等） | --- ## Tone-Based Surface 系统（3.22+） ### 概念旧的 surface 模型使用 `surfaceTint` 叠加——在表面色上覆盖一层 tint 色来表示 elevation。MD3 改为 tone-based surface：每个 elevation 级别有独立的 surface 颜色，由 HCT 色彩系统自动计算。 ### 新旧模型对比 | 模型 | 机制 | 问题 | |------|------|------| | M2 opacity 模型 | surface + surfaceTint 叠加 | 颜色计算不准确 | | MD3 tone-based | 独立 surface 颜色 | 更精确的 elevation 感知 | ### Elevation 与 Surface 颜色映射 | Elevation | Light Mode surface | Dark Mode surface | |-----------|-------------------|-------------------| | 0dp | `surface` | `surface` | | 1dp | `surfaceContainerLow` | — | | 2dp | `surfaceContainer` | — | | 3dp | `surfaceContainerHigh` | — | | 4dp+ | `surfaceContainerHighest` | — | ### Flutter 中的使用 ```dart // MD3 中 Card 的 elevation 现在用 surfaceTint 实现 Card( elevation: 2, // 实际效果：背景色从 surface → surfaceContainerHigh // 同时 surfaceTint 层叠 ) // 如需恢复 M2 行为（透明 tint） Card( color: Theme.of(context).colorScheme.surface, elevation: 2, surfaceTintColor: Colors.transparent, ) ``` --- ## Extended Colors（扩展色板） ### 概念 Extended Colors 允许从品牌色生成多组协调的 accent 颜色。每个 seedColor 可以生成 4 组 accent 色调。 ### API ```dart ColorScheme.fromSeed( seedColor: Colors.blue, dynamicSchemeVariant: DynamicSchemeVariant.vibrant, ) // 生成 extended 颜色 ColorScheme.fromSeed( seedColor: Colors.blue, brightness: Brightness.light, ).copyWith( // 手动扩展更多颜色 ) ``` --- ## 动态配色（Dynamic Color） ### Android 12+ 动态配色 Android 12+ 支持从壁纸提取颜色作为主题色。 ```dart // 自动检测是否支持动态配色 ColorScheme.fromImageProvider( provider: const NetworkImage('https://example.com/wallpaper.jpg'), brightness: Brightness.light, ) ``` ### Flutter 中的动态配色 ```dart // 使用系统动态配色（Android 12+） MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Theme.of(context).colorScheme.seed, dynamicSchemeVariant: DynamicSchemeVariant.system, ), ), ) ``` --- ## 深色主题 ### 深色模式颜色生成 ```dart // 自动从 seed 生成深色配色 ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.indigo, brightness: Brightness.dark, ), ) // 或使用 copyWith ThemeData().copyWith( colorScheme: ColorScheme.fromSeed( seedColor: Colors.indigo, brightness: Brightness.dark, ), ) ``` ### 手动深色模式 ```dart MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo), ), darkTheme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Colors.indigo, brightness: Brightness.dark, ), ), themeMode: ThemeMode.system, ) ``` --- ## 迁移检查清单 | 检查项 | 操作 | |--------|------| | `ColorScheme.light()` 旧写法 | 改用 `ColorScheme.fromSeed()` | | `ColorScheme.background` | 替换为 `ColorScheme.surface` | | `ColorScheme.onBackground` | 替换为 `ColorScheme.onSurface` | | `ColorScheme.surfaceVariant` | 替换为 `ColorScheme.surfaceContainerHighest` | | 手动设置的 `surfaceTint` | 移除或设为 `Colors.transparent` | | 亮色种子生成偏暗 | 添加 `dynamicSchemeVariant: .fidelity` | --- ## 相关链接 - [Material 3 迁移指南](https://flutter.cn/ui/design/material) - [ColorScheme.fromSeed API](https://api.flutter.cn/flutter/material/ColorScheme/fromSeed.html) - [Material Color Utilities 包](https://pub.dev/packages/material_color_utilities) - [Flutter Material 3 Demo](https://github.com/flutter/samples/tree/main/material_3_demo) FILE:references/color-system.md --- name: material-design-color description: Google Material Design 3 色彩系统完整参考，覆盖动态配色、色板构建、主题配置。 source: https://m3.material.io/styles/color/overview --- # Material Design 3 Color System Reference > 官方文档: https://m3.material.io/styles/color/overview ## Overview The Material 3 color system provides: - **Built-in set of accessible color relationships** - colors designed to work together with proper contrast - **26+ color roles** mapped to Material Components - **Built-in dark theme colors** - automatically generated from baseline scheme - **Static baseline color scheme** - default colors assigned to each role - **Dynamic color features** - user-generated and content-based color schemes (Material You) ### Baseline vs Dynamic Color Schemes | Aspect | Baseline (Static) | Dynamic | |--------|------------------|---------| | Colors change based on wallpaper | No | Yes | | Personalized experience | No | Yes | | User-controlled contrast | No | Yes | | Accessible contrast | Yes | Yes | | M2 compatibility | Yes | No | --- ## Color Roles System ### Core Color Roles | Role | Purpose | Light Theme Default | Dark Theme Default | |------|---------|---------------------|-------------------| | **Primary** | Main brand color, key actions | #6750A4 | #D0BCFF | | **On Primary** | Text/icons on primary | #FFFFFF | #381E72 | | **Primary Container** | Secondary primary surfaces | #EADDFF | #4F378B | | **On Primary Container** | Text on primary container | #21005D | #EADDFF | | **Secondary** | Supporting UI elements | #625B71 | #CCC2DC | | **On Secondary** | Text/icons on secondary | #FFFFFF | #332D41 | | **Secondary Container** | Tertiary secondary surfaces | #E8DEF8 | #4A4458 | | **On Secondary Container** | Text on secondary container | #1D192B | #E8DEF8 | | **Tertiary** | Accent color for variety | #7D5260 | #EFB8C8 | | **On Tertiary** | Text/icons on tertiary | #FFFFFF | #492532 | | **Tertiary Container** | Tertiary surface color | #FFD8E4 | #633B48 | | **On Tertiary Container** | Text on tertiary container | #31111D | #FFD8E4 | | **Error** | Error states, destructive actions | #B3261E | #F2B8B5 | | **On Error** | Text/icons on error | #FFFFFF | #601410 | | **Error Container** | Error surface color | #F9DEDC | #8C1D18 | | **On Error Container** | Text on error container | #410E0B | #F9DEDC | | **Background** | Page background | #FFFBFE | #1C1B1F | | **On Background** | Text on background | #1C1B1F | #E6E1E5 | | **Surface** | Card/component backgrounds | #FFFBFE | #1C1B1F | | **On Surface** | Text on surface | #1C1B1F | #E6E1E5 | | **Surface Variant** | Subtle surface differentiation | #E7E0EC | #49454F | | **On Surface Variant** | Text on surface variant | #49454F | #CAC4D0 | | **Outline** | Borders, dividers | #79747E | #938F99 | | **Outline Variant** | Subtle borders | #CAC4D0 | #49454F | | **Inverse Surface** | Surfaces for inverse colors | #313033 | #E6E1E5 | | **Inverse On Surface** | Text for inverse surface | #F4EFF4 | #313033 | | **Inverse Primary** | Inverse of primary | #D0BCFF | #6750A4 | | **Surface Tint** | Tint applied to surfaces | #6750A4 | #D0BCFF | ### Surface Roles | Role | Usage | |------|-------| | Surface | Default card/component background | | Surface Container | Container-level surfaces (closer to outline) | | Surface Container Low | Lower elevation containers | | Surface Container High | Higher elevation containers | | Surface Container Highest | Highest elevation containers | | Surface Container Center | Center-height containers | --- ## Dynamic Color (Material You) ### Overview Dynamic color changes UI colors based on: - **User-generated source**: Wallpaper on Android - **Content-based source**: In-app content (album art, book covers, photos) ### User-Generated Color (Wallpaper-based) ``` Source: User's wallpaper on Android Availability: Android 12+ (API 31+) ``` **When to use:** - Products wanting personalized experience - Showcase latest Material features - Consumer apps benefiting from personalization ### Content-Based Color ``` Source: In-app content (images, media) Availability: Android 12+ (API 31+), Flutter, Web ``` **When to use:** - Content is front-and-center (media players, readers) - Team can do advanced customization - Contained screen elements adjacent to source image ### Multiple Color Sources Products can combine multiple schemes: - Baseline + User-generated - Baseline + Content-based - User-generated + Content-based --- ## Color Scheme Construction ### Light Theme Construction ``` Primary → Primary Container (lighter) → On Primary Container Primary → Surface Tint (for subtle tinting) Secondary → Secondary Container (lighter) → On Secondary Container Tertiary → Tertiary Container (lighter) → On Tertiary Container Error → Error Container (lighter) → On Error Container ``` ### Dark Theme Construction The dark theme is generated from the light theme: - Primary tones shift darker - Surface colors become darker - Contrast is maintained for accessibility ### Contrast Levels Color roles support **three levels of contrast** (May 2025 update): - Default - Medium (increased) - High (maximum) Users can select their preferred contrast level in system settings. --- ## Platform-Specific Implementation ### Flutter / Dart ```dart import 'package:flutter/material.dart'; // Using Material 3 with dynamic color MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromSeed( seedColor: Color(0x6750A4), // Primary seed color brightness: Brightness.light, ), useMaterial3: true, ), ); // Dynamic color on Android 12+ MaterialApp( theme: ThemeData( colorScheme: ColorScheme.fromDynamicBrightness( brightness: Brightness.light, ), useMaterial3: true, ), ); // Manual M3 color scheme final colorScheme = ColorScheme( primary: Color(0x6750A4), onPrimary: Color(0xFFFFFFFF), primaryContainer: Color(0xFFEADDFF), onPrimaryContainer: Color(0xFF21005D), // ... other roles ); ``` ### Jetpack Compose ```kotlin import androidx.compose.material3.* import androidx.compose.ui.graphics.Color // Using dynamic color (Android 12+) val colorScheme = when { dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> { val context = ContextAmbient.current if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context) } else -> lightColorScheme() // or custom scheme } // Baseline color scheme private val LightColorScheme = lightColorScheme( primary = Color(0x6750A4), onPrimary = Color(0xFFFFFFFF), primaryContainer = Color(0xFFEADDFF), onPrimaryContainer = Color(0xFF21005D), secondary = Color(0x625B71), onSecondary = Color(0xFFFFFFFF), secondaryContainer = Color(0xE8DEF8), onSecondaryContainer = Color(0xFF1D192B), tertiary = Color(0x7D5260), onTertiary = Color(0xFFFFFFFF), tertiaryContainer = Color(0xFFD8E4), onTertiaryContainer = Color(0xFF31111D), error = Color(0xB3261E), onError = Color(0xFFFFFFFF), errorContainer = Color(0xF9DEDC), onErrorContainer = Color(0xFF410E0B), background = Color(0xFFFBFE), onBackground = Color(0xFF1C1B1F), surface = Color(0xFFFBFE), onSurface = Color(0xFF1C1B1F), surfaceVariant = Color(0xFFE7E0EC), onSurfaceVariant = Color(0xFF49454F), outline = Color(0xFF79747E), outlineVariant = Color(0xFFCAC4D0), ) ``` ### Android (XML / Views) ```xml #6750A4 #FFFFFF #EADDFF #21005D ``` ### CSS / Web ```css /* CSS Custom Properties for M3 Color System */ :root { /* Primary */ --md-sys-color-primary: #6750A4; --md-sys-color-on-primary: #FFFFFF; --md-sys-color-primary-container: #EADDFF; --md-sys-color-on-primary-container: #21005D; /* Secondary */ --md-sys-color-secondary: #625B71; --md-sys-color-on-secondary: #FFFFFF; --md-sys-color-secondary-container: #E8DEF8; --md-sys-color-on-secondary-container: #1D192B; /* Tertiary */ --md-sys-color-tertiary: #7D5260; --md-sys-color-on-tertiary: #FFFFFF; --md-sys-color-tertiary-container: #FFD8E4; --md-sys-color-on-tertiary-container: #31111D; /* Error */ --md-sys-color-error: #B3261E; --md-sys-color-on-error: #FFFFFF; --md-sys-color-error-container: #F9DEDC; --md-sys-color-on-error-container: #410E0B; /* Background & Surface */ --md-sys-color-background: #FFFBFE; --md-sys-color-on-background: #1C1B1F; --md-sys-color-surface: #FFFBFE; --md-sys-color-on-surface: #1C1B1F; --md-sys-color-surface-variant: #E7E0EC; --md-sys-color-on-surface-variant: #49454F; /* Outline */ --md-sys-color-outline: #79747E; --md-sys-color-outline-variant: #CAC4D0; } /* Dark theme */ @media (prefers-color-scheme: dark) { :root { --md-sys-color-primary: #D0BCFF; --md-sys-color-on-primary: #381E72; --md-sys-color-primary-container: #4F378B; --md-sys-color-on-primary-container: #EADDFF; /* ... dark theme values */ } } ``` --- ## Advanced Customizations ### Applying Colors 1. **Combine multiple color schemes** - Baseline + Dynamic content-based - Multiple schemes in same app experience 2. **Remap colors to components** - Override component's default color mapping - Apply colors to custom components ### Defining New Colors 1. **Static colors in dynamic schemes** - Useful for semantic colors (brand colors that shouldn't change) - Mark specific colors as non-dynamic 2. **Custom color roles** - Define new roles beyond the 26+ standard roles - Extend the color scheme ### Adjusting Colors 1. **Custom baseline scheme** - Input your own colors to define baseline 2. **Custom dynamic scheme** - Define algorithm rules for custom dynamic output 3. **Apply dynamic color to imagery** - Tint imagery based on dynamic color scheme --- ## Accessibility Requirements ### Contrast Ratios | Element Type | Minimum Ratio (AA) | Recommended (AAA) | |--------------|--------------------|--------------------| | Normal text (< 18pt / < 14pt bold) | 4.5:1 | 7:1 | | Large text (≥ 18pt / ≥ 14pt bold) | 3:1 | 4.5:1 | | UI components / graphics | 3:1 | N/A | | Decorative elements | No requirement | N/A | ### Key Accessibility Features in M3 - **Built-in accessible color relationships**: Color pairs are designed to meet contrast requirements - **Three contrast levels**: Users can choose contrast preference in system settings - **Surface tones**: Proper tonal values ensure text readability on all surfaces - **Error color accessibility**: Error colors meet minimum contrast ratios --- ## Key Color Tokens Reference ### Tone Values (Light Theme Example) | Token | Hex | Usage | |-------|-----|-------| | Primary-0 | #FFFFFF | On Primary Container text | | Primary-10 | #EADDFF | Primary Container | | Primary-20 | #C9A7EB | - | | Primary-30 | #B185DB | - | | Primary-40 | #9A82DB | - | | Primary-50 | #8661C9 | - | | Primary-60 | #6750A4 | Primary | | Primary-70 | #563EA6 | - | | Primary-80 | #4B2C9A | - | | Primary-90 | #3A1D87 | - | | Primary-100 | #21005D | On Primary Container | ### Semantic Naming Convention ``` [Role] = Base color (e.g., primary, secondary, tertiary, error) On[Role] = Text/icon on that color (e.g., onPrimary) [Role]Container = Surface variant of that color (e.g., primaryContainer) On[Role]Container = Text on the container color ``` --- ## Resources | Resource | Link | Status | |----------|------|--------| | Design Kit (Figma) | Material Design Kit | Available | | MDC-Android | GitHub | Available | | Jetpack Compose | Compose Material 3 | Available | | Flutter | flutter/material.dart | Available | | Material Theme Builder | materialthemebuilder.com | Available | --- ## Related Documentation - [Color Overview](https://m3.material.io/styles/color/overview) - [Choosing a Color Scheme](https://m3.material.io/styles/color/choosing-a-scheme) - [Dynamic Color](https://m3.material.io/styles/color/dynamic/overview) - [Advanced Customizations](https://m3.material.io/styles/color/advanced/overview) FILE:references/components-overview.md --- name: material-design-components-overview description: Google Material Design 3 组件库总览，列出所有组件及平台可用性。 source: https://m3.material.io/components --- # Material Design 3 Components Overview Components are interactive building blocks for creating a user interface. They can be organized into categories based on their purpose: Action, containment, communication, navigation, selection, and text input. --- ## Platform Availability Key | Platform | Badge | |----------|-------| | Flutter | F | | Jetpack Compose | C | | MDC-Android | A | | Web | W | **Note:** Some components have an "Expressive" variant (marked as F✗, C✗, A✗, W✗) which is a May 2025 update with expanded features and visual design changes. Components marked as "No longer recommended" are being phased out in favor of newer alternatives. --- ## Categories ### [Buttons](./buttons.md) Buttons prompt most actions in a UI. | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Buttons](./buttons.md) | ✓ | ✓ | ✓ | ✓ | | | [Button groups](./buttons.md#button-groups) | ✓ | ✓ | ✓ | ✓ | | | [Extended FABs](./extended-fabs.md) | ✓ | ✓ | ✓ | ✓ | | | [FAB menu](./fab-menu.md) | — | — | — | — | Not indexed | | [Floating action buttons](./fabs.md) | ✓ | ✓ | ✓ | ✓ | | | [Icon buttons](./icon-buttons.md) | — | — | — | — | Not indexed | | [Segmented buttons](./segmented-buttons.md) | ✓ | ✓ | ✓ | ✗ | No longer recommended (use connected button group) | | [Split buttons](./split-buttons.md) | — | — | — | — | Not indexed | --- ### [Date & Time Pickers](./date-pickers.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Date pickers](./date-pickers.md) | — | — | — | — | Not indexed | | [Time pickers](./time-pickers.md) | — | — | — | — | Not indexed | --- ### [Loading & Progress](./loading-progress.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Loading indicators](./loading-indicators.md) | — | — | — | — | Not indexed | | [Progress indicators](./progress-indicators.md) | — | — | — | — | Not indexed | --- ### [Navigation](./navigation.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Navigation bar](./navigation-bar.md) | ✓ | ✓ | ✓ | ✗ | Flexible variant available (May 2025) | | [Navigation drawer](./navigation-drawer.md) | ✓ | ✓ | ✓ | ✗ | No longer recommended (use expanded navigation rail) | | [Navigation rail](./navigation-rail.md) | ✓ | ✓ | ✓ | ✗ | Expanded variant available (May 2025) | --- ### [Sheets](./sheets.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Bottom sheets](./bottom-sheets.md) | ✓ | ✓ | ✓ | ✗ | | | [Side sheets](./side-sheets.md) | — | — | — | — | Not indexed | --- ### [Selection](./selection.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Checkboxes](./checkboxes.md) | ✓ | ✓ | ✓ | ✓ | | | [Chips](./chips.md) | ✓ | ✓ | ✓ | ✓ | | | [Radio buttons](./radio-buttons.md) | ✓ | ✓ | ✓ | ✓ | | | [Switches](./switches.md) | ✓ | ✓ | ✓ | ✓ | | --- ### [Text Input](./text-fields.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Text fields](./text-fields.md) | ✓ | ✓ | ✓ | ✓ | | --- ### [Containment](./containment.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [App bars (Top app bar)](./app-bars.md) | ✓ | ✓ | ✓ | ✗ | Flexible variants available (May 2025) | | [Cards](./cards.md) | ✓ | ✓ | ✓ | ✗ | | | [Dialogs](./dialogs.md) | ✓ | ✓ | ✓ | ✓ | | | [Lists](./lists.md) | ✓ | ✓ | ✓ | ✓ | Expressive variant available (Dec 2025) | | [Sheets](./sheets.md) | — | — | — | — | See Navigation category | --- ### [Communication](./communication.md) | Component | F | C | A | W | Status | |-----------|---|---|---|---|--------| | [Snackbars](./snackbars.md) | ✓ | ✓ | ✓ | ✗ | | --- ## Component Status Summary ### Fully Available (All Platforms) - Buttons - Checkboxes - Chips - Dialogs - Lists - Radio buttons - Switches - Text fields ### Desktop/Web Unavailable - App bars (Web ✗) - Bottom sheets (Web ✗) - Cards (Web ✗) - FABs (Web ✗) - Extended FABs (Web ✗) - Navigation bar (Web ✗) - Navigation drawer (Web ✗) - Navigation rail (Web ✗) - Segmented buttons (Web ✗) - Snackbars (Web ✗) ### No Longer Recommended (M3 Expressive May 2025) - Navigation drawer → Use expanded navigation rail - Segmented buttons → Use connected button group - Baseline navigation bar → Use flexible navigation bar - Baseline navigation rail → Use collapsed/expanded navigation rail ### New Expressive Variants Available (May 2025) - Lists: Expressive variant with segmented visual style - Navigation bar: Flexible variant - Navigation rail: Collapsed and expanded variants - App bars: Medium flexible and large flexible variants --- ## M3 Expressive Update (May 2025) The May 2025 M3 Expressive update introduced: - New component sizes and shapes - Toggle functionality for buttons - Shape morphs when selected or pressed - Expanded navigation components - Improved typography --- ## Quick Reference Table | Component | Category | F | C | A | W | |-----------|----------|---|---|---|---| | App bars | Containment | ✓ | ✓ | ✓ | ✗ | | Bottom sheets | Sheets | ✓ | ✓ | ✓ | ✗ | | Button groups | Buttons | ✓ | ✓ | ✓ | ✓ | | Buttons | Buttons | ✓ | ✓ | ✓ | ✓ | | Cards | Containment | ✓ | ✓ | ✓ | ✗ | | Checkboxes | Selection | ✓ | ✓ | ✓ | ✓ | | Chips | Selection | ✓ | ✓ | ✓ | ✓ | | Date pickers | Date & Time | — | — | — | — | | Dialogs | Containment | ✓ | ✓ | ✓ | ✓ | | Extended FABs | Buttons | ✓ | ✓ | ✓ | ✓ | | FAB menu | Buttons | — | — | — | — | | Floating action buttons | Buttons | ✓ | ✓ | ✓ | ✓ | | Icon buttons | Buttons | — | — | — | — | | Lists | Containment | ✓ | ✓ | ✓ | ✓ | | Loading indicators | Loading | — | — | — | — | | Navigation bar | Navigation | ✓ | ✓ | ✓ | ✗ | | Navigation drawer | Navigation | ✓ | ✓ | ✓ | ✗ | | Navigation rail | Navigation | ✓ | ✓ | ✓ | ✗ | | Progress indicators | Loading | — | — | — | — | | Radio buttons | Selection | ✓ | ✓ | ✓ | ✓ | | Segmented buttons | Buttons | ✓ | ✓ | ✓ | ✗ | | Side sheets | Sheets | — | — | — | — | | Snackbars | Communication | ✓ | ✓ | ✓ | ✗ | | Split buttons | Buttons | — | — | — | — | | Switches | Selection | ✓ | ✓ | ✓ | ✓ | | Text fields | Text Input | ✓ | ✓ | ✓ | ✓ | | Time pickers | Date & Time | — | — | — | — | --- ## Related References - [Motion System](../foundations/motion-system.md) - [Color Overview](../foundations/color-overview.md) - [Typography Overview](../foundations/typography-overview.md) - [Elevation Overview](../foundations/elevation-overview.md) - [Shape Overview](../foundations/shape-overview.md) FILE:references/components-quickref.md # Material Design 3 组件代码对照速查 > 来源：Google Material Design 3 — Components Reference > URL: https://m3.material.io/components > 版本：M3 2024-2025 > 抓取时间：2026-04-23 --- hermes: source: https://m3.material.io/ version: "2024-2025" platform: android|flutter|web updated: 2026-04-23 ## 按钮（Buttons）对照表 | 属性 | Android Compose | Flutter | Web (H5) | |------|----------------|---------|-----------| | **Filled Button** | `Button()` | `FilledButton()` | `.md-button--filled` | | **Filled Tonal** | `FilledTonalButton()` | `FilledButton.tonal()` | `.md-button--tonal` | | **Outlined** | `OutlinedButton()` | `OutlinedButton()` | `.md-button--outlined` | | **Text** | `TextButton()` | `TextButton()` | `.md-button--text` | | **FAB Standard** | `FloatingActionButton()` | `FloatingActionButton()` | `.md-fab` | | **FAB Large** | `LargeFloatingActionButton()` | `FloatingActionButton.large()` | `.md-fab--large` | | **FAB Extended** | `ExtendedFloatingActionButton()` | `FloatingActionButton.extended()` | 自定义 | | **高度** | `40.dp` | `40.0` | `40px` | | **最小宽度** | `64.dp` | `64.0` | `64px` | | **圆角** | `28.dp` | `BorderRadius.circular(28)` | `border-radius: 28px` | | **图标尺寸** | `24.dp` | `24.0` | `24px` | ### Android Compose 代码 ```kotlin // 标准 Filled Button Button( onClick = { /* */ }, modifier = Modifier.height(40.dp), shape = RoundedCornerCorner(28.dp) ) { Text("按钮文字") } // FAB Large LargeFloatingActionButton( onClick = { /* */ }, shape = RoundedCornerCorner(28.dp), containerColor = MaterialTheme.colorScheme.primaryContainer, contentColor = MaterialTheme.colorScheme.onPrimaryContainer ) { Icon(Icons.Filled.Add, contentDescription = "添加") } // FAB Extended ExtendedFloatingActionButton( onClick = { /* */ }, icon = { Icon(Icons.Filled.Add) }, text = { Text("添加到") }, containerColor = MaterialTheme.colorScheme.primaryContainer ) // Icon Button IconButton( onClick = { /* */ }, modifier = Modifier.size(48.dp) // 触摸目标 48dp ) { Icon(Icons.Filled.Settings, contentDescription = "设置") } ``` ### Flutter 代码 ```dart // Filled Button FilledButton( onPressed: () { /* */ }, style: FilledButton.styleFrom( minimumSize: const Size(64, 40), shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), ), child: const Text('按钮文字'), ) // FAB Large FloatingActionButton.large( onPressed: () { /* */ }, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), backgroundColor: Theme.of(context).colorScheme.primaryContainer, child: const Icon(Icons.add), ) // FAB Extended FloatingActionButton.extended( onPressed: () { /* */ }, icon: const Icon(Icons.add), label: const Text('添加到'), ) // Icon Button IconButton( onPressed: () { /* */ }, icon: const Icon(Icons.settings), iconSize: 24, // 注意：IconButton 默认触摸目标偏小，建议外套 Container ) ``` --- ## 卡片（Cards）对照表 | 属性 | Android Compose | Flutter | Web (H5) | |------|----------------|---------|-----------| | **圆角** | `28.dp` | `BorderRadius.circular(28)` | `border-radius: 28px` | | **内边距** | `16.dp` | `16.0` | `padding: 16px` | | **背景** | `colorScheme.surface` | `colorScheme.surface` | `var(--md-sys-color-surface)` | | **Surface Tint** | `0.05f` | `0.05` | `opacity: 0.05` | | **边框** | 无（用 Surface Tint） | 无 | 无 | ### Android Compose ```kotlin // Elevated Card (MD3 推荐) Card( modifier = Modifier.fillMaxWidth().tint( MaterialTheme.colorScheme.primary.copy(alpha = 0.05f) ), shape = RoundedCornerCorner(28.dp), colors = CardDefaults.cardColors( containerColor = MaterialTheme.colorScheme.surface ), elevation = CardDefaults.cardElevation(defaultElevation = 0.dp) ) { Column(modifier = Modifier.padding(16.dp)) { Text("卡片标题", style = MaterialTheme.typography.titleMedium) Spacer(Modifier.height(8.dp)) Text("卡片正文内容", style = MaterialTheme.typography.bodyMedium) } } // 带图片的卡片 Card( modifier = Modifier.fillMaxWidth(), shape = RoundedCornerCorner(28.dp) ) { Column { AsyncImage( model = "https://example.com/image.jpg", contentDescription = "图片描述", modifier = Modifier.fillMaxWidth().height(180.dp) ) Column(modifier = Modifier.padding(16.dp)) { Text("带图片的卡片", style = MaterialTheme.typography.titleMedium) } } } ``` ### Flutter ```dart Card( elevation: 0, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), color: Theme.of(context).colorScheme.surface, child: Padding( padding: const EdgeInsets.all(16), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text('卡片标题', style: Theme.of(context).typography.titleMedium), const SizedBox(height: 8), Text('卡片正文内容', style: Theme.of(context).typography.bodyMedium), ], ), ), ) // 带图片 Card( elevation: 0, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), clipBehavior: Clip.antiAlias, child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Image.network( 'https://example.com/image.jpg', width: double.infinity, height: 180, fit: BoxFit.cover, ), Padding( padding: const EdgeInsets.all(16), child: Text('带图片的卡片', style: Theme.of(context).typography.titleMedium), ), ], ), ) ``` --- ## 输入组件对照表 | 属性 | Android Compose | Flutter | Web (H5) | |------|----------------|---------|-----------| | **OutlinedTextField** | `OutlinedTextField()` | `TextField(decoration: InputDecoration(border: OutlineInputBorder))` | `` | | **SearchBar** | `SearchBar()` | `SearchBar()` | 自定义 | | **高度** | `56.dp` | `56.0` | `56px` | | **标签** | `label = { Text(...) }` | `labelText:` | `` | | **顶部圆角** | `4.dp` | `BorderRadius.vertical(top: Radius.circular(4))` | `border-radius: 4px 4px 0 0` | ### Android Compose ```kotlin // Outlined TextField（MD3 推荐） OutlinedTextField( value = text, onValueChange = { text = it }, label = { Text("邮箱") }, placeholder = { Text("请输入邮箱地址") }, leadingIcon = { Icon(Icons.Filled.Email) }, trailingIcon = { if (text.isNotEmpty()) { IconButton(Icons.Filled.Clear) { text = "" } } }, modifier = Modifier.fillMaxWidth(), shape = RoundedCornerCorner(topStart = 4.dp, topEnd = 4.dp), colors = OutlinedTextFieldDefaults.colors( focusedBorderColor = MaterialTheme.colorScheme.primary, unfocusedBorderColor = MaterialTheme.colorScheme.outline, ) ) // 多行 TextField OutlinedTextField( value = text, onValueChange = { text = it }, label = { Text("备注") }, modifier = Modifier.fillMaxWidth().height(120.dp), maxLines = 5, shape = RoundedCornerCorner(4.dp) ) // SearchBar（MD3 新组件） SearchBar( inputField = { SearchBarDefaults.InputField( query = query, onQueryChange = { query = it }, onSearch = { /* 执行搜索 */ }, expanded = false, placeholder = { Text("搜索") }, leading = { Icon(Icons.Search) }, trailing = { if (query.isNotEmpty()) IconButton(Icons.Filled.Clear) { query = "" } } ) }, expanded = false, onExpandedChange = { }, modifier = Modifier.fillMaxWidth() ) { /* 搜索结果列表 */ } ``` ### Flutter ```dart // Outlined TextField TextField( decoration: InputDecoration( labelText: '邮箱', hintText: '请输入邮箱地址', prefixIcon: Icon(Icons.email), border: OutlineInputBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(4)), ), focusedBorder: OutlineInputBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(4)), borderSide: BorderSide( color: Theme.of(context).colorScheme.primary, width: 2, ), ), ), ) // 多行 TextField TextField( decoration: InputDecoration( labelText: '备注', border: OutlineInputBorder(borderRadius: BorderRadius.circular(4)), ), maxLines: 5, minLines: 3, ) // SearchBar (Material 3) SearchBar( hint: const Text('搜索'), leading: const Icon(Icons.search), trailing: [ if (query.isNotEmpty) IconButton( icon: const Icon(Icons.clear), onPressed: () => setState(() => query = ''), ), ], onChanged: (value) => setState(() => query = value), ) ``` --- ## 导航组件对照表 | 属性 | Android Compose | Flutter | Web (H5) | |------|----------------|---------|-----------| | **NavigationBar** | `NavigationBar()` | `NavigationBar()` | `.md-bottom-nav` | | **高度** | `80.dp` | `80.0` | `80px` | | **图标尺寸** | `24.dp` | `24.0` | `24px` | | **选中色** | `onSurface` | `onSurfaceVariant` | `var(--md-sys-color-on-surface)` | | **Indicator** | `surfaceTint 8%` | `tertiaryContainer` | Surface Tint Level 2 | ### Android Compose ```kotlin NavigationBar( modifier = Modifier.height(80.dp), containerColor = MaterialTheme.colorScheme.surface, tonalElevation = 0.dp ) { NavigationBarItem( selected = selectedIndex == 0, onClick = { selectedIndex = 0 }, icon = { Icon(if (selectedIndex == 0) Icons.Filled.Home else Icons.Outlined.Home) }, label = { Text("首页") }, colors = NavigationBarItemDefaults.colors( selectedIconColor = MaterialTheme.colorScheme.onSurface, selectedLabelColor = MaterialTheme.colorScheme.onSurface, indicatorColor = MaterialTheme.colorScheme.surfaceTint.copy(alpha = 0.08f), unselectedIconColor = MaterialTheme.colorScheme.onSurfaceVariant, unselectedLabelColor = MaterialTheme.colorScheme.onSurfaceVariant, ) ) // 更多 items... } ``` ### Flutter ```dart NavigationBar( height: 80, selectedIndex: selectedIndex, onDestinationSelected: (index) => setState(() => selectedIndex = index), destinations: const [ NavigationDestination( icon: Icon(Icons.outlined_home), selectedIcon: Icon(Icons.filled_home), label: '首页', ), NavigationDestination( icon: Icon(Icons.outlined_search), selectedIcon: Icon(Icons.filled_search), label: '搜索', ), NavigationDestination( icon: Icon(Icons.outlined_person), selectedIcon: Icon(Icons.filled_person), label: '我的', ), ], ) ``` --- ## Chips 对照表 | 类型 | Android Compose | Flutter | Web (H5) | |------|----------------|---------|-----------| | **Filter Chip** | `FilterChip()` | `FilterChip()` | `.md-chip--filter` | | **Assist Chip** | `AssistChip()` | `AssistChip()` | `.md-chip--assist` | | **Suggestion Chip** | `SuggestionChip()` | `SuggestionChip()` | `.md-chip--suggestion` | | **圆角** | `8.dp` | `BorderRadius.circular(8)` | `border-radius: 8px` | | **高度** | `32.dp` | `32.0` | `32px` | --- ## 对话框与底部表单 ### Modal Bottom Sheet | 属性 | Android Compose | Flutter | Web (H5) | |------|----------------|---------|-----------| | **顶部圆角** | `28.dp` | `BorderRadius.vertical(top: Radius.circular(28))` | `border-radius: 28px 28px 0 0` | | **拖动指示器** | `BottomSheetDefaults.DragHandle()` | `自动显示` | 自定义 | ### Android Compose ```kotlin ModalBottomSheet( onDismissRequest = { /* 关闭 */ }, sheetState = sheetState, shape = RoundedCornerCorner(topStart = 28.dp, topEnd = 28.dp), containerColor = MaterialTheme.colorScheme.surface, dragHandle = { BottomSheetDefaults.DragHandle(color = MaterialTheme.colorScheme.onSurfaceVariant) } ) { Column(modifier = Modifier.padding(16.dp)) { Text("标题", style = MaterialTheme.typography.titleLarge) Spacer(Modifier.height(16.dp)) Text("内容...") } } ``` ### Flutter ```dart showModalBottomSheet( context: context, shape: const RoundedRectangleBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(28)), ), builder: (context) => Padding( padding: const EdgeInsets.all(16), child: Column( mainAxisSize: MainAxisSize.min, children: [ Text('标题', style: Theme.of(context).typography.titleLarge), const SizedBox(height: 16), Text('内容...'), ], ), ), ) ``` --- ## 尺寸规范速查表 | 元素 | 尺寸 | |------|------| | 最小触摸区域 | 48×48dp/px | | Filled Button 高度 | 40dp | | Button 圆角 | 28dp（全圆角） | | FAB Standard | 56×56dp | | FAB Large | 96×96dp | | Card 圆角 | 28dp | | TextField 高度 | 56dp | | NavigationBar 高度 | 80dp | | Bottom Sheet 圆角 | 28dp | | Chips 圆角 | 8dp | | Icon 标准尺寸 | 24dp | | Icon 小尺寸 | 20dp | | 对比度（正文） | 4.5:1 | | 对比度（大字） | 3:1 | --- ## 来源 FILE:references/components.md # Material Design 3 组件规范详解 > 来源：Google Material Design 3 — Components > URL: https://m3.material.io/components > 版本：M3 2024-2025 > 抓取时间：2026-04-23 --- hermes: source: https://m3.material.io/ version: "2024-2025" platform: android|flutter|web updated: 2026-04-23 ## 按钮（Buttons） ### 五种按钮类型 | 类型 | 强调级别 | 圆角 | 典型用法 | |------|---------|------|---------| | **Filled Button** | 高（Primary） | 28dp（全圆角） | 确定/提交主操作 | | **Filled Tonal Button** | 中（Secondary） | 28dp | 次要主操作 | | **Outlined Button** | 低 | 28dp | 辅助确认 | | **Text Button** | 最低 | 无 | 取消/跳过/链接 | | **FAB** | 最高 | 16dp（Small）/28dp（Large） | 创建/添加 | ### 尺寸规范 | 属性 | Filled/Outlined | FAB Small | FAB Standard | FAB Large | |------|----------------|-----------|--------------|-----------| | 高度 | 40dp | 40dp | 56dp | 96dp | | 宽度 | min 64dp | 40dp | 56dp | 96dp | | 圆角 | 28dp | 12dp | 16dp | 28dp | | Icon Size | 24dp | 24dp | 24dp | 36dp | ### Android Compose 按钮 ```kotlin import androidx.compose.material3.* import androidx.compose.ui.unit.dp // Filled Button Button( onClick = { }, modifier = Modifier.height(40.dp), shape = RoundedCornerCorner(28.dp) ) { Text("主要操作") } // Filled Tonal Button FilledTonalButton( onClick = { }, modifier = Modifier.height(40.dp), shape = RoundedCornerCorner(28.dp) ) { Text("次要操作") } // Outlined Button OutlinedButton( onClick = { }, modifier = Modifier.height(40.dp), shape = RoundedCornerCorner(28.dp) ) { Text("辅助操作") } // Text Button TextButton(onClick = { }) { Text("文字按钮") } // FAB Large LargeFloatingActionButton( onClick = { }, shape = RoundedCornerCorner(28.dp), containerColor = MaterialTheme.colorScheme.primaryContainer, contentColor = MaterialTheme.colorScheme.onPrimaryContainer ) { Icon(Icons.Filled.Add, contentDescription = "添加") } // Extended FAB ExtendedFloatingActionButton( onClick = { }, containerColor = MaterialTheme.colorScheme.primaryContainer, contentColor = MaterialTheme.colorScheme.onPrimaryContainer ) { Icon(Icons.Filled.Add, contentDescription = null) Spacer(12.dp) Text("添加到") } ``` ### Flutter 按钮 ```dart import 'package:flutter/material.dart'; // Filled Button FilledButton( onPressed: () {}, style: FilledButton.styleFrom( minimumSize: const Size(64, 40), shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), ), child: const Text('主要操作'), ) // Filled Tonal Button FilledButton.tonal( onPressed: () {}, style: FilledButton.styleFrom( minimumSize: const Size(64, 40), shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), ), child: const Text('次要操作'), ) // Outlined Button OutlinedButton( onPressed: () {}, style: OutlinedButton.styleFrom( minimumSize: const Size(64, 40), shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), ), child: const Text('辅助操作'), ) // Text Button TextButton(onPressed: () {}, child: const Text('文字按钮')) // FAB Large FloatingActionButton.large( onPressed: () {}, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), child: const Icon(Icons.add), ) // Extended FAB FloatingActionButton.extended( onPressed: () {}, icon: const Icon(Icons.add), label: const Text('添加到'), shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(16)), ) ``` --- ## 卡片（Cards） ### 卡片规范 | 属性 | 规范值 | |------|--------| | 圆角 | `28dp` | | 内边距 | `16dp` | | 容器背景 | `Surface` + Surface Tint Level 1 | | 无边框 | 层级通过 Surface Tint 区分 | | Elevation | 0dp（MD3 不再用阴影表示层级） | ### 支持的卡片类型 | 类型 | 用途 | Surface Tint Level | |------|------|-------------------| | Elevated Card | 静止状态 | Level 1（5%） | | Filled Card | 填充背景 | 静态填充色 | | Outlined Card | 带边框 | 1dp Outline 边框 | ### Android Compose Cards ```kotlin // Elevated Card（MD3 推荐） Card( modifier = Modifier .fillMaxWidth() .tint(MaterialTheme.colorScheme.primaryTint.copy(alpha = 0.05f)), shape = RoundedCornerCorner(28.dp), colors = CardDefaults.cardColors( containerColor = MaterialTheme.colorScheme.surface ), elevation = CardDefaults.cardElevation(defaultElevation = 0.dp) ) { Column(modifier = Modifier.padding(16.dp)) { Text("卡片标题", style = MaterialTheme.typography.titleMedium) Spacer(Modifier.height(8.dp)) Text("卡片内容", style = MaterialTheme.typography.bodyMedium) } } // Filled Card Card( modifier = Modifier.fillMaxWidth(), shape = RoundedCornerCorner(28.dp), colors = CardDefaults.cardColors( containerColor = MaterialTheme.colorScheme.surfaceContainerLow ) ) { /* content */ } // Outlined Card Card( modifier = Modifier.fillMaxWidth(), shape = RoundedCornerCorner(28.dp), colors = CardDefaults.cardColors( containerColor = MaterialTheme.colorScheme.surface ), border = BorderStroke(1.dp, MaterialTheme.colorScheme.outline) ) { /* content */ } ``` ### Flutter Cards ```dart // Elevated Card Card( elevation: 0, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), color: Theme.of(context).colorScheme.surface, child: Padding( padding: const EdgeInsets.all(16), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text('卡片标题', style: Theme.of(context).typography.titleMedium), const SizedBox(height: 8), Text('卡片内容', style: Theme.of(context).typography.bodyMedium), ], ), ), ) // Filled Card Card( elevation: 0, shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), color: Theme.of(context).colorScheme.surfaceContainerLow, child: // content ) // Outlined Card Card( elevation: 0, shape: RoundedRectangleBorder( borderRadius: BorderRadius.circular(28), side: BorderSide(color: Theme.of(context).colorScheme.outline), ), color: Theme.of(context).colorScheme.surface, child: // content ) ``` --- ## 输入组件（Text Fields & SearchBar） ### TextField 样式对比 | 样式 | 顶部圆角 | 底部圆角 | 边框 | 用法 | |------|---------|---------|------|------| | **Outlined** | 4dp | 4dp | 有 | **MD3 推荐**，表单首选 | | **Filled** | 0dp | 4dp | 无 | 搜索框、底部表单 | ### Outlined TextField 规范 - 标签：浮动标签（Floating Label） - 聚焦时：边框变为 Primary 色，厚度 2dp - 未聚焦：边框为 Outline 色，厚度 1dp - 错误状态：边框变为 Error 色 ### Android Compose TextField ```kotlin import androidx.compose.material3.* import androidx.compose.ui.text.input.PasswordVisualTransformation import androidx.compose.ui.text.input.VisualTransformation // Outlined TextField（MD3 推荐） OutlinedTextField( value = text, onValueChange = { text = it }, label = { Text("标签文字") }, placeholder = { Text("提示文字") }, modifier = Modifier.fillMaxWidth(), shape = RoundedCornerCorner(topStart = 4.dp, topEnd = 4.dp, bottomStart = 4.dp, bottomEnd = 4.dp), colors = OutlinedTextFieldDefaults.colors( focusedBorderColor = MaterialTheme.colorScheme.primary, unfocusedBorderColor = MaterialTheme.colorScheme.outline, errorBorderColor = MaterialTheme.colorScheme.error, focusedLabelColor = MaterialTheme.colorScheme.primary, ) ) // 带前导/尾随图标 OutlinedTextField( value = text, onValueChange = { text = it }, label = { Text("密码") }, leadingIcon = { Icon(Icons.Filled.Lock, contentDescription = null) }, trailingIcon = { IconButton(onClick = { passwordVisible = !passwordVisible }) { Icon( if (passwordVisible) Icons.Filled.VisibilityOff else Icons.Filled.Visibility, contentDescription = "切换密码可见性" ) } }, visualTransformation = if (passwordVisible) VisualTransformation.None else PasswordVisualTransformation(), modifier = Modifier.fillMaxWidth(), ) // SearchBar（MD3 新组件） SearchBar( inputField = { SearchBarDefaults.InputField( query = query, onQueryChange = { query = it }, onSearch = { /* 搜索 */ }, expanded = false, placeholder = { Text("搜索") }, leading = { Icon(Icons.Search) }, trailing = { if (query.isNotEmpty()) { IconButton(Icons.Filled.Clear) { query = "" } } } ) }, expanded = false, onExpandedChange = { /* 展开/收起搜索结果 */ }, modifier = Modifier.fillMaxWidth() ) { /* 搜索结果内容 */ } ``` ### Flutter TextField ```dart // Outlined TextField TextField( decoration: InputDecoration( labelText: '标签文字', hintText: '提示文字', border: OutlineInputBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(4)), ), focusedBorder: OutlineInputBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(4)), borderSide: BorderSide( color: Theme.of(context).colorScheme.primary, width: 2, ), ), enabledBorder: OutlineInputBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(4)), borderSide: BorderSide(color: Theme.of(context).colorScheme.outline), ), errorBorder: OutlineInputBorder( borderRadius: BorderRadius.vertical(top: Radius.circular(4)), borderSide: BorderSide(color: Theme.of(context).colorScheme.error), ), ), ) // 带密码可见性切换 TextField( obscureText: !passwordVisible, decoration: InputDecoration( labelText: '密码', prefixIcon: Icon(Icons.lock), suffixIcon: IconButton( icon: Icon(passwordVisible ? Icons.visibility_off : Icons.visibility), onPressed: () => setState(() => passwordVisible = !passwordVisible), ), ), ) ``` --- ## 导航组件 ### Bottom Navigation | 属性 | 规范 | |------|------| | 高度 | `80dp` | | 图标尺寸 | `24dp` | | 标签 | 始终显示（MD3 vs MD2 关键区别） | | 选中图标色 | `On Surface` | | 选中标签色 | `On Surface` | | 选中态背景 | Surface Tint Level 2（8%） | ### Android Compose NavigationBar ```kotlin NavigationBar( modifier = Modifier.height(80.dp), containerColor = MaterialTheme.colorScheme.surface, tonalElevation = 0.dp ) { items.forEachIndexed { index, item -> NavigationBarItem( selected = selectedIndex == index, onClick = { selectedIndex = index }, icon = { Icon( if (selectedIndex == index) item.selectedIcon else item.unselectedIcon, contentDescription = item.label ) }, label = { Text(item.label) }, colors = NavigationBarItemDefaults.colors( selectedIconColor = MaterialTheme.colorScheme.onSurface, selectedLabelColor = MaterialTheme.colorScheme.onSurface, indicatorColor = MaterialTheme.colorScheme.surfaceTint.copy(alpha = 0.08f), unselectedIconColor = MaterialTheme.colorScheme.onSurfaceVariant, unselectedLabelColor = MaterialTheme.colorScheme.onSurfaceVariant, ) ) } } ``` ### Flutter NavigationBar ```dart NavigationBar( height: 80, selectedIndex: selectedIndex, onDestinationSelected: (index) => setState(() => selectedIndex = index), destinations: [ NavigationDestination( icon: Icon(Icons.outlined_home), selectedIcon: Icon(Icons.filled_home), label: '首页', ), NavigationDestination( icon: Icon(Icons.outlined_search), selectedIcon: Icon(Icons.filled_search), label: '搜索', ), NavigationDestination( icon: Icon(Icons.outlined_person), selectedIcon: Icon(Icons.filled_person), label: '我的', ), ], ) ``` ### Navigation Drawer | 属性 | 规范 | |------|------| | 宽度 | `360dp` | | 圆角（右侧） | `28dp`（与屏幕右边缘对齐） | | 背景色 | `SurfaceContainerLow` | | 头部高度 | `160dp` | ### Navigation Rail（导航导轨） | 属性 | 规范 | |------|------| | 宽度 | `80dp` | | 图标尺寸 | `24dp` | | 标签 | 始终显示 | | 适用场景 | 平板电脑横屏、桌面端 | --- ## Chips（ Chips 组件） ### Chip 类型 | 类型 | 背景色 | 边框 | 用法 | |------|--------|------|------| | **Filter Chip** | Surface Tint / Primary Container | 无（选中时） | 多选过滤 | | **Input Chip** | Surface | 有（Outline） | 输入标签（联系人选择） | | **Assist Chip** | Surface | 无 | 辅助操作（"发送邮件"） | | **Suggestion Chip** | Surface | 无 | 建议文本 | ### 圆角规范 | 组件 | 圆角 | |------|------| | Chips | `8dp` | | Filled Button / Outlined Button | `28dp` | | Cards | `28dp` | | FAB | `16dp`（Small）/ `28dp`（Large） | | TextField | `4dp`（顶部）/ `0dp`（底部） | --- ## 对话框与模态（Dialogs & Modal） ### Modal Bottom Sheet | 属性 | 规范 | |------|------| | 圆角（顶部） | `28dp` | | 拖动指示器 | 宽 32dp × 高 4dp，圆角 2dp | | 最大高度 | 屏幕高度 50% | ### Android Compose ModalBottomSheet ```kotlin ModalBottomSheet( onDismissRequest = { /* 关闭 */ }, sheetState = sheetState, shape = RoundedCornerCorner(topStart = 28.dp, topEnd = 28.dp), containerColor = MaterialTheme.colorScheme.surface, dragHandle = { BottomSheetDefaults.DragHandle(color = MaterialTheme.colorScheme.onSurfaceVariant) } ) { Column(modifier = Modifier.padding(16.dp)) { Text("标题") Spacer(Modifier.height(16.dp)) // 内容 } } ``` --- ## 来源 FILE:references/display-components.md --- name: Display Components description: Material Design 3 display components including FAB, Cards, Dialogs, Snackbars, Bottom Sheets, and Lists source: https://m3.material.io/components/extended-fab/overview --- # Display Components ## FAB (Floating Action Button) **Description:** FABs provide quick access to primary actions on a screen. Use for the most common or important action. **Source:** https://m3.material.io/components/extended-fab/overview ### Variants | Variant | Size | Description | |---------|------|-------------| | Small | 56dp | Compact FAB | | Medium | 80dp | Standard extended FAB | | Large | 96dp | Large extended FAB | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | Jetpack Compose: Expressive | Available | | Android | MDC-Android | Available | | Android | MDC-Android: Expressive | Available | | Web | Web | Available | ### Key Updates (M3 Expressive) - Extended FAB now has three sizes: small, medium, large with updated type styles - Baseline extended FAB (56dp) no longer recommended - Surface FAB no longer recommended - Adjusted typography to be larger --- ## Cards **Description:** Cards display content and actions about a single subject. **Source:** https://m3.material.io/components/cards/overview ### Variants | Variant | Description | |---------|-------------| | Elevated | Shadow elevation, on-surface background | | Filled | Filled container background | | Outlined | Outlined border, transparent background | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Unavailable | ### Design Guidelines - Use cards to contain related elements - Contents can include images, headlines, supporting text, buttons, and lists - Can also contain other components - Flexible layouts based on contents ### Key Updates (M3) - Lower elevation, no shadow by default - New color mappings with dynamic color support --- ## Dialogs **Description:** Dialogs provide important prompts in a user flow. **Source:** https://m3.material.io/components/dialogs/overview ### Variants | Variant | Description | |---------|-------------| | Basic | Standard dialog | | Full-screen | Full-screen dialog | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Available | ### Design Guidelines - Use dialogs to make sure users act on information - Should be dedicated to completing a single task - Can display information relevant to the task - Commonly used to confirm high-risk actions (e.g., deleting progress) ### Key Updates (M3) - Greater padding for increased corner-radius and title size - Option for custom basic dialog positioning - Increased corner-radius - Larger and darker headline - New color mappings with dynamic color support --- ## Snackbars **Description:** Snackbars show short updates about app processes at the bottom of the screen. **Source:** https://m3.material.io/components/snackbar/overview ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Unavailable | ### Design Guidelines - Should not interrupt user's experience - Usually appear at the bottom of the UI - Can disappear on their own (dismissive) or remain until user takes action (non-dismissive) ### Key Updates (M3) - Clarified behavior: snackbars can be dismissive or non-dismissive - New color mappings with dynamic color support --- ## Bottom Sheets **Description:** Bottom sheets show secondary content anchored to the bottom of the screen. **Source:** https://m3.material.io/components/bottom-sheets/overview ### Variants | Variant | Description | |---------|-------------| | Standard | Standard bottom sheet | | Modal | Modal bottom sheet | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Unavailable | ### Design Guidelines - Use in compact and medium window sizes - Content should be additional or secondary (not main content) - Can be dismissed to interact with main content ### Key Updates (M3) - 28dp top corner radius - New max-width of 640dp - Optional drag handle with 48dp hit target - New color mappings with dynamic color support --- ## Lists **Description:** Lists help people find a specific item and act on it. **Source:** https://m3.material.io/components/lists/overview ### List Item Elements (Customizable) - Label text - Supporting text - Leading image - Trailing icon ### Visual Styles | Style | Description | |-------|-------------| | Standard | Standard list appearance | | Segmented | New segmented visual style | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | Jetpack Compose: Expressive | Available | | Android | MDC-Android | Available | | Android | MDC-Android: Expressive | Available | | Web | Web | Available | ### Design Guidelines - Order list items in logical ways (alphabetical, numerical, etc.) - Keep items short and easy to scan - Show icons, text, and actions in a consistent format ### Key Updates (M3 Expressive) - New segmented visual style - Improved selection treatment - Flexible slots support - Expressive list is recommended for new designs - Baseline list still available FILE:references/foundations.md --- name: material-design-foundations description: Google Material Design 3 设计原则与自适应布局完整参考。 source: https://m3.material.io/foundations --- # Material Design 3 Foundations Material Design 3 (M3) 是一个适应性设计系统，包含指南、组件和工具，支持界面设计的最佳实践。 ## M3 Design Principles ### Expressive M3 通过颜色、排版、形状和动态效果实现品牌表达。 - **颜色系统**: 支持动态颜色和个性化配色方案，26+ 颜色角色映射到组件 - **排版**: 15 个基础类型样式 + 15 个强调类型样式，支持可变字体 - **形状系统**: 35 种预设形状，支持形状渐变（morphing） - **动态效果**: 基于内容和用户偏好的自适应视觉体验 ### Responsive 响应式设计使产品可在不同设备和使用场景下使用。 - 窗格（Pane）作为布局构建块 - 窗口尺寸类别（Window Size Classes）自适应布局 - 支持折叠屏、多屏幕、多窗口等复杂场景 ### Accessible 无障碍设计让具有不同能力的用户都能导航、理解和使用界面。 - 内置可访问的颜色对比关系 - 支持三种对比度级别 - 动态颜色自动保持可访问的对比度 --- ## Adaptive Design ### What Does Adaptive Mean? 自适应设计是一系列技术，允许界面响应以下上下文： | Context Type | Examples | |--------------|----------| | **User** | 用户偏好和设置 | | **Device** | 手表、手机、折叠屏、平板、桌面、XR 设备 | | **Usage** | 窗口调整、方向改变、设备切换 | ### Conditions 条件是决定应用何时以及如何适配的信号。Material 自适应系统支持三类条件： #### Device Conditions - 全屏环境 - 窗口化环境 - 空间化环境 - 设备姿态（如折叠状态） #### Window Size Conditions - **窗口尺寸类别**（Window Size Classes） - 屏幕方向（横屏/竖屏） #### Input Modality Conditions - 触摸 - 手写笔 - 外设 - 眼动追踪 - 手部追踪 ### Window Size Classes | Size Class | Breakpoint | Typical Devices | |------------|------------|-----------------| | **Compact** | < 600dp | 手机、折叠屏内屏 | | **Medium** | 600dp - 840dp | 折叠屏外屏、小平板 | | **Expanded** | > 840dp | 大平板、桌面显示器 | ### Layout Patterns #### Pane-Based Layout 窗格是布局的构建块，每个窗格是产品中的单一目的地。 **示例 - 消息应用：** - 窗格 1: 消息列表 - 窗格 2: 特定对话线程 #### Layout Behavior by Window Size **Compact (< 600dp)** ``` ┌─────────────────┐ │ │ │ Single │ │ Pane │ │ │ └─────────────────┘ ``` **Medium (600dp - 840dp)** ``` ┌─────────┬───────┐ │ │ │ │ List │ Detail│ │ Pane │ Pane │ │ │ │ └─────────┴───────┘ ``` **Expanded (> 840dp)** ``` ┌─────┬─────────┬───────┐ │ Nav │ List │ Detail│ │ │ Pane │ Pane │ │ │ │ │ └─────┴─────────┴───────┘ ``` --- ## Grid System & Layout Principles ### Layout Foundation 布局是元素在屏幕上的视觉排列。M3 布局系统基于以下原则： 1. **可见性**: 内容根据窗口尺寸和条件显示或隐藏 2. **空间**: 元素间距和对齐遵循 4dp/8dp 网格系统 3. **层次**: 通过海拔（Elevation）和色调区分内容层次 ### Responsive Grid | Window Size | Column Count | Gutter | Margin | |-------------|--------------|--------|--------| | Compact | 4 | 16dp | 16dp | | Medium | 8 | 24dp | 24dp | | Expanded | 12 | 24dp | 24dp | --- ## Accessibility Guidelines ### Core Principles - **可感知**: 信息和UI组件必须以用户可感知的方式呈现 - **可操作**: UI组件和导航必须可操作 - **可理解**: 信息和UI操作必须可理解 - **健壮**: 内容必须能被各种用户代理（包括辅助技术）解释 ### Color Accessibility - 所有颜色组合需满足 WCAG 2.1 对比度要求 - M3 提供三种对比度级别供用户选择 - 动态颜色自动保持可访问对比度 ### Typography Accessibility - 支持系统字体缩放 - 强调样式用于突出重要内容而非唯一信息载体 - 文本可调整大小（最大 200%） ### Interaction States 交互元素需明确传达状态： - **Default**: 正常状态 - **Hover**: 悬停状态 - **Pressed**: 按下状态 - **Focused**: 焦点状态 - **Disabled**: 禁用状态 - **Drag**: 拖拽状态 --- ## Platform-Specific Considerations ### Mobile (Phone) - 触控优先交互 - 紧凑布局（单窗格） - 底部导航或导航栏 - 手势导航支持 ### Tablet - 可使用触控或键盘交互 - 中等布局（双窗格列表/详情） - 导航导轨（Navigation Rail） - 支持分屏多任务 ### Desktop - 精确指针交互 - 展开布局（三窗格） - 顶部应用栏或导航抽屉 - 窗口调整支持 ### Large Screen / Foldable - 最大化显示空间利用 - 动态布局调整 - 多任务分屏支持 - 铰链区域考虑 ### Wear / XR - 特定设备姿态支持 - 空间化环境适配 - 眼动/手部追踪输入 - 3D 深度和海拔表现 --- ## Design Tokens Tokens 存储样式值（颜色、字体等），确保相同值可用于跨设计、代码、工具和平台。 ### Token Categories | Category | Examples | |----------|----------| | **Color** | Primary, Secondary, Surface, Error | | **Typography** | Font family, Size, Weight, Line height | | **Shape** | Corner radius, Family | | **Elevation** | Level 0-24, Tint/opacity values | | **Spacing** | 4dp, 8dp, 16dp increments | --- ## Design System Overview ### Building for Everyone Material Design 为具有不同能力的用户设计，包含内置无障碍功能。 ### Customizing Material M3 使品牌表达比以往更简单、更美观： - 动态颜色生成 - 可配置的组件变体 - 主题化 API ### Material A-Z 关键术语和概念索引，帮助理解 Material Design 完整体系。 --- *Source: [Material Design 3 Foundations](https://m3.material.io/foundations)* FILE:references/input-components.md --- name: Input Components description: Material Design 3 input components including Buttons, Text Fields, Chips, Segmented Buttons, Switches, Checkboxes, and Radio Buttons source: https://m3.material.io/components/buttons/overview --- # Input Components ## Buttons **Description:** Buttons prompt most actions in a UI. **Source:** https://m3.material.io/components/buttons/overview ### Variants | Variant | Description | |---------|-------------| | Default | Standard button actions | | Toggle | Selection functionality | ### Color Styles | Style | Use Case | |-------|----------| | Elevated | Secondary emphasis | | Filled | Primary emphasis | | Tonal | Moderate emphasis | | Outlined | Tertiary emphasis | | Text | Minimal emphasis | ### Sizes | Size | Description | |------|-------------| | Extra Small | Compact spaces | | Small (Default) | Standard compact | | Medium | Standard | | Large | Prominent | | Extra Large | Maximum emphasis | ### Shapes - Round - Square (shape morphs when pressed/selected) ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | Jetpack Compose: Expressive | Available | | Android | MDC-Android | Available | | Android | MDC-Android: Expressive | Available | | Web | Web | Available | ### Key Updates (M3 Expressive) - Wider variety of shapes and sizes - Toggle functionality added - Shape morphs when selected - New small button padding: 16dp (recommended) --- ## Text Fields **Description:** Text fields let users enter text into a UI. **Source:** https://m3.material.io/components/text-fields/overview ### Variants | Variant | Description | |---------|-------------| | Filled | Filled background style | | Outlined | Outlined border style | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Available | ### Design Guidelines - Make text fields look interactive - State (blank, with input, error, etc.) should be visible at a glance - Keep labels and error messages brief and easy to act on - Commonly appear in forms and dialogs --- ## Chips **Description:** Chips help people enter information, make selections, filter content, or trigger actions. **Source:** https://m3.material.io/components/chips/overview ### Variants | Variant | Description | |---------|-------------| | Assist | Trigger actions | | Filter | Filter content | | Input | Enter information | | Suggestion | Provide suggestions | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Available | ### Design Guidelines - Use chips to show options for a specific context - Chip elevation defaults to 0 but can be elevated if more visual separation is needed ### Key Updates (Aug 2024) - Stroke color changed from outline to outline variant for improved visual hierarchy --- ## Segmented Buttons **Description:** Segmented buttons help people select options, switch views, or sort elements. **Source:** https://m3.material.io/components/segmented-buttons/overview ### Variants | Variant | Description | |---------|-------------| | Single-select | Select one option | | Multi-select | Select multiple options | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Unavailable | ### Key Updates (M3 Expressive) - **Deprecated:** Segmented buttons are no longer recommended - **Replacement:** Use connected button group instead (same functionality, updated visual design) ### Design Guidelines - Can contain icons, label text, or both - Use for simple choices between 2-5 items - For more items or complex choices, use chips instead --- ## Switches **Description:** Switches toggle the selection of an item on or off. **Source:** https://m3.material.io/components/switch/overview ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Available | ### Design Guidelines - Use switches (not radio buttons) if items in a list can be independently controlled - Best way to let people adjust settings - Selection state (on/off) should be visible at a glance ### Key Differences from M2 - Taller and wider track - Optional icon within switch handle - New color mappings with dynamic color support - Improved accessibility --- ## Checkboxes **Description:** Checkboxes let users select one or more items from a list, or turn an item on or off. **Source:** https://m3.material.io/components/checkbox/overview ### States | State | Description | |-------|-------------| | Unselected | Default unchecked | | Selected | Checked | | Indeterminate | Partial selection | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Available | ### Design Guidelines - Use checkboxes when multiple options can be selected from a list - Label should be scannable - Selected items more prominent than unselected ### Key Updates (M3) - New indeterminate states - Error states for unselected, selected, and indeterminate - New color mappings with dynamic color support --- ## Radio Buttons **Description:** Radio buttons let people select one option from a set of options. **Source:** https://m3.material.io/components/radio-button/overview ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Available | ### Design Guidelines - Use radio buttons (not switches) when only one item can be selected from a list - Label should be scannable - Selected items more prominent than unselected ### Key Updates (M3) - New color mappings with dynamic color support FILE:references/layout-constraints.md # Flutter 布局约束权威指南 Flutter 布局核心规则：**上层 widget 向下传递约束 → 下层 widget 向上传递大小 → 父级决定子级位置**。理解这条规则，才能理解为什么 `width: 100` 不一定是 100 像素宽。 ## 约束模型约束（Constraints）是 4 个浮点数的集合：最小/最大宽度、最小/最大高度。布局流程： ``` Parent → 向下传递约束 (minWidth~maxWidth, minHeight~maxHeight) ↓ Widget 遍历 children，向每个 child 传递各自的约束 ↓ Child 决定自己想要的尺寸（向上回报） ↓ Widget 确定自身大小（受原始约束限制） ↓ Widget 告诉 Parent 自己的大小 ↓ Parent 决定每个 child 的位置（x/y 坐标） ``` **约束下行，尺寸上行，位置由父级决定。** ## 核心原则 ### 1. Widget 无法自定大小，只能在父级约束内决定 ```dart // 这样写：widget 不知道自己会被约束成什么尺寸 Container(width: 100) // 在无限宽的 parent 里，这可能无效 // Flutter 布局不是"我要多大"，而是"我在给我的约束里能多大" ``` ### 2. 位置由父级决定，Widget 自身无法知晓 Widget 的 `x/y` 坐标由其 parent 决定，不是自身决定的。 ### 3. 整棵树决定单个 Widget 的最终尺寸 Widget 的 size 取决于它的 parent，而 parent 的 size 又取决于 grandparent。脱离整棵树无法精确定义任何 Widget 的最终尺寸。 ### 4. 对齐要明确如果 child 想要的尺寸和 parent 能给的不一致，且 parent 没有足够信息对齐，则 child's size 可能被忽略。**定义对齐时要明确指定。** ## 常见困境 ### `width: 100` 不生效 ```dart // 错误：width: 100 在这个 context 可能无效 Container(width: 100, child: Text('hello')) // 如果 parent 约束是 50~∞，这个 Container 就会被拉伸或收缩 // 正确理解：在 Center 之外，Container 会尝试用 100，但受 parent 约束限制 ``` ### `FittedBox` 不起作用 `FittedBox` 只在 parent 给了固定约束时才能正确 fit。如果 parent 本身是 unconstrained，`FittedBox` 的 fit 就无从谈起。 ### `Column` 溢出 `Column` 的 children 如果在垂直方向上超出了 `Column` 自身的约束，就会溢出。解决方案通常是包裹在 `Expanded` 或 `Flexible` 中，或调整 parent 的约束。 ### `IntrinsicWidth` / `IntrinsicHeight` 当需要一个 widget "按内容自适应"但 parent 给了硬约束时，`IntrinsicWidth` 可以让 child 先按自己内容决定理想宽度，再把约束传递给 child。但性能开销大，应避免在频繁重建的列表中使用。 ## LayoutBuilder 与 Constraints ```dart LayoutBuilder( builder: (context, constraints) { if (constraints.maxWidth > 600) { return Row(children: [...]); } else { return Column(children: [...]); } }, ) ``` `LayoutBuilder` 让你在 build 时实时获取 parent 传下来的约束，是响应式布局的关键工具。 ## 调试技巧 ```dart // 1. 用 Widget Inspector 可视化约束传递 // 2. 加一个 ColoredBox 看实际占位 Container(color: Colors.red) // 看实际渲染大小 // 3. 常见溢出：太长的 Text 在有限宽度的 Column cell 里 // 解决：Expanded / Flexible 包裹，或 maxLines 限制 ``` ## 来源 [Understanding constraints - Flutter](https://flutter.cn/ui/layout/constraints) (CC BY 4.0) FILE:references/m3-migration-guide.md # Material 3 迁移完全指南 > 来源：Flutter 中文网 / GitHub cfug/flutter.cn > URL: https://github.com/cfug/flutter.cn/blob/main/src/content/release/breaking-changes/material-3-migration.md > 版本：Flutter 3.16+ (2023年11月) > 抓取时间：2026-04-24 --- ## 概述 Flutter 3.16 版本将 Material 3 设为默认主题。Material Design 3 (MD3) 相比 Material 2 做了大量更新，包括新的组件、颜色系统、字体系统、层级系统等。大部分更新是自动无缝完成的，但部分组件需要手动迁移。 **时间线：** Flutter 3.16 稳定版（2023年11月）起，`useMaterial3: true` 成为默认值。 --- ## useMaterial3 标志 ### 启用/禁用 MD3 ```dart // Flutter 3.16+ 默认 useMaterial3: true MaterialApp( theme: ThemeData( useMaterial3: true, // 显式启用 MD3 ), ) // 临时回退到 M2（不推荐，仅用于过渡） MaterialApp( theme: ThemeData( useMaterial3: false, // 临时回退，过渡期使用 ), ) ``` **注意：** `useMaterial3` 属性和 Material 2 实现将在未来版本中被移除，详见 [Flutter 弃用政策](https://flutter.cn/release/compatibility-policy#deprecation-policy)。 --- ## 颜色迁移 ### ColorScheme.fromSeed（推荐方式） MD3 的核心变化之一：`ColorScheme.fromSeed` 现在是推荐的颜色生成方式。 ```dart // ❌ 旧方式（M2） theme: ThemeData( colorScheme: ColorScheme.light(primary: Colors.blue), ) // ✅ 新方式（M3）—— 从种子色生成完整配色 theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ) ``` ### 动态配色（Dynamic Color） ```dart // 从网络图片动态生成配色 ColorScheme.fromImageProvider( provider: NetworkImage('https://example.com/image.jpg'), brightness: Brightness.light, ) // 从种子色 + brightness 手动指定 ColorScheme.fromSeed( seedColor: Colors.deepPurple, brightness: Brightness.dark, ) ``` ### 颜色角色变更（3.22+ 版本） MD3 新增了基于色调的 surface 颜色角色，替代旧的 opacity 模型： | 旧名称（M2） | 新名称（MD3） | 说明 | |------------|-------------|------| | `ColorScheme.background` | `ColorScheme.surface` | 主背景色 | | `ColorScheme.onBackground` | `ColorScheme.onSurface` | 背景上的文字色 | | `ColorScheme.surfaceVariant` | `ColorScheme.surfaceContainerHighest` | 表面变体 | ```dart // ❌ 旧颜色查找（M2） final bg = Theme.of(context).colorScheme.background; final onBg = Theme.of(context).colorScheme.onBackground; final surfaceVar = Theme.of(context).colorScheme.surfaceVariant; // ✅ 新颜色查找（MD3） final surface = Theme.of(context).colorScheme.surface; final onSurface = Theme.of(context).colorScheme.onSurface; final surfaceHigh = Theme.of(context).colorScheme.surfaceContainerHighest; ``` ### 新的 Surface 颜色角色（3.22+） MD3 新增 7 个基于色调的 surface 颜色，替代旧的 surfaceTint 叠加模型： | 角色 | 说明 | |------|------| | `surfaceBright` | 最亮的 surface | | `surfaceDim` | 最暗的 surface | | `surfaceContainer` | 标准容器色 | | `surfaceContainerLow` | 低 elevation 容器 | | `surfaceContainerLowest` | 最低容器色 | | `surfaceContainerHigh` | 高 elevation 容器 | | `surfaceContainerHighest` | 最高 elevation 容器 | ### surfaceTint 变更 `surfaceTint` 现在用于表示组件的 elevation。所有组件默认 `surfaceTint: null`。 ```dart // 恢复 M2 行为（不推荐） theme: ThemeData( colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple).copyWith( surfaceTint: Colors.transparent, ), appBarTheme: AppBarTheme( elevation: 4.0, shadowColor: Theme.of(context).colorScheme.shadow, ), ) ``` --- ## 字体迁移 ### Typography 变化 MD3 更新了 `TextTheme` 的默认值（字号、字重、字间距、行高）。 ```dart // ❌ M2 bodyLarge 在 200pt 约束下显示 2 行 ConstrainedBox( constraints: const BoxConstraints(maxWidth: 200), child: Text( 'This is a very long text that should wrap to multiple lines.', style: Theme.of(context).textTheme.bodyLarge, ), ) // ✅ M3 bodyLarge 默认行高更小，同等约束显示 3 行 // 如需恢复旧行为，调整 letterSpacing ConstrainedBox( constraints: const BoxConstraints(maxWidth: 200), child: Text( 'This is a very long text that should wrap to multiple lines.', style: Theme.of(context).textTheme.bodyMedium!.copyWith( letterSpacing: 0.0, ), ), ) ``` --- ## 组件迁移 ### BottomNavigationBar → NavigationBar MD3 的 NavigationBar 比 M2 的 BottomNavigationBar 更高，使用胶囊形指示器。 ```dart // ❌ M2 BottomNavigationBar BottomNavigationBar( items: const [ BottomNavigationBarItem( icon: Icon(Icons.home), label: 'Home', ), BottomNavigationBarItem( icon: Icon(Icons.business), label: 'Business', ), BottomNavigationBarItem( icon: Icon(Icons.school), label: 'School', ), ], ) // ✅ M3 NavigationBar NavigationBar( destinations: const [ NavigationDestination( icon: Icon(Icons.home), label: 'Home', ), NavigationDestination( icon: Icon(Icons.business), label: 'Business', ), NavigationDestination( icon: Icon(Icons.school), label: 'School', ), ], ) ``` ### Drawer → NavigationDrawer ```dart // ❌ M2 Drawer Drawer( child: ListView( children: [ DrawerHeader( child: Text('Drawer Header'), ), ListTile( leading: Icon(Icons.message), title: Text('Messages'), onTap: () { }, ), ], ), ) // ✅ M3 NavigationDrawer NavigationDrawer( children: [ DrawerHeader( child: Text('Drawer Header'), ), const NavigationDrawerDestination( icon: Icon(Icons.message), label: Text('Messages'), ), ], ) ``` ### ToggleButtons → SegmentedButton ```dart // ❌ M2 ToggleButtons enum Weather { cloudy, rainy, sunny } ToggleButtons( isSelected: const [false, true, false], onPressed: (int newSelection) { }, children: const [ Icon(Icons.cloud_outlined), Icon(Icons.beach_access_sharp), Icon(Icons.brightness_5_sharp), ], ) // ✅ M3 SegmentedButton enum Weather { cloudy, rainy, sunny } SegmentedButton( selected: const {Weather.rainy}, onSelectionChanged: (Set newSelection) { }, segments: const >[ ButtonSegment( icon: Icon(Icons.cloud_outlined), value: Weather.cloudy, ), ButtonSegment( icon: Icon(Icons.beach_access_sharp), value: Weather.rainy, ), ButtonSegment( icon: Icon(Icons.brightness_5_sharp), value: Weather.sunny, ), ], ) ``` ### AppBar → Medium/Large AppBar MD3 引入了 Medium 和 Large AppBar，滚动时使用 `surfaceTint` 代替阴影分隔内容。 ```dart CustomScrollView( slivers: [ const SliverAppBar.medium( title: Text('Title'), ), SliverToBoxAdapter( child: Card( child: SizedBox( height: 1200, child: Padding( padding: const EdgeInsets.fromLTRB(8, 100, 8, 100), child: Text( 'Here be scrolling content...', ), ), ), ), ), ], ) ``` ### TabBar 新增 secondary 类型 ```dart AppBar( title: const Text('Title'), bottom: const TabBar( tabAlignment: TabAlignment.start, isScrollable: true, tabs: [ Tab(icon: Icon(Icons.cloud_outlined)), Tab(icon: Icon(Icons.beach_access_sharp)), Tab(icon: Icon(Icons.brightness_5_sharp)), ], ), ) ``` ### ElevatedButton → FilledButton ```dart // ❌ M2 ElevatedButton 样式 ElevatedButton( onPressed: () {}, child: const Text('Button'), ) // ✅ M3 FilledButton（无 elevation 变化和阴影） FilledButton( onPressed: () {}, child: const Text('Button'), ) // 或使用 M2 风格手动设置 ElevatedButton( style: ElevatedButton.styleFrom( backgroundColor: Theme.of(context).colorScheme.primary, foregroundColor: Theme.of(context).colorScheme.onPrimary, ), onPressed: () {}, child: const Text('Button'), ) ``` --- ## 新增组件（MD3 全新华实现）以下组件在 M2 中不存在，必须使用 MD3 方式： ### MenuBar / MenuAnchor（桌面/Web 菜单） ```dart // 桌面风格菜单系统 MenuBar( children: [ SubmenuButton( menuChildren: [ MenuItemButton( onPressed: () {}, child: const Text('New File'), ), ], child: const Text('File'), ), ], ) ``` ### DropdownMenu（组合框） ```dart DropdownMenu( initialSelection: Entry.entry1, dropdownMenuEntries: listEntries, onSelected: (Entry entry) {}, ) ``` ### SearchBar / SearchAnchor（搜索组件） ```dart SearchAnchor( builder: (context, controller, child) { return SearchBar( controller: controller, hintText: 'Search', leading: const Icon(Icons.search), onTap: () {}, ); }, suggestionsBuilder: (context, controller) { return List.generate(5, (index) { return ListTile( title: Text('Suggestion $index'), onTap: () {}, ); }); }, ) ``` ### Badge（徽章） ```dart Badge( label: Text('+1'), child: Icon(Icons.notifications), ) ``` ### FilterChip.elevated / ChoiceChip.elevated / ActionChip.elevated ```dart // 凸起变体 Chip FilterChip.elevated( selected: isSelected, onSelected: (bool selected) {}, label: Text('Filter'), ) ChoiceChip.elevated( selected: isSelected, onSelected: (bool selected) {}, label: Text('Choice'), ) ActionChip.elevated( onPressed: () {}, label: Text('Action'), ) ``` ### Dialog.fullscreen（全屏对话框） ```dart Dialog.fullscreen( onDismiss: () {}, child: Scaffold( appBar: AppBar( title: Text('Title'), actions: [ IconButton( icon: const Icon(Icons.close), onPressed: () {}, ), ], ), body: Center( child: Text('Full screen dialog'), ), ), ) ``` --- ## 按钮 styleFrom 迁移 ### TextButton.styleFrom ```dart // ❌ 旧属性（v3.1 起弃用） TextButton.styleFrom( primary: Colors.red, onSurface: Colors.black, ) // ✅ 新属性（MD3） TextButton.styleFrom( foregroundColor: Colors.red, disabledForegroundColor: Colors.black, ) ``` ### ElevatedButton.styleFrom ```dart // ❌ 旧属性 ElevatedButton.styleFrom( primary: Colors.red, onPrimary: Colors.blue, onSurface: Colors.black, ) // ✅ 新属性 ElevatedButton.styleFrom( backgroundColor: Colors.red, foregroundColor: Colors.blue, disabledForegroundColor: Colors.black, ) ``` ### OutlinedButton.styleFrom ```dart // ❌ 旧属性 OutlinedButton.styleFrom( primary: Colors.red, onSurface: Colors.black, ) // ✅ 新属性 OutlinedButton.styleFrom( foregroundColor: Colors.red, disabledForegroundColor: Colors.black, ) ``` --- ## 相关链接 - [Material Design for Flutter](https://flutter.cn/ui/design/material) - [ThemeData.useMaterial3 API](https://api.flutter.cn/flutter/material/ThemeData/useMaterial3.html) - [Flutter Material 3 示例](https://github.com/flutter/samples/tree/main/material_3_demo) - [MD3 umbrella issue](https://github.com/flutter/flutter/issues/91605) FILE:references/md3-api-changes.md # MD3 Flutter API 变更速查 > 来源: Flutter Breaking Changes (cfug/flutter.cn) > URL: https://github.com/cfug/flutter.cn/tree/main/src/content/release/breaking-changes > 更新: 2026-04 本文档汇总 Flutter Material 3 相关的核心 API 变更，按影响范围分组。 --- ## 1. Button 体系 (v2.0.0) ### Widget 替换对照 | M2 (已废弃) | MD3 | Theme | |------------|------|-------| | `FlatButton` | `TextButton` | `TextButtonTheme` / `TextButtonThemeData` | | `RaisedButton` | `ElevatedButton` | `ElevatedButtonTheme` / `ElevatedButtonThemeData` | | `OutlineButton` | `OutlinedButton` | `OutlinedButtonTheme` / `OutlinedButtonThemeData` | | `ButtonTheme` | — | `ButtonBar` → 各组件独立 theme | ### ButtonStyle API 新按钮使用统一的 `ButtonStyle` 而非分散的参数（`textColor`, `disabledTextColor`, `elevation` 等）： ```dart // ✅ MD3 方式 TextButton( style: TextButton.styleFrom( foregroundColor: Colors.blue, disabledForegroundColor: Colors.grey, ), onPressed: () {}, child: Text('Text'), ) // ❌ M2 旧方式 (已废弃) FlatButton( textColor: Colors.blue, disabledTextColor: Colors.grey, onPressed: () {}, child: Text('Text'), ) ``` ### MaterialStateProperty 状态颜色 ```dart ButtonStyle( overlayColor: MaterialStateProperty.resolveWith((states) { if (states.contains(MaterialState.hovered)) return Colors.blue.withOpacity(0.04); if (states.contains(MaterialState.focused)) return Colors.blue.withOpacity(0.12); if (states.contains(MaterialState.pressed)) return Colors.blue.withOpacity(0.12); return null; }), ) ``` ### 恢复 M2 外观 ```dart final flatStyle = TextButton.styleFrom( foregroundColor: Colors.black87, minimumSize: Size(88, 36), padding: EdgeInsets.symmetric(horizontal: 16), shape: BorderRadius.all(Radius.circular(2)), ); // 适用于 TextButton → FlatButton final raisedStyle = ElevatedButton.styleFrom( foregroundColor: Colors.black87, backgroundColor: Colors.grey[300], minimumSize: Size(88, 36), padding: EdgeInsets.symmetric(horizontal: 16), shape: BorderRadius.all(Radius.circular(2)), ); // 适用于 ElevatedButton → RaisedButton ``` --- ## 2. ColorScheme 角色扩展 (v3.22+) ### M2 → MD3 角色对照 | M2 `ColorScheme` | MD3 `ColorScheme` | 说明 | |-----------------|-------------------|------| | `primary` | `primary` | 主色（不变） | | `primaryVariant` | `primaryContainer` / `onPrimaryContainer` | 新增容器色 | | `secondary` | `secondary` | 不变 | | — | `secondaryContainer` / `onSecondaryContainer` | 新增 | | — | `tertiary` / `tertiaryContainer` | 新增 accent 色 | | `surface` | `surface` | 不变 | | — | `surfaceContainerHighest` 等层级 | 新的表面层级 | | `error` | `error` | 不变 | | — | `errorContainer` / `onErrorContainer` | 新增 | ### ColorScheme.fromSeed 工厂构造 ```dart // ✅ MD3 推荐方式：自动生成 harmonious 配色 ColorScheme.fromSeed( seedColor: Color(0xFF6750A4), // Material Purple brightness: Brightness.light, // 或 .dark ) // 生成完整的 primaryContainer / secondary / tertiary 等角色 ``` ### DynamicSchemeVariant 动态配色 ```dart // 纯色主题 ColorScheme.fromSeed(seedColor: color, dynamicSchemeVariant: DynamicSchemeVariant.vibrant) // 柔和主题 (M3 默认) ColorScheme.fromSeed(seedColor: color, dynamicSchemeVariant: DynamicSchemeVariant.tonal) // 鲜艳主题 ColorScheme.fromSeed(seedColor: color, dynamicSchemeVariant: DynamicSchemeVariant.fruitSalad) ``` --- ## 3. ThemeData 组件主题标准化 (v3.27+) ### `*Theme` → `*ThemeData` 类型变更 ```dart // ❌ 旧类型 (Flutter 3.27 之前) final CardTheme cardTheme = Theme.of(context).cardTheme; final DialogTheme dialogTheme = Theme.of(context).dialogTheme; final TabBarTheme tabBarTheme = Theme.of(context).tabBarTheme; // ✅ 新类型 final CardThemeData cardTheme = Theme.of(context).cardTheme; final DialogThemeData dialogTheme = Theme.of(context).dialogTheme; final TabBarThemeData tabBarTheme = Theme.of(context).tabBarTheme; ``` --- ## 4. 导航组件 ### BottomNavigationBar → NavigationBar (MD3) | M2 `BottomNavigationBar` | MD3 `NavigationBar` | |------------------------|---------------------| | `type: BottomNavigationBarType.fixed` | 默认 MD3 风格 | | `type: BottomNavigationBarType.shifting` | 使用 `NavigationDestinationLabelBehavior.alwaysHide` | | 单一背景色 | 表面容器 + elevation 0 | ```dart // ✅ MD3 NavigationBar NavigationBar( destinations: const [ NavigationDestination( icon: Icon(Icons.home_outlined), selectedIcon: Icon(Icons.home), label: '首页', ), NavigationDestination( icon: Icon(Icons.search_outlined), selectedIcon: Icon(Icons.search), label: '搜索', ), ], onDestinationSelected: (index) { }, ) // ❌ M2 BottomNavigationBar (已废弃但仍可用) BottomNavigationBar( items: const [ BottomNavigationBarItem(icon: Icon(Icons.home), label: '首页'), BottomNavigationBarItem(icon: Icon(Icons.search), label: '搜索'), ], onTap: (index) { }, ) ``` ### TabBar → MD3 Tabs ```dart // ✅ MD3 TabBar (配合 TabBarTheme) TabBar( tabs: const [Tab(text: 'Tab1'), Tab(text: 'Tab2')], labelColor: Theme.of(context).colorScheme.primary, unselectedLabelColor: Theme.of(context).colorScheme.onSurfaceVariant, ) // ✅ ThemeData.indicatorColor → TabBarThemeData.indicatorColor MaterialApp( theme: ThemeData( tabBarTheme: TabBarThemeData( indicatorColor: Colors.red, // 不再使用 ThemeData.indicatorColor ), ), ) ``` --- ## 5. 废弃 API 一览 | 废弃 API | 替代方案 | 版本 | |---------|---------|------| | `ThemeData.indicatorColor` | `TabBarThemeData.indicatorColor` | 3.32 | | `ThemeData.useMaterial3` | 保持使用，MD3 默认开启 | — | | `ButtonTheme` | `TextButtonTheme` / `ElevatedButtonTheme` 等 | 2.0 | | `FlatButton` / `RaisedButton` / `OutlineButton` | `TextButton` / `ElevatedButton` / `OutlinedButton` | 2.0 | | `CardTheme` | `CardThemeData` | 3.27 | | `DialogTheme` | `DialogThemeData` | 3.27 | | `TabBarTheme` | `TabBarThemeData` | 3.27 | | `Chip` 的 `deleteButtonTooltipMessage` | `Chip.deleteButtonTooltipMessage` 已更名 | — | | `ListTile` 的 `color` / `selectedColor` | `ListTileThemeData` 或直接设置 | — | | `containerColor` 参数 | 各组件自有的 surface/tint 参数 | — | --- ## 6. Elevation 和表面层级 (v3.22+) ### 新的表面层级 API ```dart // M2: elevation 数字 Container(color: Colors.white, elevation: 2) // MD3: 表面层级系统 (无 elevation，只有 tonal 变化) Container( color: Theme.of(context).colorScheme.surfaceContainerHighest, // elevation 由系统通过颜色差异隐式表达 ) ``` ### ElevationToken 更新 ```dart // MD3 elevation token 映射 elevation.level0 → 无阴影，表面颜色 elevation.level1 → 卡片、底部导航 elevation.level2 → 导航抽屉、AppBar (scrolled) elevation.level3 → 浮动按钮、搜索栏 elevation.level4 → 菜单、FAB (按下) elevation.level5 → 对话框、模态底部导航 ``` --- ## 7. Chip 组件变更 (v3.22+) ### Chip deleteButtonTooltip 更名 ```dart // ❌ 旧 Chip( deleteButtonTooltipMessage: '删除', onDeleted: () {}, ) // ✅ 新 Chip( deleteTooltip: '删除', // 改名 onDeleted: () {}, ) ``` ### Chip 语义变更 ```dart // Chip 的 semanticsLabel 行为变更 // MD3 下 Chip 会自动合成可访问性信息 // 显式设置 label 而非仅依赖 child 文本 Chip( label: Text('芯片'), avatar: CircleAvatar(child: Text('A')), labelBehavior: NavigationIndicatorLabelBehavior.onlyShowSelected, ) ``` --- ## 8. Material State 系统 ### MaterialStateProperty 核心用法 ```dart // 单一状态值 MaterialStateProperty.all(Colors.blue) // 动态解析状态 MaterialStateProperty.resolveWith((states) { if (states.contains(MaterialState.disabled)) return Colors.grey; if (states.contains(MaterialState.hovered)) return Colors.blue.shade100; if (states.contains(MaterialState.pressed)) return Colors.blue.shade200; if (states.contains(MaterialState.focused)) return Colors.blue.shade50; return null; }) // 常用状态标志 MaterialState.disabled MaterialState.hovered MaterialState.pressed MaterialState.focused MaterialState.selected MaterialState.dragged MaterialState.scrolledUnder ``` --- ## 9. Dialog / BottomSheet 变更 ### Dialog Border Radius (v3.16+) ```dart // M2: Dialog 默认圆角 4px // MD3: Dialog 默认圆角 28px (large)) showDialog( builder: (context) => Dialog( child: Padding( padding: EdgeInsets.all(24), child: Text('MD3 Dialog'), ), ), ) // 自定义圆角 Dialog( shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(28)), ) ``` ### ScrollableAlertDialog (v3.16+) ```dart // MD3 AlertDialog 内容超长时可滚动 AlertDialog( title: Text('标题'), content: SingleChildScrollView( // 可选，显式滚动 child: Text('很长的内容...'), ), actions: [...], ) ``` --- ## 10. Snackbar 变更 (v3.19+) ```dart // snackBarBehavior 默认值变更 // M2: SnackBarBehavior.floating // MD3: SnackBarBehavior.endFloating (底部留出 FAB 空间) // action 颜色 Snackbar( action: SnackBarAction( label: '撤销', textColor: Theme.of(context).colorScheme.inversePrimary, // M2: SnackBarAction.textColor ), ) ``` --- ## 版本时间线 | Flutter 版本 | 主要 MD3 变更 | |------------|-------------| | 1.20–1.22 | Button 新 API 引入 | | 2.0 | FlatButton/RaisedButton/OutlineButton 废弃 | | 3.0 | Material 3 默认关闭 (`useMaterial3: false`) | | 3.16 | Dialog 圆角 4→28px, ScrollableAlertDialog | | 3.19 | SnackbarBehavior 变更 | | 3.22 | ColorScheme 大扩展, DynamicScheme, 新 surface 层级 | | 3.27 | ComponentTheme 标准化 (*Theme → *ThemeData) | | 3.30 | `ThemeData.indicatorColor` 废弃 | FILE:references/motion-animation.md # Material Design 3 动效与 Motion 设计 > 来源：Google Material Design 3 — Motion > URL: https://m3.material.io/design/motion > 版本：M3 2024-2025 > 抓取时间：2026-04-23 --- hermes: source: https://m3.material.io/ version: "2024-2025" platform: android|flutter|web updated: 2026-04-23 ## Motion 三大原则 | 原则 | 说明 | 示例 | |------|------|------| | **Expressive** | 动效表达品牌个性，体现产品情感 | FAB 展开动画、页面转场 | | **Informative** | 动效传达状态变化和空间关系 | 选中态、加载状态、列表操作 | | **Responsive** | 用户操作后立即响应，动画跟随 | 按钮点击反馈、拖拽跟随 | --- ## 动画时长规范 | 类型 | 时长 | 应用场景 | |------|------|---------| | **Micro（微交互）** | 100-200ms | 按钮状态变化、图标切换、选择反馈 | | **Short（中短）** | 200-300ms | 展开/收起、Toast、Snackbar | | **Medium（中）** | 300-400ms | 大型容器展开、页面过渡 | | **Long（长）** | 400-500ms | 大型表单展开、复杂 FAB 展开菜单 | **规则：用户参与程度越高，时长越短（越快越"响应"）** --- ## 缓动曲线（Easing） ### 四种核心曲线 | 曲线名称 | 特征 | 语义 | CSS | Flutter | Compose | |---------|------|------|------|---------|---------| | **Standard** | 减速进入，快速退出 | 主屏幕元素的标准过渡 | `cubic-bezier(0.4, 0.0, 0.2, 1)` | `Curves.easeInOut` | `FastOutSlowIn` | | **Emphasized** | 快速进入，缓慢退出 | 强调元素（FABS、Selection） | `cubic-bezier(0.2, 0.0, 0.0, 1.0)` | `Curves.easeOut` | `FastOutLinearIn` | | **Decelerated** | 快速进入，逐渐停止 | 进入动画（元素出现） | `cubic-bezier(0.0, 0.0, 0.2, 1)` | `Curves.easeOutCubic` | `SlowOutFastIn` | | **Accelerated** | 逐渐加速，快速离开 | 退出动画（元素消失） | `cubic-bezier(0.4, 0.0, 1, 1)` | `Curves.easeInCubic` | `LinearOutSlowIn` | ### 曲线应用场景 | 场景 | 推荐曲线 | |------|---------| | 元素出现（Fade + Scale in） | Decelerated | | 元素消失（Fade + Scale out） | Accelerated | | 页面主内容过渡 | Standard | | FAB 展开菜单 | Emphasized | | Bottom Sheet 展开 | Standard | | 选中状态变化 | Emphasized | | 列表项增删 | Standard | --- ## Android Compose 动画 ### 基础动画 ```kotlin import androidx.compose.animation.* // Fade 动画 AnimatedVisibility( visible = visible, enter = fadeIn(animationSpec = tween(300, easing = FastOutSlowIn)), exit = fadeOut(animationSpec = tween(200, easing = LinearOutSlowIn)) ) { Content() } // Scale + Fade 进入 AnimatedVisibility( visible = visible, enter = scaleIn( initialScale = 0.8f, animationSpec = tween(300, easing = SlowOutFastIn) ) + fadeIn(), exit = scaleOut( targetScale = 0.8f, animationSpec = tween(200, easing = LinearOutSlowIn) ) + fadeOut() ) // Slide 动画 AnimatedVisibility( visible = visible, enter = slideInVertically( initialOffsetY = { fullHeight -> fullHeight }, animationSpec = tween(300, easing = FastOutSlowIn) ), exit = slideOutVertically( targetOffsetY = { fullHeight -> fullHeight }, animationSpec = tween(200, easing = LinearOutSlowIn) ) ) ``` ### Crossfade（淡入淡出） ```kotlin // 两状态之间的淡入淡出 Crossfade( targetState = currentTab, animationSpec = tween(300), label = "tab_crossfade" ) { tab -> when (tab) { Tab.HOME -> HomeContent() Tab.SEARCH -> SearchContent() Tab.PROFILE -> ProfileContent() } } ``` ### 共享元素过渡（Shared Element） ```kotlin // 列表项到详情页的过渡 AnimatedContent( targetState = selectedItem, transitionSpec = { fadeIn(animationSpec = tween(300, easing = FastOutSlowIn)) togetherWith fadeOut(animationSpec = tween(200, easing = LinearOutSlowIn)) }, label = "item_transition" ) { item -> if (item != null) { ItemDetail(item = item) } else { ItemList() } } ``` ### Infinite Transition（循环动画） ```kotlin val infiniteTransition = rememberInfiniteTransition(label = "loading") val alpha by infiniteTransition.animateFloat( initialValue = 0.3f, targetValue = 1f, animationSpec = infiniteRepeatable( animation = tween(600, easing = FastOutSlowIn), repeatMode = RepeatMode.Reverse ), label = "alpha" ) // Loading 动画 CircularProgressIndicator( modifier = Modifier.graphicsLayer { alpha = this.alpha } ) ``` --- ## Flutter 动画 ### 基础动画 ```dart import 'package:flutter/material.dart'; // AnimatedOpacity AnimatedOpacity( opacity: visible ? 1.0 : 0.0, duration: const Duration(milliseconds: 300), curve: Curves.easeInOut, child: Content(), ) // AnimatedContainer AnimatedContainer( duration: const Duration(milliseconds: 300), curve: Curves.easeInOut, width: expanded ? 200 : 100, height: expanded ? 200 : 100, decoration: BoxDecoration( color: Theme.of(context).colorScheme.primaryContainer, borderRadius: BorderRadius.circular(expanded ? 28 : 8), ), ) // AnimatedSwitcher + Fade AnimatedSwitcher( duration: const Duration(milliseconds: 300), transitionBuilder: (child, animation) => FadeTransition( opacity: animation, child: child, ), child: KeyedSubtree(key: ValueKey(selected), child: Content()), ) ``` ### Slide 动画 ```dart // SlideTransition + AnimationController class _MyWidgetState extends State with SingleTickerProviderStateMixin { late AnimationController _controller; late Animation _slideAnimation; @override void initState() { super.initState(); _controller = AnimationController( duration: const Duration(milliseconds: 300), vsync: this, ); _slideAnimation = Tween( begin: const Offset(0, 1), end: Offset.zero, ).animate(CurvedAnimation( parent: _controller, curve: Curves.easeOutCubic, )); } @override void dispose() { _controller.dispose(); super.dispose(); } @override Widget build(BuildContext context) { return SlideTransition( position: _slideAnimation, child: Content(), ); } } ``` ### Hero 动画（共享元素） ```dart // 列表项 -> 详情页 Hero 动画 // 列表项 ListTile( leading: Hero( tag: 'avatar-${item.id}', child: CircleAvatar(backgroundImage: NetworkImage(item.avatarUrl)), ), title: Text(item.name), onTap: () => Navigator.push( context, MaterialPageRoute(builder: (_) => DetailPage(item: item)), ), ) // 详情页 Hero( tag: 'avatar-${item.id}', child: CircleAvatar( radius: 60, backgroundImage: NetworkImage(item.avatarUrl), ), ) ``` ### 循环动画 ```dart // 旋转 Loading class LoadingSpinner extends StatefulWidget { @override _LoadingSpinnerState createState() => _LoadingSpinnerState(); } class _LoadingSpinnerState extends State with SingleTickerProviderStateMixin { late AnimationController _controller; @override void initState() { super.initState(); _controller = AnimationController( duration: const Duration(milliseconds: 1000), vsync: this, )..repeat(); } @override void dispose() { _controller.dispose(); super.dispose(); } @override Widget build(BuildContext context) { return RotationTransition( turns: _controller, child: const Icon(Icons.refresh, size: 32), ); } } ``` --- ## H5 动画 ### CSS Transitions ```css /* 基本 Transition */ .md-button { transition: background-color 200ms ease-in-out, box-shadow 200ms ease-in-out; } .md-button:hover { background-color: var(--md-sys-color-primary); box-shadow: 0 2px 4px rgba(0,0,0,.2); } /* Scale 变换 */ .md-card:hover { transform: scale(1.02); transition: transform 200ms cubic-bezier(0.4, 0.0, 0.2, 1); } /* FAB 展开动画 */ .md-fab-menu { display: flex; flex-direction: column; gap: 16px; } .md-fab-menu-item { opacity: 0; transform: scale(0.8) translateY(20px); transition: opacity 300ms ease-out, transform 300ms cubic-bezier(0.2, 0.0, 0.0, 1); } .md-fab-menu.expanded .md-fab-menu-item { opacity: 1; transform: scale(1) translateY(0); } ``` ### H5 + JS 动画 ```html ``` --- ## 响应式动效 ### 减少动画（无障碍） | 用户设置 | 动作 | |---------|------| | `prefers-reduced-motion: reduce` | 所有动画时长设为 0 或极短 | | 运动障碍 | 禁用所有位移动画，只保留 Fade | ```css /* H5 — 尊重减少动画偏好 */ @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; } } ``` ```kotlin // Android — 尊重减少动画 @Composable fun Content() { val reducedMotion = androidx.compose.animation.core.rememberInfiniteTransition(label = "") // 使用 Animatable 或以编程方式检测系统设置 } ``` --- ## 平台差异速查 | 特性 | Android | Flutter | Web | |------|---------|---------|-----| | 声明式动画 | `AnimatedVisibility` | `AnimatedSwitcher` | CSS `transition` | | 程序化动画 | `Animatable.animateTo()` | `AnimationController` | `requestAnimationFrame` | | 共享元素 | `SharedTransitionLayout` | `Hero` | `View Transitions API` | | 循环动画 | `rememberInfiniteTransition` | `AnimationController.repeat()` | CSS `@keyframes` | | 缓动曲线 | `FastOutSlowIn` 等 | `Curves.*` | `cubic-bezier()` | | 减少动画 | `MediaQuery.disableAnimations()` | `MediaQuery.platformDataOf(context)` | `@media (prefers-reduced-motion)` | --- ## 来源 FILE:references/motion.md --- name: material-design-motion description: Google Material Design 3 动效系统完整参考，覆盖物理弹簧、Motion Scheme、过渡动画。 source: https://m3.material.io/styles/motion/overview/how-it-works --- # Material Design 3 Motion System Reference > 官方文档: https://m3.material.io/styles/motion/overview/how-it-works ## Overview Material 3 introduced a new **physics-based motion system** with M3 Expressive. This system makes interactions and transitions feel more alive, fluid, and natural. The physics system is replacing the previous system based on easing and duration. ### Platform Availability | Platform | Status | |----------|--------| | **MDC-Android** | Available. Not yet added to components. See specs | | **Flutter** | 部分可用：物理弹簧动画（`SpringSimulation`）✅，官方 M3 Motion 库封装 ❌ | | **Jetpack Compose** | Available | | **Web** | Compatible with Compose springs | --- ## Motion Philosophy: Physics-Based vs Easing-Based ### Physics-Based Motion Physics-based animations use spring physics to determine movement: - **Natural feel**: Motion responds to forces and continues based on physical properties - **Interruptible**: Can be interrupted mid-animation and transitions smoothly to new target - **Overshoot capability**: Can naturally exceed target values (bounce effect) - **No fixed duration**: Animation time varies based on physics parameters ### Easing-Based Motion (Legacy) The old system used predefined easing curves with fixed durations: ```javascript // Legacy easing-based approach transition: all 300ms ease-in-out; ``` ### Comparison | Aspect | Physics-Based | Easing-Based | |--------|--------------|--------------| | Feel | Natural, alive | Mechanical | | Interruptibility | Smooth interruption | Jumps or restarts | | Duration | Variable | Fixed | | Overshoot | Natural | Not supported | | Complexity | Higher | Lower | --- ## Motion Schemes The physics system provides two preset motion schemes. The scheme defines how your product feels. ### Expressive Scheme Material's **opinionated motion scheme** for most situations, particularly hero moments and key interactions. **Characteristics:** - Overshoots final values to add bounce - More playful and dynamic - Emphasizes important moments ``` Expressive → overshoots → settles ``` ### Standard Scheme More **functional with minimal bounce**. Best for utilitarian products. **Characteristics:** - Ease-in-out with minimal overshoot - Efficient and focused - Less visual emphasis ``` Standard → smooth ease → arrives ``` ### Choosing a Scheme | Use Case | Recommended Scheme | |----------|-------------------| | Hero moments | Expressive | | Key interactions | Expressive | | Important transitions | Expressive | | Utility apps | Standard | | Data-heavy interfaces | Standard | | Form-filling tasks | Standard | ### Advanced Customization Products can swap schemes to emphasize key moments while using a different scheme for the majority of motion. --- ## Spring Physics ### Spring Model Parameters The spring physics system uses these core parameters: | Parameter | Description | Effect | |-----------|-------------|--------| | **Stiffness** | Resistance to displacement | Higher = snappier | | **Damping** | Resistance to oscillation | Higher = less bounce | | **Mass** | Inertia of the object | Higher = slower | ### Spring Tokens Material 3 defines spring tokens that map to common use cases: ``` // Expressive spring (bouncy) spring: { damping: 0.6, stiffness: 200, mass: 1.0 } // Standard spring (controlled) spring: { damping: 0.8, stiffness: 300, mass: 1.0 } ``` ### Overshoot Behavior - **Expressive**: Springs overshoot the target value before settling - Creates bounce effect - Feels more responsive and playful - **Standard**: Springs approach target with minimal overshoot - Controlled arrival - Feels more precise and efficient ### Damping Ratio | Damping Ratio | Behavior | |---------------|----------| | < 1.0 | Underdamped (oscillates/bounces) | | = 1.0 | Critically damped (no overshoot) | | > 1.0 | Overdamped (slow settling) | Material 3 Expressive uses underdamped springs (~0.6-0.7) for bounce. --- ## Transition Patterns ### Container Transform Moving content between containers with smooth spatial transition. **Use for:** - List items expanding to detail views - Cards transforming into full-screen content - FAB expanding into screen ### Fade Through Content is replaced with a new element. **Use for:** - Navigation between major sections - Tab content changes - Mode switches ### Shared Axis Elements maintain relationship through 3D space. **Use for:** - Onboarding flows - Step-by-step processes - Sequential content ### Elevation Transition Elements moving up/down in z-axis. **Use for:** - FAB morphing - Bottom sheets - Dialogs ### Staggered Animation Sequential or overlapping animations of multiple elements. **Use for:** - List item animations - Grid reveals - Dashboard loading states --- ## Platform Implementation ### Flutter Flutter uses implicit animations with physics-based support. ```dart import 'package:flutter/material.dart'; // Implicit animation with AnimatedContainer AnimatedContainer( duration: Duration(milliseconds: 300), curve: Curves.easeInOut, width: isExpanded ? 200 : 100, height: isExpanded ? 200 : 100, child: Container(color: Colors.blue), ) // Custom spring animation with AnimationController class SpringAnimation extends StatefulWidget { @override _SpringAnimationState createState() => _SpringAnimationState(); } class _SpringAnimationState extends State with SingleTickerProviderStateMixin { late AnimationController _controller; late Animation _animation; @override void initState() { super.initState(); _controller = AnimationController( vsync: this, // No fixed duration - driven by physics ); _animation = Tween(begin: 0, end: 1).animate( CurvedAnimation( parent: _controller, curve: Curves.elasticOut, // Simulates spring overshoot ), ); } } ``` **Note:** M3 Expressive motion is not yet available for Flutter. ### Jetpack Compose Compose provides comprehensive spring animation support. ```kotlin import androidx.compose.animation.core.* import androidx.compose.foundation.background import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box import androidx.compose.runtime.* import androidx.compose.ui.Modifier import androidx.compose.ui.graphics.Color import androidx.compose.ui.unit.dp @Composable fun SpringAnimationExample() { var expanded by remember { mutableStateOf(false) } // Spring-based animation state val animatedSize by animateDpAsState( targetValue = if (expanded) 200.dp else 100.dp, animationSpec = spring( dampingRatio = SpringDampingRatio.R_mediumBouncy, stiffness = SpringStiffness.medium, ), label = "size" ) Box( modifier = Modifier .size(animatedSize) .background(Color.Blue) .clickable { expanded = !expanded } ) } // Explicit spring specification val springSpec = spring( dampingRatio = 0.6f, // Bouncy overshoot stiffness = 200f, // Snappiness mass = 1f // Heaviness ) // Using with animateFloatAsState @Composable fun FloatAnimation() { var target by remember { mutableStateOf(0f) } val animatedValue by animateFloatAsState( targetValue = target, animationSpec = spring( dampingRatio = SpringDampingRatio.NoBouncy, stiffness = SpringStiffness.high, ), label = "float" ) } ``` ### Android (Views / XML) Android uses the Transition framework with spring physics. ```xml import android.animation.SpringAnimation import android.animation.SpringForce // Spring animation for a view property val scaleXAnimation = SpringAnimation(view, SpringAnimation.SCALE_X, targetScale).apply { spring = SpringForce(targetScale).apply { dampingRatio = SpringForce.DAMPING_RATIO_MEDIUM_BOUNCY stiffness = SpringForce.STIFFNESS_MEDIUM } } // Start the animation scaleXAnimation.start() // Cancel on interruption scaleXAnimation.cancel() ``` ```kotlin // Container transform transition (AndroidX) import androidx.transition.TransitionSet import androidx.transition.Slide import androidx.transition.Fade val customTransition = TransitionSet().apply { ordering = TransitionSet.ORDERING_TOGETHER addTransition(Slide(Gravity.END)) addTransition(Fade(Fade.OUT)) } // Apply to fragment val exitTransition = customTransition val reenterTransition = Fade(Fade.IN) ``` ### Web / CSS Web supports spring-like animations through CSS and JavaScript. ```css /* CSS with custom properties (limited spring support) */ .motion-expressive { --motion-spring-damping: 0.6; --motion-spring-stiffness: 200; transition: transform var(--motion-duration-medium) cubic-bezier(0.34, 1.56, 0.64, 1); /* spring-like curve */ } .motion-standard { transition: transform var(--motion-duration-medium) cubic-bezier(0.4, 0.0, 0.2, 1); /* ease-in-out */ } /* Web Animations API with physics */ @keyframes spring-bounce { 0% { transform: scale(0.8); } 50% { transform: scale(1.1); } /* overshoot */ 100% { transform: scale(1.0); } } ``` ```javascript // Web Animations API with spring-like timing element.animate([ { transform: 'scale(0.8)', offset: 0 }, { transform: 'scale(1.1)', offset: 0.6 }, // overshoot at 60% { transform: 'scale(1.0)', offset: 1 } ], { duration: 400, easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)', // spring curve fill: 'forwards' }); ``` --- ## When to Use Motion ### Use Motion When | Scenario | Motion Type | |----------|-------------| | **Showing spatial relationships** | Container transform | | **Indicating state changes** | Fade through | | **Emphasizing importance** | Expressive spring | | **Guiding user attention** | Staggered reveals | | **Confirming actions** | Bounce/scale feedback | | **Navigating between views** | Shared axis | | **Expanding/collapsing content** | Spring-based implicit | ### Don't Overuse Motion Avoid motion when: - User prefers reduced motion (respect `prefers-reduced-motion`) - Motion serves no communicative purpose - Animation is purely decorative in a utilitarian context - It slows down task completion - It causes nausea or discomfort (flashing, rapid movement) ### Accessibility ```kotlin // Compose: Respecting reduced motion preferences @Composable fun AccessibleAnimation() { val prefersReducedMotion = LocalLayoutDirection.current val animatedValue by animateFloatAsState( targetValue = target, animationSpec = if (prefersReducedMotion) { snap() // Instant or very short } else { spring(dampingRatio = 0.6f) } ) } ``` ```dart // Flutter: Checking accessibility preferences MediaQuery.of(context).disableAnimations; // Returns true if user wants reduced motion // Wrap animations to check preference Widget build(BuildContext context) { final reduceMotion = MediaQuery.of(context).disableAnimations; return AnimatedContainer( duration: reduceMotion ? Duration.zero : Duration(milliseconds: 300), curve: reduceMotion ? Curves.linear : Curves.easeInOut, // ... ); } ``` --- ## Key Token Reference ### Duration Tokens | Token | Duration | Use Case | |-------|----------|----------| | `motion_duration_short1` | 50ms | Micro-interactions | | `motion_duration_short2` | 100ms | Small state changes | | `motion_duration_medium1` | 200ms | Standard transitions | | `motion_duration_medium2` | 300ms | Larger movements | | `motion_duration_long1` | 400ms | Full screen transitions | | `motion_duration_long2` | 500ms | Complex animations | ### Easing Tokens (Legacy Reference) | Token | Curve | Character | |-------|-------|-----------| | `easing-standard` | 0.4, 0.0, 0.2, 1 | Smooth entry/exit | | `easing-emphasized` | 0.4, 0.0, 0.2, 1 | Slightly more pronounced | | `easing-decelerated` | 0.0, 0.0, 0.2, 1 | Entering | | `easing-accelerated` | 0.4, 0.0, 1.0, 1 | Exiting | --- ## Resources | Resource | Link | Status | |----------|------|--------| | Motion Overview | https://m3.material.io/styles/motion/overview | Official docs | | MDC-Android | GitHub | Available | | Jetpack Compose | Compose Material 3 | Available | | Flutter | flutter/material.dart | M3 Expressive unavailable | | Design Kit (Figma) | Material Design Kit | Available | --- ## Related Documentation - [Motion Overview](https://m3.material.io/styles/motion/overview) - [Motion System - How it Works](https://m3.material.io/styles/motion/overview/how-it-works) - [Flutter Animations](https://docs.flutter.dev/development/ui/animations) - [Jetpack Compose Animation](https://developer.android.com/jetpack/compose/animation) FILE:references/navigation-components.md --- name: Navigation Components description: Material Design 3 navigation components including Navigation Bar, Navigation Drawer, Navigation Rail, and App Bars source: https://m3.material.io/components/navigation-bar/overview --- # Navigation Components ## Navigation Bar **Description:** Navigation bars let people switch between UI views on smaller devices. Use in compact or medium window sizes with 3-5 destinations of equal importance. **Source:** https://m3.material.io/components/navigation-bar/overview ### Variants | Variant | Description | |---------|-------------| | Flexible (New) | Shorter height, supports horizontal navigation items in medium windows | | Baseline (Legacy) | No longer recommended | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | Jetpack Compose: Expressive | Available | | Android | MDC-Android | Available | | Android | MDC-Android: Expressive | Available | | Web | Web | Unavailable | ### Key Updates (M3 Expressive) - Active label color changed from `on-surface-variant` to `secondary` - Flexible navigation bar is shorter and supports horizontal nav items --- ## Navigation Drawer **Description:** Navigation drawers let people switch between UI views on larger devices. **Source:** https://m3.material.io/components/navigation-drawer/overview ### Variants | Variant | Window Size | |---------|-------------| | Standard | Expanded, large, extra-large | | Modal | Compact and medium | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | MDC-Android | Available | | Web | Web | Unavailable | ### Key Updates (M3 Expressive) - **Deprecated:** Navigation drawer is no longer recommended - **Replacement:** Use expanded navigation rail instead, which has mostly the same functionality --- ## Navigation Rail **Description:** Navigation rails let people switch between UI views on mid-sized devices. Use in medium, expanded, large, or extra-large window sizes with 3-7 destinations plus an optional FAB. **Source:** https://m3.material.io/components/navigation-rail/overview ### Variants | Variant | Description | |---------|-------------| | Collapsed | Replaces baseline nav rail | | Expanded | Replaces navigation drawer | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | Jetpack Compose: Expressive | Available | | Android | MDC-Android | Available | | Android | MDC-Android: Expressive | Available | | Web | Web | Unavailable | ### Key Updates (M3 Expressive) - Collapsed and expanded rail introduced to replace baseline nav rail - Expanded rail meant to replace navigation drawer --- ## App Bars **Description:** App bars are placed at the top of the screen to help people navigate through a product. Display labels and page navigation controls. **Source:** https://m3.material.io/components/app-bars/overview ### Variants | Variant | Description | |---------|-------------| | Small | Standard app bar | | Medium Flexible (New) | Replaces medium, with flexible improvements | | Large Flexible (New) | Replaces large, with flexible improvements | | Search App Bar (New) | Supports icons inside/outside search bar, centered text | ### Platform Availability | Platform | Resource | Status | |----------|----------|--------| | Design | Figma Design Kit | Available | | Flutter | Flutter | Available | | Android | Jetpack Compose | Available | | Android | Jetpack Compose: Expressive | Available | | Android | MDC-Android | Available | | Android | MDC-Android: Expressive | Available | | Web | Web | Unavailable | ### Key Updates (M3 Expressive) - Search app bar supports icons inside/outside and centered text - Opens search view component when selected - Medium and large flexible app bars replace medium/large (no longer recommended) - Small app bar updated with flexible improvements ### Design Guidelines - Focus on describing the current page - Provide 1-2 essential actions - On scroll, apply fill color to separate from body content - Can animate on/off screen with another bar of controls FILE:references/platform-implementation.md --- name: material-design-platform description: Google Material Design 3 跨平台实现完整参考，覆盖 Flutter、Jetpack Compose、Android、Web。 source: https://m3.material.io/develop --- # Material Design 3 跨平台实现参考 ## 1. Cross-platform Overview Material Design 3 (M3) provides official implementation libraries for four platforms: | Platform | Library | M3 Status | M3 Expressive | |----------|---------|-----------|---------------| | **Android View** | MDC-Android | ✅ Available | ❌ Not available | | **Jetpack Compose** | Compose Material 3 | ✅ Available | ✅ Available (May 2025) | | **Flutter** | Material Widgets | ✅ Available | ❌ Not available | | **Web** | Material Web Components | 🔒 Maintenance mode | ❌ Not available | All platforms share: - **26+ color roles** mapped to components - **Unified color scheme system** (static baseline + dynamic color) - **Typography scale** with M3 type levels - **Elevation system** with tonal vs. overlay approaches - **Shape tokens** for component corner radii --- ## 2. Flutter Implementation ### Enabling Material 3 ```dart import 'package:flutter/material.dart'; void main() { runApp(const MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( title: 'M3 Demo', theme: ThemeData( useMaterial3: true, // Opt-in to M3 colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ), home: const MyHomePage(), ); } } ``` ### ColorScheme in Flutter ```dart // From seed color (recommended) final colorScheme = ColorScheme.fromSeed( seedColor: Colors.blue, brightness: Brightness.light, // or Brightness.dark ); // From predefined scheme final colorScheme = ColorScheme.fromScheme( scheme: ColorScheme.appleMedium(), // iOS-style baseline brightness: Brightness.light, ); // Manual color roles final colorScheme = ColorScheme( brightness: Brightness.light, primary: Color(0xFF006590), onPrimary: Colors.white, primaryContainer: Color(0xFFC4E7FF), onPrimaryContainer: Color(0xFF001E2F), secondary: Color(0xFF4F600E), onSecondary: Colors.white, // ... all 12+ color roles ); ``` ### Dynamic Color (Wallpaper-based) ```dart ColorScheme.fromDynamic( dynamicScheme: DynamicScheme.fromImage( imageProvider: wallpaperImage, sourceColorHct: Hct.fromInt(Colors.blue.toARGB32()), ), ); ``` ### Applying Theme to Components ```dart // Wrap with MaterialApp using ThemeData MaterialApp( theme: ThemeData( useMaterial3: true, colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), ), home: const Scaffold(body: ...), ); // Access in widgets Widget build(BuildContext context) { final colorScheme = Theme.of(context).colorScheme; return Card( color: colorScheme.primaryContainer, child: Text('Hello', style: TextStyle(color: colorScheme.onPrimaryContainer)), ); } ``` ### Key Flutter Theming Properties ```dart ThemeData( useMaterial3: true, colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue), // Typography (M3 type scale) textTheme: Typography.material2021atypeScale, // Elevation overrides (optional) elevatedButtonTheme: ElevatedButtonThemeData( style: ElevatedButton.styleFrom( elevation: 2, // M3 uses tonal elevation ), ), ) ``` --- ## 3. Jetpack Compose Implementation ### Setup ```kotlin // build.gradle.kts dependencies { implementation("androidx.compose.material3:material3:1.3.0") } ``` ### Basic M3 Theme ```kotlin import androidx.compose.material3.* import androidx.compose.runtime.Composable import androidx.compose.ui.graphics.Color @Composable fun MyApp() { MaterialTheme( colorScheme = colorScheme, typography = Typography(), content = { /* app content */ } ) } private val colorScheme = lightColorScheme( primary = Color(0xFF006590), onPrimary = Color.White, primaryContainer = Color(0xFFC4E7FF), onPrimaryContainer = Color(0xFF001E2F), secondary = Color(0xFF4F600E), onSecondary = Color.White, // ... all color roles ) ``` ### Using rememberMaterial3Theme (Optional) ```kotlin @Composable fun rememberMaterial3Theme( seedColor: Color = Color(0xFF6750A4), lightTonalPalette: TonalPalette? = null, darkTonalPalette: TonalPalette? = null, ): MaterialTheme { val colorScheme = when { lightTonalPalette != null && darkTonalPalette != null -> { dynamicMultiBreakpointColorScheme( lightTonalPalette = lightTonalPalette, darkTonalPalette = darkTonalPalette, ) } else -> { val scheme = ColorScheme.from( Color(seedColor), "en" // locale ) if (darkTonalPalette != null) scheme.dark else scheme.light } } return MaterialTheme(colorScheme = colorScheme) } ``` ### Dynamic Color (Android 12+) ```kotlin @Composable fun DynamicColorMaterialTheme( content: @Composable () -> Unit ) { val colorScheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { val context = LocalContext.current dynamicLightColorScheme(context) // or dynamicDarkColorScheme(context) for dark mode } else { lightColorScheme() // fallback } MaterialTheme(colorScheme = colorScheme, content = content) } ``` ### Applying Colors in Components ```kotlin @Composable fun MyCard() { Card( colors = CardDefaults.cardColors( containerColor = MaterialTheme.colorScheme.primaryContainer ) ) { Text( "Hello", color = MaterialTheme.colorScheme.onPrimaryContainer ) } } ``` ### M3 Expressive (Motion Physics) - Compose 1.3+ ```kotlin // Motion theming with spring physics val springSpec = SpringSpec( dampingRatio = Spring.DampingRatioMediumBouncy, stiffness = Spring.StiffnessMedium ) // Apply to component transitions AnimatedVisibility( visibleState = expanded, enterMotionSpec = springSpec, exitMotionSpec = springSpec ) ``` --- ## 4. Android View Implementation (MDC-Android) ### Setup ```gradle // build.gradle dependencies { implementation 'com.google.android.material:material:1.12.0' } ``` ### Applying M3 Theme ```xml ``` ### Programmatically with ColorScheme (M3 1.2+) ```kotlin import com.google.android.material.color.DynamicColors import com.google.android.material.color.ColorScheme // Apply dynamic colors (wallpaper-based) to Activity class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { DynamicColors.applyToActivityIfSupported(this) super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) } } // Use ColorScheme programmatically val colorScheme = ColorScheme.from( seedColor = Color(0xFF6750A4), brightness = Brightness.LIGHT ) val primaryPaint = Paint().apply { color = colorScheme.primary } ``` ### Material3 color roles (26+ roles) ```kotlin // Light scheme val colorScheme = ColorScheme.light( primary = Color(0xFF6750A4), onPrimary = Color.White, primaryContainer = Color(0xFFEADDFF), onPrimaryContainer = Color(0xFF21005D), secondary = Color(0xFF625B71), onSecondary = Color.White, secondaryContainer = Color(0xFFE8DEF8), onSecondaryContainer = Color(0xFF1D192B), tertiary = Color(0xFF7D5260), onTertiary = Color.White, tertiaryContainer = Color(0xFFFFD8E4), onTertiaryContainer = Color(0xFF31111D), error = Color(0xFFB3261E), onError = Color.White, errorContainer = Color(0xFFF9DEDC), onErrorContainer = Color(0xFF410E0B), background = Color(0xFFFFFBFE), onBackground = Color(0xFF1C1B1F), surface = Color(0xFFFFFBFE), onSurface = Color(0xFF1C1B1F), surfaceVariant = Color(0xFFE7E0EC), onSurfaceVariant = Color(0xFF49454F), outline = Color(0xFF79747E), outlineVariant = Color(0xFFCAC4D0), // ... more roles ) ``` ### Using M3 Components ```xml ``` --- ## 5. Web Implementation ### Status > ⚠️ **Note**: Material Web Components are currently in **maintenance mode**. No new features are being added. M3 Expressive is **not implemented** on Web. ### Installation ```bash npm install @material/web ``` ### Basic Setup with CSS Custom Properties ```html

Hello

World ``` ### CSS Theming with M3 Tokens ```css :root { /* M3 Color Tokens - Light */ --md-sys-color-primary: #6750A4; --md-sys-color-on-primary: #FFFFFF; --md-sys-color-primary-container: #EADDFF; --md-sys-color-on-primary-container: #21005D; --md-sys-color-secondary: #625B71; --md-sys-color-on-secondary: #FFFFFF; --md-sys-color-secondary-container: #E8DEF8; --md-sys-color-on-secondary-container: #1D192B; --md-sys-color-surface: #FFFBFE; --md-sys-color-on-surface: #1C1B1F; --md-sys-color-surface-variant: #E7E0EC; --md-sys-color-on-surface-variant: #49454F; --md-sys-color-outline: #79747E; --md-sys-color-outline-variant: #CAC4D0; /* Typography */ --md-sys-typescale-display-large: Roboto, sans-serif; --md-sys-typescale-headline-large: Roboto, sans-serif; --md-sys-typescale-body-large: Roboto, sans-serif; /* Shape */ --md-sys-shape-corner-extra-large: 28px; --md-sys-shape-corner-large: 16px; --md-sys-shape-corner-medium: 12px; --md-sys-shape-corner-small: 8px; } ``` ### Using Web Components ```html

Confirm

Card Title

Subtitle

Card content here

``` ### JavaScript Integration ```javascript import { MdButton } from '@material/web/button/md-button.js'; // Customize via properties const button = document.querySelector('md-filled-button'); button.disabled = false; button.icon = 'check'; // Listen to events button.addEventListener('click', (e) => { console.log('Button clicked:', e.target); }); ``` ### Applying Theme in JavaScript ```javascript import { Theme } from '@material/web/theme/theme.js'; // Apply M3 theme to elements const theme = new Theme(); theme.applyTo(document.body); // Or via CSS document.documentElement.style.setProperty('--md-sys-color-primary', '#6750A4'); ``` --- ## 6. Theming Across Platforms ### Shared Token Structure All platforms share the same 26+ M3 color roles: | Token Category | Roles | |----------------|-------| | **Primary** | primary, onPrimary, primaryContainer, onPrimaryContainer | | **Secondary** | secondary, onSecondary, secondaryContainer, onSecondaryContainer | | **Tertiary** | tertiary, onTertiary, tertiaryContainer, onTertiaryContainer | | **Error** | error, onError, errorContainer, onErrorContainer | | **Surface** | surface, onSurface, surfaceVariant, onSurfaceVariant | | **Outline** | outline, outlineVariant | | **Background** | background, onBackground (non-surface roles) | | **Inverse** | inverseSurface, inverseOnSurface, inversePrimary | | **Shadow** | shadow, scrim | | **Surface Tint** | surfaceTint | ### Unified Color Scheme Generation ``` Seed Color → Tonal Palette Generation → Color Role Mapping ↓ Blue → 16 tonal steps → 26+ color roles per theme mode ``` ### Platform Comparison | Feature | Flutter | Compose | Android View | Web | |---------|---------|---------|--------------|-----| | **Enable M3** | `useMaterial3: true` | `MaterialTheme()` | `Theme.Material3.*` | CSS tokens | | **From seed** | `ColorScheme.fromSeed()` | `ColorScheme.from()` | `ColorScheme.from()` | N/A | | **Dynamic color** | ✅ | ✅ | ✅ | ❌ | | **Dark mode** | `Brightness.dark` | `darkColorScheme()` | `Theme.Material3.Dark` | CSS media query | | **Typography** | `textTheme` | `Typography()` | `textAppearance` | CSS `font-*` | | **Elevation** | Tonal (default) | Tonal (default) | Tonal (default) | CSS `box-shadow` | | **Components** | Material Widgets | `material3` library | `Material` library | Web Components | ### ColorScheme Generation Example (Unified Concept) ``` // All platforms can generate a ColorScheme from a seed color: Flutter: ColorScheme.fromSeed(seedColor: Colors.purple) Compose: ColorScheme.from(Color(0xFF6750A4)) Android: ColorScheme.from(seedColor = Color(0xFF6750A4)) Web: Use --md-sys-color-primary CSS token // Result: Consistent color relationships across all platforms ``` ### Typography Scale (M3) | Level | Flutter | Compose | Android View | Web | |-------|---------|---------|--------------|-----| | Display Large | `displayLarge` | `DisplayLarge` | `DisplayLarge` | `--typescale-display-large` | | Headline | `headlineMedium` | `HeadlineMedium` | `HeadlineMedium` | `--typescale-headline-medium` | | Title | `titleLarge` | `TitleLarge` | `TitleLarge` | `--typescale-title-large` | | Body | `bodyLarge` | `BodyLarge` | `BodyLarge` | `--typescale-body-large` | | Label | `labelMedium` | `LabelMedium` | `LabelMedium` | `--typescale-label-medium` | --- ## Resources | Platform | Documentation | |----------|---------------| | Flutter | https://m3.material.io/develop/flutter | | Jetpack Compose | https://m3.material.io/develop/android/jetpack-compose | | MDC-Android | https://m3.material.io/develop/android | | Web | https://m3.material.io/develop/web | | Material Theme Builder | https://material-foundation.github.io/material-theme-builder/ | FILE:references/shape-elevation-icons.md --- name: material-design-shape-elevation description: Google Material Design 3 形状、Elevation、图标系统完整参考。 source: https://m3.material.io/styles/shape/overview --- # Material Design 3 — Shape, Elevation & Icons ## Shape System ### Overview M3 形状系统包含 35 种预设形状、圆角半径刻度和形状渐变（Shape Morph）功能。 **核心原则：** - 形状与文字和谐使用 - 通过形状渐变连接功能与情感 - 大胆运用张力 - 形状是表现性的，非语义性的 - 抽象形状仅用于强调时刻 - 形状可以是 2.5D ### 圆角半径刻度（Corner Radius Scale） | 样式 | Token | 值 | |------|-------|-----| | None | `none` | 0dp | | Extra Small | `extraSmall` | 4dp | | Small | `small` | 8dp | | Medium | `medium` | 12dp | | Large | `large` | 16dp | | Large Increased | `largeIncreased` | 20dp | | Extra Large | `extraLarge` | 28dp | | Extra Large Increased | `extraLargeIncreased` | 32dp | | Extra Extra Large | `extraExtraLarge` | 48dp | | Full | `full` | 完全圆角 | **说明：** M3 Expressive 更新（2025年5月）新增了 Large Increased (20dp)、Extra Large Increased (32dp)、Extra Extra Large (48dp) 三个刻度，并将"完全圆角"从 50% 改为 `full` token。 ### 形状 Tokens | 形状 Token | 描述 | |-----------|------| | `fullyRounded` | 四角完全圆角 | | `extraLargeTopRounding` | 顶部圆角加大 | | `extraLargeRounding` | 整体加大圆角 | | `largeTopRounding` | 顶部大圆角 | | `largeEndRounding` | 末端大圆角 | | `largeStartRounding` | 首端大圆角 | | `largeRounding` | 整体大圆角 | | `mediumRounding` | 中等圆角 | | `smallRounding` | 小圆角 | | `extraSmallTopRounding` | 顶部小圆角 | | `extraSmallRounding` | 整体小圆角 | | `noRounding` | 无圆角 | | `largeIncreasedRounding` | 增大圆角 | | `extraLargeIncreasedRounding` | 超大增大圆角 | | `extraExtraLargeRounding` | 超超大圆角 | ### 资源 | 平台 | 资源 | 状态 | |------|------|------| | Design | Shape Library (Figma Design Kit) | Available | | Implementation | Jetpack Compose (Shape Library) | Available | | Android | MDC-Android | Available | --- ## Elevation 系统 ### Overview Elevation 表示两个表面在 z 轴上的距离，以 dps（密度无关像素）为单位。 **核心原则：** - 所有表面和组件都有 Elevation 值 - Tokens 编码 z 轴距离，确保组件相对关系一致 - Tokens 本身不含阴影或颜色，由各平台实现 - Elevation 可通过色调表面颜色或阴影显示 - 避免修改 Material 3 组件的默认 Elevation - 使用少量 Elevation 级别 ### Elevation 级别 | Level | Token | 用途 | |-------|-------|------| | 0 | `level0` / `none` | 背景表面 | | 1 | `level1` | 表面 | | 2 | `level2` | 导航组件 | | 3 | `level3` | 组件（如 FAB） | | 4 | `level4` | 模态组件 | | 5 | `level5` | 对话框 | **注意：** M2 与 M3 的关键区别： - **阴影**：M3 仅在需要创建额外保护或鼓励交互时才使用阴影 - **颜色**：新的颜色映射，支持动态配色 ### 资源 | 平台 | 资源 | 状态 | |------|------|------| | Design | Design Kit (Figma) | Available | | Implementation | Flutter | Available | | Implementation | Jetpack Compose | Available | | Implementation | MDC-Android | Available | | Implementation | MWC-Web | Available | --- ## Icons 系统 ### Overview Material Icons 是用于识别操作和类别的微小符号。现已升级为 **Material Symbols** 可变字体。 ### Material Symbols 样式 | 样式 | 描述 | |------|------| | Outlined | 描边风格 | | Rounded | 圆角风格 | | Sharp | 锐利风格 | ### 可调轴（Adjustable Axes） Material Symbols 有四个可调属性： | 轴 | 描述 | |----|------| | Weight | 字重（粗细） | | Fill | 填充程度 | | Optical Size | 光学尺寸 | | Grade | 等级（灰度级别） | ### 图标尺寸 | 场景 | 推荐尺寸 | |------|----------| | 界面图标 (UI Icons) | 24dp | | 触控目标 | 最小 48×48dp | | 密集布局 | 20dp | | 装饰性图标 | 16dp | ### 使用指南 - 通过 fonts.google.com/icons 获取 Material Symbols - 使用 Material Symbols 可变字体实现动态样式 - 可在 Figma 中使用 Material Symbols 插件 - 支持复制粘贴自定义图标（调整大小、颜色后） ### 资源 | 类型 | 资源 | 状态 | |------|------|------| | Design | Icons Catalog | Available | | Design | Material Symbols Figma Plugin | Available | | Design | Icon Keyline Template (ZIP) | Available | --- ## 平台实现 ### Jetpack Compose ```kotlin // Shape shape = RoundedCornerShape(16.dp) // Elevation Modifier.shadow(elevation = 8.dp) // Icon Icon( imageVector = Icons.Filled.Star, contentDescription = "Star" ) ``` ### Android (MDC) ```xml app:shapeAppearanceOverlay="@style/ShapeAppearance.Material3.LargeComponent" android:elevation="8dp" ``` ### Flutter ```dart // Shape shape: RoundedRectangleBorder( borderRadius: BorderRadius.circular(16), ) // Elevation elevation: 8.0 // Icon Icon(Icons.star) ``` ### Web (MWC) ```html

``` FILE:references/typography.md --- name: material-design-typography description: Google Material Design 3 字体系统完整参考，覆盖 Type Scale、Token、平台实现。 source: https://m3.material.io/styles/typography/overview --- # Material Design 3 Typography Reference ## Overview M3 type scale contains **30 type styles**: 15 baseline and 15 emphasized (May 2025 Expressive update). The type scale organizes styles into five roles: Display, Headline, Title, Label, and Body. Each role has three sizes: Large, Medium, and Small. --- ## M3 Type Scale ### Baseline Type Styles | Role | Size | Token | Size (px) | Line Height (px) | Weight | Tracking | |------|------|-------|-----------|------------------|--------|----------| | **Display** | Large | `typescale-display-large` | 57 | 64 | 400 | -0.25 | | **Display** | Medium | `typescale-display-medium` | 45 | 52 | 400 | 0 | | **Display** | Small | `typescale-display-small` | 36 | 44 | 400 | 0 | | **Headline** | Large | `typescale-headline-large` | 32 | 40 | 400 | 0 | | **Headline** | Medium | `typescale-headline-medium` | 28 | 36 | 400 | 0 | | **Headline** | Small | `typescale-headline-small` | 24 | 32 | 400 | 0 | | **Title** | Large | `typescale-title-large` | 22 | 28 | 400 | 0 | | **Title** | Medium | `typescale-title-medium` | 16 | 24 | 500 | 0.15 | | **Title** | Small | `typescale-title-small` | 14 | 20 | 500 | 0.1 | | **Body** | Large | `typescale-body-large` | 16 | 24 | 400 | 0.5 | | **Body** | Medium | `typescale-body-medium` | 14 | 20 | 400 | 0.25 | | **Body** | Small | `typescale-body-small` | 12 | 16 | 400 | 0.4 | | **Label** | Large | `typescale-label-large` | 14 | 20 | 500 | 0.1 | | **Label** | Medium | `typescale-label-medium` | 12 | 16 | 500 | 0.5 | | **Label** | Small | `typescale-label-small` | 11 | 16 | 500 | 0.5 | ### Emphasized Type Styles (M3 Expressive) Emphasized styles add more expression to highlighted moments with higher weight and minor adjustments. They complement baseline styles. | Role | Size | Token | Size (px) | Line Height (px) | Weight | Tracking | |------|------|-------|-----------|------------------|--------|----------| | **Display** | Large | `typescale-display-large-emphasis` | 57 | 64 | 400 | -0.25 | | **Display** | Medium | `typescale-display-medium-emphasis` | 45 | 52 | 400 | 0 | | **Display** | Small | `typescale-display-small-emphasis` | 36 | 44 | 400 | 0 | | **Headline** | Large | `typescale-headline-large-emphasis` | 32 | 40 | 400 | 0 | | **Headline** | Medium | `typescale-headline-medium-emphasis` | 28 | 36 | 400 | 0 | | **Headline** | Small | `typescale-headline-small-emphasis` | 24 | 32 | 400 | 0 | | **Title** | Large | `typescale-title-large-emphasis` | 22 | 28 | 500 | 0 | | **Title** | Medium | `typescale-title-medium-emphasis` | 16 | 24 | 500 | 0.15 | | **Title** | Small | `typescale-title-small-emphasis` | 14 | 20 | 500 | 0.1 | | **Body** | Large | `typescale-body-large-emphasis` | 16 | 24 | 500 | 0.5 | | **Body** | Medium | `typescale-body-medium-emphasis` | 14 | 20 | 500 | 0.25 | | **Body** | Small | `typescale-body-small-emphasis` | 12 | 16 | 500 | 0.4 | | **Label** | Large | `typescale-label-large-emphasis` | 14 | 20 | 500 | 0.1 | | **Label** | Medium | `typescale-label-medium-emphasis` | 12 | 16 | 500 | 0.5 | | **Label** | Small | `typescale-label-small-emphasis` | 11 | 16 | 500 | 0.5 | --- ## Font Families ### Default Typeface: Roboto Roboto is the default typeface for Android and M3. It includes over 3,300 glyphs supporting hundreds of languages worldwide. ### Variable Fonts (Available for Customization) #### Roboto Flex - Variable font with extended flexibility - Additional customizable attributes including size-specific designs - Over 900 glyphs with support for Latin, Greek, and Cyrillic - Not yet part of the M3 typescale (May 2025) #### Roboto Serif - Variable font designed for comfortable reading - Minimal and highly functional - Extensive set of weights and widths across a broad range of sizes - Suitable for app interfaces and editorial content #### Roboto Mono - Monospaced version of Roboto - Each letter has equal space with adjusted letterforms --- ## Type Scale Tokens Each type style has a **single composite token** that captures all default properties. Individual axis tokens enable granular customization: | Token Type | Description | Example | |------------|-------------|---------| | **Composite token** | All properties in one | `typescale-display-large` | | **Font token** | Font family only | `typography-font-family` | | **Size token** | Font size only | `typography-size` | | **Line height token** | Line height only | `typography-line-height` | | **Tracking token** | Letter spacing only | `typography-tracking` | | **Weight token** | Font weight only | `typography-weight` | ### Token Naming Convention ``` // Composite token material.typography.typescale.[role].[size] // Individual axis token material.typography.[role].[size].[property] ``` --- ## Applying Type ### Role Guidelines #### Display - **Use for**: Short, important text or numerals; largest text on screen - **Best on**: Large screens - **Consider**: Expressive fonts (handwritten, script) for visual impact - **Tip**: Set appropriate optical size when available #### Headline - **Use for**: Short, high-emphasis text on smaller screens; marking primary passages - **Suitable for**: Section headers, important content regions - **Expressive option**: Can use expressive typefaces with adjusted line height and letter spacing #### Title - **Use for**: Titles of content sections, card headers - **Medium/Small sizes**: Use weight 500 (Medium) for increased emphasis #### Body - **Use for**: Longer paragraphs of text, content that requires reading - **Large**: Primary body text - **Medium/Small**: Secondary text, captions #### Label - **Use for**: Buttons, tabs, chips, small UI text - **Tracking**: Medium and Small labels have higher tracking for legibility at small sizes ### Typesetting Best Practices 1. **Optical sizing**: Set appropriate optical size for display and headline styles 2. **Line height**: Ensure adequate line height for readability (typically 1.2-1.5× font size) 3. **Line length**: Target 50-75 characters per line for body text 4. **Contrast**: Maintain sufficient contrast between text and background 5. **Tracking adjustment**: Increase tracking for small text labels ### Ensuring Readability - Body text minimum: 12px for legible text - Label text minimum: 11px - Line height ratios: 1.2× for headlines, 1.4-1.5× for body text - Letter spacing: Adjust for size - smaller text may need more tracking --- ## Platform Implementation ### Flutter ```dart // Using TextTheme TextTheme( displayLarge: TextStyle(fontSize: 57, height: 64/57), displayMedium: TextStyle(fontSize: 45, height: 52/45), displaySmall: TextStyle(fontSize: 36, height: 44/36), headlineLarge: TextStyle(fontSize: 32, height: 40/32), headlineMedium: TextStyle(fontSize: 28, height: 36/28), headlineSmall: TextStyle(fontSize: 24, height: 32/24), titleLarge: TextStyle(fontSize: 22, height: 28/22), titleMedium: TextStyle(fontSize: 16, height: 24/16, fontWeight: FontWeight.w500), titleSmall: TextStyle(fontSize: 14, height: 20/14, fontWeight: FontWeight.w500), bodyLarge: TextStyle(fontSize: 16, height: 24/16), bodyMedium: TextStyle(fontSize: 14, height: 20/14), bodySmall: TextStyle(fontSize: 12, height: 16/12), labelLarge: TextStyle(fontSize: 14, height: 20/14, fontWeight: FontWeight.w500), labelMedium: TextStyle(fontSize: 12, height: 16/12, fontWeight: FontWeight.w500), labelSmall: TextStyle(fontSize: 11, height: 16/11, fontWeight: FontWeight.w500), ) ``` **Status**: M3 Expressive is NOT available on Flutter. ### Jetpack Compose ```kotlin // Using Typography Typography( displayLarge = TextStyle(fontSize = 57.sp, lineHeight = 64.sp), displayMedium = TextStyle(fontSize = 45.sp, lineHeight = 52.sp), displaySmall = TextStyle(fontSize = 36.sp, lineHeight = 44.sp), headlineLarge = TextStyle(fontSize = 32.sp, lineHeight = 40.sp), headlineMedium = TextStyle(fontSize = 28.sp, lineHeight = 36.sp), headlineSmall = TextStyle(fontSize = 24.sp, lineHeight = 32.sp), titleLarge = TextStyle(fontSize = 22.sp, lineHeight = 28.sp), titleMedium = TextStyle(fontSize = 16.sp, lineHeight = 24.sp, fontWeight = FontWeight.Medium), titleSmall = TextStyle(fontSize = 14.sp, lineHeight = 20.sp, fontWeight = FontWeight.Medium), bodyLarge = TextStyle(fontSize = 16.sp, lineHeight = 24.sp), bodyMedium = TextStyle(fontSize = 14.sp, lineHeight = 20.sp), bodySmall = TextStyle(fontSize = 12.sp, lineHeight = 16.sp), labelLarge = TextStyle(fontSize = 14.sp, lineHeight = 20.sp, fontWeight = FontWeight.Medium), labelMedium = TextStyle(fontSize = 12.sp, lineHeight = 16.sp, fontWeight = FontWeight.Medium), labelSmall = TextStyle(fontSize = 11.sp, lineHeight = 16.sp, fontWeight = FontWeight.Medium) ) ``` **Status**: M3 Expressive IS available on Jetpack Compose (May 2025). ### Android (XML) ```xml ``` ### CSS ```css /* M3 Type Scale CSS */ :root { --md-sys-typescale-display-large: clamp(3.56rem, 3.54rem + 0.11vw, 3.57rem); --md-sys-typescale-display-medium: clamp(2.81rem, 2.8rem + 0.05vw, 2.81rem); --md-sys-typescale-display-small: clamp(2.25rem, 2.25rem + 0vw, 2.25rem); /* ... additional type scale values ... */ } /* Example usage */ .text-display-large { font-family: Roboto; font-size: 57px; line-height: 64px; letter-spacing: -0.25px; font-weight: 400; } ``` **Status**: M3 Expressive IS NOT available on Web. --- ## Accessibility ### Minimum Readable Sizes | Context | Minimum Size | |---------|--------------| | Body text | 12px | | Labels (buttons, chips) | 11px | | Captions | 12px | ### Line Height Guidelines - **Headlines**: 1.2× font size (e.g., 32px text → 40px line height) - **Body text**: 1.4-1.5× font size (e.g., 14px text → 20px line height) - **Small labels**: 1.3-1.5× font size for legibility ### Contrast Requirements - Normal text: 4.5:1 contrast ratio minimum - Large text (18px+ or 14px bold): 3:1 contrast ratio minimum - Ensure sufficient contrast in both light and dark themes ### Additional Considerations 1. **Touch targets**: Label text should be at least 11px but ensure clickable areas are at least 48×48dp 2. **Scaling**: Support dynamic text scaling while maintaining layout integrity 3. **Language support**: Roboto supports 3,300+ glyphs for internationalization 4. **Line length**: Limit body text to 50-75 characters per line for optimal readability --- ## M3 Expressive Update (May 2025) The M3 Expressive update introduced emphasized type styles: - **15 new emphasized styles** complement the 15 baseline styles - Emphasized styles have **higher weight** and minor adjustments - Best used for **bold, selection, and other areas of emphasis** - Baseline and emphasized styles are **meant to be used together** - **Roboto Flex** enables expressive typography but is not yet part of the M3 typescale ### Where Emphasized Styles Are Available | Platform | Status | |----------|--------| | Flutter | Not available | | Jetpack Compose | Available | | MDC-Android | Available | | Web | Not available | --- ## Resources - **Google Fonts**: [Roboto](https://fonts.google.com/specimen/Roboto), [Roboto Flex](https://fonts.google.com/specimen/Roboto+Flex), [Roboto Serif](https://fonts.google.com/specimen/Roboto+Serif), [Roboto Mono](https://fonts.google.com/specimen/Roboto+Mono) - **Design Kit**: Available (Figma) - **Official Documentation**: https://m3.material.io/styles/typography/overview

Material Design Skill

Comments (0)