ال Server Sent Events يتصل الامتداد بـ”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events”> مصدر الحدث مباشرة من HTML. فهو يدير الاتصالات بخادم الويب الخاص بك، ويستمع إلى أحداث الخادم، ثم يقوم بتبديل محتوياتها إلى صفحة الويب htmx الخاصة بك في الوقت الفعلي.
يعد SSE بديلاً خفيف الوزن لـ WebSockets الذي يعمل عبر اتصالات HTTP الموجودة، لذا فهو سهل الاستخدام من خلال الخوادم الوكيلة وجدران الحماية. تذكر أن SSE هي خدمة أحادية الاتجاه، لذا لا يمكنك إرسال أي رسائل إلى خادم SSE بمجرد إنشاء الاتصال. إذا كنت بحاجة إلى اتصال ثنائي الاتجاه، فيجب عليك التفكير في استخدامه”https://htmx.org/extensions/ws/”>مآخذ ويب بدلاً من.
يحل هذا الامتداد محل التجريبي hx-sse السمة المضمنة في الإصدارات السابقة من htmx. للحصول على مساعدة في الترحيل من الإصدارات الأقدم، راجع دليل الترحيل الموجود أسفل هذه الصفحة.
استخدم السمات التالية لتكوين كيفية تصرف اتصالات SSE:
sse-connect="– عنوان URL لخادم SSE." مبادلة="– اسم الرسالة المراد تبديلها في DOM." hx-trigger="sse:– يمكن لرسائل SSE أيضًا تشغيل عمليات رد اتصال HTTP باستخدام ملف”noopener” الهدف=”_blank” href=”https://htmx.org/attributes/hx-trigger”>" hx-triggerيصف.sse-close=– لإغلاق EventStream بأمان عند تلقي تلك الرسالة. قد يكون هذا مفيدًا إذا كنت تريد إرسال معلومات إلى عميل سيتوقف في النهاية.
التثبيت
اسرع طريقة للتثبيت sse هو تحميله عبر CDN. تذكر دائمًا تضمين مكتبة htmx الأساسية قبل الامتداد و”https://htmx.org/extensions/sse/#usage”> تمكين الامتداد.
"HTML">رأس> البرنامج النصي src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.8/dist/htmx.min.js" نزاهة="sha384-/TgkGk7p307TH7EXJDuUlgG3Ce1UVolAOFopFekQkkXihi5u/6OCvVKyz1W+idaz" com.crossorigin="anonymous">البرنامج النصي> البرنامج النصي src="https://cdn.jsdelivr.net/npm/htmx-ext-sse@2.2.4" نزاهة="sha384-A986SAtodyH8eg8x8irJnYUk7i9inVQqYigD6qZ9evobksGNIXfeFvDwLSHcp31N" com.crossorigin="anonymous">البرنامج النصي>رأس>جسم hx تحويلة="sse">
يتوفر أيضًا إصدار غير مصغر على https://cdn.jsdelivr.net/npm/htmx-ext-sse/dist/sse.js.
على الرغم من أن نهج CDN بسيط، فقد ترغب في أخذه بعين الاعتبار”noopener” الهدف=”_blank” href=”https://blog.wesleyac.com/posts/why-not-javascript-cdn”> عدم استخدام شبكات CDN في الإنتاج. الطريقة الأسهل التالية للتثبيت sse هو ببساطة نسخه إلى مشروعك. قم بتنزيل الامتداد من https://cdn.jsdelivr.net/npm/htmx-ext-sse، قم بإضافته إلى الدليل المناسب في مشروعك وقم بتضمينه عند الضرورة مع ملف علامة.
بالنسبة لأنظمة البناء على نمط npm، يمكنك التثبيت sse عبر”noopener” الهدف=”_blank” href=”https://www.npmjs.com/”>npm:
"shell">تثبيت npm htmx-ext-sse
بعد التثبيت، ستحتاج إلى استخدام الأدوات المناسبة للتجميع node_modules/htmx-ext-sse/dist/sse.js (أو .min.js). على سبيل المثال، يمكنك تجميع الامتداد مع htmx core من node_modules/htmx.org/dist/htmx.js والكود الخاص بالمشروع.
إذا كنت تستخدم أداة تجميع لإدارة جافا سكريبت (مثل Webpack وRollup):
- ثَبَّتَ
htmx.orgوhtmx-ext-sseعبر نبم - قم باستيراد كلا الحزمتين إلى ملفك
index.js
"JS">يستورد "htmx.org".;يستورد "htmx-ext-sse".;
الاستخدام
"html">شعبة hx تحويلة="sse" sse-connect="/chatroom" مبادلة sse="message"> سيتم تحديث محتويات هذا الصندوق في الوقت الحقيقي مع كل رسالة SSE يتم تلقيها من غرفة الدردشة.شعبة>
الاتصال بخادم SSE
للاتصال بخادم SSE، استخدم hx-تحويلة="sse" لتثبيت الامتداد على عنصر HTML هذا، ثم قم بإضافته sse-connect=" إلى العنصر لإجراء الاتصال.
عند تصميم تطبيق الخادم الخاص بك، تذكر أن SSE يعمل تمامًا مثل أي طلب HTTP. على الرغم من أنه لا يمكنك إرسال أي رسائل إلى الخادم بعد إنشاء اتصال، إلا أنه يمكنك إرسال معلمات إلى الخادم مع طلبك. لذلك، بدلاً من إجراء اتصال SSE بالخادم الخاص بك على https://my-server/chat-updates يمكنك أيضًا الاتصال بـ https://my-server/chat-updates?friends=true&format=detailed. يتيح ذلك لخادمك تخصيص استجاباته وفقًا لما يحتاجه عميلك.
تلقي الأحداث المسماة
تتكون رسائل SSE من اسم الحدث وحزمة البيانات. لا يُسمح بأي بيانات تعريف أخرى في الرسالة. هنا مثال:
"txt">الحدث: اسم الحدثالبيانات:المحتوى المراد تبديله في صفحة HTML الخاصة بك.
سوف نستخدم sse-swap السمة للاستماع إلى هذا الحدث وتبديل محتوياته إلى صفحة الويب الخاصة بنا.
"html">شعبة hx تحويلة="sse" sse-connect="/event-source" مبادلة sse="EventName">شعبة>
لاحظ أن الاسم EventName من رسالة الخادم يجب أن تتطابق مع القيمة الموجودة في sse-swap يصف. يمكن لخادمك استخدام العديد من أسماء الأحداث المختلفة حسب الضرورة، ولكن كن حذرًا: يمكن للمتصفحات الاستماع فقط للأحداث التي تمت تسميتها بشكل صريح. لذلك، إذا أرسل الخادم الخاص بك حدثًا باسم ChatroomUpdate لكن متصفحك يستمع فقط للأحداث المسماة ChatUpdate ثم سيتم تجاهل الحدث الإضافي.
تلقي الأحداث غير المسماة
يمكن أيضًا إرسال رسائل SSE بدون أي اسم للحدث. في هذه الحالة، يستخدم المتصفح الاسم الافتراضي message في مكانه. نفس القواعد المحددة أعلاه لا تزال سارية. إذا أرسل خادمك رسالة غير مسماة، فيجب عليك الاستماع إليها عن طريق تضمينها مبادلة="message". لا يوجد خيار لاستخدام اسم استقبال الرسائل الخاطئة. وإليك كيف يبدو هذا:
"txt">البيانات: المحتوى المراد تبديله في صفحة HTML الخاصة بك.
"html">شعبة hx تحويلة="sse" sse-connect="/event-source" مبادلة sse="message">شعبة>
تلقي أحداث متعددة
يمكنك أيضًا الاستماع إلى أحداث متعددة (مسماة أو غير مسماة) من مصدر حدث واحد. يجب أن يكون المستمعون إما 1) نفس العنصر الذي يحتوي على hx-ext و sse-connect السمات، أو 2) العناصر الفرعية للعنصر الذي يحتوي على hx-ext و sse-connect صفات.
"html">أحداث متعددة في نفس العنصرشعبة hx تحويلة="sse" sse-connect="/server-url" مبادلة sse="event1,event2">شعبة>أحداث متعددة في عناصر مختلفة (من نفس المصدر).شعبة hx تحويلة="sse" sse-connect="/server-url"> شعبة مبادلة sse="event1">شعبة> شعبة مبادلة sse="event2">شعبة>شعبة>
تشغيل عمليات الاسترجاعات للخادم
عند إنشاء اتصال للأحداث المرسلة من الخادم، يمكن للعناصر الفرعية الاستماع إلى هذه الأحداث باستخدام الخاص”noopener” الهدف=”_blank” href=”https://htmx.org/attributes/hx-trigger”>hx-trigger بناء الجملة sse:. هذا، عندما يقترن ب hx-get أو ما شابه ذلك سوف يؤدي إلى تشغيل العنصر لتقديم طلب.
هنا مثال:
"html">شعبة hx تحويلة="sse" sse-connect="/event_stream"> شعبة hx-get="/chatroom" hx-trigger="sse:chatter"> ... شعبة>شعبة>
ينشئ هذا المثال اتصال SSE بـ event_stream نقطة النهاية والتي تؤدي بعد ذلك إلى أ GET إلى /chatroom عنوان url كلما كان chatter ويرى الحدث.
إعادة الاتصال التلقائي
إذا تم إغلاق تدفق أحداث SSE بشكل غير متوقع، فمن المفترض أن تحاول المتصفحات إعادة الاتصال تلقائيًا. ومع ذلك، في حالات نادرة، لا يعمل هذا الأمر ويمكن ترك متصفحك معلقًا. يضيف هذا الامتداد منطق إعادة الاتصال الخاص به (باستخدام ملف”noopener” الهدف=”_blank” href=”https://en.wikipedia.org/wiki/Exponential_backoff”> خوارزمية التراجع الأسي) أعلى إعادة الاتصال التلقائي للمتصفح، بحيث تكون تدفقات SSE الخاصة بك دائمًا موثوقة قدر الإمكان.
اختبار اتصالات SSE مع الخادم التجريبي
يشتمل Htmx على خادم SSE تجريبي مكتوب بلغة Node.js والذي سيساعدك على رؤية SSE أثناء العمل، والبدء في تمهيد كود SSE الخاص بك. وهو موجود في المجلد /test/ws-sse الخاص بملف”noopener” الهدف=”_blank” href=”https://github.com/bigskysoftware/htmx-extensions”>htmx-extensions مستودع. انظر إلى /test/ws-sse/README.md للحصول على إرشادات حول تشغيل واستخدام خادم الاختبار.
الترحيل من الإصدارات السابقة
استخدمت الإصدارات السابقة من htmx علامة مضمنة hx-sse لتنفيذ الأحداث المرسلة من الخادم. تم ترحيل هذا الرمز إلى ملحق بدلاً من ذلك. فيما يلي الخطوات التي يتعين عليك اتخاذها للانتقال إلى هذا الإصدار:
| السمة القديمة | سمة جديدة | تعليقات |
|---|---|---|
hx-sse="" |
hx-تحويلة="sse" |
استخدم hx-تحويلة="sse" سمة لتثبيت ملحق SSE في أي عنصر HTML. |
hx-sse="connect: |
sse-connect=" |
إضافة سمة جديدة sse-connect إلى العلامة التي تحدد عنوان URL لتدفق الأحداث. يجب أن تكون هذه السمة في نفس العلامة مثل hx-ext يصف. |
hx-sse="swap: |
مبادلة=" |
إضافة سمة جديدة sse-swap إلى أي عناصر سيتم تبديلها عبر امتداد SSE. يجب وضع هذه السمة على أو داخل العلامة التي تحتوي على hx-ext يصف. |
hx-trigger="sse: |
لا تغيير | أي hx-trigger السمات لا تحتاج إلى التغيير. سيحدد الامتداد هذه السمات ويضيف المستمعين لأي أحداث مسبوقة بـ sse: |
الاستماع إلى الأحداث التي يرسلها هذا الامتداد
يرسل هذا الملحق العديد من الأحداث. يمكنك الاستماع لهذه الأحداث مثل ذلك:
"javascript">document.body.addEventListener("htmx:sseBeforeMessage", وظيفة (ه) { // افعل شيئًا قبل تبديل بيانات الحدث})
يحتوي كل كائن حدث على detail الحقل الذي يحتوي على تفاصيل الحدث.
htmx:sseOpen
يتم إرسال هذا الحدث عند إنشاء اتصال SSE بنجاح.
التفاصيل
detail.elt– العنصر الذي تم إعداد اتصال SSE عليه. هذا هو العنصر الذي يحتوي علىsse-connectيصف.detail.source– ال”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource”> مصدر الحدث هدف.
“htmx-sseerror”>htmx:sseError
يتم إرسال هذا الحدث عندما يتعذر إنشاء اتصال SSE.
التفاصيل
detail.error– الخطأ الذي حدث أثناء إنشاء”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource”> مصدر الحدث.detail.source– ال”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource”> مصدر الحدث.
htmx:sseBeforeMessage
يتم إرسال هذا الحدث مباشرةً قبل تبديل بيانات حدث SSE إلى DOM. إذا كنت لا ترغب في تبديل المكالمة preventDefault() على الحدث. بالإضافة إلى ذلك detail الحقل هو”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event”> حدث الرسالة – هذا هو الحدث الذي تم إنشاؤه بواسطة”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource”> مصدر الحدث عندما يتلقى رسالة SSE.
التفاصيل
detail.elt– هدف المبادلة.
htmx:sseMessage
يتم إرسال هذا الحدث بعد تبديل بيانات حدث SSE إلى DOM. ال detail الحقل هو”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event”> حدث الرسالة – هذا هو الحدث الذي تم إنشاؤه بواسطة”noopener” الهدف=”_blank” href=”https://developer.mozilla.org/en-US/docs/Web/API/EventSource”> مصدر الحدث عندما يتلقى رسالة SSE.
htmx:sseClose
يتم إرسال هذا الحدث في ثلاثة سيناريوهات إغلاق مختلفة. للتحكم في السيناريو، يمكن للمستخدم التحكم في الخاصية evt.detail.sseclos.
"javascript">document.body.addEventListener("هتمكس: sseClose", وظيفة (ه) { ثابت سبب =ه.التفاصيل.يكتب يُحوّل (سبب) { قضية "nodeMissing": // العقدة الأصلية مفقودة وبالتالي تم إغلاق الاتصال ... قضية "nodeReplaced": // تسبب استبدال العقدة الأصلية في إغلاق الاتصال ... قضية "message": // تم إغلاق الاتصال بسبب استقبال الرسالة sse-Close ... }})
التفاصيل
detail.elt– هدف المبادلة.