# 聊天历史记录查询选项

> Query chat history with various filtering options.

ChatHistoryQueryOptions 是一个可选的选项模型，可以包含在 [`VivoxService.Instance.GetDirectTextMessageHistoryAsync`](https://docs.unity3d.com/Packages/com.unity.services.vivox@latest/index.html?subfolder=/api/Unity.Services.Vivox.IVivoxService.html#Unity_Services_Vivox_IVivoxService_GetDirectTextMessageHistoryAsync_System_String_System_Int32_Unity_Services_Vivox_ChatHistoryQueryOptions_) 或 [`VivoxService.Instance.GetChannelTextMessageHistoryAsync`](https://docs.unity3d.com/Packages/com.unity.services.vivox@latest/index.html?subfolder=/api/Unity.Services.Vivox.IVivoxService.html#Unity_Services_Vivox_IVivoxService_GetChannelTextMessageHistoryAsync_System_String_System_Int32_Unity_Services_Vivox_ChatHistoryQueryOptions_) 调用中以指定应返回的消息。

## SearchText##searchtext

`ChatHistoryQueryOptions` 的 SearchText 字段可用于指定聊天历史记录查询返回的每条消息中应包含的文本字符串。例如，以下代码将确保返回的 historyMessages 仅包含那些具有“Hello, lobby!”文本的消息。

```cs
var options = new ChatHistoryQueryOptions();
options.SearchText = "Hello, lobby!";
var historyMessages =
    await VivoxService.Instance.GetChannelTextMessageHistoryAsync(LobbyChannelName, 10, options);
```

## TimeStart - TimeEnd##timestart---timeend

`ChatHistoryQueryOptions` 的 TimeStart 和 TimeEnd 字段都是 `DateTimes`，分别描述应发送消息的开始和结束时间。例如，以下代码将返回发出请求前 24 小时和发出请求前 12 小时之间的最后 10 条消息。

```cs
var options = new ChatHistoryQueryOptions();
options.TimeStart = DateTime.Now().AddDays(-1);
options.TimeEnd = DateTime.Now().AddDays(-0.5);
var historyMessages =
    await VivoxService.Instance.GetChannelTextMessageHistoryAsync(LobbyChannelName, 10, options);
```

请注意，除非启用文本证据管理功能，否则聊天历史记录仅存储七天。

## PlayerId##playerid

对于 `ChannelTextMessageHistory` 请求，ChatHistoryQueryOptions 的 PlayerId 字段描述了将成为所有返回消息的发送方的 PlayerId。例如，以下代码将返回指定频道中特定参与者发送的最后 10 条消息。

```cs
IReadOnlyCollection<VivoxMessage> GetMessagesFromPlayerAsync(VivoxParticipant participant)
{
    var options = new ChatHistoryQueryOptions();
    options.PlayerId = participant.PlayerId;
    var historyMessages =
        await VivoxService.Instance.GetChannelTextMessageHistoryAsync(LobbyChannelName, 10, options);
    return historyMessages;
}
```

## 被屏蔽参与者的基于频道的聊天历史记录##channel-based-chat-history-for-blocked-participants

在设置 `history_session` 查询响应的格式时，您可以过滤出被屏蔽用户的消息。

从频道获取聊天历史记录时，SDK 会略过被屏蔽用户的消息。如果用户 A 在应用程序中屏蔽了用户 B，则用户 A 看不到用户 B 发送的消息。

### 被屏蔽参与者涉及的历史记录会话##history-sessions-when-blocked-participants-are-involved

如果历史记录请求中的所有消息都来自被屏蔽参与者，该请求可能会返回为空。在这种情况下，响应包含一个游标，指示后续页面上的频道中有更多消息。每个历史记录请求返回的默认消息数为每页 10 条。使用后续请求中的游标值可获取下一页消息。

如果频道中有被屏蔽用户，则最大页面大小参数 (Max) 显示的消息数少于请求的消息数。为聊天历史记录请求特定的页面大小时，请注意，如果频道中有被屏蔽用户，`history_session` 显示的消息数可能少于选择的消息数。此功能对于确保隐私和防止不必要的交互至关重要。

“上次读取”显示未读消息的计数。Vivox 会跟踪您的已读消息并提供未读消息的计数。但是，请注意，此计数包括被屏蔽消息，这些消息是故意从您的响应中过滤出去的。如果频道中有被屏蔽用户，则未读消息的计数可能不准确。

### 被屏蔽参与者的帐户聊天历史记录##account-chat-history-for-blocked-participants

针对帐户提交聊天历史记录请求时，查询仅显示用户发送的消息。