1. 序論
◎非規範的`~custom強調~API^cite （ `Custom Highlight API^en ）は、 `強調~疑似要素$の概念 （ `CSS-PSEUDO-4$r `§ 強調~用の疑似要素＠~CSSPSEUDO#highlight-pseudos$を見よ） を拡張して， ~web開発者~向けに［ 任意な`範囲o$【！ Range ~obj】群の`中身$rgを成す~text ］を~styleする仕方を供する — ~UA定義な［ `selection$pe, `inactive-selection^pe†, `spelling-error$pe, `grammar-error$pe ］に制限されることなく。 【† `inactive-selection^pe は `CSS-PSEUDO-4$r から除去された。】 これは、 次に挙げるものなど，様々な局面で有用になる ⇒＃ 自前の選択を実装したいと望む編集用~framework／ ~virtual化された文書に対する~page内検索／ ~onlineでの協同を表現するための複数の選択／ 綴り検査~用の~framework ◎ 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.
`~custom強調~API^cite は、 強調【 `Highlight$I ~obj】を［ 追加する／除去する ］ための~program的な仕方を供する — それらの強調は、 下層の~DOM構造に影響することなく，［ `highlight()$pe 疑似要素を介して~accessされる`範囲o$ ］に基づいて~textに~styleを適用する。 ◎ 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.
次の~codeは、 `highlight()$pe 疑似要素を利用して，~text "One two" に色を適用する — 背景は `yellow^v, 前景は `blue^v になるよう。 それは、 `HighlightRegistry$I ~objに `Highlight$I ~objを追加することにより，これを行う （どちらの~interfaceも，この仕様により導入される）。 この `Highlight$I ~objは、［ ~text "One two" を囲う`境界点$ ］を伴う `Range$I を包含することになる。 ◎ 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 HighlightRegistry (both of these are new concepts introduced by this specification). The Highlight will contain a Range whose boundary points surround the text One two.
`intro-ex^xCode結果は、 次の様な見かけになろう： ◎ The result would look like:
One Two three…
2. ~module間の相互作用
この~moduleは、 `INFRA$r, `WebIDL$r に依存する。 ◎ This module depends on the Infra Standard [INFRA] and on WebIDL [WebIDL].
この~moduleは、 一般に【読者が】［ ~CSS, ~DOM標準 `DOM$r ］に馴染んでいると見做す。 特定的に、 `CSS-PSEUDO-4$r にて定義される`強調~疑似要素$を取扱うため仕組みを拡張する。 `疑似要素$が一般にどう働くかは、 `SELECTORS-4$r が定義する。 ◎ 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.
依存関係の全部的な~listは、 `§ 参照文献＠#references$を見よ。 ◎ See References for a full list of dependencies.
注記： この草案は、 早期~versionである。 ~CSS~WGは、 この草案が成熟するに伴い，［ 独立な~moduleとして保つ ］ものと裁定するかもしれないし，［ `CSS-PSEUDO-4$r （または，それの後の~version）の中に織り込む ］ことを選好するかもしれない。 ◎ 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. ~custom強調を設定しておく
3.1. ~custom強調の作成-法
`~custom強調@ は、［ 文書を成す ある部位を表現している`範囲o$ ］たちが成す~collectionである。 それは、 要素~treeの中に収まるとは限らず，要素~境界を任意に — 要素の入子ng構造を尊守することなく — またがり得る。 それは、 次のために利用できる ⇒＃ 文書を成す これらの部位の外観に影響させる（`§ ~custom強調の~style法＠#styling-highlights$を見よ）／ それらに結付けられた~eventを取扱う（`§ ~eventの取扱い＠#events$を見よ）。 ◎ A custom highlight is a 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 § 7 Event Handling).
`~custom強調$は、 ある `Highlight$I ~objにより表現される — それは，`~setlike$~objであり、 その`~set~entry群$は，一連の`範囲o$（ `AbstractRange$I ~obj）からなる。 それらの`範囲o$は、［ 構築子に渡すか， ~setlike~objの通例的な［ `~set~entry群$を操作する~API ］を利用する ］ことにより，`~custom強調$に追加できる。 ◎ 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.
注記： `~custom強調$内の各`範囲o$は， `AbstractRange$I ~objなので、 作者は，［ `Range$I ~obj, `StaticRange$I ~obj ］どちらを利用することも選べる。 どちらを選ぶか, それによる含意についての詳細は、 `§ 範囲oの更新-法と無効~化＠#range-invalidation$を見よ。 ◎ 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.
注記： 作者は、［ `~custom強調$に利用するために `Range$I ~objを作成する ］ときは， `範囲o$の`境界点$【！endpoint】を`書記素$の途中に設置するのを避けることが示唆される — ~textを成す可視な単位【すなわち，書記素】が複数個の`符号位置$からなるときなど。 そうすると、 ~Indic音節の一部に限り強調するなど，望ましくない効果が生じる。 加えて，`補足的な文字$†の途中に`境界点$【！endpoint】を設置するのも避けるよう~careする必要がある。 【† 言い換えれば、 2 個の`~surrogate$が成す~pairとして表現される文字（例：絵文字） — `範囲o$は（符号位置ではなく）`符号単位$に基づくので。】 ◎ Note: When creating Range objects for use in custom highlights, it is suggested that authors avoid placing range endpoints in the middle of a grapheme, such as when a visible unit of text is comprised of multiple Unicode code points. Doing so can create undesirable highlighting effects, such as highlighting only part of an Indic syllable. In addition, care needs to be taken to avoid placing an endpoint in the middle of a supplementary character.
enum `HighlightType@I {
`highlight@l,
`spelling-error@l,
`grammar-error@l
};
[`Exposed$=Window]
interface `Highlight@I {
`Highlight$mc(`AbstractRange$I... %initialRanges);
setlike<`AbstractRange$I>;
attribute `long$ `priority@m;
attribute `HighlightType$I `type@m;
};
`priority$m 属性についての さらなる情報は、 `§ 重合している強調どうしの優先度＠#priorities$を見よ。 ◎ See § 4.2.5 Priority of Overlapping Highlights for more information on the priority attribute.
`type$m 属性についての さらなる情報は、 `§ 強調の種別＠#highlight-types$を見よ。 ◎ See § 4.2.6 Highlight types for more information on the type attribute.
`new Highlight(AbstractRange... initialRanges)@m 構築子~手続きは： ◎ When the Highlight(AbstractRange... initialRanges) constructor is invoked, run the following steps:
- コレの ⇒＃ `priority$m ~SET 0, `type$m ~SET `highlight$l ◎ Let highlight be the new Highlight object. ◎ Set highlight’s priority to 0. ◎ Set highlight’s type to highlight.
-
%initialRanges を成す ~EACH( %範囲o ) に対し：
- %範囲o引数 ~LET `~JS値に変換する$( %範囲o )
- 組込みの~setlike `add＠~WEBIDLjs#js-set-add$c 関数~用の手続きを［ `this^c 値としてコレ, 引数~群として ( %範囲o引数 ) ］を与える下で走らす
【 `WEBIDL$r における`構築子~手続き$の規約に従って、 この訳では，単に初期化のみを遂行するよう改める。 】
3.2. ~custom強調の登録-法
`~custom強調$が効果を発揮するためには、 `強調~registry$の中に`登録-$する必要がある。 ◎ In order to have any effect, custom highlights need to be registered into the highlight registry.
`強調~registry@ は、 `CSS$I 名前空間の `highlights$m 属性を介して~accessされる。 それは、 `現在の大域~obj$に`結付けられた文書$用に`登録-済み$な すべての`~custom強調$を表現する。 それは、 `~maplike$であり，その通例的な~methodたちを利用して更新できる。 その`~map~entry群$は，初期~時は空とする。 ◎ The highlight registry 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 maplike, and can be updated using the usual methods. It’s map entries is initially empty.
`~custom強調$のうち，`強調~registry$内にあるものは `登録-済み@ という — 後で除去されたものは、 `登録-済み$でなくなる。 ◎ A custom highlight is said to be registered if it is in the highlight registry. It stops being registered if it is later removed.
partial namespace `CSS$I {
readonly attribute `HighlightRegistry$I `highlights@m;
};
[`Exposed$=Window]
interface `HighlightRegistry@I {
maplike<`DOMString$, `Highlight$I>;
};
`~custom強調を登録する@ ~algoは、 所与の ( `HighlightRegistry$I %~registry, `~custom強調~名$ %名前, `~custom強調$ %強調 ) に対し ⇒ %~registry の `set^c ~methodを呼出す — すなわち、［ %~registry の組込みの~maplike `set＠~WEBIDLjs#js-map-set$c 関数 ］用の手続きを［ `this^c 値として %~registry, 引数~群として « %名前, %強調 » ］を与える下で走らす ◎ To register a custom highlight, invoke the set method of the highlight registry which will run the steps for a built-in maplike set function, with the highlight registry as the this value, the passed-in custom highlight name as keyArg, and the passed-in highlight as valueArg.
`~custom強調~名@ は、 `~custom強調$が`登録-$されるとき，それにアテガわれる。 それは、 ~styleしている間に強調を識別するために利用される （`§ ~custom強調の~style法＠#styling-highlights$を見よ）。 ◎ The custom highlight name assigned to a custom highlight when it is registered is used to identify the highlight during styling (see § 4 Styling Custom Highlights).
注記： 作者は［ `~custom強調$を登録するときには，`~custom強調~名$として妥当な`~CSS識別子$を利用する ］ことを勧める。 妥当でない識別子を名前に利用すると、 ~CSSを介して強調を~styleすることが難しくなり，一部の事例では不可能になる。 ◎ Note: When registering a custom highlight, authors are advised to use a custom highlight name that is a valid CSS identifier. Using a name that is not a valid identifier can make the highlight hard, and in some cases impossible, to style via CSS.
注記： 同じ`~custom強調$を複数の`~custom強調~名$の下で`登録-$することもアリではあるが、 複数の名前を利用して強調を~styleすると， 当の強調に複数の異なる~style群をアテガうことになる — ［ これらの~style群のうち競合している~style群どうし ］の積層~順序を［ `塗ngの間＠#painting$に制御する仕方 ］を伴わずに。 これは、 作者を制限して【どう制限する？】， 作者を惑わす塗ngの挙動の原因にもなり得る （`下の例＠#styling-problems-with-multiple-names-per-highlight$を見よ）。 したがって、 作者には， 強調ごとに 1 個の名前のみを利用して~styleする ことを勧める。 ◎ Note: It is possible to register a custom highlight with more than one custom highlight name. However, using more than one name to style a highlight will assign the highlight multiple different sets of styles, without a way to control the stacking order of conflicting styles within these sets during painting. This could be limiting for authors and could cause confusing painting behavior (see the example below for more context). Therefore, authors are advised to only use one name per highlight during styling.
上の例では、 同じ`~custom強調$を名前 `foo^l, `bar^l の下で`登録-$している。 各`~style規則$は、［ 同じ強調を~targetにする ］かつ［ 同じ`詳細度$を伴う ］ので、 作者は，最後の規則が~cascade法において優先され， 強調される内容は `green^v になると期待するかもしれない。 しかしながら、 各~強調~名は独立な強調~style群を取得するので、 強調は名前ごとに 1 回~塗られることになる。 この事例では `foo^l が `bar^l より前に登録されたので、 当の強調は， `foo^l の色（ `green^v ）で塗られてから `bar^l の色（ `red^v ）で塗られ、 その結果，強調された内容は `red^v に現れることになる。 ◎ In the example above, the same custom highlight object is registered under the names foo and bar. Since each of the style rules target the same highlight and have the same specificity, authors might expect the last rule to win in cascading order and the highlighted content to be green. However, each highlight name gets an independent set of highlight styles, and the highlight will be painted once per name. In this case, because foo was registered before bar, the highlight will be first painted with foo’s color (green) and then with bar’s color (red). As a result, the highlighted content will appear red.
4. ~custom強調の~style法
4.1. ~custom強調~疑似要素： `highlight()^pe
`highlight()$pe 疑似要素は， `~custom強調~疑似要素@ とも呼ばれ、 文書を成す ある部位として，［ 引数に指定された`~custom強調~名$を伴って`登録-$された`~custom強調$ ］を成す すべての`範囲o$の`中身$rg【！being contained or partially contained】を表現する。 ◎ The ::highlight() 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 custom highlight name specified as its argument.
4.2. 処理~model
4.2.1. 適用-可能な~prop
`~custom強調~疑似要素$に対し~styleできる~propの集合は、 組込みの`強調~疑似要素$と同様に制限される。 全部的な~listは、 `CSS-PSEUDO-4$r `§ 強調の~style法＠~CSSPSEUDO#highlight-styling$ を見よ。 ◎ Custom 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. 既定の~style
~UAは、 `~custom強調~疑似要素$用には，［ 既定の~UA~stylesheet規則／`~pairにされた既定の強調~色$ ］を定義しないモノトスル。 言い換えれば、 何らかの内容が~styleを伴わない~custom強調により強調されたときには， その呈示を変更しないモノトスル。 ◎ UAs must not define any default UA stylesheet rules or paired default highlight colors for any custom highlight pseudo-elements. In other words, when some content is highlighted by an unstyled custom highlight, its presentation must not change.
4.2.3. ~cascade法と継承
`~custom強調~疑似要素$の`~cascade法$と`継承$は、 組込みの`強調~疑似要素$と同じく， `CSS-PSEUDO-4$r `§ ~cascade法と要素ごとの強調~style＠~CSSPSEUDO#highlight-cascade$ にて定義されるとおりに取扱われる。 ◎ The 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.5 Cascading and Per-Element Highlight Styles.
4.2.4. 塗法
`~custom強調$の塗ngは、 組込みの`強調~疑似要素$と同じく， `CSS-PSEUDO-4$r ［ `§ 強調を成す区画＠~CSSPSEUDO#highlight-bounds$, `§ 強調の塗法＠~CSSPSEUDO#highlight-painting$ ］に指定されるとおりに取扱われるが、 次に挙げる明確化も伴う： ◎ The 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.4 Area of a Highlight and CSS Pseudo-Elements 4 § 3.6 Painting the Highlight, with the following clarifications:
- `畳まれて$rgいる`範囲o$は描画されない。 ◎ Collapsed ranges are not rendered.
-
単独の`~custom強調$の中で互いに重合している`範囲o$たちは、［ それらの和を表現している 1 個の範囲o ］が指定されたかのように描画される。 ◎ Overlapping ranges within a single custom highlight are rendered as if a single range representing the union of the overlapping ones had been specified.
次の例は、 単独の強調~内に，半透明な背景~色 `blue^v で描画される — 重合していて互いに透けて見える 2 個の強調~内にではなく。 ◎ The following example renders in a single highlight with semi-transparent blue background, not two overlapping ones which can be seen through each other.
`overlap-ranges-ex^xCode言い換えれば、 正しい描画は次のようになり： ◎ In other words, this rendering would be correct:
Lorem Ipsum.次の描画は不正になる： ◎ However, this one would be incorrect:
Lorem Ipsum. - `~custom強調$の`強調~overlay$は、［ `CSS-PSEUDO-4$r `§ 強調の塗法＠~CSSPSEUDO#highlight-painting$にて述べられる積層~順序 ］において，組込みの`強調~疑似要素$の`強調~overlay$の下（背後）に来る。 ◎ The highlight overlays of the custom highlights are below those of the built-in highlight pseudo-elements in the stacking order described in CSS Pseudo-Elements 4 § 3.6 Painting the Highlight.
- 複数の`~custom強調$の`強調~overlay$どうしの相対的な積層~順序は、 それらの`優先度$により定義される （`§ 重合している強調どうしの優先度＠#priorities$を見よ）。 ◎ The relative stacking order of the highlight overlays of multiple custom highlights is defined by their priority (see § 4.2.5 Priority of Overlapping Highlights).
4.2.5. 重合している強調どうしの優先度
`~custom強調$の `優先度@ は、 その `priority$m 属性がとる整数として定義される。 これは、［ 塗ng演算の間に対応している`強調~overlay$の積層~順序を決定する ］ために利用される （ `§ 塗法＠#painting$を見よ）。 `優先度$が高い（数として正な無限大に近い）ものほど，積層~順序において上（手前）に来る。 ~custom強調に `priority$m 属性が明示的に設定されなかった場合、 優先度は 0 が既定になる。 ◎ 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.4 Painting). A higher priority results in being above in the stacking order. A custom highlight will have a default numerical priority of 0 if its priority attribute has not been explicitly set.
複数の`~custom強調$の`優先度$が数として等しいときは、 後に`登録-$されたものほど実質的な`優先度$は高くなる。 ◎ When two or more custom highlights have the same numerical priority, the one most recently registered has the higher effective priority.
%h1, %h2 どちらにも優先度は設定されないので （すなわち、それらの優先度は 0 であり，等しい）、 ~custom強調の~styleは，`強調~registry$の中へ挿入された順序で積層される。 描画される結果は、次の様になる ⇒＃ 背景 `yellow^v 上に `blue^v ~text "Som", 背景 `orange^v 上に `blue^v ~text "e t", 背景 `orange^v 上に既定の色を伴う "ext" ◎ As there are no priorities set (i.e. there is a tie between h1 and h2), the custom highlights' styles are stacked in order of insertion into the highlight registry. 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
%h1 の `priority$m を 1 に設定すると、 %h1 の優先度は %h2 より高くなり， %h2 より上に積層させることになる。 その結果は、次の様になる ⇒＃ 背景 `yellow^v 上に `blue^v ~text "Some t", 背景 `orange^v 上に既定の色を伴う~text "ext" ◎ Setting h1.priority = 1; would cause h1 to stack higher than h2, which would result in "Some t" being blue on yellow, and "ext" being default color on orange.
Some text
4.2.6. 強調の種別
`~custom強調$の `type$m 属性は、 作者により，強調の意味論上の意味を指定するために利用される。 これは、［ 支援技術が利用者に強調を公開するとき，この意味を含める ］ことを許容する。 ◎ A custom highlight’s type attribute is used by authors to specify the semantic meaning of the highlight. This allows assistive technologies to include this meaning when exposing the highlight to users.
~custom強調の種別【 `HighlightType$I 値】は、 その `type$m 属性が明示的に設定されなかった場合には， `highlight$l が既定になる。 ◎ A custom highlight will have a default type of highlight if its type attribute has not been explicitly set.
注記： 作者は、 `~custom強調$が［ 綴りが誤った／文法~的に不正な ］内容を強勢するために利用するときは，その `type$m を［ `spelling-error$l ／ `grammar-error$l ］に設定するよう勧める。 他のすべての利用事例では、 `type$m は `highlight$l のままにしておくのが最善である。 ◎ Note: Authors are advised to set a custom highlight’s type to spelling-error when that custom highlight is being used to emphasize misspelled content. Authors are advised to set a custom highlight’s type to grammar-error when that custom highlight is being used to emphasize content that is grammatically incorrect. For all other use cases type is best left as highlight.
~UAは、 `~custom強調$を支援技術からも可用にするベキである。 所与の~platform~accessibility~APIを利用して強調を公開するときは、 ~UAは 当の強調の意味論上の意味を その `type$m 属性に指定されたとおりに公開するベキである — 当の~accessibility~API用にアリな限りの特定度で。 ◎ UAs should make custom highlights available to assistive technologies. When exposing a highlight using a given platform accessibility API, UAs should expose the semantic meaning of the highlight as specified by its type attribute with as much specificity as possible for that accessibility API.
注記： 例えば，~platformの~accessibility~APIが：
- 特定的に［ 綴りの誤り, 文法の誤り ］を表出する能力を有する場合、 ~UAには，［ `spelling-error$l, `spelling-error$l ］を伴う強調~用の意味論を［ これらの能力を利用して伝達する ］ことが期待される。
- 綴りの誤りを表出する能力しか有さない場合、 ~UAには，［ `spelling-error$l, `grammar-error$l ］伴う強調~用の意味論どちらも［ その能力を利用して伝達する ］ことが期待される。
- ［ 綴りの誤り, 文法の誤り ］どちらも，それを表出する~supportを備えない場合、 ~UAは，すべての強調を — 実際の `type$m に関わらず — 汎用な `highlight$l として公開することになる。
注記： 種別~用に この初期~集合が選ばれたのは、 それらが［ 期待される強調~API用に普及した利用事例 ］であり，［ 今日の~platform~accessibility~APIにおいて， それらの意味論を表出する既存の~supportがある ］からである。 現時点では、 ~accessibility~APIには，他の［ 期待される強調~APIの利用事例 ］に特有な意味論を表出する仕方は無い。 ~accessibility~APIに追加的な［ 普及した強調~APIの利用事例 ］を表出するための~supportが備わるに伴い、 `HighlightType$I には，種別~用の値がさらに追加され得る。 ◎ Note: This initial set of types was chosen because they are expected to be popular use cases for Highlight API and there is some existing support for expressing their semantics in platform accessibility APIs today. Accessibility APIs currently don’t have any way to express the specific semantics of other expected Highlight API use cases. More types could later be added to HighlightType as accessibility APIs gain support for expressing additional popular use cases of Highlight API.
5. 変化に対する応答-法
5.1. 塗直し
~UAは，［ `強調~registry$に対し，`~custom強調$が［ 追加された／除去された ］とき／ `登録-済み$な`~custom強調$に対し，`範囲o$が［ 追加された／除去された ］とき ］は、 描画を評価し直して，適切になる場合は塗直すモノトスル。 ◎ The addition or removal of a custom highlight in the highlight registry, or of a range in a registered custom highlight, must cause the user agent to reevaluate the rendering, and to repaint if appropriate.
~UAは、 `登録-済み$な`~custom強調$に対し，作者により［ その `priority$m ／ それを成す いずれかの `Range$I 【`~live範囲o$】の`境界点$ ］が変更されたときは、 それに呼応して，必要に応じて強調を塗直すモノトスル。 ◎ 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.
この塗直しは，非同期に起きるが、 それを待機している間でも，上に言及した~API群を阻まないモノトスル。 ◎ This repaint is asynchronous, and the APIs mentioned above must not block while waiting for the repaint to happen.
5.2. 範囲oの更新-法と無効~化
作者は、 `~custom強調$を築くときに［ `Range$I ／ `StaticRange$I ］どちらも利用できる。 ◎ Authors can build custom highlights using either Ranges or StaticRanges.
いずれにせよ，結果の`~custom強調$は、 当の文書を成す同じ各部を表現し，同じように~styleできる。 しかしながら、 下層の~DOM【！文書】が改変された事例では，挙動は異なる。 ◎ 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.
`Range$I は、 `~live範囲o$である。 ~UAは，［ 範囲o／その境界 ］に重合している~DOMが変化したとき、 それに呼応して `Range$I の`境界点$を調整して，それに則って`塗直す＠#repaint$ことになる。 作者は、 `~live範囲o$の`境界点$を変更できる。 ◎ 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.
他方、 ~UAは，~DOMが変化しても、 それに呼応して `StaticRange$I の`境界点$を調整しないモノトスル。 作者は、 作成~後において，その`境界点$を改変できない†。 ~UAには、 実際の `StaticRange$I を格納することが期待される — それらを`~live範囲o$ 【！~live `Range$I 】で~back-upするのではなく。 ◎ 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. The user agent is expected to store the actual StaticRanges, rather than backing them up with live Ranges.
【† `Range$I と違って、 `StaticRange$I には，`境界点$を改変するための~methodは無い。 】
~DOMが改変されるに伴い，すべての `Range$I ~objを更新することには、 処理能に有意な~costがかかる。 作者は、［ ~DOM変化を観測して、 それらの`~custom強調$内の範囲oを［ 調整する／作成し直す ］ことにより，それらに反応する ］よう意図するときは、 この~costがかかるが不必要な段を避けるため， `StaticRange$I を利用することが強く奨励される。 ◎ 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 highlights are strongly encouraged to use StaticRanges in order to avoid this costly but unnecessary step.
逆に， `StaticRange$I を利用する作者は、 ~DOM変化を観測して，~~古くなった［ `範囲o$／`~custom強調$ ］は破棄して，新たなものを作成し直すことにより反応するベキである。 ◎ Conversely, authors who use StaticRanges should observe and react to DOM changes, by discarding stale ranges or custom highlights and recreating new ones.
~UAは，文書 %文書 を描画する方法を算出するときは、［ %文書 の~windowに結付けられた`強調~registry$内の`範囲o$ ］が ~OR↓ を満たす場合には，その`範囲o$を無視するモノトスル： ◎ When computing how to render a document,＼
- その［ `始端~node$／`終端~node$ ］【！が指している `Node$I 】の`~shadowも含めた根$は %文書 でない ◎ if start node or end node of any range in the highlight registry associated with that document’s window refer to a Node whose shadow-including root is not that document, the user agent must ignore that range.＼
- `StaticRange$I であって，`妥当$rgでない ◎ If any StaticRange in the highlight registry associated with that document’s window is not valid, the user agent must ignore that range.
6. ~custom強調とのヤリトリ-法
`highlightsFromPoint(x, y, options)$m ~methodは、［ 利用者による`~custom強調$とのヤリトリを孕んでいる局面を築く ］ことを開発者に許容する。 この~methodは、［ 所与の座標 ( %x, %y ) に当たった`~custom強調$, その`範囲o$ ］を~capsule化する `HighlightHitResult$I ~objたちを包含している`連列$を返す。 この連列を成す `HighlightHitResult$I たちは、［ 各自の `highlight$mb ~memberが表現する`~custom強調$の`優先度$ ］の降順で順序付けられる。 既定では，`~shadow~tree$内の`~custom強調$は結果に含まれないが、 開発者は，［ 省略可能な %options `辞書$を成す `shadowRoots$mb ~memberに `ShadowRoot$I ~objたちを渡す ］こともアリであり、 次を満たす`~shadow~tree$の中に包含される`~custom強調$は，返されるようになる ⇒ その`根$ ~IN %options[ "`shadowRoots$mb" ] ◎ The highlightsFromPoint(x, y, options) method allows developers to build scenarios involving user interaction with custom highlights. The method returns a sequence containing HighlightHitResult objects which encapsulate the custom highlights and their ranges that are hit at a given x, y coordinate. This sequence is ordered by descending order of priority of its HighlightHitResult’s highlights. By default, custom highlights in a shadow tree are not returned, but the developer has the possibility to pass in an optional options dictionary with a shadowRoots property containing a sequence of ShadowRoot objects. Highlights contained within a shadow tree provided in this way will be returned.
`highlightsFromPoint()$m を利用して `click^et `~event$とヤリトリする仕方を 次の例に示す： ◎ The following example shows a way to use highlightsFromPoint to interact with mouse click events.
`highlights-from-point-ex^xCode上の~codeは、 ~text "abcd" が次のように表示されるよう，~styleすることになる — "b" には %h1, %h2 どちらの`~custom強調$も影響する一方で， "a" と "d" には %h1 のそれしか影響しないことに注意： ◎ The code above will display the following styled text, note that "b" is affected by both highlights h1 and h2, whereas "a" and "d" are only affected by h1:
abcd
この例では、 `click^et `~event$用に`~event~listener$が設定されている — それは、 `~custom強調$のうち［ ~clickが為された地点を占めるもの ］および それらの範囲を~logする。 ~consoleには、 利用者が~clickした文字に応じて，次が~printされる： ◎ In this example there’s an event listener set on click events that logs the custom highlights and their ranges present at the point where the click was made. The following sequences are some examples of what will be printed to console after a click:
-
"a" ⇒
[ HighlightHitResult {highlight: %h1, ranges: [%r1]} ]返される `HighlightHitResult$I 内には %r1 しか含まれないことに注意 — %h1 内で当たった範囲oは %r1 しかないので。
◎ [ HighlightHitResult {highlight: h1, ranges: [r1]} ], if the user clicks on character "a". Note that only r1 is included in the HighlightHitResult returned since that’s the only range in h1 that was hit. -
"b" ⇒
[ HighlightHitResult {highlight: %h2, ranges: [%r2]}, HighlightHitResult {highlight: %h1, ranges: [%r1]} ]%h2 は %h1 よりも優先度が高いので。
◎ [ HighlightHitResult {highlight: h2, ranges: [r2]}, HighlightHitResult {highlight: h1, ranges: [r1]} ], if the user clicks on character "b", as h2 has higher priority than h1. - "c" ⇒ `[]^c ◎ [], if the user clicks on character "c".
-
"d"
⇒
[ HighlightHitResult {highlight: %h1, ranges: [%r3]} ]◎ [ HighlightHitResult {highlight: h1, ranges: [r3]} ], if the user clicks on character "d".
`highlightsFromPoint()$m ~methodは、 `HighlightRegistry$I ~interfaceの一部を成すものとして定義される： ◎ The method highlightsFromPoint is defined as part of the HighlightRegistry interface as follows:
partial interface `HighlightRegistry$I {
`sequence$<`HighlightHitResult$I> `highlightsFromPoint$m(`float$ %x, `float$ %y, optional `HighlightsFromPointOptions$I %options = {});
};
dictionary `HighlightHitResult@I {
`Highlight$I `highlight@mb;
`sequence$<`AbstractRange$I> `ranges@mb;
};
dictionary `HighlightsFromPointOptions@I {
`sequence$<`ShadowRoot$I> `shadowRoots@mb = [];
};
`highlightsFromPoint(x, y, options)@m ~method手続きは、 次を遂行した結果を表現する`連列$を返す： ◎ The highlightsFromPoint(x, y, options) method must return the result of running these steps:
- %結果~群 ~LET « » ◎ ↓↓
-
~IF［ ~OR↓ ］…
-
~NOT ~AND↓：
- 0 ~LTE %x ~LTE `表示域$の`実効~横幅$
- 0 ~LTE %y ~LTE `表示域$の`実効~縦幅$
-
ある要素に関して， ~AND↓ が満たされる：
- それに結付けられた~boxは、 次を満たす`~box$のうち塗り順序において最上層にある ⇒ 表示域の各~子孫に適用される`変形$が適用されている下で， `表示域$内の 座標 ( %x, %y ) における`接触判定$の~targetになる
- ある`~shadow~tree$内にある
- その`~shadow根$el ~NIN %~option群[ "`shadowRoots$mb" ]
…ならば ⇒ ~RET %結果~群
◎ If any of the following are true, return the empty sequence: • x is negative • y is negative • x is greater than the viewport width excluding the size of a rendered scroll bar (if any) • y is greater than the viewport height excluding the size of a rendered scroll bar (if any) • The topmost box in the viewport in paint order that would be a target for hit testing at coordinates x,y when applying the transforms that apply to the descendants of the viewport, has an element associated to it that’s in a shadow tree whose shadow root is not contained by options.shadowRoots. -
-
コレが表現する`強調~registry$が表現する`~map~entry群$の`値~群$mapを成す ~EACH( `Highlight$I %強調 ) に対し，逆順に†： ◎ ↑↑ Otherwise, let results be an empty sequence. ◎ For each Highlight highlight in this HighlightRegistry:
【† “逆順” は、 `優先度$の定義に付随する記述 — “優先度が等しいものどうしは，後に登録されたものほど実質的な優先度は高くなる” （したがって、 %結果~群 における順序は，`~map~entry群$に対し施行される順序とは逆になる必要がある） — を反映するための，この訳による追加。 】
- %範囲o群 ~SET « » ◎ ↓↓ Let result be a new HighlightHitResult with highlight set to highlight.
-
%強調 を成す ~EACH( `AbstractRange$I %抽象-範囲o ) に対し： ◎ For each AbstractRange abstractRange in highlight:
- ~IF［ %抽象-範囲o は `StaticRange$I である ］~AND［ %抽象-範囲o は`妥当$rgでない ］ ⇒ ~CONTINUE ◎ If abstractRange is an invalid StaticRange, then continue.
- %範囲o ~LET `新たな~obj$( `Range$I ) — その ⇒＃ `始端~node$ ~SET %抽象-範囲o の`始端~node$, `終端~node$ ~SET %抽象-範囲o の`終端~node$, `始端~offset$ ~SET %抽象-範囲o の`始端~offset$, `終端~offset$ ~SET %抽象-範囲o の`終端~offset$ ◎ Let range be a new Range whose start node and end node are set to abstractRange’s start node and end node respectively, and start offset and end offset are set to abstractRange’s start offset and end offset respectively.
- %矩形~群 ~LET %範囲o 上の `getClientRects$m ~method手続き() ◎ ↓
-
%矩形~群 を成す ~EACH( %矩形 ) に対し ⇒ ~IF［ 座標 ( %x, %y ) は %矩形 の内側にある ］ ⇒＃ %範囲o群 に %抽象-範囲o を`付加する$； ~BREAK ◎ If the coordinates x,y fall inside at least one of the DOMRects returned by calling getClientRects() on range, then append abstractRange to result.ranges.
注記： `接触判定$の~~詳細は、 この仕様の視野から外れる。 したがって， `highlightsFromPoint()$m の正確な詳細についても同様になる。 接触判定は、 希望的には，~CSSまたは~HTMLの将来における改訂にて定義されることになる。 ◎ Note: The specifics of hit testing are out of scope of this specification and therefore the exact details of highlightsFromPoint() are too. Hit testing will hopefully be defined in a future revision of CSS or HTML.
- ~IF［ %範囲o群 は`空$でない ］ ⇒ %結果~群 に次を表現する新たな `HighlightHitResult$I を付加する ⇒ «[ "`highlight$mb" → %強調, "`ranges$mb" → %範囲o群 ]» ◎ If result.ranges is not empty, append result to results.
-
~RET `~listを降順に~sortする$( %結果~群, 次の手続き )
手続きは、 所与の( `HighlightHitResult$I %A, `HighlightHitResult$I %B ) に対し ⇒ ~RET ~IS［ %A[ "`highlight$mb" ] の`優先度$ ~LT %B[ "`highlight$mb" ] の`優先度$ ］◎ Sort results by descending order of priority of its HighlightHitResults' highlight attributes. - ~RET %結果~群 ◎ Return results.
7. ~eventの取扱い
~eventに関する節は、 まだこれから — この`説明書き＠https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/highlight/events-explainer.md$に基づくことになろう。 ◎ Section on Events TBD, based on https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/highlight/events-explainer.md
~custom強調は、 ~eventを取扱うための専用な仕組みを備えるべきか？ そのような仕組みは、 一般に，疑似要素に追加されるべきか？ ◎ should custom highlights have a dedicated event handling mechanism, or should that be added to pseudo-elements in general?
~privacyの考慮点
◎非規範的この仕様は、 新たな~privacyの懸念を導入するものと考えられてはいない。 これが正確aでない疑義がある者は、 ~CSS~WGか編集者たちに~~連絡をとることが奨励される。 ◎ This specification is not thought to introduce any new privacy concern. Anyone suspecting that this is not accurate is encouraged to get in touch with the CSS Working Group or the co-editors.
~securityの考慮点
◎非規範的この仕様は、 新たな~securityの懸念を導入するものと考えられてはいない。 これが正確aでない疑義がある者は、 ~CSS~WGか編集者たちに~~連絡をとることが奨励される。 ◎ This specification is not thought to introduce any new security concern. Anyone suspecting that this is not accurate is encouraged to get in touch with the CSS Working Group or the co-editors.
謝辞
◎非規範的（編集者~以外の）貢献者たちをここに挙げる。 ◎ Acknowledge people (other than editors) who deserve credit for this.
変更点
◎非規範的- `2021年 12月 15日 作業草案＠~TR/2020/WD-css-highlight-api-1-20211215/$ からの変更点 （編集上の改善や小さな手直しは除く） ◎ Changes since the 15 December 2021 Working Draft
- `HighlightRegistry$I に `highlightsFromPoint()$m ~methodを追加した。 （`7513$pull） ◎ Added a highlightsFromPoint method to HighlightRegistry. (See Issue 7513)
- 強調を塗直すときは、 非同期に行う必要があるものと指定した。 （`6987$pull） ◎ Specified that highlight repainting has to be done asynchronously. (See Issue 6987)
- ~UAは、 `~custom強調$用には，`~pairにされた既定の強調~色$を指定し得ないことを明確化した。 （`6665$pull） ◎ Clarify that UAs cannot specify paired default highlight colors for custom highlights. (See Issue 6665)
- `~custom強調$には、 `封込め$境界†をまたがらないようにする制約は無いことを明確化した。 （ `4598$issue ） 【† 本文では、単に “要素~境界” と記されている（挙げられた課題を見よ）。】 ◎ Clarify that there is no restriction on custom highlights crossing containment boundaries. (See Issue 4598)
- 国際-化にあたって、［ `書記素$／`補足的な文字$ ］の途中に`範囲o$の`境界点$を設置しないよう，警告を追加した。 ◎ Added an I18N warning about placement of range endpoints in the middle of a grapheme or supplementary character.
- `2020年 12月 8日 作業草案＠~TR/2020/WD-css-highlight-api-1-20201208/$ からの変更点 （編集上の改善や小さな手直しは除く） ◎ Changes since the 8 December 2020 Working Draft ◎ In addition to various editorial improvements and minor tweaks, the main changes are:
- `HighlightsRegister^I を `HighlightRegistry$I に改称した。 ◎ Renamed HighlightsRegister to HighlightRegistry
- `HighlightRegistry$I から 冗長な `add()^m ~methodを除去した。 （ `6092$pull ） ◎ Removed the redundant add() method from HighlightRegistry. (See Issue 6092)
- ~custom強調~overlayを~nativeな強調~overlayより下に積層するようにした。 （`4595$pull） ◎ Make custom highlight overlays stack below native highlight overlays. (See Issue 4595)
- 強調の優先度を浮動小数点数ではなく整数で取扱うようにした。 （`4592$pull） ◎ Handle highlight priority with integers rather than floats. (See Issue 4592)
- 強調~優先度~用の既定の値は 0 になるものと定義した。 （`6136$pull） ◎ Define the default value for highlight priority to be 0. (See Issue 6136)
- `HighlightRegistry^I を~maplikeにした（~setlikeではなく）。 `Highlight$I から `name^c ~propを除去した。 （`5910$pull） ◎ Made HighlightRegistry maplike (rather than setlike) and remove name property from Highlight. (See Issue 5910)
- 間違った~windowからの範囲oは塗られないことを明確化した。 （`6417$pull） ◎ Clarified that ranges from the wrong window are not painted. (See Issue 6417)
- ~custom強調には，~UA~styleは無いものと指定した。 （`6375$pull） ◎ Specify that custom highlights have no UA styles. (See Issue 6375)
- 範囲oの無効~化を `DOM$r 仕様へ先送りした （`4597$pull） ◎ Deferred to the [DOM] specification for range invalidation (See Issue 4597)
- `Highlight$I に `type$m 属性を追加した — 強調を~accessibility~toolに公開する~supportにおいて、 【種別が】異なる強調に もっと明瞭な意味論を与えるため。 （`6498$pull） ◎ Added a type attribute to Highlight to give clearer semantics to different highlights, in support of exposing highlights to accessibility tools. (See Issue 6498)
- `2020年 10 月 22日 作業草案＠~TR/2020/WD-css-highlight-api-1-20201022/$ からの変更点 ◎ Changes since the 22 October 2020 Working Draft
- 編集上の変更点しかない — `~~差分＠https://services.w3.org/htmldiff?doc1=https%3A%2F%2Fwww.w3.org%2FTR%2F2020%2FWD-css-highlight-api-1-20201022%2F&doc2=https%3A%2F%2Fwww.w3.org%2FTR%2Fcss-highlight-api-1%2F$ を見よ。 ◎ There have been only editorial changes since the 22 October 2020 Working Draft; see diffs.