> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Touchpad

> Touchpad

# Touchpad

一种模拟控件，使玩家能够以类似笔记本触控板的方式进行交互。

## 属性

`type` - "touchpad"

`axis` - *object* 或 *array*。描述此触控板控件映射关系的单个[轴](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-axis)或[轴](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-axis)数组。

`action` - *object*，*可选*。除轴映射外在触摸时要调用的[操作](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-action)。

`renderAsButton` - *boolean*，*可选*。默认为 `false`。设置为 `true` 会将触控板在视觉上呈现为按钮。

`enabled` - *boolean*，*可选*。默认为 `true`。将控件的可视状态设置为启用/禁用。禁用的控件仍会接收玩家的输入，但不会根据输入更改其可视样式。

`visible` - *boolean*，*可选*。默认为 `true`。确定该控件是否显示给玩家进行交互。要在游戏过程中更改，请参阅[使用游戏状态更改触控布局](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-changing-layouts-game-state.md#change_state)。

`styles` - *object*，*可选*。控件视觉表示的自定义。样式表示为每个可样式化状态对应的一个对象。

按钮控件可以为以下状态设置样式：

* `default` - 基本样式。
* `disabled` - 控件被禁用时的样式。如果未指定，控件被禁用时将对默认样式应用一个变换以使其显得已禁用。
* `idle` - 玩家未与控件交互时应用。
* `moving` - 玩家触摸控件且未定义 `action` 时应用。
* `activated` - 玩家触摸控件且定义了 `action` 时应用。

**每个状态的样式属性**

`opacity` - *number*，*可选*。应用于控件的不透明度。除 `disabled` 外的所有状态默认为 1.0。

`background` - *object*，*可选*。可以是[颜色](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-color)或[图像资源](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-asset)。

`faceImage` - *object*，*可选*。可以是[图标](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-icon)或[图像资源](/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-asset)。

**资源尺寸**

对于接受图像资源的每个样式对象，给定的资源以基础分辨率提供，并以该基础分辨率的 1.5x、2.0x、3.0x 和 4.0x 缩放提供。给定图像的分辨率必须小于或等于以下最大分辨率：

| 对象 | @1.0x | @1.5x | @2.0x | @3.0x | @4.0x |
| :- | :- | :- | :- | :- | :- |
| faceImage | 60x60 | 90x90 | 120x120 | 180x180 | 240x240 |
| background (renderAsButton = true) | 60x60 | 90x90 | 120x120 | 180x180 | 240x240 |
| background (renderAsButton = false) | 120x120 | 90x90 | 240x240 | 360x360 | 480x480 |

## 备注

`touchpad` 最适合非粘滞、无死区的输出——通常用于第一人称/第三人称视角游戏中的视角摄像机。

对于支持鼠标输入的游戏，`touchpad` 可以与相对鼠标配合使用，以提供更精细调优的视角摄像机体验。

**样式备注**

当 `renderAsButton` 为 `true` 时：

* 处于 `activated` 状态时，`faceImage` 显示为小 25%。
* 对于不使用自定义资源、并且仅有单一操作 `gamepadX`、`gamepadY`、`gamepadA` 或 `gamepadB` 的按钮，其背景色具有标签和默认样式。

## 示例

#### 示例 1：带有观察图标的触控板

**图 1. 触控板控件**

![用户与触控板交互](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/game-streaming-touch-control-images-touchpad.gif?s=964c6d216b29d4d0f46f3bf0c9ae96e2)

```JSON theme={null}
{
    "type": "touchpad",
    "axis": {
        "input": "axisXY",
        "output": "rightJoystick",
        "sensitivity": 3
    },
    "styles": {
        "default" : {
            "faceImage" : {
                "type": "icon",
                "value": "look"
            }
        }
    }
}
```

#### 示例 2：带有观察图标并呈现为按钮的触控板

**图 1. 按钮式触控板控件**

![用户与呈现为按钮的触控板交互](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/game-streaming-touch-control-images-touchpad-renderAsbutton.gif?s=e803a482b67fdb7ad2eaea7608d4b0c3)

```JSON theme={null}
{
    "type": "touchpad",
    "renderAsButton": true,
    "axis": {
        "input": "axisXY",
        "output": "rightJoystick",
        "sensitivity": 3
    },
    "styles": {
        "default" : {
            "faceImage" : {
                "type": "icon",
                "value": "look"
            }
        }
    }
}
```

## 要求

**布局版本：** 1.0+（样式功能自布局版本 3.0+ 起可用）


## Related topics

- [Touch Adaptation Kit](/reference/system/touchadaptationkit/touchadaptationkit-reference.md)
- [Templates](/build/core-features/common/game-streaming/tak-command-line-tool/game-streaming-tak-command-line-templates.md)
- [Modelos](/pt-BR/build/core-features/common/game-streaming/tak-command-line-tool/game-streaming-tak-command-line-templates.md)
- [Touch Adaptation Kit (TAK) Reference](/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-kit-overview.md)
- [触控适配布局的自定义资产](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-custom-assets.md)