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

# 根据游戏状态更改触控布局

> 根据游戏状态更改触控布局

游戏能够更改向玩家显示的触控布局，或修改当前显示布局所使用的状态。两种方法可以一起使用，为玩家创建最自然的体验。

**[更改布局](#change_layout)**

在以下情况下应更改布局：

* 在不同控制方案之间转换（例如驾驶车辆和第一人称射击）
* 暂时隐藏触控布局（进行完整的触控体验、启用电影体验等）

**[更改状态](#change_state)**

在以下情况下应更改包含在触控适配包上下文部分中的游戏状态：

* 根据玩家的当前游戏状态修改控件的图像/图标。一些示例包括：
  * 根据玩家选择的武器更改射击按钮上的图像。
  * 根据玩家库存中当前拥有的物品更改能力的图像。
* 根据玩家的当前游戏状态修改控件的视觉状态（可见性和是否启用）。一些示例包括：
  * 当玩家没有额外弹药时禁用装弹按钮。
  * 当玩家接近可以互动的物品时使互动按钮可见（并在他们离开时不可见）。

<a id="change_layout" />

## 在运行时更改布局

**显示指定的布局**
游戏应使用 [`XGameStreamingShowTouchControlLayout`](/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout) API 显示新布局。

**隐藏当前布局**
游戏应使用 [`XGameStreamingHideTouchControls`](/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrols) API 隐藏当前显示的布局。

游戏如何根据当前游戏状态设置布局的示例：

```C++ theme={null}
void OnGameStateChanged(GameState newState)
{
    // Toggle to the set of touch overlay controls which best match the new state of the game
    switch (newState)
    {
    case GameState::FirstPersonAction:
        XGameStreamingShowTouchControlLayout("FirstPersonAction");
        break;
    case GameState::Driving:
        XGameStreamingShowTouchControlLayout("Driving");
        break;
    case GameState::CutScene:
        // Don't show any touch overlay controls while the cut scene is rendering
        XGameStreamingHideTouchControls();
        break;
    }
}
```

<a id="change_state" />

## 在运行时更改状态

游戏启动时的初始状态由触控适配包中包含的[默认状态](/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-bundle#context)定义。在触控布局中，控件应引用可能在运行时更改的属性的状态。

游戏可以利用 `XGameStreamingUpdateTouchControlsState` API 在运行时更新状态。

例如，以下将用于让一个"装弹"控件初始禁用，但在玩家应具有该功能时启用。

```JSON theme={null}
//Example context file
{
  "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/main/touch-adaptation-kit/schemas/context/v3.0/context.json",

  "state": {
    "enableReload": false
  }
}

//Example control in the layout:
{
    "type": "button",
    "action": "leftBumper",
    "enabled": {
        "$ref": "../../context.json#/state/enableReload"
    }
    ...
}
```

游戏将进行 API 调用以更新状态：

```C++ theme={null}

// In this example, after the player has switched their active weapon - the game updates the
// enabled state of reload based on whether the player has extra magazines.
//
// Assumes passing in game structure that includes the active weapon with appropriate state.
//

void GameStreamingClientManager::UpdateStateAfterItemsChange(const playerWeapon& playerWeapon)
{
    // create an update for whether the reload button should be enabled
    XGameStreamingTouchControlsStateOperation reloadEnabled;
    reloadEnabled.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    reloadEnabled.path = "/enableReload";
    reloadEnabled.valueKind = XGameStreamingTouchControlsStateValueKind::Bool;
    reloadEnabled.booleanValue = playerWeapon.activeWeapon.reloadClips > 0;

    // combine all the updates into the update state call and make the call
    XGameStreamingTouchControlsStateOperation[1] updateOperations = {reloadEnabled};

    XGameStreamingUpdateTouchControlsState(updateOperations, _countof(updateOperations));
}
```


## Related topics

- [构建触控的设计师指南](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-designers-guide.md)
- [为 XBOX 游戏串流构建触控布局](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/index.md)
- [构建触控布局](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-building-touch-layout.md)
- [发布触控布局](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-publishing-layouts.md)
- [部署触控布局](/zh-CN/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-deploying-touch-layout.md)