文字聊天概觀

Roblox 提供在線會話期間玩家之間的文字訊息通訊，通過 TextChatService 。此服務具有標準功能，但也提供一組方法和事件來擴展和自定义聊天，例如基於 自訂需求 傳送訊息、為特定玩家添加特殊權限或管理、以及創建 自訂指令 來執行特定行動。

下列部分總結了您可以使用來自訂聊天系統的主要類別和實例。

高級配置

唯一的 TextChatService 類別負責管理整個聊天系統，包括處理聊天訊息過濾、管理和使用者權限。使用像 CreateDefaultTextChannels 和 CreateDefaultCommands 等屬性來啟用或禁用預設聊天頻道和指令。

預設使用者介面配置

TextChatService 提供一個預設介面，可以自定義以符合您的體驗需求。每一種配置都可以禁用以隱藏相關的使用者介面元素，或可以用自訂介面來替換，如果需要。

• ChatWindowConfiguration — 代表預設聊天視窗介面，包括外觀和行為。停用它以隱藏聊天視窗。
• ChatInputBarConfiguration — 代表預設聊天輸入欄介面，包括其外觀和行為。
• 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 事件將訊息顯示給其他玩家。

文字聊天鉤和回呼呼叫

API 鼓勵在聊天訊息的外觀和傳送上進行明確的分離。多個文字聊天系統的實例提供鉤和回呼來在中央化、清晰的位置格式化。

| 呼叫回來 | 返回值 | | ----------------------------------------- | ----------------------------------- | | | boolean | | | | | | | | | | | | | | |

條件發送訊息

回调 TextChannel.ShouldDeliverCallback 應僅在服務器上定義。回叫被發射到文字通道的每個 TextSource 子時，當傳送一個訊息來確定訊息是否應該傳送時，回叫會被發射到文字通道的每個子。此回呼可用於實裝自訂訊息傳送邏輯，可能需要額外的遊戲上下文，例如：

• 基於位置的聊天 用戶只能向靠近他們的人發送消息。
• 防止擁有某些特性的使用者向他人發送訊息。

自訂訊息顯示

預設 TextChatService UI 使用 富文本 來格式化和自訂訊息的顯示方式。您可以使用以下回呼來格式化訊息，在顯示給使用者之前，例如添加顏色或 聊天標籤 到使用者名稱或格式訊息內容。

以下回呼將在每次顯示 TextChatMessage 即將顯示的內容時呼叫，可以根據 TextChannel、TextSource 或 TextChatMessage 內容自定義聊天窗口外觀。當客戶端傳送訊息時，這些回呼會在訊息傳送到伺服器時被稱為一次，值 TextChatMessage.Status 將為 Enum.TextChatMessageStatus.Sending 。一旦訊息被伺服器接收並傳送給其他使用者，發送端客戶端再次收到更新的 Enum.TextChatMessageStatus 值訊息。

• TextChatService.OnIncomingMessage — 此回呼應該只在客戶端定義。回叫將在收到訊息時發射，從伺服器或本地客戶端剛剛發送訊息時。回叫被稱為每次從所有 TextChatMessage 實例收到的每個TextChannel消息的第一個處理它的消息，之前它被顯示給用戶。
• TextChannel.OnIncomingMessage — 此回呼應該只在客戶端定義。回呼會在從伺服器收到訊息時發射。回叫將在每次從 TextChatMessage 收到 TextChannel 時被呼叫。從 TextChatService.CreateDefaultTextChannels 創建的預設 TextChannel 實例具有此回呼定義，可以被覆蓋。
• TextChatService.OnBubbleAdded — 此回呼應該只在客戶端定義。使用它來自定義聊天對話框的外觀，不受聊天窗口訊息外觀的影響。
• TextChatService.OnChatWindowAdded — 此回呼應該只在客戶端定義。使用它來自訂聊天窗口的聊天訊息的外觀，獨立於聊天泡泡中訊息的外觀。

從舊版聊天轉換到新版聊天

本節協助您從舊版聊天系統過渡到使用 TextChatService 實現常見聊天功能和行為的替代方法。

1. 在 導航器 窗口中，選擇 TextChatService 。

2. 在 屬性 窗口中，尋找 ChatVersion 下拉選單，然後選擇 TextChatService。

   

基本功能

雖然兩個系統都共享相同的基本聊天功能，但 TextChatService 實現在一般來說更可持續且更容易重複。

訊息過濾

TextChatService 自動過濾聊天訊息，根據每個玩家的帳戶資訊，因此您不需要手動實現所有類型的聊天訊息過濾。

窗口和對話泡泡聊天

兩個 聊天窗口 和 對話泡泡 的行為和自訂選項與舊版聊天系統相同。由於舊版聊天系統只允許使用聊天模組或 Players 容器進行自訂，服務提供專用類別（ChatWindowConfiguration 和 BubbleChatConfiguration）來管理所有聊天窗口和泡泡聊天屬性。此外，您可以使用 Studio 設定來輕鬆調整和預覽泡泡聊天的外觀和行為特性，而不需要全部寫入腳本。

移轉喇叭「額外資料」

舊版 Lua 聊天系統允許開發人員在 SetExtraData 類上使用 Speaker。這些資料被用來格式化名稱顏色、聊天顏色或應用名稱標籤給指定的發言者。

舊版聊天系統設置額外資料
-- 舊版聊天系統上設置額外資料的舉例
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