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

### 可控设置

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

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

该 **玩家显示名称** 该字段初始化自项目范围内的 `ConvaiSettings.DefaultPlayerDisplayName` 设置，配置于 **运行时默认值** 部分，位于 **Convai → 设置**。一旦玩家保存了自己的值，已保存的覆盖值在以后再次打开时将优先生效。

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

{% 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 连接。
{% 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`)                                                                            |
| `voiceInputDropdown`        | `TMP_Dropdown` 列出可用麦克风设备                                                                        |
| `conversationModeDropdown`  | `TMP_Dropdown` 用于免提 / 按住说话                                                                      |
| `playerNameInputField`      | `TMP_InputField` 用于玩家的显示名称                                                                      |
| `transcriptToggle`          | `开关` 用于启用或禁用转录显示                                                                                |
| `notificationToggle`        | `开关` 用于启用或禁用通知                                                                                  |
| `saveButton`                | `按钮` 应用所有更改并关闭面板                                                                                |
| `closeButton`               | `按钮` 不保存直接关闭                                                                                    |
| `microphoneDropContainer`   | `GameObject` 包裹麦克风下拉框——在未找到设备时隐藏                                                                |
| `conversationModeContainer` | `GameObject` 包裹对话模式下拉框——在没有房间服务可用时隐藏                                                            |
| `transcriptModeContainer`   | `GameObject` 字段，未使用—— `SettingsPanel` 始终会在其上停用 `Awake` 并且没有其他内容会读取它。如果你在 Inspector 中看到它，可以安全忽略。 |

### `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
        });
    }
}
```

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

### 故障排除

| 症状        | 可能原因                 | 修复方法                                                                                                                                                                 |
| --------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 面板不会淡入    | `CanvasFader` 预制体中缺失 | `SettingsPanel.Awake()` 调用 `EnsureFadeComponents()`，它会添加缺失的 `CanvasGroup` 会自动执行，但只会查找现有的 `CanvasFader` ——它不会添加新的。如果 `CanvasFader` 缺失，面板会退回到即时、无动画的显示/隐藏；请在预制体上恢复该组件。 |
| 麦克风下拉框为空  | 未检测到麦克风设备或权限被拒绝      | 请确认设备已连接；在移动平台上检查 Player Settings 中的麦克风权限                                                                                                                            |
| 对话模式下拉框隐藏 | 没有活动的房间连接            | 符合预期——该下拉框仅在……期间出现 `IConvaiRoomConnectionService` 可用                                                                                                                 |
| 保存后设置未持久化 | 保存时设置服务不可用           | 在依赖项注入之前 `ConvaiManager` 在面板打开前已初始化；检查 `ConvaiManager.IsBootstrapped`                                                                                                |

### 下一步

有了设置面板，你的用户就可以在运行时调整会话偏好。要自定义面板本身的视觉样式，请参见 Customizing UI Components。面板只负责显示或隐藏转录展示——要添加和配置聊天与字幕转录 UI 本身，请参见 Chat and Subtitle Modes。

{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.