FileOperator Android Library

When file selection exceeds preset constraints (such as maximum quantity or maximum file size), you can choose between two strategies:

1. OVER_LIMIT_EXCEPT_ALL: If the limits are exceeded, the operation fails immediately and triggers the onError callback.
2. OVER_LIMIT_EXCEPT_OVERFLOW: If limits are exceeded, the system attempts to recover:
   • If the limit is exceeded by quantity or size: It keeps the files that do not exceed the limits and discards the overflowing ones.
   • If the limit is exceeded by type: It keeps the correct file types and discards all files of the incorrect type.
   • This strategy triggers the onSuccess callback with the valid subset of files.

To use FileOperator, add mavenCentral() and the Sonatype public repository to your project's build.gradle. You can then include the core library, the file selector, and the image compressor. Note that the core library is required for all features.

repositories {
   mavenCentral()
   maven { url "https://s01.oss.sonatype.org/content/groups/public" }
}

implementation 'com.github.javakam:file.core:3.9.8@aar'      //核心库必选(Core library required)
implementation 'com.github.javakam:file.selector:3.9.8@aar'  //文件选择器(File selector)
implementation 'com.github.javakam:file.compressor:3.9.8@aar'//图片压缩,修改自Luban(Image compression, based on Luban)

To process the results of a file selection request, you must pass the onActivityResult parameters to the FileSelector instance. It is recommended to use a specific requestCode (e.g., REQUEST_CHOOSE_FILE) to distinguish file selection results from other activity results.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
   super.onActivityResult(requestCode, resultCode, data)

   // Pass the selection result to FileSelector, distinguishing via requestCode
   mFileSelector?.obtainResult(requestCode, resultCode, data)
}

Call FileOperator.init within your Application class to set up the library. Pass the application context and a boolean indicating if the app is in debug mode (e.g., BuildConfig.DEBUG).

FileOperator.init(this, BuildConfig.DEBUG)

The ImageCompressor class provides a builder-based API to compress images asynchronously or synchronously. You can load images via String paths, File objects, or Uri objects.

Asynchronous Compression

Use .launch() to start a background compression process. You must provide an OnImageCompressListener to receive progress and results.

Synchronous Compression

Use .get() to perform compression on the current thread and return a list of compressed Uri objects.

After launching the file picker, you must pass the results from onActivityResult (or the equivalent ActivityResult callback) back to the FileSelector instance using obtainResult to trigger the configured FileSelectCallBack.

// In your Activity or Fragment
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // 'fileSelector' is the instance created via FileSelector.with(...)
    fileSelector.obtainResult(requestCode, resultCode, data)
}

To use FileSelector, start by calling FileSelector.with(context) or FileSelector.with(fragment). This returns a Builder instance used to configure selection constraints such as file types, counts, and size limits. Once configured, call .choose() to launch the file picker.

Note: If you are using modern Android ActivityResultLauncher, pass it to the with method to ensure compatibility with the new API.

If you encounter W / ExifInterface: Invalid image : ExifInterface got an unsupported image format, it is likely due to using the platform's default android.media.ExifInterface.

To fix this, use the AndroidX ExifInterface library which supports a wider range of formats and handles corrupted files more gracefully.

1. Add the dependency to your build.gradle:
2. Replace all imports of android.media.ExifInterface with androidx.exifinterface.media.ExifInterface.

dependencies {
    compileOnly "androidx.exifinterface:exifinterface:1.3.2"
    ...
}

When using FileSelector, you must ensure that the requestCode used in setRequestCode() matches the requestCode received in obtainResult().

Starting from version v3.9.8, if these values do not match, the library will trigger an error callback via mFileSelectCallBack?.onError() with the following error message:

"请比较 setRequestCode() 和 obtainResult() 方法中的 requestCode 值是否一致!(Please compare whether the requestCode values in setRequestCode() and obtainResult() methods are consistent!)"

Note that the default requestCode for FileSelector is 1 (val REQUEST_CODE_DEFAULT: Int = 1).