Emscripten示例中Module.requestFullscreen不是函数的问题分析

问题场景 #

使用Emscripten编译生成WebAssembly项目时，自动生成的示例HTML页面中，"Fullscreen"按钮的点击事件绑定了如下代码：

<span><input type="button" value="Fullscreen" onclick="Module.requestFullscreen(document.getElementById('pointerLock').checked, 
                                                                                document.getElementById('resize').checked)">
      </span>

同时页面中声明的Module对象包含canvas、print、setStatus等成员（代码如下），但并未定义requestFullscreen方法：

var Module = {
        print: (function() {
          var element = document.getElementById('output');
          if (element) element.value = ''; // clear browser cache
          return (...args) => {
            var text = args.join(' ');
            console.log(text);
            if (element) {
              element.value += text + "\n";
              element.scrollTop = element.scrollHeight; // focus on bottom
            }
          };
        })(),
        canvas: (() => {
          var canvas = document.getElementById('canvas');

          // WebGL上下文丢失时的默认提示
          canvas.addEventListener("webglcontextlost", (e) => { alert('WebGL context lost. You will need to reload the page.'); e.preventDefault(); }, false);

          return canvas;
        })(),
        setStatus: (text) => {
          if (!Module.setStatus.last) Module.setStatus.last = { time: Date.now(), text: '' };
          if (text === Module.setStatus.last.text) return;
          var m = text.match(/([^(]+)\((\d+(\.\d+)?)\/(\d+)\)/);
          var now = Date.now();
          if (m && now - Module.setStatus.last.time < 30) return; // 短时间内跳过重复进度更新
          Module.setStatus.last.time = now;
          Module.setStatus.last.text = text;
          if (m) {
            text = m[1];
            progressElement.value = parseInt(m[2])*100;
            progressElement.max = parseInt(m[4])*100;
            progressElement.hidden = false;
            spinnerElement.hidden = false;
          } else {
            progressElement.value = null;
            progressElement.max = null;
            progressElement.hidden = true;
            if (!text) spinnerElement.style.display = 'none';
          }
          statusElement.innerHTML = text;
        },
        totalDependencies: 0,
        monitorRunDependencies: (left) => {
          this.totalDependencies = Math.max(this.totalDependencies, left);
          Module.setStatus(left ? 'Preparing... (' + (this.totalDependencies-left) + '/' + this.totalDependencies + ')' : 'All downloads complete.');
        }
      };

点击按钮时会抛出错误：

Uncaught TypeError: Module.requestFullscreen is not a function

解决方法 #

错误根源是调用方式错误：requestFullscreen是HTML Canvas元素的原生API方法，并非Module对象的成员方法。示例中Module.canvas已指向页面中的canvas元素，因此基础的全屏功能可以直接修改调用方式：

<span><input type="button" value="Fullscreen" onclick="Module.canvas.requestFullscreen()">
      </span>

如果需要实现原按钮代码中提到的指针锁定和全屏resize逻辑，需要自行封装处理函数，示例代码如下：

function handleFullscreen(enablePointerLock, resizeOnFullscreen) {
  const canvas = Module.canvas;
  if (!canvas.requestFullscreen) {
    console.error('当前浏览器不支持全屏API');
    return;
  }

  canvas.requestFullscreen().then(() => {
    // 处理指针锁定
    if (enablePointerLock && canvas.requestPointerLock) {
      canvas.requestPointerLock();
    }

    // 处理全屏resize
    if (resizeOnFullscreen) {
      // 适配窗口尺寸
      canvas.width = window.innerWidth;
      canvas.height = window.innerHeight;
      // 如果使用WebGL，同步调整视口
      const gl = canvas.getContext('webgl');
      if (gl) {
        gl.viewport(0, 0, canvas.width, canvas.height);
      }
    }
  }).catch(err => {
    console.error('全屏切换失败:', err);
  });
}

之后修改按钮的点击事件绑定：

<span><input type="button" value="Fullscreen" onclick="handleFullscreen(document.getElementById('pointerLock').checked, 
                                                                                document.getElementById('resize').checked)">
      </span>

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