spin wheel

عجلة تدور

مكون سهل الاستخدام وقابل للتخصيص لاختيارات عشوائية وجوائز.

سمات

• الفانيليا جافا سكريبت (ES6).
• لا التبعيات.
• واجهة برمجة التطبيقات (API) بسيطة وسهلة الاستخدام.
• قم بالتدوير من خلال تطبيق الزخم والسحب، أو قم بالتحريك إلى زاوية محددة مع سهولة الحركة.
• قابلة للتفاعل مع النقر والسحب أو النقر باللمس.
• تخطيط سريع الاستجابة (يتم تغيير حجمه تلقائيًا ليناسب الحاوية الخاصة به).
• موضوع بسهولة:
  • إعطاء العناصر لونها ووزنها.
  • تدوير التسميات وتغيير المحاذاة.
  • ارسم الصور على العناصر والعجلة والمقدمة.
  • تطبيق مجموعات الألوان المتكررة.
• عمليات الاسترجاعات لأحداث مثل onSpin و onCurrentIndexChange .
• الدوران في اتجاه عقارب الساعة وعكس اتجاه عقارب الساعة.

أمثلة

• الإدارة السليمة بيئياً الأساسية
• IIFE الأساسية
• النظرة الأساسية
• تدور إلى عنصر معين
• عجلات متعددة
• المواضيع
• الملعب (للاختبار واستكشاف الأخطاء وإصلاحها)

تثبيت

الإدارة السليمة بيئياً

 import { Wheel } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/spin-wheel-esm.js' ;

إيف

 < script src =" https://cdn.jsdelivr.net/npm/[email protected]/dist/spin-wheel-iife.js " > </ script >

محلي

npm install spin-wheel

كيف تصنع العجلة بنفسك

 // 1. Configure the wheel's properties:
const props = {
  items : [
    {
      label : 'one' ,
    } ,
    {
      label : 'two' ,
    } ,
    {
      label : 'three' ,
    } ,
  ]
}

// 2. Decide where you want it to go:
const container = document . querySelector ( '.wheel-container' ) ;

// 3. Create the wheel in the container and initialise it with the props:
const wheel = new Wheel ( container , props ) ; 

كيف تدور العجلة

بالنسبة للألعاب متعددة اللاعبين أو منح الجوائز ذات القيمة الفعلية، فإن أفضل طريقة هي استدعاء Wheel.spinToItem() . سوف تدور العجلة لمدة معينة، وبمجرد الانتهاء، سيشير المؤشر إلى العنصر المحدد. يجب عليك دائمًا حساب العنصر الفائز في الواجهة الخلفية، على سبيل المثال:

 const winningItemIndex = await fetchWinningItemIndex ( ) ;
const duration = 4000 ;
const easing = easing . cubicOut ;
wheel . spinToItem ( winningItemIndex , duration , true , 2 , 1 , easing )

إذا لم تكن الدقة مهمة، فيمكنك استخدام Wheel.spin() ‎ للبدء فورًا في تدوير العجلة بسرعة معينة، والتي سيتم تقليلها بمرور الوقت وفقًا لـ Wheel.rotationResistance . يمكنك أيضًا ضبط Wheel.isInteractive = true للسماح للمستخدم بتدوير العجلة بنفسه عن طريق السحب أو النقر.

كيفية رسم المؤشر

لا تحتوي العجلة على مؤشر مدمج، وبدلاً من ذلك يمكنك ضبط Wheel.pointerAngle ورسم المؤشر بنفسك. وذلك لأن هناك العديد من الطرق التي قد ترغب في أن يظهر بها المؤشر ويتصرف، على سبيل المثال قد ترغب في تحريكه.

خياراتك لرسم المؤشر هي:

• تراكب صورة باستخدام Wheel.overlayImage
• تراكب شيء ما باستخدام DOM

الصور والخطوط

يتم تمرير الصور كمثيلات لـ HTMLImageElement ويجب تحميلها مسبقًا، وإلا فسيكون هناك تأخير أولي (أو وميض) أثناء تنزيل المتصفح لها. يجب أيضًا تحميل الخطوط مسبقًا لنفس السبب. راجع الكود الموجود خلف مثال السمات للحصول على مثال لكيفية التحميل المسبق للصور والخطوط.

إعدادات

كل شيء سهل التكوين. تستجيب العجلة ويتم تغيير حجمها تلقائيًا لتناسب الحاوية الخاصة بها، لذلك عندما يتغير حجم الحاوية، لا داعي للقلق بشأن تحديث الأشياء غير الدقيقة مثل العرض وأحجام الخطوط. ولهذا السبب، يتم التعبير عن بعض الخصائص الرقمية كنسب مئوية، بينما يتم التعبير عن البعض الآخر بالبكسل.

• خصائص النسبة المئوية هي نسبة مئوية من حجم الحاوية. على سبيل المثال، Wheel.radius 0.9 يعني أن العجلة ستملأ 90% من الحاوية.

• ترتبط خصائص البكسل بحجم حاوية يبلغ 500px . على سبيل المثال، فإن Wheel.LineWidth الذي يبلغ 1 سيكون بالضبط 1px عندما يكون حجم الحاوية 500px .

من السهل أيضًا تكوين التسميات نظرًا لأنه يتم حساب حجم الخط تلقائيًا. يمكنك اختياريًا تعيين Wheel.itemLabelFontSizeMax (بالبكسل)، ولكن بخلاف ذلك سيتم تحديد حجم تسمية العنصر الأكبر لتتناسب بين Wheel.itemLabelRadius (بالنسبة المئوية) و Wheel.itemLabelRadiusMax (بالنسبة المئوية).

فيما يلي رسم تخطيطي مفيد:

طرق Wheel

طريقة	وصف
constructor(container, props = {})	قم بإنشاء العجلة داخل عنصر الحاوية وقم بتهيئتها باستخدام الدعائم. يجب أن تكون container عنصرًا. يجب أن تكون props كائنًا أو فارغة.
init(props = {})	تهيئة جميع الخصائص. إذا لم يتم توفير قيمة للخاصية، فسيتم إعطاؤها قيمة افتراضية.
resize()	[تراث] أعد حساب العجلة وأعد رسمها. مطلوب فقط في سيناريوهات معينة للمتصفحات القديمة التي لا تدعم ResizeObserver.
remove()	قم بإزالة العجلة من DOM وقم بإلغاء تسجيل معالجات الأحداث.
spin(rotationSpeed = 0)	قم بتدوير العجلة عن طريق ضبط rotationSpeed . ستبدأ العجلة في الدوران على الفور، وتتباطأ مع مرور الوقت اعتمادًا على قيمة rotationResistance . الرقم الموجب سوف يدور في اتجاه عقارب الساعة، والرقم السالب سوف يدور عكس اتجاه عقارب الساعة.
spinTo(rotation = 0, duration = 0, easingFunction = null)	قم بتدوير العجلة لدورة معينة. سيتم تنفيذ الرسوم المتحركة خلال duration المقدمة (مللي ثانية). يمكن تعديل الرسوم المتحركة من خلال توفير easingFunction اختيارية تقبل معلمة واحدة n، حيث تتراوح n بين 0 و1 ضمنًا. إذا لم يتم توفير وظيفة التخفيف، فسيتم استخدام EaseSinOut الافتراضي. على سبيل المثال، وظائف التخفيف، انظر easing-utils.
spinToItem(itemIndex = 0, duration = 0, spinToCenter = true, numberOfRevolutions = 1, direction = 1, easingFunction = null)	قم بتدوير العجلة نحو عنصر معين. سيتم تنفيذ الرسوم المتحركة خلال duration المقدمة (مللي ثانية). إذا كان spinToCenter صحيحًا، فستدور العجلة إلى مركز العنصر، وإلا ستدور العجلة بزاوية عشوائية داخل العنصر. يتحكم numberOfRevolutions في عدد المرات التي ستدور فيها العجلة 360 درجة كاملة قبل أن تستقر على العنصر. يمكن أن يكون direction 1 (في اتجاه عقارب الساعة) أو -1 (عكس اتجاه عقارب الساعة) يمكن تعديل الرسوم المتحركة من خلال توفير easingFunction اختيارية تقبل معلمة واحدة n، حيث تتراوح n بين 0 و1 ضمنًا. إذا لم يتم توفير وظيفة التخفيف، فسيتم استخدام EaseSinOut الافتراضي. على سبيل المثال، وظائف التخفيف، انظر easing-utils.
stop()	أوقف العجلة فورًا عن الدوران، بغض النظر عن الطريقة التي تم استخدامها لتدويرها.
getCurrentIndex()	احصل على فهرس العنصر الذي يشير إليه المؤشر. يعتبر العنصر "حاليًا" إذا كان pointerAngle بين زاوية البداية (شاملة) وزاوية النهاية (حصرية).

خصائص Wheel

ملاحظة: يؤدي تعيين الخاصية إلى undefined إلى إعادة تعيينها إلى القيمة الافتراضية.

اسم	القيمة الافتراضية	وصف
borderColor	'#000'	لون CSS للخط المحيط بمحيط العجلة.
borderWidth	0	عرض الخط (بالبكسل) حول محيط العجلة.
debug	false	إذا سيتم عرض معلومات التصحيح. وهذا مفيد عند تحديد موضع التسميات.
image	null	HTMLImageElement للرسم على العجلة والتدوير باستخدام العجلة. سيتم توسيطه وتحجيمه ليناسب Wheel.radius .
isInteractive	true	إذا كان سيتم السماح للمستخدم بتدوير العجلة باستخدام النقر والسحب/النقر بالنقر. سيتم اكتشاف تفاعل المستخدم فقط ضمن حدود Wheel.radius .
itemBackgroundColors	['#fff']	ألوان CSS المستخدمة كنمط متكرر لألوان الخلفية لجميع العناصر. تم تجاوزه بواسطة Item.backgroundColor . مثال: ['#fff','#000'] .
itemLabelAlign	'right'	محاذاة جميع تسميات العناصر. القيم المحتملة: 'left' ، 'center' ، 'right' .
itemLabelBaselineOffset	0	إزاحة الخط الأساسي (أو ارتفاع الخط) لجميع تسميات العناصر (كنسبة مئوية من ارتفاع التسمية).
itemLabelColors	['#000']	ألوان CSS التي سيتم استخدامها كنمط متكرر لألوان جميع تسميات العناصر. تم تجاوزه بواسطة Item.labelColor . مثال: ['#fff','#000'] .
itemLabelFont	'sans-serif'	عائلة الخطوط التي سيتم استخدامها لجميع تسميات العناصر. مثال: 'Helvetica, sans-serif' .
itemLabelFontSizeMax	100	الحد الأقصى لحجم الخط (بالبكسل) لجميع تسميات العناصر.
itemLabelRadius	0.85	النقطة على طول نصف قطر العجلة (كنسبة مئوية، بدءًا من المركز) لبدء رسم كافة تسميات العناصر.
itemLabelRadiusMax	0.2	النقطة الموجودة على طول نصف قطر العجلة (كنسبة مئوية، بدءًا من المركز) لتحديد الحد الأقصى لعرض كافة تسميات العناصر.
itemLabelRotation	0	تدوير كافة تسميات العناصر.استخدم هذا مع itemLabelAlign لقلب التسميات 180° .
itemLabelStrokeColor	'#fff'	لون CSS للحد المطبق على الجزء الخارجي من نص التسمية.
itemLabelStrokeWidth	0	عرض الحد المطبق على الجزء الخارجي من نص التسمية.
items	[]	العناصر (أو الشرائح، الأوتاد، الأجزاء) المعروضة على العجلة. سيؤدي تعيين هذه الخاصية إلى إعادة إنشاء كافة العناصر الموجودة على العجلة بناءً على الكائنات المتوفرة. يتيح لك الوصول إلى هذه الخاصية تغيير العناصر الفردية. على سبيل المثال، يمكنك تغيير لون خلفية أحد العناصر.
lineColor	'#000'	لون CSS للخطوط بين العناصر.
lineWidth	1	عرض الخطوط بين العناصر (بالبكسل).
offset	{x: 0, y: 0}	إزاحة العجلة من مركز الحاوية الخاصة بها (كنسبة مئوية من قطر العجلة).
onCurrentIndexChange	null	رد الاتصال لحدث onCurrentIndexChange .
onRest	null	رد الاتصال لحدث onRest .
onSpin	null	رد الاتصال لحدث onSpin .
overlayImage	null	HTMLImageElement للرسم على الجزء العلوي من العجلة. سيتم توسيطها وتحجيمها لتناسب أصغر أبعاد الحاوية. استخدم هذا لرسم زخارف حول العجلة، مثل الحامل أو المؤشر.
pixelRatio	0	نسبة البكسل (كنسبة مئوية) المستخدمة لرسم العجلة. ستنتج القيم الأعلى صورة أكثر وضوحًا على حساب الأداء، لكن الحدة تعتمد على جهاز العرض الحالي. ستستخدم القيمة 0 نسبة البكسل لجهاز العرض الحالي (راجع نسبة بكسل الجهاز).
pointerAngle	0	زاوية المؤشر التي سيتم استخدامها لتحديد الفهرس currentIndex (أو العنصر "الفائز").
radius	0.95	نصف قطر العجلة (كنسبة مئوية من أصغر أبعاد الحاوية).
rotation	0	دوران (الزاوية بالدرجات) للعجلة. سيتم رسم العنصر الأول في اتجاه عقارب الساعة من هذه النقطة.
rotationResistance	-35	سيتم تقليل مقدار rotationSpeed كل ثانية حتى تتوقف العجلة عن الدوران. اضبط على 0 لتدوير العجلة إلى ما لا نهاية.
rotationSpeed	0	[للقراءة فقط] مدى سرعة دوران العجلة (الزاوية بالدرجات) كل ثانية واحدة. الرقم الموجب يعني أن العجلة تدور في اتجاه عقارب الساعة، والرقم السالب يعني عكس اتجاه عقارب الساعة، والرقم 0 يعني أن العجلة لا تدور.
rotationSpeedMax	250	الحد الأقصى للقيمة المطلقة rotationSpeed . لن تدور العجلة بشكل أسرع من هذه القيمة في أي من الاتجاهين.

أحداث Wheel

onCurrentIndexChange(event = {})

يتم رفعه عند الإشارة إلى عنصر جديد. يمكن استخدام هذا لتغيير لون العنصر الحالي، أو تشغيل صوت "تكتكة".

مفتاح	قيمة
type	'currentIndexChange'
currentIndex	فهرس العنصر الذي كان المؤشر يشير إليه. انظر Wheel.pointerAngle .

onRest(event = {})

يتم رفعه عندما تتوقف العجلة بعد الدوران.

مفتاح	قيمة
type	'rest'
currentIndex	فهرس العنصر الذي كان المؤشر يشير إليه. انظر Wheel.pointerAngle .
rotation	دوران العجلة. انظر Wheel.rotation .

onSpin(event = {})

يتم رفعه عند تدوير العجلة.

مفتاح	قيمة
type	'spin'
duration	مدة الرسوم المتحركة تدور. يتم توفيره فقط عندما تكون method = spinto أو method = spintoitem .
method	الطريقة التي تم استخدامها لتدوير العجلة هي ( interact ، spin ، spinto ، spintoitem ).
rotationResistance	قيمة Wheel.rotationResistance في وقت رفع الحدث. يتم توفيره فقط عندما تكون method = interact أو method = spin .
rotationSpeed	قيمة Wheel.rotationSpeed ​​في وقت رفع الحدث. يتم توفيره فقط عندما تكون method = interact أو method = spin .
targetItemIndex	العنصر الذي سيشير إليه المؤشر بمجرد انتهاء الرسوم المتحركة للدوران. يتم توفيره فقط عندما تكون method = spintoitem .
targetRotation	القيمة التي سيكون لها Wheel.rotation بمجرد انتهاء الرسوم المتحركة للدوران. يتم توفيره فقط عندما تكون method = spinto أو method = spintoitem .

طرق Item

اسم	وصف
getCenterAngle()	احصل على الزاوية (بالدرجات) التي ينتهي عندها هذا العنصر (حصريًا)، متجاهلاً rotation الحالي للعجلة.
getEndAngle()	احصل على الزاوية (بالدرجات) التي ينتهي عندها هذا العنصر (شاملاً)، متجاهلاً rotation الحالي للعجلة.
getIndex()	احصل على الفهرس المستند إلى 0 لهذا العنصر.
getRandomAngle()	قم بإرجاع زاوية عشوائية (بالدرجات) بين زاوية بداية هذا العنصر (شاملة) وزاوية النهاية (شاملة).
getStartAngle()	احصل على الزاوية (بالدرجات) التي يبدأ بها هذا العنصر (شاملاً)، متجاهلاً rotation الحالي للعجلة.
init(props = {})	تهيئة كافة الخصائص. إذا كانت القيمة غير محددة أو غير صالحة، فستعود هذه الخاصية إلى القيمة الافتراضية.

خصائص Item

ملاحظة: يؤدي تعيين الخاصية إلى undefined إلى إعادة تعيينها إلى القيمة الافتراضية.

اسم	القيمة الافتراضية	وصف
backgroundColor	null	لون CSS لخلفية العنصر. عندما يكون اللون null ، سيعود اللون إلى Wheel.itemBackgroundColors . مثال: '#fff' .
image	null	HTMLImageElement للرسم على العنصر. سيتم قص أي جزء من الصورة يمتد خارج العنصر. سيتم رسم الصورة أعلى Item.backgroundColor .
imageOpacity	1	العتامة (كنسبة مئوية) لـ Item.image . يكون هذا مفيدًا إذا كنت تريد تعتيم الصورة لإبراز تسمية العنصر.
imageRadius	0.5	النقطة على طول نصف قطر العجلة (كنسبة مئوية، بدءًا من المركز) لرسم مركز Item.image .
imageRotation	0	دوران (الزاوية بالدرجات) لـ Item.image .
imageScale	1	المقياس (الحجم كنسبة مئوية) لـ Item.image .
label	''	النص الذي سيتم رسمه على العنصر.
labelColor	null	لون CSS لتسمية العنصر. عندما يكون اللون null ، سيعود اللون إلى Wheel.itemLabelColors . مثال: '#000' .
value	null	بعض القيمة التي لها معنى لتطبيقك. على سبيل المثال، مرجع إلى الكائن الذي يمثل العنصر الموجود على العجلة، أو معرف قاعدة البيانات.
weight	1	الحجم المتناسب للعنصر بالنسبة للعناصر الأخرى الموجودة على العجلة. على سبيل المثال، إذا كان لديك عنصرين حيث item[0] له وزن 1 item[1] له وزن 2 ، فإن item[0] سيشغل ثلث المساحة على العجلة.

شكر وتقدير

مستوحاة من عجلة عشوائية.