include fragment element - include fragment element

include fragment element

شفرة المصدر الأخرى

v6.3.0

تنزيل

<تضمين الرفع> العنصر

يتضمن جانب العميل علامة.

تثبيت

 $ npm install --save @github/include-fragment-element

الاستخدام

يجب أن تحتوي جميع عناصر include-fragment على سمة src لاسترداد جزء من عنصر HTML.

يجب أن يتضمن تحميل الصفحة الأولية محتوى العودة المراد عرضه إذا لم يكن من الممكن جلب المورد على الفور.

 import '@github/include-fragment-element'

إبداعي

 < div class =" tip " >
  < include-fragment src =" /tips " >
    < p > Loading tip… </ p >
  </ include-fragment >
</ div >

في تحميل الصفحة ، يجلب عنصر include-fragment في عنوان URL ، يتم تحليل الاستجابة في عنصر HTML ، والذي يحل محل عنصر include-fragment بالكامل.

نتيجة

 < div class =" tip " >
  < p > You look nice today </ p >
</ div >

يجب أن يستجيب الخادم بشظية HTML لاستبدال عنصر include-fragment . لا ينبغي أن يحتوي على عنصر تشمل آخر include-fragment أو سيتم استطلاع الخادم في حلقة لا حصر لها.

سمات أخرى

يقبل

تخبر هذه السمة <include-fragment/> ما الذي يجب إرساله كرأس Accept ، كجزء من طلب الجلب. إذا تم حذفه ، أو إذا تم ضبطه على قيمة فارغة ، فسيكون السلوك الافتراضي هو text/html . من المهم أن يستجيب الخادم بـ HTML ، ولكن قد ترغب في تغيير رأس قبول للمساعدة في التفاوض على المحتوى المناسب مع الخادم.

تحميل

هذا يشير إلى متى يجب جلب المحتويات:

eager : تجلب وتحميل المحتوى على الفور ، بغض النظر عما إذا كان <include-fragment/> موجود حاليًا في إطار العرض المرئي (هذه هي القيمة الافتراضية).
lazy : تجلب المشاهدات وتحميل المحتوى حتى تصل العلامة <include-fragment/> إلى مسافة محسوبة من منفذ العرض. القصد من ذلك هو تجنب عرض النطاق الترددي للتخزين اللازم للتعامل مع المحتوى حتى يكون من المؤكد بشكل معقول أنه ستكون هناك حاجة إليها.

الأخطاء

إذا فشل عنوان URL في التحميل ، يتم ترك عنصر include-fragment في الصفحة ووضع علامة عليه بفئة CSS is-error التي يمكن استخدامها للتصميم.

الأحداث

يتم إرسال أحداث دورة LIFEDECY على العنصر <include-fragment> .

loadstart - بدأ جلب الخادم.
load - تم الانتهاء من الطلب بنجاح.
error - فشل الطلب.
loadend - اكتمل الطلب.
include-fragment-replace (القابل للإلغاء)-تم تحليل استجابة النجاح. يأتي مع event.detail.fragment الذي سيحل محل العنصر الحالي.
include-fragment-replaced -تم استبدال العنصر بالجزء.

 const loader = document . querySelector ( 'include-fragment' )
const container = loader . parentElement
loader . addEventListener ( 'loadstart' , ( ) => container . classList . add ( 'is-loading' ) )
loader . addEventListener ( 'loadend' , ( ) => container . classList . remove ( 'is-loading' ) )
loader . addEventListener ( 'load' , ( ) => container . classList . add ( 'is-success' ) )
loader . addEventListener ( 'error' , ( ) => container . classList . add ( 'is-error' ) )

خيارات

يصف	خيارات	وصف
`src`	سلسلة URL	عنوان URL المطلوب من خلال تحميل شظية عنصر HTML البديلة.

التحميل المؤجل

يبدأ طلب الترميز البديل من الخادم عندما تصبح سمة src متاحة على عنصر <include-fragment> . غالبًا ما يحدث هذا في تحميل الصفحة عند تقديم العنصر. ومع ذلك ، إذا حذفنا سمة src حتى وقت لاحق ، فيمكننا تأجيل تحميل المحتوى على الإطلاق.

يستخدم عنصر <details-menu> هذه التقنية لتأجيل محتوى القائمة حتى يتم فتح القائمة لأول مرة.

أنماط

عادة ما يتم تأجيل عرض الترميز في أنماط الاستخدام التالية.

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

أنواع موثوق بها CSP

يمكنك استدعاء setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null) من JavaScript لتعيين سياسة أنواع موثوق بها CSP ، والتي يمكنها أداء (متزامن) تصفية أو رفض استجابة fetch قبل إدخاله في الصفحة:

 import IncludeFragmentElement from "include-fragment-element" ;
import DOMPurify from "dompurify" ; // Using https://github.com/cure53/DOMPurify

// This policy removes all HTML markup except links.
const policy = trustedTypes . createPolicy ( "links-only" , {
  createHTML : ( htmlText : string ) => {
    return DOMPurify . sanitize ( htmlText , {
      ALLOWED_TAGS : [ "a" ] ,
      ALLOWED_ATTR : [ "href" ] ,
      RETURN_TRUSTED_TYPE : true ,
    } ) ;
  } ,
} ) ;
IncludeFragmentElement . setCSPTrustedTypesPolicy ( policy ) ;

السياسة لديها إمكانية الوصول إلى كائن استجابة fetch . بسبب قيود النظام الأساسي ، يمكن استخدام المعلومات المتزامنة فقط من الاستجابة (بالإضافة إلى هيئة نص HTML) في السياسة:

 import IncludeFragmentElement from "include-fragment-element" ;

const policy = trustedTypes . createPolicy ( "require-server-header" , {
  createHTML : ( htmlText : string , response : Response ) => {
    if ( response . headers . get ( "X-Server-Sanitized" ) !== "sanitized=true" ) {
      // Note: this will reject the contents, but the error may be caught before it shows in the JS console.
      throw new Error ( "Rejecting HTML that was not marked by the server as sanitized." ) ;
    }
    return htmlText ;
  } ,
} ) ;
IncludeFragmentElement . setCSPTrustedTypesPolicy ( policy ) ;

لاحظ أن:

يمكن تعيين سياسة واحدة فقط ، تشترك في جميعها IncludeFragmentElement جلبات FragmentElement.
يجب عليك استدعاء setCSPTrustedTypesPolicy() قبل أي حمولة أخرى من include-fragment-element في الكود الخاص بك.
- إذا كانت سياستك نفسها تتطلب عملًا غير متزامن ، فيمكنك أيضًا تمرير Promise<TrustedTypePolicy> .
- تمرير null لإزالة السياسة.
لا تدعم جميع المتصفحات واجهة برمجة تطبيقات الأنواع الموثوق بها في JavaScript. قد ترغب في استخدام TinyFill الموصى به لإنشاء سياسة دون التسبب في مشكلات في المتصفحات الأخرى.

تتضمن العلاقة إلى جانب الخادم

يشبه هذا النهج التصريحي توجيهات SSI أو ESI. في الواقع ، يمكن أن يحل تطبيق الحافة محل الترميز قبل تسليمه فعليًا إلى العميل.

 < include-fragment src =" /github/include-fragment/commit-count " timeout =" 100 " >
  < p > Counting commits… </ p >
</ include-fragment >

قد يحاول الوكيل إحضار الشظية واستبدالها إذا انتهى الطلب قبل المهلة. وإلا يتم تسليم العلامة إلى العميل. هذه المكتبة تنفذ الجانب جانب العميل فقط.

دعم المتصفح

يتطلب المتصفحات بدون دعم العناصر المخصصة الأصلية polyfill. المتصفحات القديمة تتطلب العديد من الملفيات الأخرى. انظر examples/index.html للحصول على التفاصيل.