> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel.md).

# 设置面板

设置面板是一个可选的场景级 UI，允许用户在运行时调整关键的对话偏好设置。要读取当前设置、应用补丁，或从代码中订阅变更，请参见 [运行时设置 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel/runtime-settings-api.md).

### 可控设置

| 将          | 描述                            |
| ---------- | ----------------------------- |
| **玩家显示名称** | 在转录气泡中显示给玩家的名称                |
| **转录**     | 完全启用或禁用转录 UI                  |
| **通知**     | 启用或禁用场景内通知弹窗                  |
| **麦克风**    | 从可用选项中选择活动输入设备                |
| **对话模式**   | 在免提和按住说话之间切换（仅在房间连接处于活动状态时显示） |

更改会在用户点击时生效 **保存**。面板会在保存后自动关闭。点击 **关闭** 会放弃未保存的更改。

### 将设置面板添加到你的场景中

{% stepper %}
{% step %}

#### 将预制体添加到你的 Canvas 中

拖拽 `SettingsPanel_Landscape.prefab` 到你的场景中。可在以下位置找到它： `Prefabs/SettingsPanel/SettingsPanel_Landscape.prefab` 在 <code class="expression">space.vars.sdk\_package\_id</code> 包中。该预制体包含其自己的 `Canvas` ——不要将它嵌套到现有的 Canvas 中。

`SettingsPanel` 会自动从 `ConvaiManager` 于 `OnEnable`中解析出所有必需的服务。基础设置不需要额外的 Inspector 连线。

{% hint style="warning" %}
**发布前需要截图：** 捕获 Unity 场景层级，其中 `SettingsPanel_Landscape` GameObject 位于场景根节点可见（不要嵌套在另一个 Canvas 中）。
{% endhint %}
{% endstep %}

{% step %}

#### 连接一个触发器以打开面板

面板初始为隐藏状态。请绑定一个按钮、键盘快捷键或暂停菜单来打开它：

```csharp
using Convai.Runtime.Components;
using UnityEngine;
using UnityEngine.UI;

public class SettingsButton : MonoBehaviour
{
    private void Start()
    {
        GetComponent<Button>().onClick.AddListener(() =>
        {
            if (ConvaiManager.ActiveManager.TryGetSettingsPanelController(out var c))
                c.Open();
        });
    }
}
```

{% endstep %}

{% step %}

#### 运行你的场景

点击触发器。面板会淡入（默认 0.5 秒）。调整设置并点击 **保存** ——面板会淡出，且更改会立即生效。麦克风下拉框会从可用的系统设备中填充；对话模式下拉框仅在房间连接处于活动状态时显示。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
当面板正确打开时，麦克风下拉框会被填充，玩家名称字段会显示当前显示名称，且转录和通知开关会反映它们当前的状态。
{% endhint %}

### `SettingsPanel` Inspector 引用

| 字段                          | 描述                                   |
| --------------------------- | ------------------------------------ |
| `fadeDuration`              | 淡入/淡出动画的秒数（默认 `0.5`)                 |
| `transcriptStyleDropdown`   | `TMP_Dropdown` 用于转录显示模式              |
| `voiceInputDropdown`        | `TMP_Dropdown` 列出可用麦克风设备             |
| `conversationModeDropdown`  | `TMP_Dropdown` 用于免提 / 按住说话           |
| `playerNameInputField`      | `TMP_InputField` 用于玩家的显示名称           |
| `transcriptToggle`          | `开关` 启用或禁用转录 UI                      |
| `notificationToggle`        | `开关` 启用或禁用通知                         |
| `saveButton`                | `按钮` 应用所有更改并关闭面板                     |
| `closeButton`               | `按钮` 不保存地关闭                          |
| `microphoneDropContainer`   | `GameObject` 包裹麦克风下拉框——当未找到设备时隐藏     |
| `transcriptModeContainer`   | `GameObject` 包裹转录样式下拉框               |
| `conversationModeContainer` | `GameObject` 包裹对话模式下拉框——当没有房间服务可用时隐藏 |

### `IConvaiSettingsPanelController` ——可见性 API

通过以下方式访问面板控制器 `ConvaiManager`:

```csharp
ConvaiManager.ActiveManager.TryGetSettingsPanelController(out var controller);
```

| 成员                                     | 描述                                 |
| -------------------------------------- | ---------------------------------- |
| `bool IsOpen`                          | `true` 当面板当前可见时                    |
| `void Open()`                          | 使用淡入动画显示面板                         |
| `void Close()`                         | 使用淡出动画隐藏面板                         |
| `void Toggle()`                        | 关闭时打开，打开时关闭                        |
| `event Action<bool> VisibilityChanged` | 在可见性变化时触发。 `bool` 参数是新的 `IsOpen` 值 |

### 使用示例

#### 安全培训——暂停菜单集成

一个安全培训模拟通过暂停菜单暴露设置面板，并在面板关闭时重新显示菜单：

```csharp
using Convai.Runtime.Components;
using Convai.Shared.Abstractions;
using UnityEngine;

public class PauseMenu : MonoBehaviour
{
    [SerializeField] private GameObject _pauseMenuRoot;
    private IConvaiSettingsPanelController _settingsController;

    private void Start()
    {
        ConvaiManager.ActiveManager.TryGetSettingsPanelController(out _settingsController);
    }

    private void OnEnable()
    {
        if (_settingsController != null)
            _settingsController.VisibilityChanged += OnPanelVisibilityChanged;
    }

    private void OnDisable()
    {
        if (_settingsController != null)
            _settingsController.VisibilityChanged -= OnPanelVisibilityChanged;
    }

    public void OpenSettings()
    {
        _pauseMenuRoot.SetActive(false);
        _settingsController?.Open();
    }

    private void OnPanelVisibilityChanged(bool isOpen)
    {
        if (!isOpen)
            _pauseMenuRoot.SetActive(true);
    }
}
```

在运行时，打开设置会隐藏暂停菜单。培训者保存并且面板关闭后，暂停菜单会自动重新出现。

#### 企业入职——根据身份验证预填设置

企业入职体验会从经过身份验证的用户资料中预填玩家名称，并在第一场会话之前启用转录：

```csharp
public void ApplyAuthenticatedProfile(string userName, bool showTranscripts)
{
    if (ConvaiManager.ActiveManager.TryGetRuntimeSettingsService(out var settings))
    {
        settings.Apply(new ConvaiRuntimeSettingsPatch
        {
            PlayerDisplayName = userName,
            TranscriptEnabled = showTranscripts
        });
    }
}
```

在运行时，培训者的真实姓名会立即显示在转录气泡中，转录显示也会预先配置为符合组织偏好。

### 故障排查

| 症状        | 可能原因                             | 修复方法                                                                                 |
| --------- | -------------------------------- | ------------------------------------------------------------------------------------ |
| 面板未淡入     | `CanvasGroup` 或 `CanvasFader` 缺少 | `SettingsPanel.Awake()` 调用 `EnsureFadeComponents()` 它会自动添加这些组件——请确认预制体完整且 Awake 正在运行 |
| 麦克风下拉框为空  | 未检测到麦克风设备或权限被拒绝                  | 确认设备已连接；在移动平台上检查 Player Settings 中的麦克风权限                                             |
| 对话模式下拉框隐藏 | 没有活动的房间连接                        | 预期结果——下拉框仅在 `IConvaiRoomConnectionService` 可用时显示                                     |
| 保存后设置未持久化 | 保存时设置服务不可用                       | 确保 `ConvaiManager` 在面板打开之前已初始化；检查 `ConvaiManager.IsBootstrapped`                     |

### 下一步

有了设置面板，你的用户可以在运行时调整他们的会话偏好。要自定义面板本身的视觉样式，请参见自定义 UI 组件。要控制面板管理的转录显示，请参见聊天和字幕模式。

{% content-ref url="/pages/5f60eaa8d444f5ee8a995392852da827736d3b54" %}
[自定义 UI 组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/customizing-ui-components.md)
{% endcontent-ref %}

{% content-ref url="/pages/583ee1c9e51b46cec2adb2388e0ffd644e8ef169" %}
[运行时设置 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel/runtime-settings-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/6695eb978b08dbf5023b367d38af0912574c4f52" %}
[聊天与字幕模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.