include fragment element - include fragment element

include fragment element

Kode sumber lainnya

v6.3.0

Unduh

<Incerted-Fragment> elemen

Sisi klien termasuk tag.

Instalasi

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

Penggunaan

Semua elemen include-fragment harus memiliki atribut src untuk mengambil fragmen elemen HTML.

Beban halaman awal harus menyertakan konten fallback untuk ditampilkan jika sumber daya tidak dapat segera diambil.

 import '@github/include-fragment-element'

Asli

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

Pada beban halaman, elemen include-fragment mengambil URL, responsnya diuraikan menjadi elemen HTML, yang menggantikan elemen include-fragment seluruhnya.

Hasil

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

Server harus merespons dengan fragmen HTML untuk menggantikan elemen include-fragment . Seharusnya tidak mengandung elemen include-fragment yang lain atau server akan disurvei dalam loop tak terbatas.

Atribut lainnya

menerima

Atribut ini memberi tahu <include-fragment/> apa yang harus dikirim sebagai header Accept , sebagai bagian dari permintaan pengambilan. Jika dihilangkan, atau jika diatur ke nilai kosong, perilaku default adalah text/html . Adalah penting bahwa server merespons dengan HTML, tetapi Anda mungkin ingin mengubah header ACCECT untuk membantu menegosiasikan konten yang tepat dengan server.

memuat

Ini menunjukkan kapan isinya harus diambil:

eager : Mengambil dan memuat konten segera, terlepas dari apakah <include-fragment/> saat ini berada dalam viewport yang terlihat (ini adalah nilai default).
lazy : Tahan mengambil dan memuat konten sampai tag <include-fragment/> mencapai jarak yang dihitung dari viewport. Maksudnya adalah untuk menghindari jaringan dan bandwidth penyimpanan yang diperlukan untuk menangani konten sampai cukup yakin bahwa itu akan diperlukan.

Kesalahan

Jika URL gagal memuat, elemen include-fragment dibiarkan di halaman dan ditandai dengan kelas CSS is-error yang dapat digunakan untuk penataan.

Acara

Acara siklus hidup permintaan dikirim pada elemen <include-fragment> .

loadstart - Fetch server telah dimulai.
load - permintaan berhasil diselesaikan.
error - Permintaan gagal.
loadend - Permintaan telah selesai.
include-fragment-replace (continable)-Respons keberhasilan telah diuraikan. Muncul dengan event.detail.fragment yang akan menggantikan elemen saat ini.
include-fragment-replaced -elemen telah digantikan oleh fragmen.

 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' ) )

Opsi

Atribut	Opsi	Keterangan
`src`	String url	URL yang diperlukan untuk memuat fragmen elemen HTML penggantian.

Pemuatan yang ditangguhkan

Permintaan untuk markup penggantian dari server dimulai ketika atribut src tersedia pada elemen <include-fragment> . Paling sering ini akan terjadi pada pemuatan halaman saat elemen diberikan. Namun, jika kita menghilangkan atribut src sampai beberapa waktu lagi, kita dapat menunda memuat konten sama sekali.

Elemen <details-menu> menggunakan teknik ini untuk menunda konten menu memuat sampai menu pertama kali dibuka.

Pola

Menunda tampilan markup biasanya dilakukan dalam pola penggunaan berikut.

Tindakan pengguna memulai pekerjaan latar belakang yang berjalan lambat di server, seperti mencadangkan file yang disimpan di server. Saat pekerjaan cadangan berjalan, bilah kemajuan ditampilkan kepada pengguna. Ketika selesai, elemen fragment termasuk diganti dengan tautan ke file cadangan.
Pertama kali pengguna mengunjungi halaman yang berisi markup yang memakan waktu untuk menghasilkan, indikator pemuatan ditampilkan. Ketika markup selesai dibangun di server, disimpan dalam memcache dan dikirim ke browser untuk mengganti loader sertakan fragment. Kunjungan berikutnya ke halaman membuat markup yang di-cache secara langsung, tanpa melalui elemen termasuk fragment.

Tipe tepercaya CSP

Anda dapat menghubungi setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null) dari JavaScript untuk menetapkan kebijakan tipe tepercaya CSP, yang dapat melakukan penyaringan atau penolakan dari respons fetch sebelum dimasukkan ke dalam halaman:

 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 ) ;

Kebijakan memiliki akses ke objek respons fetch . Karena kendala platform, hanya informasi sinkron dari respons (selain badan teks HTML) yang dapat digunakan dalam kebijakan:

 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 ) ;

Perhatikan bahwa:

Hanya satu kebijakan tunggal yang dapat ditetapkan, dibagikan oleh semua IncludeFragmentElement FetchesElement.
Anda harus menghubungi setCSPTrustedTypesPolicy() di depan beban lain dari include-fragment-element dalam kode Anda.
- Jika kebijakan Anda sendiri membutuhkan pekerjaan yang tidak sinkron untuk dibangun, Anda juga dapat memberikan Promise<TrustedTypePolicy> .
- Lewati null untuk menghapus kebijakan.
Tidak semua browser mendukung API tipe tepercaya di JavaScript. Anda mungkin ingin menggunakan tinyfill yang disarankan untuk membangun kebijakan tanpa menyebabkan masalah di browser lain.

Hubungan dengan sisi server termasuk

Pendekatan deklaratif ini sangat mirip dengan arahan SSI atau ESI. Bahkan, implementasi tepi dapat menggantikan markup sebelum benar -benar dikirimkan ke klien.

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

Proxy dapat mencoba mengambil dan mengganti fragmen jika permintaan selesai sebelum batas waktu. Kalau tidak, tag dikirim ke klien. Perpustakaan ini hanya mengimplementasikan aspek sisi klien.

Dukungan Browser

Browser tanpa dukungan elemen kustom asli memerlukan polyfill. Browser warisan membutuhkan berbagai polyfill lainnya. Lihat examples/index.html untuk detailnya.