> ## 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. # Joystick > Joystick # Joystick 行为类似操纵杆的模拟控件。 ## 属性 `type` - "joystick" `axis` - *object* 或 *array*。描述此操纵杆控件映射关系的单个[轴](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-axis)或[轴](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-axis)数组。 `action` - *object*，*可选*。除轴映射外要调用的[操作](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-action)。 `actionThreshold` - *number*，*可选*。调用操作所需的最小归一化操纵杆值（径向）。默认值为 0。 `enabled` - *boolean*，*可选*。默认为 `true`。将控件的可视状态设置为启用/禁用。禁用的控件仍会接收玩家的输入，但不会根据输入更改其可视样式。 `expand` - *boolean*，*可选*。默认值为 `true`。当放置在中央控件位置时，扩展操纵杆的范围以匹配用户的人体工程学偏好。设置为 false 可使用标准化的固定操纵杆大小。 `relative` - *boolean*，*可选*。 默认情况下 (`true`)，操纵杆将根据用户的初始触摸位置进行相对计算得出其值。将此值设置为 `false` 则会根据控件的中心点计算其值。 `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*，*可选*。控件视觉表示的自定义。样式表示为每个可样式化状态对应的一个对象。 按钮控件可以为以下状态设置样式： * `default` - 基本样式。 * `disabled` - 控件被禁用时的样式。如果未指定，控件被禁用时将对默认样式应用一个变换以使其显得已禁用。 * `idle` - 玩家未与控件交互时应用。 * `moving` - 无论定义的死区如何，操纵杆旋钮正在被交互时应用。 * `activated` - 定义了 `action` 且旋钮被移动到超出执行该操作的阈值时应用。 **每个状态的样式属性** `opacity` - *number*，*可选*。应用于控件的不透明度。除 `disabled` 外的所有状态默认为 1.0。 `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)。 [`knob`](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-knob) - *object*，*可选*。[knob](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-knob) 对象指定了操纵杆上供玩家交互的类似按钮部分的样式。 [`outline`](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-joystick-outline) - *object*，*可选*。[outline](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-joystick-outline) 对象指定了在操纵杆被交互时呈现的轮廓和指示器的样式。 **资源尺寸** 对于接受图像资源的每个样式对象，给定的资源以基础分辨率提供，并以该基础分辨率的 1.5x、2.0x、3.0x 和 4.0x 缩放提供。给定图像的分辨率必须小于或等于以下最大分辨率： | 对象 | @1.0x | @1.5x | @2.0x | @3.0x | @4.0x | | :- | :- | :- | :- | :- | :- | | background | 120x120 | 90x90 | 240x240 | 360x360 | 480x480 | | knob.faceImage | 60x60 | 90x90 | 120x120 | 180x180 | 240x240 | | knob.background | 60x60 | 90x90 | 120x120 | 180x180 | 240x240 | ## 备注 `joystick` 控件可用于提供映射到各种物理手柄操纵杆的模拟控制。 如果 `joystick` 是移动的主要方式，建议将其放置在左中央位置并将 `expand` 设置为 true，以为玩家提供最佳体验。 考虑自定义 `faceImage` 以提示玩家操纵杆将控制什么（如果你的游戏使用多个操纵杆，这一点尤其重要）。 对于仅依赖 1 个轴的动作，使用单轴操纵杆以最大化可玩性。 **样式备注** 如果使用 `background` 资源且 `expand` 为 true，`background` 资源不会缩放到完整的中央位置尺寸。 默认情况下，`outline` 仅在玩家与控件交互时显示。 如果使用自定义 `background` 资源且 `expand` 设置为 `true`，请注意该资源不会随玩家的控件自定义扩展。 > [!WARNING] > > 通过 Windows 版本的内容测试应用程序进行串流时，并非所有样式都会正确显示。 ## 示例 #### 示例 1：简单操纵杆 一个具有轻微死区的、与操纵杆 1:1 映射的基本示例。物理手柄上的拇指杆通过旋转计算其值。 **图 1. 操纵杆控件** ![用户与操纵杆交互](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/game-streaming-touch-control-images-joystick.gif?s=913fb802bb674e41afbc275dd588b88f) ```JSON theme={null} { "type": "joystick", "axis": { "input": "axisXY", "output": "leftJoystick", "deadzone": { "threshold": 0.05, "radial": true } } } ``` #### 示例 2：通过阈值时从走路切换到冲刺的操纵杆。 当超过阈值 (0.75) 时，会随操纵杆移动一起发送 leftTrigger。图标将从 'walk' 变为 'sprint'。 **图 1. 具有操作阈值的操纵杆控件** ![用户与具有操作阈值的操纵杆交互](https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/game-streaming-touch-control-images-joystick-with-threshold-action.gif?s=458d5bfd3de78ce9d89f06911b8bccc8) ```JSON theme={null} { "type": "joystick", "action": "leftTrigger", "actionThreshold":0.75, "axis": { "input": "axisXY", "output": "leftJoystick", "deadzone": { "threshold": 0.05, "radial": true } }, "styles": { "default": { "knob": { "faceImage": { "type": "icon", "value": "walk" } } }, "activated": { "knob": { "faceImage": { "type": "icon", "value": "sprint" }, "background" : { "type": "color", "value": "#0e7a0d" } } } } } ``` #### 示例 3：外观类似方向盘的单轴（水平）操纵杆 **图 1. 水平方向盘操纵杆控件** ![用户与水平方向盘操纵杆交互](https://mintcdn.com/microsoft-4404708b/VX3CRv5ayGEZiR8G/images/gdk/reference/game-streaming-touch-control-images-joystick-driving.gif?s=e3871f2e477b6ff164bdf1dc2f597819) ```JSON theme={null} { "type": "joystick", "axis": { "input": "axisX", "output": "leftJoystickX", "deadzone": { "threshold": 0.35 } }, "relative": false, "styles": { "default": { "knob": { "faceImage": { "type": "icon", "value": "steering" } } } } } ``` #### 示例 4：具有自定义颜色的操纵杆 **图 1. 自定义操纵杆控件** ![用户与具有自定义颜色的操纵杆交互](https://mintcdn.com/microsoft-4404708b/VX3CRv5ayGEZiR8G/images/gdk/reference/game-streaming-touch-control-images-joystick-customized-colors.gif?s=b1675a6c7b27845e589c3d0d08452fac) ```JSON theme={null} { "type": "joystick", "axis": { "input": "axisXY", "output": "leftJoystick", "deadzone": { "threshold": 0.05, "radial": true } }, "styles": { "default": { "outline" : { "stroke" : { "type": "solid", "color": "#107C10" } } } } } ``` ## 要求 **布局版本：** 1.0+（样式功能自布局版本 3.0+ 起） ## 另请参阅 [Touch Adaptation Kit 参考](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-kit-overview.md) ## Related topics - [A designer's guide to building touch controls](https://devdocs.xbox.com/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md) - [Guia do designer para criar controles por toque](https://devdocs.xbox.com/pt-BR/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md) - [XINPUT_KEYSTROKE](https://devdocs.xbox.com/fr-CA/reference/input/xinputongameinput/structs/xinput_keystroke.md) - [Guía del diseñador para crear controles táctiles](https://devdocs.xbox.com/es/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md) - [Guide du concepteur pour la création de commandes tactiles](https://devdocs.xbox.com/fr/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md)