include fragment element

<dunciw-fragment> elemento

Um lado do cliente inclui tag.

Instalação

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

Uso

Todos os elementos include-fragment um atributo src para recuperar um fragmento de elemento HTML.

A carga inicial da página deve incluir conteúdo de fallback a ser exibido se o recurso não puder ser buscado imediatamente.

 import '@github/include-fragment-element'

Original

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

Na carregamento da página, o elemento include-fragment inclui o URL, a resposta é analisada em um elemento HTML, que substitui completamente o elemento include-fragment .

Resultado

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

O servidor deve responder com um fragmento HTML para substituir o elemento include-fragment . Ele não deve conter outro elemento include-fragment ou o servidor será pesquisado em um loop infinito.

Outros atributos

aceitar

Este atributo informa <include-fragment/> o que enviar como cabeçalho Accept , como parte da solicitação de busca. Se omitido ou se definido como um valor vazio, o comportamento padrão será text/html . É importante que o servidor responda com HTML, mas você pode alterar o cabeçalho Aceitar para ajudar a negociar o conteúdo certo com o servidor.

carregando

Isso indica quando o conteúdo deve ser buscado:

• eager : busca e carregue o conteúdo imediatamente, independentemente de estar ou não o <include-fragment/> estar ou não dentro da viewport visível (este é o valor padrão).
• lazy : adiadores buscando e carregando o conteúdo até que a tag <include-fragment/> atinja uma distância calculada da visualização. A intenção é evitar a rede e a largura de banda de armazenamento necessárias para lidar com o conteúdo até que seja razoavelmente certo de que será necessário.

Erros

Se o URL não conseguir carregar, o elemento include-fragment na página e marcado com uma classe CSS is-error que pode ser usada para estilo.

Eventos

Os eventos do ciclo de vida solicitados são despachados no elemento <include-fragment> .

• loadstart - o servidor Fetch foi iniciado.
• load - a solicitação foi concluída com sucesso.
• error - a solicitação falhou.
• loadend - a solicitação foi concluída.
• include-fragment-replace (cancelável)-A resposta de sucesso foi analisada. Ele vem com event.detail.fragment que substituirá o elemento atual.
• include-fragment-replaced -o elemento foi substituído pelo fragmento.

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

Opções

Atributo	Opções	Descrição
src	String de URL	URL necessário para carregar o fragmento de elemento HTML de substituição.

Carregamento diferido

A solicitação de marcação de substituição do servidor é iniciada quando o atributo src fica disponível no elemento <include-fragment> . Na maioria das vezes, isso acontecerá no carregamento da página quando o elemento for renderizado. No entanto, se omitirmos o atributo src até algum tempo posterior, podemos adiar o carregamento do conteúdo.

O elemento <details-menu> usa essa técnica para adiar o conteúdo do menu de carregamento até que o menu seja aberto pela primeira vez.

Padrões

A adição da exibição de marcação é normalmente feita nos seguintes padrões de uso.

• Uma ação do usuário inicia um trabalho de segundo plano lento no servidor, como backup de arquivos armazenados no servidor. Enquanto o trabalho de backup está em execução, uma barra de progresso é mostrada ao usuário. Quando está completo, o elemento de fragmentação incluído é substituído por um link para os arquivos de backup.

• Na primeira vez em que um usuário visita uma página que contém uma peça de marcação demorada para gerar, um indicador de carregamento é exibido. Quando a marcação termina de construção no servidor, ele é armazenado em Memcache e enviado ao navegador para substituir o carregador de documentos incluídos. As visitas subsequentes à página renderizam a marcação em cache diretamente, sem passar por um elemento de fragmentação incluído.

Tipos confiáveis ​​do CSP

Você pode chamar setCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null) do JavaScript para definir uma política de tipos confiáveis ​​do CSP, que pode executar a filtragem (síncrona) ou a rejeição da resposta fetch antes de ser inserida na página:

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

A política tem acesso ao objeto de resposta fetch . Devido a restrições da plataforma, apenas informações síncronas da resposta (além do corpo de texto HTML) podem ser usadas na política:

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

Observe que:

• Somente uma única política pode ser definida, compartilhada por todos IncludeFragmentElement busca.
• Você deve chamar setCSPTrustedTypesPolicy() à frente de qualquer outra carga de include-fragment-element em seu código.
  • Se sua própria política exigir um trabalho assíncrono para construir, você também pode aprovar uma Promise<TrustedTypePolicy> .
  • Passe null para remover a política.
• Nem todos os navegadores suportam a API de tipos confiáveis ​​em JavaScript. Você pode usar o Tinyfill recomendado para construir uma política sem causar problemas em outros navegadores.

A relação com o lado do servidor inclui

Essa abordagem declarativa é muito semelhante às diretivas SSI ou ESI. De fato, uma implementação de borda pode substituir a marcação antes de ser entregue ao cliente.

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

Um proxy pode tentar buscar e substituir o fragmento se a solicitação terminar antes do tempo limite. Caso contrário, a tag será entregue ao cliente. Esta biblioteca implementa apenas o aspecto do lado do cliente.

Suporte do navegador

Os navegadores sem suporte a elementos personalizados nativos requerem um poli -preenchimento. Os navegadores herdados requerem vários outros poli -preenchimentos. Consulte examples/index.html para obter detalhes.

• Cromo
• Firefox
• Safári
• Microsoft Edge

Desenvolvimento

 npm install
npm test

Licença

Distribuído sob a licença do MIT. Consulte a licença para obter detalhes.