> 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/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md).

# 屏幕控制

为你的场景配置原生的屏幕触控控制。

在移动客户端上，玩家通过一组原生屏幕控件与你的场景交互——一个虚拟摇杆、一个准星，以及一组游戏手柄按钮。这个 `TouchScreenControls` 组件让你的场景重塑该 HUD：减少杂乱、隐藏摇杆或准星、改变中央大按钮的功能、将某个按钮的图标替换为你自己的图标，或者直接隐藏按钮并用你自己的 UI 替代它们。

<figure><img src="https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-0a69ce0ba0199fe829376ff409c7ffa02c679b0a%2Ftouch-controls-default.jpg?alt=media" alt="The default mobile HUD: virtual joystick on the left, gamepad buttons on the right"><figcaption><p>自定义之前的默认屏幕控件</p></figcaption></figure>

{% hint style="info" %}
该组件会在玩家进入你的场景时自动生效，并在他们离开的那一刻恢复为默认设置（不隐藏任何内容，跳跃作为中央按钮）——因此不使用它的场景不会受影响。它只影响带有原生屏幕控件的平台：在桌面端上不起作用，在 VR 中也没有效果。
{% endhint %}

## 按钮布局是如何工作的

游戏手柄按钮构成一个单一的 **优先级栈**。顺序是固定的：

1. `IA_JUMP`
2. `IA_POINTER`
3. `IA_PRIMARY` (E)
4. `IA_SECONDARY` (F)
5. `IA_ACTION_3` (1)
6. `IA_ACTION_4` (2)
7. `IA_ACTION_5` (3)
8. `IA_ACTION_6` (4)

屏幕上的位置也是固定的。这个 **可见的** 按钮会从栈顶向下填充这些位置——所以你更改的是 *哪些* 按钮可见，以及 *哪个按钮在最前面*，而不是它们的顺序。

| 当你……时                                    | 控件……                                                    |
| ---------------------------------------- | ------------------------------------------------------- |
| **隐藏一个按钮** （任何按钮，包括跳跃）                   | 每个更低优先级的按钮都会上移以填补空位。隐藏跳跃按钮后， `IA_POINTER` 下一个按钮会占据中央位置。 |
| **保持栈不变**                                | 第一个按钮（`IA_JUMP`）是中央大按钮；接下来的按钮填充周围的槽位。                   |
| **设置主按钮** 中调用你的 UI 渲染方法，并使用 `mainAction` | 该动作会跃至最前并成为中央按钮；其他所有按钮保持其正常顺序。                          |
| **设置一个同时被隐藏的主按钮**                        | 隐藏优先——该按钮仍然保持隐藏。                                        |
| **仅保留 5 个或更少的按钮可见**                      | 它们都会直接显示（中央按钮加上最多四个环绕按钮）；没有“+”菜单。                       |
| **保留超过 5 个按钮可见**                         | “+”会占据最后一个槽位，因此会直接显示四个按钮（中央按钮加上三个），其余按钮则位于“+”溢出切换器之后。   |

<figure><img src="https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-67ed40e222e68d9b13997d0b2fec7e399fc57de0%2Fcontrol-ordering.jpg?alt=media" alt="Three HUDs showing the gamepad reflowing as the number of visible buttons changes"><figcaption><p>按钮会如何随可见数量重新布局。 <strong>左侧（7 个按钮）：</strong> 主按钮、1–3 的弧形排列，以及在一列向上延伸的按钮中由“+”承载的溢出项（4–7）。 <strong>中间（5 个按钮）：</strong> 相同的弧形排列，后面有一个更短的溢出列（4–5）位于“+”之后。 <strong>右侧（4 个按钮）：</strong> 全部四个都直接显示，“+”消失。</p></figcaption></figure>

{% hint style="info" %}
这也是你显示 `1`/`2`/`3`/`4` 按钮的方法；它们通常藏在“+”后面：隐藏足够多的更高优先级按钮，将可见数量降到五个或更少，它们就会直接显示。
{% endhint %}

## 常见任务

`TouchScreenControls` 提供了一组便捷辅助函数。每个函数都会把组件写入场景的 `RootEntity` （客户端从这里读取），并与当前值合并，因此你可以从任何地方调用它们。

**更改主按钮** ——让中央大按钮触发不同的动作：

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

export function main() {
	TouchScreenControls.setMainAction(InputAction.IA_PRIMARY)
}
```

**隐藏摇杆或准星** ——移除移动摇杆和/或瞄准准星，并通过它们的 `显示` 对应函数把它们恢复：

```ts
TouchScreenControls.hideJoystick()
TouchScreenControls.hideCrosshair()

// 然后把它们恢复：
TouchScreenControls.showJoystick()
TouchScreenControls.showCrosshair()
```

**隐藏特定按钮** ——传入你想移除的动作（其余动作会级联上移）：

```ts
TouchScreenControls.hide([InputAction.IA_SECONDARY, InputAction.IA_JUMP])
```

**隐藏或显示所有按钮** ——清空 HUD，或重置它：

```ts
TouchScreenControls.hideAll()
TouchScreenControls.showAll()
```

`showAll()` 只会影响游戏手柄按钮——它不会恢复已隐藏的摇杆或准星。对这些内容请使用 `showJoystick()` / `showCrosshair()` 。

**替换某个按钮的图标** ——如果要完全控制（自定义图标、一次进行多项更改），请直接在场景的 `engine.RootEntity`:

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

export function main() {
	TouchScreenControls.createOrReplace(engine.RootEntity, {
		hideCrosshair: true,
		mainAction: InputAction.IA_PRIMARY,
		touchInputs: [
			{
				inputAction: InputAction.IA_PRIMARY,
				icon: { tex: { $case: 'texture', texture: { src: 'images/grab.png' } } },
			},
		],
	})
}
```

辅助函数一览：

| 辅助函数                    | 作用                                     |
| ----------------------- | -------------------------------------- |
| `setMainAction(action)` | 设置中央大按钮触发的动作。                          |
| `hideJoystick()`        | 隐藏原生虚拟摇杆。                              |
| `showJoystick()`        | 再次显示原生虚拟摇杆。                            |
| `hideCrosshair()`       | 隐藏屏幕准星 / 瞄准环。                          |
| `showCrosshair()`       | 再次显示屏幕准星 / 瞄准环。                        |
| `hide(actions)`         | 隐藏给定的游戏手柄按钮（合并到当前配置中）。                 |
| `hideAll()`             | 隐藏所有游戏手柄按钮。                            |
| `showAll()`             | 显示所有游戏手柄按钮（清除按钮隐藏列表）。会 **不是** 影响摇杆/准星。 |

## 属性

在直接使用 `createOrReplace`:

| 属性              | 类型                                                                                                                        | 描述                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `hideJoystick`  | *布尔值*                                                                                                                     | 隐藏原生虚拟移动摇杆。                                                                                                                     |
| `hideCrosshair` | *布尔值*                                                                                                                     | 隐藏屏幕准星 / 瞄准环。                                                                                                                   |
| `mainAction`    | [*InputAction*](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) | 将此动作移到栈顶，使其成为中央大按钮；其他按钮保持其顺序。只有游戏手柄动作才有效（见下文）。未设置时，第一个可见按钮（`IA_JUMP` 默认情况下）会排在前面。参见 [按钮布局是如何工作的](#how-the-button-layout-works). |
| `touchInputs`   | *数组*                                                                                                                      | 逐按钮覆盖。未列出的按钮保持默认设置（显示，使用其默认图形）。                                                                                                 |

每个 `touchInputs` 条目包含：

| 字段            | 类型                                                                                                                        | 描述                                                                                                                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputAction` | [*InputAction*](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) | 此条目配置哪个屏幕按钮。                                                                                                                                                                                               |
| `hide`        | *布尔值*                                                                                                                     | 隐藏此按钮。默认值为 `false` （显示）。任何按钮都可以被隐藏， **包括 `IA_JUMP`** ——其余按钮会级联上移以填补其位置。                                                                                                                                    |
| `图标`          | [*TextureUnion*](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/ui_background.md#background) （可选）                      | 用场景中的图片覆盖按钮图形。使用带内容映射 `纹理` 的 `src` 变体（作为场景一部分包含的图片）—— `{ tex: { $case: 'texture', texture: { src: 'images/grab.png' } } }`仅支持场景内容路径（不支持外部 URL、头像或视频纹理）。对于跳跃按钮，这会替换其所有动态状态（跳跃 / 二段跳 / 滑翔）。如果路径无法解析，则使用内置图形。 |

## 哪些动作映射到哪些按钮

该 [`InputAction`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 这里的值与 [移动端输入](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/input-on-mobile.md) 和 [点击事件](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md)中使用的值相同。以下是映射到屏幕按钮的动作：

| InputAction                                                   | 屏幕按钮             |
| ------------------------------------------------------------- | ---------------- |
| `IA_JUMP`                                                     | 中央大按钮（默认）        |
| `IA_POINTER`                                                  | 交互按钮             |
| `IA_PRIMARY`                                                  | E 按钮             |
| `IA_SECONDARY`                                                | F 按钮             |
| `IA_ACTION_3` / `IA_ACTION_4` / `IA_ACTION_5` / `IA_ACTION_6` | 1 / 2 / 3 / 4 按钮 |

{% hint style="warning" %}
`IA_ANY` 和 `IA_MODIFIER` 是元值——它们不会映射到按钮，也不能在这里使用。
{% endhint %}

## 示例

要隐藏摇杆，收起带编号的按钮，并给中央的跳跃按钮换上场景中提供的自定义图标：

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

export function main() {
	TouchScreenControls.createOrReplace(engine.RootEntity, {
		hideJoystick: true,
		touchInputs: [
			{ inputAction: InputAction.IA_ACTION_3, hide: true },
			{ inputAction: InputAction.IA_ACTION_4, hide: true },
			{ inputAction: InputAction.IA_ACTION_5, hide: true },
			{ inputAction: InputAction.IA_ACTION_6, hide: true },
			{
				inputAction: InputAction.IA_JUMP,
				icon: { tex: { $case: 'texture', texture: { src: 'images/banana.png' } } },
			},
		],
	})
}
```

<figure><img src="https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-0eef110595612782808b16d7733171deeb560f16%2Fcustom-main-action.jpg?alt=media" alt="A mobile HUD with the joystick hidden and the central jump button showing a custom banana icon"><figcaption><p>结果：摇杆消失，带编号的按钮隐藏（因此“+”也消失了），而跳跃按钮则重新设定了图标</p></figcaption></figure>

要完全替换原生控件，请在此处将它们隐藏，并用你自己的触摸按钮来构建 [UI 输入绑定](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/ui_input_binding.md).

## 相关

* [UI 输入绑定](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/ui_input_binding.md)
* [移动端输入](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/input-on-mobile.md)
* [点击事件](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md)
* [从代码中检测平台](/creator/content-creator-zh/mian-xiang-yi-dong-duan-gou-jian/kai-fa/detect-platform.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/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.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.