Lewati ke konten

Mendaftarkan Aset

Blockstudio akan otomatis mengantrekan semua file yang berakhiran .css, .scss, dan .js saat blok Anda digunakan di halaman. Anda dapat menentukan cara aset diantrekan dengan menggunakan salah satu nama file berikut. * adalah wildcard yang dapat diganti dengan string pilihan Anda.

Di dalam file blok CSS dan SCSS, %selector% diperluas menjadi kelas wrapper yang memiliki cakupan untuk blok tersebut. Dengan begitu, Anda dapat menargetkan elemen yang sama dengan yang menerima bs_get_scoped_class(), meskipun file tersebut bukan aset dengan cakupan.

Pola Perilaku
*.(s)css Diantrekan sebagai tag <link> di editor dan frontend
*.inline.(s)css Konten diantrekan dalam tag <style> sebaris di editor dan frontend
*.editor.(s)css Diantrekan sebagai tag <link> hanya di editor
*.scoped.(s)css Konten dengan cakupan diantrekan dalam tag <style> sebaris di editor dan frontend
*.js Diantrekan sebagai tag <script> di editor dan frontend
*.inline.js Konten diantrekan dalam tag <script> sebaris di editor dan frontend
*.editor.js Diantrekan sebagai tag <script> hanya di editor
*.view.js Diantrekan sebagai tag <script> hanya di frontend

Catatan

Notasi tanda hubung (*-inline.css, *-editor.css, dan seterusnya) masih didukung untuk kompatibilitas ke belakang, tetapi sudah usang. Gunakan notasi titik untuk blok baru.

Sebaris

Style dan skrip sebaris memiliki keunggulan besar karena langsung dirender sebagai tag style atau script di dalam halaman. Ini dapat mempercepat pemuatan karena menghemat permintaan tambahan yang seharusnya diperlukan.

  • File .js disisipkan sebaris di akhir body
  • File .(s)css disisipkan sebaris di akhir head
  • Setiap file hanya disisipkan sebaris satu kali

Menyisipkan Stylesheet Kecil Secara Inline

File *.(s)css ditautkan secara default, sehingga memerlukan satu permintaan per file. Pengaturan assets.inlineLimit mencetak stylesheet kecil secara inline, mengikuti aturan yang diterapkan core WordPress pada gayanya sendiri: stylesheet blok eksternal pada halaman diurutkan dari yang terkecil hingga terbesar, lalu dicetak sebagai <style> selama total berjalannya masih dalam batas. Setiap file lainnya tetap menggunakan tag <link>.

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

Batasnya dinyatakan dalam byte dan 0, nilai default, menonaktifkan perilaku ini. Batas ini mengukur file terkompilasi yang akan dimuat oleh <link>, dalam keadaan diminifikasi jika assets.minify.css aktif. Hanya pilihan antara <link> dan <style> yang bergantung pada ukuran. Setiap tag tetap berada di tempat <link> seharusnya berada, sehingga urutan pemuatan dan cascade tidak berubah. Elemen tersebut tetap mempertahankan id-nya.

Pengaturan ini tidak berlaku untuk file *.inline.(s)css dan *.scoped.(s)css, yang selalu inline, untuk aset editor dan admin, atau untuk stylesheet yang diekstrak dari modul JavaScript yang diimpor. Stylesheet global dihitung seperti stylesheet blok. File tetap ditautkan setiap kali penyisipan inline akan mengubahnya:

  • File tersebut memuat URL relatif di url() atau @import, yang ditentukan berdasarkan stylesheet saat ditautkan dan berdasarkan halaman saat disisipkan secara inline. Path absolut, URL lengkap, URI data:, dan fragmen # tidak masalah.
  • File tersebut menggunakan image-set() atau berisi urutan penutup </style.
  • File tersebut berisi escape CSS, pembuka komentar HTML, atau deklarasi @charset. Demi kehati-hatian, file-file ini tetap ditautkan agar tidak berisiko mengubah URL atau penguraian dokumen.

Gunakan filter pengaturan untuk mengubah batas dari PHP:

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

CSS yang disisipkan secara inline menjadi bagian dari HTML halaman. Cache halaman harus dibersihkan setelah stylesheet berubah, dan browser tidak dapat menyimpan byte tersebut di cache untuk digunakan di halaman lain. Karena itu, batasnya dihitung sebagai total per halaman.

Dengan Cakupan

Style dengan cakupan juga disisipkan sebaris, tetapi diberi awalan ID unik untuk setiap blok. Gunakan fungsi bs_get_scoped_class untuk menambahkan kelas ke template Anda.

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

Hasilnya adalah style dengan cakupan berikut:

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 biasa di dalam file dengan cakupan tetap menargetkan turunan wrapper dengan cakupan tersebut. Gunakan %selector% jika Anda ingin menata wrapper itu sendiri.

Global

Selain aset khusus blok, Anda juga dapat mengantrekan aset global yang tersedia di semua halaman, terlepas dari ada tidaknya blok. Aset global diantrekan dengan menambahkan awalan global- ke nama file. Sufiks mana pun (e.g. -inline) dapat digunakan bersama awalan tersebut.

Kombinasi yang dapat digunakan:

  • 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

Admin

Aset admin hanya diantrekan di area admin WordPress. Awalan admin- digunakan untuk menentukan aset admin.

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

Editor Blok

Aset editor blok hanya diantrekan di editor blok. Awalan block-editor- digunakan untuk menentukan aset editor blok.

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

Catatan

Jika WordPress menonaktifkan iframe editor karena blok sisi klien didaftarkan dengan apiVersion di bawah 3, kanvas editor dan antarmuka admin WordPress menggunakan dokumen yang sama. Skrip global atau editor yang terikat pada window, document, body, peristiwa wheel, atau pengguliran dokumen harus menangani body.block-editor-page atau mengecualikan area editor WordPress seperti .interface-complementary-area dan .interface-navigable-region.

Urutan Pemuatan

Di frontend, dengan pengantrean aset otomatis dan buffering output aktif, Blockstudio menambahkan tag blok CSS <link> dan <style> ke halaman yang di-buffer tepat sebelum tag </head> penutup, alih-alih mendaftarkannya dengan wp_enqueue_style(). Karena itu, blok CSS muncul setelah stylesheet yang WordPress sudah cetak di head, termasuk style tema dan plugin yang diantrekan dengan wp_enqueue_style(), terlepas dari prioritas antrean atau dependensinya. Aset admin dan block-editor- menggunakan sistem antrean milik WordPress.

Untuk aturan dengan tingkat kepentingan, lapisan cascade, dan spesifisitas yang sama, stylesheet blok mengungguli stylesheet tema. Untuk mengubahnya, tingkatkan spesifisitas aturan tema, atau tambahkan stylesheet tema ke head Blockstudio yang dihasilkan melalui filter blockstudio/render/head. Konten yang ditambahkan oleh filter ditempatkan setelah aset blok. Keluarkan stylesheet tersebut dari antrean WordPress juga agar tidak dimuat dua kali.

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')) . '">';
});

Filter head hanya berjalan saat Blockstudio melakukan buffering halaman. Buffering dinonaktifkan pada pratinjau Customizer dan saat blockstudio/buffer/enabled mengembalikan false. bs_is_buffering() memberi tahu Anda kasus yang sedang berlaku, sehingga tema dapat menambahkan stylesheet melalui filter saat halaman di-buffer dan memasukkannya ke antrean dengan WordPress jika tidak. Jawabannya tersedia mulai dari wp_enqueue_scripts dan bernilai false sebelum template_redirect.

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

Gunakan blockstudio/buffer/output jika Anda perlu menyusun ulang dokumen akhir dengan cara lain.

Menonaktifkan Pengantrean

Pengantrean aset otomatis dapat dinonaktifkan menggunakan pengaturan assets/enqueue. Ini berguna jika Anda ingin menangani sendiri semua pengantrean aset.

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

Per Blok

Jika template blok tidak mengembalikan apa pun, Blockstudio tidak akan mengantrekan aset apa pun untuk blok tersebut. Cara ini berguna untuk menonaktifkan pengantrean saat kondisi tertentu terpenuhi.

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 %}