企业官网建设流程全解析

简介：本资源是一个面向Unity WebGL开发者的中文输入功能完整实现方案，专为解决Web端3D/2D应用中中文输入不兼容、输入法悬浮窗无法跟随光标、全屏模式下定位失效等典型痛点而设计。适用于中高级Unity开发者，尤其在需用户实时文本交互的在线教育、Web游戏、可视化编辑器等场景中具有直接落地价值。压缩包共19个文件，含8张UI与进度图（如progressFull.Light.png）、3个核心WebGL构建产物（.unityweb）、2个关键JS脚本（UnityLoader.js、UnityProgress.js）、1个HTML入口页、1个CSS样式文件及1个ReadMe说明文档，整体17.4MB，结构清晰，开箱即用。目前已有939人学习下载，读者可直接复用其JavaScript与C#双向通信逻辑、输入法动态定位算法、全屏API适配策略，并参考其Canvas事件监听与DOM坐标映射实现细节，快速集成稳定可靠的中文输入体验。

1. Unity WebGL中文输入：不是加个InputField就完事，而是要绕过浏览器输入框劫持、DOM焦点冲突和全屏Canvas遮挡三重黑匣子

你有没有试过在Unity WebGL项目里拖一个TMP_InputField进去，本地运行好好的，一发布到网页上——点一下没反应，点两下弹出系统输入法但光标不跟随，切到全屏模式后直接失联？这不是你代码写错了，是Unity WebGL的输入机制从底层就和浏览器玩着一场“谁控制焦点”的拔河。这个资源包解决的不是“能不能输中文”，而是“在真实部署场景下，让中文输入像原生网页一样自然：输入法候选框精准贴合光标、全屏切换不丢焦点、中英文混输不卡顿、回车/退格/方向键全响应”。它适用于所有需要用户填写表单、搜索框、聊天输入、甚至游戏内指令行的WebGL项目，尤其适合某高校在线实验平台、某公司跨平台培训系统这类必须兼顾教学交互与多端一致性的场景。核心不在Unity侧魔改，而在于用最小侵入方式桥接Unity Canvas与浏览器DOM事件流——这才是真正能落地的方案。

2. 输入法跟随原理：为什么Unity默认InputField在WebGL里是“哑巴”，以及我们如何给它装上DOM耳朵

2.1 Unity WebGL输入的先天缺陷：Canvas是画布，不是可聚焦元素

Unity WebGL构建后，整个游戏画面渲染在一个<canvas>标签里。浏览器默认把<canvas>视为不可聚焦（non-focusable）的绘图区域，而输入法（IME）的触发、候选框定位、按键事件捕获，全部依赖于一个可聚焦的HTML元素（如<input>或<textarea>）获得焦点并持续持有。Unity的TMP_InputField在WebGL下实际是通过UnityLoader.js在Canvas上方动态插入一个透明<input>覆盖层来模拟输入，但这个覆盖层存在三个硬伤：

• 它的位置计算基于Canvas左上角，未考虑CSS缩放、transform: scale()、position: fixed等真实页面布局；
• 全屏（Dome）模式下Canvas尺寸动态拉满视口，覆盖层坐标未同步重算，导致输入框漂移出屏幕；
• 浏览器IME候选框的锚定位置由getBoundingClientRect()获取，而Unity覆盖层常因z-index层级或pointer-events: none被浏览器忽略，候选框直接消失。

提示：别试图用InputField.onValueChanged监听——WebGL下该事件在输入法组合过程中（如拼音打“zhong”还没选字）根本不会触发，你拿到的永远是最终确认的字符串，中间过程完全黑盒。

2.2 真实可行的桥接方案：用原生<textarea>接管输入，Unity只做“内容搬运工”

本资源采用“双通道”设计：

• DOM通道：在HTML页面中显式声明一个<textarea id="webgl-input">，设置position: absolute; opacity: 0; z-index: 9999;，确保它始终位于Canvas顶层且不遮挡画面；
• Unity通道：C#脚本通过Application.ExternalCall调用JS函数，将用户点击InputField的行为，转换为对#webgl-input的focus()调用；
• 同步通道：JS监听#webgl-input的input事件，实时将value通过SendMessage推回Unity的指定GameObject，更新TMP_Text显示。

这样做的好处是：浏览器IME完全接管输入逻辑，候选框自动跟随<textarea>光标（哪怕Canvas被缩放或全屏），Unity退化为纯渲染和业务逻辑层，规避所有底层兼容性问题。

2.3 关键JS桥接代码：聚焦、同步、防抖三件套

在index.html的<body>底部插入以下脚本（注意：必须在Unity加载完成后执行）：

<script> // 1. 初始化：确保textarea存在且样式正确 function initWebGLInput() { let input = document.getElementById('webgl-input'); if (!input) { input = document.createElement('textarea'); input.id = 'webgl-input'; input.style.cssText = ` position: absolute; top: 0; left: 0; width: 1px; height: 1px; opacity: 0; z-index: 9999; border: none; outline: none; resize: none; font-size: 16px; line-height: 1.5; overflow: hidden; `; document.body.appendChild(input); } } // 2. Unity调用：聚焦输入框（由C#调用） function focusWebGLInput() { const input = document.getElementById('webgl-input'); if (input) { // 强制滚动到可视区，避免全屏时被裁剪 input.scrollIntoView({ block: 'nearest', inline: 'nearest' }); input.focus(); // 触发IME激活（关键！否则部分浏览器不弹候选框） input.click(); } } // 3. DOM输入同步到Unity（防抖版，避免高频触发） let syncTimer = null; function syncToUnity() { const input = document.getElementById('webgl-input'); if (input && window.unityInstance) { clearTimeout(syncTimer); syncTimer = setTimeout(() => { // 发送当前值和光标位置（用于后续光标渲染） const value = input.value; const cursorPos = input.selectionStart; window.unityInstance.SendMessage('InputHandler', 'OnDOMInput', JSON.stringify({ text: value, cursor: cursorPos, isComposing: input.composing === true // 判断是否处于输入法组合状态 })); }, 50); // 50ms防抖，平衡响应与性能 } } // 4. 绑定事件 document.addEventListener('DOMContentLoaded', () => { initWebGLInput(); const input = document.getElementById('webgl-input'); if (input) { input.addEventListener('input', syncToUnity); input.addEventListener('keydown', (e) => { // 拦截回车、ESC等特殊键，转为Unity事件 if (e.key === 'Enter') { e.preventDefault(); window.unityInstance?.SendMessage('InputHandler', 'OnSubmit', ''); } else if (e.key === 'Escape') { e.preventDefault(); window.unityInstance?.SendMessage('InputHandler', 'OnCancel', ''); } }); } }); </script>

参数说明：

• opacity: 0而非display: none：确保元素仍参与布局计算，getBoundingClientRect()能获取有效坐标；
• width: 1px; height: 1px：极小尺寸避免影响页面流，同时保证可聚焦；
• scrollIntoView({ block: 'nearest' })：全屏模式下防止textarea被浏览器视口裁剪导致焦点失效；
• input.composing：现代浏览器支持该属性判断输入法是否处于“拼音输入中”状态（如打“shu”未选字），Unity可据此隐藏临时文本，只显示最终确认内容；
• setTimeout防抖：避免用户快速输入时每键都触发SendMessage，造成Unity主线程阻塞，50ms是实测平衡点——快于人眼感知延迟，又远低于Unity帧率（通常16ms/frame）。

3. 全屏（Dome）模式下的输入框锚定：Canvas尺寸突变时，如何让textarea光标不“瞬移”

3.1 全屏的本质：不是放大Canvas，而是重置其CSS宽高并修改父容器

Unity WebGL的全屏（Dome）并非简单canvas.style.width = '100vw'，而是通过SetFullscreen(true)触发一系列DOM操作：

• Canvas父容器（通常是#unity-canvas）被添加unity-fullscreen类；
• CSS规则.unity-fullscreen canvas { width: 100vw; height: 100vh; }生效；
• 浏览器触发resize事件，但Unity内部的Screen.width/height更新有延迟，且不通知外部JS。

此时，若textarea的top/left仍按原始Canvas尺寸计算，它会瞬间“飞”到页面左上角外，导致焦点丢失、IME候选框错位。

3.2 动态锚定算法：用Canvas的getBoundingClientRect()实时校准

核心思路：textarea的绝对定位坐标，必须始终等于Canvas内光标位置在视口中的物理像素坐标。实现分三步：

1. 在Unity中获取光标在Canvas内的相对坐标：

   // InputHandler.cs 中，当用户点击InputField时 public void OnInputFieldClick() { // 获取InputField在Canvas中的Rect位置（已考虑RectTransform缩放） RectTransform rt = inputField.GetComponent<RectTransform>(); Vector2 localPos; RectTransformUtility.WorldToScreenPoint(Camera.main, rt.position, out localPos); // 转换为Canvas坐标系（0~1归一化） Vector2 canvasPos = new Vector2( (localPos.x - Screen.width * 0.5f) / (Screen.width * 0.5f), (localPos.y - Screen.height * 0.5f) / (Screen.height * 0.5f) ); // 发送给JS，附带Canvas尺寸 Application.ExternalEval($"updateInputPosition({canvasPos.x}, {canvasPos.y}, {Screen.width}, {Screen.height});"); }

2. JS端实时计算textarea位置：

   // 在index.html中定义 function updateInputPosition(normX, normY, canvasWidth, canvasHeight) { const canvas = document.querySelector('canvas'); const rect = canvas.getBoundingClientRect(); // 获取Canvas在视口中的真实像素矩形 // 将归一化坐标转为视口像素坐标 const x = rect.left + (normX + 1) * 0.5 * rect.width; const y = rect.top + (1 - normY) * 0.5 * rect.height; // 设置textarea位置（偏移量需补偿textarea自身宽高，使其光标点对齐） const input = document.getElementById('webgl-input'); if (input) { input.style.left = (x - 2) + 'px'; // -2px补偿光标宽度 input.style.top = (y - 8) + 'px'; // -8px补偿字体基线 input.style.width = '4px'; // 极窄，仅够触发IME input.style.height = '24px'; } } // 监听resize事件，全屏时Canvas尺寸突变，立即重算 window.addEventListener('resize', () => { // 延迟执行，确保Canvas尺寸已稳定 setTimeout(() => { const canvas = document.querySelector('canvas'); if (canvas) { const rect = canvas.getBoundingClientRect(); // 重新锚定到当前Canvas中心（作为兜底策略） updateInputPosition(0, 0, rect.width, rect.height); } }, 100); });

3. 全屏切换钩子：主动触发重锚定
   Unity不提供全屏回调，但可通过Screen.fullScreenMode轮询检测：

   // 在MonoBehaviour中 private FullScreenMode lastMode = FullScreenMode.Windowed; void Update() { if (Screen.fullScreenMode != lastMode) { lastMode = Screen.fullScreenMode; // 全屏状态变更，强制刷新textarea位置 Application.ExternalCall("updateInputPosition", 0, 0, Screen.width, Screen.height); } }

注意：getBoundingClientRect()返回的是视口坐标（viewport coordinates），不受transform: scale()影响，这是它比offsetTop/Left更可靠的原因——某次某公司项目因使用transform: scale(0.8)缩放Canvas，导致offsetTop计算完全错误，而getBoundingClientRect()毫秒级修正。

4. 避坑指南：WebGL中文输入的五个血泪现场与后悔药

4.1 现象：点击InputField无反应，Console报错Cannot read property 'focus' of null

原因：JS脚本在Unity加载完成前就执行了document.getElementById('webgl-input')，此时DOM中尚无该元素，返回null；或Unity实例（window.unityInstance）未初始化完成，SendMessage调用失败。
解决：

• 在index.html中，将JS脚本放在<body>最底部，且在Unity<script>标签之后；
• 所有调用window.unityInstance的地方，先加判空：if (window.unityInstance && window.unityInstance.SendMessage)；
• 使用UnityLoader的onProgress回调，在进度100%后再初始化输入框：

  var gameInstance = UnityLoader.instantiate("gameContainer", "Build/game.json", { onProgress: function (progress) { if (progress == 1) { initWebGLInput(); // 此时Unity已就绪 } } });

4.2 现象：输入法候选框出现在屏幕左上角，不跟随光标

原因：<textarea>的position: absolute未设置top/left，或设置了但值为0，导致浏览器默认锚定到视口原点；或z-index不够，被Canvas或其他元素遮挡。
解决：

• 确保<textarea>的style.cssText中明确包含top: 0; left: 0;，即使初始为0，后续JS才能通过style.left动态修改；
• z-index: 9999必须大于Unity Canvas的z-index（默认为0，但某些主题可能设为100）；
• 在Chrome开发者工具中检查<textarea>是否被pointer-events: none或visibility: hidden影响——这些CSS属性会让浏览器忽略其可聚焦性。

4.3 现象：全屏后输入框“消失”，但Console能看到focus()成功

原因：全屏时Canvas尺寸变为100vw/100vh，但<textarea>的left/top仍按原始尺寸（如800x600）计算，导致坐标超出视口范围（如left: 2000px）。
解决：

• 必须使用getBoundingClientRect()动态获取Canvas当前视口坐标，而非缓存Screen.width/height；
• 在resize事件中，不仅重算位置，还要调用input.scrollIntoView()确保textarea在视口内；
• 添加视觉调试：临时将opacity: 0改为opacity: 0.5，亲眼看到textarea是否随Canvas缩放而移动。

4.4 现象：中英文混输时，英文字符正常，中文输入后光标跳到行首

原因：Unity的TMP_InputField在接收JS推送的字符串时，未正确处理selectionAnchorPosition和selectionFocusPosition，导致光标重置。
解决：

• 不要直接赋值inputField.text = newText，而是用inputField.SetTextWithoutNotify(newText)，再手动设置光标：

  public void OnDOMInput(string json) { var data = JsonUtility.FromJson<InputData>(json); inputField.SetTextWithoutNotify(data.text); // 关键：恢复光标位置 inputField.caretPosition = data.cursor; // 如果处于输入法组合状态，隐藏临时文本（可选） if (data.isComposing) { inputField.textComponent.text = ""; // 清空显示，等待最终确认 } }

• InputData结构体需包含cursor和isComposing字段，与JS端JSON.stringify保持一致。

4.5 现象：移动端Safari上，点击InputField后键盘弹出，但Canvas失去响应（触摸无效）

原因：iOS Safari的键盘弹出会触发resize事件，并改变视口高度，导致Canvas的touchstart事件坐标映射错乱；同时，<textarea>获得焦点后，浏览器默认阻止Canvas的touchmove事件冒泡。
解决：

• 在<textarea>的focus事件中，临时禁用Canvas的pointer-events：

  input.addEventListener('focus', () => { const canvas = document.querySelector('canvas'); if (canvas) canvas.style.pointerEvents = 'none'; }); input.addEventListener('blur', () => { const canvas = document.querySelector('canvas'); if (canvas) canvas.style.pointerEvents = 'auto'; });

• 在Unity中，监听TouchScreenKeyboard.done事件，键盘关闭后手动恢复Canvas交互。

5. 进阶技巧：让输入体验媲美原生网页——光标渲染、输入法状态反馈与无障碍支持

5.1 在Unity Canvas上绘制“假光标”：解决textarea透明导致的视觉断层

用户看到的是textarea光标，但Unity Canvas上没有任何指示，造成“我在输，但不知道光标在哪”的困惑。解决方案是在Unity中用一个Image组件模拟光标，并实时同步位置：

1. 创建光标预制体：新建Image，设为白色细条（宽2px，高20px），Raycast Target = false；
2. 绑定到InputField：在InputHandler.cs中：

   public Image cursorImage; private RectTransform cursorRT; void Start() { cursorRT = cursorImage.GetComponent<RectTransform>(); // 初始隐藏 cursorImage.enabled = false; } public void ShowCursor(bool show, Vector2 screenPos) { cursorImage.enabled = show; if (show) { // 将屏幕坐标转为Canvas坐标 Vector2 localPos; RectTransformUtility.ScreenPointToLocalPointInRectangle( canvasRT, screenPos, null, out localPos ); cursorRT.anchoredPosition = localPos; } }

3. JS端同步光标位置：在syncToUnity函数中，增加光标坐标推送：

   // 获取textarea光标在视口中的位置 const inputRect = input.getBoundingClientRect(); const cursorRect = inputRect.cloneNode(false); cursorRect.left = inputRect.left + input.selectionStart * 8; // 粗略估算，实际需用getSelectionRange // 更精确做法：用canvas测量文本宽度（见下文） window.unityInstance?.SendMessage('InputHandler', 'ShowCursor', JSON.stringify({ show: true, x: cursorRect.left, y: cursorRect.top }));

5.2 精确光标定位：用Canvas 2D API测量文本宽度（支持中文字体）

input.selectionStart只是字符索引，无法直接转为像素位置。正确做法是用<canvas>测量：

function measureTextWidth(text, fontSize, fontFamily) { const canvas = document.createElement('canvas'); const ctx = canvas.getContext('2d'); ctx.font = `${fontSize}px ${fontFamily}`; return ctx.measureText(text).width; } // 在syncToUnity中调用 const preText = input.value.substring(0, input.selectionStart); const width = measureTextWidth(preText, 16, 'sans-serif'); // 字体需与Unity一致 // 推送width给Unity，Unity用它计算光标X坐标

注意：measureText对中文字体支持良好，但需确保fontFamily与Unity TMP_FontAsset使用的字体名一致（如"Noto Sans CJK SC"），否则宽度偏差可达30%。

5.3 输入法状态可视化：让用户知道“正在输入拼音”

当input.composing === true时，可在Unity中显示一个微动的省略号...或“输入中”提示：

public TextMeshProUGUI composingHint; public void OnDOMInput(string json) { var data = JsonUtility.FromJson<InputData>(json); if (data.isComposing) { composingHint.text = "输入中..."; composingHint.enabled = true; } else { composingHint.enabled = false; } }

这解决了用户最大的焦虑：“我打了‘xian’，为什么没出字？”——视觉反馈直接告诉用户“系统正在等你选词”。

5.4 无障碍（Accessibility）补全：为屏幕阅读器提供语义支持

单纯<textarea>对NVDA、VoiceOver等读屏软件不够友好。需补充ARIA属性：

<textarea id="webgl-input" aria-label="游戏内文本输入框" aria-describedby="input-hint" aria-live="polite"> </textarea> <p id="input-hint" style="position: absolute; left: -9999px;">请输入您的内容，支持中文输入法</p>

aria-live="polite"确保输入内容变化时，读屏器会温和播报，不打断用户操作。

从那以后我每次交付WebGL项目，都会在index.html里预埋这套输入桥接代码，并用#webgl-input的opacity: 0.3临时开启调试模式，盯着它在各种分辨率、全屏/窗口、PC/手机上跑三遍——不是因为强迫症，而是见过太多客户在验收现场，因为一个输入框卡住，整场演示崩掉。这套方案没有魔法，只有对浏览器行为的敬畏和对Unity限制的坦诚。希望帮到你。

本文还有配套的精品资源，点击获取