块特征模式

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

内容

事件/状态/块三重奏 具有冻结事件处理程序和并发性的密封状态 连接视图持久性(可选)

事件/州/集团三人组

每个功能在lib/ui/features/<feature>/bloc/下都有三个文件。文件·责任·包含<feature>_event.dart·用户意图和副作用触发器。纯数据。 · 密封的<Feature>Event类,每个意图都有一个变体。 <feature>_state.dart · 不可变的 UI 快照。纯数据。 · 密封的<Feature>State类,每种渲染模式都有一个变体。 <feature>_bloc.dart · 将事件映射到状态。唯一调用存储库的地方。 · class <Feature>Bloc extends Bloc<<Feature>Event, <Feature>State>(或HydratedBloc,如果坚持的话)。

冷冻密封状态

将 @freezed 与 sealed 类一起使用,因此状态变体上的 switch 在编译时是详尽的。忘记处理变体会成为编译错误,而不是运行时 UI 错误。视图使用 Dart 3 模式switch 消耗密封状态:如果未来的 PR 添加CartLoaded.suspended变体,则代码库中的每个switch在处理之前都无法编译。这就是重点。

事件处理程序和并发性

bloc_concurrency提供四个EventTransformer。选择与事件语义相匹配的选项,而不是“感觉安全”的选项。 Transformer · 使用时间 · 示例事件droppable() · 提交一次。当飞行时忽略进一步的点击。 · OrderPlaced、PaymentSubmitted restartable() · 仅限最新内容。当新事件到达时取消正在进行的处理程序。 · SearchQueryChanged,RefreshRequested

连接视图

四个小部件将 Bloc 桥接至小部件树。选择最窄的一个来完成这项工作。小部件 · 目的 · 重建? BlocProvider · 将一个 Bloc 注入到子树中。放置在路线上,而不是应用程序根目录下。 · n/a BlocBuilder<B, S> · 在每次状态更改时重建。默认。 · 是的,在每个状态BlocSelector<B, S, T> · 仅当派生值T更改时才重建。用于细粒度更新。 · 是的,仅当选择器输出改变时

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
中等消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Scaffolding a Bloc Feature

Defines the canonical shape of a Bloc-driven feature: three files (`<feature>_event.dart`, `<feature>_state.dart`, `<feature>_bloc.dart`), sealed states with `freezed`, and an explicit `EventTransformer` per handler. Every other skill in the family (`flutter-bloc-async-api`, `flutter-bloc-stream-tracking`, `flutter-bloc-testing`, `flutter-bloc-forms`) builds on this shape. Prerequisite: `flutter-bloc-setup`.

## Contents
- [The Event/State/Bloc trio](#the-eventstatebloc-trio)
- [Sealed states with freezed](#sealed-states-with-freezed)
- [Event handlers and concurrency](#event-handlers-and-concurrency)
- [Wiring the View](#wiring-the-view)
- [Persistence (optional)](#persistence-optional)
- [Workflow: Scaffold a new feature](#workflow-scaffold-a-new-feature)
- [Applied to Talabat-clone](#applied-to-talabat-clone)
- [Examples](#examples)

## The Event/State/Bloc trio

Every feature has exactly three files under `lib/ui/features/<feature>/bloc/`.

| File | Responsibility | Contains |
|---|---|---|
| `<feature>_event.dart` | User intent and side-effect triggers. Plain data. | Sealed `<Feature>Event` class with one variant per intent. |
| `<feature>_state.dart` | Immutable UI snapshots. Plain data. | Sealed `<Feature>State` class with one variant per render mode. |
| `<feature>_bloc.dart` | Maps events to states. The only place that calls repositories. | `class <Feature>Bloc extends Bloc<<Feature>Event, <Feature>State>` (or `HydratedBloc` if persisting). |

Events and states are **never** mutable. The Bloc constructor registers handlers via `on<Event>(handler, transformer: ...)` and emits new state instances. Views observe state and dispatch events; they never read fields off the Bloc directly.

## Sealed states with freezed

Use `@freezed` with a `sealed` class so a `switch` over state variants is **exhaustive at compile time**. Forgetting to handle a variant becomes a compile error rather than a runtime UI bug.

```dart
// lib/ui/features/cart/bloc/cart_state.dart
import 'package:freezed_annotation/freezed_annotation.dart';
import 'package:my_app/domain/models/cart_item.dart';
import 'package:my_app/domain/models/money.dart';

part 'cart_state.freezed.dart';
part 'cart_state.g.dart'; // required when the state is also `HydratedBloc`-persisted

@Freezed(unionKey: 'type') // stable discriminator key across class renames
sealed class CartState with _$CartState {
  const factory CartState.initial() = CartInitial;
  const factory CartState.loading() = CartLoading;
  const factory CartState.loaded({
    required List<CartItem> items,
    required Money subtotal,
    required Money total,
  }) = CartLoaded;
  const factory CartState.failure({required String message}) = CartFailure;

  // Required for `HydratedBloc` round-trip — `fromJson` is **not** generated
  // automatically; you must declare this factory yourself. `CartItem` and
  // `Money` must each be JSON-serializable (typically also `@freezed` classes).
  factory CartState.fromJson(Map<String, dynamic> json) =>
      _$CartStateFromJson(json);
}
```

The View consumes the sealed state with a Dart 3 pattern `switch`:

```dart
final widget = switch (state) {
  CartInitial()    => const _EmptyCart(),
  CartLoading()    => const Center(child: CircularProgressIndicator()),
  CartLoaded(:final items, :final total) => _CartList(items: items, total: total),
  CartFailure(:final message)            => _ErrorBanner(message: message),
};
```

If a future PR adds a `CartLoaded.suspended` variant, every `switch` in the codebase fails to compile until handled. That is the point.

## Event handlers and concurrency

`bloc_concurrency` provides four `EventTransformer`s. Pick the one that matches the **semantic** of the event, not the one that "feels safe".

| Transformer | Use when | Example event |
|---|---|---|
| `droppable()` | Submit-once. Ignore further taps while one is in flight. | `OrderPlaced`, `PaymentSubmitted` |
| `restartable()` | Only the latest matters. Cancel the in-flight handler when a new event arrives. | `SearchQueryChanged`, `RefreshRequested` |
| `sequential()` | Order matters. Run handlers one at a time, FIFO. | `CartItemAdded`, `CartItemQtyChanged` |
| `concurrent()` (default) | Independent fetches. Run in parallel. | `ProductDetailsLoaded`, `ReviewsLoaded` |

```dart
class CartBloc extends HydratedBloc<CartEvent, CartState> {
  CartBloc({required CartRepository repo})
      : _repo = repo,
        super(const CartState.initial()) {
    on<CartItemAdded>(_onItemAdded, transformer: sequential());
    on<CartItemQtyChanged>(_onQtyChanged, transformer: sequential());
    on<CartCleared>(_onCleared, transformer: droppable());
  }

  final CartRepository _repo;
  // ...handlers
}
```

Sequential is **not** the default. The default `concurrent()` will reorder cart mutations — adding then removing the same item could leave the item in the cart if the remove handler finishes first. Always state the transformer explicitly for any handler that mutates shared state.

## Wiring the View

Four widgets bridge a Bloc to the widget tree. Pick the narrowest one that does the job.

| Widget | Purpose | Rebuilds? |
|---|---|---|
| `BlocProvider` | Inject a Bloc into the subtree. Place at the route, not at app root. | n/a |
| `BlocBuilder<B, S>` | Rebuild on every state change. The default. | yes, on every state |
| `BlocSelector<B, S, T>` | Rebuild only when a derived value `T` changes. Use for fine-grained updates. | yes, only when selector output changes |
| `BlocListener<B, S>` | Fire-and-forget side effects: snackbar, navigation, dialog. | **no** — child is unaffected |
| `BlocConsumer` | Rare combination of builder + listener. | yes |

**Common mistake:** wrapping the entire screen in a `BlocBuilder` that rebuilds 30 widgets when only the cart total changed. Use `BlocSelector` for the total and let the rest of the tree stay stable.

## Persistence (optional)

For state that must survive a cold start (cart, auth tokens, recently-viewed list), extend `HydratedBloc<E, S>` instead of `Bloc<E, S>` — or add `HydratedMixin` to an existing `Cubit`/`Bloc` and call `hydrate()` in its constructor when changing the parent class isn't an option. Override `fromJson` and `toJson` on the Bloc. With `freezed`, the serialization helpers are generated — but **only when the state declares an explicit `factory State.fromJson(...)` factory and the file declares `part 'state.g.dart';`**. See the `CartState` snippet above; missing either of these makes `_$CartStateFromJson` undefined and the file won't compile.

**Always override `storagePrefix`** to a stable string literal:

```dart
@override
String get storagePrefix => 'CartBloc';
```

The default storage key is `runtimeType.toString()`, which gets mangled by Dart's minifier in `flutter build apk --release` / `--obfuscate`. A user upgrading the app would find their persisted cart unreadable because the storage key changed names between builds. Pin the prefix in source so the key survives minification.

```dart
import 'package:bloc_concurrency/bloc_concurrency.dart';
import 'package:hydrated_bloc/hydrated_bloc.dart';

class CartBloc extends HydratedBloc<CartEvent, CartState> {
  CartBloc({required CartRepository repo})
      : _repo = repo,
        super(const CartState.initial()) {
    // Persistence and transformers coexist — the example is deliberately
    // explicit about both so readers see them together.
    on<CartHydrated>(_onHydrated, transformer: droppable());
    on<CartItemAdded>(_onItemAdded, transformer: sequential());
    on<CartItemQtyChanged>(_onQtyChanged, transformer: sequential());
    on<CartCleared>(_onCleared, transformer: droppable());
  }

  final CartRepository _repo;

  // ...handlers (omitted; each emits state.copyWith(...) per business rule)

  // Pin the storage key so release builds (which may minify class names)
  // continue reading the same persisted state across upgrades.
  @override
  String get storagePrefix => 'CartBloc';

  @override
  CartState? fromJson(Map<String, dynamic> json) => CartState.fromJson(json);

  @override
  Map<String, dynamic>? toJson(CartState state) =>
      (state as dynamic).toJson() as Map<String, dynamic>?;
}
```

`toJson` is cast through `dynamic` because freezed's generated `toJson` lives on each variant (e.g. `CartLoaded.toJson()`), not on the sealed parent's static analysis surface. The runtime resolution picks the right variant; the cast just gets past static type checking.

### Limitations

Persisting a Bloc whose handler uses `restartable()` or `concurrent()` has two distinct ordering subtleties — don't conflate them:

1. **`restartable()` and in-flight emits.** When event B arrives during event A's handler, `restartable()` marks A's emitter as done. Any `emit(...)` A tries after that is silently dropped (good). The persisted state reflects whatever was emitted *before* B took over — so persistence sees the last successful emit, not necessarily the last dispatched event.
2. **Process death, separately.** If the app is killed while A is mid-`await`, A never gets the chance to emit at all — there's no "cancellation" because there's no process. The persisted state is whatever was emitted *before A started*.

Either way: treat persisted state as a *starting point*. When the screen mounts after a cold start, re-fetch from the API rather than assuming the persisted state reflects an in-flight request's eventual result.

## Workflow: Scaffold a new feature

### Task Progress
- [ ] **Step 1 — Pick a feature name.** Lowercase, singular noun (e.g., `cart`, `auth`, `restaurant_list`).
- [ ] **Step 2 — Create the directory.** `mkdir -p lib/ui/features/<feature>/{bloc,view}`.
- [ ] **Step 3 — Write `<feature>_event.dart`.** Sealed `<Feature>Event` class with one factory per user intent. No logic.
- [ ] **Step 4 — Write `<feature>_state.dart`.** Sealed `<Feature>State` with `Initial`, `Loading`, `Loaded(...)`, `Failure(message)` at minimum. Add domain-specific variants as needed.
- [ ] **Step 5 — Write `<feature>_bloc.dart`.** Extend `Bloc<E, S>` (or `HydratedBloc<E, S>` if persisting). Inject the repository via constructor.
- [ ] **Step 6 — Register handlers with explicit transformers.** Use `sequential()` for mutations, `restartable()` for queries, `droppable()` for submits, `concurrent()` only for independent fetches.
- [ ] **Step 7 — If persisting.** Override `fromJson` / `toJson` on the Bloc using `freezed`-generated helpers.
- [ ] **Step 8 — Generate code.** `dart run build_runner build --delete-conflicting-outputs` (or rely on the `watch -d` side terminal from `flutter-bloc-setup`).
- [ ] **Step 9 — Wire the View.** Wrap the route in `BlocProvider(create: (_) => <Feature>Bloc(repo: context.read<<Feature>Repository>()))`. Use `BlocBuilder` for rendering, `BlocListener` for side effects, `BlocSelector` for fine-grained rebuilds.
- [ ] **Step 10 — Feedback loop.** Run `flutter analyze` → review compile errors → if a `switch` over state is non-exhaustive, handle the missing variant → re-run.

## Applied to Talabat-clone

The cart in this app has the most rules-heavy state in the system: one-cart / one-store / one-city, persistence across cold starts, and a "switch store" guard (`PRD_catalog.md §15.5`, `PRD_states.md §7`).

```text
// pseudocode sketch — see the Counter example below for runnable form
// CartEvent
sealed class CartEvent
  CartHydrated()                                              // app startup, deserialize from disk
  CartItemAdded(Product product, int qty)                     // user taps "+" on a product card
  CartItemQtyChanged(String itemId, int qty)                  // bottom-sheet qty stepper
  CartItemRemoved(String itemId)                              // swipe-to-delete
  CartCleared()                                               // checkout success or explicit clear
  CartStoreSwitchRequested(Product fromOtherStore)            // user added from a different store
  CartStoreSwitchConfirmed()                                  // user confirmed "discard current cart"
  CartStoreSwitchCancelled()                                  // user backed out

// CartState
sealed class CartState
  CartInitial()
  CartLoaded(items, store, subtotal, discount, total)
  CartStoreSwitchPending(currentLoaded, pendingProduct)        // PRD_catalog.md §15.5
  CartFailure(message)
```

`CartBloc` extends `HydratedBloc` because the cart must survive cold start. `CartItemAdded` uses `sequential()` so two rapid taps on "+" never interleave with `CartItemQtyChanged`. `CartStoreSwitchRequested` is a pure state transition — no API call — that puts the Bloc in `CartStoreSwitchPending` until the user confirms or cancels. `CartCleared` happens at checkout success when the API confirms `Cart: active → converted` (`PRD_states.md §7`).

`StoreListBloc` does **not** extend `HydratedBloc` — store availability depends on operational gating (`PRD_states.md §4`) and must be re-fetched on launch.

## Examples

A complete Counter feature illustrates the trio with no async dependencies. It uses `sequential()` because increment-then-decrement order matters.

### `lib/ui/features/counter/bloc/counter_event.dart`

```dart
import 'package:freezed_annotation/freezed_annotation.dart';

part 'counter_event.freezed.dart';

@freezed
sealed class CounterEvent with _$CounterEvent {
  const factory CounterEvent.incremented() = CounterIncremented;
  const factory CounterEvent.decremented() = CounterDecremented;
  const factory CounterEvent.reset() = CounterReset;
}
```

### `lib/ui/features/counter/bloc/counter_state.dart`

```dart
import 'package:freezed_annotation/freezed_annotation.dart';

part 'counter_state.freezed.dart';

// We use `sealed` uniformly across the codebase, even for one-variant states.
// `abstract` would also compile here but the family standardizes on `sealed`
// so future variants don't trigger a class-shape change.
@freezed
sealed class CounterState with _$CounterState {
  const factory CounterState({required int value}) = _CounterState;
}
```

### `lib/ui/features/counter/bloc/counter_bloc.dart`

```dart
import 'package:bloc_concurrency/bloc_concurrency.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

import 'counter_event.dart';
import 'counter_state.dart';

class CounterBloc extends Bloc<CounterEvent, CounterState> {
  CounterBloc() : super(const CounterState(value: 0)) {
    on<CounterIncremented>(
      (e, emit) => emit(CounterState(value: state.value + 1)),
      transformer: sequential(),
    );
    on<CounterDecremented>(
      (e, emit) => emit(CounterState(value: state.value - 1)),
      transformer: sequential(),
    );
    on<CounterReset>(
      (e, emit) => emit(const CounterState(value: 0)),
      transformer: droppable(),
    );
  }
}
```

### `lib/ui/features/counter/view/counter_view.dart`

```dart
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

import '../bloc/counter_bloc.dart';
import '../bloc/counter_event.dart';
import '../bloc/counter_state.dart';

class CounterView extends StatelessWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => CounterBloc(),
      child: const _CounterScaffold(),
    );
  }
}

class _CounterScaffold extends StatelessWidget {
  const _CounterScaffold();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter')),
      body: Center(
        child: BlocSelector<CounterBloc, CounterState, int>(
          selector: (state) => state.value,
          builder: (context, value) => Text(
            '$value',
            style: Theme.of(context).textTheme.displayLarge,
          ),
        ),
      ),
      floatingActionButton: Column(
        mainAxisAlignment: MainAxisAlignment.end,
        children: [
          FloatingActionButton(
            heroTag: 'inc',
            onPressed: () =>
                context.read<CounterBloc>().add(const CounterEvent.incremented()),
            child: const Icon(Icons.add),
          ),
          const SizedBox(height: 8),
          FloatingActionButton(
            heroTag: 'dec',
            onPressed: () =>
                context.read<CounterBloc>().add(const CounterEvent.decremented()),
            child: const Icon(Icons.remove),
          ),
        ],
      ),
    );
  }
}
```

`BlocSelector<CounterBloc, CounterState, int>` rebuilds only when `state.value` changes, not when the Bloc emits a new `CounterState` instance with the same value. For a single-field state this is overkill, but the pattern matters for screens with many fields where one cell shouldn't trigger a full rebuild.

---
> 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 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。