include fragment element - include fragment element

include fragment element

Autre code source

v6.3.0

Télécharger

élément <clut-fragment>

Un côté client comprend la balise.

Installation

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

Usage

Tous les éléments include-fragment doivent avoir un attribut src à partir de laquelle récupérer un fragment d'élément HTML.

La charge de page initiale doit inclure le contenu de secours à afficher si la ressource ne pouvait pas être récupérée immédiatement.

 import '@github/include-fragment-element'

Original

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

À la charge de la page, l'élément include-fragment obtient l'URL, la réponse est analysée dans un élément HTML, qui remplace entièrement l'élément include-fragment .

Résultat

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

Le serveur doit répondre avec un fragment HTML pour remplacer l'élément include-fragment . Il ne doit pas contenir un autre élément include-fragment ou le serveur sera interrogé dans une boucle infinie.

Autres attributs

accepter

Cet attribut indique <include-fragment/> quoi envoyer comme en-tête Accept , dans le cadre de la demande de fetch. S'il est omis, ou s'il est défini sur une valeur vide, le comportement par défaut sera text/html . Il est important que le serveur réponde avec HTML, mais vous souhaiterez peut-être modifier l'en-tête d'accepter pour aider à négocier le bon contenu avec le serveur.

chargement

Cela indique quand le contenu doit être récupéré:

eager : récupérez et chargez le contenu immédiatement, que le <include-fragment/> soit actuellement dans la fenêtre visible (il s'agit de la valeur par défaut).
lazy : les répondent à la récupération et au chargement du contenu jusqu'à ce que la balise <include-fragment/> atteigne une distance calculée de la fenêtre. L'intention est d'éviter le réseau et la bande passante de stockage nécessaire pour gérer le contenu jusqu'à ce qu'il soit raisonnablement certain qu'il sera nécessaire.

Erreurs

Si l'URL ne se charge pas, l'élément include-fragment est laissé dans la page et tagué avec une classe CSS is-error qui peut être utilisée pour le style.

Événements

Les événements de cycle de vie de demande sont envoyés sur l'élément <include-fragment> .

loadstart - le serveur Fetch a commencé.
load - la demande terminée avec succès.
error - La demande a échoué.
loadend - La demande est terminée.
include-fragment-replace (annule) - La réponse du succès a été analysée. Il est livré avec event.detail.fragment qui remplacera l'élément actuel.
include-fragment-replaced - L'élément a été remplacé par le fragment.

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

Options

Attribut	Options	Description
`src`	Chaîne d'URL	URL requise à partir de laquelle charger le fragment de l'élément HTML de remplacement.

Chargement différé

La demande de balisage de remplacement du serveur démarre lorsque l'attribut src devient disponible sur l'élément <include-fragment> . Le plus souvent, cela se produira au chargement de la page lorsque l'élément est rendu. Cependant, si nous omettons l'attribut src jusqu'à une fois plus tard, nous pouvons différer le chargement du contenu.

L'élément <details-menu> utilise cette technique pour différer le contenu du menu de chargement jusqu'à l'ouverture du menu.

Motifs

Le report de l'affichage du balisage est généralement effectué dans les modèles d'utilisation suivants.

Une action utilisateur commence un travail en arrière-plan en cours d'exécution sur le serveur, comme le sauvegarde des fichiers stockés sur le serveur. Pendant que le travail de sauvegarde est en cours d'exécution, une barre de progression est indiquée à l'utilisateur. Une fois terminé, l'élément incluant est remplacé par un lien vers les fichiers de sauvegarde.
La première fois qu'un utilisateur visite une page qui contient un élément de balisage qui prend du temps à générer, un indicateur de chargement s'affiche. Lorsque le balisage est terminé de construire sur le serveur, il est stocké dans Memcache et envoyé au navigateur pour remplacer le chargeur de fragment inclué. Les visites ultérieures de la page rendent directement le balisage mis en cache, sans passer par un élément de fragment inclué.

Types de confiance CSP

Vous pouvez appeler setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null) de JavaScript pour définir une politique de type CSP de confiance, qui peut effectuer un filtrage ou un rejet (synchrone) de la réponse fetch avant qu'il ne soit inséré dans la page:

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

La stratégie a accès à l'objet de réponse fetch . En raison des contraintes de plate-forme, seules les informations synchrones de la réponse (en plus du corps de texte HTML) peuvent être utilisées dans la politique:

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

Noter que:

Une seule stratégie peut être définie, partagée par toutes les réchauffeurs IncludeFragmentElement .
Vous devez appeler setCSPTrustedTypesPolicy() avant toute autre charge d' include-fragment-element dans votre code.
- Si votre politique elle-même nécessite un travail asynchrone à construire, vous pouvez également transmettre une Promise<TrustedTypePolicy> .
- Passer null pour supprimer la politique.
Tous les navigateurs ne prennent pas en charge l'API Types de confiance en JavaScript. Vous voudrez peut-être utiliser le TinyFill recommandé pour construire une politique sans causer de problèmes dans d'autres navigateurs.

La relation avec le côté serveur comprend

Cette approche déclarative est très similaire aux directives SSI ou ESI. En fait, une implémentation de bord pourrait remplacer le balisage avant qu'elle ne soit réellement livrée au client.

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

Un proxy peut tenter de récupérer et de remplacer le fragment si la demande se termine avant le délai d'attente. Sinon, la balise est livrée au client. Cette bibliothèque n'implémente que l'aspect côté client.

Support de navigateur

Les navigateurs sans support d'élément personnalisé natif nécessitent un polyfill. Les navigateurs hérités nécessitent divers autres polyfills. Voir examples/index.html pour plus de détails.