Android开发指南：全面解析各类文件选择器的实现方法

Android开发指南：全面解析各类文件选择器的实现方法

1、概述

在Android应用中集成文件选择功能是现代APP的基础需求之一。本文将详细介绍如何实现多种类型的文件选择器，包括系统原生方案和第三方库解决方案。

2、照片/媒体选择器

2.1、使用Intent调用系统相册

这是最简单直接的图片选择方式：

fun openGallery(isMulti: Boolean = false): Intent {
        return Intent(Intent.ACTION_PICK).apply {
            type = "image/*"
            putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("image/jpeg", "image/png"))
            putExtra(Intent.EXTRA_ALLOW_MULTIPLE, isMulti)     //是否多选
        }
    }

        launcher = registerForActivityResult(register, object : ActivityResultCallback<ActivityResult> {
            override fun onActivityResult(result: ActivityResult) {
                Log.i(TAG, "onActivityResult ${result.resultCode}")
                if (result.resultCode == Activity.RESULT_OK) {
                    result.data?.let {
                        val cnt = it.clipData?.itemCount ?: 0
                        //单个文件在it.data，多个文件在it.clipData
                        for (i in 0 until cnt) {
                            val item = it.clipData?.getItemAt(i)
                            Log.i(TAG, "clipData 文件 uri:${item?.uri}")
                            binding.text.append("已选择文件:${item?.uri}\n")
                            fileUri = item?.uri
                        }
                    }
                }
            }
        })

2.2、使用PhotoPicker API

Android 13引入了专门的PhotoPicker API（Android 13+新特性）：

fun launchModernPhotoPicker() {
    val pickMedia = PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageOnly)
        .build()

    registerForActivityResult(PickVisualMedia()) { uri ->
        // 处理返回的URI
    }.launch(pickMedia)
}

// 必须在Activity/Fragment的init阶段注册回调
class MainActivity : AppCompatActivity() {
    private val photoPickerLauncher = registerForActivityResult(PickVisualMedia()) { uri ->
        uri?.let { handleImage(it) }
    }




        visualPickLauncher = registerForActivityResult(ActivityResultContracts.PickVisualMedia()) { uri ->
            Log.i(TAG, "photoLauncher onActivityResult 已选择 照片 uri:$uri")
        }
        /**
         * PhotoPicker选择照片(单选)
         */
        binding.selectPhotoPicker.setThrottleClickListener {
            Log.i(TAG, "onClick: 选择图片")
            val pickMedia = PickVisualMediaRequest.Builder()
                .setMediaType(ActivityResultContracts.PickVisualMedia.ImageOnly)

                .build()
            visualPickLauncher?.launch(pickMedia)
        }



        pickMultipleMediaLauncher = registerForActivityResult(ActivityResultContracts.PickMultipleVisualMedia(5)) { uris ->
            // Callback is invoked after the user selects media items or closes the
            // photo picker.
            if (uris.isNotEmpty()) {
                Log.d(TAG, "Number of items selected: ${uris.size}")
                uris.forEach {
                    Log.d(TAG, "Selected: $it")
                }
            } else {
                Log.d(TAG, "No media selected")
            }
        }

        /**
         * PhotoPicker选择照片(多选)
         */
        binding.multiSelectPhotoPicker.setThrottleClickListener {
            Log.i(TAG, "onClick: 选择多图片")
            val pickMedia = PickVisualMediaRequest.Builder()
                .setMediaType(ActivityResultContracts.PickVisualMedia.ImageOnly)
                .setMaxItems(5)     
    .build()
            pickMultipleMediaLauncher?.launch(pickMedia)
        }

3、通用文件选择器

3.1、基本文件选择实现

fun selectFile() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "*/*" // 所有文件类型
        addCategory(Intent.CATEGORY_OPENABLE)
    }
    startActivityForResult(intent, REQUEST_FILE_SELECT)
}

3.2、设置特定文件类型筛选

要限定只能选择Word文档(.doc/.docx):

fun selectWordDocument() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "application/msword"
        putExtra(Intent.EXTRA_MIME_TYPES, arrayOf(
            "application/msword",
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        ))
    }
    startActivityForResult(intent, REQUEST_WORD_DOCUMENT)
}

4、目录选择器

4.1、使用Storage Access Framework

适用于API 21及以上版本：

fun selectDirectory() {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT_TREE).apply {
        flags = Intent.FLAG_GRANT_READ_URI_PERMISSION or
                Intent.FLAG_GRANT_WRITE_URI_PERMISSION
    }
    startActivityForResult(intent, REQUEST_DIRECTORY_SELECT)
}

4.2、高级用法

多文件选择，允许用户一次选择多个文件：

fun selectMultipleFiles() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "/"
        putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
    }
    startActivityForResult(intent, REQUEST_MULTIPLE_FILES)
}

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user select up to 5 media files.
val pickMultipleMedia =
        registerForActivityResult(PickMultipleVisualMedia(5)) { uris ->
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (uris.isNotEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: ${uris.size}")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// For this example, launch the photo picker and let the user choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

自定义文件过滤器，结合DocumentsProvider实现更复杂的过滤：

val filter = arrayOf(
    "application/pdf",          // PDF文件
    "text/plain",              // 文本文件
    "application/vnd.ms-excel" // Excel文件
)
intent.putExtra(Intent.EXTRA_MIME_TYPES, filter)

5、权限处理要点

运行时权限：确保已申请READ_EXTERNAL_STORAGE权限

URI权限持久化：使用takePersistableUriPermission保存长期访问权

ContentResolver查询：正确处理返回的URI内容

6、兼容性考虑

对于旧版Android，考虑使用第三方库如：

        Matisse（图片选择）

        FilePicker（通用文件选择）

        Android-FilePicker

        处理不同厂商ROM的可能差异

以上实现方案覆盖了大多数常见的文件选择场景，开发者可根据具体需求选择合适的实现方式。