在iielse/imageviewer项目中实现全屏图片预览延伸到状态栏的技术方案

背景介绍

在Android应用开发中，图片查看器是一个常见的功能需求。iielse/imageviewer作为一个优秀的开源图片查看器组件，提供了丰富的功能和灵活的定制选项。其中，全屏图片预览功能是用户经常使用的核心功能之一。然而，在实际开发过程中，开发者可能会遇到全屏预览时无法延伸到状态栏的问题，导致顶部出现黑色区域，影响视觉体验。

问题分析

全屏预览时无法延伸到状态栏的问题通常源于以下几个方面：

1. 系统Window属性设置不当
2. 状态栏透明化处理不完整
3. 不同Android版本兼容性问题
4. 主题样式配置冲突

解决方案

1. 基础配置

首先，确保在应用的Activity主题中正确设置了状态栏透明属性：

<style name="Base.Theme.APP" parent="Theme.Material3.Light.NoActionBar">
    <item name="colorPrimary">@color/colorPrimary</item>
    <item name="colorPrimaryDark">@color/colorPrimaryDark</item>
    <item name="android:windowLightStatusBar">true</item>
    <item name="android:statusBarColor">#00000000</item>
</style>

2. 动态设置Window属性

创建一个工具类来动态设置Window属性，确保在不同Android版本上都能正确工作：

object StatusBarUtils {
    private const val SYSTEM_UI_FLAG_LIGHT_STATUS_BAR = 0x00002000
    private const val SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR = 0x00000010

    private fun setWindowFlag(activity: Activity, bits: Int, on: Boolean) {
        val win = activity.window
        val winParams = win.attributes
        if (on) {
            winParams.flags = winParams.flags or bits
        } else {
            winParams.flags = winParams.flags and bits.inv()
        }
        win.attributes = winParams
    }

    @SuppressLint("ObsoleteSdkInt")
    fun update(
        activity: Activity,
        statusBarTranslucent: Boolean,
        navigationBarTranslucent: Boolean,
        statusBarLightMode: Boolean,
        navigationBarLightMode: Boolean
    ) {
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.KITKAT &&
            android.os.Build.VERSION.SDK_INT < android.os.Build.VERSION_CODES.LOLLIPOP
        ) {
            if (statusBarTranslucent) {
                setWindowFlag(activity, WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS, true)
            }
            if (navigationBarTranslucent) {
                setWindowFlag(
                    activity,
                    WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION,
                    true
                )
            }
        }
        
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.LOLLIPOP) {
            if (statusBarTranslucent) {
                setWindowFlag(activity, WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS, false)
            }
            activity.window.statusBarColor = android.graphics.Color.TRANSPARENT

            if (navigationBarTranslucent) {
                setWindowFlag(
                    activity,
                    WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION,
                    false
                )
            }
            activity.window.navigationBarColor = android.graphics.Color.TRANSPARENT
            if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.P) {
                activity.window.navigationBarDividerColor = android.graphics.Color.TRANSPARENT
            }
        }

        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.LOLLIPOP) {
            activity.windowDecorView?.systemUiVisibility =
                View.SYSTEM_UI_FLAG_VISIBLE.let { 
                    var result = it
                    if (statusBarTranslucent) result =
                        result or View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
                    if (navigationBarTranslucent) result =
                        result or View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
                    if (statusBarLightMode) result = result or SYSTEM_UI_FLAG_LIGHT_STATUS_BAR

                    if (android.os.Build.VERSION.SDK_INT < android.os.Build.VERSION_CODES.M) {
                        if (statusBarLightMode) result =
                            result or SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR
                    }

                    if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
                        if (navigationBarLightMode) result =
                            result or View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR
                    }
                    result
                }
        }
    }
}

3. 在Activity中应用设置

在需要全屏显示的Activity中调用上述工具类：

StatusBarUtils.update(
    this, 
    statusBarTranslucent = true, 
    navigationBarTranslucent = true,
    statusBarLightMode = false, 
    navigationBarLightMode = false
)

4. 自定义DialogFragment

对于使用DialogFragment实现的图片查看器，需要重写onCreateDialog方法：

class FullScreenImageViewerDialogFragment : ImageViewerDialogFragment() {
    override fun onCreateDialog(savedInstanceState: Bundle?): Dialog {
        return Dialog(requireActivity(), android.R.style.Theme_Black_NoTitleBar_Fullscreen).apply {
            setCanceledOnTouchOutside(true)
            window?.let { window ->
                window.setLayout(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
                window.setBackgroundDrawable(ColorDrawable(Color.TRANSPARENT))
                window.addFlags(WindowManager.LayoutParams.FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS)
                window.statusBarColor = Color.TRANSPARENT
                window.decorView.systemUiVisibility = (View.SYSTEM_UI_FLAG_LAYOUT_STABLE
                        or View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN)
            }
        }
    }
}

兼容性考虑

由于不同Android版本和不同厂商ROM对状态栏的处理方式存在差异，开发者需要注意以下几点：

1. Android 4.4 (KitKat) 和 Android 5.0 (Lollipop) 的状态栏透明化实现方式不同
2. 部分厂商ROM可能会覆盖系统默认的状态栏行为
3. 深色和浅色状态栏图标的适配问题
4. 全面屏设备的特殊处理

最佳实践

1. 在项目中使用统一的工具类处理状态栏相关逻辑
2. 针对不同Android版本进行差异化处理
3. 在DialogFragment和Activity中分别处理Window属性
4. 提供开关让用户可以动态切换全屏模式
5. 测试不同厂商设备上的表现

总结

通过上述方案，开发者可以在iielse/imageviewer项目中实现完美的全屏图片预览效果，使图片内容能够延伸到状态栏区域，提供更加沉浸式的用户体验。关键在于正确处理Window属性和状态栏设置，并考虑不同Android版本的兼容性问题。

实现这一功能后，图片查看器将能够充分利用设备的整个屏幕空间，消除顶部黑色状态栏区域，为用户提供更加美观和专业的视觉体验。