Maui Blazor 在 macOS 上 video 元素无法全屏的修复方法
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 上找到了相应的事件：
webkitbeginfullscreenwebkitendfullscreen
这两个事件和标准化的 webkitfullscreenchange 是两码事。它们是 iOS 上专门为移动端视频播放器内联全屏行为设计的遗留事件，分别对应进入和退出元素内全屏的时机。Mac Catalyst 在继承 iOS WebKit 时把它们一并带了过来，而且测试确认，在点击全屏按钮时这两个事件的确在正常触发。这就是仅有的、能够捕获用户全屏意图的信号。
桥接的逻辑
监听有了，桥接方案剩下的部分就清楚了：
- JS → Native 信号传递：用
webkitbeginfullscreen和webkitendfullscreen捕获全屏状态变化，通过WKScriptMessageHandler把布尔值传到原生层。 - UIKit → AppKit 窗口操作：原生层无法通过 UIKit 的 API 让窗口进入系统全屏，必须绕过 UIKit，直接向 AppKit 的
NSWindow发送toggleFullScreen:消息，让它进入或退出独立的桌面空间。
同时，原生层在收到消息后需要检查窗口当前的实际全屏状态，避免重复切换导致窗口来回缩放。
方案架构
整体分为 WebView 层和原生层两块。交互流程如下：
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 的场景提供了一个可复用的模式。
浙公网安备 33010602011771号