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

2025-07-03 12:23:31作者：薛曦旖Francesca

背景介绍

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

问题分析

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

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

解决方案

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)
            }
        }
    }
}