问题

在 .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 时把它们一并带了过来，而且测试确认，在点击全屏按钮时这两个事件的确在正常触发。这就是仅有的、能够捕获用户全屏意图的信号。

桥接的逻辑

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

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

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

方案架构

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

AppKit NSWindowCSharp 原生层WKScriptMessageHandler注入脚本video 元素AppKit NSWindowCSharp 原生层WKScriptMessageHandler注入脚本video 元素User点击全屏按钮视频在 WebView 内占满触发 webkitbeginfullscreenpostMessage(true)DidReceiveScriptMessage (true)检查 styleMask，若未全屏则 toggleFullScreen:窗口进入系统全屏 Space退出全屏 (按钮/ESC)视频结束内嵌全屏触发 webkitendfullscreenpostMessage(false)DidReceiveScriptMessage (false)检查 styleMask，若仍全屏则 toggleFullScreen:窗口退出系统全屏User

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判断后，只有在“网页想要全屏但窗口还没全屏”或“网页想退出但窗口仍处于全屏”时才真正执行切换，行为才稳定下来。

步骤拆解：

1. 通过Class和sharedApplication拿到NSApplication单例。
2. 调用windows获取窗口数组，对大多数单窗口 MAUI 应用取第一个即可。
3. 读取styleMask，和16384按位与，判断当前是否处于NSWindowStyleMaskFullScreen状态。
4. 仅当 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>

需要注意的点

1. 条件编译
   所有涉及到ObjCRuntime、NSApplication的代码必须用#if MACCATALYST包裹，否则在 iOS、Android、Windows 等平台会直接编译失败。

2. 窗口索引
   示例代码通过windows.GetItem<NSObject>(0)获取第一个窗口，适用于大多数单窗口 MAUI 应用。如果应用支持多窗口，需要根据业务逻辑定位正确的NSWindow，例如通过keyWindow或遍历匹配窗口标题。

3. 状态检查的重要性
   前文已经提到，不检查styleMask就盲目切换，会导致用户通过其它途径退出全屏时窗口反复弹跳。这个检查是保证体验稳定的关键。

4. iframe 场景
   若<video>标签位于<iframe>内部，注入脚本时需将forMainFrameOnly设为false，以保证事件穿透子框架。

5. App Store 审核
   NSApplication、NSWindow以及toggleFullScreen:都是 AppKit 的公开 API，通过运行时调用不涉及私有方法。objc_msgSend是系统公开接口，不违反审核规则。

6. 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:，实现真正的系统全屏。