> 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/2d-ui/ui_input_binding.md).

# UI 输入绑定

将输入动作绑定到你自己的 UI 元素，让它们驱动玩家输入。

`UiInputBinding` 将任何 UI 元素变成控制按钮。将一个元素绑定到一个或多个 [`InputAction`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons)s，并且在它被按住时——通过触摸或指针——这些动作会持续生效，同时驱动本地玩家的输入（移动、跳跃）以及任何场景的 [`InputAction`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 监听器，就像原生屏幕按钮一样。

用它来构建你自己的触控控制。它通常与 [屏幕控制](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md)：隐藏原生按钮，然后把你自己的放到它们的位置。

<figure><img src="https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-871e8f850109fd31650535349ba3e385565845f1%2Fui-input-binding.jpg?alt=media" alt="A retro-style gamepad assembled from custom UI elements, each wired to an input action"><figcaption><p>一个完全自定义的手柄，由 UI 元素构建——每个按钮都是绑定到某个输入动作的 UI 实体</p></figcaption></figure>

## 将动作绑定到 UI 元素

添加一个 `uiInputBinding` 属性到你 `.tsx` 的 UI 中，并列出在按下时要持续保持的动作。该属性可用于每个 UI 元素（[`UiEntity`](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#ui-entities), [`按钮`](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#ui-entities), [`Label`](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/onscreen-ui.md#ui-entities)、……），就像 `uiTransform` 和 `uiBackground`.

**一个在按住时让玩家向前移动的按钮：**

```tsx
import { InputAction } from '@dcl/sdk/ecs'
import { Button } from '@dcl/sdk/react-ecs'

export const forwardButton = () => (
	<Button
		value="▲"
		uiTransform={{ width: 100, height: 100 }}
		uiInputBinding={{ actions: [InputAction.IA_FORWARD] }}
	/>
)
```

## 构建自定义控制组

将多个已绑定元素组合起来，构成一套完整的控制方案。

**一个移动按钮加上一个会触发的动作按钮 `IA_PRIMARY`:**

```tsx
import { InputAction } from '@dcl/sdk/ecs'
import { Button, UiEntity } from '@dcl/sdk/react-ecs'

export const customControls = () => (
	<UiEntity uiTransform={{ width: 240, height: 120 }}>
		<Button
			value="▲"
			uiTransform={{ width: 100, height: 100 }}
			uiInputBinding={{ actions: [InputAction.IA_FORWARD] }}
		/>
		<Button
			value="使用"
			uiTransform={{ width: 100, height: 100 }}
			uiInputBinding={{ actions: [InputAction.IA_PRIMARY] }}
		/>
	</UiEntity>
)
```

绑定的动作表现得和原生按钮一样： `IA_FORWARD` / `IA_BACKWARD` / `IA_LEFT` / `IA_RIGHT` 移动化身，并且任何动作都可以被你的场景的 [`InputAction`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 监听器读取。移除该属性（或组件）会解除绑定。

## 属性

| 属性   | 类型                                                                                                                              | 描述                                                                                                                                                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `动作` | ……的数组 [`InputAction`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) | 当该元素被按下时持续按住的输入动作。参见 [点击事件](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md) 以查看完整的 [`InputAction`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/click-events.md#pointer-buttons) 取值列表。 |

{% hint style="info" %}
将其与 [`TouchScreenControls`](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md) 以隐藏原生控制并将其替换为你自己的触控 UI——这是发布完全自定义控制方案的推荐方式。
{% endhint %}

## 相关

* [屏幕控制](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/touch-screen-controls.md)
* [UI 按钮事件](/creator/content-creator-zh/chang-jing-sdk7/2d-ui/ui_button_events.md)
* [移动端输入](/creator/content-creator-zh/wei-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)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/2d-ui/ui_input_binding.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.