颤振块设置
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Bootstrapping Bloc in a Flutter Project
Installs and wires the canonical Bloc stack so feature-level skills (`flutter-bloc-feature-pattern`, `flutter-bloc-async-api`, `flutter-bloc-stream-tracking`, `flutter-bloc-testing`, `flutter-bloc-forms`) plug into a project with no further setup. Mobile only — Android and iOS targets. Web and desktop are out of scope.
## Contents
- [Dependencies and generators](#dependencies-and-generators)
- [App-level providers](#app-level-providers)
- [Project structure](#project-structure)
- [Workflow: Bootstrap a Bloc-ready project](#workflow-bootstrap-a-bloc-ready-project)
- [Applied to Talabat-clone](#applied-to-talabat-clone)
- [Examples](#examples)
## Dependencies and generators
Add the runtime dependencies. Pin major versions explicitly so `dart run build_runner` does not break across upgrades.
```bash
flutter pub add flutter_bloc freezed_annotation json_annotation bloc_concurrency hydrated_bloc path_provider
```
Add the generators as `dev_dependencies`. `build_runner` drives both `freezed` and `json_serializable`.
```bash
flutter pub add --dev build_runner freezed json_serializable
```
Run the generator continuously while editing `freezed`-annotated files in a side terminal. This avoids stale `*.freezed.dart` and `*.g.dart` artifacts during development.
```bash
dart run build_runner watch -d
```
This skill does **not** duplicate HTTP setup. Android `<uses-permission android:name="android.permission.INTERNET" />` and the iOS `com.apple.security.network.client` entitlement live in `flutter-use-http-package`. Run that skill once for the project before adding any feature that calls a backend.
## App-level providers
Two app-wide objects belong at the root of the widget tree.
1. **`MultiRepositoryProvider`** — exposes data-layer repositories to every feature below. Start with `const <RepositoryProvider>[]` (typed, not bare `const []`, which trips `strict-inference` lints); `flutter-bloc-async-api` adds repositories to this list as features land. Each repository entry looks like:
```dart
RepositoryProvider<AuthRepository>(
create: (_) => AuthRepository(api: AuthApiClient(...)),
lazy: true, // construct only on first read
),
```
2. **`AppBlocObserver`** — a global `BlocObserver` that logs every Bloc transition and error to the console in debug mode. It dramatically shortens the loop when a state machine misbehaves. Gate it on `kDebugMode` so production builds stay quiet.
`HydratedBloc.storage` must be initialized **before** `runApp()`; otherwise any `HydratedBloc` constructed during the first frame will crash with `HydratedStorageNotFound`. Use `path_provider` to resolve the storage directory on Android and iOS.
Use `getApplicationDocumentsDirectory()` (durable across app updates and OS reboots), **not** `getTemporaryDirectory()` — the latter can be cleared by the OS without warning, which would silently lose the user's cart on a low-storage device. Some upstream examples use the temp directory because it's faster for one-off demos; for a real app with persisted cart/auth state, the documents directory is the right choice.
## Project structure
Bloc replaces the `view_models/` directory from `flutter-apply-architecture-best-practices`. The Repository, Service, and Domain Model layers from that skill stay unchanged.
```
lib/
├── core/
│ ├── bloc/
│ │ └── app_bloc_observer.dart
│ └── result/
│ ├── failure.dart # added by flutter-bloc-async-api
│ └── result.dart # added by flutter-bloc-async-api
├── data/ # unchanged from flutter-apply-architecture-best-practices
│ ├── models/ # API DTOs
│ ├── repositories/ # consumed by Blocs via RepositoryProvider
│ └── services/
├── domain/ # unchanged
│ └── models/
└── ui/
└── features/
└── <feature>/
├── bloc/
│ ├── <feature>_bloc.dart
│ ├── <feature>_event.dart
│ └── <feature>_state.dart
└── view/
└── <feature>_view.dart
```
One folder per feature, three files per Bloc. Tests for each Bloc mirror the path under `test/ui/features/<feature>/bloc/<feature>_bloc_test.dart`.
## Workflow: Bootstrap a Bloc-ready project
### Task Progress
- [ ] **Step 1 — Install runtime deps.** `flutter pub add flutter_bloc freezed_annotation json_annotation bloc_concurrency hydrated_bloc path_provider`.
- [ ] **Step 2 — Install generators.** `flutter pub add --dev build_runner freezed json_serializable`.
- [ ] **Step 3 — Create the observer.** Write `lib/core/bloc/app_bloc_observer.dart` extending `BlocObserver`. Override `onChange` and `onError`.
- [ ] **Step 4 — Initialize storage.** In `main()`, call `WidgetsFlutterBinding.ensureInitialized()` then `HydratedBloc.storage = await HydratedStorage.build(storageDirectory: HydratedStorageDirectory((await getApplicationDocumentsDirectory()).path))` **before** `runApp()`.
- [ ] **Step 5 — Wire the observer.** `if (kDebugMode) Bloc.observer = const AppBlocObserver();` — only in debug builds, so production stays quiet.
- [ ] **Step 6 — Wrap the app root.** Replace your top-level widget with `MultiRepositoryProvider(providers: const <RepositoryProvider>[], child: MaterialApp(...))`. The `providers` list grows as features land.
- [ ] **Step 7 — Create the feature directory.** `mkdir -p lib/ui/features lib/core/bloc`.
- [ ] **Step 8 — Run the generator.** Open a side terminal: `dart run build_runner watch -d`. Leave it running while you work.
**Troubleshooting.** Run `flutter analyze` → if `dart run build_runner` errors, check that every freezed file imports `package:freezed_annotation/freezed_annotation.dart` and declares `part '<file>.freezed.dart';` → re-run. If `HydratedStorageNotFound` is thrown on first launch, your `HydratedBloc.storage` initialization happens after `runApp()` — move it before in `main()`.
## Applied to Talabat-clone
For a multi-store delivery app, the Blocs the family will eventually scaffold are (cross-referenced against `PRD_states.md`):
| Bloc | Persists? | Why |
|---|---|---|
| `AuthBloc` | yes (`HydratedBloc`) | Auth token + the user's `User: active` lifecycle state are both worth persisting across cold start; see `PRD_states.md §14` for the user-account state machine and `prd.md` for the auth/session flow. |
| `CartBloc` | yes (`HydratedBloc`) | One-cart / one-store / one-city rules; cart survives restart (`PRD_states.md §7`, `PRD_catalog.md §15.5`). |
| `StoreListBloc` | no | Re-fetch on launch; depends on location and operational gating (`PRD_states.md §4`). |
| `StoreDetailBloc` | no | Per-route, ephemeral. |
| `OrderBloc` | no | Authoritative source is the API. |
| `OrderTrackingBloc` | no | Stream-driven, scoped to an Order's `picked_up → delivered` window (deferred to `flutter-bloc-stream-tracking`). |
| `PromotionBloc` | no | Validity is computed from `start_date` / `end_date` / `is_paused` (`PRD_states.md §9` Promotion/Offer; siblings §8 Coupon and §10 Advertisement share the shape with minor variations). |
The root `MultiRepositoryProvider` will hold `AuthRepository`, `StoreRepository`, `OrderRepository`, `CartRepository` (cart is local-only; the repository wraps `hydrated_bloc` storage), and `PromotionRepository`.
## Examples
### Minimal `main.dart`
```dart
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:hydrated_bloc/hydrated_bloc.dart';
import 'package:path_provider/path_provider.dart';
import 'core/bloc/app_bloc_observer.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
HydratedBloc.storage = await HydratedStorage.build(
storageDirectory: HydratedStorageDirectory(
(await getApplicationDocumentsDirectory()).path,
),
);
if (kDebugMode) {
Bloc.observer = const AppBlocObserver();
}
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MultiRepositoryProvider(
// Typed empty list — `const []` bare would fail `strict-inference`.
providers: const <RepositoryProvider>[
// Repositories are added here by flutter-bloc-async-api as features land.
// Example:
// RepositoryProvider<AuthRepository>(
// create: (_) => AuthRepository(...),
// lazy: true,
// ),
],
child: MaterialApp(
title: 'Multi-Store Delivery',
home: Scaffold(
appBar: AppBar(title: const Text('Smoke test')),
body: const Center(child: Text('Bloc setup OK')),
),
),
);
}
}
```
### `lib/core/bloc/app_bloc_observer.dart`
```dart
import 'package:flutter/foundation.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
/// Logs every Bloc transition and error during development.
/// Wired in `main()` only when `kDebugMode` is true.
class AppBlocObserver extends BlocObserver {
const AppBlocObserver();
// Override `onTransition` (not `onChange`) so Bloc logs show the
// `event + currentState → nextState` triple. `onChange` only sees the
// state diff, which loses the event-causation half. Cubits (no events)
// fall through to `onChange` automatically.
@override
void onTransition(
Bloc<dynamic, dynamic> bloc,
Transition<dynamic, dynamic> transition,
) {
super.onTransition(bloc, transition);
debugPrint('[${bloc.runtimeType}] $transition');
}
@override
void onError(BlocBase<dynamic> bloc, Object error, StackTrace stackTrace) {
debugPrint('[${bloc.runtimeType}] ERROR: $error');
super.onError(bloc, error, stackTrace);
}
}
```
### `pubspec.yaml` excerpt
```yaml
dependencies:
flutter:
sdk: flutter
flutter_bloc: ^9.0.0
freezed_annotation: ^3.0.0
json_annotation: ^4.9.0
bloc_concurrency: ^0.3.0
hydrated_bloc: ^10.0.0
path_provider: ^2.1.0
http: ^1.2.0
dev_dependencies:
flutter_test:
sdk: flutter
build_runner: ^2.4.0
freezed: ^3.0.0
json_serializable: ^6.8.0
```
---
> Source: [abdallhMoukdad/flutter-bloc-skills](https://github.com/abdallhMoukdad/flutter-bloc-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
内容
依赖项和生成器
应用程序级提供商
项目结构
任务进度
文件/命令 -> flutter-bloc-feature-pattern · flutter-bloc-async-api · flutter-bloc-stream-tracking · flutter-bloc-testing · flutter-bloc-forms · dart run build_runner · dev_dependencies · build_runner
内容校验值 -> 2d469117dfdd
当前原文的自动摘译,尚未人工审校。
内容
依赖项和生成器 应用程序级提供程序 项目结构 工作流程:引导 Bloc 就绪项目 应用于 Talabat 克隆
依赖项和生成器
添加运行时依赖项。 明确固定主要版本,以便
dart run build_runner不会因升级而中断。应用程序级提供商
两个应用程序范围的对象属于小部件树的根。
MultiRepositoryProvider- 将数据层存储库公开给以下每个功能。从const <RepositoryProvider>[]开始(键入,而不是裸露的const [],它会导致strict-inference掉毛);flutter-bloc-async-api将存储库添加到此列表中作为功能落地。每个存储库条目如下所示:AppBlocObserver— 一个全局BlocObserver,在调试模式下将每个 Bloc 转换和错误记录到控制台。当状态机出现故障时,它会极大地缩短循环。将其设置为kDebugMode,以便生产构建保持安静。项目结构
Bloc 替换了
flutter-apply-architecture-best-practices中的view_models/目录。该技能的存储库、服务和域模型层保持不变。每个功能一个文件夹,每个块三个文件。每个 Bloc 的测试都会镜像test/ui/features/<feature>/bloc/<feature>_bloc_test.dart下的路径。任务进度
[ ] 第 1 步 — 安装运行时依赖项。
flutter pub add flutter_bloc freezed_annotation json_annotation bloc_concurrency hydrated_bloc path_provider。 [ ] 步骤 2 — 安装发电机。flutter pub add --dev build_runner freezed json_serializable。 [ ] 步骤 3 — 创建观察者。写出lib/core/bloc/app_bloc_observer.dart扩展BlocObserver。覆盖onChange和onError。 [ ] 步骤 4 — 初始化存储。在main()中,先调用WidgetsFlutterBinding.ensureInitialized(),然后调用HydratedBloc.storage = await HydratedStorage.build(storageDirectory: HydratedStorageDirectory((await getApplicationDocumentsDirectory()).path)),再调用runApp()。