كاشفات سحب واجهة المستخدم | المراجع

تسهل وتساعد مثيل UIDragDetector التفاعل مع عناصر واجهة المستخدم ثنائية الأبعاد في اللعبة، مثل المنزلقات والمراوح والمزيد. تشمل الميزات الرئيسية:

ضع UIDragDetector تحت أي مثيل GuiObject لجعله قابلاً للسحب عبر جميع مدخلات المستخدم دون الحاجة إلى سطر واحد من التعليمات البرمجية.
اختر من بين عدة خيارات DragStyle، وحدد كيف يستجيب الكائن للحركة عبر ResponseStyle، وطبق حدود المحاور أو قيود الحركة أو حدود السحب إذا رغبت في ذلك.
يمكن للبرامج النصية الاستجابة لتManipulation الكائنات المسحوبة لدفع استجابات منطقية، مثل ضبط الإعدادات.
تعمل UIDragDetectors في وضع التحرير والتشغيل في الاستوديو طالما أنك لا تستخدم أدوات التحديد أو الحركة أو التحجيم أو الدوران، ولا بعض الإضافات أو أدوات محرر واجهة المستخدم في الاستوديو.

للكاشفات السحب التي تتلاعب بالأجسام ثلاثية الأبعاد في اللعبة، مثل فتح الأبواب والأدراج أو سحب جزء حوله، انظر كاشفات السحب ثلاثية الأبعاد.

اجعل عناصر واجهة المستخدم قابلة للسحب

لجعل أي مثيل GuiObject قابلاً للسحب، ما عليك سوى إضافة UIDragDetector كنسل مباشر.

في نافذة المستكشف، مرر فوق مثيل GuiObject وانقر على زر ⊕ . ستظهر قائمة سياقية.
من القائمة، أدخل UIDragDetector.
بشكل افتراضي، سيكون الكائن الآن قابلاً للسحب في واجهة LayerCollector.

تذكر أن UIDragDetectors تعمل فقط في الاستوديو إذا كنت لا تستخدم أدوات التحديد أو الحركة أو التحجيم أو الدوران، ولا بعض الإضافات أو أدوات محرر واجهة المستخدم في الاستوديو.

تخصيص كاشفات سحب واجهة المستخدم

نمط السحب

تقوم UIDragDetectors بربط حركة المؤشر لحساب الحركة ثنائية الأبعاد المقترحة و/أو الدوران. من خلال خاصية DragStyle، يمكنك الاختيار من بين خرائط مختلفة تناسب احتياجاتك. على سبيل المثال، ينتج Enum.UIDragDetectorDragStyle.TranslatePlane ترجمة في المستوى ثنائي الأبعاد لـ LayerCollector، بينما ينتج Enum.UIDragDetectorDragStyle.Rotate عادةً دورانًا بدلاً من الترجمة.

الإعداد	الوصف
TranslateLine	حركة أحادية البعد على طول DragAxis للكاشف.
TranslatePlane	حركة ثنائية الأبعاد في مستوى LayerCollector.
Rotate	بشكل افتراضي، الدوران حول المركز المطلق لمثيل GuiObject الأب للكاشف. إذا تم تعيين ReferenceUIInstance، يحدث الدوران حول المركز المطلق لتلك المثيل.
Scriptable	يحسب الحركة المرغوبة عبر دالة مخصصة مقدمة من خلال SetDragStyleFunction().

اتجاه السحب

بشكل افتراضي، تتطابق الحركة ثنائية الأبعاد وDragStyle المرتبطة مع مساحة LayerCollector السلف. ومع ذلك، قد ترغب في تغيير ReferenceUIInstance أو DragAxis عند بناء مكونات واجهة مستخدم مختلفة.

الإعداد	الوصف	افتراضي
ReferenceUIInstance	مثيل GuiObject الذي تكون مساحته المحلية ومركزه المطلق هو مساحة المرجع والأصل للكاشف. يؤثر تعيين هذا المرجع على خصائص مثل DragUDim2 وDragRotation وسلوك DragAxis.	nil
DragAxis	قيمة Vector2 التي تحدد محور الحركة للكائن المسحوب عندما يتم تعيين DragStyle إلى Enum.UIDragDetectorDragStyle.TranslateLine. يتم تعريف المحور في المساحة المحلية لـ UIDragDetector ما لم يتم تعريف ReferenceUIInstance، وفي هذه الحالة يتم تعريف المحور في المساحة المحلية لتلك المثيل.	(1, 0)

الاستجابة للحركة

تحدد خاصية UIDragDetector.ResponseStyle كيفية تغيير قيمة موضع الكائن بواسطة الحركة المقترحة. تتيح أنماط الاستجابة المخصصة لك استخدام قيم UIDragDetector.DragUDim2 وUIDragDetector.DragRotation الناتجة كما تشاء، دون أن يقوم والد الكاشف بتنفيذ الحركة المقترحة.

الإعداد	الوصف
Offset	التحرك بواسطة قيم Offset لموضع GuiObject الأب للكاشف. هذا هو الإعداد الافتراضي.
Scale	التحرك بواسطة قيم Scale لموضع GuiObject الأب للكاشف.
CustomOffset	لن تتحرك عنصر واجهة المستخدم على الإطلاق، ولكن ستظل قيم Offset الخاصة بـ DragUDim2 محدثة وستظل أحداث الكاشف تعمل، مما يتيح لك الاستجابة لتManipulation السحب كما تريد.
CustomScale	لن تتحرك عنصر واجهة المستخدم على الإطلاق، ولكن ستظل قيم Scale الخاصة بـ DragUDim2 محدثة وستظل أحداث الكاشف تعمل، مما يتيح لك الاستجابة لتManipulation السحب كما تريد.

قيود الترجمة والدوران

بشكل افتراضي، لا توجد قيود على الحركة ثنائية الأبعاد وراء القيود الكامنة في DragStyle. يمكن إعلان حدود لكل من الترجمة والدوران الدنيا والقصوى باستخدام الخصائص التالية إذا رغبت في ذلك. بالإضافة إلى ذلك، يمكنك تحديد كيفية تقييد الكائن المسحوب ضمن حدود GuiObject محدد مثل Frame.

الخصائص	الوصف	افتراضي
MinDragTranslation MaxDragTranslation	قيود على ترجمة السحب في كل بعد، محددة بواسطة قيمة UDim2. إذا كانت MaxDragTranslation أكبر من MinDragTranslation، سيتم تقليم الترجمة ضمن تلك النطاق.	{0, 0}, {0, 0}
MinDragAngle MaxDragAngle	ذات صلة فقط إذا تم تعيين DragStyle إلى Enum.UIDragDetectorDragStyle.Rotate، أو إذا كانت الدوال المحددة من خلال SetDragStyleFunction() أو AddConstraintFunction() تحدد قيمة دوران. إذا كانت MaxDragAngle أكبر من MinDragAngle، سيتم تقليم الدوران ضمن تلك النطاق.	0
BoundingBehavior	تحدد سلوك حدود مثيل UIDragDetector عندما يتم تعيين BoundingUI. يؤدي تعيين هذا إلى EntireObject إلى تقييد واجهة المستخدم المسحوبة بالكامل ضمن BoundingUI، بينما يؤدي تعيينه إلى HitPoint إلى تقييد واجهة المستخدم المسحوبة فقط بواسطة نقطة الضرب/القبض الدقيقة وموقعها بعد الترجمة/الدوران. كراحة، فإن الافتراضي لـ Automatic يحاكي سلوك EntireObject لكائن واجهة المستخدم الذي يتم احتواؤه بالكامل بواسطة BoundingUI، أو HitPoint لكائن واجهة المستخدم الذي يكون جزئيًا خارج BoundingUI.	Automatic

تعديلات السرعة

من خلال SelectionModeDragSpeed وSelectionModeRotateSpeed، يمكنك ضبط السرعات القصوى للسحب/الدوران للكاشف. علاوة على ذلك، من خلال UIDragSpeedAxisMapping، يمكنك ضبط سرعات السحب في أبعاد X/Y، بناءً على SelectionModeDragSpeed.

الخاصية	الوصف
SelectionModeDragSpeed	تحدد السرعة القصوى للسحب للترجمة كمزيج من Scale وOffset لأقرب سلف ScreenGui أو SurfaceGui الذي ينتمي إليه UIDragDetector.
SelectionModeRotateSpeed	تحدد الزاوية القصوى في الثانية التي يمكن أن يدور بها UIDragDetector.
UIDragSpeedAxisMapping	تحدد سرعات السحب في أبعاد X/Y، بناءً على SelectionModeDragSpeed. الافتراضي هو XY، مما يعني أن سرعات المحورين X وY تعتمد على قيم Scale وOffset الخاصة بـ X وY على التوالي. البدائل هي XX وYY، مما يعني أن سرعات المحورين X وY تعتمد على المحور X (XX) أو المحور Y (YY) لـ Scale، بينما تظل قيم Offset تنطبق على محاورها الخاصة. على سبيل المثال، إذا كان أقرب سلف ScreenGui بحجم 800×600 وSelectionModeDragSpeed هو {0.1, 10}, {0.1, 20}، فإن تعيين XX ينتج عنه سرعة سحب X/Y قدرها 80+10/80+20، بينما ينتج YY 60+10/60+20 (لاحظ أن قيم Offset تظل كما هي في كلا الحالتين).

استجابات البرنامج النصي للنقر والسحب

من خلال إشارات الأحداث وتغييرات الخصائص وScriptable نمط السحب والدوال المخصصة، يمكن للبرامج النصية الاستجابة لتManipulation عناصر واجهة المستخدم المسحوبة لدفع إعدادات مختلفة أو اتخاذ قرارات منطقية، مثل المنزلقات التي تضبط حجم الموسيقى وتأثير الصوت بشكل منفصل.

للاستجابات التي يبدأها المستخدم مثل إشارات الأحداث ونمط السحب المبرمج، ستحتاج عادةً إلى وضع كود البرنامج النصي الخاص بك داخل LocalScript، أو Script مع تعيين RunContext إلى Client.

إشارات الأحداث

من خلال إشارات الأحداث التالية، يمكنك اكتشاف متى يبدأ المستخدم في سحب كائن، ويستمر، وينتهي.

الحدث	الوصف
DragStart	يتم تشغيله عندما يبدأ المستخدم في سحب الكائن.
DragContinue	يتم تشغيله عندما يستمر المستخدم في سحب الكائن بعد بدء DragStart.
DragEnd	يتم تشغيله عندما يتوقف المستخدم عن سحب الكائن.

يحدد المنزلق التالي حاويته كـ BoundingUI لتقييد حركته ضمن منطقة الحاوية، مما يسمح بنمط السحب القائم على المقياس TranslateLine ليكون محدودًا بعرض الحاوية بالكامل دون الحاجة إلى برمجة إضافية.

لاختبار هذا المثال، قم بتنزيل ملف TransparencySlider.rbxm، انقر بزر الماوس الأيمن على StarterGui في نافذة المستكشف، اختر إدراج ⟩ استيراد نموذج Roblox، واختر الملف الذي تم تنزيله.

UIDragDetector - تغيير شفافية إشارة الحدث

-- الهيكل هو SliderContainer ⟩ Handle ⟩ UIDragDetector ⟩ (هذا البرنامج النصي)
local sliderContainer = script.Parent.Parent.Parent
local handle = sliderContainer:FindFirstChild("Handle")
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- تعيين السحب بواسطة المقياس
uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.TranslateLine  -- يقيّد السحب إلى خط
uiDragDetector.BoundingUI = sliderContainer

-- تعيين الشفافية الأولية للحاوية إلى قيمة مقياس X للمقبض
sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale

-- توسيع حدود المقبض للإشارة إلى بدء القبض
uiDragDetector.DragStart:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 6
end)

-- تغيير الشفافية بناءً على مقدار السحب في المقياس
uiDragDetector.DragContinue:Connect(function(inputPosition)
	sliderContainer.BackgroundTransparency = 1 - handle.Position.X.Scale
end)

-- إعادة حدود المقبض للإشارة إلى انتهاء القبض
uiDragDetector.DragEnd:Connect(function(inputPosition)
	handle:FindFirstChildWhichIsA("UIStroke").Thickness = 4
end)

تغييرات الموضع والدوران

بالإضافة إلى إشارات الأحداث، يمكنك مراقبة التغييرات في DragUDim2 و/أو DragRotation للكاشف مباشرة.

يمتلك الكاشف التالي نمط DragStyle مضبوطًا على Rotate، مما يسمح للمستخدمين بسحب المقبض حول حلقة تدوير اللون، بينما يتم اكتشاف التغييرات في دوران السحب من خلال Instance:GetPropertyChangedSignal().

لاختبار هذا المثال، قم بتنزيل ملف HueRotator.rbxm، انقر بزر الماوس الأيمن على StarterGui في نافذة المستكشف، اختر إدراج ⟩ استيراد نموذج Roblox، واختر الملف الذي تم تنزيله.

UIDragDetector - تغيير دوران السحب

local handle = script.Parent.Parent  -- عنصر واجهة المستخدم للسحب
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.DragStyle = Enum.UIDragDetectorDragStyle.Rotate  -- تعيين نمط السحب للدوران

local function changeHue()
	local currAngle = (math.fmod(handle.Rotation, 360)) / 360
	if currAngle < 0 then
		currAngle += 1
	end
	handle.BackgroundColor3 = Color3.fromHSV(currAngle, 1, 1)
end

-- تعيين اللون الأولي لدوران المقبض
changeHue()

-- ربط الدالة بـ GetPropertyChangedSignal() لدوران السحب للكاشف
uiDragDetector:GetPropertyChangedSignal("DragRotation"):Connect(changeHue)

نمط السحب المبرمج

إذا قمت بتعيين UIDragDetector.DragStyle للكاشف إلى Enum.UIDragDetectorDragStyle.Scriptable، يمكنك تقديم دالتك الخاصة التي تأخذ في الاعتبار Vector2 لموضع الإدخال وتعيد UDim2 (الموضع) وعددًا عشريًا (الدوران). سيقوم الكاشف بتحديث الكائن إلى الموضع/الدوران المحسوب بناءً على القيم المعادة، وخصائص DragSpace وDragRelativity.

بشكل افتراضي، ستكون UDim2 المعادة والعشري هو الموضع/الدوران النهائي المرغوب فيه في المساحة المحلية لوالد الكاشف. ستظل القيود الحالية على الترجمة/الدوران سارية، وكذلك القيود المفروضة بواسطة مثيل BoundingUI المحدد.

المثال التالي يسحب عنصر واجهة مستخدم يتبع موجة جيبية محسوبة بواسطة التغيير في إحداثيات X المدخلة. لاحظ أن DragSpace للكاشف مضبوط على Enum.UIDragDetectorDragSpace.Relative.

UIDragDetector - السحب متبعًا موجة جيبية

local frame = script.Parent  -- عنصر واجهة المستخدم للسحب
local uiDragDetector = frame:FindFirstChildWhichIsA("UIDragDetector")

local initialXValue = 0
local maxHeightChange = 200
local pixelsPerRadian = 75  -- قلل هذه القيمة لزيادة التردد

uiDragDetector.DragStart:Connect(function(inputPosition)
	initialXValue = inputPosition.X
end)

local function computeSinWaveCoordinate(inputPosition)
	local deltaX = inputPosition.X - initialXValue
	-- دلتا Y سلبية بحيث تذهب "للأعلى" على الشاشة مع تغيير Y إيجابي
	local deltaY = -math.sin(deltaX / pixelsPerRadian) * maxHeightChange
	return UDim2.fromOffset(deltaX, deltaY)
end

uiDragDetector:SetDragStyleFunction(computeSinWaveCoordinate)

دالة القيود المخصصة

لا تحتوي UIDragDetectors على قواعد حركة مدمجة حول الشبكات والتثبيت، ولكن يمكنك تسجيل دوال قيود مخصصة لتحرير UIDragDetector.DragUDim2 وUIDragDetector.DragRotation قبل تطبيقها. على سبيل المثال، يمكنك الحفاظ على الحركة على شبكة عن طريق تقريب المواضع إلى زيادات محددة، أو تحديد مناطق الحركة المسموح بها. لاحظ أن هذا يتم تطبيقه قبل أي قيود على الترجمة/الدوران الحالية.

يمكن تسجيل دوال قيود متعددة وسيتم استدعاؤها بترتيب قيمة الأولوية الخاصة بها عند التسجيل، من الأقل إلى الأعلى.

المثال التالي يستخدم دالة قيود تقيد السحب المسطح إلى شبكة X/Y بناءً على عدد الصفوف والأعمدة. لاحظ أن ResponseStyle للكاشف مضبوط على Enum.UIDragDetectorResponseStyle.Scale وBoundingUI مضبوط على حاوية الشبكة.

لاختبار هذا المثال، قم بتنزيل ملف GridDrag.rbxm، انقر بزر الماوس الأيمن على StarterGui في نافذة المستكشف، اختر إدراج ⟩ استيراد نموذج Roblox، واختر الملف الذي تم تنزيله.

UIDragDetector - السحب في الشبكة، التثبيت على البلاط

-- الهيكل هو GridContainer ⟩ Handle ⟩ UIDragDetector ⟩ (هذا البرنامج النصي)
local gridContainer = script.Parent.Parent.Parent
local handle = gridContainer:FindFirstChild("Handle")  -- عنصر واجهة المستخدم للسحب
local uiDragDetector = handle:FindFirstChildWhichIsA("UIDragDetector")

uiDragDetector.ResponseStyle = Enum.UIDragDetectorResponseStyle.Scale  -- تعيين السحب بواسطة المقياس
uiDragDetector.DragRelativity = Enum.UIDragDetectorDragRelativity.Relative
uiDragDetector.BoundingUI = gridContainer

local NUM_COLUMNS = 10
local NUM_ROWS = 5

local xScaleIncrement = 1 / NUM_COLUMNS
local yScaleIncrement = 1 / NUM_ROWS
local initialParentPosition = uiDragDetector.Parent.Position

uiDragDetector.DragStart:Connect(function()
	initialParentPosition = uiDragDetector.Parent.Position
end)

local function dragToGridOnly(proposedPosition, proposedRotation)
	local griddedXScale = math.round(proposedPosition.X.Scale / xScaleIncrement) * xScaleIncrement
	local griddedYScale = math.round(proposedPosition.Y.Scale / yScaleIncrement) * yScaleIncrement

	return UDim2.fromScale(griddedXScale, griddedYScale), proposedRotation
end

uiDragDetector:AddConstraintFunction(1, dragToGridOnly)