Стиль с помощью CSS

Приложения Blockly состоят из элементов HTML и SVG. Эти элементы помечены CSS-классами, которые определяют их содержимое (например, blocklyBlock , blocklyField ), а также их состояние (например, blocklyEditing , blocklySelected ). Blockly также предоставляет набор CSS-правил по умолчанию.

Вы можете использовать CSS для стилизации своего приложения:

  • Переопределите CSS-правила Blockly своими собственными правилами.
  • Добавьте собственные CSS-классы к компонентам Blockly для дополнительной специфичности.
  • Используйте классы и правила CSS для стилизации пользовательских компонентов.

CSS-классы

Блочные приложения используют CSS-классы для определения элементов, к которым применяется стилизация. Это обеспечивает более точный контроль, чем селекторы типов (элементов).

Блочные CSS-классы

Blockly использует классы CSS для предоставления следующих видов информации об используемых им элементах HTML и SVG.

  • Тип. Большинство CSS-классов Blockly определяют, что представляет элемент. Например, корневой элемент блока имеет обозначение blocklyBlock . Некоторые элементы имеют несколько классов, каждый из которых более специфичен, чем предыдущий. Например, корневой элемент текстового поля ввода имеет обозначения blocklyField , blocklyInputField и blocklyTextInputField . Классы типов остаются неизменными на протяжении всего жизненного цикла компонента.

  • Состояние. Blockly также использует CSS-классы для определения состояния компонента. Например, когда курсор находится на поле ввода текста, его корневой элемент помечается классом blocklyEditing . При перемещении курсора этот класс удаляется.

  • Дополнительная информация. Blockly использует несколько CSS-классов для предоставления дополнительной информации. Например, элемент <div> для внедрения содержит классы, которые содержат имя текущего рендерера и темы рабочей области. Эти классы, как правило, остаются неизменными на протяжении всего срока службы приложения.

Самый простой способ узнать, какие классы CSS использует Blockly, — открыть инструменты разработчика вашего браузера и просмотреть элементы, используемые вашим приложением.

Пользовательские CSS-классы

Вы можете использовать пользовательские классы CSS, чтобы придать большую специфичность компонентам Blockly.

Рабочие пространства

Чтобы добавить или удалить класс CSS из элемента <div> внедрения рабочей области, вызовите WorkspaceSvg.addClass или WorkspaceSvg.removeClass .

Ящики для инструментов

Чтобы добавить CSS-класс к кнопке или метке на панели инструментов, используйте ключ web-class в JSON-определении панели инструментов. Подробнее см. в разделе «Кнопки и метки» .

Чтобы переопределить CSS-классы, используемые для различных частей категории, используйте ключ cssConfig в JSON-определении категории. Это позволяет стилизовать отдельные категории. Подробнее см. в разделе 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,
}]);

Вы также можете добавить или удалить класс CSS из элемента <g> блока, вызвав BlockSvg.addClass или BlockSvg.removeClass .

Поля меток

Чтобы добавить или удалить CSS-класс из элемента <text> , используемого полем метки или сериализуемым полем метки, вызовите метод 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');
  }
}

Фон правил CSS

Если вы понимаете свойства стилей SVG и каскадность CSS, вы можете пропустить этот раздел.

Свойства стилей SVG и свойства 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;" ... />

Список свойств стилей SVG связан со списком свойств CSS, но отличается от него:

  • Одна и та же концепция, одно и то же название. Например, и SVG, и CSS используют direction для указания направления письма (LTR или RTL).
  • Та же концепция, другое название. Например, 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 использует одно из них.
  • Правила, заданные браузером или пользователем.
  • Правила @scope и @layer , а также свойство animation , которые не используются Blockly.

CSS-правила

Правила CSS определяют стили вашего приложения. Blockly предоставляет набор правил по умолчанию, которые вы можете переопределить своими собственными правилами.

Блочные правила CSS

Blockly предоставляет набор CSS-правил по умолчанию. Способ и место добавления этих правил влияют на их приоритет .

Теги стиля

Большинство CSS-правил Blockly задаются двумя тегами <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.

Правила рендеринга

При создании экземпляра рендерера он добавляет тег <style> , содержащий CSS-правила, специфичные для рендерера, в качестве дочернего элемента тега <head> . Обратите внимание, что эти правила добавляются всегда — на них не влияет параметр конфигурации css . Чтобы увидеть эти правила, найдите метод getCss_ в вашем рендерере.

Встроенные стили

Встроенные стили задаются атрибутом style и обычно создаются при создании DOM-модели компонента. Частичный список см. в этом запросе на GitHub .

Встроенные стили применяются непосредственно к элементу, к которому они относятся, и имеют более высокую специфичность, чем любой селектор. Поэтому для их переопределения обычно требуется использовать аннотацию !important .

Атрибуты представления SVG

Атрибуты представления SVG — это свойства стилизации SVG, используемые в качестве атрибутов SVG-элементов. Они имеют нулевую специфичность и не могут содержать аннотацию !important , поэтому имеют самый низкий приоритет среди всех правил Blockly. Blockly обычно создаёт их в вызовах createSvgElement .

Добавьте свои собственные правила CSS

Вы можете добавить собственные CSS-правила, используя те же методы, что и Blockly:

  • Вызовите Blockly.css.register перед внедрением Blockly. Ваши правила будут добавлены после правил Blockly и будут иметь более высокий приоритет, чем правила Blockly с той же специфичностью.
  • Добавьте тег <style> или ссылку на внешнюю таблицу стилей в качестве дочернего элемента тега <head> . Поскольку Blockly добавляет свои правила в качестве первых двух дочерних элементов тега <head> , ваши правила будут иметь более высокий приоритет, чем правила Blockly с той же специфичностью.
  • Используйте встроенные стили для добавления стилей к элементам в пользовательском компоненте. Эти правила будут иметь более высокую специфичность, чем любые правила с селектором.
  • Используйте атрибуты представления для элементов SVG в пользовательском компоненте. Эти правила будут иметь меньшую специфичность, чем любые правила с селектором.

Поиск неисправностей

Если ваш CSS не работает, вот несколько возможных причин:

  • Вы используете свойства CSS для элемента SVG или свойства стилей SVG для элемента HTML. См. раздел Сравнение свойств стилей SVG и свойств CSS .

  • Ваше правило имеет более низкий приоритет, чем другое правило. Обычно это связано с более низкой специфичностью . Возможные способы исправления:

    • Используйте селектор класса вместо селектора типа (элемента).
    • Используйте множественные селекторы.
    • Если возможно, добавьте пользовательский класс к целевому элементу и используйте этот класс в своем правиле.
    • В крайнем случае добавьте к правилу аннотацию !important . Это единственный вариант, если конкурирующее правило указано с использованием встроенного стиля (атрибута style ).

  • Ваше правило имеет ту же специфичность, что и другое правило, но расположено выше на странице. Если вы не можете повысить специфичность правила, переместите его ближе к концу страницы.

Существует два типа правил CSS, которые вы не можете переопределить:

  • Свойства, которые задаются внутри правила transition .
  • !important правила, указанные браузером.