一个 ScriptDocument 实例是 Studio 脚本编辑器的文件的一个代理。它与在编辑器中打开的 LuaSourceContainer 不同，它代表打开文件的暂时状态，其代表格式比运行代码更适合阅读和编辑。特别是，
脚本编辑器本身存在并且在不同线程上改变任何 DataModel ，因此 ScriptDocument 复制了打开脚本编辑器，但它不是打开编辑器。 因为重复，有时会在编辑器中的文本与更新
Class.ScriptDocument 的存在表示脚本编辑器中的文档已打开。所有 ScriptDocument 实例的父级都有 ScriptEditorService 作为其父级。每个实例都遵守以下编码约定：
- Class.ScriptDocument 中的所有文本都已编码为 UTF-8。
- 所有线索索引都是 1 索。
- 所有角色索引都是 1 索引，所以 UTF-8 字符不是图形，所以从 TextBox.CursorPosition 的警告适用：许多 UTF-8 字符超过了一个字节。
- 所有范围都包含其起始位置和其结束位置，因此开始 == 结束会导致一个空范围。
Class.ScriptDocument 的所有 API 都位于 插件 级别的安全。
概要
方法
返回指定行的文本。当没有参数提供时，返回当前 cursor 位置的行。
返回文档中的行数。
如果存在，返回基础 LuaSourceContainer 实例，否则 nil 。
如果没有选择，则会获取编辑器中选择的文本或一个空字符串。
以脚本编辑器的最后一个选择的格式返回：CursorLine, CursorChar, AnchorLine, AnchorChar。 如果脚本编辑器没有选择，CursorLine == AnchorLine 和 CursorChar == AnchorChar 。
获取鼠标位置和锚固定的大小。如果编辑器没有选择，它们是相同的值。
获取鼠标位置和锚定位置的较小锚固。如果编辑器没有选择，它们是相同的值。
- GetText(startLine : number?,startCharacter : number?,endLine : number?,endCharacter : number?):string
从打开的编辑器中返回文本。
返回编辑器更改中显示的行号。
返回编辑器是否选择了任何文本。
如果 ScriptDocument 代表命令栏，返回 true。
与此文件关联的编辑器关闭请求。在编辑器回应请求之前，返回当前线程。
- EditTextAsync(newText : string,startLine : number,startCharacter : number,endLine : number,endCharacter : number):Tuple
将文本替换在指定范围内从( startLine , startColumn )到( endLine , 1> endColumn1> )新的文本。
- 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
返回指定行的文本。当没有参数提供时，返回当前 cursor 位置的行。
参数
默认值："nil"
返回
代码示例
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")
end
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")
end
GetScript
如果存在，返回基础 LuaSourceContainer 实例，否则 nil 。
返回
代码示例
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")
end
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")
end
GetSelection
以脚本编辑器的最后一个选择的格式返回：CursorLine, CursorChar, AnchorLine, AnchorChar。 如果脚本编辑器没有选择，CursorLine == AnchorLine 和 CursorChar == AnchorChar 。
返回
鼠标线、鼠标字、锚线、锚字。
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")
end
GetSelectionStart
获取鼠标位置和锚定位置的较小锚固。如果编辑器没有选择，它们是相同的值。
返回
代码示例
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")
end
GetText
从打开编辑器中返回文本。必须使用 0、2 或 4 个参数：
- 如果使用 0 个参数，将返回打开编辑器的全部内容。
- 如果调用 2 个参数，将文档的文字从 ( startLine 开始。 如果调用 2 个参数，将文档的文字从 ( startColumn 开始。
- 如果使用 4 个参数，将文档的文字从 ( startLine 开始，startColumn 结束，并且在 ( endLine 结束后从 ( 1> endColumn1> 结束。
参数
默认值："nil"
默认值："nil"
默认值："nil"
默认值："nil"
返回
代码示例
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")
end
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")
end
HasSelectedText
返回编辑器是否选择了任何文本。
返回
代码示例
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")
end
IsCommandBar
如果 ScriptDocument 代表命令栏，则返回 true。命令栏在此 API 中有特殊规则和限制：
- Studio 在运行插件之前创建命令栏，因此它不会总是发射打开的事件，尽管它会关闭并重新打开，当 Studio 切换到数据模型之间。
- 为了安全原因，您不能使用 EditTextAsync 编辑命令栏。
返回
代码示例
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
end
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")
end
EditTextAsync
将文本在指定范围内从 ( startLine , startColumn ) 到 ( endLine , 1> endColumn1> ) 用 <
如果函数成功，它将返回 ( true，nil )。
函数抛出一个错误如果：
- 范围无效。
- 范围将切割一个不能用的角色，例如仅替换部分不能用角色的字节。
- newText 本身包含无效的 UTF-8。
如果函数失败，它将返回 (false, strin字符串)。 string 是问题的描述。最常见的失败类型是版本不兼容。当您尝试在 EditTextAsync 中调用时，您尝试调用 ScriptDocument 与内容编辑器的版本不兼容。如果发生此情况，您可以重试编辑。
参数
返回
ForceSetSelectionAsync
向编辑器要求将其鼠标选择设置为参数值。 两个锚参数必须通过，或不。 如果没有通过，那么它们将默认为相应的鼠标选择值。 编辑器可能会拒绝更新其鼠标，如果文档的文本内容发生了变更。
参数
默认值："nil"
默认值："nil"
返回
代码示例
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")
end
RequestSetSelectionAsync
向编辑器要求将其鼠标选择设置为参数值。 两个锚参数都必须通过，或者不通过。 如果没有通过，那么它们将默认为与相应的鼠标选择参数相同。 编辑器可能会拒绝更新其鼠标，如果文档的文本内容已更改，或者鼠标已移动到更新后。 返回 (true, 字符串il) 如果编
参数
默认值："nil"
默认值："nil"
返回
代码示例
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()
--!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")
end
ViewportChanged
当显示行数在编辑器中发生变更时触发。请参阅 ScriptDocument.GetViewport 了解详细信息。
参数
代码示例
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)