工作室小部件

*此内容使用人工智能(Beta)翻译,可能包含错误。若要查看英文页面,请点按 此处

工作室赋予您创建自定义 小部件 的能力,并将其用作工具和扩展。这些小部件在工作室中表现为自定义窗口/面板,您可以将它们停靠在界面内或作为单独的窗口浮动。

创建小部件用户界面

所有工作室小部件都始于 DockWidgetPluginGui 对象,您可以用 GuiObjects 填充它们,例如文本标签和按钮。要创建一个空的小部件 GUI,请调用 CreateDockWidgetPluginGui() 函数,传入一个 ID 和一个 DockWidgetPluginGuiInfo 对象。

请注意,DockWidgetPluginGuiInfo.new() 构造函数期望其参数以 特定顺序 传入,如下所示:

#属性类型描述
1Enum.InitialDockState枚举Enum.InitialDockState 枚举之一。
2InitialEnabled布尔值小部件 GUI 的初始启用(可见)状态。
3InitialEnabledShouldOverrideRestore布尔值如果为 true,InitialEnabled 的值将覆盖之前保存的启用状态。
4FloatingXSize整数InitialDockState 设置为 Enum.InitialDockState.Float 时,GUI 的初始宽度。
5FloatingYSize整数InitialDockState 设置为 Enum.InitialDockState.Float 时,GUI 的初始高度。
6MinWidth整数GUI 的最小宽度,具有一些平台特定的变化。
7MinHeight整数GUI 的最小高度,具有一些平台特定的变化。
-- 创建新的 "DockWidgetPluginGuiInfo" 对象
local widgetInfo = DockWidgetPluginGuiInfo.new(
Enum.InitialDockState.Float, -- 小部件将在浮动面板中初始化
true, -- 小部件将最初启用
false, -- 不覆盖之前的启用状态
200, -- 浮动窗口的默认宽度
300, -- 浮动窗口的默认高度
150, -- 浮动窗口的最小宽度
150 -- 浮动窗口的最小高度
)
-- 创建新的小部件 GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "测试小部件" -- 可选的小部件标题

自定义小部件 UI

创建小部件后,您可以使用 GuiObjects 自定义其用户界面,例如信息性 TextLabels 或交互式 ImageButtons。例如,以下代码向 GUI 窗口添加一个基本的 TextButton

-- 创建新的小部件 GUI
local testWidget = plugin:CreateDockWidgetPluginGui("TestWidget", widgetInfo)
testWidget.Title = "测试小部件" -- 可选的小部件标题
local testButton = Instance.new("TextButton")
testButton.BorderSizePixel = 0
testButton.TextSize = 20
testButton.TextColor3 = Color3.new(1,0.2,0.4)
testButton.AnchorPoint = Vector2.new(0.5,0.5)
testButton.Size = UDim2.new(1,0,1,0)
testButton.Position = UDim2.new(0.5,0,0.5,0)
testButton.SizeConstraint = Enum.SizeConstraint.RelativeYY
testButton.Text = "点击我"
testButton.Parent = testWidget

更改工作室颜色主题

有效的工作室小部件理想情况下应与工作室 主题 设置相匹配,并在主题更改时动态调整。例如,如果开发者使用深色主题,则小部件的背景颜色、图像和文本标签应与工作室的本机主题颜色相得益彰。

以下代码添加了一个 syncGuiColors() 函数,该函数最初与要同步的 GUI 对象表一起调用。在函数内部,嵌套的 setColors() 函数循环遍历对象,并使用 GetColor()Enum.StudioStyleGuideColor 枚举同步它们的特定方面。此 setColors() 函数立即运行以同步工作室主题,然后连接到 ThemeChanged 事件以检测未来的主题更改。

testButton.Parent = testWidget
local function syncGuiColors(objects)
local function setColors()
for _, guiObject in objects do
-- 同步背景颜色
guiObject.BackgroundColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainBackground)
-- 同步文本颜色
guiObject.TextColor3 = settings().Studio.Theme:GetColor(Enum.StudioStyleGuideColor.MainText)
end
end
-- 运行 'setColors()' 函数以最初同步颜色
setColors()
-- 将 'ThemeChanged' 事件连接到 'setColors()' 函数
settings().Studio.ThemeChanged:Connect(setColors)
end
-- 运行 'syncGuiColors()' 函数以同步提供对象的颜色
syncGuiColors({testButton})

自定义鼠标光标

为了改善与小部件元素的预期交互,您可以将系统特定的 鼠标光标 设置为 GUI 事件,例如 MouseEnterMouseLeave。以下代码演示了如何将函数连接到 testButtonMouseEnterMouseLeave 事件以更改鼠标光标:

local function setCursor(cursorAsset)
plugin:GetMouse().Icon = cursorAsset
end
testButton.MouseEnter:Connect(function()
setCursor("rbxasset://SystemCursors/PointingHand")
end)
testButton.MouseLeave:Connect(function()
setCursor("")
end)

参考以下表格以获取鼠标光标及其潜在用例的列表:

鼠标光标图标资产用例
rbxasset://SystemCursors/Arrow默认点击和选择。
rbxasset://SystemCursors/PointingHand悬停在活动链接/按钮上。
rbxasset://SystemCursors/OpenHand悬停在可拖动项上。
rbxasset://SystemCursors/ClosedHand拖动项目。
rbxasset://SystemCursors/IBeam悬停在文本字段中。
rbxasset://SystemCursors/SizeNS悬停在垂直调整大小手柄上。
rbxasset://SystemCursors/SizeEW悬停在水平调整大小手柄上。
rbxasset://SystemCursors/SizeNESW悬停在角落调整大小手柄上。
rbxasset://SystemCursors/SizeNWSE悬停在角落调整大小手柄上。
rbxasset://SystemCursors/SizeAll悬停在多方向调整大小手柄上。
rbxasset://SystemCursors/SplitNS悬停在垂直“分割”手柄上。
rbxasset://SystemCursors/SplitEW悬停在水平“分割”手柄上。
rbxasset://SystemCursors/Forbidden悬停在锁定/禁止的项目上。
rbxasset://SystemCursors/Wait指示某个操作正在进行中。
rbxasset://SystemCursors/Busy指示系统繁忙。
rbxasset://SystemCursors/Cross悬停在精确选择区域上。

收集用户输入

UI 元素如 TextBoxTextButton 在工作室小部件中正常工作,您可以像在 Roblox 上一样构建界面。然而,UserInputService 不起作用,因为这些服务期望主游戏窗口处于焦点状态。

一种通用输入事件的解决方法是创建一个透明的 Frame 并将其覆盖在整个屏幕上。以下代码示例创建一个框架,当用户单击框架时,GuiObject.InputBegan 事件捕获框架上的键盘输入,直到用户单击其他地方:

local frame = Instance.new("Frame")
frame.BackgroundTransparency = 1 -- 隐藏框架
frame.Size = UDim2.new(1, 0, 1, 0) -- 覆盖屏幕
frame.Position = UDim2.new(0, 0, 0, 0)
frame.Parent = testWidget
local function onInputBegan(inputObject)
-- 在这里处理输入对象,例如检测按键
end
frame.InputBegan:Connect(onInputBegan)

拖放交互

使用拖放交互来改善小部件的数据流是一种简单的方法。要创建这种交互,您必须定义要拖动的元素,启动拖动,创建放置目标,并处理放置操作。

创建拖动源

您可以通过在用户按下某个 UI 元素(通常是小部件中的 TextButtonImageButton)上的鼠标按钮时调用 Plugin:StartDrag() 来开始拖动操作。以下代码示例创建一个带有文本按钮的单窗口小部件。

-- 首先创建小部件
local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 300, 200)
local dragSourceWidget = plugin:CreateDockWidgetPluginGui("拖动源", widgetInfo)
dragSourceWidget.Title = "拖动源"
-- 创建一个将启动拖动的 TextButton
local dragButton = Instance.new("TextButton")
dragButton.Size = UDim2.new(1, 0, 1, 0)
dragButton.Text = "拖动我!"
dragButton.Parent = dragSourceWidget

启动拖动

当用户单击 TextButton 时,您可以通过 MouseButton1Down() 事件启动拖动,该事件在用户按下鼠标按钮时立即触发。

在连接的函数中,确定要拖动的数据。数据的 类型 应在 MimeType 键中反映,拖动的 内容 应在 Data 键中反映,发送者 应在 Sender 键中描述自己。有关更多详细信息,请参见 Plugin:StartDrag() 页面。

local function onButton1Down()
local dragInfo = {
Data = "你好,世界", -- 正在拖动的数据
MimeType = "text/plain", -- 描述数据的 MIME 类型
Sender = "某个拖动源", -- 描述数据的来源
MouseIcon = "", -- 用于光标的图像内容
DragIcon = "", -- 在拖动期间在光标下渲染的图像内容
HotSpot = Vector2.zero -- 在 DragIcon 上居中光标的位置
}
plugin:StartDrag(dragInfo)
end
dragButton.MouseButton1Down:Connect(onButton1Down)

创建放置目标

当用户在拖动期间释放鼠标时,PluginGui.PluginDragDropped 事件会触发。在这种情况下,您需要定义一个 放置目标,例如带有 TextLabel 的第二个小部件,以检测放置。

local dragTargetWidget = plugin:CreateDockWidgetPluginGui("放置目标", widgetInfo)
dragTargetWidget.Title = "放置目标"
-- 这个 TextLabel 将显示被放置的内容
local textLabel = Instance.new("TextLabel")
textLabel.Size = UDim2.new(1, 0, 1, 0)
textLabel.Text = "放在这里..."
textLabel.Parent = dragTargetWidget

处理放置操作

创建放置目标后,在放置目标小部件上连接 PluginGui.PluginDragDropped 事件:

local function onDragDrop(dragData)
print("PluginDragDropped")
if dragData.MimeType == "text/plain" then
textLabel.Text = dragData.Data
else
textLabel.Text = dragData.MimeType
end
end
dragTargetWidget.PluginDragDropped:Connect(onDragDrop)

在拖动仍在进行时,当用户将鼠标移动到小部件上时,这三个事件会触发:

  • PluginDragEntered – 当用户将鼠标悬停在窗口上时触发
  • PluginDragMoved – 当用户将鼠标移动到窗口上时重复触发。这对于显示“放在这里!”消息很有用。
  • PluginDragLeft – 当用户的光标离开窗口时触发。这对于隐藏“放在这里!”消息很有用。
©2026 Roblox Corporation、Roblox、Roblox 标志及 Powering Imagination 是我们在美国及其他国家或地区的注册与未注册商标。