文字服務是內部負責處理遊戲中文字顯示的服務。
此類別有兩個成員函數:
TextService:GetTextSize() 功能讓開發人員能夠計算指定格式的特定文字字串所需的空間,返回 Vector2 像素大小。
TextService:FilterStringAsync() 功能必須正確過濾使用者指定的文字(例如聊天訊息或其他輸入),以保護使用者安全。不使用 Roblox 預設值 Chat 或允許用戶以其他方式輸入文字的開發人員必須使用此函數。
概要
方法
計算將使用指定的格式參數和尺寸限制時會與文字一起使用的 Vector2 維度 (以像素計算)。
- FilterAndTranslateStringAsync(stringToFilter : string,fromUserId : number,targetLocales : Array,textContext : Enum.TextFilterContext):TextFilterTranslatedResult
聊天翻譯在舊版聊天中不支持。此方法已不再支持,不應使用。
- FilterStringAsync(stringToFilter : string,fromUserId : number,textContext : Enum.TextFilterContext):TextFilterResult
過濾接收到的來自使用者的字串,並返回一個 TextFilterResult 可用於分配正確過濾的文字。
返回包含字體家族名稱和面的表。
計算給出的文字寬度和高度。
屬性
方法
GetTextSize
計算將使用指定的格式參數和尺寸限制時會與文字一起使用的 Vector2 維度 (以像素計算)。
注意,字體尺寸參數不會接受 Enum.FontSize 枚列。相反,應使用與 Enum.FontSize Enum 相應的整數尺寸。這不等於 Enum.FontSize Enum 的值。例如,對於 Size11 字體,整數 11 應該被使用。
此功能是 TextLabel.TextBounds 和 TextLabel 和 TextButton 對象的 屬性的有用替代。使用 TextLabel.TextBounds 屬性來計算需要的尺寸文字通常不實用,因為需要創建一個 TextLabel 對象。
使用 GetTextSize,特定文字字串在特定 TextLabel 或 TextButton 中需要的尺寸可以在創建任何對象或設設定文字屬性之前計算。
建議開發人員對結果添加一像素的墊片,以確保沒有文字被切關閉。
此方法僅限於列在 Enum.Font 中的字體。若要存取更多字體,您可以使用 TextService:GetTextBoundsAsync() 取代。
參數
返回
指定格式的字串所需的空間大小,以像素為單位。
範例程式碼
This example showcases a possible usage of the GetTextSize function.
It computes the possible Vector2 dimensions (in pixels) of the string "Hello World" when the font size is 12, the font size SourceSans and the frame size is (1,1).
The expected return of this function is the Vector2 value 9, 13.
local TextService = game:GetService("TextService")
local function getTextBounds()
local message = "Hello World"
local size = Vector2.new(1, 1)
local bounds = TextService:GetTextSize(message, 12, "SourceSans", size)
return bounds + Vector2.new(1, 1)
end
print(getTextBounds())
FilterAndTranslateStringAsync
聊天翻譯在舊版聊天中不支持。此方法已停止支援,不應使用。所有呼叫都會返回空對物件。翻譯聊天訊息只能透過 TextChatService 進行。
參數
返回
FilterStringAsync
FilterStringAsync 函數過濾從使用者那裡收到的字串,使用 TextService ,並返回一個 TextFilterResult 可用於分配正確過濾的文字的字串。
使用
此方法應在使用者提交訊息時每次呼叫一次。不要將此功能的結果進行緩存,並重複使用它們作為獨立訊息。如果使用者多次提交相同的文字,此方法必須在每次傳送訊息時再次呼叫。如果結果被緩存並重複使用,垃圾郵件偵測和許多上下文過濾類型將被破壞,可能會危害使用者安全。不適當使用緩存結果的遊戲可能會面臨管理。
然而,建議將這些結果對象保留以後加入伺服器的使用者顯示相同訊息。例如:這可以用來安全地和高效地實裝一個服務器聊天日誌,該日誌總是使用最少限制過濾來顯示加入後的用戶,或顯示像寵物名稱一樣的文字給一個用戶,他在寵物首次生成和名稱過濾之後加入遊戲。
可選擇的 Enum.TextFilterContext 參數不會影響查詢的過濾結果。這個值將用於改善 Roblox 的文字過濾。
私人文字是只有特定玩家看到的內容,而不是每個玩家。例如,如果聊天被單一玩家或由選定的玩家群看到,則聊天被視為私人的。團隊聊天或可能對更廣泛的群組體可見的聊天,例如伺服器,視為公開共。如果您不確定文字是否符合資格,請留下可選欄位為空。
注意:
- 這個方法總是會產生一個文字過濾服務呼叫
- 此方法可能會在出現無法解決的服務錯誤時發生。如果此功能發生錯誤,請不要重試請邀請;此方法內部實現自己的重試邏輯。如果此方法失敗,不要向任何用戶顯示文字。
- 此方法目前會在現有伺服器上線時拋出,如果 從使用者ID 不在線上,則會拋出。我們計畫在未來支持離線或在不同伺服器上的使用者。
參數
要過濾的文字。
過濾文字的玩家的ID。
過濾訊息將被使用的上下文。
返回
範例程式碼
This code sample includes a simple demonstration of how TextService:FilterStringAsync() should be implemented in a system where players are allowed to name their pets.
Note, this code sample includes the server-side implementation only (to be placed in a Script). Examples of how to implement the client-side of this system are included under the RemoteEvent and RemoteFunction examples.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local TextService = game:GetService("TextService")
local Players = game:GetService("Players")
local Remotes = Instance.new("Folder")
Remotes.Name = "PetNamingRemotes"
Remotes.Parent = ReplicatedStorage
local UserNamedPet = Instance.new("RemoteEvent")
UserNamedPet.Name = "UserNamedPet"
UserNamedPet.Parent = Remotes
local SendPetName = Instance.new("RemoteEvent")
SendPetName.Name = "SendPetName"
SendPetName.Parent = Remotes
local RequestAllPetNames = Instance.new("RemoteFunction")
RequestAllPetNames.Name = "RequestAllPetNames"
RequestAllPetNames.Parent = Remotes
local filterResults = {}
local function broadcastPetName(userId)
local filterResult = filterResults[userId]
if filterResult then
for _, player in pairs(Players:GetPlayers()) do
if player then
-- spawn a new thread so as to not yield the update
task.spawn(function()
-- grab the filtered string for this user
local toUserId = player.UserId
local filteredString = filterResult:GetNonChatStringForUserAsync(toUserId)
filteredString = filteredString or ""
SendPetName:FireClient(player, userId, filteredString)
end)
end
end
end
end
UserNamedPet.OnServerEvent:Connect(function(player, petName)
local fromUserId = player.UserId
-- pcall to catch errors
local success, result = pcall(function()
return TextService:FilterStringAsync(petName, fromUserId)
end)
if success then
filterResults[fromUserId] = result
broadcastPetName(fromUserId)
else
print("Could not filter pet name")
end
end)
RequestAllPetNames.OnServerInvoke = function(player)
local toUserId = player.UserId
local petNames = {}
-- go through filter results and filter the pet name to be sent
for fromUserId, filterResult in pairs(filterResults) do
local filteredString = filterResult:GetNonChatStringForUserAsync(toUserId)
filteredString = filteredString or ""
-- need to convert userId to string so it can't be sent via a remote function
petNames[tostring(fromUserId)] = filteredString
end
return petNames
end
Players.PlayerRemoving:Connect(function(oldPlayer)
local userId = oldPlayer.UserId
filterResults[userId] = nil
end)
GetFamilyInfoAsync
返回包含字體家族名稱和面的表。
返回的表結構如下:
type FaceInfo = {Name: string, -- 例子:「一般」、「書」、「義大利體」、「細義大利體」Weight: Enum.FontWeight,Style: Enum.FontStyle, -- 或正常或意大利文}type FamilyInfo = {Name: string, -- 範例:「源 Sans Pro」、「格林茲古蒂斯」Faces: {FaceInfo} -- 總是至少有 1 個,但最多可能有 18 個。}
如果字體家族已經由以前的呼叫 GetFamilyInfoAsync 、ContentProvider:PreloadAsync() 或具有 TextLabel.FontFace 屬性設定的文字對象載入過,那麼方法將無需退出。
錯誤
這個方法可能會因網路錯誤而失敗。你應該總是將它包裝在 pcall 中以進行錯誤處理。
在這些情況下發生錯誤:
- 傳送的家庭是空字串。
- 下載家庭失敗。
- 資產ID無效或指向不存在的資產。
參數
要查找的字體家族的資產ID。
返回
關於字體家族的資訊。
範例程式碼
This example showcases a possible usage of the TextService:GetFamilyInfoAsync() method.
It prints out information about a font family to the output window.
local TextService = game:GetService("TextService")
local familyToCheck = "rbxasset://fonts/families/Arial.json"
-- This is a yield function which may take up to a few seconds to download the font.
local info = TextService:GetFamilyInfoAsync(familyToCheck)
print("Name of the font:", info.Name)
print("Faces:")
for _, face in info.Faces do
print("--------")
print("Name:", face.Name)
print("Weight:", face.Weight.Name)
print("Style:", face.Style.Name)
end
GetTextBoundsAsync
此方法與 TextService:GetTextSize() 相似,但使用 Font 對象而不是 Enum.Font ,這樣可以使用更多字體。
用於測量一些文字的大小將會給予一組屬性,例如字串、尺寸和字體。
這是因為一些字體可能需要載入才能進行測量的輸出功能。如果字體已加載,則不會產生。ContentProvider:PreloadAsync() 可用於確保字體已載入。
錯誤
這個方法可能會因網路錯誤而失敗。你應該總是將它包裝在 pcall 中以進行錯誤處理。
在這些情況下發生錯誤:
- GetTextBoundsParams.Font 有空白家庭。
- params 參數是 nil 。
- 字體家族或字體面未能下載。
參數
一個指向 GetTextBoundsParams 對物件的參考。
返回
範例程式碼
This example shows how you can use TextService:GetTextBoundsAsync().
It measures the size of some text in a specific font, then prints the result.
local TextService = game:GetService("TextService")
local params = Instance.new("GetTextBoundsParams")
params.Text = "hello world!"
params.Font = Font.new("rbxasset://fonts/families/GrenzeGotisch.json", Enum.FontWeight.Thin)
params.Size = 20
params.Width = 200
local size = TextService:GetTextBoundsAsync(params)
print("The size of the text is:", size)