include fragment element

<include-fragment>要素

クライアント側にはタグが含まれています。

インストール

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

使用法

すべてのinclude-fragment要素には、HTML要素フラグメントを取得するためのsrc属性が必要です。

最初のページのロードには、リソースをすぐにフェッチできない場合は、表示するフォールバックコンテンツを含める必要があります。

 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 >

サーバーは、 include-fragment要素を交換するためにHTMLフラグメントで応答する必要があります。別のinclude-fragment要素を含めるべきではないか、サーバーが無限のループでポーリングされます。

その他の属性

受け入れる

この属性は<include-fragment/> fetchリクエストの一部として、 Acceptヘッダーとして送信するものを伝えます。省略した場合、または空の値に設定されている場合、デフォルトの動作はtext/htmlになります。サーバーがHTMLで応答することが重要ですが、サーバーとの適切なコンテンツの交渉を支援するために、受け入れヘッダーを変更することをお勧めします。

読み込み

これは、コンテンツをいつ取得するかを示します。

• eager ： <include-fragment/>現在表示可能なビューポート内にあるかどうかに関係なく、コンテンツをすぐにフェッチしてロードします（これはデフォルト値です）。
• lazy ： <include-fragment/>タグがビューポートから計算された距離に達するまで、コンテンツを取得してロードするdefers。目的は、コンテンツが必要になることが合理的に確実になるまで、コンテンツを処理するために必要なネットワークとストレージの帯域幅を回避することです。

エラー

URLがロードに失敗した場合、 include-fragment要素はページに残り、スタイリングに使用できるis-error CSSクラスでタグ付けされます。

イベント

リクエストライフサイクルイベントは、 <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文字列	交換用HTML要素フラグメントをロードするために必要なURL。

繰延荷重

サーバーからの交換マークアップのリクエストは、 <include-fragment>要素でsrc属性が使用可能になると開始されます。ほとんどの場合、これは要素がレンダリングされたときにページロードで発生します。ただし、 src属性を後で省略した場合、コンテンツのロードを延期することができます。

<details-menu>要素は、この手法を使用して、メニューが最初に開かれるまでメニューコンテンツの読み込みを延期します。

パターン

マークアップの表示を延期することは、通常、次の使用パターンで行われます。

• ユーザーのアクションは、サーバーに保存されているファイルをバックアップするなど、サーバー上のバックグラウンドジョブが遅いことを開始します。バックアップジョブが実行されている間、ユーザーに進行状況バーが表示されます。それが完了すると、インクルードフラグメント要素はバックアップファイルへのリンクに置き換えられます。

• ユーザーが生成するために時間のかかるマークアップを含むページに初めてアクセスしたとき、ロードインジケーターが表示されます。マークアップがサーバー上に構築が完了すると、Memcacheに保存され、ブラウザに送信されて、インクルードフラグメントローダーを置き換えます。その後のページへの訪問は、挿入要素を使用することなく、キャッシュされたマークアップを直接レンダリングします。

CSP信頼されたタイプ

javascriptからsetCSPTrustedTypesPolicy(policy: TrustedTypePolicy | Promise<TrustedTypePolicy> | null)を呼び出すには、ページに挿入される前に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 Fetchesが共有する1つのポリシーのみを設定できます。
• コードにinclude-fragment-elementの他の負荷よりも先にsetCSPTrustedTypesPolicy()を呼び出す必要があります。
  • ポリシー自体が非同期作業を構築する必要がある場合は、 Promise<TrustedTypePolicy>を渡すこともできます。
  • nullを渡してポリシーを削除します。
• すべてのブラウザがJavaScriptの信頼できるタイプAPIをサポートするわけではありません。他のブラウザで問題を引き起こすことなく、推奨されるTinyFillを使用してポリシーを構築することをお勧めします。

サーバー側との関係が含まれます

この宣言的アプローチは、SSIまたはESI指令に非常に似ています。実際、エッジの実装は、実際にクライアントに配信される前にマークアップを置き換えることができます。

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

プロキシは、タイムアウトの前にリクエストが終了した場合、フラグメントを取得して交換しようとする場合があります。それ以外の場合、タグはクライアントに配信されます。このライブラリは、クライアント側の側面のみを実装します。

ブラウザのサポート

ネイティブのカスタム要素サポートのないブラウザには、ポリフィルが必要です。レガシーブラウザには、他のさまざまなポリフィルが必要です。詳細については、 examples/index.html参照してください。

• クロム
• Firefox
• サファリ
• Microsoft Edge

発達

 npm install
npm test

ライセンス

MITライセンスの下で配布されます。詳細については、ライセンスを参照してください。