API пользовательского выделения CSS
API пользовательского выделения CSS предоставляет механизм для стилизации произвольных фрагментов текста в документе, используя JavaScript для создания фрагментов и CSS для их стилизации.
Концепции и использование
Стилизация фрагментов текста на веб-странице может быть очень полезной. Например, веб-приложения для редактирования текста выделяют ошибки в написании или грамматике, а редакторы кода выделяют синтаксические ошибки.
API пользовательского выделения CSS расширяет концепцию других псевдоэлементов выделения, таких как ::selection, ::spelling-error, ::grammar-error и ::target-text, предоставляя способ создания и стилизации произвольных объектов Range, а не ограничиваясь предопределёнными браузером фрагментами.
Используя API пользовательского выделения CSS, вы можете программно создавать фрагменты текста и выделять их, не изменяя структуру DOM на странице.
Для стилизации фрагментов текста на веб-странице с помощью API пользовательского выделения CSS существует четыре шага:
- Создание объектов
Range. - Создание объектов
Highlightдля этих фрагментов. - Регистрация выделений с помощью
HighlightRegistry. - Стилизация выделений с использованием псевдоэлемента
::highlight().
Создание фрагментов
Первый шаг — определение фрагментов текста, которые вы хотите стилизовать, создав объекты Range в JavaScript. Например:
const parentNode = document.getElementById("foo");
const range1 = new Range();
range1.setStart(parentNode, 10);
range1.setEnd(parentNode, 20);
const range2 = new Range();
range2.setStart(parentNode, 40);
range2.setEnd(parentNode, 60);
Создание выделений
Второй шаг — создание объектов Highlight для ваших фрагментов текста.
Несколько фрагментов могут быть связаны с одним выделением. Если вы хотите выделить несколько фрагментов текста одинаково, вам нужно создать одно выделение и инициализировать его соответствующими фрагментами.
const highlight = new Highlight(range1, range2);
Но вы также можете создать любое количество выделений. Например, если вы создаёте редактор текста для совместного использования, где каждый пользователь получает другой цвет текста, то вы можете создать выделение на пользователя, как показано в фрагменте кода ниже:
const user1Highlight = new Highlight(user1Range1, user1Range2); const user2Highlight = new Highlight(user2Range1, user2Range2, user2Range3);
Каждое выделение может быть стилизовано по-разному.
Регистрация выделений
После создания выделений зарегистрируйте их, используя HighlightRegistry, доступный как CSS.highlights.
Регистр — это объект, похожий на Map, используемый для регистрации выделений по именам, как показано ниже:
CSS.highlights.set("user-1-highlight", user1Highlight);
CSS.highlights.set("user-2-highlight", user2Highlight);
В приведенном выше фрагменте кода строки user-1-highlight и user-2-highlight являются пользовательскими идентификаторами, которые могут быть использованы в CSS для применения стилей к зарегистрированным выделениям.
Вы можете зарегистрировать любое количество выделений в регистре, а также удалить выделения и очистить весь регистр.
// Remove a single highlight from the registry.
CSS.highlights.delete("user-1-highlight");
// Clear the registry.
CSS.highlights.clear();
Стилизация выделений
Последний шаг — стилизация зарегистрированных выделений. Это делается с помощью псевдоэлемента ::highlight(). Например, чтобы стилизовать выделение user-1-highlight , зарегистрированное на предыдущем шаге:
::highlight(user-1-highlight) {
background-color: yellow;
color: black;
}
Интерфейсы
Highlight-
Этот интерфейс используется для представления набора фрагментов, подлежащих стилизации в документе.
HighlightRegistry-
Доступный через
CSS.highlights, этот объект, похожий наMap, используется для регистрации выделений с пользовательскими идентификаторами.
Примеры
Выделение результатов поиска
Этот пример показывает, как использовать API пользовательского выделения CSS для выделения результатов поиска.
HTML
Фрагмент HTML-кода ниже определяет поле поиска и статью с несколькими абзацами текста:
<label>Search within text <input id="query" type="text" /></label>
<article>
<p>
Maxime debitis hic, delectus perspiciatis laborum molestiae labore,
deleniti, quam consequatur iure veniam alias voluptas nisi quo. Dolorem
eaque alias, quo vel quas repudiandae architecto deserunt quidem, sapiente
laudantium nulla.
</p>
<p>
Maiores odit molestias, necessitatibus doloremque dolor illum reprehenderit
provident nostrum laboriosam iste, tempore perferendis! Ab porro neque esse
voluptas libero necessitatibus fugiat, ex, minus atque deserunt veniam
molestiae tempora? Vitae.
</p>
<p>
Dolorum facilis voluptate eaque eius similique ducimus dignissimos assumenda
quos architecto. Doloremque deleniti non exercitationem rerum quam alias
harum, nisi obcaecati corporis temporibus vero sapiente voluptatum est
quibusdam id ipsa.
</p>
</article>
JavaScript
JavaScript используется для прослушивания события input в поле поиска. Когда событие срабатывает, код находит совпадения введённого текста в тексте статьи. Затем он создаёт фрагменты для совпадений и использует API пользовательского выделения CSS для создания и регистрации объекта выделения search-results:
const query = document.getElementById("query");
const article = document.querySelector("article");
// Find all text nodes in the article. We'll search within
// these text nodes.
const treeWalker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
const allTextNodes = [];
let currentNode = treeWalker.nextNode();
while (currentNode) {
allTextNodes.push(currentNode);
currentNode = treeWalker.nextNode();
}
// Listen to the input event to run the search.
query.addEventListener("input", () => {
// If the CSS Custom Highlight API is not supported,
// display a message and bail-out.
if (!CSS.highlights) {
article.textContent = "CSS Custom Highlight API not supported.";
return;
}
// Clear the HighlightRegistry to remove the
// previous search results.
CSS.highlights.clear();
// Clean-up the search query and bail-out if
// if it's empty.
const str = query.value.trim().toLowerCase();
if (!str) {
return;
}
// Iterate over all text nodes and find matches.
const ranges = allTextNodes
.map((el) => {
return { el, text: el.textContent.toLowerCase() };
})
.map(({ text, el }) => {
const indices = [];
let startPos = 0;
while (startPos < text.length) {
const index = text.indexOf(str, startPos);
if (index === -1) break;
indices.push(index);
startPos = index + str.length;
}
// Create a range object for each instance of
// str we found in the text node.
return indices.map((index) => {
const range = new Range();
range.setStart(el, index);
range.setEnd(el, index + str.length);
return range;
});
});
// Create a Highlight object for the ranges.
const searchResultsHighlight = new Highlight(...ranges.flat());
// Register the Highlight object in the registry.
CSS.highlights.set("search-results", searchResultsHighlight);
});
CSS
Наконец, псевдоэлемент ::highlight() используется в CSS для стилизации выделений:
::highlight(search-results) {
background-color: #f06;
color: white;
}
Результат
Результат показан ниже. Введите текст в поле поиска, чтобы выделить совпадения в статье:
Спецификации
Совместимость с браузерами
| Рабочие столы | Мобильные устройства | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox для Android | Opera Android | Safari на iOS | Samsung Internet | WebView Android | |
CSS_Custom_Highlight_API |
105 | 105 | превьюЕщё нельзя использовать сtext-decoration и text-shadow. |
91 | 105 | Нет | 72 | 20.0 | 105 | ||
| Десктоп | Мобильный | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari на IOS | Samsung Internet | WebView Android | |
@@iterator |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
CSS_Custom_Highlight_API |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
clear |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
delete |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
entries |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
forEach |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
get |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
has |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
keys |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
set |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
size |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
values |
105 | 105 | превью | 91 | 17.2 | 105 | Нет | 72 | 17.2 | 20.0 | 105 |
| Настольный компьютер | Мобильный | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox для Android | Opera Android | Safari на IOS | Samsung Internet | WebView Android | |
@@iterator |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
Highlight |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
CSS_Custom_Highlight_API |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
add |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
clear |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
delete |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
entries |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
forEach |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
has |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
keys |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
priority |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
size |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
type |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
values |
105 | 105 | preview | 91 | 17.2 | 105 | No | 72 | 17.2 | 20.0 | 105 |
api.Highlight
Таблицы BCD загружаются только в браузере
api.HighlightRegistry
Таблицы BCD загружаются только в браузере
css.selectors.highlight
Таблицы BCD загружаются только в браузере
См. также
© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API