问题在 .NET MAUI Blazor 混合应用中嵌入video标签后macOS 用户点击视频自带的全屏按钮视频只会撑满整个BlazorWebView控件的区域。窗口本体并不进入 macOS 的独立桌面空间Space菜单栏和 Dock 栏仍然可见。这种“半全屏”体验和预期中的系统全屏差异明显。检查配置WKWebView的ElementFullscreenEnabled已经显式置为truee.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 上找到了相应的事件webkitbeginfullscreenwebkitendfullscreen这两个事件和标准化的webkitfullscreenchange是两码事。它们是 iOS 上专门为移动端视频播放器内联全屏行为设计的遗留事件分别对应进入和退出元素内全屏的时机。Mac Catalyst 在继承 iOS WebKit 时把它们一并带了过来而且测试确认在点击全屏按钮时这两个事件的确在正常触发。这就是仅有的、能够捕获用户全屏意图的信号。桥接的逻辑监听有了桥接方案剩下的部分就清楚了JS → Native 信号传递用webkitbeginfullscreen和webkitendfullscreen捕获全屏状态变化通过WKScriptMessageHandler把布尔值传到原生层。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:窗口退出系统全屏UserJavaScript 层实现在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且其中包含videoAddUserScript的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.GetNSObjectNSArray(windowsPtr); if (windows null || windows.Count 0) return; // 单窗口应用取第一个多窗口需调整取法 var nsWindow windows.GetItemNSObject(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_msgSendMac 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.dylibstatic 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.GetNSObjectNSArray(windowsPtr); if (windows null || windows.Count 0) return; var nsWindow windows.GetItemNSObject(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 AllowUnsafeBlockstrue/AllowUnsafeBlocks /PropertyGroup需要注意的点条件编译所有涉及到ObjCRuntime、NSApplication的代码必须用#if MACCATALYST包裹否则在 iOS、Android、Windows 等平台会直接编译失败。窗口索引示例代码通过windows.GetItemNSObject(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:实现真正的系统全屏。
