企业官网建设流程全解析

简介：这套示例面向 Unity 开发者，演示 WebGL 中文输入、输入法跟随及全屏模式适配，解决浏览器中中文输入法无法正常唤起、光标移动后输入框不跟随、全屏切换定位失效等问题。压缩包共 19 个文件，整体约 17.4MB，主要包含 Unity 构建产物、HTML 入口、JavaScript 交互脚本、CSS 样式、图标、说明文档及辅助程序，可对照查看页面、脚本与构建结果之间的配合。已有 939 人学习下载。示例展示了 JS 与 Unity 通过 JSIL 接口通信的流程，包括监听键盘事件、调用浏览器原生输入法、根据 Canvas 光标位置动态定位输入框，以及处理全屏 API 带来的 DOM 变化。同时目录结构清晰，适合作为同类输入功能的改造模板，也有助于排查不同浏览器和系统下的输入法兼容问题；在此基础上还可继续定制输入法样式、增加延迟加载与异常处理。

1. 一个输入法差点毁掉 Web 版图形编辑器：Unity WebGL 中文输入问题究竟在哪

某开发者用 Unity 做了一个 WebGL 版的地图标注工具，核心是一个带 InputField 的属性面板。第一轮真机测试时，他用微软拼音在输入框里敲"路网密度"，屏幕上先冒出一串"luwangmídu"，候选框还死死钉在画布左上角，回车确认后输入框里变成"路网"两个字，第三个字直接蒸发。这个现象几乎每个做过 Unity WebGL 编辑器的人都撞上过：Unity 的 UI 系统默认拿不到输入法组合阶段的中间字符串，IME 候选框也不会跟随光标走。这次拆的项目就是专门解决这两个痛点的 Demo，它自带输入法跟随和全屏切换，适合给 Web 端交互工具、后台配置面板、图形编辑器做输入法补齐。下面把它的实现链路和接入参数逐一拆开。

2. 拆解这个 Demo：IME 跟随的完整链路

2.1 Unity WebGL 输入法失效的根源：两层脱节

先讲清楚为什么默认的 Unity WebGL 输入框打不了中文。浏览器里的输入法分为两个阶段：组合阶段（composition）和提交阶段（commit）。拼音输入时，字母先进入组合状态，候选词浮在 IME 窗口里，用户按空格或数字确认后才提交最终汉字。问题在于，Unity WebGL 通过 emscripten 模拟了一套键盘事件流，它只感知到 keydown 和 keyup，对浏览器原生的 compositionstart、compositionupdate、compositionend 这三个事件基本无感。于是输入法在组合阶段产生的中间拼音被 Unity 当作普通按键处理，直接塞进了 InputField 的字符串缓冲区，等 IME 提交真实汉字时，Unity 侧要么多拼了一遍，要么漏掉后面的字符。

另一个脱节是坐标。InputField 里光标的位置是 Unity 世界坐标，而 IME 候选框需要知道它在浏览器屏幕上的 CSS 像素坐标。Unity 的 UGUI 坐标原点在屏幕左下角，且受 Canvas 缩放模式影响；浏览器坐标系原点在左上角，canvas 元素在页面里还有偏移，两者的换算关系如果没有单独处理，候选框就会永远贴在窗口左上角或左下角。这个 Demo 的价值在于把上面两层脱节全部补齐：C# 侧维护一个组合字符串，js 侧监听 IME 事件并推送数据，再把光标坐标换算成浏览器坐标动态喂给 IME。

2.2 Demo 的交互链路拆解

这个 Demo 的组件组织不复杂，核心链路分四段：输入框、组合串管理、IME 事件桥、坐标同步。输入框是一个常规的 UGUI InputField，但它没有依赖 Unity 原生键盘输入，而是挂了一个适配脚本，接管文本显示；组合串管理在 C# 里维护当前正在输入的拼音串，并负责在提交时合并到最终文本；IME 事件桥是一个 js 插件，放在 StreamingAssets 或 Plugins 目录下，浏览器加载页面后自动注册事件监听。

流程可以这么理解：用户敲键盘，浏览器先触发 compositionstart，js 桥里立刻向 Unity 发一条 StartComposition 消息；后续每次击键触发 compositionupdate，桥里把当前的完整拼音串发给 C#；用户选词确认后 compositionend 触发，桥里把最终选中文本发给 C#，并标记组合结束。C# 侧收到消息后，先清空上一轮组合缓存，把新拼音追加到输入框字符串的插入位置，同时刷新光标显示。整个过程中 Unity 原生键盘事件被完全旁路，IME 的中间态和最终态都用 js 桥传入。

2.3 关键脚本与参数说明

Demo 里需要关注的脚本有三个。InputFieldIMEAdapter.cs 挂在每个需要支持输入法的 InputField 上，负责接收 js 层消息、操作文本缓冲区，并提供光标位置的计算接口；ImeBridge.jslib 是外部函数接口定义，声明了三个 C# 调用 js 的方法；index.html 里的嵌入脚本是真正的桥实现，负责监听事件并调用 Unity 的 SendMessage。

参数方面，核心变量如下表。

需要手工调整的重点是 imeOffset。候选框竖排显示时通常要浮在光标下方一段距离，不同输入法对偏移的敏感程度不一样，我在项目里一般从 12 开始试，往上加到 20 基本覆盖主流输入法。updateInterval 不建议小于 0.05，否则坐标推送太频繁，低端设备会有可感知的整机卡顿。

2.4 坐标换算的数学原理

光标跟随的核心是一个归一化坐标到屏幕坐标的换算。InputField 的 caretPosition 拿到的是字符索引，先通过 TextGenerator 的 characterToLine 找到行号，再算出光标在文本范围内的相对位置，最后把这个相对位置转成 UGUI 世界坐标。得到世界坐标后，用 Camera.WorldToScreenPoint 转成屏幕点，此时 y 轴方向是反的，需要用屏幕高度减去该值，再除上 Canvas 的 scaleFactor 得到 CSS 像素值。

这一步有个隐藏坑：如果不在 Canvas 根节点挂 CanvasScaler，scaleFactor 恒为 1，缩放模式下做小窗口适配时会整体偏移。调试时我习惯先固定到 1920x1080 验证基准坐标，再拉小窗口看候选框是否跟着光标走，拉变形说明 scaleFactor 没有被正确传进 js 桥。

3. 把这些逻辑集成进自己的项目：四步接入法

3.1 把 Demo 里的核心脚本复制进工程

拿到这个 Demo 包后，第一步不是急着跑场景，而是把 Assets 目录下与 IME 相关的文件夹整个拷进目标工程。我一般复制三个文件：InputFieldIMEAdapter.cs、ImeBridge.jslib，以及一个带完整预制体的示例 UI 界面。示例场景里的 InputField 是调好的，直接拖到自己界面上能省掉大量反复设置属性的时间，但要注意示例里的字体可能不是你要用的字体，需要替换成项目内字体，否则中文会显示成方框。

复制完成后，打开 InputFieldIMEAdapter.cs，把顶部的命名空间改成自己工程的根命名空间。这个脚本引用了 UnityEngine.UI 和 System.Runtime.InteropServices，如果你工程里 UI 包版本较老，需要确认 UnityEngine.UI 命名空间还在，新版本工程则要注意 InputField 已经挪到不同程序集，引用关系可能要手动补一条。

3.2 给输入框挂适配脚本并配置参数

在场景里选中目标 InputField，挂上 InputFieldIMEAdapter。这个脚本有几个需要手动拖拽引用的字段：targetInputField 指向同物体上的 InputField，caretRenderer 指向光标显示的 Image，bridgeObject 指向场景中一个常驻的空物体（用来接收 js 层 SendMessage）。如果场景里没有常驻物体，可以新建一个名为 IMEBridge 的空物体，脚本挂上去即可。

配置完成后，打开 InputFieldIMEAdapter.cs 的 Awake 方法，检查 Start 注册那一行是否绑定了事件。默认实现里会对 targetInputField 的 onValueChanged 做一次监听，但这里要注意，适配脚本接管之后，Unity 自己的 onValueChanged 可能被屏蔽，第三方业务逻辑如果也用这个事件同步数据，需要额外手动转发。

提示：如果你的输入框放在 ScrollRect 或 CanvasGroup 里，配置时一定把脚本里 useScrollOffset 开关打开，否则滚动容器后坐标整体漂移。

3.3 在浏览器模板中引入 js 桥

下一步是处理网页模板。打开工程的 index.html，在 里、UnityLoader 的 script 标签之后，手动插入 ImeBridge 的实现代码。这段代码不能放在 UnityLoader 之前，否则 SendMessage 方法还不存在，事件回调会报空引用；也不能放在 createUnityInstance 之后，必须放在其前面定义函数，但函数体内的 SendMessage 调用在运行时才执行，所以方法可以前置定义。

这段桥负责的脏活有三件：监听 composition 事件并把字符串推给 Unity；监听 canvas 上的 click 事件，让 Unity 侧知道输入框是否聚焦；以及暴露一个 setIMECaret 方法，接收 C# 传来的坐标并移动候选框。调试时如果发现事件没触发，先打开浏览器控制台，手动执行一下 window.getComputedStyle(canvas)，看看 canvas 元素是否真的存在。某些异步加载模板里 canvas 还没创建，桥代码就已经执行了，需要在 Unity 实例化完成后再挂载监听器。

3.4 全屏模式下的坐标重算

全屏切换是这个 Demo 的另一个卖点。全屏后 canvas 元素会被拉伸到整个屏幕，光标坐标和候选框位置必须重新计算。实现方式是监听浏览器的 fullscreenchange 事件，在该事件触发时向 C# 发送一条 ScreenSizeChanged 消息，C# 侧收到消息后重新读取当前 Canvas 的实际宽高和缩放因子，并把新的坐标系起点推回 js 层。

这里有个容易被忽略的点：全屏 API 在不同浏览器下回调时机不同。Chrome 系在全屏动画结束后触发，Safari 系则在动画开始前触发。如果 C# 在动画过程中重算坐标，取到的 canvas 尺寸是中间帧，候选框会偏移几个像素。我一般的处理是延迟 100 毫秒再重算，代码里加一个 Invoke("RecomputeCaret", 0.1f)，实测最稳。你的项目如果对动画流畅度要求高，可以监听 transitionend 事件做同步。

4. 避坑记录：中文输入法接进来的五个暗坑

4.1 回车确认后输入框里出现半个拼音

现象：用户在组合阶段按回车确认汉字，输入框里最终显示成"路网"加一个"u"。

原因：compositionend 事件触发时，浏览器的默认行为会把组合串中的最后一个按键再触发一次 keydown，这个 keydown 没有被 js 桥拦截，漏进了 Unity 原生键盘流程。Unity 把它当普通字符处理，追加到了输入框尾部。

解决：在 ImeBridge 的事件回调里，先执行 event.preventDefault() 阻止默认行为。并且要检查 compositionend 的 data 是否为空，某些输入法在按 Esc 取消组合时会传入空串，此时不应该做任何提交。

4.2 候选框跟随偏了一大截

现象：候选框出现在光标右上方很远的位置，或者直接显示在左上角。

原因：典型的两处错误。一是 C# 到 js 的坐标推送没有除以 devicePixelRatio，高 DPI 屏上坐标偏大；二是 Memory 拷贝时浮点数被截断。

解决：js 桥里拿到坐标后先除以 window.devicePixelRatio 再设置 caret。另外检查 Emscripten 的堆读写，确保用 float 数组而非 int 数组传递坐标。这里最容易翻车的是把 ReceiveArray 的返回值当成 int 用，C# 侧需要显示转成 float。

4.3 全屏切换后候选框跑到画布外面

现象：从窗口模式切换全屏后，候选框出现在屏幕左上角，光标在右下角输入时，候选框也不跟随。

原因：全屏切换后 canvas 元素的 clientWidth 和 clientHeight 没有及时同步给 C#，js 侧还在用旧的窗口尺寸做坐标换算，差值一大候选框就飞出去了。

解决：C# 侧不要缓存全屏前的画布尺寸，每次计算坐标前都通过桥方法重新读取当前 clientWidth 和 clientHeight；且在全屏切换后做一次延时重算。这类问题在无头浏览器里自动化测试很难发现，必须真机手测。

4.4 iOS 设备上组合事件顺序错乱

现象：某 iPad 真机上，拼音打了三个字母，候选框一直没出现，等按空格后一次跳出三个汉字。

原因：iOS 的 WKWebView 对 compositionstart 的触发时机和桌面浏览器不同，它有时会把事件合并到 input 事件里统一派发，js 桥监听 compositionupdate 就饿死了。

解决：同时监听 input 事件作为兜底，在 input 里判断 event.isComposing，如果为 true 就当作 compositionupdate 处理。注意不能直接用 inputType 过滤，iOS 上 inputType 的值各版本不一致，isComposing 反而是全平台可靠的。

4.5 组合状态下光标不可见

现象：组合过程中，InputField 的光标闪动停止，用户看不到当前插入位置。

原因：Unity 的 InputField 光标默认依赖自身键盘焦点循环刷新，IME 组合状态切断了 Unity 原生键盘事件，光标刷新逻辑停转。

解决：适配脚本里的 updateInterval 定时器负责全周期刷新光标，但必须在 IME 组合期间保持较高频率。实测 updateInterval 设为 0.1 时，在低端安卓上会有点闪烁感，我一般在这个设备上改为 0.2，其他设备保持 0.1。

5. 进阶：把输入法跟随做成团队通用的补丁库

这个 Demo 跑通之后，我做了一次重构，把针对单个输入框的适配逻辑抽成了通用静态方法，这样组里其他人接入时不用关心事件链路。做法是把坐标计算的代码段从 MonoBehaviour 里拆出去，放到一个 IMEUtility 静态类中，公开三个方法：GetCaretScreenPosition、ConvertToBrowserCoord、PushCaretToBridge。挂载脚本只需要调用这三个方法，桥的注册在校验环境里自动完成，省掉了每个人的复杂配置。这种封装特别适合团队统一维护，因为输入法支持的演进（比如新增语音输入、手写输入）只改动桥的 js 层，C# 侧接口保持稳定。

另外一个值得长期保留的习惯是：每次接收到一个新的 Unity 或浏览器版本时，强制走一遍"中文输入、长按空格、快速回车、缩放窗口"四连测。不要觉得这次改动和输入法无关就跳过冒烟，Unity 的 WebGL 发布工具链升级时，canvas 上的事件绑定方式经常会变，js 桥和 C# 的对接最容易在这里断掉。我把这四条测试写在团队的提交前检查清单里，已经提前拦下了至少三次线上隐患。希望这套拆解能帮你少踩几个暗坑，做完输入法兼容后也别忘了补一个全屏切换的回归用例。

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