Flutter项目模板插件flutter_boilerplate的使用

Flutter项目模板插件flutter_boilerplate的使用

简介

flutter_boilerplate 是一个用于快速启动 Flutter 应用开发的项目模板插件。它包含现成的项目结构、基础服务文件和可直接使用的部件。

支持

• Android: SDK 21+
• iOS: iOS 9+

安装

在 pubspec.yaml 文件中添加以下依赖：

dev_dependencies:
  flutter_boilerplate: ^0.0.6

然后运行以下命令以安装依赖项：

flutter pub get

初始化基础项目

运行以下命令以初始化基本项目结构：

flutter pub run flutter_boilerplate:init

注意：仅在新项目中运行此命令。该命令会替换项目的 lib 文件夹和 pubspec.yaml 文件。初始化后别忘了设置图标、启动画面和包名（步骤详见相应的 YAML 文件）。运行 init 命令后，所有必需的 YAML 文件将直接导入到你的项目中！

包含的模块/包/插件

可直接使用的服务部件

HttpWidget

HttpWidget 是一个可以用来处理 HTTP 请求的部件。以下是其使用示例：

HttpWidget(
  key: const ValueKey(ApiStrings.usersAPIString),
  errorWidget: CustomLoaders.circularLoader(),
  loader:  CustomLoaders.circularLoader(),
  api: hC.getUsers(),
  useCache: true,
  apiURL: ApiStrings.usersAPIString,
  builder: (data) {
    List<UserDTO> users = (data as List).map((e) => UserDTO.fromJson(e)).toList();
    return ListView.builder(
      itemCount: users.length,
      shrinkWrap: true,
      physics: const ClampingScrollPhysics(),
      itemBuilder: (context, index) {
        return ListTile(
          leading: Text('${users[index].id}'),
          title: Text('${users[index].name}'),
          subtitle: Text('${users[index].email}'),
        );
      },
    );
  },
)

更多使用案例请参见 example 应用。

StorageListenerWidget

StorageListenerWidget 用于监听存储变化。以下是其使用示例：

StorageListenerWidget(
  storage: AppStorage.storage,
  listenKey: StorageKeys.randomStringKey,
  builder: (value) {
    return Text('RANDOM STRING :-  $value');
  },
),

更多使用案例请参见 example 应用。

可直接使用的服务文件

BaseHttp

BaseHttp 提供了一些常用的方法，如存储和获取 token、检查认证状态等：

class BaseHttp {
  Future<void> storeToken(String token);
  Future<String?> getToken();
  Future<bool> checkAuthStatus();
  Future<void> storeAuthData(Map<String, dynamic> data);
  Future<Map<String, dynamic>?> getAuthData();
  Future<void> storeDefaultHeaders(Map<String, String> headers);
  Future<Map<String, String>?> getDefaultHeaders();
  Stream<dynamic> getStream(String url);
  Future<dynamic> get(String url);
  Future<dynamic> post(String url, {Map<String, dynamic>? body});
}

BaseInterceptor

BaseInterceptor 默认与 BaseHttp 实例一起使用，提供了一些方法：

class BaseInterceptor {
  Map<String, String> getHeaders();
  void onError(error);
  void onRequest(requestOptions);
  void onResponse(response);
}

Log

kLog 用于日志记录，提供了过滤日志、写入日志文件、分配标签和类型等功能：

void logsExample() {
  kLog("on info", logStatus: LogStatus.INFO, tag: 'log_example');
  kLog("on error", logStatus: LogStatus.ERROR, tag: 'log_example');
  kLog("on warning", logStatus: LogStatus.WARNING, tag: 'log_example');
}

Storage

GetStorage 用于 StorageService，提供了存储和检索数据的功能：

class StorageService {
  Future<void> saveValue(String key, dynamic value);
  Future<void> updateValue(String key, dynamic value);
  Future<void> updateNewValue(String key, dynamic value);
  Future<dynamic> getValue(String key);
  Future<bool> hasData(String key);
  Future<void> removeValue(String key);
  Future<void> clearStorage();
}

Navigation

navigationService 提供了多种导航方法，如跳转页面、返回等：

class NavigationService {
  BuildContext context;
  void to(String route);
  void back();
  void replace(String route);
  void clearStack();
}

Utils

Utils 文件夹中包含一些实用工具文件，如字符串扩展、生命周期处理器等：

// extensions.dart
extension StringExtensions on String {
  String imagePathToBase64String();
  Color toColor();
  String toCapitalized();
}

// initializer.dart
class Initializer {
  static void init(VoidCallback callback);
}

// lifecycle_handler.dart
class LifecycleHandler {
  static void handleLifecycle();
}

// loaders.dart
class CustomLoaders {
  static Widget circularLoader();
  static Dialog loaderDialog();
  static Widget imageLoadingBuilder();
  static bool isLoading();
  static void setLoading(bool loading);
}

// utils.dart
class Utils {
  static String getFileSize(File file);
  static String getRandomString();
}

// validators.dart
class Validators {
  static bool validateEmpty(String value);
  static bool validateEmail(String value);
  static bool validateOTPCode(String value);
}

可直接使用的常量文件

Assets

abstract class Assets {
  // 例如:
  // static const exampleAsset = 'assets/images/example_assets.svg';
}

ApiStrings

abstract class ApiStrings {
  // 例如:
  // static const loginAPIString = 'example/login';
}

Constants

abstract class Constants {
  static const String appName = '';
  static Environment env = Staging();
}

StorageKeys

abstract class StorageKeys {
  // 例如:
  // static const userNameKey = 'user_name';
}

Strings

abstract class Strings {
  static const String appName = Constants.appName;

  // 认证模块
  static const welcomeBack = '欢迎回来！';
  static const getStarted = '开始';
  static const loginToContinue = '登录以继续';
  static const createAnAccount = '创建账户';
  
  // 输入字段验证
  static const String cantBeEmpty = '不能为空。';
  static const String fieldCantBeEmpty = '字段 $cantBeEmpty';
  static const String enterValid = '请输入有效的';
  static const otpValidation = '无效的验证码';

  // 全名
  static const fullName = '全名';
  static const enterYourFullName = '输入您的全名';

  // 邮箱地址
  static const emailAddress = '邮箱地址';
  static const enterYourEmailAddress = '输入您的邮箱地址';
  static const String emailCantBeEmpty = '邮箱 $cantBeEmpty';
  static const String enterValidEmail = '$enterValid 邮箱。';

  // 密码
  static const String password = '密码';
  static const enterYourPassword = '输入您的密码';
  static const forgotPassword = '忘记密码';
  static const forgotPasswordDescription = '输入您的注册邮箱以接收重置密码的说明并检查您的邮箱';
  static const String confirmPassword = '确认密码';
  static const String enterPassword = '输入密码';
  static const String passwordCantBeEmpty = '$password $cantBeEmpty';
  static const String passwordValidation = '$password 必须至少有6个字符。';
  static const confirmPasswordValidation = '$password 和确认密码必须相同。';
  static const newPassword = '新密码';
  static const createNewPassword = '现在您可以创建一个新密码';
  static const reEnterYourPassword = '重新输入您的新密码';

  // 手机号码
  static const mobileNumber = '手机号码';
  static const String emailOrMobile = '$emailAddress 或 $mobileNumber';
  static const String numberCantBeEmpty = '$emailOrMobile $cantBeEmpty';
  static const String enterValidNumber = '$enterValid $mobileNumber。';

  // 验证码
  static const String sendCode = '发送验证码';
  static const String enterVerificationCode = '输入验证码';
  static const verificationCodeSendToEmail = '我们已向您的邮箱发送验证码以验证您的邮箱地址';
  static const resendOTP = '重新发送验证码';
  static const verify = '验证';

  // 登录/注册
  static const logIn = '登录';
  static const signUp = '注册';
  static const alreadyHaveAnAccount = '您已经有账户了吗？';
  static const notHaveAnAccount = '还没有账户吗？';
  static const orContinueWith = '或继续使用';
  static const or = '或';
  static const google = 'Google';
  static const apple = 'Apple';
  static const signInWithGoogle = '使用 Google 登录';
  static const signInWithApple = '使用 Apple 登录';

  // 互联网错误字符串
  static const unknownError = '未知错误！请稍后再试。';
  static const connectionTimeout = '连接超时。请稍后再试。';
  static const noConnection = '无网络连接。请打开您的网络！';
  static const unauthorized = '未授权。请重新登录！';

  // 全局字符串
  static const String ok = '确定';
  static const String error = '错误';
  static const String noInternet = '无网络。请稍后再试。';
  static const String logOut = '登出';
  static const String retry = '重试';
  static const String confirm = '确认';
  static const String somethingWentWrong = '出错啦。';
  static const String home = '首页';

  static const gallery = '相册';
  static const camera = '相机';
  static const mobile = '手机';
  static const from = '来自';
  static const toCap = '至';
  static const success = '成功';
  static const checkboxValidation = '示例复选框验证信息';
}

Theme

abstract class Theme {
  // 添加您的应用主题
}

可直接使用的环境文件

ENV

enum ENV { staging, production }

abstract class Environment {
  String apiUrl();
  String socketUrl();
  String buildNumber();
  String appVersion();
  int isBeta();
}

TYPES

class Production extends Environment {
  @override
  String apiUrl() {
    return "";
  }

  @override
  String socketUrl() {
    return "";
  }

  @override
  String buildNumber() {
    return "1";
  }

  @override
  String appVersion() {
    return "1.0.0";
  }

  @override
  int isBeta() {
    return 0;
  }
}

可直接使用的路由服务文件

abstract class Routes {
  static const INITIAL = '/initial';
}

abstract class RouteServices {
  const RouteServices._();

  static const STARTING_POINT = Routes.INITIAL;

  static Map<String, Widget Function(BuildContext context)> routes = {
    Routes.INITIAL: (context) => const InitialPage(),
  };

  static PageRoute onGenerateRoute(settings, context) {
    return MaterialPageRoute(builder: (_) => RouteServices.routes[settings.name]!(context));
  }
}

如何导入可选模块

运行以下命令以添加可选模块：

flutter pub run flutter_boilerplate:add <arguments>

注意：你必须手动导入并为相应的包进行原生配置。以下服务模块将被添加到项目中：

项目结构

|-- lib
|   |-- common
|   |   |-- data
|   |   |   |-- assets
|   |   |   |   '-- assets.dart
|   |   |   |-- constants
|   |   |   |   |-- api_strings.dart
|   |   |   |   |-- constants.dart
|   |   |   |   '-- storage_keys.dart
|   |   |   |-- strings
|   |   |   |   '-- strings.dart
|   |   |   '-- theme
|   |   |       '-- theme.dart
|   |   |-- env
|   |   |   |-- environment.dart
|   |   |   '-- types
|   |   |       |-- production.env.dart
|   |   |       '-- staging.env.dart
|   |   |-- routes
|   |   |   '-- route_service.dart
|   |   |-- services
|   |   |   |-- http
|   |   |   |   |-- base_http.dart
|   |   |   |   '-- base_interceptor.dart
|   |   |   |-- log
|   |   |   |   '-- log.dart
|   |   |   |-- navigation
|   |   |   |   '-- navigation.dart
|   |   |   '-- storage
|   |   |       '-- storage.dart
|   |   |-- utils
|   |   |   |-- extensions.dart
|   |   |   |-- initializer.dart
|   |   |   |-- lifecycle_handler.dart
|   |   |   |-- loaders.dart
|   |   |   |-- snackbars.dart
|   |   |   |-- utils.dart
|   |   |   '-- validators.dart
|   |   '-- widgets
|   |       |-- compute
|   |       |   |-- compute_list_widget.dart
|   |       |   '-- compute_widget.dart
|   |       |-- http
|   |       |   '-- http_widget.dart
|   |       |-- image
|   |       |   '-- image_widget.dart
|   |       '-- listener
|   |           '-- storage_listener_widget.dart
|   |-- main.dart
|   '-- modules
|       '-- initial
|           '-- pages
|               |-- initial_material_app.dart
|               '-- initial_page.dart