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

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

ضع UIDragDetector تحت أي مثيل من GuiObject لجعله قابلاً للسحب عبر جميع مدخلات المستخدم دون سطر واحد من التعليمات البرمجية.
اختر من بين العديد من خيارات DragStyle، وحدد كيفية استجابة الكائن للحركة عبر ResponseStyle، وطبق حدود المحاور أو الحركة، أو قيود السحب إذا رغبت في ذلك.
يمكن للبرامج النصية الاستجابة لتلاعب الكائنات المسحوبة لتوجيه الاستجابات المنطقية، مثل ضبط الإعدادات.
تعمل 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 ستظل محدثة وستظل أحداث الموصل تعمل، مما يتيح لك الاستجابة لتلاعب السحب بالطريقة التي تريدها.
CustomScale	لن يتحرك عنصر واجهة المستخدم على الإطلاق، لكن قيم Scale للموصل DragUDim2 ستظل محدثة وستظل أحداث الموصل تعمل، مما يتيح لك الاستجابة لتلاعب السحب بالطريقة التي تريدها.

حدود الترجمة والدوران

بشكل افتراضي، لا توجد حدود للحركة الثنائية الأبعاد خلف القيود الداخلية لـ 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 نمط السحب، والوظائف المخصصة، يمكن للبرامج النصية الاستجابة لتلاعب عناصر واجهة المستخدم المسحوبة لتوجيه إعدادات مختلفة أو اتخاذ قرارات منطقية، مثل المنزلقات التي تضبط صوت الموسيقى وتأثيرات الصوت بشكل منفصل.

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

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

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

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

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

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

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 في نافذة المستعرض، واختر إدراج ⟩ استيراد نموذج روبلوكس، واختر الملف الذي تم تنزيله.

UIDragDetector - تغيير DragRotation
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 (الموضع) و float (الدوران). سيقوم الموصل بتحديث الكائن إلى الموضع/الدوران المحسوب بناءً على القيم المرتجعة، وخصائص DragSpace وDragRelativity.

بشكل افتراضي، ستكون UDim2 و float المرتجع هو الموضع/الدوران المرغوب النهائي في المساحة المحلية للموصل. ستظل القيود الحالية للترجمة/الدوران سارية، كما هي القيود الحدية المفروضة بواسطة مثيل 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 في نافذة المستعرض، واختر إدراج ⟩ استيراد نموذج روبلوكس، واختر الملف الذي تم تنزيله.

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)