> 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                  |
| **通知**     | 启用或禁用场景内通知弹窗                  |
| **麦克风**    | 从可用选项中选择当前活动输入设备              |
| **对话模式**   | 在免提和按键通话之间切换（仅在房间连接处于活动状态时显示） |

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

该 **玩家显示名称** 字段从项目级的 `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`          | `Toggle` 用于启用或禁用转录展示                                                                           |
| `notificationToggle`        | `Toggle` 用于启用或禁用通知                                                                             |
| `saveButton`                | `Button` 用于应用所有更改并关闭面板                                                                         |
| `closeButton`               | `Button` 用于不保存直接关闭                                                                             |
| `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`                                                                                                 |

### 下一步

有了设置面板，你的用户就可以在运行时调整会话偏好。若要自定义面板本身的视觉样式，请参见自定义 UI 组件。该面板只显示或隐藏转录展示——若要添加并配置聊天和字幕转录 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.