使用 CSS 設定樣式

Blockly 應用程式是由 HTML 和 SVG 元素建構而成。這些元素會標示 CSS 類別，用來識別代表的內容 (例如 blocklyBlock、blocklyField) 和狀態 (例如 blocklyEditing、blocklySelected)。Blockly 也提供一組預設的 CSS 規則。

您可以使用 CSS 設定應用程式樣式：

• 使用自己的規則覆寫 Blockly 的 CSS 規則。
• 在 Blockly 元件中加入自己的 CSS 類別，進一步指定樣式。
• 使用 CSS 類別和規則設定自訂元件的樣式。

注意： 雖然 Blockly 仍支援主題，但建議使用 CSS 設定 Blockly 應用程式的樣式。

CSS 類別

Blockly 應用程式會使用 CSS 類別來識別要設定樣式的元素。相較於類型 (元素) 選取器，這個選項可提供更精細的控制。

Blockly CSS 類別

Blockly 會使用 CSS 類別，提供所用 HTML 和 SVG 元素的下列資訊。

• 類型。大多數 Blockly CSS 類別都會識別元素代表的內容。舉例來說，區塊的根元素標示為 blocklyBlock。有些元素會標示多個類別，每個類別都比上一個更具體。舉例來說，文字輸入欄位的根元素會標示為 blocklyField、blocklyInputField 和 blocklyTextInputField。元件的生命週期內，型別類別會維持不變。

• 州/省。Blockly 也會使用 CSS 類別指定元件的狀態。舉例來說，當游標位於文字輸入欄位時，其根元素會標示 blocklyEditing 類別。游標移開時，這個類別就會移除。

• 其他資訊。Blockly 會使用幾個 CSS 類別來提供額外資訊。舉例來說，注入的 <div> 具有可提供工作區目前算繪器和主題名稱的類別。這些類別通常在應用程式的生命週期內保持不變。

如要輕鬆找出 Blockly 使用的 CSS 類別，請開啟瀏覽器的開發人員工具，並檢查應用程式使用的元素。

自訂 CSS 類別

您可以使用自訂 CSS 類別，為 Blockly 元件提供更多具體性。

工作區

如要從工作區的插入 <div> 新增或移除 CSS 類別，請呼叫 WorkspaceSvg.addClass 或 WorkspaceSvg.removeClass。

工具箱

如要在工具箱中的按鈕或標籤新增 CSS 類別，請在工具箱的 JSON 定義中使用 web-class 鍵。詳情請參閱「按鈕和標籤」。

如要覆寫用於類別各部分的 CSS 類別，請在類別的 JSON 定義中使用 cssConfig 鍵。這樣一來，您就能為個別類別設定樣式。詳情請參閱類別 CSS。

阻攻次數

如要將 CSS 類別新增至自訂區塊，請將字串或字串陣列傳遞至 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,
}]);

您也可以呼叫 BlockSvg.addClass 或 BlockSvg.removeClass，從區塊的 <g> 元素新增或移除 CSS 類別。

標籤欄位

如要從標籤欄位或可序列化標籤欄位使用的 <text> 元素新增或移除 CSS 類別，請呼叫 FieldLabel.setClass。您也可以將類別名稱傳遞至標籤的建構函式。

CSS 類別和自訂元件

建構自訂元件時，請使用下列其中一種方法新增自訂 CSS 類別：

• 如果元件是 Field 或 Icon 的子類別，請覆寫 initView 方法。例如：

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

  詳情請參閱「使用 CSS 自訂欄位」或「建立圖示的檢視區塊」。

• 建構 SVG 元素時，請將類別傳遞至 Blockly.utils.dom.createSvgElement：

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

• 建構 HTML 元素時，請使用 Blockly.utils.dom.addClass：

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

如要在建構後新增或移除類別，請使用 Blockly.utils.dom.addClass 或 Blockly.utils.dom.removeClass。

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

警告： 請勿使用 dom.addClass 或 dom.removeClass，在他人 (包括 Blockly) 編寫的元件中新增或移除類別。這可能會導致無法預測的結果。

CSS 規則背景

如果您瞭解 SVG 樣式屬性和 CSS 疊加，可以略過本節。

可擴充向量圖形樣式屬性與 CSS 屬性

SVG 元素會使用 SVG 樣式屬性設定樣式。 這些屬性可用於 SVG 元素 (又稱呈現屬性) 或 CSS 規則。因此，下列所有項目都會執行相同操作。

<!-- 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;" ... />

可擴充向量圖形樣式屬性清單與 CSS 屬性清單相關，但兩者不同：

• 概念和名稱相同。舉例來說，SVG 和 CSS 都會使用 direction 指定文字是從左至右還是從右至左。
• 概念相同，名稱不同。舉例來說，SVG 使用 fill 指定填滿顏色，而 CSS 則使用 background-color。
• 僅限 CSS。CSS 有許多 SVG 沒有的屬性，例如 margin 和 padding。
• 僅限 SVG。SVG 有幾個不在 CSS 中的屬性，例如 x 和 y。

因此，如果要設定 SVG 元素的樣式，請使用 SVG 樣式屬性。如要設定 HTML 元素的樣式，請使用 CSS 屬性。

CSS 疊加

CSS 疊加會決定 CSS 規則的優先順序，如果有多個規則適用於特定屬性和元素，系統就會根據優先順序決定要使用哪個規則。以下簡化版層疊涵蓋 Blockly 最常用的層疊部分，可協助您解決「為什麼我的 CSS 無效？」的問題。

簡化層疊

如要判斷哪個規則適用於特定元素和屬性，請按照下列步驟操作，並在只剩一個規則時停止：

1. 收集適用於資源和元素的規則。
2. 如果任何規則有 !important 註解，請捨棄所有沒有 !important 註解的規則。

3. 選擇具體程度最高的規則。

   • SVG 呈現屬性的特異性為零。
   • <style> 標記或外部樣式表中的規則會照常計算特異性。
   • 內嵌樣式 (由 style 屬性設定的樣式) 的特殊性高於任何選取器。

4. 選擇文件中最後顯示的規則。

5. 如果沒有適用規則，請從元素的父項沿用屬性的值。

這個演算法不會考量下列層疊部分：

• transition 優先順序最高的資源。Blockly 會使用其中幾項。
• @media at 規則。Blockly 會使用其中一種。
• 瀏覽器或使用者指定的規則。
• Blockly 不會使用 @scope 和 @layer at 規則，以及 animation 屬性。

CSS 規則

CSS 規則會指定應用程式的樣式。Blockly 提供一組預設規則，您可以覆寫這些規則。

Blockly CSS 規則

Blockly 提供一組預設的 CSS 規則。新增這些規則的方式和位置會影響規則的優先順序。

樣式標記

Blockly 的大部分 CSS 規則都是在兩個 <style> 標記中指定。由於這些標記出現在網頁頂端附近，因此其中的規則優先級會低於網頁稍後出現的相同特異性規則。

Blockly.css.register 規則

注入 Blockly 時，系統會將 <style> 標記新增為 <head> 標記的子項。這個代碼中的規則來自：

• Blockly.css 命名空間。如要查看這些規則，請開啟 core/css.ts 並搜尋 let content。
• 個別元件，會呼叫 Blockly.css.register 來新增元件專屬的 CSS 規則。因為 css.register 會將這些規則加到 content 字串的結尾，所以優先順序會高於先前加入的相同具體程度規則。如要查看這些規則，請參閱對 Blockly.css.register 的呼叫。

如不想使用這些規則，請將 css 設定選項設為 false。在這種情況下，您有責任提供替代的 CSS 規則集。

轉譯器規則

例項化算繪器時，系統會將含有算繪器專屬 CSS 規則的 <style> 標記，新增為 <head> 標記的子項。請注意，這些規則一律會新增，不受 css 設定選項影響。如要查看這些規則，請在算繪器中搜尋 getCss_ 方法。

內嵌樣式

內嵌樣式是使用 style 屬性指定，通常是在建立元件的 DOM 時建立。如需部分清單，請參閱這項 GitHub 查詢。

內嵌樣式會直接套用至出現的元素，且比任何選取器都更具體。因此，如要覆寫這些函式，通常需要使用 !important 註解。

SVG 呈現屬性

SVG 呈現屬性是 SVG 樣式屬性，用做 SVG 元素的屬性。這類規則的具體程度為零，且不得包含 !important 註解，因此在所有 Blockly 規則中優先順序最低。Blockly 通常會在呼叫 createSvgElement 時建立這些項目。

新增自己的 CSS 規則

您可以透過與 Blockly 相同的方法新增自己的 CSS 規則：

• 請先呼叫 Blockly.css.register，再注入 Blockly。您的規則會新增在 Blockly 規則之後，且優先順序高於具有相同明確性的 Blockly 規則。
• 在 <head> 標記的後續子項中，加入 <style> 標記或外部樣式表的連結。由於 Blockly 會將規則新增為 <head> 代碼的前兩個子項，您的規則優先順序會高於具有相同特異性的 Blockly 規則。
• 使用內嵌樣式，為自訂元件中的元素新增樣式。這些規則的特異性會高於任何含有選取器的規則。
• 在自訂元件中，對 SVG 元素使用呈現屬性。這些規則的具體程度會低於任何含有選取器的規則。

疑難排解

如果 CSS 無法正常運作，可能原因如下：

• 您在 SVG 元素上使用 CSS 屬性，或在 HTML 元素上使用 SVG 樣式屬性。請參閱「SVG 樣式屬性與 CSS 屬性比較」。

• 您的規則優先順序低於其他規則。這通常是因為特異性較低。可能的解決方法包括：

  • 請使用類別選取器，而非類型 (元素) 選取器。
  • 使用多個選取器。
  • 請盡可能為目標元素新增自訂類別，並在規則中使用這個類別。
  • 最後，在規則中加入 !important 註解。如果使用內嵌樣式 (style 屬性) 指定競爭規則，就只能選擇這個選項。

• 您的規則與另一項規則的明確度相同，但出現在網頁上的時間較早。如果無法提高規則的明確度，請將規則移至網頁的後方。

您無法覆寫以下兩種 CSS 規則：

• 在 transition 規則中設定的屬性。
• 瀏覽器指定的 !important 規則。