# boxes-android

**Repository Path**: sunlunchang/boxes-android

## Basic Information

- **Project Name**: boxes-android
- **Description**: Android开发基础框架
- **Primary Language**: Android
- **License**: MIT
- **Default Branch**: master-final-dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 1
- **Created**: 2022-04-06
- **Last Updated**: 2026-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SlcBoxs
###### 这是一个灵活而强大的Android开发基础框架！
###### 目前处于稳定且不断更新状态。
## 导入方式
````java
implementation 'com.gitee.sunlunchang:boxes-android:lastVersion'
````
###### 仅支持Android X
###### 文档仍在补全当中…… 代码是最好的老师，如遇问题，请先查看源码
## 模块介绍
#### SlcBoxs由android-util、hutool、or、rx、rx-lifecycle、design、bar-plus、popup、adapter、db、enhance-nav、core、core-lifecycle等模块组成，下文会对其进行详细介绍。
![enter description here](./images/IMG_1.png)
### android-util
###### 这是blankj的[AndroidUtilCode](https://github.com/Blankj/AndroidUtilCode "AndroidUtilCode")，修改了部分工具类的实现。本模块提供了 80+ 个工具类，涵盖 Android 开发的各个方面，包括文件操作、缓存管理、网络相关、设备信息、UI 相关、权限管理、数据存储、加密编码、图片处理、时间处理、字符串处理、线程管理、日志工具等。

#### 功能特性
- **80+ 工具类**：提供丰富的 Android 开发常用工具类
- **核心工具**：Utils（初始化入口）、ApiUtils（API 管理）、UtilsBridge（桥接层）
- **文件操作**：FileUtils、FileIOUtils、PathUtils、ZipUtils、SDCardUtils
- **缓存管理**：CacheDiskUtils、CacheMemoryUtils、CacheDoubleUtils
- **网络相关**：NetworkUtils（网络状态检测、网络类型判断）
- **设备信息**：DeviceUtils、PhoneUtils、RomUtils、ScreenUtils、BarUtils
- **UI 相关**：ViewUtils、SizeUtils、SpanUtils、ToastUtils、SnackbarUtils、DialogUtils
- **权限管理**：PermissionUtils
- **数据存储**：SPUtils、SPStaticUtils
- **加密编码**：EncryptUtils、EncodeUtils
- **其他工具**：AppUtils、IntentUtils、UriUtils、ClipboardUtils、KeyboardUtils 等

#### 使用示例
```java
// 初始化（在 Application 中）
Utils.init(this);

// 文件操作
FileUtils.createOrExistsFile("/sdcard/test.txt");
String content = FileUtils.readFile2String("/sdcard/test.txt");

// Toast 显示
ToastUtils.show("提示信息");

// 权限申请
PermissionUtils.permission(Manifest.permission.CAMERA)
    .callback(new PermissionUtils.SimpleCallback() {
        @Override
        public void onGranted() {
            // 权限已授予
        }
    })
    .request();
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:android-util:lastVersion'
````

### hutool
###### 这是hutool Java7的最后一个版本提取了部分工具类在此处。本模块提供了大量实用的工具类，涵盖了 Java 开发的各个方面，包括字符串处理、Bean 操作、日期时间、编码解码、集合操作、IO 操作、类型转换等。

#### 功能特性
- **字符串工具**：StrUtil（判空、截取、格式化、转换等）
- **Bean 操作**：BeanUtil（Map 转 Bean、Bean 转 Map、属性复制等）
- **日期时间**：DateUtil（格式化、解析、计算等）
- **编码解码**：Base64、Base32、Base62、BCD、Caesar、Morse
- **集合工具**：CollUtil（判空、创建、操作、分组、去重等）
- **类型转换**：Convert（基本类型转换、日期转换、集合转换等）
- **IO 工具**：IoUtil、FileUtil（文件操作、IO 操作）
- **Map 工具**：MapUtil（判空、创建、操作等）
- **数学工具**：MathUtil（排列组合、最大值、最小值等）
- **其他工具**：AnnotationUtil、CloneSupport、Builder、Comparator、ExceptionUtil

#### 使用示例
```java
// 字符串处理
StrUtil.isBlank(str);
StrUtil.format("Hello {}", "World");
StrUtil.toCamelCase("hello_world"); // helloWorld

// Bean 操作
User user = BeanUtil.mapToBean(map, User.class, false);
Map<String, Object> map = BeanUtil.beanToMap(user);

// 日期时间
DateTime now = DateUtil.date();
String dateStr = DateUtil.format(now, "yyyy-MM-dd HH:mm:ss");
Date tomorrow = DateUtil.offsetDay(now, 1);

// 编码解码
String encoded = Base64.encode("Hello World");
String decoded = Base64.decodeStr(encoded);
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:hutool:lastVersion'
````
### or
###### 该模块是对[retrofit](https://github.com/square/retrofit "retrofit")进行了二次封装，快速构建retrofit。基于 Retrofit + OkHttp + RxJava3，提供了参数构建、文件上传、Retrofit 实例管理等功能。

#### 功能特性
- **Retrofit 实例管理**：支持默认实例和多个自定义实例的管理
- **参数构建工具**：SlcParam 类封装了所有类型的请求参数，适应任何请求场景
- **文件上传支持**：FileRequestBody 支持文件上传，可轻松监听上传进度
- **线程安全**：使用同步机制保证多线程环境下的安全性
- **Debug 模式**：支持控制日志拦截器的启用

#### 使用示例
```java
// 初始化（在 Application 中）
SlcNu.setDebugMode(BuildConfig.DEBUG);
SlcNu.getInstance().setBaseUrl("https://api.example.com/");

// 创建 API 服务
ApiService service = SlcNu.getInstance().create(ApiService.class);

// 文件上传
File file = new File("/path/to/file.jpg");
FileRequestBody requestBody = SlcParam.createFReq(file, new FileRequestBody.FileUploadListener() {
    @Override
    public void onProgressChange(int progress, long bytesWritten, long contentLength) {
        // 进度更新
    }
});
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:or:lastVersion'
````
### rx
###### 该模块基于 RxJava3 封装了常用的调度器转换工具和简化的 Observer 实现类，旨在简化 Android 开发中 RxJava 的使用。

#### 功能特性
- **调度器转换工具**：提供便捷的线程调度转换器，统一处理 IO/Computation 线程执行和主线程观察
- **简化 Observer 实现**：提供多个简化的 Observer 基类，减少样板代码
- **支持所有 RxJava 类型**：支持 Observable、Flowable、Single、Maybe、Completable 等

#### 使用示例
```java
// 使用 IO 线程执行，主线程观察
Observable.just("Hello")
    .compose(SlcRxJavaUtils.applyOoAndroidSchedulers())
    .subscribe(new SimpleObserver<String>() {
        @Override
        public void onNext(@NonNull String s) {
            // 在主线程执行
            textView.setText(s);
        }
    });
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:rx:lastVersion'
````
### rx-lifecycle
###### 基于 com.uber.autodispose2:autodispose，封装了简单的 RxJava 生命周期管理工具，用于在非 Android 组件场景下管理 RxJava 订阅的生命周期。

#### 功能特性
- **SimpleLifecycleScopeProvider**：简单的生命周期范围提供者，与 AutoDispose 配合使用
- **自动管理订阅**：自动管理 RxJava 订阅的生命周期，防止内存泄漏
- **线程安全**：线程安全的实现
- **防止重复初始化**：支持防止重复初始化

#### 使用示例
```java
// 创建生命周期提供者
SimpleLifecycleScopeProvider provider = SimpleLifecycleScopeProvider.create();
provider.start();

// 在 RxJava 流中使用
Observable.just("data")
    .to(AutoDispose.autoDisposable(provider))
    .subscribe(data -> {
        // 处理数据
    });

// 停止生命周期（会自动取消所有订阅）
provider.stop();
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:rx-lifecycle:lastVersion'
````
### design
###### 该模块提供了 Material3 主题相关的属性和样式，以及针对不基于 Material 风格项目的表单、列表样式。主要包含资源文件，提供统一的 UI 设计规范。

#### 功能特性
- **Material3 主题支持**：提供 Material3 主题相关的自定义属性
- **表单样式**：针对表单输入框提供统一的样式和属性
- **颜色工具**：DesignColorUtils 提供颜色级别计算功能
- **UI 颜色规范**：提供统一的 UI 颜色定义
- **动画资源**：提供常用的动画资源文件

#### 使用示例
```java
// 使用颜色工具类
int[] uiColors = DesignColorUtils.getUiColorArray(context);
int semiTransparentWhite = DesignColorUtils.getWhiteLevel16(8);
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:design:lastVersion'
````
### bar-plus
###### 该模块针对 AndroidX 的顶部工具栏和菜单增加了部分组件，提供了更便捷的 Toolbar 使用方式和自定义 ActionProvider 支持。

#### 功能特性
- **简化的 Toolbar 操作**：通过 SlcToolBarDelegate 简化 Toolbar 的常用操作
- **自定义 ActionProvider**：支持子菜单弹出功能的自定义 ActionProvider
- **多种主题支持**：提供 Light、Dark 和 Material3 三种主题布局
- **便捷的工具类**：提供菜单工具类和常用工具方法

#### 使用示例
```java
// 使用 Builder 模式
ISlcToolBarDelegate toolbarDelegate = new SlcToolBarDelegate.Builder(activity)
    .setAppBarLayoutId(R.id.appBarLayout)
    .setToolbarId(R.id.toolBar)
    .build();

// 设置标题
toolbarDelegate.setTitle("标题");
toolbarDelegate.setSubtitle("副标题");
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:bar-plus:lastVersion'
````
### popup
###### 该模块对 Android 的弹窗组件进行了无入侵式封装，提供了统一的弹窗管理接口。支持 Dialog、PopupWindow、ShadowPopupWindow、BottomSheetDialog 等多种弹窗类型。

#### 功能特性
- **统一管理**：通过 SlcPopup2 统一管理所有弹窗，支持通过 key 标识和管理
- **多种弹窗类型**：支持 AlertDialog、PopupWindow、ShadowPopupWindow、BottomSheetDialog 等
- **内存安全**：使用 WeakReference 存储弹窗引用，避免内存泄漏
- **线程安全**：使用同步机制保证多线程环境下的安全性
- **便捷构建**：提供 Builder 模式快速构建弹窗

#### 使用示例
```java
// 创建并注册弹窗
AlertDialog dialog = new AlertDialog.Builder(context)
    .setTitle("提示")
    .setMessage("这是一个提示对话框")
    .create();

AlertDialogOperateImpl operate = new AlertDialogOperateImpl(dialog);
SlcPopup2.addOperate("dialog_key", operate);
operate.show();

// 通过 key 关闭弹窗
SlcPopup2.dismissByKey("dialog_key");
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:popup:lastVersion'
````
### adapter
###### 关于 RecyclerView 的 Adapter 的模块，基于 BaseRecyclerViewAdapterHelper 封装了 RecyclerView 的适配器，提供了下拉刷新、加载更多、分页逻辑等通用功能。

#### 功能特性
- **下拉刷新**：支持 SwipeRefreshLayout 下拉刷新
- **加载更多**：支持上拉加载更多功能
- **分页逻辑**：提供完整的分页数据处理工具（PageUtils、LoadMoreDataFormat）
- **选择功能**：支持单选、多选功能（SelectUtils、SelectBox）
- **DiffUtil 支持**：支持数据差异更新，提升性能
- **点击事件代理**：简化 Item 和 ItemChild 的点击事件处理

#### 使用示例
```java
CommonlySwipeRecycler<String> swipeRecycler = new CommonlySwipeRecycler<>(
    activity, R.id.swipeRefreshLayout, R.id.recyclerView,
    new OnLoadAdapterListener<String>() {
        @Override
        public BaseQuickAdapter<String, BaseViewHolder> onLoadAdapter() {
            return new MyAdapter();
        }
    }
);

swipeRecycler.initView()
    .setOnRefreshListener(() -> refreshData())
    .setOnLoadMoreListener(() -> loadMoreData());
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:adapter:lastVersion'
````
### db
###### 本模块提供了数据持久化解决方案，基于 SharedPreferences 封装了快速调用接口，同时提供了基于内存缓存和文件缓存的实现，提供了与 SharedPreferences 相同的 API。在大屏、广告机等场景上做配置文件比较方便。

#### 功能特性
- **统一接口**：DataPersistence 接口提供统一的数据持久化 API
- **多种实现**：支持 SharedPreferences（DbSp）、内存缓存和文件缓存（DbCd）等多种实现
- **自动保存默认值**：支持自动保存默认值功能
- **类型安全**：提供类型检查和转换功能
- **线程安全**：使用 ConcurrentHashMap 保证线程安全

#### 使用示例
```java
// 使用 DbSp（SharedPreferences）
DbSp dbSp = new DbSp("my_prefs");
dbSp.putValue("username", "admin");
String username = dbSp.getString("username", "");

// 使用 DbCd（缓存）
DbCd dbCd = new DbCd("my_config");
dbCd.putValue("theme", "dark");
String theme = dbCd.getString("theme", "light");
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:db:lastVersion'
````
### enhance-nav
###### 基类 Activity 和 Fragment，基于 AndroidX Navigation 组件，提供了增强的 Activity 和 Fragment 基类。该模块为 core 模块提供基础支持，实现了可见性监听、懒加载等功能。

#### 功能特性
- **Navigation 支持**：基于 AndroidX Navigation 组件
- **可见性监听**：支持 Fragment 可见性监听（onFragmentVisible/onFragmentInvisible）
- **懒加载**：支持 Fragment 懒加载功能（onLazyLoad）
- **生命周期管理**：完善的 Fragment 生命周期管理

#### 使用示例
```java
public class MyFragment extends EnhanceFragment {
    @Override
    protected boolean enableSupport() {
        return true; // 启用支持功能
    }
    
    @Override
    protected void onLazyLoad() {
        // 懒加载数据，只在首次可见时调用
        loadData();
    }
    
    @Override
    protected void onFragmentVisible() {
        // Fragment 可见时调用
        refreshData();
    }
}
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:enhance-nav:lastVersion'
````
### core
###### 这是 SlcBoxes 核心模块，提供了 MVVM 架构的基础实现，包括 Activity、Fragment、ViewModel、ViewDelegate 等核心组件。模块将 Activity 和 Fragment 的相关初始化方式封装了代理类，并为 Activity 和 Fragment 提供了一致的方法名，方便在项目中因使用 Activity 不合适时，仅更改继承的父类就可实现 Activity 和 Fragment 一键替换。

#### 功能特性
- **MVVM 架构**：提供完整的 MVVM 架构实现
- **ViewDelegate 模式**：采用代理模式将视图相关逻辑从 Activity/Fragment 中分离
- **ViewModel 支持**：提供多种 ViewModelProvider（App、Activity、Fragment）
- **DataBinding 支持**：自动绑定 ViewDataBinding，自动设置 LifecycleOwner
- **统一界面操作**：统一的界面操作事件（finish、backPressed、startActivity、fillResult）
- **VmSub 支持**：用于将 ViewModel 的部分功能模块化

#### 核心组件
- **BaseActivity / BaseFragment**：基础的 Activity 和 Fragment
- **VmActivity / VmFragment**：支持 ViewModel 的 Activity 和 Fragment
- **MvvmActivity / MvvmFragment**：支持 DataBinding 的 MVVM Activity 和 Fragment
- **BaseViewModel**：基础的 ViewModel，提供统一的界面操作事件
- **SingleLiveEvent**：单次事件 LiveData，确保事件只被消费一次
- **ViewDelegate**：视图代理，处理视图创建和生命周期

#### 使用示例
```java
public class MainActivity extends MvvmActivity<ActivityMainBinding> {
    private MainViewModel viewModel;

    @Override
    public Object setContentView() {
        return R.layout.activity_main;
    }

    @Override
    public void onBindView(@Nullable Bundle savedInstanceState) {
        viewModel = getVmByActivityProvider(MainViewModel.class);
        registerLiveEvent(viewModel);
        getDataBinding().setViewModel(viewModel);
        getDataBinding().setLifecycleOwner(this);
    }
}
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:core:lastVersion'
````

### core-lifecycle
###### 基于 core 和 rx-lifecycle 的集成模块，提供了 RxJava 与 Android 生命周期的自动管理功能。通过 AutoDispose 自动管理 RxJava 订阅的生命周期，避免内存泄漏。

#### 功能特性
- **RxViewModel**：支持 RxJava 生命周期管理的 ViewModel，扩展了 BaseViewModel
- **RxVmSub**：支持 RxJava 生命周期管理的 VmSub，用于 ViewModel 的模块化组件
- **自动生命周期管理**：ViewModel 注册到 Activity/Fragment 时会自动初始化生命周期
- **自动清理订阅**：ViewModel 销毁时自动停止生命周期，所有订阅会自动取消
- **RxMvvmActivity / RxMvvmFragment**：支持 RxJava 生命周期管理的 MVVM Activity 和 Fragment

#### 使用示例
```java
public class MyViewModel extends RxViewModel {
    public void loadData() {
        Observable.just("data")
            .to(bindToLifecycle())
            .subscribe(data -> {
                // 处理数据，自动管理生命周期
            });
    }
}

public class MyActivity extends FastRxMvvmActivity<ActivityMainBinding, MyViewModel> {
    @Override
    public int getLayoutResId() {
        return R.layout.activity_main;
    }
    
    @Override
    protected void onBindView(Bundle savedInstanceState) {
        MyViewModel viewModel = getViewModel();
        // ViewModel 已自动初始化 RxJava 生命周期
        viewModel.loadData();
    }
}
```

#### 依赖方式
````java
implementation 'com.gitee.sunlunchang.boxes-android:core-lifecycle:lastVersion'
````
### all
###### 一键依赖了所有模块
#### 依赖方式
````java
implementation 'com.gitee.sunlunchang:boxes-android:lastVersion'
````