使用guacamole-common-js时移动端浏览器键盘无法触发求助

核心问题分析 #

你的问题本质是移动端浏览器的键盘事件捕获机制、焦点管理和桌面端存在差异，加上React的DOM渲染时机可能导致InputSink或OnScreenKeyboard无法正确绑定事件/获取焦点。

针对性解决方案 #

1. 优化InputSink的焦点与DOM操作（替代直接getElementById） #

React中直接用document.getElementById可能存在DOM未完全渲染的问题，改用useRef获取DOM节点更可靠，同时确保InputSink在连接建立后再聚焦，并且在触摸操作时强制保持焦点：

import { useState, useEffect, useRef } from 'react';

const GuacdPage = (props) => {
  const { connectionParam, onError, onStateChange, onSync } = props;
  const displayRef = useRef(null);
  const [client, setClient] = useState(null);

  useEffect(() => {
    if (!displayRef.current) return;
    const cleanup = renderDisplay();
    return cleanup;
  }, [connectionParam]);

  const renderDisplay = () => {
    const tunnel = new Guacamole.WebSocketTunnel("/api/ws");
    const guacdClient = new Guacamole.Client(tunnel);

    guacdClient.onerror = onError;
    guacdClient.onsync = onSync;
    guacdClient.onstatechange = (state) => {
      onStateChange(state);
      // 连接建立后自动聚焦InputSink
      if (state === Guacamole.Client.State.CONNECTED) {
        sink.focus();
      }
    };

    const display = guacdClient.getDisplay();
    displayRef.current.appendChild(display.getElement());
    setClient(guacdClient);

    // 创建InputSink并绑定键盘事件
    const sink = new Guacamole.InputSink();
    displayRef.current.appendChild(sink.getElement());
    
    const keyboard = new Guacamole.Keyboard(sink.getElement());
    keyboard.onkeydown = (keysym) => guacdClient.sendKeyEvent(1, keysym);
    keyboard.onkeyup = (keysym) => guacdClient.sendKeyEvent(0, keysym);

    // 鼠标/触摸操作时强制聚焦InputSink
    const mouse = new Guacamole.Mouse(display.getElement());
    mouse.onmousedown = mouse.onmouseup = mouse.onmousemove = (mouseState) => {
      sink.focus();
      guacdClient.sendMouseState(mouseState);
    };

    const touch = new Guacamole.Mouse.Touchscreen(display.getElement());
    touch.onmousedown = touch.onmousemove = touch.onmouseup = (state) => {
      sink.focus();
      guacdClient.sendMouseState(state);
    };

    guacdClient.connect("connection=" + connectionParam);

    const handleResize = () => {
      const width = document.body.offsetWidth;
      const height = document.body.offsetHeight;
      guacdClient.sendSize(width, height);
    };
    window.addEventListener("resize", handleResize);

    return () => {
      guacdClient.disconnect();
      window.removeEventListener("resize", handleResize);
    };
  };

  return (
    <div className="container">
      <div ref={displayRef} id="display" />
    </div>
  );
};

export default GuacdPage;

2. 修复OnScreenKeyboard的事件绑定 #

如果要用屏幕键盘，需要确保键盘的按键事件正确传递给Guacamole Client，之前无效果大概率是没绑定事件：

// 在renderDisplay函数中添加以下代码（放在InputSink逻辑后）
const onScreenKeyboard = new Guacamole.OnScreenKeyboard(sink.getElement());
// 绑定键盘事件到client
onScreenKeyboard.onkeydown = (keysym) => guacdClient.sendKeyEvent(1, keysym);
onScreenKeyboard.onkeyup = (keysym) => guacdClient.sendKeyEvent(0, keysym);
// 将键盘元素添加到DOM
displayRef.current.appendChild(onScreenKeyboard.getElement());

3. 移动端额外适配技巧 #

• 给InputSink添加CSS确保它能获取焦点：

#display .guac-input-sink {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  opacity: 0;
  z-index: 10;
}

• 监听移动端touchstart事件，强制聚焦InputSink，避免软键盘弹出后焦点丢失：

// 在renderDisplay函数中添加
displayRef.current.addEventListener('touchstart', () => {
  sink.focus();
}, { passive: true });

关键注意点 #

• React中避免直接操作DOM，优先用useRef获取节点，确保DOM已挂载后再初始化Guacamole组件
• 移动端软键盘弹出会触发resize事件，确保sendSize能正确传递新的窗口尺寸
• InputSink必须保持焦点才能捕获键盘事件，所以在任何用户交互（点击/触摸）时都要重新聚焦

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