fpj_core

MsrJie 的 Flutter 封装基础库，汇集日常开发中常用的扩展方法、组件和工具类，帮助快速构建 Flutter 应用。

安装

在 pubspec.yaml 中添加依赖：

dependencies:
  fpj_core:
    git:
      url: https://github.com/PsjNick/fpj_core

然后执行：

flutter pub get

入口文件

只需导入一个文件即可使用所有功能：

import 'package:fpj_core/fpj_cores.dart';

该入口自动 re-export 了以下常用第三方库，无需重复导入：

库	用途
get	状态管理、路由、依赖注入
flutter_screenutil	屏幕适配
gap	组件间距
cached_network_image	网络图片缓存
oktoast	Toast 提示
pull_to_refresh_flutter3	下拉刷新 / 上拉加载
badges	角标徽章
palette_generator	图片取色
common_utils	通用工具（日期、加密等）

---

一、应用启动：fpjRunApp

用 fpjRunApp 替代原生 runApp，它会自动初始化 GetStorage 和 WidgetsFlutterBinding：

void main() async {
  await fpjRunApp(
    app: MyApp(),
    configLocalKVName: 'my_storage', // 可选，默认为 "Storage"
    onInit: () {
      // 应用初始化回调，在 GetStorage 初始化之前执行
    },
  );
}

---

二、基础组件

FpjWidgetApp — 应用根组件

封装了 ScreenUtilInit + OKToast + GetMaterialApp，集成了屏幕适配、Toast、国际化、生命周期监听等常用配置：

FpjWidgetApp(
  title: 'My App',
  home: HomePage(),
  size: Size(375, 812),          // 设计稿尺寸（用于 ScreenUtil）
  getPages: [                    // GetX 路由
    GetPage(name: '/home', page: () => HomePage()),
  ],
  supportedLocales: [            // 国际化支持
    Locale('zh', 'CN'),
    Locale('en', 'US'),
  ],
  scaffoldBackgroundColor: Colors.white,
  routingCallback: (routing) {
    // 路由变化回调
  },
)

FpjWidgetPage — 页面组件

自带生命周期回调的页面包装组件，基于 lifecycle 库：

FpjWidgetPage(
  page: YourPageContent(),
  title: '页面标题',
  bgColor: Colors.white,
  autoClearFocus: true,     // 点击空白处自动收起键盘
  onPush: () {},            // 页面被 push 时
  onVisible: () {},         // 页面可见时
  onActive: () {},          // 页面激活时
  onInactive: () {},        // 页面失活时
  onInvisible: () {},       // 页面不可见时
  onPop: () {},             // 页面被 pop 时
  actionChilds: [           // AppBar 右侧操作按钮
    Icon(Icons.more_horiz),
  ],
)

FpjWidgetContainer — 容器组件

简化版 Container，支持圆角、阴影、渐变、点击等常用属性：

FpjWidgetContainer(
  width: 100,
  height: 100,
  radius: 12,               // 统一圆角
  // 或分别设置：
  // radiusTopL: 12, radiusTopR: 12, radiusBottomL: 0, radiusBottomR: 0,
  color: Colors.blue,
  elevation: 4,
  paddingAll: 10,
  boxShadow: [
    BoxShadow(color: Colors.black26, blurRadius: 5),
  ],
  gradient: LinearGradient(colors: [Colors.red, Colors.orange]),
  onTap: () => print('点击'),
  child: Text('Hello'),
)

FpjWidgetImageNetwork — 网络图片组件

基于 cached_network_image 的网络图片组件，内置圆角裁剪和点击事件：

FpjWidgetImageNetwork(
  imageUrl: 'https://example.com/image.jpg',
  width: 100,
  height: 100,
  radius: 12,
  fit: BoxFit.cover,
  onTapImage: (url) {
    // 点击预览大图
  },
)

FpjWidgetImageSvg — SVG 图片组件

统一处理本地和网络 SVG 资源：

// 本地 SVG
FpjWidgetImageSvg(url: 'assets/icons/logo.svg', size: 48)

// 网络 SVG
FpjWidgetImageSvg(url: 'https://example.com/icon.svg', size: 48, color: Colors.blue)

FpjWidgetQrCode — 二维码组件

基于 pretty_qr_code 的二维码生成组件：

FpjWidgetQrCode(
  data: 'https://example.com',
  decorationImageAssets: 'assets/logo.png', // 可选：中间 Logo
)

---

三、扩展方法

导入后，以下类型自动获得扩展能力。

3.1 String 扩展

// 颜色转换
Color color = '#FF5733'.toColor();

// 本地 KV 存储（基于 get_storage）
String? name = 'user_name'.getFromLocalKV<String>();
'user_name'.setToLocalKV('John');
'user_name'.delFromLocalKV();

// 剪切板
await 'hello'.copyToClipBoard(showTip: true);

// 字符串判断
bool valid = '123.45'.checkIsIWhatDoubleStr(maxDecimalNum: 2);
double? d = '3.14'.strToDouble();
int count = 'hello world'.repeatNum(checkStr: 'o'); // → 2

3.2 int 扩展

// 延时
await 2.delaySeconds();       // 延迟 2 秒

// Duration 转换
Duration d = 5.durationSeconds();

// 时间戳 → 格式化日期字符串
String date = 1690000000000.dateTime(format: 'yyyy-MM-dd HH:mm:ss');

3.3 num 扩展

// 快速创建 SizedBox
50.sizedBox(child: Text('50x50'));

// 快速创建 Container
100.container(color: Colors.red, child: ...);

// 快速创建 Gap 间距
20.gap();

3.4 List 扩展

List<Widget> widgets = [...];

// 快速生成 ListView
widgets.genListView(
  padding: EdgeInsets.all(10),
  build: (data, index) => ListTile(title: Text('$data')),
);

// 带分割线的 ListView
items.genBuildListView(
  buildWidget: (context, data, index) => ListTile(title: Text('$data')),
  buildDivider: (context, data, index) => Divider(),
);

// 快速生成 GridView
widgets.genGridView(
  crossAxisCount: 3,
  aspectRatio: 1,
  build: (data, index) => Container(color: Colors.blue),
);

// 快速生成 Row
[Text('A'), Text('B'), Icon(Icons.star)].row(
  mainAxisAlignment: MainAxisAlignment.center,
);

3.5 Widget 扩展

// 居中
Text('Hello').center()

// 点击
Container().onTap(() => print('tapped'))

// 水波纹点击（InkWell + ClipRRect）
Container().onTapWithInk(() {}, radius: 12)

// 角标徽章
Icon(Icons.notifications).widgetBadgeNum(5)

// GetX Obx 自动订阅
Text('xxx').obx()

// Positioned 定位
Container().positioned(left: 10, top: 20)

// 背景色（Material 包装）
Container().colorBg(Colors.white)

// 裁剪圆角
Image.network('...').clipRadius(12)

3.6 Text 扩展

Text('Hello')
  .textColor(Colors.red)
  .fontSize(18)
  .height(1.5);

3.7 Icon 扩展

Icon(Icons.home)
  .iconSize(28)
  .iconColor(Colors.blue);

3.8 IconData 扩展

Icons.star.toIcon(size: 24, color: Colors.amber);

3.9 SizedBox 扩展

SizedBox(width: 100, height: 100)
  .sizedBoxChild(child: Text('Content'));

3.10 BoxScrollView 扩展（下拉刷新）

ListView().wrapRefresher(
  controller: refreshController,
  refresh: (controller) async {
    // 下拉刷新逻辑
  },
  loadmore: (controller) async {
    // 上拉加载更多逻辑
  },
);

3.11 Object 扩展

// 日志输出（基于 logger）
'debug info'.logD();
'error info'.logE();
'info'.logI();
'warning'.logW();

// 任意对象 → Text Widget
123.toTextWidget(color: Colors.blue, fontSize: 16);

// Toast 提示（基于 oktoast）
'操作成功'.toast(bgColor: Colors.green);
'操作失败'.toast(bgColor: Colors.red);

---

四、控制器：FpjController

基础控制器，继承自 GetxController，在 GetX 项目中使用：

class MyController extends FpjController {
  var count = 0.obs;

  void increment() => count++;

  @override
  void onInit() {
    super.onInit();
    // 初始化逻辑
  }
}

---

五、工具类：FpjUtil

随机颜色

Color color = FpjUtil.genRandomColor();

责任链模式

await FpjUtil().chainHandler(handles: [
  () { /* 处理1 */ return false; }, // 返回 true 则中断
  () { /* 处理2 */ return true;  },
  () { /* 不会执行 */ return false; },
]);

清除键盘焦点

FpjUtil().clearFocus(); // 默认用 Get.context
FpjUtil().clearFocus(context: myContext);

XOR 加解密（来自 FpjUtilWithCrypto）

final util = FpjUtil();

String encoded = util.encode(orgStr: 'hello', key: 'secret');
String decoded = util.decode(secStr: encoded, key: 'secret');

---

六、全局配置

本地 KV 存储名称

通过 fpjRunApp 的 configLocalKVName 设置，默认值为 "Storage"。底层基于 get_storage。所有 String 扩展中的 getFromLocalKV / setToLocalKV / delFromLocalKV 都使用此存储实例。可配合 GetStorage 直接使用：

GetStorage box = GetStorage('Storage');
box.write('key', 'value');

---

许可证

See LICENSE.