工作室赋予您创建自定义 小部件 的能力,并将其用作工具和扩展。这些小部件在工作室中表现为自定义窗口/面板,您可以将它们停靠在界面内或作为单独的窗口浮动。
创建小部件用户界面
所有工作室小部件都始于 DockWidgetPluginGui 对象,您可以用 GuiObjects 填充它们,例如文本标签和按钮。要创建一个空的小部件 GUI,请调用 CreateDockWidgetPluginGui() 函数,传入一个 ID 和一个 DockWidgetPluginGuiInfo 对象。
请注意,DockWidgetPluginGuiInfo.new() 构造函数期望其参数以 特定顺序 传入,如下所示:
| # | 属性 | 类型 | 描述 |
|---|---|---|---|
| 1 | Enum.InitialDockState | 枚举 | Enum.InitialDockState 枚举之一。 |
| 2 | InitialEnabled | 布尔值 | 小部件 GUI 的初始启用(可见)状态。 |
| 3 | InitialEnabledShouldOverrideRestore | 布尔值 | 如果为 true,InitialEnabled 的值将覆盖之前保存的启用状态。 |
| 4 | FloatingXSize | 整数 | 当 InitialDockState 设置为 Enum.InitialDockState.Float 时,GUI 的初始宽度。 |
| 5 | FloatingYSize | 整数 | 当 InitialDockState 设置为 Enum.InitialDockState.Float 时,GUI 的初始高度。 |
| 6 | MinWidth | 整数 | GUI 的最小宽度,具有一些平台特定的变化。 |
| 7 | MinHeight | 整数 | 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 事件,例如 MouseEnter 和 MouseLeave。以下代码演示了如何将函数连接到 testButton 的 MouseEnter 和 MouseLeave 事件以更改鼠标光标:
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 元素如 TextBox 和 TextButton 在工作室小部件中正常工作,您可以像在 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 元素(通常是小部件中的 TextButton 或 ImageButton)上的鼠标按钮时调用 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 – 当用户的光标离开窗口时触发。这对于隐藏“放在这里!”消息很有用。















