PAYATHON 2026

Maui 应用如何在 Samsung 设备上启用 Fullscreen Mode?

排障赵师傅

Android 的沉浸式模式可以隐藏 Samsung 设备上的状态栏和导航栏。你当前的代码在设置全屏后,又调用了 Show() 显示这两个系统栏,应改用 WindowInsetsControllerCompat.Hide() 隐藏它们。

Samsung 的“全屏应用”设置涉及应用的宽高比适配。修改窗口 flags 无法保证应用出现在该列表中,使用沉浸式全屏也不需要先进入这个列表。

现有代码有哪些问题?

Window.SetFlags(
    WindowManagerFlags.Fullscreen,
    WindowManagerFlags.Fullscreen);

Window.InsetsController.Show(WindowInsets.Type.StatusBars());
Window.InsetsController.Show(WindowInsets.Type.NavigationBars());

WindowManagerFlags.Fullscreen 用于隐藏状态栏,后面的 Show() 却又要求系统显示状态栏和导航栏,混用时容易出现不符合预期的行为。

下面这行代码控制的是内容布局范围:

WindowCompat.SetDecorFitsSystemWindows(Window, false);

它允许内容延伸到系统栏区域,本身不会隐藏系统栏。内容是否延伸到屏幕边缘、系统栏是否可见,需要分别控制。参见 WindowCompat API 文档。

窗口配置也不适合放在 OnCreateView() 中。这个方法负责创建 View,可能被多次调用,而且你代码中的 parent is null 分支会直接跳过窗口配置。把全屏逻辑放到 Activity 生命周期方法中会更清楚。

在 MAUI 中启用沉浸式全屏

在 Platforms/Android/MainActivity.cs 中添加命名空间:

using Android.OS;
using AndroidX.Core.View;

删除原来用于设置全屏的 OnCreateView() 重写,将以下方法放入现有的 MainActivity 类,并保留项目原有的 [Activity(...)] 配置和 CheckDeepLink() 方法。

protected override void OnCreate(Bundle? savedInstanceState)
{
    base.OnCreate(savedInstanceState);

    CheckDeepLink();
    ApplyFullscreen();
}

public override void OnWindowFocusChanged(bool hasFocus)
{
    base.OnWindowFocusChanged(hasFocus);

    if (hasFocus)
    {
        ApplyFullscreen();
    }
}

private void ApplyFullscreen()
{
    var window = Window;
    if (window is null)
    {
        return;
    }

    WindowCompat.SetDecorFitsSystemWindows(window, false);

    var controller = new WindowInsetsControllerCompat(
        window,
        window.DecorView);

    controller.SystemBarsBehavior =
        WindowInsetsControllerCompat.BehaviorShowTransientBarsBySwipe;

    controller.Hide(WindowInsetsCompat.Type.SystemBars());
}

SystemBars() 包括状态栏和导航栏。设置 BehaviorShowTransientBarsBySwipe 后,用户可以从屏幕边缘滑动,临时唤出系统栏,随后系统会自动将其隐藏。Android 的这种沉浸式交互仍允许用户访问系统导航。参见 Android 沉浸式模式文档。

在 OnWindowFocusChanged() 中调用全屏方法,适合整个 Activity 都需要保持全屏的情况。如果只有视频页等特定页面需要全屏,就应根据页面状态决定是否调用,避免返回普通页面后系统栏仍被隐藏。

退出沉浸式模式时,可以调用:

var window = Window;
if (window is not null)
{
    var controller = new WindowInsetsControllerCompat(
        window,
        window.DecorView);

    controller.Show(WindowInsetsCompat.Type.SystemBars());
}

这段代码只恢复系统栏的可见性,页面仍需根据自身布局处理系统栏的 insets。

为什么应用没有出现在 Samsung 的全屏列表里?

Samsung 的“全屏应用”设置通常用于调整应用的显示宽高比。根据 Samsung 官方说明,该选项是否可用取决于机型和软件版本,折叠屏在展开和折叠时也可能有不同的选项。参见 Samsung 全屏显示说明。

列表中没有应用,并不能说明应用缺少某个全屏权限。缺少具体机型、One UI 版本和实际设置页面,也就无法确定这台设备按什么条件筛选列表。

如果系统栏已经隐藏,应用四周却仍有黑边,应检查最终合并的 Android Manifest:

  • 是否设置了限制宽高比的 android:maxAspectRatio、android:minAspectRatio,或旧的 android.max_aspect 元数据。
  • Activity 是否设置为不可调整大小,即 android:resizeableActivity="false"。
  • 是否锁定了屏幕方向,导致当前窗口进入兼容显示模式。

如果布局支持窗口尺寸变化,可以允许 Activity 调整大小。Android 文档说明,resizeableActivity="true" 时会忽略 minAspectRatio 和 maxAspectRatio 限制。MAUI 会将属性生成的配置与 Manifest 合并,因此应以最终合并结果为准。这些配置可以改善窗口适配,但无法保证应用出现在 Samsung 的某个设置列表中。参见 Android 设备兼容模式文档。

系统栏隐藏后,顶部仍有空白怎么办?

如果空白集中在前置摄像头附近,需要检查挖孔区域的布局策略。Android 从 9(API 28)开始提供 display cutout 相关配置,例如 shortEdges,允许内容延伸到屏幕短边的挖孔区域。

具体行为受 Android 版本和目标 SDK 影响。例如,对于面向 API 35、运行在 Android 15 上的非浮动窗口,系统会将 shortEdges 按 always 解释。因此,挖孔配置需要结合运行环境判断,无法作为所有 Samsung 设备的通用修复。参见 Android 挖孔屏适配文档。

还需要区分 Android 系统栏和应用自身的导航栏。上述代码控制 Android 系统栏;MAUI 的 Shell 导航栏或 NavigationPage 导航栏属于应用界面,需要单独设置。例如,Shell 页面可以使用:

<ContentPage
    ...
    Shell.NavBarIsVisible="False">

在目标 Samsung 真机上,应分别检查手势导航和三键导航下的表现,以及应用切到后台再返回后的情况。背景铺满屏幕时,按钮和文字仍需留出合适的 insets,避免被摄像头或临时显示的系统栏遮住。

备注:内容仅供参考。