This section is non-normative.
The Custom Highlight API extends the concept of highlight pseudo-elements (see CSS Pseudo-Elements 4 §3 Highlight Pseudo-elements) by providing a way for web developers to style the text of arbitrary Range objects, rather than being limited to the user agent defined ::selection, ::inactive-selection, ::spelling-error, and '::grammar-error'. This is useful in a variety of scenarios, including editing frameworks that wish to implement their own selection, find-on-page over virtualized documents, multiple selection to represent online collaboration, or spellchecking frameworks.
The Custom Highlight API provides a programmatic way of adding and removing highlights that do not affect the underlying DOM structure, but instead applies styles to text based on range objects, accessed via the ::highlight() pseudo element.
The following code uses the
::highlight()pseudo-element to apply a yellow background and blue foreground color to the text
One two
. It does so by adding a
Highlight
to the
HighlightsRegister
(both of these are new concepts introduced by this specification). The
Highlight
will contain a
Range
whose boundary points surround the text
One two
.
<style>
:root::highlight(example-highlight) {
background-color: yellow;
color: blue;
}
</style>
<body><span>One </span><span>two </span><span>three…</span>
<script>
let r = new Range();
r.setStart(document.body, 0);
r.setEnd(document.body, 2);
CSS.highlights.add(new Highlight("example-highlight", r));
</script>
The result would look like:
One Two three…
2. Module InteractionsThis module depends on the Infra Standard [INFRA] and on WebIDL [WebIDL].
It assumes general familiarity with CSS and with the DOM Standard [DOM], and specifically extends the mechanisms defined in CSS Pseudo-Elements Module Level 4 [css-pseudo-4] to handle highlight pseudo-elements. The Selectors Level 4 [selectors-4] specification defines how pseudo-elements work in general.
See References for a full list of dependencies.
Note: This draft is an early version. As it matures, the CSS-WG could decide to keep it as an independent module, or might prefer to fold it into [css-pseudo-4], or a later version of that module.
3. Setting up Custom Highlights 3.1. Creating Custom HighlightsA custom highlight is a named collection of ranges representing portions of a document. They do not necessarily fit into the element tree, and can arbitrarily cross element boundaries without honoring its nesting structure. They can be used to affect the appearance of these portions of the document (see § 4 Styling Custom Highlights), or to handle to events associated with them (see § 6 Event Handling).
Custom highlights are represented by Highlight objects, setlike objects whose set entries are AbstractRange objects. Ranges can be added to a custom highlight either by passing them to its constructor, or by using the usual API of setlike objects to manipulate its set entries.
Note: As the ranges in a custom highlight are AbstractRange objects, authors can chose between using Range objects and StaticRange objects. See § 5.2 Range Updating and Invalidation for more details about this choice and its implications.
The name of a custom highlight is represented by its name attribute, which must must be a valid <ident-token>.
[Exposed=Window]
interface Highlight {
constructor(CSSOMString name, AbstractRange... initialRanges);
setlike<AbstractRange>;
attribute double priority;
readonly attribute CSSOMString name;
};
See § 4.2.4 Priority of Overlapping Highlights for more information on the priority attribute.
In order to have any effect, custom highlights then needs to be registered it into the highlights register.
The highlights register is accessed via the highlights attribute of the CSS namespace, and represents all the custom highlights registered for the current global object’s associated Document. It is a setlike, and can be updated using the usual methods. It’s set entries is initially empty.
A custom highlight is said to be registered if it is in the highlights register. It stops being registered if it is later removed.
partial namespace CSS {
readonly attribute HighlightsRegister highlights;
};
[Exposed=Window]
interface HighlightsRegister {
setlike<Highlight>;
HighlightsRegister add(Highlight value);
};
4. Styling Custom Highlights 4.1. The Custom Highlight Pseudo-element: ::highlight()
The ::highlight(<highlight-name>) pseudo-element (also known as the custom highlight pseudo-element) represents the portion of a document that is being contained or partially contained in all the ranges of the registered custom highlight with the name <highlight-name>, if any. <highlight-name> must be a valid CSS <ident-token>.
4.2. Processing Model 4.2.1. Applicable PropertiesCustom highlight pseudo-elements, like the built-in highlight pseudo-elements, can only be styled with a limited set of properties. See CSS Pseudo-Elements 4 §3.2 Styling Highlights for the full list.
4.2.2. Cascading and InheritanceThe cascading and inheritance of custom highlight pseudo-elements is handled identically to that of the built-in highlight pseudo-elements, as defined in CSS Pseudo-Elements 4 §3.4 Cascading and Per-Element Highlight Styles.
4.2.3. PaintingThe painting of custom highlights is also handled identically to that of the built-in highlight pseudo-elements, as specified in CSS Pseudo-Elements 4 §3.3 Area of a Highlight and CSS Pseudo-Elements 4 §3.5 Painting the Highlight, with the following clarifications:
The following example renders in a single highlight with semi-transparent blue background, not two overlapping ones which can be seen through each other.
<style>
::highlight(sample) { background-color: rgba(0, 0, 255, 0.3); }
</style>
<body>Lorem Ipsum.
<script>
let r1 = new Range();
r1.setStart(document.body, 1);
r1.setEnd(document.body, 5);
let r2 = new Range();
r2.setStart(document.body, 3);
r2.setEnd(document.body, 7);
CSS.highlights.add(new Highlight("sample", r1, r2));
</script>
In other words, this rendering would be correct:
Lorem Ipsum.
However, this one would be incorrect:
Lorem Ipsum.
A custom highlight's priority attribute defines its priority. This is used to determine the stacking order of the corresponding highlight overlay during painting operations (see § 4.2.3 Painting). A higher priority results in being above in the stacking order.
When two ore more custom highlights have the same numerical priority, the one most recently registered has the higher effective priority.
should negative numbers mean stacking below the built-in highlight pseudo-elements? <https://github.com/w3c/csswg-drafts/issues/4593>
Should priority be an (unsigned) integer instead? That would make comparisons more reliable, but would likely lead to numbering reminiscent of BASIC line numbers. <https://github.com/w3c/csswg-drafts/issues/4592>
Should we drop priority by numbers entirely, and replace it with some other ordering mechanism? Experience with BASIC line number or z-index does not give much confidence that ordering by number is a good idea. Is placing in an ordered data-structure better? Should authors be able to express a desired to be placed above/below other named highlights, and let the UA figure it out? <https://github.com/w3c/csswg-drafts/issues/4591>
Should the built-in highlight pseudo-elements be exposed as well, so that they too can be reordered, and so that they can be interleaved with custom ones freely? <https://github.com/w3c/csswg-drafts/issues/4594>
<style>
p::highlight(foo) {
color:blue;
background-color:yellow;
}
p::highlight(bar) {
background-color:orange;
}
</style>
<body>Some text
<script>
let r1 = new Range();
r1.setStart(document.body, 0);
r1.setEnd(document.body, 6);
let r2 = new Range();
r2.setStart(document.body, 3);
r2.setEnd(document.body, 9);
CSS.highlights.add(new Highlight("foo", r1));
CSS.highlights.add(new Highlight("bar", r2));
</script>
As there are no priorities set (i.e. there is a tie between rg1 and rg2), the custom highlights' styles are stacked in order of insertion into the highlights register. The rendered results will have "Som" with blue text on yellow background, "e t" with blue text on orange background, and "ext" with the default color on orange background.
Some text
Setting rg1 . priority = 1 ; would cause rg1 to stack higher than rg2, which would result in "Some t" being blue on yellow, and "ext" being default color on orange.
Some text
5. Responding to Changes 5.1. RepaintsThe addition or removal of a custom highlight in the highlights register, or of a range in a [registered=] custom highlight, must cause the User Agent to reevaluate the rendering, and to repaint if appropriate.
The User Agent must also repaint highlights as needed in response to changes by the author to the priority, or to the boundary points of Ranges of a registered custom highlight.
How should we specify the timing (and synchronicity) of this reevaluation? <https://github.com/w3c/csswg-drafts/issues/4596>
5.2. Range Updating and InvalidationAuthors can build custom highlights using either Ranges or StaticRanges.
The resulting custom highlight represents the same parts of the document, and can be styled identically. However, the behavior is different in case the underlying document is modified.
Ranges are live ranges. The User Agent will adjust the boundary points of Ranges in response to DOM changes overlapping the range or at its boundary, and repaint accordingly. Boundary points of live ranges can also be changed by the author.
On the other hand, the User Agent must not adjust the boundary points of StaticRanges in response to DOM changes, nor can they be modified by the author after creation.
Updating all
Range
objects as the DOM is modified has a significant performance cost. Authors who intend to observe DOM changes and react to them by adjusting or recreating the ranges in their
custom highlightsare strongly encouraged to user
StaticRange
s in order to avoid this costly but unnecessary step.
Conversedly, authors who use StaticRanges should observe and react to DOM changes, by discarding stale ranges or custom highlights and recreating new ones.
When computing how to render the document, if start node or end node of any range in the highlights register refer to a Node which is no longer in a document tree, the User Agent must ignored that range. If the start offset or end offset of any range are greater than the corresponding node’s length, The User Agent must behave as if it was equal to that length.
As far as I am aware, prior uses of StaticRanges were for ranges created by the User Agent and passed to the author. Here, it’s the other way around, which raises (for the first time?) the question of invalidation of static ranges. Can the above work? Is it Fast enough that it’s worth distinguishing static and live ranges? Would some alternative handling be better? <https://github.com/w3c/csswg-drafts/issues/4597>
The interaction of StaticRanges in a custom highlight and [css-contain-2] seems problematic: on a fully contained element, you should expect that DOM changes to descendants of that element will not cause invalidation and restyling/repainting of elements outside the contained one. However, if a static range has a boundary point inside the contained subtree and another boundary point outside of it, and the DOM in the contained subtree is changed so that the boundary point inside no longer points to a valid node, the whole range should be ignored, which would affect painting outside the contained subtree. Is this a weakness of style containment, or of the invalidation logic above, or something else? <https://github.com/w3c/csswg-drafts/issues/4598>
Section on Events TBD, based on https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/highlight/events-explainer.md
should custom highlights have a dedicated event handling mechanism, or should that be added to pseudo-elements in general?
Appendix A. Privacy and Security ConsiderationsThis section is non-normative.
Provide summary of Privacy and Security Considerations for this specification
Note: The TAG has developed a self-review questionnaire to help editors and Working Groups evaluate the risks introduced by their specifications. This document was used in preparing this section.
Appendix B. AcknowledgementsThis section is non-normative.
Acknowledge people (other than editors) who deserve credit for this.
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:
Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:
Note, this is an informative note.
Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.
A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.
A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.
The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.
So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported property values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.
Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.
To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4