Maui Blazor 在 macOS 上 video 元素无法全屏的修复方法

问题

在 .NET MAUI Blazor 混合应用中嵌入 <video> 标签后，macOS 用户点击视频自带的全屏按钮，视频只会撑满整个 BlazorWebView 控件的区域。窗口本体并不进入 macOS 的独立桌面空间（Space），菜单栏和 Dock 栏仍然可见。这种“半全屏”体验和预期中的系统全屏差异明显。

检查配置，WKWebView 的 ElementFullscreenEnabled 已经显式置为 true：

e.Configuration.Preferences.ElementFullscreenEnabled = true;

完全没有效果。Apple 开发者论坛上也有不少讨论，确认 elementFullscreenEnabled 在 Mac Catalyst 环境下不起作用。

原理

一开始的思路很直接：网页里的视频要进入 macOS 原生的全屏空间，最合理的做法就是在 JS 侧捕捉全屏事件，通过消息通道传给原生层，再由原生层去操作真正的系统窗口。这条“JS → Native → 窗口操作”的通信链路，就是后面要反复用到的桥接。

方向定了，第一步就是去接标准全屏事件，结果直接撞上第一堵墙。document.addEventListener("fullscreenchange", ()=>{}); 无效。

Mac Catalyst 的 UIKit 底子

Mac Catalyst 的设计初衷是把 iPad 应用快速带到 Mac 上，所以底层依赖的是 UIKit，而不是 AppKit。顶层窗口在逻辑上是 UIWindow，负责网页渲染的 WebView 也来自 iOS 版本的 WKWebView，而不是桌面版 Safari 那一套。

HTML5 标准全屏模型——Element.requestFullscreen、``fullscreenchange` 事件——属于桌面 WebKit 的能力，需要与 AppKit 窗口服务器交互。iOS 上没有独立 Space 的概念，因此 iOS 版 WebKit 从最初就没有实现这套接口。基于 UIKit 的 Mac Catalyst 自然也继承了这一限制，标准全屏通路到这里就走不下去了。

前缀 API 同样无效

尝试带厂商前缀的版本 webkitfullscreenchange 事件，在桌面 Safari 中都可用，但放到 Mac Catalyst 里同样没有任何反应。这些方法在 iOS 版 WebKit 中直接落入空操作分支，调用不报错，行为上等于什么都没做。

仅存的信号：两个 iOS 残留事件

标准全屏走不通，但 <video> 元素点击全屏按钮后，视频还是会铺满 WKWebView 的可视区域。这说明底层必然有某种事件被触发。在 stackoverflow 上找到了相应的事件：

webkitbeginfullscreen
webkitendfullscreen

这两个事件和标准化的 webkitfullscreenchange 是两码事。它们是 iOS 上专门为移动端视频播放器内联全屏行为设计的遗留事件，分别对应进入和退出元素内全屏的时机。Mac Catalyst 在继承 iOS WebKit 时把它们一并带了过来，而且测试确认，在点击全屏按钮时这两个事件的确在正常触发。这就是仅有的、能够捕获用户全屏意图的信号。

桥接的逻辑

监听有了，桥接方案剩下的部分就清楚了：

JS → Native 信号传递：用 webkitbeginfullscreen 和 webkitendfullscreen 捕获全屏状态变化，通过 WKScriptMessageHandler 把布尔值传到原生层。
UIKit → AppKit 窗口操作：原生层无法通过 UIKit 的 API 让窗口进入系统全屏，必须绕过 UIKit，直接向 AppKit 的 NSWindow 发送 toggleFullScreen: 消息，让它进入或退出独立的桌面空间。

同时，原生层在收到消息后需要检查窗口当前的实际全屏状态，避免重复切换导致窗口来回缩放。

方案架构

整体分为 WebView 层和原生层两块。交互流程如下：

sequenceDiagram actor User participant Video as video 元素 participant JS as 注入脚本 participant Handler as WKScriptMessageHandler participant Native as CSharp 原生层 participant NSWindow as AppKit NSWindow User->>Video: 点击全屏按钮 Video->>Video: 视频在 WebView 内占满 Video-->>JS: 触发 webkitbeginfullscreen JS->>Handler: postMessage(true) Handler->>Native: DidReceiveScriptMessage (true) Native-->>NSWindow: 检查 styleMask，若未全屏则 toggleFullScreen: NSWindow-->>NSWindow: 窗口进入系统全屏 Space User->>Video: 退出全屏 (按钮/ESC) Video->>Video: 视频结束内嵌全屏 Video-->>JS: 触发 webkitendfullscreen JS->>Handler: postMessage(false) Handler->>Native: DidReceiveScriptMessage (false) Native-->>NSWindow: 检查 styleMask，若仍全屏则 toggleFullScreen: NSWindow-->>NSWindow: 窗口退出系统全屏

JavaScript 层实现

在 BlazorWebViewInitializing 事件中拿到 WKUserContentController，注册消息处理器，并注入监听脚本。

e.Configuration.UserContentController.AddScriptMessageHandler(
    new FullscreenHandler(), "fullscreenHandler");

e.Configuration.UserContentController.AddUserScript(
    new WKUserScript(new NSString(@"
        const notifyFullscreenChange = (isEnterFullscreen) => {
            window.webkit.messageHandlers.fullscreenHandler.postMessage(isEnterFullscreen);
        };
        document.addEventListener('webkitbeginfullscreen', () => notifyFullscreenChange(true), true);
        document.addEventListener('webkitendfullscreen', () => notifyFullscreenChange(false), true);
    "), WKUserScriptInjectionTime.AtDocumentEnd, true));

几个容易出问题的地方：

事件监听使用捕获阶段（addEventListener 第三个参数 true）。如果漏掉这个参数，事件可能被内部元素阻止冒泡而丢失，表现为全屏按钮点了没反应。排查时遇到过这种情况，加回来后恢复正常。
消息体直接传布尔值。true 和 false 明确表达进入和退出，原生层不需要额外维护状态机去猜测意图。
若页面内有 <iframe> 且其中包含 <video>，AddUserScript 的 forMainFrameOnly 参数需要设为 false，否则子框架中的事件无法浮出。

原生层实现

消息接收与转发

FullscreenHandler 收到 JS 消息后，取出布尔值，通过 MainThread.BeginInvokeOnMainThread 在主线程上调用 ToggleFullscreen，因为所有 UI 操作包括窗口全屏切换，都必须在主线程执行。

public override void DidReceiveScriptMessage(WKUserContentController userContentController, WKScriptMessage message)
{
    if (message.Body is NSNumber number)
    {
        bool isEnterFullscreen = number.BoolValue;
        MainThread.BeginInvokeOnMainThread(() => ToggleFullscreen(isEnterFullscreen));
    }
}

带状态检查的窗口切换

ToggleFullscreen 是整个方案的核心。它不会盲目调用 toggleFullScreen:，而是先通过 NSWindow 的 styleMask 属性判断窗口当前是否已处于系统全屏状态，仅当 JS 请求的状态与当前实际状态不一致时才执行切换。

private static void ToggleFullscreen(bool isEnterFullscreen)
{
    // 获取 NSApplication 单例
    var nsAppClass = new Class("NSApplication");
    var sharedAppSel = new Selector("sharedApplication");
    var nsApp = Messaging.IntPtr_objc_msgSend(nsAppClass.Handle, sharedAppSel.Handle);
    if (nsApp == IntPtr.Zero) return;

    // 获取窗口列表
    var windowsSel = new Selector("windows");
    var windowsPtr = Messaging.IntPtr_objc_msgSend(nsApp, windowsSel.Handle);
    var windows = Runtime.GetNSObject<NSArray>(windowsPtr);
    if (windows == null || windows.Count == 0) return;

    // 单窗口应用取第一个，多窗口需调整取法
    var nsWindow = windows.GetItem<NSObject>(0);
    if (nsWindow == null) return;

    var handle = nsWindow.Handle;

    // 读取 styleMask 位掩码
    var styleMaskSel = new Selector("styleMask");
    var styleMask = Messaging.nuint_objc_msgSend(handle, styleMaskSel.Handle);

    // NSWindowStyleMaskFullScreen = 16384 (1 << 14)
    bool isFullscreen = (styleMask & 16384) == 16384;

    // 只在状态不一致时切换
    if (isEnterFullscreen != isFullscreen)
    {
        var toggleFullScreenSel = new Selector("toggleFullScreen:");
        Messaging.void_objc_msgSend_IntPtr(handle, toggleFullScreenSel.Handle, IntPtr.Zero);
    }
}

早期版本没有做状态检查，收到 webkitendfullscreen 就直接调 toggleFullScreen:。当用户通过 Esc 键或窗口绿色按钮退出系统全屏后，窗口回到初始大小， <video> 元素依然充满整个WebView，点击 <video> 元素的退出全屏按钮，webkitendfullscreen 事件被触发， <video> 元素变回初始大小，窗口反而进入了全屏。加上 styleMask 判断后，只有在“网页想要全屏但窗口还没全屏”或“网页想退出但窗口仍处于全屏”时才真正执行切换，行为才稳定下来。

步骤拆解：

通过 Class 和 sharedApplication 拿到 NSApplication 单例。
调用 windows 获取窗口数组，对大多数单窗口 MAUI 应用取第一个即可。
读取 styleMask，和 16384 按位与，判断当前是否处于 NSWindowStyleMaskFullScreen 状态。
仅当 JS 传入的意图位与实际全屏位不一致时，通过 objc_msgSend 向 NSWindow 发送 toggleFullScreen:。

为什么直接用 objc_msgSend

Mac Catalyst 下也可以通过 PerformSelector 动态调用 AppKit 方法，比如：

keyWindow?.PerformSelector(new Selector("toggleFullScreen:"), null);

但实际调试中发现这种方式存在几个问题：

返回值被包装为 NSObject，需要拆装箱，处理 styleMask 这种整数返回值时比较麻烦。
部分 AppKit 方法返回结构体或特定整数类型，用 objc_msgSend 配合精确的 P/Invoke 声明才能正确获取。
统一的底层调用方式也方便后续扩展其他窗口操作，比如监听窗口大小变化等。

直接使用 objc_msgSend 同步发送消息，行为完全确定，也更贴近 Objective‑C 运行时的实际执行模型。

objc_msgSend 声明

用 .NET 6 引入的 LibraryImport 替代传统的 DllImport，对 AOT 编译更友好，直接链接到系统的 libobjc.dylib：

static partial class Messaging
{
    private const string LIBOBJC = "/usr/lib/libobjc.dylib";

    [System.Runtime.InteropServices.LibraryImport(LIBOBJC, EntryPoint = "objc_msgSend")]
    public static partial IntPtr IntPtr_objc_msgSend(IntPtr receiver, IntPtr selector);

    [System.Runtime.InteropServices.LibraryImport(LIBOBJC, EntryPoint = "objc_msgSend")]
    public static partial nuint nuint_objc_msgSend(IntPtr receiver, IntPtr selector);

    [System.Runtime.InteropServices.LibraryImport(LIBOBJC, EntryPoint = "objc_msgSend")]
    public static partial void void_objc_msgSend_IntPtr(IntPtr receiver, IntPtr selector, IntPtr arg1);
}

三个重载分别对应返回 id/指针、返回 NSUInteger 以及带一个 id 参数且无返回值的方法。声明与 Objective‑C 运行时的消息发送语义严格对齐。

完整代码集成

把以下代码合并到 MainPage.xaml.cs（或任意包含 BlazorWebView 的页面），加上条件编译以区分平台：

#if MACCATALYST
using Foundation;
using WebKit;
using ObjCRuntime;
#endif

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
#if MACCATALYST
        blazorWebView.BlazorWebViewInitializing += BlazorWebView_BlazorWebViewInitializing;
#endif
    }

#if MACCATALYST
    private void BlazorWebView_BlazorWebViewInitializing(object? sender, 
        Microsoft.AspNetCore.Components.WebView.BlazorWebViewInitializingEventArgs e)
    {
        e.Configuration.UserContentController.AddScriptMessageHandler(
            new FullscreenHandler(), "fullscreenHandler");
        e.Configuration.UserContentController.AddUserScript(new WKUserScript(new NSString(@"
            const notifyFullscreenChange = (isEnterFullscreen) => {
                window.webkit.messageHandlers.fullscreenHandler.postMessage(isEnterFullscreen);
            };
            document.addEventListener('webkitbeginfullscreen', () => notifyFullscreenChange(true), true);
            document.addEventListener('webkitendfullscreen', () => notifyFullscreenChange(false), true);
        "), WKUserScriptInjectionTime.AtDocumentEnd, true));
    }

    private sealed class FullscreenHandler : WKScriptMessageHandler
    {
        public override void DidReceiveScriptMessage(
            WKUserContentController userContentController, WKScriptMessage message)
        {
            if (message.Body is NSNumber number)
            {
                bool isEnterFullscreen = number.BoolValue;
                MainThread.BeginInvokeOnMainThread(() => ToggleFullscreen(isEnterFullscreen));
            }
        }

        private static void ToggleFullscreen(bool isEnterFullscreen)
        {
            var nsAppClass = new Class("NSApplication");
            var sharedAppSel = new Selector("sharedApplication");
            var nsApp = Messaging.IntPtr_objc_msgSend(nsAppClass.Handle, sharedAppSel.Handle);
            if (nsApp == IntPtr.Zero) return;

            var windowsSel = new Selector("windows");
            var windowsPtr = Messaging.IntPtr_objc_msgSend(nsApp, windowsSel.Handle);
            var windows = Runtime.GetNSObject<NSArray>(windowsPtr);
            if (windows == null || windows.Count == 0) return;

            var nsWindow = windows.GetItem<NSObject>(0);
            if (nsWindow == null) return;

            var handle = nsWindow.Handle;
            var styleMaskSel = new Selector("styleMask");
            var styleMask = Messaging.nuint_objc_msgSend(handle, styleMaskSel.Handle);
            bool isFullscreen = (styleMask & 16384) == 16384;

            if (isEnterFullscreen != isFullscreen)
            {
                var toggleFullScreenSel = new Selector("toggleFullScreen:");
                Messaging.void_objc_msgSend_IntPtr(handle, toggleFullScreenSel.Handle, IntPtr.Zero);
            }
        }
    }

    static partial class Messaging
    {
        private const string LIBOBJC = "/usr/lib/libobjc.dylib";

        [System.Runtime.InteropServices.LibraryImport(LIBOBJC, EntryPoint = "objc_msgSend")]
        public static partial IntPtr IntPtr_objc_msgSend(IntPtr receiver, IntPtr selector);

        [System.Runtime.InteropServices.LibraryImport(LIBOBJC, EntryPoint = "objc_msgSend")]
        public static partial nuint nuint_objc_msgSend(IntPtr receiver, IntPtr selector);

        [System.Runtime.InteropServices.LibraryImport(LIBOBJC, EntryPoint = "objc_msgSend")]
        public static partial void void_objc_msgSend_IntPtr(IntPtr receiver, IntPtr selector, IntPtr arg1);
    }
#endif
}

在.csproj项目文件中添加下面的代码，以允许不安全代码：

	<PropertyGroup>
		<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
	</PropertyGroup>

需要注意的点

条件编译
所有涉及到 ObjCRuntime、NSApplication 的代码必须用 #if MACCATALYST 包裹，否则在 iOS、Android、Windows 等平台会直接编译失败。
窗口索引
示例代码通过 windows.GetItem<NSObject>(0) 获取第一个窗口，适用于大多数单窗口 MAUI 应用。如果应用支持多窗口，需要根据业务逻辑定位正确的 NSWindow，例如通过 keyWindow 或遍历匹配窗口标题。
状态检查的重要性
前文已经提到，不检查 styleMask 就盲目切换，会导致用户通过其它途径退出全屏时窗口反复弹跳。这个检查是保证体验稳定的关键。
iframe 场景
若 <video> 标签位于 <iframe> 内部，注入脚本时需将 forMainFrameOnly 设为 false，以保证事件穿透子框架。
App Store 审核
NSApplication、NSWindow 以及 toggleFullScreen: 都是 AppKit 的公开 API，通过运行时调用不涉及私有方法。objc_msgSend 是系统公开接口，不违反审核规则。
Windows 平台的对应方案
Windows 上使用的 WebView2 提供了更直接的全屏元素监听机制。通过 ContainsFullScreenElementChanged 事件即可获知全屏状态变化，然后调用 AppWindow.SetPresenter 切换全屏/默认模式，实现成本远低于 macOS 侧。

#if WINDOWS
using Microsoft.UI.Windowing;
using Microsoft.Web.WebView2.Core;
#endif

    public partial class MainPage : ContentPage
    {
#if WINDOWS
        private static AppWindow? AppWindow => (Application.Current?.Windows[0]?.Handler?.PlatformView as Microsoft.UI.Xaml.Window)?.AppWindow;
#endif
        public MainPage()
        {
            InitializeComponent();

#if WINDOWS
            blazorWebView.BlazorWebViewInitialized += BlazorWebView_BlazorWebViewInitialized;
#endif
        }
#if WINDOWS
        private void BlazorWebView_BlazorWebViewInitialized(object? sender, Microsoft.AspNetCore.Components.WebView.BlazorWebViewInitializedEventArgs e)
        {
            e.WebView.CoreWebView2.ContainsFullScreenElementChanged += CoreWebView2_ContainsFullScreenElementChanged;
        }

        private void CoreWebView2_ContainsFullScreenElementChanged(CoreWebView2 sender, object args)
        {
            if (sender.ContainsFullScreenElement)
            {
                AppWindow?.SetPresenter(AppWindowPresenterKind.FullScreen);
            }
            else
            {
                AppWindow?.SetPresenter(AppWindowPresenterKind.Default);
            }
        }
#endif
    }

小结

Mac Catalyst 环境下 video 全屏问题的本质，本质上是 Mac Catalyst WKWebView 没能提供桌面级 Web 全屏能力。只能靠我们自己探讨出一套全屏方案：

利用两个 iOS 专有全屏事件捕获用户意图，并携带精确的布尔状态；
通过 WKScriptMessageHandler 实现 JS 到原生层的高效通信；
使用 objc_msgSend 直接操作 AppKit 的 NSWindow，在检查 styleMask 后按需调用 toggleFullScreen:，实现真正的系统全屏。

整个修复不修改 Blazor 组件逻辑，也不破坏 MAUI 的跨平台能力，只在 Mac Catalyst 平台上注入一段脚本和对应的原生桥接代码，让 NSWindow 在收到网页全屏信号后进入真正的系统全屏。方案中 objc_msgSend 的用法，也为其它需要绕过 UIKit 直接操作 AppKit 的场景提供了一个可复用的模式。

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园_首页