Flutter 插件 proviso 的使用说明

简介

proviso 是一个用于Flutter的工具包，它提供了条件渲染（如if-else和switch条件）、子树包装以及一些便捷的小部件（例如DebugWidget、WebOnlyWidget、SafeBuilder等）。这些工具可以简化代码，提高可读性。

安装

在您的Flutter项目中添加依赖：

dependencies:
  ...
  proviso: ^1.0.5

使用场景

为了使条件语句代码更简洁易读，proviso 提供了多种方式来处理条件渲染和其他逻辑。

条件渲染

单个 Widget 的条件渲染

通过 ConditionWidget 和 ConditionBuilder 可以实现基于条件的单个 Widget 渲染。

示例：

Row(
  children: [
    ConditionWidget(
      condition: starred,
      widget: Icon(Icons.favorite),
      fallback: fallbackWidget
    ),
    ConditionWidget(
      condition: archived,
      widget: Icon(Icons.archive)
    )  
  ]
)

Builder 模式下的条件渲染

使用 ConditionalBuilder.widget 或 ConditionalBuilder.widgets 来根据条件构建单个或多个 Widgets。

示例：

ConditionalBuilder.widget(
  context: context,
  condition: (_) => _evaluateSomething(),
  trueBuilder: (_) => trueWidget,
  fallbackBuilder: (_) => fallbackWidget,
);

Switch Case 渲染

对于多条件分支，可以使用 SwitchCaseBuilder.widget 或 SwitchCaseBuilder.widgets 来处理不同情况下的渲染。

示例：

final Widget targetConditionWidget = Container();
final Widget fallbackWidget = Container();

SwitchCaseBuilder.widget<String>(
  context: context,
  condition: (_) => '1',
  caseBuilders: {'1': (_) => targetConditionWidget, '2': (_) => Container()},
  fallbackBuilder: (_) => fallbackWidget,
);

包装父级 Widget

有时候需要根据某些条件决定是否将子元素包裹在一个父组件内，这时可以使用 ConditionalWrap。

示例：

ConditionalWrap(
  shouldWrap: shouldWrapChildInParent,
  child: Container(),
  parentBuilder: (child) => Container(child: child),
)

Try/Catch 构建器

当您想要捕获并处理潜在错误时，可以使用 SafeBuilder。

示例：

SafeBuilder(
  widgetBuilder: (_) => validWidget,
  fallbackBuilder: (e, _) => fallbackWidget, // 当 widgetBuilder 抛出异常时调用
)

其他辅助工具

此外，proviso 还提供了一些特定平台的辅助小部件，如 DebugOnlyWidget, WebOnlyWidget 等。

示例 Demo

以下是一个完整的示例应用，展示了如何使用 proviso 中的各种特性：

import 'package:flutter/material.dart';
import 'package:proviso/proviso.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Proviso Example')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: <Widget>[
              // 条件渲染
              ConditionWidget(
                condition: true,
                widget: Icon(Icons.check_circle, color: Colors.green),
                fallback: Icon(Icons.error, color: Colors.red),
              ),
              
              SizedBox(height: 20),
              
              // Switch Case 渲染
              SwitchCaseBuilder<int>.widget(
                context: context,
                condition: (_) => 2,
                caseBuilders: {
                  1: (_) => Text('One'),
                  2: (_) => Text('Two'),
                },
                fallbackBuilder: (_) => Text('Default'),
              ),
              
              SizedBox(height: 20),
              
              // Try/Catch 构建器
              SafeBuilder(
                widgetBuilder: (_) => Text('Valid Widget'),
                fallbackBuilder: (e, _) => Text('Error occurred: $e'),
              ),
              
              SizedBox(height: 20),
              
              // Conditional Parent Widget
              ConditionalWrap(
                shouldWrap: true,
                child: Text('Wrapped Child'),
                parentBuilder: (child) => Padding(padding: EdgeInsets.all(8.0), child: child),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

这个例子涵盖了 proviso 的主要功能，并展示了它们在实际项目中的应用。希望这能帮助您更好地理解和使用该插件！如果有任何问题或需要进一步的帮助，请随时提问。