Lampio 知识库

主题

UI Guidelines ​

Material 3 设计规范指南

最后更新：2026-02-21

📋 规范文档列表 ​

文档内容状态
Material 3 设计系统文本/图标/颜色/间距设计原则和系统规范✅ 完成
按钮样式规范FilledButton/OutlinedButton/TextButton 使用规范✅ 完成
对话框样式规范AlertDialog/SimpleDialog 使用规范✅ 完成
表单组件指南TextField/Checkbox/Radio 使用规范✅ 完成
卡片组件指南Card/ListTile 使用规范✅ 完成
导航组件指南AppBar/BottomNavigationBar 使用规范✅ 完成
弹出菜单样式规范PopupMenuButton/PopupMenuItem 使用规范✅ 完成
动画设计规范Duration/Curve/Motion Springs 规范✅ 完成 🆕
Elevation 设计规范阴影层级/暗色模式处理✅ 完成 🆕
无障碍设计规范触摸目标/对比度/语义化标签✅ 完成 🆕
图标尺寸规范标准尺寸/组件图标/颜色✅ 完成 🆕

🎯 快速参考 ​

按钮选择决策树 ​

按钮用途？
├── 主要操作（保存、确认、提交）
│   └── FilledButton（primary 背景）
│
├── 次要操作（跳过、稍后、下一步）
│   └── FilledButton.tonal（secondaryContainer 背景）
│
├── 取消/返回操作
│   └── OutlinedButton（透明背景+边框）
│
└── 低优先级操作（链接、内联操作）
    └── TextButton（无背景无边框）

圆角规范 ​

元素圆角大小
对话框28px
按钮12px
卡片内元素12px
容器12px
PopupMenu12px

常用代码片段 ​

dart
// 主按钮
FilledButton(
  style: FilledButton.styleFrom(
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
  onPressed: _onPressed,
  child: const Text('确认'),
)

// 次要按钮
FilledButton.tonal(
  style: FilledButton.styleFrom(
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
  onPressed: _onPressed,
  child: const Text('跳过'),
)

// 取消按钮
OutlinedButton(
  style: OutlinedButton.styleFrom(
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
  onPressed: _onPressed,
  child: const Text('取消'),
)

// 弹出菜单（使用主题配置，无需自定义）
PopupMenuButton<String>(
  icon: const Icon(Icons.more_vert),
  offset: const Offset(0, 40),  // 避免遮挡内容
  itemBuilder: (context) => [
    PopupMenuItem(
      value: 'edit',
      child: Row(
        children: [
          Icon(Icons.edit_outlined, size: 20),
          const SizedBox(width: 12),
          const Text('编辑'),
        ],
      ),
    ),
  ],
  onSelected: (value) {
    // 处理选择
  },
)

❌ 常见错误 ​

1. 使用废弃的 ElevatedButton ​

dart
// ❌ 错误
ElevatedButton(
  onPressed: _save,
  child: const Text('保存'),
)

// ✅ 正确
FilledButton(
  style: FilledButton.styleFrom(
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
  onPressed: _save,
  child: const Text('保存'),
)

2. 硬编码颜色 ​

dart
// ❌ 错误
FilledButton(
  style: FilledButton.styleFrom(
    backgroundColor: Colors.blue,
    foregroundColor: Colors.white,
  ),
  child: const Text('确认'),
)

// ✅ 正确
FilledButton(
  // 自动使用 primary/onPrimary
  child: const Text('确认'),
)

3. 圆角不统一 ​

dart
// ❌ 错误
BorderRadius.circular(8)  // 不统一！
BorderRadius.circular(16) // 不统一！

// ✅ 正确
BorderRadius.circular(12) // 统一使用 12px

📚 详细规范 ​

请查看各个规范文档获取详细说明和代码示例：

组件规范 ​

基础规范 🆕 ​

🔍 规范检查工具 ​

代码审查检查清单 ​

使用以下命令快速检查代码是否符合规范：

bash
# 检查是否还有 ElevatedButton
grep -r "ElevatedButton" lib/features --include="*.dart" | grep -v "test"

# 检查硬编码颜色
grep -r "backgroundColor:.*Colors\." lib/features --include="*.dart"
grep -r "foregroundColor:.*Colors\." lib/features --include="*.dart"

# 检查圆角不统一
grep -r "BorderRadius.circular" lib/features --include="*.dart" | grep -v "12\)"

📊 Migration Progress ​

Material 3 迁移进度（2026-01-18） ​

  • ✅ 按钮规范：100% 完成（24+ 处修复）
  • ✅ 对话框规范：100% 完成（检查完成）
  • ✅ 颜色规范：100% 完成（移除所有硬编码）
  • ✅ 圆角规范：100% 完成（统一12px）

总结：应用已完全符合 Material 3 设计规范！

维护者：Reading Vocab Helper Team 问题反馈：请在项目中提 Issue