设置面板

添加运行时设置面板，让用户调整麦克风、转录模式和通知偏好，或者以编程方式访问相同设置。

设置面板是一个可选的场景级 UI，允许用户在运行时调整关键的对话偏好设置。要读取当前设置、应用补丁，或从代码中订阅变更，请参见 运行时设置 API.

可控设置

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

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

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

1

将预制体添加到你的 Canvas 中

拖拽 SettingsPanel_Landscape.prefab 到你的场景中。可在以下位置找到它： Prefabs/SettingsPanel/SettingsPanel_Landscape.prefab 在 com.convai.convai-sdk-for-unity 包中。该预制体包含其自己的 Canvas ——不要将它嵌套到现有的 Canvas 中。

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

发布前需要截图： 捕获 Unity 场景层级，其中 SettingsPanel_Landscape GameObject 位于场景根节点可见（不要嵌套在另一个 Canvas 中）。

2

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

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

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();
        });
    }
}

3

运行你的场景

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

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

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:

ConvaiManager.ActiveManager.TryGetSettingsPanelController(out var controller);

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

使用示例

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

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

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

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

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

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

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 组件。要控制面板管理的转录显示，请参见聊天和字幕模式。

自定义 UI 组件运行时设置 API聊天与字幕模式