コンテンツへスキップ

アセットの登録

Blockstudioは、ブロックがページで使われるときに、.css、.scss、.jsで終わるファイルをすべて自動的に読み込みます。以下のいずれかのファイル名を使って、アセットの読み込み方法を指定できます。*はワイルドカードで、任意の文字列に置き換えられます。

ブロックのCSSファイルとSCSSファイル内では、%selector%はブロック固有のラッパークラスに展開されます。これにより、そのファイルがスコープ付きアセットでなくても、bs_get_scoped_class()が適用される要素を指定できます。

パターン 動作
*.(s)css エディターとフロントエンドで<link>タグとして読み込む
*.inline.(s)css エディターとフロントエンドで内容をインラインの<style>タグとして読み込む
*.editor.(s)css エディターのみで<link>タグとして読み込む
*.scoped.(s)css エディターとフロントエンドでスコープ付きの内容をインラインの<style>タグとして読み込む
*.js エディターとフロントエンドで<script>タグとして読み込む
*.inline.js エディターとフロントエンドで内容をインラインの<script>タグとして読み込む
*.editor.js エディターのみで<script>タグとして読み込む
*.view.js フロントエンドのみで<script>タグとして読み込む

注

*-inline.css、*-editor.cssなどのダッシュ形式も後方互換性のため引き続き使えますが、非推奨です。新しいブロックではドット形式を使用してください。

インライン

インラインのスタイルとスクリプトは、ページ内のstyleタグまたはscriptタグとして直接出力されます。そのため、本来必要となる追加リクエストを省き、読み込み時間を短縮できます。

  • .jsファイルはbodyの末尾にインラインで挿入されます
  • .(s)cssファイルはheadの末尾にインラインで挿入されます
  • 各ファイルは一度だけインライン挿入されます

小さなスタイルシートをインライン化する

*.(s)cssファイルはデフォルトでリンクされるため、ファイルごとに1回のリクエストが発生します。assets.inlineLimit設定を使うと、小さなスタイルシートをインラインで出力します。これは、WordPressが独自のスタイルに適用するルールに従います。ページの外部ブロックスタイルシートをサイズの小さい順に取り出し、合計が上限内に収まる間は<style>として出力します。それ以外のファイルはすべて<link>タグを維持します。

JSON
{
  "assets": {
    "inlineLimit": 40000
  }
}

上限の単位はバイトです。デフォルトの0では、この動作は無効になります。サイズは<link>が読み込むコンパイル済みファイルで測定され、assets.minify.cssが有効な場合は圧縮後のサイズになります。サイズによって変わるのは<link>と<style>のどちらを選ぶかだけです。各タグは<link>が配置されるはずの位置に残るため、読み込み順とカスケードは変わりません。要素のidも維持されます。

この設定は、常にインラインになる*.inline.(s)cssファイルと*.scoped.(s)cssファイル、エディターおよび管理画面のアセット、インポートされたJavaScriptモジュールから抽出されたスタイルシートには適用されません。グローバルスタイルシートはブロックスタイルシートと同様に数えられます。インライン化すると変更が生じる場合は、ファイルはリンクされたままになります。

  • url()または@import内に相対URLが含まれています。リンク時はスタイルシートを基準に、インライン時はページを基準に解決されます。絶対パス、完全なURL、data: URI、#フラグメントは問題ありません。
  • image-set()を使用しているか、閉じる</styleシーケンスが含まれています。
  • CSSエスケープ、HTMLコメント開始子、または@charset宣言が含まれています。変更されたURLやドキュメントの解析に影響するリスクを避けるため、これらのファイルは安全側に倒してリンクされたままにします。

設定フィルターを使って、上限をPHPから変更します。

PHP
add_filter('blockstudio/settings/assets/inline_limit', fn() => 40000);

インライン化されたCSSはページのHTMLの一部になります。スタイルシートを変更した後はページキャッシュを消去する必要があり、ブラウザーはページ間でそのバイト列をキャッシュできません。そのため、上限はページごとの合計です。

スコープ付き

スコープ付きスタイルもインラインで挿入されますが、各ブロック固有のIDが先頭に付加されます。bs_get_scoped_class関数を使ってテンプレートにクラスを追加してください。

PHP
<section class="hero <?php echo bs_get_scoped_class($b['name']); ?>">
  <h1 class="hero__title">Scope me!</h1>
</section>
CSS
%selector% {
  --hero-gap: var(--wp--preset--spacing--space-10);
}

%selector%.hero {
  border-bottom: 1px solid currentColor;
}

.hero__title {
  color: red;
}

上記の結果、次のスコープ付きスタイルが生成されます:

HTML
<style>
  .bs-62df71e6cc9a {
    --hero-gap: var(--wp--preset--spacing--space-10);
  }

  .bs-62df71e6cc9a.hero {
    border-bottom: 1px solid currentColor;
  }

  .bs-62df71e6cc9a .hero__title {
    color: red;
  }
</style>

<section class="hero bs-62df71e6cc9a">
  <h1 class="hero__title">Scope me!</h1>
</section>

スコープ付きファイル内の通常のセレクターは、引き続きスコープ付きラッパーの子孫要素を対象にします。ラッパー自体にスタイルを適用するには%selector%を使用してください。

グローバル

ブロック固有のアセットに加えて、ブロックの有無にかかわらずすべてのページで使えるグローバルアセットも読み込めます。ファイル名にglobal-プレフィックスを付けると、グローバルアセットになります。任意のサフィックス(e.g、-inline)を組み合わせて使用できます。

使用できる組み合わせは次のとおりです:

  • global-styles.(s)css
  • global-styles.inline.(s)css
  • global-styles.editor.(s)css
  • global-styles.scoped.(s)css
  • global-scripts.js
  • global-scripts.inline.js
  • global-scripts.editor.js
  • global-scripts.view.js

管理画面

管理画面用アセットはWordPress管理画面でのみ読み込まれます。admin-プレフィックスで管理画面用アセットを指定します。

  • admin-styles.(s)css
  • admin-scripts.js

ブロックエディター

ブロックエディター用アセットはブロックエディターでのみ読み込まれます。block-editor-プレフィックスでブロックエディター用アセットを指定します。

  • block-editor-styles.(s)css
  • block-editor-scripts.js

注

クライアント側ブロックが3未満のapiVersionで登録されているためにWordPressがエディターのiframeを無効にすると、エディターのキャンバスとWordPress管理画面のUIは同じドキュメントを共有します。グローバルスクリプトやエディタースクリプトでwindow、document、body、ホイールイベント、またはドキュメントのスクロールを扱う場合は、body.block-editor-pageを避ける処理を入れるか、.interface-complementary-areaや.interface-navigable-regionなどのWordPressエディター領域を対象外にしてください。

読み込み順序

フロントエンドでアセットの自動読み込みと出力バッファリングが有効な場合、BlockstudioはブロックのCSS、<link>、<style>タグを</head>終了タグの直前でバッファリング中のページに追加します。wp_enqueue_style()には登録しません。そのため、ブロックのCSSは、wp_enqueue_style()で読み込まれたテーマやプラグインのスタイルを含め、WordPressがheadにすでに出力したスタイルシートの後に配置されます。読み込み優先度や依存関係は影響しません。管理画面とblock-editor-のアセットには、代わりにWordPressの読み込みシステムが使われます。

重要度、カスケードレイヤー、詳細度が同じルールでは、ブロックのスタイルシートがテーマのスタイルシートより優先されます。これを変更するには、テーマルールの詳細度を上げるか、Blockstudioが生成するheadにテーマのスタイルシートを追加します。blockstudio/render/headフィルターで追加したコンテンツは、ブロックのアセットの後に配置されます。スタイルシートが二重に読み込まれないよう、WordPressからもキューを解除してください。

PHP
add_action('wp_enqueue_scripts', function() {
  wp_dequeue_style('theme-overrides');
}, 100);

add_filter('blockstudio/render/head', function($head) {
  return $head . '<link rel="stylesheet" href="' . esc_url(get_theme_file_uri('overrides.css')) . '">';
});

headフィルターは、Blockstudioがページをバッファリングするときにのみ実行されます。カスタマイザーのプレビュー中、およびblockstudio/buffer/enabledがfalseを返す場合は、バッファリングされません。bs_is_buffering()で該当する状況を確認できます。ページがバッファリングされるときはテーマからフィルター経由でスタイルシートを追加し、それ以外の場合はWordPressでエンキューできます。結果はwp_enqueue_scripts以降に利用でき、template_redirectより前にはfalseです。

PHP
add_action('wp_enqueue_scripts', function() {
  $url = get_theme_file_uri('overrides.css');

  if (bs_is_buffering()) {
    add_filter('blockstudio/render/head', function($head) use ($url) {
      return $head . '<link rel="stylesheet" href="' . esc_url($url) . '">';
    });
    return;
  }

  wp_enqueue_style('theme-overrides', $url);
});

最終的なドキュメントの構成を別の方法で変更する必要がある場合は、blockstudio/buffer/outputを使用してください。

読み込みを無効にする

assets/enqueue設定でアセットの自動読み込みを無効にできます。すべてのアセットを自分で読み込みたい場合に便利です。

PHP
add_filter('blockstudio/settings', function($settings) {
  $settings['assets']['enqueue'] = false;
  return $settings;
});

ブロック単位

ブロックのテンプレートが何も返さない場合、Blockstudioはそのブロックのアセットを読み込みません。特定の条件が成立したときに読み込みを無効にするのに便利です。

PHP

PHP
<?php
  if ( !$a['slides'] ) {
    // or return '';
    return false;
  }
?>

<div>my slider</div>

Twig

Twig
{% if not a.slides %}
  <div>my slider</div>
{% endif %}