故障排查
以下各节从可见现象出发，按常见程度列出原因，并链接到详细说明。
文本
文本不显示
- 缺少字体。 没有已加载的字体资源，文本不会绘制。引擎应用需要
pc.FontHandler，且字体必须加载完成。 - 缺少字符。 字体中没有的字符会显示为空格，控制台会逐一警告。应将其加入字体，详见选择字符。
- 颜色或不透明度。 文字与背景同色，或
opacity为 0 时，虽然存在也不可见。 - 位于屏幕外。 未设置锚点的元素默认位于父项左下角，可能超出可见范围，详见锚点。
文本不换行
需要启用 Wrap Lines 并提供约束宽度：关闭 Auto Width 后设置宽度，或使用水平分离锚点。详见尺寸、换行与行数限制。
文本不缩小适配
Auto Fit Width 和 Auto Fit Height 仅在对应的 Auto Width 和 Auto Height 关闭时生效，详见缩小适配。
标记显示为普通文本
需要启用 Enable Markup。启用后，如果存在标签未闭合等错误，文本仍会原样显示，控制台会报告错误，详见标记。
输入
点击被忽略
- 没有
ElementInput。 引擎应用需自行创建，详见配置。 - 输入关闭。 只有启用 Use Input 的元素接收输入，详见启用界面输入。
- 其他元素覆盖。 上层启用输入的元素，例如不可见组，会优先接收点击，详见命中检测。
- 摄像机未渲染所属图层。 仅通过渲染相应图层的摄像机检测元素。
- 被遮罩裁切。 只有遮罩矩形内的部分接收输入，详见遮罩与输入。
- 指针已锁定。 锁定时忽略鼠标按下，详见指针锁定。
- 按钮未激活。
active关闭时不触发按钮事件，详见禁用按钮。 - 正在编辑器视口中测试。 视口界面不响应输入，应启动场景。
界面点击同时传到游戏
在界面的 mousedown 和 touchstart 处理中阻止传播，并先创建 ElementInput，再创建鼠标和触摸设备。详见隔离游戏输入。画布上方的 HTML 则参阅隔离 HTML 输入。
触摸点击穿透到按钮后方
触摸后浏览器发送模拟鼠标事件。若按钮点击后隐藏，事件就会到达后方对象。应取消画布的 touchend 默认行为，详见触摸屏。
按钮
悬停或按下时外观不变
悬停时按钮变灰或不透明
染色会替换图像颜色和不透明度，默认染色是灰色且完全不透明。请设置匹配按钮的颜色，详见染色。
尺寸与缩放
界面过小、过大或放不下
- Scale Mode 为 None。 未使用 Blend 时，界面按像素构建，不跟随画布尺寸，详见 Blend 缩放。
- 像素比。 None 模式下，更高像素比会使界面更小，详见像素比。
- Scale Blend。 竖屏下取 1 会使按横屏设计的界面过宽，详见选择缩放混合值。
- 世界空间屏幕缩放。 米制尺寸等于分辨率乘实体缩放，详见尺寸与缩放。
界面被压扁
摄像机 rect 仅覆盖部分画布时，会将屏幕空间界面压缩到该区域，详见图层与摄像机。
滚动视图与布局
滚动视图不滚动
- 内容未启用输入。 要从空白处拖动，内容元素需要开启 Use Input。
- 内容不大于视口。 滚动视图不会自动调整内容尺寸，详见内容尺寸。
- 未设置滚动轴、模式或摩擦。 代码创建时需显式配置，详见创建滚动视图。
- 没有鼠标设备。 引擎中鼠标拖动需要
pc.Mouse。
部分内容初始就在视口外
滚动视图按内容轴心定位，轴心必须为左上角 [0, 1]。居中轴心会使一半内容超出左侧或顶部，详见滚动视图。
布局组中锚点或位置不生效
布局组会设置子项的锚点、位置和计算尺寸。可通过 LayoutChild 的 Exclude from Layout 排除子项，详见子项放置规则。
图像与遮罩
遮罩内没有内容
自定义材质不可见
UI 图层仅绘制透明材质，应设置 blendType 开启混合，详见自定义材质。
图像出现暗边或亮边
纹理透明像素的颜色被滤波混入可见边缘，详见避免暗边。
本地化
显示本地化键而非译文
- 当前语言区域及其回退语言都没有该键的消息。
- 文件未加载。
app.i18n不负责加载本地化文件。编辑器中应保留这些资源的 Preload，详见加载文件。
显示 {number}
该键对应复数消息。文本元素会显示第一种形式，并保留 {number}。应通过脚本调用 getPluralText 设置文本，详见脚本中的字符串。
切换语言后文本消失
该语言区域指定了独立字体，加载完成前文本不会显示，详见本地化字体。
绘制
界面绘制两次
两个摄像机都渲染 UI 图层，应从另一个摄像机移除，详见图层与摄像机。
元素顺序错误
元素按层级顺序绘制，将应置顶的元素移到其他元素之后，详见绘制顺序。React 中，新 <Entity> 始终添加到已有同级项之后，与 JSX 位置无关。屏幕重叠时应设置不同优先级，详见多屏幕与优先级。
世界空间界面从背面消失
世界空间屏幕为单面，详见背面观察。
世界空间界面穿墙
摄像机使用 CameraFrame，绘制 UI 图层时没有场景深度，详见世界空间界面与后处理。