Document (rozszerzenie)#
Document.hidden#
Właściwość hidden zwraca boolowską wartość true jeśli dany dokument zawarty w kontekście przeglądania najwyższego poziomu jest całkowicie niewidoczny, w przeciwnym razie zwrócona zostanie wartość false (tj. kiedy dokument zawarty w kontekście przeglądania najwyższego poziomu jest częściowo widoczny przynajmniej na jednym ekranie). Właściwość jest tylko do odczytu.
Składnia#
Samo wywołanie i poszczególne jego części najlepiej objaśnić na zapisie składniowym:
var is_hidden = document.hidden;
gdzie poszczególne człony oznaczają:
is_hidden- boolowskietruelubfalse.document- dokument będący obiektem kontekstu.
Jeśli widok domyślny dokumentu jest wartością null to właściwość hidden musi zawsze zwracać boolowską wartość true.
Aby uwzględnić narzędzia dostępności, które zajmują zazwyczaj cały ekran, ale wciąż pokazują widok strony, to w stosownych przypadkach właściwość hidden może zwracać boolowską wartość false, kiedy aplikacja kliencka nie jest zminimalizowana, ale jest całkowicie zasłonięta przez inne aplikacje.
Oto kilka klasycznych przypadków, gdzie zastosowana zostanie konkretna wartość dla właściwość hidden:
true- Aplikacja kliencka jest zminimalizowana.
- Aplikacja kliencka nie jest zminimalizowana, ale strona znajduje się na nieaktywnej karcie.
- Aplikacja kliencka ma rozładować (opuścić) stronę.
- Aplikacja kliencka ma przejść do pozycji w historii sesji.
- Ekran blokady w systemie operacyjnym jest wyświetlany.
false- Aplikacja kliencka nie jest zminimalizowana i strona znajduje się na aktywnej karcie (na pierwszym planie).
- Aplikacja kliencka jest całkowicie zasłonięta przez narzędzia dostępności (np. szkło powiększające), ale widok strony jest pokazywany.
Praktyczne operowanie właściwością hidden najczęściej odbywa się poprzez nasłuchiwanie dedykowanego zdarzenia typu visibilitychange.
W przeglądarkach, które nie wspierają właściwości hidden każde odwołanie do niej zwróci wartość undefined (pod warunkiem, że sami jej nie ustawimy). Jest to jedna z fałszywych wartości (falsy values) i w wyrażeniach warunkowych będzie oznaczać, że strona jest zawsze widoczna. Takie zachowanie zostało wprowadzone celowo dla zapewnienia wstecznej kompatybilności z programami nie obsługującymi najnowszego API.
Alternatywnie można skorzystać z bardziej szczegółowej właściwości Document.visibilityState.
Prosty przykład:
<script>
document.write(document); // [object HTMLDocument]
document.write("<br>");
document.write(document.defaultView); // [object Window]
document.write("<br>");
document.write(document.hidden); // false
document.write("<br><br>");
var new_doc = document.implementation.createHTMLDocument("Samotny dokument");
document.write(new_doc); // [object HTMLDocument]
document.write("<br>");
document.write(new_doc.defaultView); // null
document.write("<br>");
document.write(new_doc.hidden); // true
</script>Interfejs Web IDL#
readonly attribute boolean hidden;