English versionСинтаксис правил BlockIt
Версия синтаксиса 1
Правила BlockIt расширяют CSS-селекторы условиями, которые невозможно или неудобно надёжно выразить обычным CSS. Правило остаётся похожим на селектор: сначала указывается CSS-часть, затем псевдоклассы BlockIt.
div.card:attr-count(=2):has(> span:own-text("Реклама"))
Основа CSS
Поддерживаются теги, идентификаторы, классы, атрибуты, списки селекторов и стандартные комбинаторы:
div.notice
#banner
section[data-kind="ad"]
main > section
.anchor + .target
.anchor ~ .target
article, aside
Можно использовать нативные псевдоклассы CSS, которые поддерживает браузер. Расширения BlockIt могут находиться внутри :has(), :is(), :where() и :not().
Значения и регулярные выражения
Текстовые значения заключаются в двойные кавычки, например :text("Реклама"). Чтобы записать двойную кавычку или обратную косую черту внутри значения, поставьте перед ней обратную косую черту: \" или \\. Псевдоклассы для шаблонов принимают регулярные выражения JavaScript, например /^data-[a-z]+$/i. Нумерация позиций и результатов начинается с единицы.
Атрибуты и классы
| Синтаксис | Значение |
|---|
:attr-count(=3) | Ровно три атрибута. Операторы: =, <, <=, >, >=. :attribute-count() — синоним. |
:class-count(>=2) | Количество отдельных классов. |
:attr-name(/^data-/) | Имя хотя бы одного атрибута соответствует регулярному выражению. |
:attr(/^data-/, /^ad-/) | Имя и значение одного атрибута соответствуют двум выражениям. |
[data-*] | Существует атрибут, имя которого начинается с data-. После шаблона имени можно указать условие для значения атрибута. |
:class-name(/^card-/) | Хотя бы один класс соответствует выражению. |
:attrs(["id", /^data-/]) | Существуют все перечисленные точные имена или шаблоны имён. |
:style-property("--adaptive-width") | В inline-атрибуте style существует указанное CSS-свойство; значение игнорируется. |
Текст и HTML
| Синтаксис | Значение |
|---|
:text("Реклама") | Точное совпадение нормализованного текста элемента и потомков. |
:own-text("Реклама") | Точное совпадение только собственного текста. |
:text-starts(), :text-ends(), :text-contains(), :text-matches() | Начало, конец, подстрока или регулярное выражение для всего текста. |
:own-text-starts(), :own-text-ends(), :own-text-contains(), :own-text-matches() | Те же режимы только для собственных текстовых узлов. |
:html(/шаблон/) | Сериализованный HTML элемента соответствует выражению. |
Структура и связи
| Синтаксис | Значение |
|---|
:has(селектор) | Есть подходящий потомок или элемент относительного селектора. |
:within(селектор) | Есть подходящий предок; возможен переход через host Shadow DOM. |
:near(селектор) | Есть подходящий sibling в любом направлении и на любом расстоянии. |
:sibling-distance(previous, 2, селектор) | Второй предыдущий sibling соответствует селектору. |
:sibling-distance(next, 3, селектор) | Третий следующий sibling соответствует селектору. |
:children(селектор, >=2) | Количество подходящих непосредственных детей удовлетворяет условию. |
:sibling-position(2) | Элемент является вторым ребёнком родителя. |
:matches-position(2) | Из всех элементов, найденных полным правилом, блокировать только второй. Несколько номеров разделяются запятыми или пробелами. |
Условия живой страницы и доступности
| Синтаксис | Значение |
|---|
:visible(...) | Проверяет видимость на живой странице. |
:size(...) | Проверяет отображаемый размер. |
:style(...) | Проверяет вычисленный стиль. |
:property(...) | Проверяет JavaScript-свойство DOM. |
:accessible(...) | Проверяет признаки доступности. |
Эти условия зависят от состояния браузера и могут быть недоступны при поиске по сохранённому DOM-снимку.
Iframe и Shadow DOM
| Синтаксис | Значение |
|---|
:in-frame(...) | Ограничивает поиск содержимым iframe. |
:in-shadow(...) | Ограничивает поиск Shadow DOM. |
:frame-has(селектор) | Документ iframe содержит совпадение. |
:has-frame(...) | Элемент содержит iframe, удовлетворяющий условию. |
Для cross-origin iframe и закрытых Shadow Root действуют ограничения браузера и разрешений расширения.
Примеры правил
Примеры ниже показывают, как объединять обычную CSS-часть с условиями BlockIt. Правило может содержать несколько условий одновременно: элемент будет найден, только если выполняются все условия.
Обычные CSS-селекторы
| Правило | Что найдёт |
|---|
article.card[data-type="advertisement"] | Элементы <article>, у которых есть класс card и атрибут data-type с точным значением advertisement. Другие классы и атрибуты не мешают совпадению. |
main > aside.promo, section[data-kind="sponsor"] | Либо непосредственные дочерние <aside class="promo"> внутри <main>, либо любые <section> с указанным атрибутом. |
Атрибуты и классы
| Правило | Что найдёт |
|---|
[data-*] | Элементы с любым атрибутом, имя которого начинается с data-, например <div data-zone="sidebar">. Значение атрибута может быть любым. |
[data-*="advert"] | Элементы, у которых хотя бы один атрибут data-* имеет точное значение advert, например <aside data-kind="advert">. |
[data-*^="ad-"] | Элементы, у которых значение хотя бы одного атрибута data-* начинается с ad-, например <div data-slot="ad-top">. |
[data-*$="-banner"] | Элементы, у которых значение хотя бы одного атрибута data-* заканчивается на -banner, например <section data-kind="top-banner">. |
[data-**="advert"] | Элементы, у которых значение хотя бы одного атрибута data-* содержит строку advert, например <div data-label="sidebar advertisement">. |
div:attr-count(=3):class-count(>=2) | Элементы <div> ровно с тремя атрибутами и как минимум с двумя отдельными классами. |
section:attrs(["id", /^data-/]) | Элементы <section>, у которых одновременно есть атрибут id и хотя бы один атрибут с именем, начинающимся с data-. |
div:attr(/^data-/, /^ad-/) | Элементы <div>, у которых один и тот же атрибут имеет имя, начинающееся с data-, и значение, начинающееся с ad-. |
Текст и HTML
| Правило | Что найдёт |
|---|
button:own-text("Закрыть") | Кнопки, собственный текст которых после нормализации точно равен слову «Закрыть». Текст вложенных элементов не учитывается. |
div.notice:text-contains("Отключите блокировщик") | Элементы <div class="notice">, в полном тексте которых, включая потомков, встречается указанная фраза. |
article:html(/data-slot="ad-[^"]+"/i) | Элементы <article>, в сериализованном HTML которых есть атрибут data-slot со значением, начинающимся с ad-. Регистр не учитывается. |
Структура, связи и позиции
| Правило | Что найдёт |
|---|
section:has(> div:attr-count(=2) > span:own-text("Реклама")) | Элементы <section> с непосредственным дочерним <div> ровно с двумя атрибутами, внутри которого находится непосредственный <span> с собственным текстом «Реклама». |
div.card:within(main.content):near(div.promo) | Элементы <div class="card">, расположенные внутри <main class="content"> и имеющие сиблинга <div class="promo">. |
div.target:sibling-distance(previous, 2, div.new-menu) | Элементы <div class="target">, у которых второй предыдущий сиблинг соответствует div.new-menu. |
ul:children(li, >=3) | Списки <ul>, содержащие не менее трёх непосредственных дочерних элементов <li>. |
article.card:matches-position(2, 4) | Второй и четвёртый элементы среди всех результатов, найденных правилом article.card. |
Состояние страницы и доступность
| Правило | Что найдёт |
|---|
button:visible():accessible(role="button", name=/закрыть/i) | Видимые кнопки с ролью button, доступное имя которых содержит слово «закрыть» без учёта регистра. |
div.banner:size(width>=300, height<250):style(display, "block") | Элементы <div class="banner"> шириной не менее 300 пикселей, высотой менее 250 пикселей и с вычисленным значением display: block. |
div:style-property("--adaptive-width") | Элементы <div>, в inline-атрибуте style которых объявлено CSS-свойство --adaptive-width; его значение может быть любым. |
input:property(disabled, "false") | Элементы <input>, JavaScript-свойство disabled которых имеет строковое представление false. |
Iframe и Shadow DOM
| Правило | Что найдёт |
|---|
*:in-frame(/docs\.example\.com/) | Элементы внутри iframe, адрес которого соответствует указанному регулярному выражению. |
button:in-shadow(video-player) | Кнопки внутри Shadow DOM, хост которого соответствует селектору video-player. |
iframe:frame-has(button:own-text("Закрыть")) | Элементы <iframe>, документ которых содержит кнопку с собственным текстом «Закрыть». |
div.viewer:has-frame(> iframe, button:own-text("Закрыть")) | Элементы <div class="viewer"> с непосредственным дочерним iframe, внутри которого есть кнопка с собственным текстом «Закрыть». |
Совместимость
Сохранённые правила продолжат работать после обновлений BlockIt. Новые возможности могут добавляться без изменения смысла существующих конструкций.