# AndroidBase

**Repository Path**: superpeter2020/androidbase

## Basic Information

- **Project Name**: AndroidBase
- **Description**: 更快捷的去开发安卓应用
- **Primary Language**: Kotlin
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-06-28
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AndroidBase 项目文档

## 项目简介

AndroidBase 采用 MVVM 架构模式，致力于打造一个安卓快速开发框架，解决应用搭建、组件选型繁琐等问题，让开发者可以更迅速的投入到业务开发当中。同时为了考虑开发者的不同需要以及更好的精简 APP 的体积，该项目分成了一共3个模块供开发者使用：mvvm、common-ui、fast-ui，它们之间根据 UI 样式介入的多少，存在互相依赖的关系，同时只需要引入其中一个库即可。

## 技术栈

- **架构模式**: MVVM
- **编程语言**: Kotlin
- **网络请求**: Retrofit + OkHttp
- **数据库**: Room
- **UI框架**: ViewModel + ViewBinding + LiveData

## 各模块依赖

- **JitPack 配置**
##### `build.gradle`
```groovy
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url 'https://jitpack.io' }
    }
}
```
##### `build.gradle.kts`
```groovy
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}
```
- **mvvm**
```groovy
implementation("com.gitee.superpeter2020.androidbase:mvvm:0.0.4")
```
- **common-ui**
```groovy
implementation("com.gitee.superpeter2020.androidbase:common-ui:0.0.4")
```
- **fast-ui**
```groovy
implementation("com.gitee.superpeter2020.androidbase:fast-ui:0.0.4")
```

如果出现有依赖包无法下载的情况，可添加阿里云的资源库地址：
```groovy
maven { url 'https://maven.aliyun.com/repository/public' }
```

## 模块说明和使用方式

### `mvvm`

基础架构模块，提供了基本页面构造以及数据获取方式。
该模块适用于想使用 MVVM 搭建基础架构，又不想有其他 UI 相关的包集成进来的开发者。

#### `自定义 Application，配置在 manifest`

##### `kotlin 用例`
```kotlin
class CustomApplication : BaseApplication()
```
##### `java 用例`
```java
public class CustomApplication extends BaseApplication {}
```

#### `Activity 和 Fragment 构造`

##### `kotlin 用例`
```kotlin
class MainActivity : BaseLifecycleActivity<MainViewModel>() {
    override fun addDataObserver(viewModel: MainViewModel) {
        // ViewModel 是连接 Activity 和 数据的桥梁
        // 所有和视图相关的数据都应该在这个回调里进行处理
        viewModel.liveData.observe(this) {
            // 更新视图
        }
    }
}
class SubFragment : BaseLifecycleFragment<SubViewModel>() {
    override fun addDataObserver(viewModel: SubViewModel) {
        // 使用方式同 Activity
    }
}
```
##### `java 用例`
```java
public class MainActivity extends BaseLifecycleActivity<MainViewModel> {
    @Override
    protected void addDataObserver(@NonNull MainViewModel mainViewModel) {
        // ViewModel 是连接 Activity 和 数据的桥梁
        // 所有和视图相关的数据都应该在这个回调里进行处理
        viewModel.liveData.observe(this, content -> {
            // 更新视图
        });
    }
}
public class SubFragment extends BaseLifecycleFragment<SubViewModel> {
    @Override
    protected void addDataObserver(@NonNull SubViewModel subViewModel) {
        // 使用方式同 Activity
    }
}
```

ViewModel 是连接页面和数据的桥梁，需要根据不同的需要使用不同的 ViewModel，下面列出几种 ViewModel 的类型：

- 无需网络请求或者操作数据库（`NulViewModel`）
- 需要处理网络请求（`NetViewModel`）
- 需要操作数据库（`DatabaseViewModel`）
- 兼具网络请求和操作数据库（`MultiViewModel`）

#### `ViewModel 构造`

##### `kotlin 用例`
```kotlin
class MainViewModel(application: Application) : NulViewModel(application) {
    
    val liveData: BaseLiveData<String> = BaseLiveData()
}
```
##### `java 用例`
```java
public class MainViewModel extends NulViewModel {

    public BaseLiveData<String> liveData = new BaseLiveData<>();

    public MainViewModel(@NonNull Application application) {
        super(application);
    }
}
```

#### `网络请求的使用`

#### `1. 创建网络请求 ViewModel`

##### `kotlin 用例`
```kotlin
class NetworkViewModel(application: Application) : NetViewModel<NetworkRepository>(application) {
    val getRequestData = RequestLiveData<String>()
    val postRequestData = RequestLiveData<PostResponse>()

    // GET 请求
    fun doGetRequest() {
        mRepository?.doGetRequest(getRequestData)
    }

    // POST 请求
    fun doPostRequest(request: PostRequest) {
        mRepository?.doPostRequest(request, postRequestData)
    }

    // 下载请求
    fun doDownloadRequest(liveData: DownloadLiveData?) {
        mRepository?.doDownloadRequest(liveData)
    }

    // 上传请求
    fun doUploadRequest(liveData: UploadLiveData<String>) {
        mRepository?.doUploadRequest(liveData)
    }

}
```
##### `java 用例`
```java
public class NetworkViewModel extends NetViewModel<NetworkRepository> {
    RequestLiveData<String> getRequestData = new RequestLiveData<>();
    RequestLiveData<PostResponse> postRequestData = new RequestLiveData<>();

    // GET 请求
    void doGetRequest() {
        if (null != mRepository) {
            mRepository.doGetRequest(getRequestData);
        }
    }

    // POST 请求
    void doPostRequest(PostRequest request) {
        if (null != mRepository) {
            mRepository.doPostRequest(request, postRequestData);
        }
    }

    // 下载请求
    void doDownloadRequest(DownloadLiveData liveData) {
        if (null != mRepository) {
            mRepository.doDownloadRequest(liveData);
        }
    }

    // 上传请求
    void doUploadRequest(UploadLiveData<String> liveData) {
        if (null != mRepository) {
            mRepository.doUploadRequest(liveData);
        }
    }
}
```

#### `2. 创建供 ViewModel 使用的网络请求能力类`

##### `kotlin 用例`
```kotlin
class NetworkRepository(netImpl: NetRequestInterface) : NetRepository<NetworkServer>(netImpl) {

    // GET 请求
    fun doGetRequest(liveData: RequestLiveData<String>) {
        sendRequest(mServer.doGetRequest(), liveData)
    }

    // POST 请求
    fun doPostRequest(request: PostRequest, liveData: RequestLiveData<PostResponse>?) {
        sendRequest(mServer.doPostRequest(request), liveData)
    }

    // 下载请求
    fun doDownloadRequest(liveData: DownloadLiveData?) {
        downloadFile(mServer.doDownloadRequest(), liveData)
    }

    // 上传请求
    fun doUploadRequest(liveData: UploadLiveData<String>) {
        uploadFile(
            mServer.doUploadRequest(
                createUploadParams(liveData, keyFileName = "file", null, null)
            ),
            liveData
        )
    }
}
```
##### `java 用例`
```java
public class NetworkRepository extends NetRepository<NetworkServer> {

    // GET 请求
    public void doGetRequest(RequestLiveData<String> liveData) {
        sendRequest(mServer.doGetRequest(), liveData);
    }
    
    // POST 请求
    public void doPostRequest(PostRequest request, RequestLiveData<PostResponse> liveData) {
        sendRequest(mServer.doPostRequest(request), liveData);
    }

    // 下载请求
    public void doDownloadRequest(DownloadLiveData liveData) {
        downloadFile(mServer.doDownloadRequest(), liveData);
    }

    // 上传请求
    public void doUploadRequest(UploadLiveData<String> liveData) {
        uploadFile(mServer.doUploadRequest(
                        createUploadParams(liveData, "file", null, null)),
                        liveData);
    }
}
```

#### `3. 创建接口服务`

##### `kotlin 用例`
```kotlin
interface NetworkServer {

    // GET 请求
    @GET("test/getRequest")
    fun doGetRequest(): Observable<String>

    // POST 请求
    @POST("test/postRequest")
    fun doPostRequest(@Body request: PostRequest): Observable<PostResponse>

    // 下载请求
    @GET("test/downloadRequest")
    @Streaming
    fun doDownloadRequest(): Observable<ResponseBody>

    // 上传请求
    @POST("test/uploadRequest")
    @Multipart
    fun doUploadRequest(@Part parts: List<MultipartBody.Part>?): Observable<String>
}
```
##### `java 用例`
```java
public interface NetworkServer {

    // GET 请求
    @GET("test/getRequest")
    Observable<String> doGetRequest();

    // POST 请求
    @POST("test/postRequest")
    Observable<PostResponse> doPostRequest(@Body PostRequest request);

    // 下载请求
    @GET("test/downloadRequest")
    @Streaming
    Observable<ResponseBody> doDownloadRequest();

    // 上传请求
    @POST("test/uploadRequest")
    @Multipart
    Observable<String> doUploadRequest(@Part List<MultipartBody.Part> parts);
}
```

#### `4. 监听请求数据/上传下载调用`

##### `kotlin 用例`
```kotlin
override fun addDataObserver(viewModel: NetworkViewModel) {
    viewModel.getRequestData.observeRequest(this,
        object : RequestObserver<String>() {
            override fun onRequestResult(result: String) {
                // 更新页面
            }
    })
    viewModel.postRequestData.observeRequest(this,
        object : RequestObserver<PostResponse>() {
            override fun onRequestResult(result: PostResponse) {
                // 更新页面
            }
    })
}
// 文件下载
private fun downloadFile() {
    val downloadFile = File("文件下载路径")
    val liveData = DownloadLiveData(downloadFile)
    liveData.observeDownload(this,
        object : DownloadObserver() {
            override fun onDownloadFile(file: File) {
                // 处理文件
            }
        })
    mViewModel.doDownloadRequest(liveData)
}
// 文件上传
private fun uploadFile() {
    val file = File("上传文件路径")
    val liveData = UploadLiveData<String>(file)
    liveData.observeUpload(this, object : UploadObserver<String>() {
        override fun onUploadResult(result: String) {
            // 处理文件上传结果
        }
    })
    mViewModel.doUploadRequest(liveData)
}
```
##### `java 用例`
```java
public class NetFragment extends BaseLifecycleFragment<NetworkViewModel> {
    @Override
    protected void addDataObserver(@NonNull NetworkViewModel viewModel) {
        viewModel.getRequestData.observeRequest(this,
                new RequestObserver<String>(null, null) {
                    @Override
                    public void onRequestResult(String result) {
                        // 更新页面
                    }
                });
        viewModel.postRequestData.observeRequest(this,
                new RequestObserver<PostResponse>(null, null) {
                    @Override
                    public void onRequestResult(PostResponse response) {
                        // 更新页面
                    }
                });
    }
    // 文件下载
    private void downloadFile() {
        File downloadFile = new File("文件下载路径");
        DownloadLiveData liveData = new DownloadLiveData(downloadFile);
        liveData.observeDownload(this, new DownloadObserver(null) {
            @Override
            public void onDownloadFile(@NonNull File file) {
                // 处理文件
            }
        });
        mViewModel.doDownloadRequest(liveData);
    }
    // 文件上传
    private void uploadFile() {
        File file = new File("上传文件路径");
        UploadLiveData<String> liveData = new UploadLiveData<>(file, null);
        liveData.observeUpload(this, new UploadObserver<String>(null) {
            @Override
            public void onUploadResult(String result) {
                // 处理文件上传结果
            }
        });
        mViewModel.doUploadRequest(liveData);
    }
}
```

#### `初始化网络请求配置`

##### `kotlin 用例`
```kotlin
class CustomApplication : BaseApplication() {

    override fun onCreate() {
        super.onCreate()
        initHttpConfig()
    }

    private fun initHttpConfig() {
        RetrofitManager.getInstance().init(
            HttpConfig.Builder()
                .setBaseUrl("服务地址")
                .build())
    }
}
```
##### `java 用例`
```java
public class CustomApplication extends BaseApplication {
    
    @Override
    public void onCreate() {
        super.onCreate();
        initHttpConfig();
    }

    private void initHttpConfig() {
        RetrofitManager.Companion.getInstance().init(
                new HttpConfig.Builder()
                        .setBaseUrl("服务地址")
                        .build());
    }
}
```

#### `如何创建并操作数据库`

因为数据库框架使用的是 Room，因为 Room 使用了注解处理工具，所以在使用数据库的时候需要配置 kapt:
```groovy
plugins {
    id("org.jetbrains.kotlin.kapt")
}

kapt("androidx.room:room-compiler:xxx")
```
更高版本的 Room 更推荐使用编译速度更快的 ksp:
```groovy
plugins {
    id("id("com.google.devtools.ksp")")
}

ksp("androidx.room:room-compiler:xxx")
```

#### `1. 创建数据库 ViewModel`

##### `kotlin 用例`
```kotlin
class DBViewModel(application: Application) : DatabaseViewModel<DBRepository>(application) {
    val insertData = DatabaseLiveData<Long>()
    val deleteData = DatabaseLiveData<Int>()
    val updateData = DatabaseLiveData<Int>()
    val queryData = DatabaseLiveData<List<User>>()

    fun insertUser(user: User) {
        mRepository?.insertUser(user, insertData)
    }

    fun deleteUser(user: User) {
        mRepository?.deleteUser(user, deleteData)
    }

    fun updateUser(user: User) {
        mRepository?.updateUser(user, updateData)
    }

    fun queryUser() {
        mRepository?.queryUser(queryData)
    }

}
```
##### `java 用例`
```java
public class DBViewModel extends DatabaseViewModel<DBRepository> {
    public DatabaseLiveData<Long> insertData = new DatabaseLiveData<>();
    public DatabaseLiveData<Integer> deleteData = new DatabaseLiveData<>();
    public DatabaseLiveData<Integer> updateData = new DatabaseLiveData<>();
    public DatabaseLiveData<List<User>> queryData = new DatabaseLiveData<>();

    // 增
    public void insertUser(User user) {
        if (null != mRepository) {
            mRepository.insertUser(user, insertData);
        }
    }

    // 删
    public void deleteUser(User user) {
        if (null != mRepository) {
            mRepository.deleteUser(user, deleteData);
        }
    }

    // 改
    public void updateUser(User user) {
        if (null != mRepository) {
            mRepository.updateUser(user, updateData);
        }
    }

    // 查
    public void queryUser() {
        if (null != mRepository) {
            mRepository.queryUser(queryData);
        }
    }
}
```

#### `2. 创建供 ViewModel 使用的数据库能力类`

##### `kotlin 用例`
```kotlin
class DBRepository(impl: DatabaseInterface,
                   application: Application
) : DatabaseRepository<AppDatabase>(impl, application) {

    override fun addMigrations(builder: RoomDatabase.Builder<AppDatabase>) {
        builder.addMigrations(object : Migration(1, 2) {
            override fun migrate(database: SupportSQLiteDatabase) {
                // 处理数据库升降版本时的数据迁移或者表结构变更
            }
        })
    }

    override fun getDbName(): String {
        return "定义数据库DB文件名称"
    }

    // 增
    fun insertUser(user: User, liveData: DatabaseLiveData<Long>) {
        execute(mDb.userDao().insert(user), liveData)
    }

    // 删
    fun deleteUser(user: User, liveData: DatabaseLiveData<Int>) {
        execute(mDb.userDao().delete(user), liveData)
    }

    // 改
    fun updateUser(user: User, liveData: DatabaseLiveData<Int>) {
        execute(mDb.userDao().update(user), liveData)
    }

    // 查
    fun queryUser(liveData: DatabaseLiveData<List<User>>) {
        execute(mDb.userDao().query(), liveData)
    }

}
```
##### `java 用例`
```java
public class DBRepository extends DatabaseRepository<AppDatabase> {
    @Override
    protected String getDbName() {
        return "定义数据库DB文件名称";
    }

    @Override
    protected void addMigrations(@NonNull RoomDatabase.Builder<AppDatabase> builder) {
        builder.addMigrations(new Migration(1, 2) {
            @Override
            public void migrate(@NonNull SupportSQLiteDatabase database) {
                // 处理数据库升降版本时的数据迁移或者表结构变更
            }
        });
    }

    // 增
    public void insertUser(User user, DatabaseLiveData<Long> liveData) {
        execute(mDb.userDao().insert(user), liveData);
    }

    // 删
    public void deleteUser(User user, DatabaseLiveData<Integer> liveData) {
        execute(mDb.userDao().delete(user), liveData);
    }

    // 改
    public void updateUser(User user, DatabaseLiveData<Integer> liveData) {
        execute(mDb.userDao().update(user), liveData);
    }

    // 查
    public void queryUser(DatabaseLiveData<List<User>> liveData) {
        execute(mDb.userDao().query(), liveData);
    }
}
```

#### `3. 自定义数据库`

##### `kotlin 用例`
```kotlin
@Database(
    entities = [ User::class ], // 表结构
    version = Config.VERSION,   // 数据库的版本
    exportSchema = false        // 是否需要生成 Schema 文件
)
abstract class AppDatabase :  RoomDatabase() {

    abstract fun userDao(): UserDao // 访问和操作表的对象

}
```
##### `java 用例`
```java
@Database(
        entities = { User.class }, // 表结构
        version = Config.VERSION,  // 数据库的版本
        exportSchema = false       // 是否需要生成 Schema 文件
)
public abstract class AppDatabase extends RoomDatabase {

    public abstract UserDao userDao(); // 访问和操作表的对象

}
```

#### `4. 自定义表结构以及访问表的对象`

##### `kotlin 用例`
```kotlin
@Entity
data class User(

    @PrimaryKey(autoGenerate = true)
    val id: Long?,

    /**
     * 姓名
     */
    @ColumnInfo(name = "nick_name") // 实体对象的名称可以和对应表的列名不同
    val name: String,

    /**
     * 年龄
     */
    val age: Int

)
@Dao
interface UserDao {
    /**
     * 插入用户
     */
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    fun insert(user: User): Single<Long>

    /**
     * 删除用户
     */
    @Delete
    fun delete(user: User): Single<Int>

    /**
     * 修改用户
     */
    @Update
    fun update(user: User): Single<Int>

    /**
     * 查询用户
     */
    @Query("SELECT * FROM User where name = 'Peter'")
    fun query(): Single<List<User>>
}
```
##### `java 用例`
```java
@Entity
public class User {

    @PrimaryKey(autoGenerate = true)
    private long id;

    /**
     * 姓名
     */
    @ColumnInfo(name = "nick_name") // 实体对象的名称可以和对应表的列名不同
    private String name;

    /**
     * 年龄
     */
    private int age;

    // 省略 getter/setter
}
@Dao
public interface UserDao {
    /**
     * 插入用户
     */
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    Single<Long> insert(User user);

    /**
     * 删除用户
     */
    @Delete
    Single<Integer> delete(User user);

    /**
     * 修改用户
     */
    @Update
    Single<Integer> update(User user);

    /**
     * 查询用户
     */
    @Query("SELECT * FROM User where name = 'Peter'")
    Single<List<User>> query();
}
```

#### `5. 操作数据库并监听结果`

##### `kotlin 用例`
```kotlin
class DBFragment : BaseLifecycleFragment<DBViewModel>() {
    override fun addDataObserver(viewModel: DBViewModel) {
        viewModel.insertData.observeExecute(this, object : DatabaseObserver<Long>() {
            override fun onExecuteResult(result: Long) {
                // 若 result > 0，插入新数据成功
            }
        })
        viewModel.deleteData.observeExecute(this, object : DatabaseObserver<Int>() {
            override fun onExecuteResult(result: Int) {
                // 若 result > 0, 则删除数据成功
            }
        })
        viewModel.updateData.observeExecute(this, object : DatabaseObserver<Int>() {
            override fun onExecuteResult(result: Int) {
                // 若 result > 0, 则更新数据成功
            }
        })
        viewModel.queryData.observeExecute(this, object : DatabaseObserver<List<User>>() {
            override fun onExecuteResult(result: List<User>) {
                // 处理查询到的数据
            }
        })
        viewModel.insertUser() // 新增数据
        viewModel.deleteUser() // 删除数据
        viewModel.updateUser() // 更改数据
        viewModel.queryUser()  // 查询数据
    }
}
```
##### `java 用例`
```java
public class DBFragment extends BaseLifecycleFragment<DBViewModel> {
    @Override
    protected void addDataObserver(@NonNull DBViewModel viewModel) {
        viewModel.insertData.observeExecute(this, new DatabaseObserver<Long>() {
            @Override
            public void onExecuteResult(Long result) {
                // 若 result > 0，插入新数据成功
            }
        });
        viewModel.deleteData.observeExecute(this, new DatabaseObserver<Integer>() {
            @Override
            public void onExecuteResult(Integer result) {
                // 若 result > 0, 则删除数据成功
            }
        });
        viewModel.updateData.observeExecute(this, new DatabaseObserver<Integer>() {
            @Override
            public void onExecuteResult(Integer result) {
                // 若 result > 0, 则更新数据成功
            }
        });
        viewModel.queryData.observeExecute(this, new DatabaseObserver<List<User>>() {
            @Override
            public void onExecuteResult(List<User> result) {
                // 处理查询到的数据
            }
        });
        viewModel.insertUser(); // 新增数据
        viewModel.deleteUser(); // 删除数据
        viewModel.updateUser(); // 更改数据
        viewModel.queryUser();  // 查询数据
    }
}
```


### `common-ui`

通用组件模块，在 mvvm 的基础上进一步封装了常用的组件，同时也集成了一些优秀的第三方组件。
该模块适用于不仅想使用 MVVM 搭建项目，还可以快速集成一些通用的 UI 组件，便于项目快速开发的开发者。

因为 common-ui 默认使用 ViewBinding 绑定布局文件，所以项目里必须开启以下配置：
```groovy
buildFeatures {
    viewBinding = true
}
```
初始化 common-ui 配置：
```java
public class DemoApplication extends BaseApplication {
    private void initCu() {
        Cu.init(new CuConfig.Builder()
                .setOpenConsole(true) // 是否打开控制台
                .setHttpConfig(new HttpConfig.Builder() // 网络请求配置
                        .setBaseUrl(BASE_URL)  // 服务地址
                        .build())
                .setRefreshConfig(new CommonRefreshUiConfig.Builder()  // 下拉刷新配置
                        .setHeadBgColorId()  // 下拉头背景颜色
                        .setHeadEnableLastTime(false) // 下拉头是否需要显示上次刷新时间
                        .build())
                .setAutoSizeConfig(new CommonAutoSizeConfig.Builder()  // 分辨率适配配置
                        .setBaseOnWidth(true) // 　是否根据宽度适配
                        .setAutoSizeWidth(DESIGN_WIDTH)  // 设计稿宽度， 默认 375
                        .setAutoSizeHeight(DESIGN_HEIGHT) // 设计稿高度， 默认 667
                        .build())
                .setStatusHandleCls()  // 自定义网络请求状态处理（弹框效果）
                .setAdapterStatusHandleCls() // 自定义 recyclerView 在无网络、空数据下的显示效果
                .build());
    }
}
```

common-ui 模块总体包含了以下功能：
- `Console`：控制台（包含网络请求/通用日志）
- `CommonActivity`：ViewBinding 布局绑定、沉浸式状态栏/导航栏、autoSize 分辨率适配等实现
- `CommonFragment`：实现 ViewBinding 布局绑定
- `CommonQuickAdapter`：通用 RecyclerView 适配器
- `CommonRefreshActivity/CommonRefreshFragment`：下拉刷新/上拉加载
- `CommonPagingFragment`: 实现分页效果

#### `如何开启和使用控制台`

##### `1. 请确保在初始化配置的时候已打开控制台`
##### `2. 因为控制台是以悬浮框的形式存在，所以需配置以下权限，并确保设置应用可以显示在其他应用的上层`
```xml
<manifest>
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
    <uses-permission android:name="android.permission.SYSTEM_OVERLAY_WINDOW"/>
</manifest>
```
##### `3. 如何输出日志到控制台`
```text
Console.log("输出日志到控制台");
```

#### `定制化 CommonActivity`

##### `1. 初始化 ViewBinding`
当开启 ViewBinding 配置后，一般情况下只需要在 CommonActivity 的泛型参数里配置对应布局的生成类即可自动初始化，
如果有特殊需要也可以复写 initViewBinding 方法手动进行初始化，初始化完成后，即可在 initView 方法里使用 mBinding 直接访问布局对象。

##### `kotlin 用例`
```kotlin
class MainActivity : CommonActivity<ActivityMainBinding, MainViewModel>() {
    
    override fun initView(savedInstanceState: Bundle?) {
        mBinding.tvTest.text = "测试"
    }
    
}
```
##### `java 用例`
```java
public class MainActivity extends CommonActivity<ActivityMainBinding, MainViewModel> {
    
    @Override
    protected void initView(@Nullable Bundle savedInstanceState) {
        mBinding.tvText.setText("测试");
    }
    
}
```

##### `2. 沉浸式状态栏/导航栏`

kotlin 和 java 用法一致，复写方法并返回期望值，下面只给出 java 用例：
```java
public class MainActivity extends CommonActivity<ActivityMainBinding, MainViewModel> {

    // 设置状态栏文字深色（默认为 false）
    @Override
    protected boolean isStatusDark() {
        return true;
    }

    // 设置内容是否在状态栏区域下（默认为 true）
    @Override
    protected boolean isStatusFitWindow() {
        return false;
    }

    // 设置状态栏背景色（默认为透明色）
    @Override
    protected int getStatusBgColor() {
        return ResourcesCompat.getColor(getResources(), R.color.title_bg_color, null);
    }

    // 设置导航栏浅色（默认为 true）
    @Override
    protected boolean isNavigationLight() {
        return false;
    }

    // 设置内容是否在导航栏区域上（默认为 false）
    @Override
    protected boolean isNavigationFitWindow() {
        return true;
    }

    // 设置导航栏背景色（默认透明）
    @Override
    protected int getNavigationBgColor() {
        return ResourcesCompat.getColor(getResources(), R.color.content_bg_color, null);
    }
}
```

##### `3. autoSize分辨率适配`

分辨率适配的目的是为了保证在各手机分辨率上都可以还原设计稿。
Cu.init 里可以设置设计稿的宽和高，默认为 375 x 667，这里的单位是设备独立像素，也就是安卓里的dp。
需要注意的是，开启分辨率适配后，在某些需要横竖屏切换的页面使用dp可能会存在一些问题，下面会给出不开启分辨率适配的方法。

##### `kotlin 用例`
```kotlin
// 继承 CommonActivityCancelAdapt，则不使用分辨率适配方案
class MainActivity : CommonActivityCancelAdapt<ActivityMainBinding, MainViewModel>() {
    // 同时可以对单个页面进行定制化适配，比如有的页面只希望在屏幕高度区域内展示，那则可以适配设计稿高度
    override fun isBaseOnWidth(): Boolean {
        return false // 适配高度
    }

    override fun getSizeInDp(): Float {
        return 1024f // 返回当前页面的设计稿尺寸（根据适配宽度/高度返回具体数值）
    }
}
```
##### `java 用例`
```java
// 继承 CommonActivityCancelAdapt，则不使用分辨率适配方案
public class MainActivity extends CommonActivityCancelAdapt<ActivityMainBinding, MainViewModel> {
    // 同时可以对单个页面进行定制化适配，比如有的页面只希望在屏幕高度区域内展示，那则可以适配设计稿高度
    @Override
    public boolean isBaseOnWidth() {
        return false; // 适配高度
    }

    @Override
    public float getSizeInDp() {
        return 1024f; // 返回当前页面的设计稿尺寸（根据适配宽度/高度返回具体数值）
    }
}
```

##### `4. 定制化标题栏`

定制化标题栏的初衷是为了让有返回按钮的标题栏页面，无需去重复处理返回按钮事件，让代码可以更加简洁。
使用方式为自定义标题栏 View，继承 CommonTitleView，同时在布局中使用即可。

#### `定制化 CommonFragment`

ViewBinding 使用方式同 CommonActivity，这里不再赘述。

#### `如何使用 CommonQuickAdapter`

CommonQuickAdapter 的目的是为了让在使用 RecyclerView 时可以更加便捷快速的使用适配器。
CommonQuickAdapter 同样以 ViewBinding 来绑定布局文件，增加开发效率。

##### `1. 如何构造 CommonQuickAdapter`

##### `kotlin 用例`
```kotlin
class MainActivity : CommonActivity<ActivityMainBinding, MainViewModel>() {
    override fun initView(savedInstanceState: Bundle?) {
        // 1. mBinding.rvContent 为需要使用快速适配器的 RecyclerView
        // 2. ItemViewBinding 为列表 item 对应的布局
        // 3. ItemData 为列表 item 对应的数据项
        // 4. dataList 为整个数据列表
        mBinding.rvContent.adapter = object : CommonQuickAdapter<ItemViewBinding, ItemData>(dataList) {
            override fun convert(binding: ItemViewBinding, data: ItemData, position: Int) {
                // 处理 item 布局以及对应 item 数据
            }

            override fun onItemClick(data: ItemData, position: Int) {
                // 处理 item 点击的回调
            }
        }
    }
}
```
##### `java 用例`
```java
public class MainActivity extends CommonActivity<ActivityMainBinding, MainViewModel> {
    @Override
    protected void initView(@Nullable Bundle savedInstanceState) {
        // 1. mBinding.rvContent 为需要使用快速适配器的 RecyclerView
        // 2. ItemViewBinding 为列表 item 对应的布局
        // 3. ItemData 为列表 item 对应的数据项
        // 4. dataList 为整个数据列表
        mBinding.rvContent.setAdapter(new CommonQuickAdapter<ItemViewBinding, ItemData>(dataList) {

            @Override
            protected void convert(@NonNull ItemViewBinding binding, ItemData data, int position) {
                // 处理 item 布局以及对应 item 数据
            }

            @Override
            protected void onItemClick(ItemData data, int position) {
                // 处理 item 点击的回调
            }
        });
    }
}
```

##### `2. 使用 CommonQuickAdapter 内部方法`

- `addData`：添加数据
- `removeData`：删除数据
- `clearData`：清空数据
- `setEmptyView`：设置空视图


##### `3. 使用通用装饰器`

- `CommonDividerDecoration`：分割线装饰器
- `CommonGridSpaceDecoration`：网格装饰器


#### `如何使用 CommonRefreshActivity/CommonRefreshFragment 实现下拉刷新/上拉加载`

CommonRefreshActivity 和 CommonRefreshFragment 用法相似，这里只以 CommonRefreshFragment 为例。

##### `1. 无需自定义页面`
```kotlin
class RefreshFragment : CommonRefreshFragment<LayoutCuRefreshBinding, NulViewModel>() {

    override fun onRefreshConfig(build: CommonRefreshConfig.Builder) {
        build.apply {
            setEnableRefresh(true) // 开启上拉刷新
            setEnableLoadMore(true) // 开启下拉加载
        }
    }

    override fun onRefresh(refreshLayout: RefreshLayout) {
        // 上拉刷新触发回调
    }

    override fun onLoadMore(refreshLayout: RefreshLayout) {
        // 下拉加载触发回调
    }

}
```

##### `2. 自定义页面`
```xml
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">

    <!-- 自定义布局必须包含 -->
    <include
        layout="@layout/layout_cu_refresh_merge">
    </include>

</LinearLayout>
```

#### `如何使用 CommonPagingFragment 构造分页页面`

##### `kotlin 用例`
```kotlin
// CommonPagingFragment 泛型的4个参数含义分别为：
// 1. 页面布局，使用方式同 CommonRefreshFragment
// 2. 页面对应 ViewModel
// 3. 列表项布局
// 4. 列表项数据类型
class RefreshLoadPagingFragment : CommonPagingFragment<LayoutCuRefreshBinding, NulViewModel, ItemQuickAdapterBinding, Int>() {

    /**
     * 获取每页的数据回调
     */
    override fun getPageData(page: Int) {
        // 获取到数据后调用该方法
        doPagingResult(list)
    }

    /**
     * 获取总页数
     */
    override fun getTotalPage(): Int {
        return PAGE_COUNT
    }

    /**
     * 对recycleView进行自定义
     */
    override fun setRecyclerView(recyclerView: RecyclerView) {

    }

    /**
     * 渲染列表项
     */
    override fun convert(viewBinding: ItemQuickAdapterBinding, data: Int, position: Int) {

    }
}
```
##### `java 用例`
```java
// CommonPagingFragment 泛型的4个参数含义分别为：
// 1. 页面布局，使用方式同 CommonRefreshFragment
// 2. 页面对应 ViewModel
// 3. 列表项布局
// 4. 列表项数据类型
public class RefreshLoadPagingFragment extends CommonPagingFragment<LayoutCuRefreshBinding, NulViewModel, ItemQuickAdapterBinding, Integer> {
    /**
     * 获取每页的数据回调
     */
    @Override
    protected void getPageData(int page) {
        // 获取到数据后调用该方法
        doPagingResult(list);
    }

    /**
     * 获取总页数
     */
    @Override
    protected int getTotalPage() {
        return PAGE_COUNT;
    }

    /**
     * 对recycleView进行自定义
     */
    @Override
    protected void setRecyclerView(@NonNull RecyclerView recyclerView) {
        
    }

    /**
     * 渲染列表项
     */
    @Override
    protected void convert(@NonNull ItemQuickAdapterBinding viewBinding, Integer data, int position) {
        
    }
}
```


### `fast-ui`

快速组件模块，在 common-ui 的基础上添加了 UI 样式，只有在该模块才会存在资源文件，包含 common-ui 的所有功能。
该模块存在的意义是为了不介意 UI 样式被介入，可以更加快速的开发业务模块的开发者。
目前快速组件的功能还有限，后续会持续更新，目前已有的功能包含：

- `网络请求/上传下载弹窗`
- `RecyclerView 空数据/无网络等提示页面`
- `应用升级弹窗提示`

fast-ui 的使用配置方式和 common-ui 相似，只需把 Cu.init 修改成 Fu.init 即可。

#### `如何可以让网络请求/上传下载出现窗口提示`

上述有网络请求的具体用法，这里只列出如何在上述用法的基础上，显示弹窗：
- `RequestObserver`： 参数1传入this；参数2传入想显示的弹窗文字id，默认为null
- `DownloadObserver`：参数传入this则显示
- `UploadObserver`：参数传入this则显示

#### `如何快速升级`

##### `kotlin 用例`
```kotlin
val builder =  FuUpdateConfig.Builder()
        builder.setTitle("配置升级标题")
                .setVersion("配置升级版本")
                .setContent("配置升级具体内容")
        // 最后在显示升级框前还需要配置获取升级包的接口（文件流下载）
        Fu.showUpdateDialog(builder.build(mViewModel.getUpdateServer(), this))
```
##### `java 用例`
```java
public class UpdateActivity extends CommonTitleActivity<LayoutUpdateBinding, UpdateViewModel> {
    
    private void showUpdateDialog() {
        FuUpdateConfig.Builder builder = new FuUpdateConfig.Builder();
        builder.setTitle("配置升级标题")
                .setVersion("配置升级版本")
                .setContent("配置升级具体内容");
        // 最后在显示升级框前还需要配置获取升级包的接口（文件流下载）
        Fu.showUpdateDialog(builder.build(mViewModel.getUpdateServer(), this));
    }
    
}
```

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建新分支 (`git checkout -b feature/new-feature`)
3. 提交更改 (`git commit -am 'Add new feature'`)
4. 推送分支 (`git push origin feature/new-feature`)
5. 提交 Pull Request

## 许可证

本项目采用 MIT License，请参阅 [LICENSE](LICENSE) 文件了解详细信息。

--- 

如果有定制化的需求可联系作者（13915948827）。