样式规则

• 行长度：80 个字符或更少
• 命名约定：
  • 类使用 PascalCase
  • 成员/变量/函数/枚举使用 camelCase
  • 文件使用 snake_case
• 无尾随注释
• 对于简单的一行函数使用箭头语法

错误处理

• 预见并处理潜在错误 - 永远不要静默失败
• 使用带有适当异常类型的 try-catch 块
• 为特定代码情况使用自定义异常
• 正确使用 async/await 并配合稳健的错误处理

文档

• 为所有公共 API（类、构造函数、方法、顶级函数）添加 dartdoc 注释
• 为复杂/非显而易见的代码编写清晰的注释
• 使用 /// 作为文档注释
• 以单句摘要开头，以句号结尾
• 注释代码为何以某种方式编写，而不是它做了什么

Dart 最佳实践

类型系统与空安全

• 编写健全的空安全代码
• 利用 Dart 的空安全特性
• 避免使用 ! 操作符，除非值保证非空
• 在能简化代码的地方使用模式匹配功能
• 当定义类很繁琐时，使用记录来返回多种类型
• 优先使用穷尽的 switch 语句/表达式（不需要 break）

异步编程

• 对于单个异步操作，使用 Futures、async、await
• 对于异步事件序列，使用 Streams
• 确保异步操作中的正确错误处理

类与库组织

• 在同一库文件中定义相关的类
• 对于大型库：从单个顶级库导出较小的私有库
• 将相关库分组在同一文件夹中

Flutter 最佳实践

小部件设计

• 小部件（尤其是 StatelessWidget）是不可变的
• 当 UI 需要改变时，Flutter 会重建小部件树
• 优先组合更小的小部件，而不是扩展现有的小部件
• 使用小的、私有的 Widget 类，而不是返回小部件的私有辅助方法
• 将大型 build() 方法分解为更小、可重用的私有 Widget 类
• 尽可能使用 const 构造函数以减少重建

性能优化

• 对于长列表（懒加载）使用 ListView.builder 或 SliverList
• 使用 compute() 在单独的 isolate 中运行昂贵的计算（例如，JSON 解析）
• 避免在 build() 方法中进行昂贵的操作（网络调用、复杂计算）
• 在 build() 方法中使用 const 构造函数以最小化重建

响应式设计

• 使用 LayoutBuilder 或 MediaQuery 实现响应式 UI
• 确保跨不同屏幕尺寸的移动端响应式设计
• 在移动端和 Web 平台上进行测试

状态管理

除非明确要求第三方，否则优先使用 Flutter 的内置解决方案：

内置解决方案（按简单程度排序）

1. ValueNotifier + ValueListenableBuilder - 简单的、具有单个值的局部状态

final ValueNotifier<int> _counter = ValueNotifier<int>(0);

ValueListenableBuilder<int>(
  valueListenable: _counter,
  builder: (context, value, child) => Text('Count: $value'),
);

2. ChangeNotifier + ListenableBuilder - 跨小部件的复杂/共享状态

class CounterModel extends ChangeNotifier {
  int _count = 0;
  int get count => _count;
  void increment() {
    _count++;
    notifyListeners();
  }
}

ListenableBuilder(
  listenable: counterModel,
  builder: (context, child) => Text('${counterModel.count}'),
);

3. Streams + StreamBuilder - 异步事件序列 4. Futures + FutureBuilder - 单个异步操作

高级模式

• MVVM : 用于健壮应用程序的 Model-View-ViewModel 模式
• 依赖注入 : 使用手动构造函数注入来明确依赖关系
• Provider : 仅在明确要求用于手动注入之外的依赖注入时使用

导航

GoRouter（推荐）

使用 go_router 进行声明式导航、深度链接和 Web 支持：

// 添加依赖
flutter pub add go_router

// 配置路由器
final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) {
            final String id = state.pathParameters['id']!;
            return DetailScreen(id: id);
          },
        ),
      ],
    ),
  ],
);

// 在 MaterialApp 中使用
MaterialApp.router(routerConfig: _router);

• 为身份验证流程配置 redirect 属性
• 用于可深度链接的路由

Navigator（内置）

用于不需要深度链接的短暂屏幕（对话框、临时视图）：

Navigator.push(context, MaterialPageRoute(builder: (context) => DetailsScreen()));
Navigator.pop(context);

包管理

使用 pub 工具

• 添加依赖：flutter pub add <package_name>
• 添加开发依赖：flutter pub add dev:<package_name>
• 添加覆盖：flutter pub add override:<package_name>:1.0.0
• 移除依赖：dart pub remove <package_name>

外部包

• 在 pub.dev 上搜索合适的、稳定的包
• 建议新依赖项时解释其优势

数据处理

JSON 序列化

使用 json_serializable 和 json_annotation：

import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';

@JsonSerializable(fieldRename: FieldRename.snake)
class User {
  final String firstName;
  final String lastName;
  
  User({required this.firstName, required this.lastName});
  
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

代码生成

• 确保 build_runner 是开发依赖项
• 修改后运行：dart run build_runner build --delete-conflicting-outputs

日志记录

使用 dart:developer 进行结构化日志记录：

import 'dart:developer' as developer;

// 简单消息
developer.log('用户登录成功。');

// 结构化错误日志记录
try {
  // 代码
} catch (e, s) {
  developer.log(
    '获取数据失败',
    name: 'myapp.network',
    level: 1000, // SEVERE
    error: e,
    stackTrace: s,
  );
}

UI 与主题

Material Design 3 与 ThemeData

使用 ColorScheme.fromSeed() 获取和谐的调色板：

MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.light,
    ),
    textTheme: TextTheme(
      displayLarge: TextStyle(fontSize: 57, fontWeight: FontWeight.bold),
      bodyMedium: TextStyle(fontSize: 14, height: 1.4),
    ),
  ),
  darkTheme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.dark,
    ),
  ),
  themeMode: ThemeMode.system,
);

自定义主题扩展

用于标准 ThemeData 之外的自定义设计标记：

@immutable
class MyColors extends ThemeExtension<MyColors> {
  const MyColors({required this.success, required this.danger});
  final Color? success;
  final Color? danger;
  
  @override
  ThemeExtension<MyColors> copyWith({Color? success, Color? danger}) {
    return MyColors(success: success ?? this.success, danger: danger ?? this.danger);
  }
  
  @override
  ThemeExtension<MyColors> lerp(ThemeExtension<MyColors>? other, double t) {
    if (other is! MyColors) return this;
    return MyColors(
      success: Color.lerp(success, other.success, t),
      danger: Color.lerp(danger, other.danger, t),
    );
  }
}

// 在 ThemeData 中注册
theme: ThemeData(
  extensions: [MyColors(success: Colors.green, danger: Colors.red)],
),

// 在小部件中使用
Container(color: Theme.of(context).extension<MyColors>()!.success)

字体

使用 google_fonts 包获取自定义字体：

flutter pub add google_fonts

final TextTheme appTextTheme = TextTheme(
  displayLarge: GoogleFonts.oswald(fontSize: 57, fontWeight: FontWeight.bold),
  titleLarge: GoogleFonts.roboto(fontSize: 22, fontWeight: FontWeight.w500),
  bodyMedium: GoogleFonts.openSans(fontSize: 14),
);

图片与资源

在 pubspec.yaml 中声明：

flutter:
  uses-material-design: true
  assets:
    - assets/images/



// 本地图片
Image.asset('assets/images/placeholder.png')

// 网络图片（始终包含错误处理）
Image.network(
  'https://example.com/image.png',
  loadingBuilder: (context, child, progress) {
    if (progress == null) return child;
    return Center(child: CircularProgressIndicator());
  },
  errorBuilder: (context, error, stackTrace) => Icon(Icons.error),
)

布局最佳实践

灵活布局

• Expanded : 填充 Row/Column 中的剩余空间
• Flexible : 收缩以适应（不要与 Expanded 结合使用）
• Wrap : 溢出时自动换行
• SingleChildScrollView : 用于大于视口的固定尺寸内容
• ListView.builder/GridView.builder : 用于长列表（懒加载）
• FittedBox : 在父容器内缩放/适应单个子项
• LayoutBuilder : 基于可用空间的响应式布局

堆叠布局

• Positioned : 通过锚定到边缘来精确放置子项
• Align : 使用对齐方式定位（例如，Alignment.center）

覆盖层

使用 OverlayPortal 实现位于所有内容之上的 UI 元素：

final _controller = OverlayPortalController();

OverlayPortal(
  controller: _controller,
  overlayChildBuilder: (context) => Positioned(
    top: 50,
    left: 10,
    child: Card(child: Text('覆盖层内容')),
  ),
  child: ElevatedButton(
    onPressed: _controller.toggle,
    child: Text('切换'),
  ),
)

视觉设计原则

设计指南

• 遵循现代设计，构建美观、直观的 UI
• 确保跨屏幕尺寸（移动端和 Web）的响应性
• 提供直观的导航
• 使用排版层次结构（主标题、标题、关键词）
• 应用微妙的背景纹理以获得高级感
• 使用多层阴影增加深度感
• 结合图标以增强理解
• 交互元素具有带颜色发光效果的阴影

颜色指南

• 60-30-10 法则 : 60% 主色/中性色，30% 辅助色，10% 强调色
• 对比度比率 (WCAG 2.1)：
  • 正常文本：最低 4.5:1
  • 大文本（18pt 或 14pt 粗体）：最低 3:1
• 避免使用互补色作为文本/背景（会导致视觉疲劳）
• 谨慎使用互补色作为强调色

排版

• 限制使用 1-2 种字体系列
• 优先考虑可读性（UI 正文文本使用无衬线字体）
• 行高：字体大小的 1.4 倍 - 1.6 倍
• 行长：正文文本 45-75 个字符
• 避免在长文本中使用全大写

测试

测试类型

• 单元测试 : package:test 用于领域逻辑、数据层、状态管理
• 小部件测试 : package:flutter_test 用于 UI 组件
• 集成测试 : package:integration_test 用于端到端流程

测试最佳实践

• 遵循 Arrange-Act-Assert (Given-When-Then) 模式
• 优先使用 package:checks 以获得更具表现力的断言
• 优先使用伪造/存根而非模拟
• 如果需要模拟：使用 mockito 或 mocktail
• 力求高测试覆盖率
• 编写可测试的代码：使用 file、process、platform 包进行依赖注入

运行测试

flutter test

无障碍功能 (A11y)

• 颜色对比度 : 文本与背景的最低对比度比率为 4.5:1
• 动态文本缩放 : 使用增加的系统字体大小测试 UI
• 语义标签 : 使用 Semantics 小部件提供清晰、描述性的标签
• 屏幕阅读器测试 : 使用 TalkBack（Android）和 VoiceOver（iOS）进行测试

分析与 Linting

在 analysis_options.yaml 中包含：

include: package:flutter_lints/flutter.yaml

linter:
  rules:
    # 在此处添加额外的 lint 规则

附加资源

有关详细模式和示例，请参阅：

• references/navigation_patterns.md - 使用 GoRouter 的高级导航模式
• references/state_patterns.md - 全面的状态管理示例
• references/theme_patterns.md - 高级主题和样式模式

每周安装量

83

仓库

bogdanustyak/fl…rt-skill

首次出现

2026年1月23日

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

gemini-cli71

opencode69

codex63

cursor59

github-copilot58

claude-code57

Code Quality Standards

Styling Rules

• Line length: 80 characters or fewer
• Naming conventions:
  • PascalCase for classes
  • camelCase for members/variables/functions/enums
  • snake_case for files
• No trailing comments
• Use arrow syntax for simple one-line functions

Error Handling

• Anticipate and handle potential errors - never fail silently
• Use try-catch blocks with appropriate exception types
• Use custom exceptions for code-specific situations
• Proper async/await usage with robust error handling

Documentation

• Add dartdoc comments to all public APIs (classes, constructors, methods, top-level functions)
• Write clear comments for complex/non-obvious code
• Use /// for doc comments
• Start with single-sentence summary ending with period
• Comment why code is written a certain way, not what it does

Dart Best Practices

Type System & Null Safety

• Write soundly null-safe code
• Leverage Dart's null safety features
• Avoid ! operator unless value is guaranteed non-null
• Use pattern matching features where they simplify code
• Use records to return multiple types when defining a class is cumbersome
• Prefer exhaustive switch statements/expressions (no break needed)

Async Programming

• Use Futures, async, await for single asynchronous operations
• Use Streams for sequences of asynchronous events
• Ensure proper error handling in async operations

Class & Library Organization

• Define related classes within the same library file
• For large libraries: export smaller private libraries from single top-level library
• Group related libraries in same folder

Flutter Best Practices

Widget Design

• Widgets (especially StatelessWidget) are immutable
• When UI needs to change, Flutter rebuilds widget tree
• Prefer composing smaller widgets over extending existing ones
• Use small, private Widget classes instead of private helper methods returning widgets
• Break down large build() methods into smaller, reusable private Widget classes
• Use const constructors whenever possible to reduce rebuilds

Performance Optimization

• Use ListView.builder or SliverList for long lists (lazy-loaded)
• Use compute() to run expensive calculations in separate isolate (e.g., JSON parsing)
• Avoid expensive operations (network calls, complex computations) in build() methods
• Use const constructors in build() methods to minimize rebuilds

Responsive Design

• Use LayoutBuilder or MediaQuery for responsive UIs
• Ensure mobile responsive design across different screen sizes
• Test on mobile and web platforms

State Management

Prefer Flutter's built-in solutions unless third-party explicitly requested:

Built-in Solutions (in order of simplicity)

1. ValueNotifier + ValueListenableBuilder - Simple, local state with single value

final ValueNotifier<int> _counter = ValueNotifier<int>(0);

ValueListenableBuilder<int>(
  valueListenable: _counter,
  builder: (context, value, child) => Text('Count: $value'),
);

2. ChangeNotifier + ListenableBuilder - Complex/shared state across widgets

class CounterModel extends ChangeNotifier {
  int _count = 0;
  int get count => _count;
  void increment() {
    _count++;
    notifyListeners();
  }
}

ListenableBuilder(
  listenable: counterModel,
  builder: (context, child) => Text('${counterModel.count}'),
);

3. Streams + StreamBuilder - Sequences of asynchronous events 4. Futures + FutureBuilder - Single async operations

Advanced Patterns

• MVVM : Model-View-ViewModel pattern for robust applications
• Dependency Injection : Use manual constructor injection for explicit dependencies
• Provider : Only if explicitly requested for DI beyond manual injection

Navigation

GoRouter (Recommended)

Use go_router for declarative navigation, deep linking, and web support:

// Add dependency
flutter pub add go_router

// Configure router
final GoRouter _router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'details/:id',
          builder: (context, state) {
            final String id = state.pathParameters['id']!;
            return DetailScreen(id: id);
          },
        ),
      ],
    ),
  ],
);

// Use in MaterialApp
MaterialApp.router(routerConfig: _router);

• Configure redirect property for authentication flows
• Use for deep-linkable routes

Navigator (Built-in)

Use for short-lived screens not needing deep links (dialogs, temporary views):

Navigator.push(context, MaterialPageRoute(builder: (context) => DetailsScreen()));
Navigator.pop(context);

Package Management

Using pub Tool

• Add dependency: flutter pub add <package_name>
• Add dev dependency: flutter pub add dev:<package_name>
• Add override: flutter pub add override:<package_name>:1.0.0
• Remove dependency: dart pub remove <package_name>

External Packages

• Search pub.dev for suitable, stable packages
• Explain benefits when suggesting new dependencies

Data Handling

JSON Serialization

Use json_serializable and json_annotation:

import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';

@JsonSerializable(fieldRename: FieldRename.snake)
class User {
  final String firstName;
  final String lastName;
  
  User({required this.firstName, required this.lastName});
  
  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
  Map<String, dynamic> toJson() => _$UserToJson(this);
}

Code Generation

• Ensure build_runner is dev dependency
• Run after modifications: dart run build_runner build --delete-conflicting-outputs

Logging

Use dart:developer for structured logging:

import 'dart:developer' as developer;

// Simple messages
developer.log('User logged in successfully.');

// Structured error logging
try {
  // code
} catch (e, s) {
  developer.log(
    'Failed to fetch data',
    name: 'myapp.network',
    level: 1000, // SEVERE
    error: e,
    stackTrace: s,
  );
}

UI & Theming

Material Design 3 & ThemeData

Use ColorScheme.fromSeed() for harmonious palettes:

MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.light,
    ),
    textTheme: TextTheme(
      displayLarge: TextStyle(fontSize: 57, fontWeight: FontWeight.bold),
      bodyMedium: TextStyle(fontSize: 14, height: 1.4),
    ),
  ),
  darkTheme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.deepPurple,
      brightness: Brightness.dark,
    ),
  ),
  themeMode: ThemeMode.system,
);

Custom Theme Extensions

For custom design tokens beyond standard ThemeData:

@immutable
class MyColors extends ThemeExtension<MyColors> {
  const MyColors({required this.success, required this.danger});
  final Color? success;
  final Color? danger;
  
  @override
  ThemeExtension<MyColors> copyWith({Color? success, Color? danger}) {
    return MyColors(success: success ?? this.success, danger: danger ?? this.danger);
  }
  
  @override
  ThemeExtension<MyColors> lerp(ThemeExtension<MyColors>? other, double t) {
    if (other is! MyColors) return this;
    return MyColors(
      success: Color.lerp(success, other.success, t),
      danger: Color.lerp(danger, other.danger, t),
    );
  }
}

// Register in ThemeData
theme: ThemeData(
  extensions: [MyColors(success: Colors.green, danger: Colors.red)],
),

// Use in widgets
Container(color: Theme.of(context).extension<MyColors>()!.success)

Fonts

Use google_fonts package for custom fonts:

flutter pub add google_fonts

final TextTheme appTextTheme = TextTheme(
  displayLarge: GoogleFonts.oswald(fontSize: 57, fontWeight: FontWeight.bold),
  titleLarge: GoogleFonts.roboto(fontSize: 22, fontWeight: FontWeight.w500),
  bodyMedium: GoogleFonts.openSans(fontSize: 14),
);

Images & Assets

Declare in pubspec.yaml:

flutter:
  uses-material-design: true
  assets:
    - assets/images/



// Local images
Image.asset('assets/images/placeholder.png')

// Network images (always include error handling)
Image.network(
  'https://example.com/image.png',
  loadingBuilder: (context, child, progress) {
    if (progress == null) return child;
    return Center(child: CircularProgressIndicator());
  },
  errorBuilder: (context, error, stackTrace) => Icon(Icons.error),
)

Layout Best Practices

Flexible Layouts

• Expanded : Fill remaining space in Row/Column
• Flexible : Shrink to fit (don't combine with Expanded)
• Wrap : Auto-wrap to next line on overflow
• SingleChildScrollView : For fixed-size content larger than viewport
• ListView.builder/GridView.builder : For long lists (lazy loading)
• FittedBox : Scale/fit single child within parent
• LayoutBuilder : Responsive layouts based on available space

Stack Layouts

• Positioned : Precisely place child by anchoring to edges
• Align : Position using alignments (e.g., Alignment.center)

Overlays

Use OverlayPortal for UI elements on top of everything:

final _controller = OverlayPortalController();

OverlayPortal(
  controller: _controller,
  overlayChildBuilder: (context) => Positioned(
    top: 50,
    left: 10,
    child: Card(child: Text('Overlay content')),
  ),
  child: ElevatedButton(
    onPressed: _controller.toggle,
    child: Text('Toggle'),
  ),
)

Visual Design Principles

Design Guidelines

• Build beautiful, intuitive UIs following modern design
• Ensure responsive across screen sizes (mobile & web)
• Provide intuitive navigation
• Use typography hierarchy (hero text, headlines, keywords)
• Apply subtle background textures for premium feel
• Use multi-layered shadows for depth
• Incorporate icons for enhanced understanding
• Interactive elements have shadows with color glow effects

Color Guidelines

• 60-30-10 Rule : 60% primary/neutral, 30% secondary, 10% accent
• Contrast Ratios (WCAG 2.1):
  • Normal text: 4.5:1 minimum
  • Large text (18pt or 14pt bold): 3:1 minimum
• Avoid complementary colors for text/background (causes eye strain)
• Use complementary colors sparingly for accents

Typography

• Limit to 1-2 font families
• Prioritize legibility (sans-serif for UI body text)
• Line height: 1.4x-1.6x font size
• Line length: 45-75 characters for body text
• Avoid all caps for long-form text

Testing

Test Types

• Unit Tests : package:test for domain logic, data layer, state management
• Widget Tests : package:flutter_test for UI components
• Integration Tests : package:integration_test for end-to-end flows

Testing Best Practices

• Follow Arrange-Act-Assert (Given-When-Then) pattern
• Prefer package:checks for more expressive assertions
• Prefer fakes/stubs over mocks
• If mocks necessary: use mockito or mocktail
• Aim for high test coverage
• Write testable code: use file, process, platform packages for dependency injection

Running Tests

flutter test

Accessibility (A11y)

• Color Contrast : Text minimum 4.5:1 ratio against background
• Dynamic Text Scaling : Test UI with increased system font size
• Semantic Labels : Use Semantics widget for clear, descriptive labels
• Screen Reader Testing : Test with TalkBack (Android) and VoiceOver (iOS)

Analysis & Linting

Include in analysis_options.yaml:

include: package:flutter_lints/flutter.yaml

linter:
  rules:
    # Add additional lint rules here

Additional Resources

For detailed patterns and examples, see:

• references/navigation_patterns.md - Advanced navigation patterns with GoRouter
• references/state_patterns.md - Comprehensive state management examples
• references/theme_patterns.md - Advanced theming and styling patterns

Weekly Installs

83

Repository

bogdanustyak/fl…rt-skill

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

gemini-cli71

opencode69

codex63

cursor59

github-copilot58

claude-code57