游戏引擎 / 系统课时

调试手机横竖屏和触控冲突

调试手机横竖屏和触控冲突

桌面浏览器运行正常的 Phaser 游戏,在手机上可能出现画面过小、旋转后按钮错位、拖动时页面滚动或触摸无响应。本课使用 Chrome 移动设备模拟器和真机,建立可复现的测试页面,定位视口、屏幕方向与浏览器默认手势之间的冲突,并完成移动端验收。

学习目标

  • 使用 Chrome DevTools 模拟手机横竖屏,检查视口尺寸和游戏画布的缩放结果。
  • 配置 Phaser 4.2.1 的触控输入与 CSS touch-action,识别页面滚动、缩放和指针事件冲突。
  • 在 Android 与 iOS 真机上验证触控坐标、屏幕旋转、浏览器工具栏及安全区域的行为。

在移动设备模拟器中复现问题

Chrome DevTools 的设备模式可以模拟移动视口、设备像素比和触控输入,适合快速定位布局问题。但它不能完整模拟真实手机的多指手势、系统边缘操作和浏览器工具栏行为,因此最终仍需真机验收。

按以下步骤建立测试环境:

  1. 使用桌面 Chrome 打开游戏页面,按 F12 打开开发者工具。
  2. 按 Ctrl+Shift+M(macOS 为 Cmd+Shift+M)启用设备工具栏。
  3. 在设备尺寸下拉框中选择 Responsive,手动输入 390 × 844,模拟手机竖屏。
  4. 点击设备工具栏中的旋转图标,切换到 844 × 390 横屏。
  5. 在设备工具栏的设备类型设置中确认使用 Mobile,使鼠标操作模拟触控输入。
  6. 打开 Console 和 Elements,分别检查 JavaScript 日志与 Canvas 元素的实际尺寸。

本课以设计逻辑分辨率 960 × 540、宽高比 16:9 的横向游戏为例。使用 Phaser.Scale.FIT 时,画布始终保持设计宽高比。

假设父容器恰好是 844 × 390,没有额外内边距,实际显示画布约为 693 × 390,左右分别留白约 75 像素。若父容器为 390 × 844,画布则约为 390 × 219,上下留下较大空白。

这些留白是 FIT 保持比例的正常结果,并非渲染错误。不过,竖屏下整幅横向游戏会明显缩小,因此需要评估触控按钮是否仍然容易操作。正式项目可以提供独立竖屏布局,或在竖屏时显示横屏提示。

建立可观测的触控测试页面

为了区分画布缩放问题和触控事件问题,先制作一个不依赖图片素材的最小测试页面。页面包含一个青绿色圆点:点击时圆点移动到触控位置,按住拖动时持续跟随,并在控制台记录屏幕方向和画布尺寸变化。

以下示例适用于 Phaser 4.2.1,使用 Vite 的 Vanilla JavaScript 模板。需要本机已安装 Node.js 和 npm。

在终端执行:

bash
npm create vite@latest phaser-mobile-check -- --template vanilla
cd phaser-mobile-check
npm install
npm install phaser@4.2.1

预期结果:生成包含 index.html、package.json 和 src/main.js 的项目,且依赖中安装 Phaser 4.2.1。安装命令应正常结束,不出现 npm ERR!。

将项目根目录的 index.html 替换为以下内容:

html
<!doctype html>
<html lang='zh-CN'>
<head>
  <meta charset='UTF-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1, viewport-fit=cover'>
  <title>Phaser 移动端触控检查</title>
  <style>
    html, body { margin: 0; width: 100%; height: 100%; }
    body {
      box-sizing: border-box;
      height: 100vh;
      height: 100dvh;
      overflow: hidden;
      padding: env(safe-area-inset-top) env(safe-area-inset-right)
               env(safe-area-inset-bottom) env(safe-area-inset-left);
      background: #102236;
    }
    #game { width: 100%; height: 100%; }
    /* 只禁止游戏画布内的浏览器默认触摸手势 */
    #game canvas { display: block; touch-action: none; }
  </style>
</head>
<body>
  <div id='game'></div>
  <script type='module' src='/src/main.js'></script>
</body>
</html>

这里有三个直接影响手机表现的设置:

  • width=device-width, initial-scale=1:让布局视口跟随设备的 CSS 像素宽度,避免浏览器按桌面网页宽度缩放整个页面。
  • 100dvh:让容器高度跟随动态视口,适应移动浏览器工具栏显示与收起时的可见区域变化;前面的 100vh 作为旧环境的回退值。
  • env(safe-area-inset-*):为支持安全区域的浏览器预留边距,避免游戏画布进入刘海、圆角或底部系统指示条区域。

touch-action: none 仅应用于游戏 Canvas,避免拖动游戏时触发页面滚动或浏览器缩放。示例页面是全屏游戏,因此还设置了 overflow: hidden。如果游戏嵌入可滚动网页,不应直接把这些限制扩大到整个页面。

然后将 src/main.js 替换为:

js
import Phaser from 'phaser';

class MobileDebugScene extends Phaser.Scene {
  constructor() {
    super('MobileDebugScene');
  }

  create() {
    const status = this.add.text(24, 24, '点按或拖动屏幕', {
      fontFamily: 'Arial, sans-serif',
      fontSize: '28px',
      color: '#ffffff'
    });
    const marker = this.add.circle(480, 270, 36, 0x18b89b);

    // 使用 Phaser 已换算的游戏逻辑坐标,不再乘设备像素比
    const showPoint = (name, pointer) => {
      marker.setPosition(pointer.x, pointer.y);
      status.setText(`${name}: ${Math.round(pointer.x)}, ${Math.round(pointer.y)}`);
    };

    this.input.on('pointerdown', pointer => {
      showPoint('down', pointer);
      console.log('down', pointer.id);
    });
    this.input.on('pointermove', pointer => {
      if (pointer.isDown) showPoint('move', pointer);
    });
    this.input.on('pointerup', pointer => {
      showPoint('up', pointer);
      console.log('up', pointer.id);
    });
    this.input.on('pointerupoutside', pointer => {
      status.setText(`outside: ${pointer.id}`);
    });

    // 记录逻辑画布尺寸与实际显示尺寸,便于定位缩放问题
    this.scale.on('resize', (gameSize, baseSize, displaySize) => {
      console.log('resize',
        `${gameSize.width}x${gameSize.height}`,
        `${displaySize.width}x${displaySize.height}`);
    });
    this.scale.on('orientationchange', orientation => {
      console.log('orientationchange', orientation);
    });
  }
}

new Phaser.Game({
  type: Phaser.AUTO,
  parent: 'game',
  backgroundColor: '#132a40',
  scale: {
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
    width: 960,
    height: 540
  },
  input: {
    activePointers: 2,
    touch: { capture: true }
  },
  scene: MobileDebugScene
});

input.touch.capture 让 Phaser 的 Touch Manager 尝试阻止触摸事件的浏览器默认行为;CSS touch-action 则提前声明哪些手势允许由浏览器处理。二者作用层次不同,可以配合使用。activePointers: 2 预留两个触摸指针,便于后续双指测试。

启动开发服务器:

bash
npm run dev -- --host 0.0.0.0

预期输出格式如下,版本号、启动时间、局域网地址和端口以终端实际显示为准:

text
VITE v<VERSION> ready in <TIME> ms
Local:   http://localhost:<PORT>/
Network: http://<LAN_IP>:<PORT>/

在桌面浏览器访问 Local 地址,用鼠标点击和拖动游戏区域。

预期结果:页面出现深蓝色游戏画布和青绿色圆点。点击时状态文字变为 down: x, y,拖动时变为 move: x, y,圆点跟随指针移动;松开后显示 up: x, y。其中 x、y 为本次操作得到的实际逻辑坐标。

在移动设备模拟器中切换横竖屏,控制台应记录相应的 resize 信息。部分浏览器还会触发 orientationchange。事件是否触发以及输出顺序可能因浏览器而不同,不能仅凭缺少方向事件就认定缩放失败。

区分视口变化、方向变化和坐标错误

移动端调试时需要区分三个尺寸:浏览器布局视口、Phaser 游戏逻辑尺寸,以及 Canvas 的实际显示尺寸。

检查对象 本例观察值 含义
浏览器视口 如 844 × 390 手机页面可用于布局的 CSS 像素区域
游戏逻辑尺寸 960 × 540 游戏内部对象使用的坐标空间
Canvas 显示尺寸 约 693 × 390 FIT 后实际显示的画布尺寸

上表显示尺寸仅对应父容器恰好为 844 × 390 且没有安全区域内边距的情况。实际设备上应以 displaySize 和 Elements 面板中的 Canvas 尺寸为准。

屏幕方向也不能直接通过游戏设计尺寸判断。this.scale.isGameLandscape 表示游戏本身是横向设计,而 this.scale.isLandscape 才表示 Scale Manager 检测到的设备方向。浏览器是否提供方向信息具有兼容性差异,因此布局判断还应结合实际视口宽高。

如果横屏后触控位置偏移,先检查是否对 pointer.x、pointer.y 额外执行了 devicePixelRatio 倍乘,或手动减去了画布留白。Phaser 的 Input Manager 已经负责将触摸输入映射为游戏坐标,在普通 FIT 场景中不应重复转换。

当页面通过 CSS transform 移动画布,或者父容器发生特殊布局变化时,应检查 Canvas 的实际边界。不要只修改 Canvas 的 CSS 宽高而绕过 Scale Manager;否则视觉尺寸与输入坐标可能不同步。

定位浏览器默认手势与游戏触控冲突

手机触摸操作首先由浏览器接收。浏览器需要判断手势用于页面滚动、缩放,还是交给游戏处理。如果浏览器开始接管平移或缩放手势,游戏的拖动序列可能中断,原生 Pointer Events 路径中也可能发生 pointercancel。

浏览器默认手势与 Phaser 触控事件的正常路径和冲突路径

可按照以下顺序定位具体问题:

  1. 点击没有反应:查看 Console 是否出现 down,检查 Canvas 上方是否存在覆盖层,并确认监听器属于当前正在运行的 Scene。
  2. 拖动时整个网页移动:在 Elements 的 Computed 样式中检查 Canvas 的 touch-action 是否实际为 none,再检查 Phaser 的 input.touch.capture 配置。
  3. 拖动开始后突然停止:检查是否发生浏览器手势接管、手指滑出 Canvas、页面失焦或 Scene 被暂停。
  4. 触摸位置不准确:比较实际 Canvas 边界、Scale Manager 显示尺寸与逻辑坐标,排除重复坐标缩放。
  5. 一次触摸触发两次操作:检查是否同时给同一个动作绑定了 DOM click、原生 touchstart 和 Phaser pointerdown,避免重复执行。

如果游戏需要手指拖动控制角色,建议由 Phaser 统一处理 Canvas 内的输入。不要额外在 document 上无条件调用 preventDefault(),否则可能破坏页面滚动、输入框操作以及辅助功能。

对于没有自定义拖动需求、仍需要浏览器滚动的区域,可以保留 touch-action: auto 或根据交互需求选择 manipulation 等值。touch-action: none 会限制浏览器的部分缩放操作,正式产品还应考虑可访问性,避免对非游戏内容使用。

pointerupoutside 可以辅助处理手指在 Canvas 外松开的情况,但它并不保证覆盖所有浏览器取消或系统中断事件。持续按住才能移动的虚拟方向键,还应在页面 blur、visibilitychange 或游戏失去焦点时清除按下状态,防止角色持续移动。

使用真机完成横竖屏验收

确保电脑与手机位于可以互相访问的局域网,且本机防火墙允许开发服务器端口访问。在手机浏览器中打开终端显示的 Network 地址,访问时保持电脑上的开发服务器运行。

Chrome 模拟器的尺寸与触控模拟只能作为第一轮检查。第二轮至少使用一台 Android Chrome 和一台 iOS Safari 真机,按下表执行验收。

测试场景 操作 通过标准
竖屏进入 保持竖屏首次打开 无横向网页溢出;测试页正常显示,正式横屏游戏应提供清楚的方向提示或适配布局
旋转到横屏 旋转设备后点击画布四角附近 画面比例正常,触点与游戏对象位置匹配
连续旋转 横屏、竖屏往返 5 次 不出现黑屏、异常拉伸、Canvas 重叠或重复创建游戏实例
单指拖动 按住圆点区域持续滑动 3 秒 圆点持续跟随,页面不因游戏内拖动而滚动
多指输入 两指同时接触不同位置 不触发意外网页缩放;正式游戏的多指控制按设计工作
浏览器工具栏 滚动或改变 Safari、Chrome 工具栏状态 可视区域变化后画布保持正常比例,不遮挡重要 UI
安全区域 检查刘海、圆角和底部手势条附近 关键按钮与提示没有被设备区域遮挡
中断触控 按住时切换应用,再返回游戏 正式游戏的持续输入状态已释放,不会自动移动或连续触发

其中双指和中断测试应使用真实游戏的控制逻辑验收。本文的最小示例主要用于观察触点和坐标,不包含虚拟摇杆的持续运动状态管理。

最后在目标设备上重复执行点击、拖动、旋转和页面失焦测试。如果问题只发生在某一台真机,应记录设备型号、操作系统、浏览器版本、横竖屏状态、复现步骤和 Console 信息,再修复对应行为,而不是直接修改整个游戏的设计分辨率。

完成验收的标准是:不同方向下画布和 UI 的显示结果符合预期,触控坐标与视觉位置一致,游戏操作不被浏览器默认手势意外打断,并且旋转或失焦后输入状态能够正确恢复。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

调试手机横竖屏和触控冲突

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通