> 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/safe-area.md).

# 移动端安全区域

场景 UI 在移动端可以安全显示的区域——避开设备硬件边距和客户端自身控制。

在手机上，有两种互不相关的因素会挤占 UI 可安全使用的屏幕空间：

* **设备硬件边缘区域** ——刘海或摄像头开孔、状态栏、主屏幕指示条和圆角。绘制在这些区域下方的 UI 会被部分遮挡，或难以点击。
* **Decentraland 客户端自身的控件** ——摇杆、聊天、个人资料、摄像头控件和操作按钮。放在这些控件下方的场景 UI 会产生视觉冲突，还会争抢点击操作。

无需测量这两种区域。客户端会在运行时报告它们的范围，而 SDK 会根据你选择的范围将 UI 放置在其中，方法是使用 [`screenInset`](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-inset-area) 渲染器选项：

| 你的需求                  | 传入的值                                |
| --------------------- | ----------------------------------- |
| 避开硬件边缘区域              | 无需设置—— `screenInset: 'device'` 是默认值 |
| 避开硬件边缘区域 **以及** 客户端控件 | `screenInset: 'interactable'`       |
| 使用整个屏幕，边缘区域由你自行处理     | `screenInset: 'none'`               |

```ts
// 推荐用于不得与移动端控件冲突的场景 UI
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })
```

{% hint style="warning" %}
**客户端支持**: `'interactable'` 需要移动客户端 `1.12.1` 或更高版本。在旧版客户端中，报告的区域大小为零，UI 会退回到覆盖整个屏幕。同一版本还统一了 Android 和 iOS 之间的 `'device'` 区域。

**在桌面端并非无效操作** ——桌面客户端会为自身 UI 预留屏幕左侧约 25% 的区域，因此 `'interactable'` 也会改变桌面布局。如果只想在手机上应用内缩，请使用 [`isMobile()`](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md) 进行分支判断。
{% endhint %}

请参阅 [屏幕内缩区域](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-inset-area) 查看完整参考：真实设备上并列展示的三个区域、各渲染器的行为，以及它们与 [虚拟屏幕](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#default-virtual-size).

## 客户端控件所在的位置

`'interactable'` 会为你提供 **各个客户端指定用于场景 UI 的区域** ——但这并不意味着所有客户端控件都一定在该区域之外。移动客户端中的可交互区域是设备安全区域减去左侧栏（聊天、个人资料、摇杆、表情动作）；右下角的操作按钮则会按设计绘制在该区域 **之上**.

<figure><img src="https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e68f1a62cc357cbe24e75f24c58db7d37a4f4ee2%2Fscreeninset-interactable.webp?alt=media" alt="Scene UI inset to the area the mobile client reports as free of its own HUD"><figcaption><p><code>移动客户端上的 screenInset: 'interactable'</code> 屏幕内缩区域 <code>1.12.1</code>。洋红色矩形表示场景 UI，绿色轮廓表示可交互区域。左侧栏不包含在该区域内；右下角的操作按钮则位于该区域之上。</p></figcaption></figure>

因此，即使使用了 `'interactable'`，以下区域仍可能比较拥挤：

* **右下角** ——操作按钮和交互按钮会绘制在其上方。放在这里的内容仍然可以访问，但会与这些按钮争夺点击。
* **右上角** ——个人资料和摄像头控件位于该区域之外，因此紧贴这个角落的 UI 看起来会像是客户端 HUD 的一部分。

该区域的覆盖范围由各个 Explorer 自行决定，也可能随版本变化。请在运行时读取，切勿将其硬编码，并在目标平台上进行检查。

## 场景 UI 的放置位置

* **屏幕中央** ——可交互的对话框，以及玩家需要阅读并回应的内容。
* **顶部居中** ——不可交互的消息、状态和通知。
* **底部居中，位于交互按钮上方** ——上下文相关的提示。
* **不要放在右下角** ——即使在可交互区域内，这里也属于操作按钮。

## 改为仅对部分 UI 应用安全区域

如果你选择退出安全区域处理，使用 `screenInset: 'none'` 并且只想保护部分 UI，可以将其包裹在 `ScreenInsetArea` 或 `InteractableArea` 组件中。每个组件都会读取对应的区域，并将其应用到子元素。请从 `@dcl/sdk/react-ecs`:

```tsx
import ReactEcs, { ReactEcsRenderer, UiEntity, ScreenInsetArea } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export function setupUi() {
  ReactEcsRenderer.setUiRenderer(() => (
    <ScreenInsetArea>
      {/* 尺寸为 100% × 100% 的子元素会恰好填满安全区域 */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ), { screenInset: 'none' })
}
```

这两个组件都会使用客户端报告的数值进行绝对定位，因此其 `positionType` 和 `position` 的 `uiTransform` 字段为保留字段——你为它们设置的任何值都会被忽略。其他所有 `uiTransform` 属性（`padding`, `flexDirection`, `alignItems`、……）和 UI 组件（`uiBackground`, `onMouseDown`、……）都照常工作。当区域发生变化时（例如屏幕旋转，或系统栏显示或隐藏），它们会自动作出响应，并补偿 [UI 缩放因子](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale)，因此无论虚拟屏幕尺寸如何，边距都能准确显示。

{% hint style="warning" %}
**📔 请勿重复应用安全区域偏移：** 的 `screenInset: 'none'` 上面的代码片段中很重要。如果你将 UI 包裹在一个组件中，同时渲染器也应用了相应的内边距，你的 UI 就会被向内推移两倍的边距。二者选其一即可。
{% endhint %}

{% hint style="info" %}
**📱 仅限移动端：** 设备内边距只有在 **移动端客户端**上才有实际值。在 **桌面端客户端** 中，它们为 `(0, 0, 0, 0)`，因此 `screenInset: 'device'` 和 `ScreenInsetArea` 组件在桌面端都不会生效，你的 UI 渲染效果与未使用它们时完全相同。与设备内边距不同，交互区域 *在* 桌面端并非零值。
{% endhint %}

## 为何重要

与客户端控件重叠的场景 UI 会：

* 被摇杆、交互按钮或镜头控制部分遮挡。
* 与这些控件争抢点击操作——玩家可能会意外触发其中一个。
* 让场景在移动端显得无法正常运行，从而影响内容推荐和用户留存。

务必使用 [预览二维码](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/preview-on-mobile.md).

## 相关内容

* [屏幕内边距区域](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#screen-inset-area) ——完整的 `screenInset` 参考文档。
* [移动端 UI 最佳实践](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/ui-best-practices.md)
* [在代码中检测平台](https://docs.decentraland.org/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.md) ——使用 `isMobile()` 切换布局。
* [屏幕 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/safe-area.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.
