> ## 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. # Button > Button # Button 一种可以响应玩家触摸输入的基本控件。可以为其背景和图案图像设置自定义样式。 ## 属性 `type` - *"button"*。指定控件类型。 `action` - *string*。玩家触摸按钮时要调用的[操作](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-action)。 `enabled` - *boolean*，*可选*。默认为 `true`。将控件的可视状态设置为启用/禁用。禁用的控件仍会接收玩家的输入，但*不会*根据输入更改其可视样式。 `pullAction` - *string* 或 *object*，*可选*。当玩家在触摸期间拉动按钮时要调用的[操作](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-action)。当将拉动操作定义为对象时（如下面的示例所示），拉动按钮会被分段，使得拉动操作 `items` 数组中的每一项都为该段分配一个操作。段在按钮周围均匀分布，最多允许 4 段。 * 分段拉动操作属性（v4.1 中引入） * `type` - *"segmented"*。指定拉动操作的类型为分段拉动操作。 * `items` - *array*。最多包含 4 个[操作](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-action)的数组，每个操作在玩家将触摸拖到或拉到该段方向的控件边缘时被调用。 `toggle` - *boolean*，*可选*。默认为 `false`。 * 若为 `false`，按下按钮时发送输入，不按时不发送。 * 若为 `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*，*可选*。控件视觉表示的自定义。样式表示为每个可样式化状态对应的一个对象。 按钮控件可以为以下状态设置样式。 * `default` - 基本样式。 * `disabled` - 控件被禁用时的样式。如果未指定，控件被禁用时将对默认样式应用一个变换以使其显得已禁用。 * `idle` - 玩家*未*与控件交互时应用。 * `activated` - 玩家触摸按钮时应用。 * `pulled` - 玩家触摸并拉动按钮时应用。对于分段拉动操作，只有正在被拉动的单个段以此状态设置样式；其他段保留 `activated` 样式。 * `toggled` - 按钮处于切换状态且玩家未触摸按钮时应用。 **每个状态的样式属性** `opacity` - *number*，*可选*。应用于控件的不透明度。除 `disabled` 外的所有状态默认为 1.0。 `faceImage` - *object*，*可选*。可以是[图标](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-icon)或[图像资源](https://devdocs.xbox.com/zh-CN/reference/system/touchadaptationkit/types/game-streaming-touch-asset)。 `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)。在 idle 和 disabled 状态下不可见。 **资源尺寸** 对于接受图像资源的每个样式对象，给定的资源以基础分辨率提供，并以该基础分辨率的 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 | 60x60 | 90x90 | 120x120 | 180x180 | 240x240 | ## 备注 按钮通常用于让玩家执行原本通过物理手柄上一个或多个物理按钮完成的操作。 利用多个操作使玩家能够轻松地复刻组合操作（例如同时按下左肩键和右肩键）。 **样式备注** 处于 `activated` 状态时，`faceImage` 显示为小 25%。 对于不使用自定义资源、并且仅有单一操作 `gamepadX`、`gamepadY`、`gamepadA` 或 `gamepadB` 的按钮，其背景色具有标签和默认样式。 ## 示例 #### 示例 1：映射到 A 按钮的跳跃按钮 ![用户按下按钮](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-button.gif?s=585c8746250b36534c236117851e82f4) ```JSON theme={null} { "type": "button", "action": "gamepadA", "styles": { "default": { "faceImage": { "type": "icon", "value": "jump" } } } } ``` #### 示例 2：映射为同时按下左肩键和右肩键的蹲下按钮 ![用户按下映射到两个操作的按钮](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-button-2.gif?s=0c9485ee05b533ae100e8edaee6882b6) ```JSON theme={null} { "type": "button", "action": [ "leftBumper", "rightBumper"] , "styles": { "default": { "faceImage": { "type": "icon", "value": "crouch" } } } } ``` #### 示例 3：具有自定义图案图像和背景图像的按钮 ![用户按下带有自定义资源的按钮](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-button-3.gif?s=4503a193449c834d72a50e19a111e9d2) ```JSON theme={null} { "type": "button", "action": "gamepadA", "enabled" : true, "styles": { "default": { "background": { "type": "asset", "value": "hex_background" }, "faceImage": { "type": "asset", "value": "one" } }, "activated": { "background": { "type": "asset", "value": "hex_background_glow" } } } } ``` #### 示例 4：具有每段自定义样式的分段拉动操作 > [!NOTE] > > 为分段拉动按钮设置样式时，`pullIndicator` 数组的长度必须与定义各段的 `items` 属性长度相同。换句话说，每个段必须有一个样式定义，或者必须使用 `null` 来省略特定段的样式覆盖。 ![用户按下带有分段拉动操作的按钮。](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-button-segmented-pull.gif?s=d28b3799cc728ed15d8af352b009bb46) ```JSON theme={null} { "type": "button", "action": "gamepadA", "pullAction": { "type": "segmented", "items": [ "gamepadB", "gamepadY" ] }, "styles": { "default": { "pullIndicator": [ { "faceImage": { "type": "icon", "value": "sword" } }, { "faceImage": { "type": "icon", "value": "block" } } ] }, "idle": { "pullIndicator": [ null, { "opacity": 0.5 } ] } } } ``` ## 要求 **最低布局版本：** 1.0+（样式支持自 2.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 - [GAMEPAD_BUTTONS Enumeration](https://devdocs.xbox.com/reference/tools/xtf/xtfinput/enumerations/GAMEPAD_BUTTONS-typedef-xtfinput-xbox-windows-t.md) - [GAMEPAD_MORE_BUTTONS](https://devdocs.xbox.com/reference/tools/xtf/xtfinput/enumerations/gamepad_more_buttons.md) - [Enumeración GAMEPAD_BUTTONS](https://devdocs.xbox.com/es/reference/tools/xtf/xtfinput/enumerations/GAMEPAD_BUTTONS-typedef-xtfinput-xbox-windows-t.md) - [Énumération GAMEPAD_BUTTONS](https://devdocs.xbox.com/fr-CA/reference/tools/xtf/xtfinput/enumerations/GAMEPAD_BUTTONS-typedef-xtfinput-xbox-windows-t.md)