自定义聊天窗口 | 文档 - Roblox 创作者中心

in-game text chat系统由TextChatService提供支持，允许玩家在实时游戏中轻松与彼此沟通和社交。除了支持默认文本聊天外，您还可以自定义前端用户界面。

聊天窗口配置

整体聊天窗口由以下部分组成：

聊天窗口
输入栏
渠道标签（可选）

渠道标签默认禁用，每个组件可以在Studio中或通过脚本进行启用或禁用：

在资源管理器窗口中，展开TextChatService分支并选择ChatWindowConfiguration、ChatInputBarConfiguration或ChannelTabsConfiguration。然后在属性窗口中启用或禁用组件。

当ChannelTabsConfiguration启用时，每个默认的TextChannel会在标签中显示，如下表所示。此外，每个自定义的TextChannel会创建一个与频道的Name属性相对应的标签。

默认频道	标签名称
RBXGeneral	常规
RBXSystem	常规（与RBXGeneral合并为一个标签）
RBXTeam	队伍
RBXWhisper	其他玩家的用户名

窗口外观

总体聊天窗口的外观可以通过ChatWindowConfiguration进行自定义。

Explorer层次结构中的ChatWindowConfiguration实例。

属性	描述	默认值
BackgroundColor3	Color3聊天窗口的背景颜色。	[25, 27, 29]
BackgroundTransparency	聊天窗口背景的透明度。	0.3
Enabled	是否显示默认聊天窗口。设置为false以隐藏。	true
FontFace	聊天窗口文本的Font。	BuilderSansMedium
TextColor3	聊天窗口文本的Color3。	[255, 255, 255]
TextSize	聊天窗口文本的大小。	14
TextStrokeColor3	聊天窗口文本的笔画Color3。	[0, 0, 0]
TextStrokeTransparency	聊天窗口文本的笔画透明度。	0.5
HorizontalAlignment	聊天窗口的水平对齐方式。	Left
VerticalAlignment	聊天窗口的垂直对齐方式。	Top
HeightScale	聊天窗口相对于屏幕大小的高度比例。	1
WidthScale	聊天窗口相对于屏幕大小的宽度比例。	1

输入栏外观

聊天输入栏的外观可以通过ChatInputBarConfiguration进行自定义。

Explorer层次结构中的ChatInputBarConfiguration实例。

属性	描述	默认值
BackgroundColor3	Color3聊天输入栏的背景颜色。	[25, 27, 29]
BackgroundTransparency	聊天输入栏背景的透明度。	0.2
FontFace	聊天输入文本的Font。	BuilderSansMedium
PlaceholderColor3	Color3占位符聊天输入文本的颜色。	[178, 178, 178]
TextColor3	Color3玩家输入的聊天文本颜色。	[255, 255, 255]
TextSize	聊天输入文本的大小。	14
TextStrokeColor3	Color3聊天输入文本的笔画颜色。	[0, 0, 0]
TextStrokeTransparency	聊天输入文本笔画的透明度。	0.5
AutocompleteEnabled	文本聊天系统是否显示表情符号和命令的自动补全选项。表情符号通过输入:后接非空格字符进行自动补全，而命令通过输入/进行自动补全。	true
KeyboardKeyCode	玩家可以按下的其他键，以触发聚焦到默认聊天输入栏。	Slash

渠道标签外观

渠道标签的外观可以通过ChannelTabsConfiguration进行自定义。

Explorer层次结构中的ChannelTabsConfiguration实例。

属性	描述	默认值
BackgroundColor3	Color3渠道标签的背景颜色。	[25, 27, 29]
BackgroundTransparency	渠道标签背景的透明度。	0
HoverBackgroundColor3	Color3在悬停时标签的背景颜色。	[125, 125, 125]
FontFace	渠道标签中文本的Font。	BuilderSansBold
TextColor3	未选择标签中文本的Color3。	[175, 175, 175]
SelectedTabTextColor3	选定标签中文本的Color3。	[255, 255, 255]
TextSize	渠道标签中文本的大小。	18
TextStrokeColor3	Color3渠道标签中文本的笔画颜色。	[0, 0, 0]
TextStrokeTransparency	渠道标签中文本的笔画透明度。	1

自定义消息

您可以使用ChatWindowMessageProperties和TextChatService.OnChatWindowAdded回调自定义聊天消息主体和前缀的外观，而无需覆盖现有的用户界面。这些自定义选项让您修改聊天消息的外观以匹配游戏的主题，您还可以通过为前缀着色或添加聊天标签来对不同用户组的消息进行排序或高亮显示。

ChatWindowMessageProperties和OnChatWindowAdded仅影响聊天窗口中消息的外观。要自定义聊天气泡，请参见气泡聊天。

颜色用户名称

当用户发送聊天消息时，他们的DisplayName作为消息的前缀部分显示。默认情况下，每个用户的名称根据其Player.TeamColor着色，但您可以使用ChatWindowMessageProperties和OnChatWindowAdded更改聊天名称的颜色。以下LocalScript在StarterPlayerScripts中为每个用户分配预定颜色，从RGB颜色表中随机选择。

LocalScript - 随机用户名颜色
local TextChatService = game:GetService("TextChatService")

local chatWindowConfiguration = TextChatService.ChatWindowConfiguration

local nameColors = {
	Color3.fromRGB(255, 0, 0),
	Color3.fromRGB(0, 255, 0),
	Color3.fromRGB(0, 0, 255),
	Color3.fromRGB(255, 255, 0),
}

TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
	local properties = chatWindowConfiguration:DeriveNewMessageProperties()

	local textSource = message.TextSource
	if textSource then
		local index: number = (textSource.UserId % #nameColors) + 1
		local randomColor: Color3 = nameColors[index]

    	properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
		properties.PrefixTextProperties.TextColor3 = randomColor
	end

	return properties
end

您还可以通过使用UIGradient为消息前缀应用颜色和透明度渐变。

渐变用户名颜色
local TextChatService = game:GetService("TextChatService")

local chatWindowConfiguration = TextChatService.ChatWindowConfiguration

local gradient = Instance.new("UIGradient")
gradient.Color = ColorSequence.new{
	ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 0, 0)),
	ColorSequenceKeypoint.new(0.5, Color3.fromRGB(255, 255, 0)),
	ColorSequenceKeypoint.new(1, Color3.fromRGB(255, 0, 255))
}

TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
	local properties = chatWindowConfiguration:DeriveNewMessageProperties()

	local textSource = message.TextSource
	if textSource then
    	properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
		gradient:Clone().Parent = properties.PrefixTextProperties
	end

	return properties
end

富文本自定义

富文本字体颜色标签可用于格式化聊天消息，如果您想对消息的特定部分应用格式非常有用。请注意，富文本不支持渐变，但以下代码示例展示了如何将用户名（存储在TextChatMessage.PrefixText）移动到消息主体中，然后仅对名称部分应用富文本标签。

富文本自定义
local TextChatService = game:GetService("TextChatService")
local Players = game:GetService("Players")

local chatWindowConfiguration = TextChatService.ChatWindowConfiguration

local gradient = Instance.new("UIGradient")
gradient.Color = ColorSequence.new{
	ColorSequenceKeypoint.new(0, Color3.fromRGB(255, 0, 0)),
	ColorSequenceKeypoint.new(0.5, Color3.fromRGB(255, 255, 0)),
	ColorSequenceKeypoint.new(1, Color3.fromRGB(255, 0, 255))
}

TextChatService.OnChatWindowAdded = function(message: TextChatMessage)
	local properties = chatWindowConfiguration:DeriveNewMessageProperties()

	if message.TextSource then
		properties.PrefixText = "[VIP]"
		properties.Text = string.format("<font color='#00ffff'>%s</font>", message.PrefixText) .. " " .. message.Text

		properties.PrefixTextProperties = chatWindowConfiguration:DeriveNewMessageProperties()
		gradient:Clone().Parent = properties.PrefixTextProperties
	end

	return properties
end

非玩家来源的消息

当TextChatService.CreateDefaultTextChannels为true时，默认文本频道之一是RBXSystem频道。默认聊天脚本会自动在此频道中显示系统消息。您可以使用TextChannel.OnIncomingMessage回调自定义这些消息的外观。

您可能想要自定义或更改自动由聊天系统发出的系统消息。由于默认系统消息是针对用户本地化的，如果您希望自定义其外观，则应该通过TextChatMessage.Metadata在您的文本聊天回调中引用它们。例如，您可以使用Metadata来识别游戏中特定系统的系统消息、错误消息或消息。

系统

要将系统消息传递给本地玩家，例如来自公共广播系统的“讲话”，请调用默认的RBXGeneral频道中的DisplaySystemMessage()，并在玩家的显示名称之前加上前缀。

Client Script
local Players = game:GetService("Players")
local TextChatService = game:GetService("TextChatService")

local player = Players.LocalPlayer
local generalChannel: TextChannel = TextChatService:WaitForChild("TextChannels").RBXGeneral

local PREFIX = "[Guide] Welcome "

-- 发送“系统消息”给玩家并附加他们的显示名称
generalChannel:DisplaySystemMessage(PREFIX .. player.DisplayName)

NPC/对象

您还可以为非玩家对话进行样式设计，并添加聊天气泡，使其看起来像是来自3D世界中的NPC或对象的消息。

Client Script
local TextChatService = game:GetService("TextChatService")
local Workspace = game:GetService("Workspace")

local generalChannel: TextChannel = TextChatService:WaitForChild("TextChannels").RBXGeneral

TextChatService.OnIncomingMessage = function(textChatMessage: TextChatMessage)
	local properties = Instance.new("TextChatMessageProperties")

	-- 检查是否为包含元数据的系统消息
	if not textChatMessage.TextSource and textChatMessage.Metadata ~= "" then

		-- 添加前缀使消息看起来像是由玩家发送的
		properties.PrefixText = string.format("<font color='#%s'>%s: </font>", "#50C999", textChatMessage.Metadata)

		-- 添加气泡聊天
		TextChatService:DisplayBubble(Workspace.Statue, textChatMessage.Text)
	end

	return properties
end

local message = "欢迎！我将成为你的向导。"
local speakerName = "古代骑士"
generalChannel:DisplaySystemMessage(message, speakerName)