Android WebView在Oculus Quest 2中无法进入VR全屏模式求助

一、修复主题崩溃错误 #

你的MainActivity继承自AppCompatActivity，但Manifest中应用使用的是原生Android主题@android:style/Theme.Black.NoTitleBar.Fullscreen——这类主题不属于AppCompat体系，直接导致崩溃报错java.lang.IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity.。

解决方法： #

把应用主题替换为AppCompat子类主题，修改Manifest的android:theme属性：

android:theme="@style/Theme.AppCompat.Light.NoActionBar.Fullscreen"

如果需要深色全屏主题，可在res/values/styles.xml自定义：

<style name="AppTheme.Fullscreen" parent="Theme.AppCompat.NoActionBar">
    <item name="android:windowFullscreen">true</item>
    <item name="android:windowContentOverlay">@null</item>
    <item name="android:windowBackground">@android:color/black</item>
</style>

之后在Manifest中引用这个自定义主题即可。

二、解决WebVR沉浸式模式失效问题 #

应用在Quest 2中以窗口模式启动可交互，但点击VR按钮后变空白，这是因为WebView默认不处理WebXR（原WebVR）的全屏沉浸式请求，必须配置WebView参数并实现WebChromeClient来响应全屏切换。

1. 完善WebView初始化代码 #

修改MainActivity，添加必要设置和全屏处理逻辑：

class MainActivity : AppCompatActivity() {
    private var webView: WebView? = null
    private var customView: View? = null
    private var customViewCallback: WebChromeClient.CustomViewCallback? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        webView = findViewById(R.id.webview)
        val webSettings = webView?.settings

        // 启用WebXR所需的核心设置
        webSettings?.javaScriptEnabled = true
        webSettings?.domStorageEnabled = true
        webSettings?.allowFileAccess = true
        webSettings?.javaScriptCanOpenWindowsAutomatically = true
        webSettings?.setSupportZoom(false)
        webSettings?.builtInZoomControls = false
        // 强制硬件加速，WebXR必须依赖这个
        webView?.setLayerType(View.LAYER_TYPE_HARDWARE, null)

        // 配置WebChromeClient处理全屏请求
        webView?.webChromeClient = object : WebChromeClient() {
            override fun onShowCustomView(view: View, callback: CustomViewCallback) {
                // 切换到全屏视图
                customView = view
                customViewCallback = callback
                setContentView(view)
                // 隐藏系统UI，实现沉浸式
                window.decorView.systemUiVisibility = (View.SYSTEM_UI_FLAG_FULLSCREEN
                        or View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
                        or View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY)
            }

            override fun onHideCustomView() {
                // 退出全屏，恢复原布局
                customViewCallback?.onCustomViewHidden()
                customView = null
                setContentView(R.layout.activity_main)
                window.decorView.systemUiVisibility = View.SYSTEM_UI_FLAG_VISIBLE
            }
        }

        webView?.loadUrl("file:///android_asset/test.html")
    }

    override fun onBackPressed() {
        // 优先处理全屏退出逻辑
        if (customView != null) {
            webView?.webChromeClient?.onHideCustomView()
        } else {
            super.onBackPressed()
        }
    }
}

2. 更新Manifest配置 #

添加必要权限和VR相关配置，确保Quest设备识别：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="my.package.name">

    <!-- 互联网权限（加载远程资源时需要，本地asset可保留） -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- 声明VR硬件需求 -->
    <uses-feature android:name="android.hardware.vr.headtracking" android:required="true" />
    <uses-feature android:glEsVersion="0x00030001" android:required="true" />

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme.Fullscreen"
        tools:targetApi="31"
        android:configChanges="density|keyboard|keyboardHidden|navigation|orientation|screenLayout|screenSize|uiMode"
        android:launchMode="singleTask"
        android:resizeableActivity="false"
        <!-- 全局开启硬件加速 -->
        android:hardwareAccelerated="true">

        <meta-data android:name="com.oculus.intent.category.VR" android:value="vr_only"/>
        <meta-data android:name="com.oculus.supportedDevices" android:value="quest|quest2"/>
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:hardwareAccelerated="true"
            android:configChanges="orientation|screenSize|keyboardHidden|uiMode">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
                <category android:name="com.oculus.intent.category.VR" />
            </intent-filter>
        </activity>

    </application>
    <uses-sdk android:minSdkVersion="23"/>
</manifest>

3. 额外检查项 #

• 确认你的HTML内容使用WebXR API（WebVR已被废弃，Quest原生浏览器支持WebXR），检查VR启动逻辑是否正确调用navigator.xr.requestSession('immersive-vr')。
• 确保Quest 2系统版本和WebView版本为最新，旧版本可能存在兼容性问题。

内容的提问来源于stack exchange，提问作者Terence Eden