ページ可視性 — Page Visibility 2

1. 序論

Page Visibility API は、~program的に`~top-level閲覧文脈$の`可視性~状態$を決定したり, `可視性~状態$の変化~時に通知してもらえるようにするための手段を定義する。 ~pageの`可視性~状態$を決定できない間、~web開発者たちは，~web~pageを常に可視とみなして設計してきた。 これは、~machine資源をより多く費やすのみならず、~web開発者たちが［ ~pageが利用者から可視であるかどうかに基づいて 実行時にふるまいを切り替える ］ことも，難しくしている。 ~web~pageを，その`可視性~状態$について知り得る下で設計できれば、利用者~体験と~siteの効率性を改善させられる。 ◎ The Page Visibility API defines a means to programmatically determine the visibility state of a top level browsing context, and to be notified if the visibility state changes. Without knowing the visibility state of a page, web developers have been designing web pages as if they are always visible. This not only results in higher machine resource utilization, but it prevents web developers from making runtime decisions based on whether the web page is visible to the user. Designing web pages with knowledge of the page's visibility state can result in improved user experiences and power efficient sites.

この~APIにより、~web~appは，利用者から `visible$l （可視）かどうかに基づいて挙動を改めれるようになる。 例えば、~pageが `visible$l でなくなったときに 仕事を縮退できる。 ◎ With this API, web applications can choose to alter their behavior based on whether they are visible to the user or not. For example, this API can be used to scale back work when the page is no longer visible.

2. 適合性

【 この節の内容は W3C 日本語訳 共通ページ に委譲 】

【この訳に固有の表記規約】

この訳の，~algoや定義の記述に利用されている各種記号（ ~LET, ~EQ, ~IF, ~EACH (…), ~RET, 等々）の意味や定義の詳細は、~SYMBOL_DEF_REFを~~参照されたし。

3. 用例

~appは、自身が `visible$l のときは~videoを自動再生し， `hidden$l のときは 再生を自動的に静止させることで、利用者~体験を改善させつつ， CPU と電力の効率性を最適化することもできる： ◎ To improve the user experience and optimize CPU and power efficiency the application could autoplay a video when the application is visible, and automatically pause the playback when the application is hidden:

var %videoElement = document.getElementById("videoElement");

/* 
`visible$l なら~videoを自動再生する
◎
Autoplay the video if application is visible
 */
if (document.visibilityState == "visible") {
  %videoElement.play();
}

/* 
~page可視性~変化~eventを取扱う
◎
Handle page visibility change events
 */
function handleVisibilityChange() {
if (document.visibilityState == "hidden") {
    %videoElement.pause();
  } else {
    %videoElement.play();
  }
}

document.addEventListener(
    '`visibilitychange^et', handleVisibilityChange, false
);

似たような~logicは、［ より賢く［ 静止-／再開-／加減速- ］する ／ ~animation~loopなどの ~app~codeの実行 ／ 解析 ］その他の処理にも適用-可能になる。 `Document$I ~interfaceの `visibilityState$m 属性と `visibilitychange$et ~eventを組合せれば、~appは，~pageの可視性~eventを照会したり, ~listenして、利用者~体験を向上させつつ 効率性や処理能も改善できるようになる。 ◎ Similar logic can be applied to intelligently pause and resume, or throttle, execution of application code such as animation loops, analytics, and other types of processing. By combining the visibilityState attribute of the Document interface and the visibilitychange event, the application is able to both query and listen to page visibility events to deliver a better user experience, as well as improve efficiency and performance of its execution.

4. 可視性~状態と `VisibilityState^I 列挙型

`~top-level閲覧文脈$の`文書$は、次のいずれかの `可視性~状態@ をとり得る： ◎ The Document of the top level browsing context can be in one of the following visibility states:

`hidden@l

`文書$のどの部分も，どの~screenにおいても `visible$l でないことを表す。 ◎ The Document is not visible at all on any screen.

`visible@l

`文書$は，ある~screenにて どこか一部が可視であることを表す。 これは `hidden$m 属性が ~F に設定されているときと同じ条件になる。 ◎ The Document is at least partially visible on at least one screen. This is the same condition under which the hidden attribute is set to false.

`可視性~状態$ は、 `VisibilityState$I 列挙型の値を介して~APIに反映される： ◎ The visibility states are reflected in the API via the VisibilityState enum.

enum `VisibilityState@I {
    `hidden$l,
    `visible$l,
};

5. `Document^I ~interfaceに対する拡張

この仕様は、 `Document$I ~interface `HTML5$r を拡張する： ◎ This specification extends the [HTML51] Document interface:

partial interface `Document$I {
    readonly    attribute boolean         `hidden$m;
    readonly    attribute `VisibilityState$I `visibilityState$m;
                attribute EventHandler `onvisibilitychange$m;
};

`hidden@m ◎ 5.1. hidden attribute

取得子は、次に与える `文書が hidden かどうか決定する手続き@ の結果を返さ~MUST： ◎ On getting, the hidden attribute MUST run the steps to determine if the document is hidden:

1. ~RET `可視性~状態を決定する手続き$を走らせた結果に応じて ⇒＃ `visible$l ならば ~F ／ ~ELSE_ ~T ／ ◎ If steps to determine the visibility state return visible, then return false. ◎ Otherwise, return true.

注記： `hidden$m 属性の~supportは保守されているのは、歴史的~理由による。 開発者は、可能な所では `visibilityState$m を利用するべきである。 ◎ Support for hidden attribute is maintained for historical reasons. Developers should use visibilityState where possible.

`visibilityState@m ◎ 5.2. visibilityState attribute

取得子は、次に与える `可視性~状態を決定する手続き@ の結果を返さ~MUST： ◎ On getting, the visibilityState attribute the user agent MUST run the steps to determine the visibility state:

1. %文書 ~LET `~top-level閲覧文脈$の`文書$ ◎ Let doc be the Document of the top level browsing context.
2. ~IF［ %文書 の `defaultView$m ~EQ ~NULL ］ ⇒ ~RET `hidden$l ◎ If the defaultView of doc is null, return hidden.

3. 次に従って， %文書 の`可視性~状態$に最も近く合致する `VisibilityState$I 値を返す： ◎ Otherwise, return the VisibilityState value that best matches the visibility state of doc:

   1. ~IF［ 次のいずれかに該当する ］ ⇒ ~RET `visible$l ： ◎ Return "visible" if:

      • ［ ~UAは最小化されてない 【アイコン化, 等】 ］~AND［ %文書 は前面の~tab上にある ］ ◎ The user agent is not minimized and doc is the foreground tab.
      • ［ ~UAは 拡大鏡などの~accessibility~toolにより全部的に遮られている ］~AND［ %文書 の~viewは見えている ］ ◎ The user agent is fully obscured by an accessibility tool, like a magnifier, but a view of the doc is shown.

   2. ~IF［ 次のいずれかに該当する ］ ⇒ ~RET `hidden$l ： ◎ Return "hidden" if:

      • ［ ~UAは最小化されている ］~OR［ %文書 は背後の~tab上にある ］ ◎ The user agent is minimized. ◎ The user agent is not minimized, but doc is on a background tab.
      • ~UA は %文書 を`~unload$しつつある ◎ The user agent is to unload doc.
      • OS が~screenを~lockしている ◎ The Operating System lock screen is shown.

概して，［ 全~screenでありつつ, ~pageの~viewも示すような支援技術 ］に適応するためとして、次に該当するときは，適用-可能なら `hidden$l に代えて `visible$l が返されても~MAY ⇒ ~UAは最小化されてはいないが，他の~appで全部的に遮られているとき ◎ To accommodate assistive technologies that are typically full screen but still show a view of the page, when applicable, on getting, the visibilityState attribute MAY return visible, instead of hidden, when the user agent is not minimized but is fully obscured by other applications.

`onvisibilitychange@m ◎ 5.3. onvisiblitychange event handler

`visibilitychange$et ~event型~用の`~event~handler IDL 属性$。 ◎ onvisibilitychange is an event handler IDL attribute for the visibilitychange event type.

6. `visibilitychange^et （可視性の変化）に反応するとき

以下における`~task$の`~task源$は、`利用者~対話~task源$とする。 ◎ The task source for these tasks is the user interaction task source.

~UAは、`~top-level閲覧文脈$の`文書$の可視性が変化したものと決定したときは，次の手続きを走らせ~MUST。 ◎ When the user agent determines that the visibility of the Document of the top level browsing context has changed, the user agent MUST run the following steps:

1. %文書 ~LET `~top-level閲覧文脈$の`文書$ ◎ Let doc be the Document of the top level browsing context.

2. ~IF［ %文書 は現在 `visible$l である ］： ◎ If doc is now visible:

   1. %~task ~LET `~now~visible~algo$を走らせる`~task$ ◎ ↓
   2. ~IF［ `~session履歴~entry$に向けて辿っている ］ ⇒ `pageshow$et ~eventを発火する手続きに入る前に， %~task を走らせる ◎ If traversing to a session history entry, run the now visible algorithm before running the step to fire the pageshow event.
   3. ~ELSE ⇒ %~task を`~queueする$ ◎ Otherwise, queue a task that runs the now visible algorithm.

3. ~ELIF %文書 は［ `visible$l でなくなった ］~OR［ ~UAは %文書 を`~unload$しつつある ］： ◎ Else if doc is now not visible, or if the user agent is to unload doc:

   1. %~task ~LET `~now~hidden~algo$を走らせる`~task$ ◎ ↓
   2. ~IF［ ~UAは、 %文書 を`~unload$しつつある ］ ⇒ `文書~unload時の可視性~変更~手続き$の間に， %~task を走らす。 ◎ If the user agent is to unload the Document, run the now hidden algorithm during the unloading document visibility change steps.
   3. ~ELSE ⇒ %~task を`~queueする$ ◎ Otherwise, queue a task that runs the now hidden algorithm.

`~now~visible~algo@ は、次の手続きを同期的に走らす： ◎ The now visible algorithm runs the following steps synchronously:

1. `~top-level閲覧文脈$の`文書$に向けて，名前 `visibilitychange^et の`~eventを発火する$ ◎ Let doc be the Document of the top level browsing context. ◎ Fire a simple event named visibilitychange that bubbles, isn't cancelable, and has no default action, at the doc.

`~now~hidden~algo@ は、次の手続きを同期的に走らす： ◎ The now hidden algorithm runs the following steps synchronously:

1. `~top-level閲覧文脈$の`文書$に向けて，名前 `visibilitychange^et の`~eventを発火する$ ◎ Let doc be the Document of the top level browsing context. ◎ Fire a simple event named visibilitychange that bubbles, isn't cancelable, and has no default action, at the doc.

他から指定されない限り、 `visibilitychange^et には，既定動作はない。 ◎ ↑

7. ~privacyと保安

Page Visibility API は、`文書$が いつ可視または~focusされたかを開発者が知ることを可能化する。 `Window^I ~objに対する `focus$et や `blur$et ~eventなどの既存の仕組みは、`文書$が作動中かどうか検出する仕組みをすでに供している。 また、 `unload^et ~eventは、~pageが~unload中にあることを通知する。 ◎ The Page Visibility API enables developers to know when a Document is visible or in focus. Existing mechanisms, such as the focus and blur events, when attached to the Window object already provide a mechanism to detect when the Document is the active document; the unload event provides a notification that the page is being unloaded.

8. 各種用語

謝辞

この仕事に協力された次の方々に：

Thanks to Arvind Jain, Boris Zbarsky, Jatinder Mann, Nat Duca, Philippe Le Hegaret, Ryosuke Niwa, Shubhie Panicker, Todd Reifsteck, Yoav Weiss, and Zhiheng Wang, for their contributions to this work.