文字聊天概览

Roblox 提供在实时会话中玩家之间的文本消息通过 TextChatService 。该服务具有其标准功能，但还提供一组方法和事件来扩展和自定义聊天，例如基于 自定义需求 发送消息，添加特殊权限或管理到特定玩家，以及创建 自定义命令 执行特定操作。

以下部分摘要了您可以使用来自定义聊天系统的主要类别和实例。

顶层配置

单例类 TextChatService 负责管理整个聊天系统，包括处理聊天消息过滤、管理和用户权限。使用属性 like CreateDefaultTextChannels 和 CreateDefaultCommands 来启用或禁用默认聊天频道和命令。

默认 UI 配置

TextChatService 提供默认用户界面，可以自定义以满足您的体验需求。每一种配置都可以禁用以隐藏相关的用户界面元素，或可以替换为自定义界面如果需要。

• ChatWindowConfiguration — 代表默认聊天窗口 UI，包括其外观和行为。禁用它以隐藏聊天窗口。
• ChatInputBarConfiguration — 代表默认聊天输入栏 UI，包括其外观和行为。
• BubbleChatConfiguration — 代表默认的 泡泡聊天 UI，包括其外观和行为。

通道、消息和命令

• TextChannel — 代表一个文字聊天通道，将客户端向服务器发送的聊天消息传递到服务器，然后根据权限显示给其他用户。这些实例必须被父辈到 TextChatService 才能运行。

  如果 TextChatService.CreateDefaultTextChannels 设置为 true ,服务自动创建两个文本通道, RBXGeneral 和 RBXSystem .您还可以手动创建额外的 TextChannel 实例并将其作为父级 TextChatService ,以及。

• TextSource — 在 TextChannel 中代表用户。这些实例直接属于 TextChannel 当 AddUserAsync() 被调用时。文本源包含通道中用户的详细权限，例如他们发送消息的能力。单个用户可以与多个文本来源关联，如果它们已添加到多个文本通道。

• TextChatMessage — 代表文本通道中的单个聊天消息，包含基本信息，例如消息发件人、原始消息、过滤消息和创建时间戳。

• TextChatCommand — 允许用户通过发送匹配 PrimaryAlias 或 SecondaryAlias 的消息来触发特定的行动或行为。这些实例必须被父辈到 TextChatService 才能运行。

  如果 TextChatService.CreateDefaultCommands 设置为 true，默认聊天命令将自动创建。您还可以手动创建额外的 TextChatCommand 实例并将其作为父来 TextChatService ,以及。

聊天流程图

文字聊天使用 客户端-服务器 模型，包括 发送客户端 、 服务器 和 接收客户端 。

1. 一名玩家从本地设备发送消息，触发 TextChannel:SendAsync() 方法。该方法处理消息，并确定它是聊天命令还是普通聊天消息。

   • 如果消息是聊天命令，它会触发 TextChatCommand.Triggered 事件执行定义的行动。无需进行进一步操作。

   • 如果消息是常规聊天消息，它会触发 TextChatService.SendingMessage 事件将消息显示给发送客户端的发送者。同时，TextChannel:SendAsync() 将消息传给服务器。

2. 服务器发射 TextChannel.ShouldDeliverCallback 来确定是否根据权限和 Roblox 社区过滤要求向其他玩家发送消息。

3. 如果 TextChannel.ShouldDeliverCallback 确定该消息可以发送给其他玩家，服务器应用任何过滤器并触发 TextChannel.OnIncomingMessage 两次：

   1. 第一次是在发送客户端上，它表示服务器正在通过 TextChatService.MessageReceived 事件处理消息。该事件会将发送客户端上的本地消息替换为服务器处理的消息。如果原始文件没有需要过滤，那么消息也是相同的。

   2. 第二次是在接收客户端，这会触发 TextChatService.MessageReceived 事件将消息显示给其他玩家。

文本聊天钩和回调

TextChatService 鼓励在聊天消息的外观和交付上进行明确分离。文字聊天系统的多个实例提供钩和回调来在中央化、清晰的位置格式化。

| 回调 | 返回值 | | ----------------------------------------- | ----------------------------------- | | | boolean | | | | | | | | | | | | | | |

条件发送消息

TextChannel.ShouldDeliverCallback 应仅在服务器上定义。回调在发送消息时为文本通道的每个 TextSource 子发射，以确定消息是否应该发送。此回调可用于实现可能依赖额外游戏上下文的自定义消息传递逻辑，例如：

• 基于距离的聊天 在这里，用户只能向靠近他们的人发送消息。
• 防止具有某些属性的用户向其他人发送消息。

自定义消息显示

默认 TextChatService 用户界面依赖 富文本 来格式化和自定义消息显示方式。您可以使用以下回调来格式化消息，以便在显示给用户之前格式化消息，例如添加颜色或 聊天标签 到用户名或格式化消息内容。

以下回调在每次显示即将显示的 TextChatMessage 之前被调用，可以根据 TextChannel、TextSource 或 TextChatMessage 内容自定义聊天窗口外观。当客户端发送消息时，这些回调会在消息发送到服务器时调用一次，值 TextChatMessage.Status 将为 Enum.TextChatMessageStatus.Sending 。一旦消息被服务器收到并交付给其他用户，发送客户端再次收到更新的 Enum.TextChatMessageStatus 值，将消息重新发送给其他用户。

• TextChatService.OnIncomingMessage — 此回调应仅在客户端定义。回调在收到消息时发射，从服务器或本地客户端刚刚发送消息时。回调在每次收到所有 TextChatMessage 实例的每一个 TextChannel 请求时被调用，是第一个处理消息的用户显示之前的处理。
• TextChannel.OnIncomingMessage — 此回调应仅在客户端定义。回调在服务器收到消息时发射。回调在每次收到 TextChatMessage 从 TextChannel 时被调用。默认 TextChannel 从 TextChatService.CreateDefaultTextChannels 创建的实例具有此回调定义，可以覆盖。
• TextChatService.OnBubbleAdded — 此回调应仅在客户端定义。使用它来自定义聊天窗口 UI 中的消息显示独立于聊天窗口中的聊天泡泡的外观。
• TextChatService.OnChatWindowAdded — 此回调应仅在客户端定义。使用它来自定义聊天窗口用户独立于聊天泡泡中消息的外观的聊天消息外观。

从传统聊天迁移

本节可帮助您从遗产聊天系统迁移到使用 TextChatService 实现常见聊天功能和行为的替代方法。

1. 在 资源管理器 窗口中，选择 TextChatService .

2. 在 属性 窗口中，找到 ChatVersion 下拉列表并选择 TextChatService 。

   

基本功能

虽然两个系统都共享相同的基本聊天功能，但 TextChatService 实现在整体上更可持续，更容易反复使用。

消息筛选

TextChatService 自动根据每个玩家的帐户信息过滤聊天消息，因此您不需要手动实现所有类型的聊天消息的文本过滤。

窗口和泡泡聊天

both the 聊天窗口 和 泡泡聊天 行为和自定义选项的 TextChatService 与遗产聊天系统相同。由于遗产聊天系统只允许使用聊天模块或 Players 容器进行自定义，服务提供了专用类 ( ChatWindowConfiguration 和 BubbleChatConfiguration )来管理所有聊天窗口和泡泡聊天属性。此外，您可以使用工作室设置轻松调整和预览泡泡聊天的外观和行为属性，而不需要全部编写脚本。

迁移发言者“额外数据”

遗产 Lua 聊天系统允许开发人员在 SetExtraData 类上使用 Speaker。这些数据被用来格式化名称颜色、聊天颜色或为特定发言人应用名称标签。

遗产聊天系统 SetExtraData
-- 遗产聊天系统中设置额外数据的示例
ChatService.SpeakerAdded:Connect(function(playerName)
	local speaker = ChatService:GetSpeaker(playerName)
	speaker:SetExtraData("NameColor", Color3.fromRGB(255, 255, 55))
	speaker:SetExtraData("ChatColor", Color3.fromRGB(212, 175, 55))
	speaker:SetExtraData("Tags", {{TagText = "YourTagName", TagColor = Color3.fromRGB(0, 255, 0)}, {TagText = "OtherTagName", TagColor = Color3.fromRGB(255, 0, 0)}})
end)

TextChatService 没有直接等价于 SetExtraData 的。相反，使用 回调 例如 OnWindowAdded 来自定义基于消息 TextSource 的富文本的消息外观。

以下是使用 Player 对象上的属性访问遗产 Lua 聊天的“额外数据”的示例：

文字聊天服务设置属性
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
	player:SetAttribute("NameColor", Color3.fromRGB(255, 255, 55))
	player:SetAttribute("ChatColor", Color3.fromRGB(212, 175, 55))
	player:SetAttribute("isYourTag", true)
	player:SetAttribute("isOtherTag", true)
end)

然后，您可以使用 OnChatWindowAdded 回调来根据玩家设置的属性自定义聊天窗口的外观：

在聊天窗口添加的 TextChatService
local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

TextChatService.OnChatWindowAdded = function(textChatMessage)
	local textSource = textChatMessage.TextSource
	if textSource then
		local player = Players:GetPlayerByUserId(textSource.UserId)
		if player then
			local overrideProperties = TextChatService.ChatWindowConfiguration:DeriveNewMessageProperties()
			overrideProperties.PrefixText = textChatMessage.PrefixText
			overrideProperties.Text = textChatMessage.Text

			local nameColor = player:GetAttribute("NameColor")
			if nameColor and typeof(nameColor) == "Color3" then
				overrideProperties.PrefixTextProperties.TextColor3 = nameColor
			end

			local chatColor = player:GetAttribute("ChatColor")
			if chatColor and typeof(chatColor) == "Color3" then
				overrideProperties.TextColor3 = chatColor
			end

			local isYourTag = player:GetAttribute("isYourTag")
			if isYourTag == true then
				overrideProperties.PrefixText = `<font color='rgb(0, 255, 0)'>[YourTag]</font> {overrideProperties.PrefixText}`
			end

			local isOtherTag = player:GetAttribute("isOtherTag")
			if isOtherTag == true then
				overrideProperties.PrefixText = `<font color='rgb(255, 0, 0)'>[OtherTag]</font> {overrideProperties.PrefixText}`
			end

			return overrideProperties
		end
	end

	return nil
end