# flutter_fast_kit

**Repository Path**: AriesHoo/flutter_fast_kit

## Basic Information

- **Project Name**: flutter_fast_kit
- **Description**: Flutter 快速开发组件--自用
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flutter_fast_kit

Flutter 快速开发工具库：应用初始化、Dio 封装（拦截器可外挂）、Provider 状态切换、四态占位与分页列表。

**要求 Flutter SDK ≥ 3.35（Dart ≥ 3.8）。**

## 规范落点

| 文件 | 作用 |
| --- | --- |
| `analysis_options.yaml` | Effective Dart / flutter_lints、命名与分包、公开 API 文档 |
| `.cursor/rules/flutter-conventions.mdc` | Agent 与协作者的命名、分包、注释、配置合并优先级 |

实现全部在 `lib/src/`，外部只 `import 'package:flutter_fast_kit/flutter_fast_kit.dart'`。

## 配置优先级

对齐 Flutter `Theme` / `ThemeData`：

1. 组件局部参数  
2. 子树 `FastKitTheme`  
3. `FastKit.ensureInitialized(FastKitConfig(...))`  
4. 内置 `defaults`

## 初始化

```dart
Future<void> main() async {
  await FastKit.ensureInitialized(
    FastKitConfig(
      http: FastHttpConfig(
        baseUrl: 'https://api.example.com',
        interceptors: [LogInterceptor()],
      ),
      theme: FastKitThemeData(
        enableRetryOnEmpty: true,
        enableRetryOnError: true,
      ),
    ),
  );

  FastHttp.instance.interceptors.add(InterceptorsWrapper(
    onRequest: (options, handler) {
      options.headers['Authorization'] = 'Bearer xxx';
      handler.next(options);
    },
  ));

  runApp(
    FastApp(
      child: MaterialApp(
        // navigatorKey 留给 go_router / 业务自己用
        home: HomePage(),
      ),
    ),
  );
}
```

## 网络

```dart
final res = await FastHttp.instance.get<Map<String, dynamic>>(
  '/users',
  options: FastHttpRequestOptions(
    headers: {'X-Local': '1'},
    receiveTimeout: Duration(seconds: 8),
  ),
  decoder: (data) => Map<String, dynamic>.from(data as Map),
);

// 局部独立客户端，不污染全局
final upload = FastHttp.instance.withConfig(
  FastHttpConfig(baseUrl: 'https://upload.example.com'),
);

// 全局 Loading（默认关闭）
FastHttpConfig(
  loading: FastLoadingConfig(
    enabled: true,
    cancelOnDismiss: false,
    barrierDismissible: true,
    message: '请稍候',
  ),
);

// 单次覆盖：关 Loading / 换样式 / 关闭后取消请求
FastHttp.instance.get(
  '/users',
  options: FastHttpRequestOptions(
    loading: FastLoadingConfig(
      enabled: true,
      cancelOnDismiss: true,
      builder: (context) => const FastDefaultHttpLoading(message: '保存中'),
    ),
  ),
);
```

Loading 由 `FastApp` 内的 `FastLoadingHost` 绘制，**不必**设置 `MaterialApp.navigatorKey`。该 key 可留给 go_router 等。不用 FastApp 时自行包一层 `FastLoadingHost`。

## 多状态

```dart
ChangeNotifierProvider(
  create: (_) => FastLoadStateController(task: () async {
    await api.load();
    return LoadState.success;
  })..load(),
  child: FastLoadStateView(
    enableRetryOnError: true, // 调用端控制是否重试
    enableRetryOnEmpty: false,
    child: ContentView(),
  ),
);
```

## 分页列表

```dart
ChangeNotifierProvider(
  create: (_) => FastLoadListController<User>(
    fetchPage: (page, pageSize) => api.users(page, pageSize),
  )..refresh(),
  child: FastLoadListView<User>(
    enableRefresh: true,
    enableLoadMore: true,
    itemBuilder: (context, user, index) => UserTile(user),
  ),
);
```

更多可运行代码见 `example/`，已包含 Android、iOS、Web、Windows、Linux、macOS 工程。