> 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()`](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md) 进行分支判断。
* **将关键 UI 放在** [**安全区域**](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/safe-area.md)**.** 设备的硬件边缘区域（刘海、状态栏、主屏幕指示条）默认会为你留出；只要不要通过 `screenInset: 'none'`选择退出即可。客户端自己的控件位于另一个区域，而 `screenInset: 'interactable'` 也能处理其中一部分：它会将 UI 放置在浏览器为场景 UI 指定的矩形区域内。在移动端，这会避开左侧控件；右下角的操作按钮则按设计叠加在该区域上，因此请留意 [这些角落](https://docs.decentraland.org/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](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale) —— `1600x720` 是移动端默认值， `1920x1080` 则是桌面端和网页版的默认值。请确认像素值所依据的参考分辨率；如果不是默认值，请明确传入，并搭配适应平台的尺寸设置。只有确实需要使用原始画布像素时，才禁用虚拟屏幕（传入尺寸 `0`）。
* **不要将元素放在安全区域之外。** 否则会与客户端控件冲突。
* **不要将 UI 锚定在左上角或左侧边缘。** 客户端会在这里绘制聊天、个人资料和虚拟摇杆，这些内容都会覆盖在场景 UI 上。请改为锚定在右侧或中央，或者使用 `screenInset: 'interactable'`。请参阅 [切勿将 UI 锚定在左上角](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/ti-yan-she-ji/ux-ui-guide.md#never-anchor-your-ui-to-the-top-left).
* **不要在右下角放置可交互元素。** 操作按钮会覆盖该区域，在那里点击会触发客户端按钮，而不是场景中的元素。
* **不要依赖小按钮。** 在触摸屏上，小型目标很难可靠地点按。
* **不要将按键操作绑定到 `IA_SECONDARY` 或 `IA_ACTION_3`–`IA_ACTION_6`** （也就是键盘上的 `F` 和 `1`/`2`/`3`/`4` 键），除非场景中显示了这些按钮。在移动设备上，这些按钮默认隐藏（SDK 7.32.0+）。请参阅 [移动设备上的输入](https://docs.decentraland.org/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()
  // ... show your UI
}

function closeScoreboard() {
  TouchScreenControls.showDefault()
  TouchScreenControls.showJoystick()
  // ... hide your UI
}
```

使用 `showDefault()` 而不是 `showAll()` 来恢复按钮：场景初始时仅显示跳跃、指针和主操作按钮，因此 `showAll()` 会重新显示玩家原本并没有的另外五个按钮。三按钮默认设置和 `showDefault()` 都需要 SDK 7.32.0 或更高版本；在较旧的 SDK 上，八个按钮都会显示，而 `showAll()` 是恢复这些按钮的唯一方法。 `showDefault()` 只会恢复游戏手柄按钮，因此还要配合 `showJoystick()`使用。这两个辅助函数在桌面设备上均不起作用，因此无需按平台进行分支处理。请参阅 [屏幕控件](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md) 了解完整组件。

如果还希望面板打开时角色停止移动，请再添加一个 [输入修改器](https://docs.decentraland.org/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 倍**，视网膜屏笔记本电脑上也一样。无法关闭此功能。
* **虚拟屏幕会根据平台采用不同的默认值**, `1600x720` 在移动设备上，而 `1920x1080` 在桌面端和 Web 端，因此在手机上，相同的像素值已经能覆盖约 1.2 倍的屏幕区域。

沿用现有的桌面端尺寸作为起点，在真实设备上进行测量——请参阅 [在移动设备上预览](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/preview-on-mobile.md) ——只有在点击目标或文本确实显得过小时才放大。需要两者有所不同时，可使用 [`isMobile()`](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md) 进行分支处理。

## 相关内容

* [缺失功能](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/yi-dong-ke-hu-duan/missing-features.md)
* [移动设备安全区域](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/safe-area.md)
* [在代码中检测平台](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md)
* [屏幕 UI](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md)
* [UX 与 UI 指南](https://docs.decentraland.org/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.
