> ## 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.

# Directional Pad

> Directional Pad

# Directional Pad

方向键控件，始终映射手柄方向键。

## 属性

`type` - *"directionalPad"*。指定控件类型。

`scale` - *number*，*可选*。默认为 1。大小倍数，方向键的放置方式类似按钮，不像操纵杆那样自动缩放，因此此项很有用。

`deadzone` - *number*，*可选*。介于 0 和 1 之间的值，指定死区大小占控件的百分比。请注意，与操纵杆的[死区](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-deadzone)不同，方向键的死区始终是轴向（方形）的。

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

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

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

`interaction` - *object*，*可选*。可以改变用户与控件交互机制的属性定义。

**Interaction**

`activationType` - *string*，*可选*。定义在方向键交互中任一给定方向所允许的激活类型。默认为 `allowNeighboring`。当设置为 `exclusive` 时，方向键上任何时刻只能激活一个方向（即 'Up'、'Right'、'Down' 或 'Left' 之一）。当设置为 `allowNeighboring` 时，可以通过在两个相邻方向之间点击来同时激活一个方向及其相邻方向之一（即用户可以通过在它们之间点击激活 'Up+Right'、'Right+Down'、'Down+Left' 或 'Left+Up'，同时保留独立激活各方向的能力）。

**状态和样式属性**

方向键控件可以为以下状态设置样式：

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

以下属性可用于设置方向键控件的样式：

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

`fill` - *object*，*可选*。一个定义了颜色的对象，供方向键激活时用作渐变色。

`gradient` - *object*，*可选*。一个定义了颜色的对象，供方向键激活时用作渐变色。

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

`stroke` - *object*，*可选*。用于方向键轮廓的颜色。必须是 [stroke](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-stroke) 对象。

**资源尺寸**

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

| 对象 | @1.0x | @1.5x | @2.0x | @3.0x | @4.0x |
| :- | :- | :- | :- | :- | :- |
| background | 75x75 | 112x112 | 150x150 | 225x225 | 300x300 |

## 备注

方向键用于提供类似于物理手柄上方向键的体验。

如果这是玩家的主要移动机制（通常在 `left` `inner` 位置），建议将 scale 设为 2。

**样式备注**

如果对 `background` 使用自定义图像资源，则所引用的最大分辨率适用于 scale=1.0。如果使用不同的 scale，则最大分辨率将等于分辨率与 scale 的乘积。例如，scale=1.5 意味着 @1.0x DPI 的背景图像的最大分辨率可以为 90x90。

> [!WARNING]
>
> 通过 Windows 版本的内容测试应用程序进行串流时，并非所有样式都会正确显示。

## 示例

#### 示例 1：默认方向键

**图 1. 方向键**

![用户与方向键交互](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-directional-pad.gif?s=663feec658af51030d5c73cca7b8fc6e)

```
{
    "type": "directionalPad",
    "scale": 1.0
}
```

#### 示例 2：具有自定义颜色的较大方向键。

**图 1. 自定义方向键**

![用户与自定义方向键交互](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-directional-pad-2.gif?s=1ccee19714099eab37c0d825a9621856)

```
{
    "type": "directionalPad" ,
    "scale": 2.0,
    "styles" : {
        "default" : {
            "fill" : "#0e7a0d10",
            "gradient" : {
                "color": "#0e7a0d10"
            },
            "stroke" : {
                "type": "solid",
                "color" : "#0e7a0dff"
            }
        }
    }
}
```

## 要求

**布局版本：** 1.0+（样式支持自 3.0+，Interaction 支持自 3.4+）。


## Related topics

- [XGameStreamingGamepadPhysicality](https://devdocs.xbox.com/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality.md)
- [Touch Adaptation Kit](https://devdocs.xbox.com/reference/system/touchadaptationkit/touchadaptationkit-reference.md)
- [Touch Adaptation Kit (TAK) Reference](https://devdocs.xbox.com/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-kit-overview.md)
- [XINPUT_KEYSTROKE](https://devdocs.xbox.com/reference/input/xinputongameinput/structs/xinput_keystroke.md)
- [GameInputGamepadButtons](https://devdocs.xbox.com/reference/input/gameinput/enums/gameinputgamepadbuttons.md)