> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/ui-best-practices.md).

# UI 最佳实践

设计在移动端表现良好的场景 UI 的注意事项与禁忌。

目前还没有针对 Decentraland 移动端 UI 的单一已验证方案——平台还很新，我们仍在不断迭代。本页建议是目前最佳实践，源自真实场景中的工作。请把它们当作起点，并在真机上测试。

{% embed url="<https://www.youtube.com/watch?v=5OmTTzpPdDc>" %}

## 应做事项

* **设计移动端专用 UI**，或根据屏幕尺寸和平台调整你的 UI。使用 [`isMobile()`](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md) 进行分支。
* **将关键 UI 保持在** [**安全区域**](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/safe-area.md)**.** 设备的硬件边距（刘海、状态栏、主页指示器）默认会为你清除——只要不要通过 `screenInset: 'none'`。客户端自身的控件是一个单独区域，并且 `screenInset: 'interactable'` 部分承担了这项工作：它会将你的 UI 放置在探索器为场景 UI 指定的矩形区域内。在移动端，这会清除左侧控件；右下角的操作按钮会按设计覆盖在该区域之上，因此请将 [这些角落](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/safe-area.md#where-the-client-controls-live) 牢记在心。 `'interactable'` 需要移动端客户端 `1.12.1` 或更新版本——旧客户端完全不会报告边距，UI 会覆盖整个屏幕。
* **尽量减少选项。** 只显示玩家此刻真正需要的内容，其余内容逐步展示。
* **将可操作对话框放在屏幕中央** ——任何玩家需要阅读并作出回应的地方。
* **将不可操作消息放在顶部居中** ——状态、通知和环境信息。
* **将触摸控制隐藏在全屏 UI 之后。** 当记分板、商店或结果面板打开时，玩家无需跳跃或按 E。参见 [覆盖操作按钮的全屏 UI](#full-screen-ui-over-the-action-buttons).

## 不应做事项

* **不要在没有考虑虚拟屏幕的情况下，仅按像素来设定 UI 元素大小。** 像素值是相对于 `virtualWidth` / `virtualHeight` 所述的参考分辨率 [屏幕上的 UI](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale) — `1600x720` 在移动端默认是， `1920x1080` 在桌面端和网页端。请明确你的像素值是基于哪个参考分辨率编写的；如果不是默认值，请显式传入，并结合考虑平台的尺寸设置。只有当你确实想要原始画布像素时，才禁用虚拟屏幕（通过传入大小为 `0`)）如果你确实想要原始画布像素。
* **不要将元素放置在安全区域之外。** 它们会与客户端控件冲突。
* **不要将 UI 锚定在左上角或左边缘。** 客户端会在那个区域绘制聊天、个人资料和虚拟摇杆，而且都覆盖在你的场景 UI 之上。改为锚定到右侧或居中，或者使用 `screenInset: 'interactable'`。参见 [永远不要把你的 UI 锚定到左上角](/creator/content-creator-zh/chang-jing-sdk7/ti-yan-she-ji/ux-ui-guide.md#never-anchor-your-ui-to-the-top-left).
* **不要将交互元素放在右下角。** 操作按钮会覆盖在该区域上，那里发生的点击会发送给客户端按钮，而不是你的场景。
* **不要依赖小按钮。** 在触摸屏上，小目标很难准确点击。
* **不要将按键操作绑定到 `IA_ACTION_3`—`IA_ACTION_6`** （桌面端的 `1`/`2`/`3`/`4` 键盘上的按键）。它们在移动端不易触及。参见 [移动端输入](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/input-on-mobile.md).

## 覆盖操作按钮的全屏 UI

`screenInset: 'interactable'` 可让你的 UI 避开左侧控件，但右下角的操作按钮会按设计覆盖在该区域。即使面板填满了该区域，也仍会被覆盖；该区域内的点击会触发客户端按钮，而不是你的 UI。

对于 **游戏 HUD** 在玩家移动时仍需可用的，请将其避开右下角：锚定到右上或顶部居中。

对于 **会中断游戏流程的 UI**，例如记分板、商店或结果界面，在其打开时隐藏触摸控制，并在关闭时恢复：

```ts
import { TouchScreenControls } from '@dcl/sdk/ecs'

function openScoreboard() {
  TouchScreenControls.hideAll()
  TouchScreenControls.hideJoystick()
  // ... 显示你的 UI
}

function closeScoreboard() {
  TouchScreenControls.showAll()
  TouchScreenControls.showJoystick()
  // ... 隐藏你的 UI
}
```

`showAll()` 只会恢复游戏手柄按钮，因此请将其与 `showJoystick()`配合使用。两个辅助函数在桌面端都不会执行任何操作，因此无需按平台分支。参见 [屏幕控制](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md) 以查看完整组件。

如果在面板打开时还应让头像停止移动，请再添加一个 [输入修饰器](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/locomotion.md#freeze-the-player) 叠加。

## 尺寸设置

旧经验法则—— *先在桌面端设计，然后将移动端的 UI 尺寸放大 3 倍* ——早于两项 SDK 变更，因此不应再盲目套用。现在其中大部分 3 倍缩放已经由系统替你应用：

* **`devicePixelRatio` 不参与 UI 布局。** 以像素为单位的 UI 现在会渲染为 `devicePixelRatio` 原来的数倍——通常是 **在手机上为 2–3 倍**，在 Retina 笔记本上也是如此。没有关闭选项。
* **各平台的虚拟屏幕默认值为**, `1600x720` 移动端相对于 `1920x1080` 桌面端和网页端，因此相同的像素值在手机上已经能覆盖大约 1.2 倍更多的屏幕。

保持桌面端尺寸不变，在真机上测量——参见 [在移动端预览](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/preview-on-mobile.md) ——并且只在点击目标或文本确实不足时再放大。使用 [`isMobile()`](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md) 在两者确实需要不同的时候进行分支。

## 相关

* [缺失的功能](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/yi-dong-ke-hu-duan/missing-features.md)
* [移动端安全区域](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/safe-area.md)
* [从代码中检测平台](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md)
* [屏幕上的 UI](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md)
* [UX 与 UI 指南](/creator/content-creator-zh/chang-jing-sdk7/ti-yan-she-ji/ux-ui-guide.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/ui-best-practices.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.