> 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/features/conversation-availability/gate-your-ui.md).

# 根据可用性控制 UI

根据对话可用性控制自定义聊天输入框或麦克风按钮，使玩家输入要等到角色能听到时才生效。

将你自己的聊天字段、麦克风按钮或发送操作绑定到 `ConvaiManager.ConversationAvailability` ，这样它只会在被提及的角色确实能听到输入后才接受输入。当你正在构建自定义输入 UI 而不是使用随附的聊天字段时，请使用此页面，因为后者已经会自行进行门控——参见 [自定义聊天字段提示](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability/customise-chat-prompts.md) 如果这正是你要配置的内容。

### 前置条件

* 一个场景中有 `ConvaiManager` 以及至少一个处于活动状态的 `ConvaiCharacter`。请参阅 [场景组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/scene-components.md).
* 熟悉对话可用性状态。参见 [对话可用性的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability/how-availability-works.md).

### 读取当前判定结果

`ConvaiManager.ConversationAvailability` 返回当前的 `ConvaiConversationAvailability` 用于 `ConvaiManager.AddressedCharacter`。调用 `CanAcceptPlayerInput()` 对结果进行处理，以获得 UI 需要的单个布尔值：

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

public class SendButtonGate : MonoBehaviour
{
    [SerializeField] private ConvaiManager _manager;
    [SerializeField] private Button _sendButton;

    private void Update()
    {
        _sendButton.interactable = _manager.ConversationAvailability.CanAcceptPlayerInput();
    }
}
```

### 响应变化事件，而不是轮询

`ConvaiManager.ConversationAvailabilityChanged` 每当判定结果发生变化时都会触发，包括当玩家开始指向另一个可用性不同的角色时。订阅它以便在变化发生的瞬间更新 UI，而不是等到下一帧：

```csharp
private void OnEnable() => _manager.ConversationAvailabilityChanged += HandleAvailabilityChanged;
private void OnDisable() => _manager.ConversationAvailabilityChanged -= HandleAvailabilityChanged;

private void HandleAvailabilityChanged(ConvaiConversationAvailability availability)
{
    _sendButton.interactable = availability.CanAcceptPlayerInput();
}
```

### 针对特定角色而不是被指向的角色进行门控

与某个特定角色绑定的 UI 元素——例如姓名牌、多角色场景中的单独角色指示器——应该读取 `ConvaiCharacter.ConversationAvailability` ，并直接读取该角色，而不是 `ConvaiManager.ConversationAvailability`，后者始终针对当前被指向的对象进行回答：

```csharp
[SerializeField] private ConvaiCharacter _character;
[SerializeField] private Image _indicator;

private void Update()
{
    _indicator.color = _character.CanAcceptPlayerInput ? Color.green : Color.gray;
}
```

{% hint style="warning" %}
`ConvaiCharacter.ConversationAvailability` 并不等同于 `ConvaiCharacter.IsCharacterReady`. `IsCharacterReady` 该值会在角色就绪信号从 Convai 发出时被设置一次，之后即使角色不再占据房间中的席位也不会清除。请将 `ConversationAvailability` 用于任何会对玩家输入进行门控的地方。
{% endhint %}

### 验证门控

进入播放模式，连接后，在角色尚未被确认之前尝试输入或按发送。门控应当阻止该操作，直到可用性报告 `Ready` 或 `Answering`。在对话过程中断开该角色，并确认门控再次关闭。

### 下一步

{% content-ref url="/pages/d6e6831a3a8119af9517d8ac6de60d6c38cb05f1" %}
[响应玩家开始说话](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability/local-player-activity.md)
{% endcontent-ref %}

{% content-ref url="/pages/529a05fa8aa08e60134072820b4eee04f3269f6f" %}
[对话可用性参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/conversation-availability/availability-reference.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/features/conversation-availability/gate-your-ui.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.