Flutter 项目命名规范 提升开发效率
一份完整的 Flutter 项目命名规范文档（包含文件、类名、控件、资源、方法等），再配上 示例文档。
📖 Flutter 项目命名规范文档
总体原则：由大到小
命名遵循 “由大到小” 的规则，从大范围到小范围依次命名，保证统一性和层级感。
- 项目级：全局通用前缀（如
App/Global） - 模块级：功能域（如
Video/User/Comment） - 类级：控件 / 业务逻辑类（如
VideoPlayerWidget/UserProfileModel） - 方法级：行为动作（如
buildCommentItem/fetchUserData） - 变量级：具体对象或状态（如
videoController/userList） - 资源级：图片 / 字体 / json 等（如
ic_video_play.png/img_user_avatar.png）
一、目录 & 文件命名
- 全部小写，单词以下划线分隔（snake_case）
- 按业务模块建立文件夹
✅ 正确：
lib/├── pages/│ ├── short_video/│ │ ├── short_video_page.dart│ │ ├── short_video_controller.dart│ │ └── short_video_widget.dart│ └── user_profile/│ ├── user_profile_page.dart│ └── user_profile_controller.dart
❌ 错误：
ShortVideoPage.dart
UserprofilePage.dart
二、类命名
- 类、枚举、扩展：大驼峰 (PascalCase)
- Widget 类以
Widget结尾 - 页面类以
Page结尾 - 控制器类以
Controller结尾 - 工具类以
Utils或Helper结尾
✅ 正确：
class ShortVideoPage extends StatefulWidget {}class CommentListWidget extends StatelessWidget {}class VideoPlayerController {}class StringUtils {}
三、方法与变量命名
- 方法 / 函数 / 变量：小驼峰 (camelCase)
- 私有变量：加
_前缀 - 常量：全大写 + 下划线
✅ 正确：
final int videoCount = 0;
final String videoTitle = "标题";const int MAX_VIDEO_COUNT = 99;void loadVideoList() {}
void _fetchUserData() {}
四、资源命名（图片 / 图标）
🔑 命名规则
[前缀]_[业务模块/对象]_[状态/尺寸]
🖼 图片资源命名前缀规范（Flutter 项目）
| 前缀 | 含义 | 示例 |
|---|---|---|
ic_ | icon 图标（功能、按钮、Tab 等） | ic_home_normal.png, ic_video_play.png |
bg_ | 背景图（页面、弹窗、模块背景） | bg_login.png, bg_profile_header.jpg |
btn_ | 按钮图（有状态的按钮资源） | btn_submit_normal.png, btn_play_pressed.png |
img_ | 普通图片（插画、展示图、banner） | img_banner_spring.png, img_empty_state.png |
avatar_ | 头像（用户头像、默认头像） | avatar_user_default.png |
logo_ | Logo（App/品牌 logo） | logo_app.png, logo_company.png |
divider_ | 分割线/装饰线 | divider_horizontal.png, divider_vertical.png |
placeholder_ | 占位图（加载中、空数据、错误） | placeholder_article.png, placeholder_avatar.png |
anim_ | 动效/动画文件（Lottie/json/svg） | anim_loading.json, anim_success.json |
flag_ | 国旗/标志图 | flag_china.png, flag_usa.png |
tab_ | Tab 图标（专用场景，可选） | tab_home_selected.png, tab_user_normal.png |
badge_ | 角标/小红点 | badge_vip.png, badge_new.png |
iconfont_ | 字体图标资源（如果用 iconfont） | iconfont_music.ttf |
- 前缀：见上表
- 业务模块/对象：如
home、video、user - 状态：
normal、selected、disabled、pressed、active… - 尺寸（可选）：
small、large、2x、3x
📌 示例
- 首页 Tab 图标（默认）：
ic_home_normal.png - 首页 Tab 图标（选中）：
ic_home_selected.png - 视频播放按钮（按下）：
btn_play_pressed.png - 登录页顶部背景图：
bg_login_top.jpg - 用户默认头像：
avatar_user_default.png - 活动横幅（春季）：
img_banner_spring.png - 加载动画：
anim_loading.json - 分割线：
divider_horizontal.png - 占位图：
placeholder_article.png
五、控件命名
- 局部方法构建控件 →
buildXxxWidget - 通用复用 Widget →
XxxWidget类单独抽取
✅ 示例：
Widget buildVideoDescriptionWidget(String title, String desc, List<String> tags) {return Column(crossAxisAlignment: CrossAxisAlignment.start,children: [Text(title, style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold)),SizedBox(height: 8),Text(desc, maxLines: 2, overflow: TextOverflow.ellipsis),Wrap(spacing: 6,children: tags.map((e) => Chip(label: Text(e))).toList(),)],);
}
六、🎯 图片/控件状态命名表
| 英文 | 中文 | 用途示例 |
|---|---|---|
| normal | 正常 | 默认状态，例如按钮默认图标 |
| selected | 选中 | 收藏、Tab 选中 |
| disabled | 禁用 | 按钮不可点击 |
| pressed | 按下 | 点击时的状态 |
| hover | 悬停 | Web/桌面鼠标移入 |
| focused | 聚焦 | 输入框/可聚焦控件 |
| active | 激活 | 正在使用的功能（如麦克风开关） |
| inactive | 非激活 | 功能关闭/未启用 |
| checked | 已勾选 | 复选框/开关选中 |
| unchecked | 未勾选 | 复选框/开关未选 |
| expanded | 展开 | 折叠面板展开状态 |
| collapsed | 收起 | 折叠面板收起状态 |
| success | 成功 | 请求成功提示 |
| error | 错误 | 失败状态，加载失败图 |
| warning | 警告 | 风险/异常提醒 |
| info | 信息 | 普通提示状态 |
| loading | 加载中 | 请求、异步任务进行中 |
| empty | 空状态 | 列表无数据时 |
| placeholder | 占位 | 加载前的占位图 |
| highlight | 高亮 | 强调/提示某元素 |
| hidden | 隐藏 | 不可见但保留占位 |
👉 这样整理下来，你的 Flutter 项目在团队协作里会非常清晰、统一。