دليل شامل لاكتشاف أجهزة واجهة المستخدم (HIDs) والتفاعل معها باستخدام WebHID API في JavaScript. تعرف على تعداد الأجهزة، والتصفية، وأفضل ممارسات الاتصال.
تعداد أجهزة WebHID في الواجهة الأمامية: اكتشاف الأجهزة المتصلة باستخدام JavaScript
تفتح WebHID API إمكانية لتطبيقات الويب للتواصل مباشرة مع مجموعة واسعة من أجهزة واجهة المستخدم (HIDs) التي عادة ما تكون متاحة فقط للتطبيقات الأصلية. هذا يفتح إمكانيات مثيرة لإنشاء تجارب ويب مبتكرة تتفاعل مع الأجهزة المتخصصة مثل وحدات تحكم الألعاب، وأجهزة الإدخال المخصصة، والأدوات العلمية، والمزيد. يتعمق هذا الدليل الشامل في المفهوم الأساسي لتعداد الأجهزة، وهو الخطوة الأولى الحاسمة في إنشاء اتصال بجهاز HID المطلوب.
ما هي WebHID API؟
تسمح WebHID API لتطبيقات الويب بالوصول إلى أجهزة واجهة المستخدم. تشمل هذه الأجهزة فئة واسعة، بما في ذلك:
- وحدات تحكم الألعاب: عصا التحكم، لوحات الألعاب، عجلات السباق
- أجهزة الإدخال: لوحات المفاتيح، الفئران، كرات التتبع
- ضوابط صناعية: لوحات تحكم متخصصة، واجهات استشعار
- أدوات علمية: أجهزة الحصول على البيانات، أدوات القياس
- أجهزة مخصصة: أجهزة إدخال مخصصة تم إنشاؤها لأغراض محددة
على عكس واجهات برمجة التطبيقات القديمة للمتصفح التي قدمت دعمًا محدودًا لـ HID، توفر WebHID API وصولاً مباشرًا إلى أجهزة HID، مما يتيح للمطورين إنشاء تطبيقات ويب أغنى وأكثر تفاعلية. تخيل التحكم في ذراع روبوتية في معمل بعيد، أو معالجة نموذج ثلاثي الأبعاد بجهاز إدخال مخصص، أو تلقي بيانات المستشعرات مباشرة في لوحة تحكم قائمة على الويب - كل ذلك داخل المتصفح.
فهم تعداد أجهزة HID
قبل أن تتمكن من التفاعل مع جهاز HID، يحتاج تطبيق الويب الخاص بك إلى اكتشاف الأجهزة المتصلة بنظام المستخدم. تسمى هذه العملية تعداد الأجهزة. توفر WebHID API آلية لطلب الوصول إلى أجهزة HID محددة بناءً على معرف البائع (VID) ومعرف المنتج (PID) أو باستخدام مرشح أوسع.
تتضمن العملية عادةً هذه الخطوات:
- طلب الوصول إلى الجهاز: يطالب تطبيق الويب المستخدم بتحديد جهاز HID باستخدام
navigator.hid.requestDevice(). - تصفية الأجهزة: يمكنك تحديد عوامل تصفية لتضييق قائمة الأجهزة المعروضة للمستخدم. تستند هذه المرشحات إلى VID و PID للجهاز.
- معالجة اختيار الجهاز: يختار المستخدم جهازًا من القائمة.
- فتح الجهاز: يفتح التطبيق اتصالاً بالجهاز المحدد.
- نقل البيانات: بمجرد إنشاء الاتصال، يمكن للتطبيق إرسال واستقبال البيانات من الجهاز.
دليل خطوة بخطوة لتعداد الأجهزة
1. طلب الوصول إلى الجهاز باستخدام عوامل التصفية
navigator.hid.requestDevice() هي نقطة الدخول لطلب الوصول إلى أجهزة HID. تأخذ وسيطة اختيارية `filters`، وهي مصفوفة من الكائنات التي تحدد VID و PID للأجهزة التي تريد العثور عليها.
إليك مثال لكيفية طلب الوصول إلى جهاز بمعرف بائع ومعرف منتج محددين:
async function requestHIDDevice() {
try {
const devices = await navigator.hid.requestDevice({
filters: [
{
vendorId: 0x1234, // استبدل بمعرف البائع لجهازك
productId: 0x5678 // استبدل بمعرف المنتج لجهازك
},
// أضف المزيد من عوامل التصفية للأجهزة الأخرى إذا لزم الأمر
]
});
if (devices.length > 0) {
const device = devices[0]; // استخدم أول جهاز محدد
console.log("تم العثور على جهاز HID:", device);
// افتح الجهاز وابدأ الاتصال
await openHIDDevice(device);
} else {
console.log("لم يتم تحديد أي جهاز HID.");
}
} catch (error) {
console.error("خطأ في طلب جهاز HID:", error);
}
}
// مثال على الاستخدام (على سبيل المثال، يتم تشغيله عن طريق النقر على زر):
document.getElementById('requestButton').addEventListener('click', requestHIDDevice);
اعتبارات هامة:
- معرف البائع (VID) ومعرف المنتج (PID): هذه معرفات فريدة مخصصة لأجهزة USB و Bluetooth. ستحتاج إلى الحصول على VID و PID للجهاز المستهدف من وثائق الشركة المصنعة أو باستخدام أدوات النظام (مثل، Device Manager على Windows، System Information على macOS، أو `lsusb` على Linux).
- موافقة المستخدم: تعرض طريقة
requestDevice()مطالبة إذن يتحكم فيها المتصفح للمستخدم، مما يسمح له باختيار أجهزة HID التي يمنحها الإذن بالوصول إليها. هذا إجراء أمني حاسم لمنع المواقع الضارة من الوصول إلى الأجهزة الحساسة دون موافقة المستخدم. - عوامل تصفية متعددة: يمكنك تضمين عوامل تصفية متعددة في مصفوفة `filters` لطلب الوصول إلى الأجهزة ذات معرفات البائع والمنتج المختلفة. هذا مفيد إذا كان تطبيقك يدعم تكوينات أجهزة متعددة.
2. الحصول على معلومات الجهاز
بمجرد أن يختار المستخدم جهازًا، تقوم طريقة requestDevice() بإرجاع مصفوفة من كائنات HIDDevice. يحتوي كل كائن HIDDevice على معلومات حول الجهاز، مثل VID و PID و usagePage و usage والمجموعات. يمكنك استخدام هذه المعلومات لتحديد الجهاز وتكوينه بشكل أكبر.
async function openHIDDevice(device) {
try {
await device.open();
console.log("تم فتح جهاز HID:", device.productName);
// الاستماع لتقارير الإدخال
device.addEventListener("inputreport", event => {
const { data, reportId } = event;
const uint8Array = new Uint8Array(data.buffer);
console.log(`تم استلام تقرير الإدخال ${reportId}:`, uint8Array);
// معالجة بيانات تقرير الإدخال
});
device.addEventListener("disconnect", event => {
console.log("تم فصل جهاز HID:", device.productName);
// معالجة فصل الجهاز
});
} catch (error) {
console.error("خطأ في فتح جهاز HID:", error);
}
}
خصائص الجهاز:
vendorId: معرف البائع للجهاز.productId: معرف المنتج للجهاز.productName: اسم المنتج القابل للقراءة.collections: مصفوفة من كائناتHIDCollectionInfoتصف مجموعات HID الخاصة بالجهاز (تقارير، ميزات، إلخ). يمكن أن يكون هذا معقدًا للغاية ولا يلزم إلا للأجهزة المعقدة.
3. معالجة اتصال الجهاز وفصله
توفر WebHID API أحداثًا لإعلام تطبيقك عند اتصال جهاز أو فصله. يمكنك الاستماع إلى أحداث connect و disconnect على الكائن navigator.hid.
navigator.hid.addEventListener("connect", event => {
const device = event.device;
console.log("تم توصيل جهاز HID:", device);
// معالجة توصيل الجهاز (على سبيل المثال، إعادة فتح الجهاز)
});
avigator.hid.addEventListener("disconnect", event => {
const device = event.device;
console.log("تم فصل جهاز HID:", device);
// معالجة فصل الجهاز (على سبيل المثال، تنظيف الموارد)
});
أفضل الممارسات لإدارة الاتصال:
- إعادة التعداد عند الاتصال: عند توصيل جهاز، غالبًا ما يكون من الممارسات الجيدة إعادة تعداد الأجهزة لضمان أن تطبيقك لديه قائمة محدثة.
- تنظيف الموارد عند الفصل: عند فصل جهاز، حرر أي موارد مرتبطة به (على سبيل المثال، أغلق اتصال الجهاز، قم بإزالة مستمعي الأحداث).
- معالجة الأخطاء: قم بتطبيق معالجة أخطاء قوية للتعامل مع المواقف التي يفشل فيها الجهاز في الاتصال أو ينفصل بشكل غير متوقع.
تقنيات تصفية الأجهزة المتقدمة
بالإضافة إلى تصفية VID و PID الأساسية، تقدم WebHID API تقنيات أكثر تقدمًا لاستهداف أجهزة محددة. هذا مفيد بشكل خاص عند التعامل مع الأجهزة التي تحتوي على واجهات أو وظائف متعددة.
1. التصفية حسب صفحة الاستخدام والاستخدام
تنظم أجهزة HID في صفحات الاستخدام و الاستخدامات، والتي تحدد نوع الوظيفة التي يوفرها الجهاز. على سبيل المثال، تنتمي لوحة المفاتيح إلى صفحة الاستخدام "Generic Desktop" ولديها استخدام "Keyboard". يمكنك تصفية الأجهزة بناءً على صفحة الاستخدام والاستخدام لاستهداف أنواع أجهزة محددة.
async function requestSpecificKeyboard() {
try {
const devices = await navigator.hid.requestDevice({
filters: [
{
usagePage: 0x01, // صفحة المكتب العام
usage: 0x06 // استخدام لوحة المفاتيح
}
]
});
// ... (بقية الكود لمعالجة الجهاز)
} catch (error) {
console.error("خطأ في طلب جهاز HID:", error);
}
}
العثور على قيم صفحة الاستخدام والاستخدام:
- جداول استخدام HID: تحدد جداول استخدام HID الرسمية (المنشورة بواسطة USB Implementers Forum) صفحات الاستخدام والاستخدامات الموحدة لأنواع الأجهزة المختلفة.
- وثائق الجهاز: قد تحدد وثائق الشركة المصنعة للجهاز قيم صفحة الاستخدام والاستخدام لجهازها.
- واصفات تقرير HID: للسيناريوهات المتقدمة، يمكنك تحليل واصف تقرير HID لجهاز لتحديد صفحات الاستخدام والاستخدامات المدعومة.
2. معالجة الواجهات المتعددة
تكشف بعض أجهزة HID عن واجهات متعددة، لكل منها مجموعة وظائفها الخاصة. تعامل WebHID API كل واجهة كجهاز HID منفصل. للوصول إلى واجهة معينة، قد تحتاج إلى دمج تصفية VID/PID مع تصفية صفحة الاستخدام/الاستخدام لاستهداف الواجهة المطلوبة.
أمثلة عملية وحالات استخدام
1. بناء واجهة تحكم مخصصة للألعاب
تخيل أنك تقوم ببناء لعبة قائمة على الويب وتريد دعم وحدة تحكم مخصصة للألعاب. يمكنك استخدام WebHID API لقراءة المدخلات مباشرة من أزرار وحدة التحكم وعصا التحكم وعناصر التحكم الأخرى. يتيح لك ذلك إنشاء تجربة لعب سريعة الاستجابة وغامرة للغاية.
2. إنشاء وحدة تحكم MIDI قائمة على الويب
يمكن للموسيقيين والمهندسين الصوتيين الاستفادة من وحدات تحكم MIDI القائمة على الويب التي تتفاعل مع محطات عمل الصوت الرقمية (DAWs) أو أجهزة التوليف. تتيح لك WebHID API بناء وحدات تحكم MIDI مخصصة ترسل وتستقبل رسائل MIDI مباشرة في المتصفح.
3. التفاعل مع الأدوات العلمية
يمكن للباحثين والعلماء استخدام WebHID API للتفاعل مع الأدوات العلمية، مثل أجهزة الحصول على البيانات والمستشعرات وأدوات القياس. يتيح لهم ذلك جمع وتحليل البيانات مباشرة في لوحة تحكم أو أداة تحليل قائمة على الويب.
4. تطبيقات إمكانية الوصول
توفر WebHID فرصًا لإنشاء تقنيات مساعدة. على سبيل المثال، يمكن دمج أجهزة الإدخال المتخصصة للمستخدمين الذين يعانون من إعاقات حركية مباشرة في تطبيقات الويب، مما يوفر تجارب أكثر تخصيصًا وسهولة في الوصول. قد تشمل الأمثلة العالمية دمج أجهزة تتبع العين المتخصصة للتنقل بدون استخدام اليدين أو صفائف أزرار قابلة للتخصيص للوصول بمفتاح واحد عبر لغات وطرق إدخال مختلفة.
توافق المتصفح واعتبارات الأمان
1. دعم المتصفح
يتم دعم WebHID API حاليًا في المتصفحات المستندة إلى Chromium (Chrome و Edge و Opera) ويجري تطويره للمتصفحات الأخرى. قبل تنفيذ WebHID API في تطبيقك، من المهم التحقق من توافق المتصفح وتوفير آليات احتياطية للمتصفحات التي لا تدعم واجهة برمجة التطبيقات.
2. اعتبارات الأمان
تم تصميم WebHID API مع مراعاة الأمان. يطلب المتصفح من المستخدم الإذن قبل السماح لتطبيق الويب بالوصول إلى جهاز HID. هذا يمنع المواقع الضارة من الوصول إلى الأجهزة الحساسة دون موافقة المستخدم. علاوة على ذلك، تعمل WebHID API ضمن بيئة أمان المتصفح (sandbox)، مما يحد من وصول التطبيق إلى موارد النظام.
- HTTPS فقط: يتطلب WebHID، مثل واجهات برمجة التطبيقات القوية الأخرى على الويب، سياقًا آمنًا (HTTPS) للعمل.
- إيماءات المستخدم: يتطلب طلب الوصول إلى الجهاز عادةً إيماءة من المستخدم (على سبيل المثال، النقر على زر) لمنع طلبات الوصول غير المرغوب فيها.
- Permissions API: يمكن استخدام Permissions API للاستعلام عن أذونات WebHID وإدارتها.
استكشاف الأخطاء وإصلاحها للمشكلات الشائعة
1. عدم العثور على الجهاز
إذا لم يتمكن تطبيقك من العثور على جهاز HID، فتحقق مرة أخرى من VID و PID. تأكد من تطابقهما مع المعرفات الفعلية للجهاز. تأكد أيضًا من أن الجهاز متصل بشكل صحيح ومعترف به من قبل نظام التشغيل.
2. رفض الإذن
إذا رفض المستخدم الإذن بالوصول إلى جهاز HID، فلن يتمكن تطبيقك من الاتصال به. تعامل مع هذا السيناريو بلطف عن طريق عرض رسالة للمستخدم وشرح سبب الحاجة إلى الوصول. ضع في اعتبارك توفير طرق بديلة للمستخدم للتفاعل مع تطبيقك.
3. مشكلات تنسيق البيانات
غالبًا ما تستخدم أجهزة HID تنسيقات بيانات مخصصة لإرسال واستقبال البيانات. ستحتاج إلى فهم تنسيق بيانات الجهاز وتنفيذ منطق التحليل والتسلسل المناسب في تطبيقك. استشر وثائق الشركة المصنعة للجهاز للحصول على معلومات حول تنسيق البيانات.
خاتمة
تمكن WebHID API مطوري الويب من إنشاء تطبيقات ويب مبتكرة وتفاعلية تتواصل مباشرة مع أجهزة واجهة المستخدم. من خلال فهم مبادئ تعداد الأجهزة والتصفية وإدارة الاتصال، يمكنك إطلاق العنان للإمكانات الكاملة لـ WebHID API وإنشاء تجارب مستخدم جذابة. احتضن قوة WebHID لربط الويب بالعالم المادي، وتعزيز إمكانيات جديدة للإبداع والإنتاجية وإمكانية الوصول في جميع أنحاء العالم.