> 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](https://docs.convai.com/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` 检查器引用

| 字段                          | 说明                                                                                     |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `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` 中将其停用，且没有其他代码读取它。如果在检查器中看到它，可以放心忽略。 |

### `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 组件](https://docs.convai.com/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](https://docs.convai.com/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" %}
[聊天和字幕模式](https://docs.convai.com/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.
