Menyesuaikan gaya dengan CSS

Aplikasi Blockly dibuat dari elemen HTML dan SVG. Elemen ini diberi label dengan class CSS yang mengidentifikasi apa yang diwakilinya (misalnya, blocklyBlock, blocklyField) serta statusnya (misalnya, blocklyEditing, blocklySelected). Blockly juga menyediakan serangkaian aturan CSS default.

Anda dapat menggunakan CSS untuk mendesain aplikasi:

• Ganti aturan CSS Blockly dengan aturan Anda sendiri.
• Tambahkan class CSS Anda sendiri ke komponen Blockly untuk spesifisitas tambahan.
• Gunakan class dan aturan CSS untuk menata gaya komponen kustom.

Catatan: Meskipun Blockly masih mendukung tema, cara yang lebih disukai untuk menata aplikasi Blockly adalah dengan CSS.

Class CSS

Aplikasi Blockly menggunakan class CSS untuk mengidentifikasi elemen yang akan diberi gaya. Hal ini memberikan kontrol yang lebih terperinci daripada pemilih jenis (elemen).

Class CSS Blockly

Blockly menggunakan class CSS untuk memberikan jenis informasi berikut tentang elemen HTML dan SVG yang digunakannya.

• Jenis. Sebagian besar class CSS Blockly mengidentifikasi apa yang direpresentasikan oleh suatu elemen. Misalnya, elemen root blok diberi label blocklyBlock. Beberapa elemen diberi label dengan beberapa class, yang masing-masing lebih spesifik daripada yang terakhir. Misalnya, elemen root kolom input teks diberi label blocklyField, blocklyInputField, dan blocklyTextInputField. Class jenis tetap sama selama masa aktif komponen.

• Negara bagian. Blockly juga menggunakan class CSS untuk menentukan status komponen. Misalnya, saat kursor berada di kolom input teks, elemen root-nya diberi label dengan class blocklyEditing. Saat kursor dipindahkan ke luar, kelas ini akan dihapus.

• Informasi tambahan. Blockly menggunakan beberapa class CSS untuk memberikan informasi tambahan. Misalnya, injeksi <div> memiliki class yang menyediakan nama tema dan perender saat ini di ruang kerja. Class ini umumnya tetap sama selama masa aktif aplikasi.

Cara termudah untuk mengetahui class CSS yang digunakan Blockly adalah dengan membuka alat developer browser dan memeriksa elemen yang digunakan oleh aplikasi Anda.

Class CSS kustom

Anda dapat menggunakan class CSS kustom untuk memberikan spesifisitas yang lebih besar pada komponen Blockly.

Ruang kerja

Untuk menambahkan atau menghapus class CSS dari injeksi <div> ruang kerja, panggil WorkspaceSvg.addClass atau WorkspaceSvg.removeClass.

Toolbox

Untuk menambahkan class CSS ke tombol atau label di toolbox, gunakan kunci web-class dalam definisi JSON toolbox Anda. Untuk mengetahui informasi selengkapnya, lihat Tombol dan label.

Untuk mengganti class CSS yang digunakan untuk berbagai bagian kategori, gunakan kunci cssConfig dalam definisi JSON kategori Anda. Hal ini memungkinkan Anda menata gaya setiap kategori. Untuk mengetahui informasi selengkapnya, lihat CSS Kategori.

Blok

Untuk menambahkan class CSS ke blok kustom, teruskan string atau array string ke kunci classes.

Blockly.common.defineBlocksWithJsonArray([{
  "type": "string_length",
  "message0": 'length of %1',
  "args0": [
    {
      "type": "input_value",
      "name": "VALUE",
      "check": "String",
    }
  ],
  "classes": "myStringLengthBlock",
  "output": "Number",
  "colour": 160,
}]);

Anda juga dapat menambahkan atau menghapus class CSS dari elemen <g> blok dengan memanggil BlockSvg.addClass atau BlockSvg.removeClass.

Kolom label

Untuk menambahkan atau menghapus class CSS dari elemen <text> yang digunakan oleh kolom label atau kolom label yang dapat diserialisasi, panggil FieldLabel.setClass. Anda juga dapat meneruskan nama class ke konstruktor label.

Class CSS dan komponen kustom

Saat membuat komponen kustom, gunakan salah satu metode berikut untuk menambahkan class CSS kustom:

• Jika komponen Anda adalah subclass dari Field atau Icon, ganti metode initView. Contoh:

  class MyCustomField extends Blockly.FieldTextInput {
    ...
  
    initView() {
      super.initView();
  
      // Add custom CSS class so we can style the field.
      if (this.fieldGroup_) {
        Blockly.utils.dom.addClass(this.fieldGroup_, 'myCustomField');
      }
    }
  }
  

  Untuk mengetahui informasi selengkapnya, lihat Menyesuaikan kolom dengan CSS atau Membuat tampilan ikon.

• Saat membuat elemen SVG, teruskan class Anda ke Blockly.utils.dom.createSvgElement:

  this.svgRoot = Blockly.utils.dom.createSvgElement(Svg.G, {'class': 'myCustomComponent'});
  

• Saat membuat elemen HTML, gunakan Blockly.utils.dom.addClass:

  const myDiv = document.createElement('div');
  Blockly.utils.dom.addClass(myDiv, 'myInformation');
  

Untuk menambahkan atau menghapus kelas setelah konstruksi, gunakan Blockly.utils.dom.addClass atau Blockly.utils.dom.removeClass.

setMyHighlight(highlight) {
  if (highlight) {
    Blockly.utils.dom.addClass(this.svgRoot, 'myHighlight');
  } else {
    Blockly.utils.dom.removeClass(this.svgRoot, 'myHighlight');
  }
}

Peringatan: Jangan gunakan dom.addClass atau dom.removeClass untuk menambahkan atau menghapus class dari komponen yang ditulis oleh orang lain, termasuk Blockly. Hal ini dapat menyebabkan hasil yang tidak dapat diprediksi.

Latar belakang aturan CSS

Jika Anda memahami properti gaya SVG dan susunan CSS, Anda dapat melewati bagian ini.

Properti gaya SVG versus properti CSS

Elemen SVG diberi gaya dengan properti gaya SVG. Atribut ini dapat digunakan sebagai atribut pada elemen SVG (alias atribut presentasi) atau dalam aturan CSS. Jadi, semua perintah berikut melakukan hal yang sama.

<!-- SVG file with presentation attributes. -->
<circle fill="red" ... />

<!-- SVG file with <style> tag. -->
<style>
  circle {fill:red;}
</style>
<circle ... />

/* External CSS file.*/
circle {fill:red;}

<!-- SVG file with inline style. -->
<circle style="fill:red;" ... />

Daftar properti gaya SVG terkait dengan, tetapi berbeda dari daftar properti CSS:

• Konsep yang sama, nama yang sama. Misalnya, SVG dan CSS menggunakan direction untuk menentukan apakah teks berjenis LTR atau RTL.
• Konsep yang sama, nama yang berbeda. Misalnya, SVG menggunakan fill untuk menentukan warna pengisi; CSS menggunakan background-color.
• Khusus CSS. CSS memiliki banyak properti yang tidak ada di SVG, seperti margin dan padding.
• Khusus SVG. SVG memiliki beberapa properti yang tidak ada di CSS, seperti x dan y.

Oleh karena itu, jika Anda menata gaya elemen SVG, gunakan properti penataan gaya SVG. Jika Anda menata gaya elemen HTML, gunakan properti CSS.

Cascading CSS

Cascading Style Sheets (CSS) menentukanprioritas aturan CSS, yang menentukan aturan mana yang akan digunakan jika lebih dari satu aturan berlaku untuk properti dan elemen tertentu. Cascade yang disederhanakan berikut mencakup bagian cascade yang paling umum digunakan oleh Blockly dan dapat membantu Anda menjawab pertanyaan, "Mengapa CSS saya tidak berfungsi?"

Cascading yang disederhanakan

Untuk menentukan aturan mana yang berlaku untuk elemen dan properti tertentu, ikuti langkah-langkah ini dan berhenti saat hanya ada satu aturan:

1. Kumpulkan semua aturan yang berlaku untuk properti dan elemen.
2. Jika ada aturan yang memiliki anotasi !important, hapus semua aturan yang tidak memiliki anotasi !important.

3. Pilih aturan dengan spesifisitas tertinggi.

   • Atribut presentasi SVG memiliki spesifisitas nol.
   • Aturan dalam tag <style> atau stylesheet eksternal memiliki spesifisitas yang dihitung secara normal.
   • Gaya inline (gaya yang ditetapkan oleh atribut style) memiliki spesifisitas yang lebih tinggi daripada pemilih mana pun.

4. Pilih aturan yang muncul terakhir dalam dokumen.

5. Jika tidak ada aturan yang berlaku, warisi nilai properti dari induk elemen.

Algoritma ini tidak mempertimbangkan bagian-bagian berikut dari cascade:

• Properti transition, yang memiliki prioritas tertinggi. Blockly menggunakan beberapa di antaranya.
• Aturan @ @media. Blockly menggunakan salah satunya.
• Aturan yang ditentukan oleh browser atau pengguna.
• Aturan @@scope dan @@layer serta properti animation, yang tidak digunakan oleh Blockly.

Aturan CSS

Aturan CSS menentukan gaya aplikasi Anda. Blockly menyediakan serangkaian aturan default yang dapat Anda ganti dengan aturan Anda sendiri.

Aturan CSS Blockly

Blockly menyediakan kumpulan aturan CSS default. Cara dan tempat aturan ini ditambahkan memengaruhi prioritasnya.

Tag gaya

Sebagian besar aturan CSS Blockly ditentukan dalam dua tag <style>. Karena tag ini muncul di dekat bagian atas halaman, aturan di dalamnya memiliki prioritas yang lebih rendah daripada aturan dengan spesifisitas yang sama yang muncul di bagian selanjutnya dalam halaman.

Aturan Blockly.css.register

Saat disisipkan, Blockly akan menambahkan tag <style> sebagai turunan tag <head>. Aturan dalam tag ini berasal dari:

• Namespace Blockly.css. Untuk melihat aturan ini, buka core/css.ts dan cari let content.
• Komponen individual, yang memanggil Blockly.css.register untuk menambahkan aturan CSS khusus komponen. Karena css.register menambahkan aturan ini ke akhir string content, aturan ini memiliki prioritas yang lebih tinggi daripada aturan dengan spesifisitas yang sama yang ditambahkan sebelumnya. Untuk melihat aturan ini, lihat panggilan ke Blockly.css.register.

Jika Anda tidak ingin menggunakan aturan ini, tetapkan opsi konfigurasi css ke false. Dalam hal ini, Anda bertanggung jawab untuk menyediakan kumpulan aturan CSS alternatif.

Aturan perender

Saat di-instantiate, perender akan menambahkan tag <style> yang berisi aturan CSS khusus perender sebagai turunan tag <head>. Perhatikan bahwa aturan ini selalu ditambahkan -- tidak terpengaruh oleh opsi konfigurasi css. Untuk melihat aturan ini, telusuri metode getCss_ di perender Anda.

Gaya inline

Gaya inline ditentukan dengan atribut style dan umumnya dibuat saat DOM untuk komponen dibuat. Untuk daftar sebagian, lihat kueri GitHub ini.

Gaya inline diterapkan langsung ke elemen tempat gaya tersebut muncul dan memiliki spesifisitas yang lebih tinggi daripada pemilih mana pun. Oleh karena itu, untuk menggantinya, Anda umumnya harus menggunakan anotasi !important.

Atribut presentasi SVG

Atribut presentasi SVG adalah properti gaya SVG yang digunakan sebagai atribut elemen SVG. Aturan ini memiliki spesifisitas nol dan tidak boleh berisi anotasi !important, sehingga memiliki prioritas terendah dari semua aturan Blockly. Blockly umumnya membuatnya dalam panggilan ke createSvgElement.

Menambahkan aturan CSS Anda sendiri

Anda dapat menambahkan aturan CSS Anda sendiri menggunakan metode yang sama seperti Blockly:

• Panggil Blockly.css.register sebelum menyuntikkan Blockly. Aturan Anda akan ditambahkan setelah Blockly dan memiliki prioritas yang lebih tinggi daripada aturan Blockly dengan spesifisitas yang sama.
• Tambahkan tag <style> atau tautkan ke lembar gaya eksternal sebagai turunan terakhir dari tag <head>. Karena Blockly menambahkan aturannya sebagai dua turunan pertama dari tag <head>, aturan Anda akan memiliki prioritas yang lebih tinggi daripada aturan Blockly dengan spesifisitas yang sama.
• Gunakan gaya inline untuk menambahkan gaya ke elemen dalam komponen kustom. Aturan ini akan memiliki kekhususan yang lebih tinggi daripada aturan apa pun dengan pemilih.
• Gunakan atribut presentasi pada elemen SVG dalam komponen kustom. Aturan ini akan memiliki spesifisitas yang lebih rendah daripada aturan apa pun dengan pemilih.

Pemecahan masalah

Jika CSS Anda tidak berfungsi, berikut beberapa kemungkinan penyebabnya:

• Anda menggunakan properti CSS pada elemen SVG atau properti gaya SVG pada elemen HTML. Lihat properti gaya SVG versus properti CSS.

• Aturan Anda memiliki prioritas yang lebih rendah daripada aturan lain. Hal ini biasanya disebabkan oleh spesifisitas yang lebih rendah. Berikut kemungkinan cara untuk memperbaikinya:

  • Gunakan pemilih class, bukan pemilih jenis (elemen).
  • Gunakan beberapa pemilih.
  • Jika memungkinkan, tambahkan class kustom ke elemen target dan gunakan class ini dalam aturan Anda.
  • Sebagai upaya terakhir, tambahkan anotasi !important ke aturan Anda. Ini adalah satu-satunya pilihan Anda jika aturan yang bersaing ditentukan menggunakan gaya inline (atribut style).

• Aturan Anda memiliki spesifisitas yang sama dengan aturan lain, tetapi muncul lebih awal di halaman. Jika Anda tidak dapat meningkatkan spesifisitas aturan, pindahkan aturan tersebut ke bagian bawah halaman.

Ada dua jenis aturan CSS yang tidak dapat Anda ganti:

• Properti yang ditetapkan di dalam aturan transition.
• Aturan !important yang ditentukan oleh browser.