一個 ScriptDocument 實例是 Studio 腳本編輯器的文件代理。與在編輯器中打開的 LuaSourceContainer 不同，它代表開啟文件的暫時狀態，其代表格式比執行它更適合閱讀和編輯代碼，而不是執行它。特別是，ScriptDocument 反映任何在草稿模式中對開放腳本進行的變更，源屬性沒有。
腳本編輯器本身存在且在不同的線程上變更，因此 複製開啟的腳本編輯器，但它不是開啟的編輯器。由於複製，有時會在更改編輯器中的文字和更新 ScriptDocument 之間出現稍微延遲。延遲通常發生因為 DataModel 很忙，而且差不多總是非常小，但仍然存在。
一個 ScriptDocument 的存在表示有文件在腳本編輯器中打開。所有 ScriptDocument 實例都有 ScriptEditorService 作為其父元素。每個實例遵守以下編碼規約：
- 在 ScriptDocument 中的所有文字都使用 UTF-8 編碼。
- 所有線索都是 1 索引。
- 所有角色指數都是 1 索引並計數 UTF-8 字元，而不是字形，因此同樣的警告適用於 TextBox.CursorPosition：許多Unicode字元需要超過一個字元。
- 所有範圍包括其起始位置和獨家終止位置，因此開始 == 結束暗示一個空白範圍。
所有 API 對於 ScriptDocument 都位於 插件 等級安全。
概要
方法
返回指定線的文字。當沒有提供參數時，返回當前鼠標位置的線。
返回文件中的行數。
如果存在，返回底層 LuaSourceContainer 實個體、實例；否則返回 nil 。
獲得編輯器中選擇的文字，或空字串，如果沒有選擇。
以格式 CursorLine, CursorChar, AnchorLine, AnchorChar 返回腳本編輯器最後一次知道的選擇。如果腳本編輯器沒有選擇，則 CursorLine == AnchorLine 和 CursorChar == AnchorChar 。
獲得更大的鼠標位置和固定。如果編輯器沒有選擇，它們是相同值。
獲得鼠標位置和固定點中最小的值。如果編輯器沒有選擇，它們是相同值。
- GetText(startLine : number?,startCharacter : number?,endLine : number?,endCharacter : number?):string
從開啟的編輯器返回文字。
返回編輯器變更中顯示的線號。
返回編輯器是否有任何文字已選取。
如果 ScriptDocument 代表指令欄，則返回真值。
要求與此文件相關的編輯程式關閉。在編輯程式回應要邀請之前，提供現有線程。
- EditTextAsync(newText : string,startLine : number,startCharacter : number,endLine : number,endCharacter : number):Tuple
以新文字取代指定範圍內的文字(startLine、startColumn到(endLine、endColumn)的文字。
- ForceSetSelectionAsync(cursorLine : number,cursorCharacter : number,anchorLine : number?,anchorCharacter : number?):Tuple
請求編輯器將鼠標選擇設置為引數值。
- RequestSetSelectionAsync(cursorLine : number,cursorCharacter : number,anchorLine : number?,anchorCharacter : number?):Tuple
請求編輯器將鼠標選擇設置為引數值。
活動
- SelectionChanged(positionLine : number,positionCharacter : number,anchorLine : number,anchorCharacter : number):RBXScriptSignal
當變更腳本文件時發生火災，包括文字變更後立即發生。
當編輯器中顯示的行號碼變更時發生火災。
屬性
方法
GetLine
返回指定線的文字。當沒有提供參數時，返回當前鼠標位置的線。
參數
預設值："nil"
返回
範例程式碼
ScriptDocument.SelectionChanged and ScriptDocument:GetLine()
ScriptDocument.SelectionChanged and ScriptDocument:GetLine()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
scriptDocument.SelectionChanged:Connect(function(positionLine, positionCharacter, anchorLine, anchorCharacter)
print(`Selected: Line {positionLine}, Char {positionCharacter}`)
print(`Anchor: Line {anchorLine}, Char {anchorCharacter}`)
local lineText = scriptDocument:GetLine(positionLine)
print(`Selected line text: {lineText}`)
end)
else
print("No scripts open")
endGetLineCount
返回有效文件中的行數。
返回
範例程式碼
ScriptDocument:GetLineCount()
ScriptDocument:GetLineCount()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
local lineCount = scriptDocument:GetLineCount()
print(`The script has {lineCount} lines!`)
else
print("No scripts open")
endGetScript
如果存在，返回底層 LuaSourceContainer 實個體、實例；否則返回 nil 。
返回
範例程式碼
ScriptDocument:GetScript()
ScriptDocument:GetScript()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
local openScript = scriptDocument:GetScript()
print(`Currently open script: {openScript:GetFullName()}`)
else
print("No scripts open")
endGetSelectedText
獲得編輯器中選擇的文字，或空字串，如果沒有選擇。
返回
範例程式碼
ScriptDocument:HasSelectedText() and :GetSelectedText()
ScriptDocument:HasSelectedText() and :GetSelectedText()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
scriptDocument.SelectionChanged:Connect(function()
if scriptDocument:HasSelectedText() then
local selectedText = scriptDocument:GetSelectedText()
print(`Currently selected text: {selectedText}`)
else
print("No text currently selected")
end
end)
else
print("No scripts open")
endGetSelection
以格式 CursorLine, CursorChar, AnchorLine, AnchorChar 返回腳本編輯器最後一次知道的選擇。如果腳本編輯器沒有選擇，則 CursorLine == AnchorLine 和 CursorChar == AnchorChar 。
返回
CursorLine、CursorChar、AnchorLine、AnchorChar。
GetSelectionEnd
獲得更大的鼠標位置和固定。如果編輯器沒有選擇，它們是相同值。
返回
範例程式碼
ScriptDocument:GetSelectionStart() and :GetSelectionEnd()
ScriptDocument:GetSelectionStart() and :GetSelectionEnd()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
local startLine, startCharacter = scriptDocument:GetSelectionStart()
local endLine, endCharacter = scriptDocument:GetSelectionEnd()
print(`Selection start: Line {startLine}, Char {startCharacter}`)
print(`Selection end: Line {endLine}, Char {endCharacter}`)
else
print("No scripts open")
endGetSelectionStart
獲得鼠標位置和固定點中最小的值。如果編輯器沒有選擇，它們是相同值。
返回
範例程式碼
ScriptDocument:GetSelectionStart() and :GetSelectionEnd()
ScriptDocument:GetSelectionStart() and :GetSelectionEnd()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
local startLine, startCharacter = scriptDocument:GetSelectionStart()
local endLine, endCharacter = scriptDocument:GetSelectionEnd()
print(`Selection start: Line {startLine}, Char {startCharacter}`)
print(`Selection end: Line {endLine}, Char {endCharacter}`)
else
print("No scripts open")
endGetText
從開啟的編輯器返回文字。必須使用 0、2 或 4 個參數呼叫：
- 如果使用 0 個參數呼叫，會獲得開啟編輯器的全部內容。
- 如果使用 2 個參數呼叫，會獲得文件的文字，從 ( startLine , startColumn ) 開始。
- 如果使用 4 個參數呼叫，會獲得文件的文字，從 ( ) 開始，到 ( > ) 結束。
參數
預設值："nil"
預設值："nil"
預設值："nil"
預設值："nil"
返回
範例程式碼
ScriptDocument:GetText()
ScriptDocument:GetText()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
local text = scriptDocument:GetText()
print(`Script contents: {text}`)
else
print("No scripts open")
endGetViewport
返回編輯器變更中顯示的線號。編輯器會顯示從開始線到結束線之間的線，包括在內。第一行和最後行可能只顯示部分。例如，最後一行的最上方像素可能只在畫面上。此外，代碼折疊可能會隱藏起始線和結束線之間的線。
返回
範例程式碼
ScriptDocument:GetViewport
ScriptDocument:GetViewport
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
local firstLine, lastLine = scriptDocument:GetViewport()
print(`Currently viewing lines {firstLine} to {lastLine}`)
else
print("No scripts open")
endHasSelectedText
返回編輯器是否有任何文字已選取。
返回
範例程式碼
ScriptDocument:HasSelectedText() and :GetSelectedText()
ScriptDocument:HasSelectedText() and :GetSelectedText()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
scriptDocument.SelectionChanged:Connect(function()
if scriptDocument:HasSelectedText() then
local selectedText = scriptDocument:GetSelectedText()
print(`Currently selected text: {selectedText}`)
else
print("No text currently selected")
end
end)
else
print("No scripts open")
endIsCommandBar
如果 ScriptDocument 代表命令欄，返回真值；命令欄在此 API 中有特殊規則和限制：
- 工作室在執行插件之前創建指令欄，因此它並不總是發射開啟的事件，雖然它會關閉並重新開啟，因為它在數據模型之間轉移時。
- 你無法因安全原因編輯指令欄 EditTextAsync 。
返回
範例程式碼
ScriptDocument:IsCommandBar()
ScriptDocument:IsCommandBar()
--!nocheck
-- Run the following code in the Command Bar
local ScriptEditorService = game:GetService("ScriptEditorService")
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if document:IsCommandBar() then
print("Command bar document:", document)
end
endCloseAsync
要求與此文件相關的編輯程式關閉。在編輯器回應要邀請之前，提供現有線程。如果功能成功，它將返回 (true、nil)。如果功能失敗，它會返回 (false、strin字串) 作為問題的說明。
此功能無法關閉指令欄。
返回
範例程式碼
ScriptDocument:CloseAsync
ScriptDocument:CloseAsync
--!nocheck
-- Run the following code in the Command Bar
local ScriptEditorService = game:GetService("ScriptEditorService")
local documents = ScriptEditorService:GetScriptDocuments()
local scriptDocument
-- Find the first open script document
for _, document in documents do
-- The Command Bar can't be closed, so don't select it
if not document:IsCommandBar() then
scriptDocument = document
break
end
end
if scriptDocument then
local success, err = scriptDocument:CloseAsync()
if success then
print(`Closed {scriptDocument.Name}`)
else
warn(`Failed to close {scriptDocument.Name} because: {err}`)
end
else
print("No open scripts")
endEditTextAsync
以 newText 取代指定範圍內的文字 ( startLine, startColumn ) 到 ( endLine, endColumn ) 的文字。如果範圍為空，則函數會在(startLine和(startColumn中插入文字。如果文字捕捉器在指定範圍內，則捕捉器會移動到編輯的最後位置。否則，文字捲動器不會移動工具。此功能返回編輯器對編輯的回應直到它收到編輯器的回應為止。
如果函數成功，它將返回（true，nil）。
如果功能發生錯誤，則：
- 範圍無效。
- 範圍將切割一個Unicode字元，例如只替換Unicode字元的部分字元。
- newText 本身包含無效的 UTF-8。
如果功能失敗，它將返回 (false、string)。字串是問題的描述。最常見的故障類型是版本不匹配。這會發生當你嘗試在 期間呼叫 時，當 與編輯器內容不同步時。如果發生這種情況，您可以重試編輯。
參數
預設值：""
預設值：""
預設值：""
預設值：""
預設值：""
返回
ForceSetSelectionAsync
請求編輯器將鼠標選擇設置為引數值。兩個錨定參數必須傳送，或不傳送。如果兩者都未傳送，則兩者將各自默認為與對應的曲標參數相同。編輯器可能會拒絕更新其鼠標，如果文件的文字內容已變更。與 ScriptDocument:RequestSetSelectionAsync() 不同，編輯器不會拒絕移動其鼠標，如果鼠標自請求以來已移動。如果鼠標已更新，返回 (true、nil)；如果未更新，則返回 (false、string) 並附上說明字串。在編輯器回應之前，提供現有線程。
參數
預設值：""
預設值：""
預設值："nil"
預設值："nil"
返回
範例程式碼
ScriptDocument:ForceSetSelectionAsync()
ScriptDocument:ForceSetSelectionAsync()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
-- Get the text on the cursor's current line
local cursorLine = scriptDocument:GetSelection()
local lineText = scriptDocument:GetLine(cursorLine)
-- Force select the entire line of text
local success, err = scriptDocument:ForceSetSelectionAsync(cursorLine, 1, cursorLine, #lineText + 1)
if success then
print("Set selection!")
else
print(`Failed to set selection because: {err}`)
end
else
print("No scripts open")
endRequestSetSelectionAsync
請求編輯器將鼠標選擇設置為引數值。兩個錨定參數必須傳送，或不傳送。如果兩者都未傳送，則兩者將各自默認為與對應的曲標參數相同。編輯器可能拒絕更新其鼠標內容，如果文件的文字內容已更改，或鼠標自請求以來已移動。如果鼠標已更新，返回 (true、nil)；如果未更新，則返回 (false、string) 並附上說明字串。在編輯器回應之前，提供現有線程。
參數
預設值：""
預設值：""
預設值："nil"
預設值："nil"
返回
範例程式碼
ScriptDocument:RequestSetSelectionAsync()
ScriptDocument:RequestSetSelectionAsync()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
-- Get the text on the cursor's current line
local cursorLine = scriptDocument:GetSelection()
local lineText = scriptDocument:GetLine(cursorLine)
-- Force select the entire line of text
local success, err = scriptDocument:RequestSetSelectionAsync(cursorLine, 1, cursorLine, #lineText + 1)
if success then
print("Set selection!")
else
print(`Failed to set selection because: {err}`)
end
else
print("No scripts open")
end活動
SelectionChanged
當變更腳本文件時發生火災，包括文字變更後立即發生。
參數
範例程式碼
ScriptDocument.SelectionChanged and ScriptDocument:GetLine()
ScriptDocument.SelectionChanged and ScriptDocument:GetLine()
--!nocheck
-- Run the following code in the Command Bar while a script is open
local ScriptEditorService = game:GetService("ScriptEditorService")
local function getFirstOpenDocument()
local documents = ScriptEditorService:GetScriptDocuments()
for _, document in documents do
if not document:IsCommandBar() then
return document
end
end
return nil
end
local scriptDocument = getFirstOpenDocument()
if scriptDocument then
scriptDocument.SelectionChanged:Connect(function(positionLine, positionCharacter, anchorLine, anchorCharacter)
print(`Selected: Line {positionLine}, Char {positionCharacter}`)
print(`Anchor: Line {anchorLine}, Char {anchorCharacter}`)
local lineText = scriptDocument:GetLine(positionLine)
print(`Selected line text: {lineText}`)
end)
else
print("No scripts open")
endViewportChanged
當編輯器中顯示的行號碼發生變更時，發出火焰。詳情請見 ScriptDocument.GetViewport 。
參數
範例程式碼
Demonstrates using ScriptDocument.ViewportChanged to print the start and end line of the script's viewport when it changes.
To run:
- Ensure Output view is open
- Run the below code in the Command Bar
- Scroll up and down in the opened Script window
Connecting to ScriptDocument.ViewportChanged
--!nocheck
--[[
To run:
1. Ensure Output view is open
2. Run the below code in the Command Bar
3. Scroll up and down in the opened Script window
Print statements from the ViewportChanged event will appear in the Output
]]
local Workspace = game:GetService("Workspace")
local ScriptEditorService = game:GetService("ScriptEditorService")
-- Create text that spans many lines
local dummyText = string.rep("-- Dummy Text\n", 60)
-- Create a script containing the dummy text and open it
local otherScript = Instance.new("Script")
otherScript.Source = dummyText
otherScript.Parent = Workspace
local success, err = ScriptEditorService:OpenScriptDocumentAsync(otherScript)
if not success then
warn(`Failed to open script because: {err}`)
return
end
-- Get a reference to the opened script
local scriptDocument = ScriptEditorService:FindScriptDocument(otherScript)
local function onViewportChanged(startLine: number, endLine: number)
print(`Script Viewport Changed - startLine: {startLine}, endLine: {endLine}`)
end
-- Connect the ViewportChanged event to the function above that prints the start and end line of the updated viewport
scriptDocument.ViewportChanged:Connect(onViewportChanged)