此服務用於與 ScriptDocument 實例互動。
概要
方法
移除先前註冊的名為 name 的回調。
移除先前註冊的名為 name 的回調。
返回與給定的 LuaSourceContainer 對應的打開 ScriptDocument,如果給定的腳本未打開則返回 nil。
返回給定腳本的編輯時源代碼。
返回當前打開的腳本文檔的數組,包括命令欄。
請求一個腳本編輯器打開指定的腳本。如果請求成功,則返回 (true, nil)。如果請求失敗,則返回 (false, string),並附帶描述問題的字符串。
註冊一個名為 name 的自動完成回調 callbackFunction,並指定優先級 priority。
註冊一個名為 name 的腳本分析回調 callbackFunction,並指定 priority。
從舊腳本生成新內容,並在編輯器打開時更新腳本編輯器,或在腳本編輯器關閉時更新 Script 實例。
活動
在 ScriptDocument 變更後立即觸發。
在 ScriptDocument 對象被銷毀之前觸發,這發生在腳本編輯器關閉之後。
在 ScriptDocument 對象被創建並添加到服務中後立即觸發,這發生在腳本編輯器打開之後。
屬性
方法
DeregisterAutocompleteCallback
移除先前註冊的名為 name 的回調。
參數
返回
範例程式碼
game.ScriptEditorService:DeregisterAutocompleteCallback("foo")
DeregisterScriptAnalysisCallback
移除先前註冊的名為 name 的回調。
參數
返回
範例程式碼
local ScriptEditorService = game:GetService("ScriptEditorService")
ScriptEditorService:DeregisterScriptAnalysisCallback("foo")
FindScriptDocument
返回與給定的 LuaSourceContainer 對應的打開 ScriptDocument,如果給定的腳本未打開則返回 nil。
參數
返回
範例程式碼
腳本文件:關閉異步
--!nocheck
-- 在命令列中執行以下程式碼
local ScriptEditorService = game:GetService("ScriptEditorService")
local documents = ScriptEditorService:GetScriptDocuments()
local scriptDocument
-- 找到第一個打開的腳本文件
for _, document in documents do
-- 命令列不能關閉,因此不要選擇它
if not document:IsCommandBar() then
scriptDocument = document
break
end
end
if scriptDocument then
local success, err = scriptDocument:CloseAsync()
if success then
print(`已關閉 {scriptDocument.Name}`)
else
warn(`無法 關閉 {scriptDocument.Name} 原因:{err}`)
end
else
print("沒有打開的 腳本")
end
演示使用 ScriptDocument.ViewportChanged 在視口變化時打印腳本的開始和結束行。
要運行:
確保輸出視圖已開啟
在命令欄中運行以下代碼
在打開的腳本窗口中上下滾動
--!nocheck
--[[
要運行:
1. 確保輸出視圖已開啟
2. 在命令欄中運行以下代碼
3. 在打開的腳本窗口中上下滾動
來自 ViewportChanged 事件的打印語句將出現在輸出中
]]
local Workspace = game:GetService("Workspace")
local ScriptEditorService = game:GetService("ScriptEditorService")
-- 創建跨越多行的文本
local dummyText = string.rep("-- 假文本\n", 60)
-- 創建一個包含假文本的腳本並打開它
local otherScript = Instance.new("Script")
otherScript.Source = dummyText
otherScript.Parent = Workspace
local success, err = ScriptEditorService:OpenScriptDocumentAsync(otherScript)
if not success then
warn(`無法打開腳本,因為: {err}`)
return
end
-- 獲取對打開的腳本的引用
local scriptDocument = ScriptEditorService:FindScriptDocument(otherScript)
local function onViewportChanged(startLine: number, endLine: number)
print(`腳本視口已變更 - 開始行: {startLine}, 結束行: {endLine}`)
end
-- 連接視口變更事件到上面的函數,該函數打印更新後視口的開始和結束行
scriptDocument.ViewportChanged:Connect(onViewportChanged)
GetEditorSource
返回給定腳本的編輯時源代碼。
如果腳本在 Script Editor 中打開,則此方法返回當前在編輯器中顯示的文本。如果腳本未在編輯器中打開,則方法返回在開啟編輯器時該腳本將顯示的文本。編輯時源代碼不一定與 Script.Source 屬性一致。
參數
返回
GetScriptDocuments
返回當前打開的腳本文檔的數組,包括命令欄。
返回
範例程式碼
獲取場景中所有腳本文件,使用 ScriptEditorService:GetScriptDocuments() 並列印它們的名稱。
--!nocheck
-- 在命令欄執行以下代碼
local ScriptEditorService = game:GetService("ScriptEditorService")
local scriptDocuments = ScriptEditorService:GetScriptDocuments()
for _, scriptDocument in scriptDocuments do
-- 列印每個腳本的名稱
if not scriptDocument:IsCommandBar() then
print(scriptDocument.Name)
end
end
OpenScriptDocumentAsync
請求一個腳本編輯器打開指定的腳本。如果請求成功,則返回 (true, nil)。如果請求失敗,則返回 (false, string),並附帶描述問題的字符串。
如果腳本已經打開,則此函數成功並切換到相關的編輯器選項卡。
參數
返回
範例程式碼
ScriptEditorService:打開腳本文件異步
--!nocheck
-- 在命令列中運行以下代碼
local ScriptEditorService = game:GetService("ScriptEditorService")
local Workspace = game:GetService("Workspace")
local newScript = Instance.new("Script")
newScript.Parent = Workspace
local success, err = ScriptEditorService:OpenScriptDocumentAsync(newScript)
if success then
print("已打開腳本文件")
else
print(`打開腳本文件失敗:{err}`)
end
RegisterAutocompleteCallback
註冊一個名為 name 的自動完成回調 callbackFunction,並指定優先級 priority。
當腳本編輯器調用自動完成時,所有註冊的自動完成回調都按升序優先級順序調用,並返回自動完成請求和響應。多個回調可以共享相同的優先級,但它們的調用順序不可預測。每個回調應返回一個響應表,其格式與響應輸入表相同。 回調不應該讓出。第一個被調用的回調接收內部自動完成的響應,後續的回調接收前一個回調的輸出作為它們的響應表。回調可以修改傳遞的表或返回相同格式的新表。
callbackFunction 必須具有以下類型:(Request: table, Response: table) -> table
請求表具有以下格式:
type Request = {position: {line: number,character: number},textDocument: {document: ScriptDocument?,script: LuaSourceContainer?}}
- position 是你正在自動完成的以 1 為索引的光標位置。
- textDocument.document 是你正在完成的打開的 ScriptDocument,如果存在。
- textDocument.script 是你正在完成的 LuaSourceContainer,如果存在。
如果 textDocument.document 和 textDocument.script 同時存在,則它們彼此對應: req.textDocument.document:GetScript() == req.textDocument.script
響應表具有以下格式:
type Response = {items: {{label: string, -- 標籤kind: Enum.CompletionItemKind?,tags: {Enum.CompletionItemTag}?,detail: string?,documentation: {value: string,}?,overloads: number?,learnMoreLink: string?,codeSample: string?,preselect: boolean?,textEdit: {newText: string,insert: { start: { line: number, character: number }, ["end"]: { line: number, character: number } },replace: { start: { line: number, character: number }, ["end"]: { line: number, character: number } },}?}}}
- Response.items 是自動完成項的數組。該數組的順序不是重要的,並且在用戶輸入時會重新排序。
- Response.items[n].label 是顯示在自動完成菜單中的項目標籤。
- Response.items[n].kind 指定這是什麼類型的自動完成項。主要控制項目在編輯器中給予的圖標。並非所有類型都有獨特的圖標。如果未指定,編輯器使用 "Text" 圖標。未支持的類型默認顯示 "Property" 圖標。
- Response.items[n].tags 指定描述此完成項的標籤的數組。詳情請參閱 Enum.CompletionItemTag。
- Response.items[n].details 指定描述有關完成項的詳細信息的字符串。對於默認項,這是其類型的字符串表示。注意為了文檔小部件顯示,documentation 必須存在,但 documentation.value 可以是空的。
- Response.items[n].documentation 指定其 value 字段的文檔主體。即使 value 是空的,documentation 仍然存在,因此如果指定了詳細信息或重載,文檔窗口將顯示。
- Response.items[n].overloads 指定函數自動完成的重載數量。
- Response.items[n].learnMoreLink 連結到創作者文檔上的相關頁面。此 URL 必須是 https 請求到 create.roblox.com;在編輯器中不顯示其他 URL。
- Response.items[n].codeSample 指定該自動完成項的示例用法。documentation 必須為非空以顯示此字段。
- Response.items[n].preselect 如果為 true,則編輯器會將此自動完成項排在所有其他項目之前並默認選中。為 false 或缺失時無任何效果。
- Response.items[n].textEdit 如果存在,接受自動完成將應用此文本編輯 - 在開始和結束位置之間插入或替換 newText。
如果回調返回格式錯誤的結果或遇到錯誤,編輯器將丟棄修改後的響應表並使用內置的自動完成結果列表。
參數
返回
範例程式碼
ScriptEditorService:註冊自動完成回調
ScriptEditorService:註銷自動完成回調
--!nocheck
-- 在命令欄中運行以下代碼
local ScriptEditorService = game:GetService("ScriptEditorService")
type Request = {
position: {
line: number,
character: number,
},
textDocument: {
document: ScriptDocument?,
script: LuaSourceContainer?,
},
}
type Response = {
items: {
{
label: string,
kind: Enum.CompletionItemKind?,
tags: { Enum.CompletionItemTag }?,
detail: string?,
documentation: {
value: string,
}?,
overloads: number?,
learnMoreLink: string?,
codeSample: string?,
preselect: boolean?,
textEdit: {
newText: string,
replace: {
start: { line: number, character: number },
["end"]: { line: number, character: number },
},
}?,
}
},
}
local autocompleteCallback = function(request: Request, response: Response): Response
local item = {
label = "foo",
preselect = true,
}
table.insert(response.items, item)
return response
end
ScriptEditorService:RegisterAutocompleteCallback("foo", 1, autocompleteCallback)
-- 若要註銷回調,請在命令欄中運行以下代碼
ScriptEditorService:DeregisterAutocompleteCallback("foo")
RegisterScriptAnalysisCallback
註冊一個名為 name 的腳本分析回調 callbackFunction,並指定 priority。當 Studio 中的腳本分析運行時,所有註冊的回調按升序優先級調用。每個回調旨在返回與以下格式相匹配的響應表。回調不應該讓出。
請求表具有以下格式,其中 script 是將被分析的 LuaSourceContainer。
type Request = {script: LuaSourceContainer?}
響應表具有以下格式,其中 diagnostics 是一個診斷表的數組。每個診斷表都具有以下列出的條目。
type Response = {diagnostics: {{range: {start: {line: number,character: number,},["end"]: {line: number,character: number,}},code: string?,message: string,severity: Enum.Severity?,codeDescription: { href: string }?}}}
- range 代表應由 linter 高亮顯示的文本範圍,提供應高亮的起始行/字符和結束行/字符。
- code 是消息的標籤。
- message 是要顯示的警告消息。當用戶將光標懸停在腳本編輯器中的行上時,這也將出現在工具提示中。
- severity 是診斷的 Enum.Severity 值。這決定了在 Studio 中的腳本分析工具中診斷的分類方式,以及如何在腳本編輯器中高亮顯示文本。
- codeDescription 連結到創作者文檔上的相關頁面。此 URL 必須是請求 https 到 create.roblox.com;在編輯器中不顯示其他 URL。
參數
返回
範例程式碼
type Request = {
["script"]: LuaSourceContainer,
}
type Response = {
diagnostics: {
{
range: {
start: {
line: number,
character: number,
},
["end"]: {
line: number,
character: number,
},
},
code: string?,
message: string,
severity: Enum.Severity?,
codeDescription: { href: string }?,
}
},
}
local ScriptEditorService = game:GetService("ScriptEditorService")
ScriptEditorService:RegisterScriptAnalysisCallback("foo", 1, function(Req: Request): Response
local response = {
diagnostics = {},
}
local lineNo = 1
-- 逐行迭代
for text, newline in Req.script.Source:gmatch("([^\r\n]*)([\r\n]*)") do
local startIndex, endIndex = string.find(text, "Foo")
if startIndex and endIndex then
table.insert(response.diagnostics, {
range = {
["start"] = {
line = lineNo,
character = startIndex,
},
["end"] = {
line = lineNo,
character = endIndex,
},
},
code = "FooFinder",
message = "在這裡找到 Foo!",
severity = Enum.Severity.Warning,
})
end
lineNo = lineNo + #newline:gsub("\n+", "\0%0\0"):gsub(".%z.", "."):gsub("%z", "")
end
return response
end)
UpdateSourceAsync
返回給定腳本的編輯時 Script.Source。
此函數使用舊內容調用傳遞的回調,以計算腳本的新內容。
如果腳本在 Script Editor 中打開,則它會向編輯器發出請求以更新其源。如果在調用此函數時 Script.Source 屬性與用戶的腳本版本不一致,則編輯器可能會拒絕此更新,在這種情況下將重新調用回調並重複嘗試。
回調不應該讓出。如果回調返回 nil,則操作會被取消。此函數會等待直到操作被取消或成功。
如果腳本未在編輯器中打開,則新內容會更新到腳本源,即如果腳本被打開編輯器將顯示的文本。
local ses = game:GetService('ScriptEditorService')
ses:UpdateSourceAsync(Workspace.Script,
function(oldContent)
return oldContent .. " World!"
end)
參數
要更新的腳本實例。
返回新腳本內容的函數。
返回
活動
TextDocumentDidChange
在 ScriptDocument 變更後立即觸發。textChanged 是一個變更結構的數組,其格式為:
{ range : { start : { line : number, character : number }, end : { line : number, character : number } }, text: string }
參數
範例程式碼
ScriptEditorService.文本文件已變更
--!nocheck
-- 在命令欄中運行以下代碼
local ScriptEditorService = game:GetService("ScriptEditorService")
ScriptEditorService.TextDocumentDidChange:Connect(function(scriptDocument, changes)
print("已變更", scriptDocument, changes)
end)
TextDocumentDidClose
在 ScriptDocument 對象被銷毀之前觸發,這發生在腳本編輯器關閉之後。此事件觸發後,ScriptDocument 進入「已關閉」狀態,試圖調用其方法會引發錯誤。ScriptDocument 對象不可重用,即使腳本編輯器重新打開相同的腳本。
參數
範例程式碼
腳本編輯器服務. 文檔關閉
--!nocheck
-- 在命令欄中運行以下代碼
local ScriptEditorService = game:GetService("ScriptEditorService")
ScriptEditorService.TextDocumentDidClose:Connect(function(scriptDocument)
print("已關閉", scriptDocument)
end)
TextDocumentDidOpen
在 ScriptDocument 對象被創建並添加到服務中後立即觸發,這發生在腳本編輯器打開之後。
參數
範例程式碼
腳本編輯器服務. 文檔已打開
--!nocheck
-- 在命令欄中運行以下代碼
local ScriptEditorService = game:GetService("ScriptEditorService")
ScriptEditorService.TextDocumentDidOpen:Connect(function(scriptDocument)
print("已打開", scriptDocument)
end)