From 68fc8e96a9629e73469ed457abd955e548ec670c Mon Sep 17 00:00:00 2001 From: Florian Merz Date: Thu, 11 Feb 2021 14:49:58 +0100 Subject: unslug pt-br: move --- files/pt-br/web/api/api_de_desempenho/index.html | 138 --- .../web/api/api_push/best_practices/index.html | 73 -- files/pt-br/web/api/api_push/index.html | 172 --- files/pt-br/web/api/api_web_audio/index.html | 480 -------- .../api_web_audio/sintetizador_simples/index.html | 579 --------- .../web/api/audiocontext/currenttime/index.html | 114 -- .../api/baseaudiocontext/currenttime/index.html | 114 ++ files/pt-br/web/api/battery_status_api/index.html | 58 + .../ondischargingtimechange/index.html | 35 + .../ondischargintimechange/index.html | 35 - .../api/canvas_api/a_basic_ray-caster/index.html | 76 ++ files/pt-br/web/api/canvas_api/index.html | 134 ++ .../tutorial/advanced_animations/index.html | 386 ++++++ .../tutorial/applying_styles_and_colors/index.html | 725 +++++++++++ .../tutorial/basic_animations/index.html | 331 +++++ .../api/canvas_api/tutorial/basic_usage/index.html | 153 +++ .../tutorial/compositing/example/index.html | 294 +++++ .../api/canvas_api/tutorial/compositing/index.html | 112 ++ .../canvas_api/tutorial/drawing_shapes/index.html | 581 +++++++++ .../canvas_api/tutorial/drawing_text/index.html | 169 +++ .../web/api/canvas_api/tutorial/finale/index.html | 49 + files/pt-br/web/api/canvas_api/tutorial/index.html | 56 + .../tutorial/optimizing_canvas/index.html | 115 ++ .../canvas_api/tutorial/using_images/index.html | 333 +++++ .../web/api/crypto/getrandomvalues/index.html | 116 ++ files/pt-br/web/api/cryptokey/algorithm/index.html | 113 -- .../pt-br/web/api/cryptokey/extractable/index.html | 111 -- files/pt-br/web/api/cryptokey/type/index.html | 118 -- files/pt-br/web/api/cryptokey/usages/index.html | 124 -- files/pt-br/web/api/deviceacceleration/index.html | 43 - .../api/devicemotioneventacceleration/index.html | 43 + .../api/devicemotioneventrotationrate/index.html | 93 ++ files/pt-br/web/api/devicerotationrate/index.html | 93 -- .../web/api/document/activeelement/index.html | 165 --- .../web/api/document/elementfrompoint/index.html | 133 -- .../web/api/document/elementoregistrado/index.html | 132 -- .../pt-br/web/api/document/getselection/index.html | 9 - .../api/document/readystatechange_event/index.html | 83 ++ .../web/api/document/registerelement/index.html | 132 ++ .../api/document_object_model/events/index.html | 82 ++ .../api/document_object_model/examples/index.html | 376 ++++++ .../how_to_create_a_dom_tree/index.html | 145 +++ .../pt-br/web/api/document_object_model/index.html | 379 ++++++ .../document_object_model/introduction/index.html | 251 ++++ .../document_object_model/whitespace/index.html | 227 ++++ .../documentorshadowroot/activeelement/index.html | 165 +++ .../elementfrompoint/index.html | 133 ++ .../documentorshadowroot/getselection/index.html | 9 + files/pt-br/web/api/element/accesskey/index.html | 19 - .../web/api/element/addeventlistener/index.html | 322 ----- files/pt-br/web/api/element/blur_event/index.html | 154 +++ files/pt-br/web/api/element/focus_event/index.html | 137 +++ .../pt-br/web/api/element/focusin_event/index.html | 125 ++ .../web/api/element/focusout_event/index.html | 125 ++ files/pt-br/web/api/element/name/index.html | 80 -- .../comparativo_entre_event_targets/index.html | 167 --- .../event/comparison_of_event_targets/index.html | 167 +++ .../api/eventtarget/addeventlistener/index.html | 322 +++++ .../fetch_api/cross-global_fetch_usage/index.html | 35 + .../fetch_api/uso_de_busca_cross-global/index.html | 35 - files/pt-br/web/api/geolocation_api/index.html | 227 ++++ files/pt-br/web/api/history_api/example/index.html | 418 +++++++ files/pt-br/web/api/history_api/exemplo/index.html | 418 ------- .../file_drag_and_drop/index.html | 91 ++ .../web/api/html_drag_and_drop_api/index.html | 258 ++++ .../web/api/htmlcontentelement/select/index.html | 98 ++ .../web/api/htmlcontentelement/seletor/index.html | 98 -- .../pt-br/web/api/htmlelement/accesskey/index.html | 19 + files/pt-br/web/api/htmlelement/blur/index.html | 89 -- files/pt-br/web/api/htmlelement/dataset/index.html | 97 -- files/pt-br/web/api/htmlelement/focus/index.html | 62 - .../pt-br/web/api/htmlelement/innertext/index.html | 86 ++ .../web/api/htmlelement/input_event/index.html | 248 ++++ .../api/htmlmediaelement/abort_event/index.html | 70 ++ .../web/api/htmlorforeignelement/blur/index.html | 89 ++ .../api/htmlorforeignelement/dataset/index.html | 97 ++ .../web/api/htmlorforeignelement/focus/index.html | 62 + .../api/indexeddb_api/usando_indexeddb/index.html | 1281 -------------------- .../api/indexeddb_api/using_indexeddb/index.html | 1281 ++++++++++++++++++++ .../web/api/network_information_api/index.html | 56 + .../index.html" | 55 - files/pt-br/web/api/node/innertext/index.html | 86 -- files/pt-br/web/api/notificacoes/index.html | 217 ---- files/pt-br/web/api/notification/index.html | 217 ++++ files/pt-br/web/api/performance_api/index.html | 138 +++ .../web/api/push_api/best_practices/index.html | 73 ++ files/pt-br/web/api/push_api/index.html | 172 +++ .../api/randomsource/getrandomvalues/index.html | 116 -- files/pt-br/web/api/randomsource/index.html | 109 -- files/pt-br/web/api/selection/index.html | 206 ++++ .../web/api/sele\303\247\303\243o/index.html" | 206 ---- .../api/svgaelement/svgalement.target/index.html | 106 -- files/pt-br/web/api/svgaelement/target/index.html | 106 ++ files/pt-br/web/api/touch_events/index.html | 353 ++++++ .../usando_a_web_animations_api/index.html | 358 ------ .../using_the_web_animations_api/index.html | 358 ++++++ files/pt-br/web/api/web_audio_api/index.html | 480 ++++++++ .../web/api/web_audio_api/simple_synth/index.html | 579 +++++++++ files/pt-br/web/api/web_storage_api/index.html | 139 +++ .../using_the_web_storage_api/index.html | 267 ++++ .../pt-br/web/api/web_storage_api_pt_br/index.html | 139 --- .../using_the_web_storage_api/index.html | 267 ---- .../index.html | 226 ++++ .../index.html | 226 ---- .../simple_rtcdatachannel_sample/index.html | 272 +++++ .../simples_rtcdatachannel_amostra/index.html | 272 ----- files/pt-br/web/api/websockets_api/index.html | 178 +++ .../index.html | 182 +++ .../writing_websocket_server/index.html | 237 ++++ .../writing_websocket_servers/index.html | 263 ++++ .../web/api/window/beforeunload_event/index.html | 106 ++ .../api/window/domcontentloaded_event/index.html | 177 +++ files/pt-br/web/api/window/load_event/index.html | 89 ++ files/pt-br/web/api/window/localstorage/index.html | 123 ++ files/pt-br/web/api/window/onscroll/index.html | 99 -- files/pt-br/web/api/window/url/index.html | 101 -- .../web/api/window/window.localstorage/index.html | 123 -- files/pt-br/web/api/windowbase64/atob/index.html | 72 -- files/pt-br/web/api/windowbase64/index.html | 121 -- .../api/windoworworkerglobalscope/atob/index.html | 72 ++ .../cleartimeout/index.html | 100 ++ .../web/api/windowtimers/cleartimeout/index.html | 100 -- files/pt-br/web/api/windowtimers/index.html | 117 -- .../requisicoes_sincronas_e_assincronas/index.html | 234 ---- .../index.html | 234 ++++ .../usando_xmlhttprequest/index.html | 688 ----------- .../xmlhttprequest/using_xmlhttprequest/index.html | 688 +++++++++++ 127 files changed, 16155 insertions(+), 9112 deletions(-) delete mode 100644 files/pt-br/web/api/api_de_desempenho/index.html delete mode 100644 files/pt-br/web/api/api_push/best_practices/index.html delete mode 100644 files/pt-br/web/api/api_push/index.html delete mode 100644 files/pt-br/web/api/api_web_audio/index.html delete mode 100644 files/pt-br/web/api/api_web_audio/sintetizador_simples/index.html delete mode 100644 files/pt-br/web/api/audiocontext/currenttime/index.html create mode 100644 files/pt-br/web/api/baseaudiocontext/currenttime/index.html create mode 100644 files/pt-br/web/api/battery_status_api/index.html create mode 100644 files/pt-br/web/api/batterymanager/ondischargingtimechange/index.html delete mode 100644 files/pt-br/web/api/batterymanager/ondischargintimechange/index.html create mode 100644 files/pt-br/web/api/canvas_api/a_basic_ray-caster/index.html create mode 100644 files/pt-br/web/api/canvas_api/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/advanced_animations/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/basic_animations/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/basic_usage/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/compositing/example/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/compositing/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/drawing_shapes/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/drawing_text/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/finale/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/optimizing_canvas/index.html create mode 100644 files/pt-br/web/api/canvas_api/tutorial/using_images/index.html create mode 100644 files/pt-br/web/api/crypto/getrandomvalues/index.html delete mode 100644 files/pt-br/web/api/cryptokey/algorithm/index.html delete mode 100644 files/pt-br/web/api/cryptokey/extractable/index.html delete mode 100644 files/pt-br/web/api/cryptokey/type/index.html delete mode 100644 files/pt-br/web/api/cryptokey/usages/index.html delete mode 100644 files/pt-br/web/api/deviceacceleration/index.html create mode 100644 files/pt-br/web/api/devicemotioneventacceleration/index.html create mode 100644 files/pt-br/web/api/devicemotioneventrotationrate/index.html delete mode 100644 files/pt-br/web/api/devicerotationrate/index.html delete mode 100644 files/pt-br/web/api/document/activeelement/index.html delete mode 100644 files/pt-br/web/api/document/elementfrompoint/index.html delete mode 100644 files/pt-br/web/api/document/elementoregistrado/index.html delete mode 100644 files/pt-br/web/api/document/getselection/index.html create mode 100644 files/pt-br/web/api/document/readystatechange_event/index.html create mode 100644 files/pt-br/web/api/document/registerelement/index.html create mode 100644 files/pt-br/web/api/document_object_model/events/index.html create mode 100644 files/pt-br/web/api/document_object_model/examples/index.html create mode 100644 files/pt-br/web/api/document_object_model/how_to_create_a_dom_tree/index.html create mode 100644 files/pt-br/web/api/document_object_model/index.html create mode 100644 files/pt-br/web/api/document_object_model/introduction/index.html create mode 100644 files/pt-br/web/api/document_object_model/whitespace/index.html create mode 100644 files/pt-br/web/api/documentorshadowroot/activeelement/index.html create mode 100644 files/pt-br/web/api/documentorshadowroot/elementfrompoint/index.html create mode 100644 files/pt-br/web/api/documentorshadowroot/getselection/index.html delete mode 100644 files/pt-br/web/api/element/accesskey/index.html delete mode 100644 files/pt-br/web/api/element/addeventlistener/index.html create mode 100644 files/pt-br/web/api/element/blur_event/index.html create mode 100644 files/pt-br/web/api/element/focus_event/index.html create mode 100644 files/pt-br/web/api/element/focusin_event/index.html create mode 100644 files/pt-br/web/api/element/focusout_event/index.html delete mode 100644 files/pt-br/web/api/element/name/index.html delete mode 100644 files/pt-br/web/api/event/comparativo_entre_event_targets/index.html create mode 100644 files/pt-br/web/api/event/comparison_of_event_targets/index.html create mode 100644 files/pt-br/web/api/eventtarget/addeventlistener/index.html create mode 100644 files/pt-br/web/api/fetch_api/cross-global_fetch_usage/index.html delete mode 100644 files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html create mode 100644 files/pt-br/web/api/geolocation_api/index.html create mode 100644 files/pt-br/web/api/history_api/example/index.html delete mode 100644 files/pt-br/web/api/history_api/exemplo/index.html create mode 100644 files/pt-br/web/api/html_drag_and_drop_api/file_drag_and_drop/index.html create mode 100644 files/pt-br/web/api/html_drag_and_drop_api/index.html create mode 100644 files/pt-br/web/api/htmlcontentelement/select/index.html delete mode 100644 files/pt-br/web/api/htmlcontentelement/seletor/index.html create mode 100644 files/pt-br/web/api/htmlelement/accesskey/index.html delete mode 100644 files/pt-br/web/api/htmlelement/blur/index.html delete mode 100644 files/pt-br/web/api/htmlelement/dataset/index.html delete mode 100644 files/pt-br/web/api/htmlelement/focus/index.html create mode 100644 files/pt-br/web/api/htmlelement/innertext/index.html create mode 100644 files/pt-br/web/api/htmlelement/input_event/index.html create mode 100644 files/pt-br/web/api/htmlmediaelement/abort_event/index.html create mode 100644 files/pt-br/web/api/htmlorforeignelement/blur/index.html create mode 100644 files/pt-br/web/api/htmlorforeignelement/dataset/index.html create mode 100644 files/pt-br/web/api/htmlorforeignelement/focus/index.html delete mode 100644 files/pt-br/web/api/indexeddb_api/usando_indexeddb/index.html create mode 100644 files/pt-br/web/api/indexeddb_api/using_indexeddb/index.html create mode 100644 files/pt-br/web/api/network_information_api/index.html delete mode 100644 "files/pt-br/web/api/node/entendendo_o_uso_do_m\303\251todo_appendchild-javascript/index.html" delete mode 100644 files/pt-br/web/api/node/innertext/index.html delete mode 100644 files/pt-br/web/api/notificacoes/index.html create mode 100644 files/pt-br/web/api/notification/index.html create mode 100644 files/pt-br/web/api/performance_api/index.html create mode 100644 files/pt-br/web/api/push_api/best_practices/index.html create mode 100644 files/pt-br/web/api/push_api/index.html delete mode 100644 files/pt-br/web/api/randomsource/getrandomvalues/index.html delete mode 100644 files/pt-br/web/api/randomsource/index.html create mode 100644 files/pt-br/web/api/selection/index.html delete mode 100644 "files/pt-br/web/api/sele\303\247\303\243o/index.html" delete mode 100644 files/pt-br/web/api/svgaelement/svgalement.target/index.html create mode 100644 files/pt-br/web/api/svgaelement/target/index.html create mode 100644 files/pt-br/web/api/touch_events/index.html delete mode 100644 files/pt-br/web/api/web_animations_api/usando_a_web_animations_api/index.html create mode 100644 files/pt-br/web/api/web_animations_api/using_the_web_animations_api/index.html create mode 100644 files/pt-br/web/api/web_audio_api/index.html create mode 100644 files/pt-br/web/api/web_audio_api/simple_synth/index.html create mode 100644 files/pt-br/web/api/web_storage_api/index.html create mode 100644 files/pt-br/web/api/web_storage_api/using_the_web_storage_api/index.html delete mode 100644 files/pt-br/web/api/web_storage_api_pt_br/index.html delete mode 100644 files/pt-br/web/api/web_storage_api_pt_br/using_the_web_storage_api/index.html create mode 100644 files/pt-br/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html delete mode 100644 files/pt-br/web/api/webgl_api/tutorial/adicionando_conteudo_2d_a_um_contexto_webgl/index.html create mode 100644 files/pt-br/web/api/webrtc_api/simple_rtcdatachannel_sample/index.html delete mode 100644 files/pt-br/web/api/webrtc_api/simples_rtcdatachannel_amostra/index.html create mode 100644 files/pt-br/web/api/websockets_api/index.html create mode 100644 files/pt-br/web/api/websockets_api/writing_websocket_client_applications/index.html create mode 100644 files/pt-br/web/api/websockets_api/writing_websocket_server/index.html create mode 100644 files/pt-br/web/api/websockets_api/writing_websocket_servers/index.html create mode 100644 files/pt-br/web/api/window/beforeunload_event/index.html create mode 100644 files/pt-br/web/api/window/domcontentloaded_event/index.html create mode 100644 files/pt-br/web/api/window/load_event/index.html create mode 100644 files/pt-br/web/api/window/localstorage/index.html delete mode 100644 files/pt-br/web/api/window/onscroll/index.html delete mode 100644 files/pt-br/web/api/window/url/index.html delete mode 100644 files/pt-br/web/api/window/window.localstorage/index.html delete mode 100644 files/pt-br/web/api/windowbase64/atob/index.html delete mode 100644 files/pt-br/web/api/windowbase64/index.html create mode 100644 files/pt-br/web/api/windoworworkerglobalscope/atob/index.html create mode 100644 files/pt-br/web/api/windoworworkerglobalscope/cleartimeout/index.html delete mode 100644 files/pt-br/web/api/windowtimers/cleartimeout/index.html delete mode 100644 files/pt-br/web/api/windowtimers/index.html delete mode 100644 files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html create mode 100644 files/pt-br/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html delete mode 100644 files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html create mode 100644 files/pt-br/web/api/xmlhttprequest/using_xmlhttprequest/index.html (limited to 'files/pt-br/web/api') diff --git a/files/pt-br/web/api/api_de_desempenho/index.html b/files/pt-br/web/api/api_de_desempenho/index.html deleted file mode 100644 index 1b6997e293..0000000000 --- a/files/pt-br/web/api/api_de_desempenho/index.html +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: API de Desempenho -slug: Web/API/API_de_Desempenho -translation_of: Web/API/Performance_API ---- -
{{DefaultAPISidebar("High Resolution Time")}}
- -

The High Resolution Time standard defines a {{domxref("Performance")}} interface that supports client-side latency measurements within applications. The {{domxref("Performance")}} interfaces are considered high resolution because they are accurate to a thousandth of a millisecond (subject to hardware or software constraints). The interfaces support a number of use cases including calculating frame-rates (potentially important in animations) and benchmarking (such as the time to load a resource).

- -

Since a platform's system clock is subject to various skews (such as NTP adjustments), the interfaces support a monotonic clock i.e. a clock that is always increasing. As such, the Performance API defines a {{domxref("DOMHighResTimeStamp")}} type rather than using the {{jsxref("Date.now","Date.now()")}} interface.

- -

DOMHighResTimeStamp

- -

The {{domxref("DOMHighResTimeStamp")}} type, as its name implies, represents a high resolution point in time. This type is a double and is used by the performance interfaces. The value could be a discrete point in time or the difference in time between two discrete points in time.

- -

The unit of DOMHighResTimeStamp is milliseconds and should be accurate to 5 µs (microseconds). However, If the browser is unable to provide a time value accurate to 5 microseconds (because, for example, due to hardware or software constraints), the browser can represent the value as a time in milliseconds accurate to a millisecond.

- -

Methods

- -

The {{domxref("Performance")}} interface has two methods. The {{domxref("Performance.now","now()")}} method returns a {{domxref("DOMHighResTimeStamp")}} whose value that depends on the {{domxref("PerformanceTiming.navigationStart","navigation start")}} and scope. If the scope is a window, the value is the time the browser context was created and if the scope is a {{domxref("Worker","worker")}}, the value is the time the worker was created.

- -

The {{domxref("Performance.toJSON","toJSON()")}} method returns a serialization of the {{domxref("Performance")}} object, for those attributes that can be serialized.

- -

Properties

- -

The {{domxref("Performance")}} interface has two properties. The {{domxref("Performance.timing","timing")}} property returns a {{domxref("PerformanceTiming")}} object containing latency-related performance information such as the start of navigation time, start and end times for redirects, start and end times for responses, etc.

- -

The {{domxref("Performance.navigation","navigation")}} property returns a {{domxref("PerformanceNavigation")}} object representing the type of navigation that occurs in the given browsing context, such as the page was navigated to from history, the page was navigated to by following a link, etc.

- -

Interfaces

- -
-
{{domxref('Performance')}}
-
Provides methods and properties containing timing-related performance information for the given page.
-
{{domxref('PerformanceEntry')}}
-
Provides methods and properties the encapsulate a single performance metric that is part of the performance timeline.
-
{{domxref('PerformanceFrameTiming')}}
-
Provides methods and properties containing frame timing data about the browser's event loop.
-
{{domxref('PerformanceMark')}}
-
An abstract interface for performance entries with an entry type of "mark". Entries of this type are created by calling performance.mark() to add a named DOMHighResTimeStamp (the mark) to the browser's performance timeline.
-
{{domxref('PerformanceMeasure')}}
-
An abstract interface for performance entries with an entry type of "measure". Entries of this type are created by calling performance.measure() to add a namedDOMHighResTimeStamp (the measure) between two marks to the browser's performance timeline.
-
{{domxref('PerformanceNavigationTiming')}}
-
Provides methods and properties to store and retrieve high resolution timestamps or metrics regarding the browser's document navigation events.
-
{{domxref('PerformanceObserver')}}
-
Provides methods and properties used to observe performance measurement events and be notified of new performance entries as they are recorded in the browser's performance timeline.
-
{{domxref('PerformanceResourceTiming')}}
-
Provides methods and properties for retrieving and analyzing detailed network timing data regarding the loading of an application's resources.
-
- -

Specifications

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('Highres Time')}}{{Spec2('Highres Time')}}Initial definition.
{{SpecName('Highres Time Level 2')}}{{Spec2('Highres Time Level 2')}}Adds performance attribute on Window and WorkerGlobalScope.
{{SpecName('Highres Time Level 3')}}{{Spec2('Highres Time Level 3')}}Add timeOrigin property to Performance interface.
{{SpecName('Frame Timing')}}{{Spec2('Frame Timing')}}Adds PerformanceFrameTiming interface.
{{SpecName('Navigation Timing')}}{{Spec2('Navigation Timing')}}Adds the PerformanceTiming and PerformanceNavigation interfaces. Adds timing and navigation properties to the Performance interface.
{{SpecName('Navigation Timing Level 2')}}{{Spec2('Navigation Timing Level 2')}}Adds the PerformanceNavigationTiming interface. Obsolete's the the PerformanceTiming interface, the PerformanceNavigation interface, as well as the timing and navigation properties to the Performance interface.
{{SpecName('Performance Timeline')}}{{Spec2('Performance Timeline')}}Adds the PerformanceEntry interface, the PerformanceEntryList type, as well as the getEntries(), getEntriesByType(), and getEntriesByName() methods on the Performance interface.
{{SpecName('Performance Timeline Level 2')}}{{Spec2('Performance Timeline Level 2')}}Adds serializer to the PerformanceEntry interface as well as adding the PerformanceObserver interface and callback
{{SpecName('Resource Timing')}}{{Spec2('Resource Timing')}}Adds the PerformanceResourceTiming interface. Adds the clearResourceTimings() method, the setResourceTimingBufferSize() method, and the onresourcetimingbufferfull event handler to the Performance interface. Also adds the Timing-Allow-Origin response header.
{{SpecName('Resource Timing 2')}}{{Spec2('Resource Timing 2')}}Adds the nextHopProtocol, workerStart, transferSize, encodedBodySize, and decodedBodySize properties to the PerformanceResourceTiming interface.
{{SpecName('Resource Timing 3')}}{{Spec2('Resource Timing 3')}}
{{SpecName('User Timing')}}{{Spec2('User Timing')}}Adds mark(), clearMarks(), measure() and clearMeasures() methods to the Performance interface. Adds the PerformanceMark and PeformanceMeasure interfaces.
{{SpecName('User Timing Level 2')}}{{Spec2('User Timing Level 2')}}
- -

Implementation status

- -

As shown in the {{domxref("Performance")}} interface's Browser Compatibility table, most of these interfaces are broadly implemented by desktop browsers.

- -

To test your browser's support for the {{domxref("Performance")}} interface, run the perf-api-support application.

- -

See Also

- - diff --git a/files/pt-br/web/api/api_push/best_practices/index.html b/files/pt-br/web/api/api_push/best_practices/index.html deleted file mode 100644 index 9b0fafd2b7..0000000000 --- a/files/pt-br/web/api/api_push/best_practices/index.html +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Melhores práticas -slug: Web/API/API_Push/Best_Practices -tags: - - Apps - - Iniciante - - Melhores Práticas - - Notificações - - Push API - - Usabilidade -translation_of: Web/API/Push_API/Best_Practices ---- -

{{draft}}

- -

Este artigo proporciona um compilado das melhores práticas a serem usadas enquanto estiver desenvolvendo websites e aplicações que usem Notificações push para engajamento de usuários.

- -
-

“Se feito de uma maneira correta, as notificações ajudam os usuarios, se não, so irritam.” — Conversa entre dois desenvolvedores a respeito da etica das notificações push.

-
- -

Visão Geral do web push notifications

- -

Notificações Web Push (criadas usando uma combinação das APIs de Notificações, Push e Service Worker) são parte de um movimento crescente em que desenvolvedores e comerciantes estão usando para conseguir atenção para seus sites. Uma procura rápida pelo termo "web push notifications", irá resultar em vários artigos, em que especialistas em marketing que acreditam que deve-se usar a API de Push para recapturar a atenção de pessoas que saíram de seu site para que possam terminar o que estavam fazendo, por exemplo, uma compra, ou então enviar as últimas notícias e até recomendação de produtos

- -

O Lado obscuro

- -

Essa novidade oferece uma oportunidade nova e inexplorada para sites empresariais chegarem aos seus consumidores finais. Seu usuário trocou de aba para responder um email? Consiga-os de volta com uma oferta que expira em um tempo limitado ou oferecendo frete grátis, o qual ele não vai poder ignorar

- -

Mas sério, qual o melhor uso das notificações push? Ou é apenas uma nova interação dos bons e velhos pop-ups?

- -
-

“O envio de notificações push não corre o risco de acabar na pasta de spam. Nem pode ser bloqueado por bloqueadores de anúncios. Ele aparece na sua área de trabalho, mesmo quando o site está fechado. No celular, ele aparece na barra de notificações, assim como as notificações por push do aplicativo, mesmo quando o navegador não está em execução.” — um site de marketing anonimo

-
- -

Bons usos das notificações

- -

Mas há também um lado bom no que se diz respeito as notificações por push. Digamos que você e sua equipe usem normalmente um programa de bate-papo para se comunicar, mas hoje você está feliz e saltitante trabalhando e surge um problema. Digamos que seu gerente tenha encontrado um problema nas aprovações e queira receber seu feedback sobre algo antes que ela prossiga.

- -

Neste documento, falaremos sobre o uso correto das notificações por push da web. Às vezes, eles podem eliminar a frustração e o aborrecimento e, às vezes, causá-los. Cabe a você, como desenvolvedor, fazer recomendações (e decisões) sábias sobre o uso de notificações por push.

- -

O que se espera alcançar com as notificações push?

- -

Como tudo, com grande poder vem uma grande responsabilidade. Toda notificação push devem ser úteis e sensíveis ao tempo, o usuário sempre deve fornecer a permissão antes de recebe-la primeiro e deve-se oferecer uma maneira fácil de optar por não receber mais no futuro.

- -

Temos que responder algumas perguntas basicas para verificar se as notificações são necessarias:

- - - -

Além da questão de saber se uma notificação por push é necessária, existem muitas variedades de notificações por push, variando de casual e efêmera a persistente e exigente.

- -

Aconselhamos que você use as notificações que exigem uma interação de forma conciente e com moderação, pois estas podem irritar seu usuario e afasta-lo. Suas notificações devem ser acolhedoras, não hostis.

- -

Gerando confiança

- -

Alguns estudos mostraram que até 60% das notificações por push não chegam ao usuário final. Permitir que seu usuario receba notificações por push em tempo real exige confiança, por parte do aplicativo. Você pode criar confiança ao ter um site bem projetado que forneça um bom conteúdo e que mostre respeito pelo usuário alem de um valor claro para que o usuario aceite as notificações push.

- -

Mitigações dos navegadores

- -

Por causa dos abusos da utilização das notificações por push no passado, os desenvolvedores de navegadores começaram a implementar estratégias para ajudar a mitigar esse problema. Por exemplo, o Safari 12.1 agora exige - e outros navegadores já o fazem ou estão planejando[1] fazer—que o usuário interaja com a página de alguma forma antes que ela possa solicitar permissão para executar notificações por push, assim como já acontece com os popups. Isso pelo menos impede que o usuário receba espontaneamente essa pergunta em páginas da Web que apenas olharam de uma só vez, raramente ou nunca mais.

- -

[1] No caso do Firefox, veja {{bug(1524619)}}, podemos observar que Firefox 68 implementa isso, desabilitado por padrão, usando a preferência dom.webnotifications.requireuserinteraction.

- -

Veja também

- - diff --git a/files/pt-br/web/api/api_push/index.html b/files/pt-br/web/api/api_push/index.html deleted file mode 100644 index 563b711cd8..0000000000 --- a/files/pt-br/web/api/api_push/index.html +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: API Push -slug: Web/API/API_Push -tags: - - API - - Experimental - - Notificações - - Push - - Referencia - - Service Workers -translation_of: Web/API/Push_API ---- -
{{DefaultAPISidebar("Push API")}}{{SeeCompatTable}}
- -

A API Push torna possível que aplicações web recebam mensagens enviadas a elas de um servidor, indepententemente de aplicação estar ou não em primeiro plano, ou até mesmo carregada, em um agente de usuário. Isso permite que desenvolvedores entreguem notificações e atualizações assíncronas a usuários que optarem por elas, resultando num melhor engajamento com conteúdo novo oportuno.

- -
-

Nota: Esta documentação cobre a especificação W3C da API Push; se você procura pela documentação do sistema de notificação proprietária do mecanismo push, veja Simple Push.

-
- -

Conceitos e uso de Push

- -

Para uma aplicação receber mensagens push, ela precisa ter um service worker ativo. Quando o service worker está ativo, ele pode se inscrever para utilizar notificações push {{domxref("PushManager.subscribe()")}}.

- -

O resultado de {{domxref("PushSubscription")}} inclui toda informação que a aplicação precisa para receber uma mensagem push: um endpoint e a chave encriptada necessária para o envio de dados.

- -

O service worker será iniciado conforme o necessário para lidar com as mensagens recebidas, que são entregues ao manipulador de evento {{domxref("ServiceWorkerGlobalScope.onpush")}} . Isto permite que a aplicação reaja a cada mensagem recebida, por exemplo para exibir a notificação ao usuário (usando {{domxref("ServiceWorkerRegistration.showNotification()")}}.)

- -

Cada assinatura é única para um service worker.  O endpoint para a assinatura é uma capability URL única: o conhecimento do endpoint é tudo que é necessário para enviar uma mensagem para sua aplicação. A URL do endpoint precisa ser mantida em segredo, ou outras aplicações estranhas poderão enviar mensagens push para a sua aplicação.

- -

A ativação de um service worker para entregar mensagens push pode resultar em um aumento de uso de recursos, particularmente de bateria. Diferentes navegadores tem diferentes formas para lidar com isso — atualmente não existe uma forma padrão. Firefox permite um número limitado (cota) de mensagens push para serem enviadas para uma aplicação, embora as mensagens Push que gerem notificações são isentas deste limite.  O limite é atualizado a cada site visitado. Numa comparação, Chrome não aplica nenhum limite, mas requer que cada mensagem push exiba uma notificação.

- -
-

Nota: A partir do Gecko 44, a cota permitida de mensagens push por aplicação não é incrementada quando uma nova notificação é disparada quando outra está visível, por um período de três segundos. Isso lida com casos em que várias notificações são recebidas ao mesmo tempo, mas nem todas estão visíveis.

-
- -
-

Nota: Chrome atualmente requer que você crie um projeto no Google Cloud Messaging para enviar mensagens push e use um número do projeto e chave da API para o envio de notificações push. Isto também requer um app manifest com alguns parâmetros especiais para usar o serviço. Essa restrição deverá ser removida no futuro.

-
- -

Interfaces

- -
-
{{domxref("PushEvent")}}
-
Representa uma ação push enviada para o global scope de um {{domxref("ServiceWorker")}}. Ele contém informações enviadas de uma aplicação para um {{domxref("PushSubscription")}}.
-
{{domxref("PushManager")}}
-
Fornece uma forma de receber notificações de servidor third-party bem como solicitar URL para notificações push. Essa interface substitui a funcionalidade oferecida que está obsoleta {{domxref("PushRegistrationManager")}} interface.
-
{{domxref("PushMessageData")}}
-
Fornece acesso aos dados push enviados por um servidor, e inclui métodos para manipular os dados recebidos.
-
{{domxref("PushSubscription")}}
-
Fornece a URL de assinatura do endpoint e permite o cancelamento da assinatura de um serviço push.
-
- -

Service worker additions

- -

As seguintes informações adicionais para a Service Worker API foram especificadas na Push API spec, para fornecer um ponto de entrada para usar mensagens Push, e para monitorar e responder os eventos de envio e assinatura.

- -
-
{{domxref("ServiceWorkerRegistration.pushManager")}} {{readonlyinline}}
-
Retorna uma referência para a interface {{domxref("PushManager")}} para administrar assinaturas push incluindo subscrever, obter uma assinatura ativa e acessar o status de permissão de envio. Este é o ponto de entrada para usar mensagens Push.
-
{{domxref("ServiceWorkerGlobalScope.onpush")}}
-
Um manipulador de eventos disparado sempre que um evento  {{Event("push")}} ocorre; isto é, sempre que uma mensagem do servidor de envio for recebida.
-
{{domxref("ServiceWorkerGlobalScope.onpushsubscriptionchange")}}
-
Um manipulador de eventos disparado sempre que um evento  {{Event("pushsubscriptionchange")}} ocorre; por exemplo, quando uma assinatura push está inválida, ou está prestes a ser invalidada (ex. quando um serviço push service define um tempo de expiração.)
-
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName("Push API")}}{{Spec2("Push API")}}Definição Inicial
- -

Compatibilidade em Browsers

- -
{{CompatibilityTable}}
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
FuncionalidadeChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico{{CompatChrome(42.0)}}{{CompatGeckoDesktop(44.0)}}[1]{{CompatNo}}[2]{{CompatUnknown}}{{CompatUnknown}}
{{domxref("PushEvent.data")}},
- {{domxref("PushMessageData")}}		{{CompatNo}}{{CompatGeckoDesktop(44.0)}}{{CompatNo}}{{CompatNo}}{{CompatNo}}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FuncionalidadeAndroidAndroid WebviewFirefox Mobile (Gecko)Firefox OSIE MobileOpera MobileSafari MobileChrome for Android
Suporte básico{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatUnknown}}[2]{{CompatUnknown}}{{CompatUnknown}}{{CompatChrome(42.0)}}
{{domxref("PushEvent.data")}},
- {{domxref("PushMessageData")}}		{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}
-
- -

[1] Atualmente disponível apenas nas versões desktop do Firefox; ainda, mensagens push são encaminhadas apenas quando o Firefox está em execução.

- -

[2] Ainda não implementado. Veja Microsoft Edge status information.

- -

Veja também

- - diff --git a/files/pt-br/web/api/api_web_audio/index.html b/files/pt-br/web/api/api_web_audio/index.html deleted file mode 100644 index 8f582eb524..0000000000 --- a/files/pt-br/web/api/api_web_audio/index.html +++ /dev/null @@ -1,480 +0,0 @@ ---- -title: API Web Áudio -slug: Web/API/API_Web_Audio -tags: - - Web Audio API - - api de áudio - - áudio api - - áudio web -translation_of: Web/API/Web_Audio_API ---- -
-

A API de áudio da web disponibiliza um poderoso e versátil sistema de controle de áudio para a Web, permitindo aos desenvolvedores escolher arquivos de áudio, adicionar efeitos a estes arquivos, criar reprodutores de áudio, aplicar spatial effects (como panning) e muito mais.

-
- -

Web audio: conceitos e uso

- -

A API de Web audio envolve manipulação de operações com áudio dentro de um contexto de áudio, e foi desenvolvida para permitir o roteamento modular. Operações básicas de áudio são feitas com audio nodes (nós de áudio), que são ligados para formar gráficos de roteamento de áudio. Várias fontes - com diferentes tipos de layout de canal - são suportados mesmo em um único contexto. Este design modular permite flexibilidade para criar funções de áudio complexas com efeitos dinâmicos.

- -

Audio nodes são ligados pelas suas entradas e saídas, formando uma cadeia que começa com uma ou mais fontes, passa por um ou mais nodes e então acaba em um destino (embora você não tenha que fornecer um destino, por exemplo, se você quiser apenas visualizar alguns dados de áudio). Um fluxo de trabalho simples, com Web áudio, seria algo parecido com isso:

- -
    -
  1. Crie um contexto de áudio
    2. -
  2. Dentro do contexto, crie fontes de áudio — como <audio>, oscilador, stream
    3. -
  3. Crie efeitos de áudio, como reverb, biquad filter, panner, compressor
    4. -
  4. Escolha o destino final de áudio, por exemplo os auto-falantes de seu sistema
    5. -
  5. Conecte as fontes de áudio com os efeitos, e os efeitos com o destino.
    6. -
- -

A simple box diagram with an outer box labeled Audio context, and three inner boxes labeled Sources, Effects and Destination. The three inner boxes have arrow between them pointing from left to right, indicating the flow of audio information.

- -

O sincronismo é controlado com alta precisão e baixa latência, permitindo aos desenvolvedores escrever códigos que respondam com precisão a eventos e capazes de gerar exemplos específicos, mesmo com uma alta taxa de amostragem. Dessa forma, aplicações como baterias eletrônicas e seqüenciadores estarão facilmente ao alcance dos desenvolvedores.

- -

A API de Web Audio também permite o controle de como o áudio será ordenado. Usando um sistema baseado em um modelo de source-listener, a API permite controlar os painéis de modelo para serem usados e tratados com atenuação de distância induzida ou doppler shift induzido por uma fonte em movimento (ou um ouvinte em movimento).

- -
-

Nota: Você pode ver mais detalhes sobre a teoria da API de Web Audio em nosso artigo Basic concepts behind Web Audio API.

-
- -

Web Audio: Interfaces da API

- -

A API de Web Audio possui um total de 28 interfaces e eventos associados, que nós dividimos e categorizamos em 9 funcionalidades.

- -

Definições gerais de grafos de áudio (audio graph)

- -

Definições gerais que moldam os grafos de áudio no uso da API de Web Audio.

- -
-
{{domxref("AudioContext")}}
-
A interface AudioContext representa um grafo de processamento de áudio construído a partir de módulos de áudio ligados entre si, cada um representado por um {{domxref("AudioNode")}}. Um contexto de áudio (audio context) controla a criação dosnós que ele contém e a execução do processamento de áudio, ou a decodificação. Como tudo acontece dentro de um contexto, você deve criar um AudioContext antes de fazer qualquer outra coisa.
-
{{domxref("AudioNode")}}
-
A interface AudioNode representa um módulo de processamento de áudio como uma fonte de áudio (por exemplo, um HTML {{HTMLElement("áudio")}} ou um elemento {{HTMLElement("vídeo")}}), destino de áudio, módulo de processamento intermediário (por exemplo, um filtro como {{domxref("BiquadFilterNode")}}, ou controle de volume, como {{domxref("GainNode")}}).
-
{{domxref("AudioParam")}}
-
A interface AudioParam representa um parâmetro relacionado ao áudio, como um parâmetro de um {{domxref("AudioNode")}}. Ele pode ser configurado com um valor específico ou uma mudança de valor, e pode ser programado para "acontecer" em um momento específico e seguindo um padrão específico.
-
{{event("ended_(Web_Audio)", "ended")}} (event)
-
O evento ended é disparado quando a reprodução parou porque o fim da mídia foi atingido.
-
- -

Definindo fontes de áudio

- -

Interfaces que definem fontes de áudio para uso na API de Web Audio.

- -
-
{{domxref("OscillatorNode")}}
-
A interface OscillatorNode representa uma onda senoidal. Esta interface é um módulo de processamento de áudio que gera uma onda senoidal com determinada frequência.
-
{{domxref("AudioBuffer")}}
-
A interface AudioBuffer representa uma pequena porção de áudio armazenada na memória, criada a partir de um arquivo de áudio usando o método {{ domxref("AudioContext.decodeAudioData()") }}, ou criado com os dados brutos usando o método {{ domxref("AudioContext.createBuffer()") }}. Uma vez decodificado neste formato o áudio pode ser colocada em um {{ domxref("AudioBufferSourceNode") }}.
-
{{domxref("AudioBufferSourceNode")}}
-
A interface AudioBufferSourceNode representa uma fonte de áudio que consiste em dados de áudio na memória, armazenados em um {{domxref ("AudioBuffer")}}. É um {{domxref ("AudioNode")}} que atua como uma fonte de áudio.
-
{{domxref("MediaElementAudioSourceNode")}}
-
A interface MediaElementAudioSourceNode  representa uma fonte de audio consiste de um HTML5 {{ htmlelement("audio") }} ou {{ htmlelement("video") }} elemento. É uma {{domxref("AudioNode")}} que atua como uma fonte de áudio.
-
{{domxref("MediaStreamAudioSourceNode")}}
-
The MediaStreamAudioSourceNode interface represents an audio source consisting of a WebRTC {{domxref("MediaStream")}} (such as a webcam or microphone.) It is an {{domxref("AudioNode")}} that acts as an audio source.
-
- -

Definindo filtros de efeitos de áudio

- -

Interfaces para definição de efeitos que você deseja aplicar em suas fontes de áudio.

- -
-
{{domxref("BiquadFilterNode")}}
-
The BiquadFilterNode interface represents a simple low-order filter. It is an {{domxref("AudioNode")}} that can represent different kinds of filters, tone control devices or graphic equalizers. A BiquadFilterNode always has exactly one input and one output.
-
{{domxref("ConvolverNode")}}
-
The ConvolverNode interface is an {{domxref("AudioNode")}} that performs a Linear Convolution on a given AudioBuffer, often used to achieve a reverb effect.
-
{{domxref("DelayNode")}}
-
The DelayNode interface represents a delay-line; an {{domxref("AudioNode")}} audio-processing module that causes a delay between the arrival of an input data and its propagation to the output.
-
{{domxref("DynamicsCompressorNode")}}
-
The DynamicsCompressorNode interface provides a compression effect, which lowers the volume of the loudest parts of the signal in order to help prevent clipping and distortion that can occur when multiple sounds are played and multiplexed together at once.
-
{{domxref("GainNode")}}
-
The GainNode interface represents a change in volume. It is an {{domxref("AudioNode")}} audio-processing module that causes a given gain to be applied to the input data before its propagation to the output.
-
{{domxref("WaveShaperNode")}}
-
The WaveShaperNode interface represents a non-linear distorter. It is an {{domxref("AudioNode")}} that use a curve to apply a waveshaping distortion to the signal. Beside obvious distortion effects, it is often used to add a warm feeling to the signal.
-
{{domxref("PeriodicWave")}}
-
Used to define a periodic waveform that can be used to shape the output of an {{ domxref("OscillatorNode") }}.
-
- -

Definindo destinos de áudio

- -

Uma vez que você tenha feito o processamento do seu áudio, estas interfaces definirão aonde será a saída do áudio.

- -
-
{{domxref("AudioDestinationNode")}}
-
The AudioDestinationNode interface represents the end destination of an audio source in a given context — usually the speakers of your device.
-
{{domxref("MediaStreamAudioDestinationNode")}}
-
The MediaElementAudioSourceNode interface represents an audio destination consisting of a WebRTC {{domxref("MediaStream")}} with a single AudioMediaStreamTrack, which can be used in a similar way to a MediaStream obtained from {{ domxref("Navigator.getUserMedia") }}. It is an {{domxref("AudioNode")}} that acts as an audio destination.
-
- -

Análise dos dados e visualização

- -

Se você deseja extrair tempo, frequencia e outras informações do seu áudio, o AnalyserNode é o que você necessita.

- -
-
{{domxref("AnalyserNode")}}
-
The AnalyserNode interface represents a node able to provide real-time frequency and time-domain analysis information, for the purposes of data analysis and visualization.
-
- -

Dividindo e mesclando canais de áudio

- -

Para dividir e mesclar canais de áudio, você utilizará essas interfaces.

- -
-
{{domxref("ChannelSplitterNode")}}
-
The ChannelSplitterNode interface separates the different channels of an audio source out into a set of mono outputs.
-
{{domxref("ChannelMergerNode")}}
-
The ChannelMergerNode interface reunites different mono inputs into a single outputs. Each input will be used to fill a channel of the output.
-
- -

Audio spatialization

- -

These interfaces allow you to add audio spatialization panning effects to your audio sources.

- -
-
{{domxref("AudioListener")}}
-
The AudioListener interface represents the position and orientation of the unique person listening to the audio scene used in audio spatialization.
-
{{domxref("PannerNode")}}
-
The PannerNode interface represents the behavior of a signal in space. It is an {{domxref("AudioNode")}} audio-processing module describing its position with right-hand Cartesian coordinates, its movement using a velocity vector and its directionality using a directionality cone.
-
- -

Processamento de áudio por JavaScript

- -

Se você quiser usar um script externo para processar sua fonte de áudio, Node e eventos abaixo tornarão isto possível.

- -
-
{{domxref("ScriptProcessorNode")}}
-
The ScriptProcessorNode interface allows the generation, processing, or analyzing of audio using JavaScript. It is an {{domxref("AudioNode")}} audio-processing module that is linked to two buffers, one containing the current input, one containing the output. An event, implementing the {{domxref("AudioProcessingEvent")}} interface, is sent to the object each time the input buffer contains new data, and the event handler terminates when it has filled the output buffer with data.
-
{{event("audioprocess")}} (event)
-
The audioprocess event is fired when an input buffer of a Web Audio API {{domxref("ScriptProcessorNode")}} is ready to be processed.
-
{{domxref("AudioProcessingEvent")}}
-
The Web Audio API AudioProcessingEvent represents events that occur when a {{domxref("ScriptProcessorNode")}} input buffer is ready to be processed.
-
- -

Áudio offline

- -

Manipular áudio offline é possível com estas interfaces.

- -
-
{{domxref("OfflineAudioContext")}}
-
The OfflineAudioContext interface is an {{domxref("AudioContext")}} interface representing an audio-processing graph built from linked together {{domxref("AudioNode")}}s. In contrast with a standard AudioContext, an OfflineAudioContext doesn't really render the audio but rather generates it, as fast as it can, in a buffer.
-
{{event("complete")}} (event)
-
The complete event is fired when the rendering of an {{domxref("OfflineAudioContext")}} is terminated.
-
{{domxref("OfflineAudioCompletionEvent")}}
-
The OfflineAudioCompletionEvent represents events that occur when the processing of an {{domxref("OfflineAudioContext")}} is terminated. The {{event("complete")}} event implements this interface.
-
- -

Interfaces obsoletas

- -

As interfaces a seguir foram definidas em versões antigas das especificações da API de Web Audio, mas agora elas estão obsoletas e serão substituidas por outras interfaces.

- -
-
{{domxref("JavaScriptNode")}}
-
Used for direct audio processing via JavaScript. This interface is obsolete, and has been replaced by {{domxref("ScriptProcessorNode")}}.
-
{{domxref("WaveTableNode")}}
-
Used to define a periodic waveform. This interface is obsolete, and has been replaced by {{domxref("PeriodicWave")}}.
-
- -

Exemplo

- -

Este exemplo mostra uma grande variedade de funções da API de Web Audio que podem ser utilizadas. Você pode ver este código em ação na demo Voice-change-o-matic (também verificar o código-fonte completo no Github) - esta é uma demonstração de um modificador de voz de brinquedo experimental; aconselhamos manter seus alto-falantes baixo ao utilizá-lo, pelo menos para começar!

- -

As linhas API de Web Audio estão destacadas; se você quiser encontrar mais informações sobre os diferentes métodos, faça uma busca através das páginas de referência.

- -
var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); // define audio context
-// Webkit/blink browsers need prefix, Safari won't work without window.
-
-var voiceSelect = document.getElementById("voice"); // select box for selecting voice effect options
-var visualSelect = document.getElementById("visual"); // select box for selecting audio visualization options
-var mute = document.querySelector('.mute'); // mute button
-var drawVisual; // requestAnimationFrame
-
-var analyser = audioCtx.createAnalyser();
-var distortion = audioCtx.createWaveShaper();
-var gainNode = audioCtx.createGain();
-var biquadFilter = audioCtx.createBiquadFilter();
-
-function makeDistortionCurve(amount) { // function to make curve shape for distortion/wave shaper node to use
-  var k = typeof amount === 'number' ? amount : 50,
-    n_samples = 44100,
-    curve = new Float32Array(n_samples),
-    deg = Math.PI / 180,
-    i = 0,
-    x;
-  for ( ; i < n_samples; ++i ) {
-    x = i * 2 / n_samples - 1;
-    curve[i] = ( 3 + k ) * x * 20 * deg / ( Math.PI + k * Math.abs(x) );
-  }
-  return curve;
-};
-
-navigator.getUserMedia (
-  // constraints - only audio needed for this app
-  {
-    audio: true
-  },
-
-  // Success callback
-  function(stream) {
-    source = audioCtx.createMediaStreamSource(stream);
-    source.connect(analyser);
-    analyser.connect(distortion);
-    distortion.connect(biquadFilter);
-    biquadFilter.connect(gainNode);
-    gainNode.connect(audioCtx.destination); // connecting the different audio graph nodes together
-
-    visualize(stream);
-    voiceChange();
-
-  },
-
-  // Error callback
-  function(err) {
-    console.log('The following gUM error occured: ' + err);
-  }
-);
-
-function visualize(stream) {
-  WIDTH = canvas.width;
-  HEIGHT = canvas.height;
-
-  var visualSetting = visualSelect.value;
-  console.log(visualSetting);
-
-  if(visualSetting == "sinewave") {
-    analyser.fftSize = 2048;
-    var bufferLength = analyser.frequencyBinCount; // half the FFT value
-    var dataArray = new Uint8Array(bufferLength); // create an array to store the data
-
-    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);
-
-    function draw() {
-
-      drawVisual = requestAnimationFrame(draw);
-
-      analyser.getByteTimeDomainData(dataArray); // get waveform data and put it into the array created above
-
-      canvasCtx.fillStyle = 'rgb(200, 200, 200)'; // draw wave with canvas
-      canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);
-
-      canvasCtx.lineWidth = 2;
-      canvasCtx.strokeStyle = 'rgb(0, 0, 0)';
-
-      canvasCtx.beginPath();
-
-      var sliceWidth = WIDTH * 1.0 / bufferLength;
-      var x = 0;
-
-      for(var i = 0; i < bufferLength; i++) {
-
-        var v = dataArray[i] / 128.0;
-        var y = v * HEIGHT/2;
-
-        if(i === 0) {
-          canvasCtx.moveTo(x, y);
-        } else {
-          canvasCtx.lineTo(x, y);
-        }
-
-        x += sliceWidth;
-      }
-
-      canvasCtx.lineTo(canvas.width, canvas.height/2);
-      canvasCtx.stroke();
-    };
-
-    draw();
-
-  } else if(visualSetting == "off") {
-    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);
-    canvasCtx.fillStyle = "red";
-    canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);
-  }
-
-}
-
-function voiceChange() {
-  distortion.curve = new Float32Array;
-  biquadFilter.gain.value = 0; // reset the effects each time the voiceChange function is run
-
-  var voiceSetting = voiceSelect.value;
-  console.log(voiceSetting);
-
-  if(voiceSetting == "distortion") {
-    distortion.curve = makeDistortionCurve(400); // apply distortion to sound using waveshaper node
-  } else if(voiceSetting == "biquad") {
-    biquadFilter.type = "lowshelf";
-    biquadFilter.frequency.value = 1000;
-    biquadFilter.gain.value = 25; // apply lowshelf filter to sounds using biquad
-  } else if(voiceSetting == "off") {
-    console.log("Voice settings turned off"); // do nothing, as off option was chosen
-  }
-
-}
-
-// event listeners to change visualize and voice settings
-
-visualSelect.onchange = function() {
-  window.cancelAnimationFrame(drawVisual);
-  visualize(stream);
-}
-
-voiceSelect.onchange = function() {
-  voiceChange();
-}
-
-mute.onclick = voiceMute;
-
-function voiceMute() { // toggle to mute and unmute sound
-  if(mute.id == "") {
-    gainNode.gain.value = 0; // gain set to 0 to mute sound
-    mute.id = "activated";
-    mute.innerHTML = "Unmute";
-  } else {
-    gainNode.gain.value = 1; // gain set to 1 to unmute sound
-    mute.id = "";
-    mute.innerHTML = "Mute";
-  }
-}
-
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('Web Audio API')}}{{Spec2('Web Audio API')}} 
- -

Compatibilidade de navegadores

- -
{{CompatibilityTable}}
- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support14 {{property_prefix("webkit")}}23{{CompatNo}}15 {{property_prefix("webkit")}}
- 22 (unprefixed)		6 {{property_prefix("webkit")}}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - -
FeatureAndroidChromeFirefox Mobile (Gecko)Firefox OSIE PhoneOpera MobileSafari Mobile
Basic support{{CompatNo}}28 {{property_prefix("webkit")}}251.2{{CompatNo}}{{CompatNo}}6 {{property_prefix("webkit")}}
-
- -

 

- -

Veja também

- - - - diff --git a/files/pt-br/web/api/api_web_audio/sintetizador_simples/index.html b/files/pt-br/web/api/api_web_audio/sintetizador_simples/index.html deleted file mode 100644 index b0fdf2a0c4..0000000000 --- a/files/pt-br/web/api/api_web_audio/sintetizador_simples/index.html +++ /dev/null @@ -1,579 +0,0 @@ ---- -title: 'Tutorial e exemplo: Teclado de Sintetizador Simples' -slug: Web/API/API_Web_Audio/Sintetizador_simples -tags: - - Audio - - Exemplo - - Guía - - Media - - Oscilador - - Piano - - Sintetizador - - Tutorial - - Web Audio API -translation_of: Web/API/Web_Audio_API/Simple_synth ---- -
{{DefaultAPISidebar("Web Audio API")}}
- -

Este artigo apresenta o código e uma demonstração funcional de um teclado que você pode tocar usando seu mouse. O teclado lhe permite alternar entre formas de onda padrões e customizadas. Esse exemplo utiliza das seguintes interfaces de Web API: {{domxref("AudioContext")}}, {{domxref("OscillatorNode")}}, {{domxref("PeriodicWave")}}, e {{domxref("GainNode")}}.

- -

Já que {{domxref("OscillatorNode")}} é baseado no {{domxref("AudioScheduledSourceNode")}}, isso até certo ponto também é um exemplo pra isto.

- -

O Teclado Visual

- -

HTML

- -

Existem três componentes primários para o display do nosso teclado virtual. O primeito do qual é o teclado musical em si. Nós extraimos em um par de elementos {{HTMLElement("div")}} aninhados para permitir a rolagem horizontal caso as teclas não encaixem na tela.

- -

O Teclado

- -

Primeiro, criamos o espaço no qual construiremos o teclado. Estaremos construindo o teclado programaticamente, considerando que ao fazer desse jeito teremos a flexibilidade de configurar cada tecla conforme determinamos as informações apropriadas para tecla correspondente. No nosso caso, pegamos a frequência de cada tecla através de uma tabela, mas poderia ser calculado de forma algoritmica também.

- -
<div class="container">
-  <div class="keyboard"></div>
-</div>
-
- -

O {{HTMLElement("div")}} nomeado de "container" é a barra de rolagem que permite o teclado ser rolado horizontalmente se for largo demais para o espaço disponivel. As teclas em si serão inseridas no bloco de classe "keyboard".

- -

A barra de opções

- -

Abaixo do teclado, colocaremos alguns controles para configurar o camada. Por enquanto, teremos dois controles: Um para controlar o volume e outro para selecionar a forma de onda periodica usada ao gerar as notas.

- -
O controle de volume
- -

Primeiro criamos o <div> para conter a barra de opções, para ser personalizado conforme preciso. Então estabelecemos uma caixa que será apresentada no lado esquerdo da barra e colocar um rotulo e um elemento {{HTMLElement("input")}} do tipo "range". O elemento range será tipicamente apresentado como o controle da barra de rolagem ; configuramos ele para permitir qualquer valor entre 0.0 e 1.0 em cada posição.

- -
<div class="settingsBar">
-  <div class="left">
-    <span>Volume: </span>
-    <input type="range" min="0.0" max="1.0" step="0.01"
-        value="0.5" list="volumes" name="volume">
-    <datalist id="volumes">
-      <option value="0.0" label="Mute">
-      <option value="1.0" label="100%">
-    </datalist>
-  </div>
-
- -

Especificamos um valor padrão de 0.5, e provemos um elemento {{HTMLElement("datalist")}} no qual é conectado ao range usando o atributo {{htmlattrxref("name")}} para achar uma lista de opções cujo ID encaixa; nesse caso, o conjunto de informações é nomeado de "volume". isso nos permite prover um conjunto de valores comuns e strings especiais que o browser pode de forma opcional escolher mostrar de alguma maneira; e então atribuimos nomes aos valores 0.0 ("Mute") e 1.0 ("100%").

- -
A seleção de forma de onda
- -

E no lado da barra de configurações, colocamos um rótulo e um elemento {{HTMLElement("select")}} nomeado de "waveform" cujas opções correspondem as formas de onda disponiveis.

- -
  <div class="right">
-    <span>Current waveform: </span>
-    <select name="waveform">
-      <option value="sine">Sine</option>
-      <option value="square" selected>Square</option>
-      <option value="sawtooth">Sawtooth</option>
-      <option value="triangle">Triangle</option>
-      <option value="custom">Custom</option>
-    </select>
-  </div>
-</div>
- - - -

JavaScript

- -

O código em JavaScript começa inicializando algumas váriaveis.

- -
let audioContext = new (window.AudioContext || window.webkitAudioContext)();
-let oscList = [];
-let masterGainNode = null;
-
- -
    -
  1. audioContext é colocado para referenciar o objeto global {{domxref("AudioContext")}} (ou webkitAudioContext se  necessário).
    2. -
  2. oscillators está colocado para conter uma lista de todos os osciladores atualmente tocando. Ele começa nulo, afinal não há nenhum oscilador tocando ainda.
    3. -
  3. masterGainNode é colocado como nulo; durante o processo de setup, ele será configurado para contar um {{domxref("GainNode")}} no quall todos os osciladores irão se conectar para permitir o volume geral a ser controlado por apenas uma barra de rolagem.
    4. -
- -
let keyboard = document.querySelector(".keyboard");
-let wavePicker = document.querySelector("select[name='waveform']");
-let volumeControl = document.querySelector("input[name='volume']");
-
- -

Referencias aos elementos que precisaremos acessar são obtidas através dp:

- - - -
let noteFreq = null;
-let customWaveform = null;
-let sineTerms = null;
-let cosineTerms = null;
-
- -

Enfim, variaveis globais que serão usadas quando as formas de onda são criadas:

- - - -

Criando a tabela de notas

- -

A função createNoteTable() constrói a matriz noteFreq para conter uma matriz de objetos representando cada oitava. Cada oitava, possui uma propriedade para cada nota nessa oitava; O nome dessa propriedade é o nome da nota (utilizando da notação em inglês, como "C" para representar "dó"), e o valor é a frequência, em Hertz, daquela nota.

- -
function createNoteTable() {
-  let noteFreq = [];
-  for (let i=0; i< 9; i++) {
-    noteFreq[i] = [];
-  }
-
-  noteFreq[0]["A"] = 27.500000000000000;
-  noteFreq[0]["A#"] = 29.135235094880619;
-  noteFreq[0]["B"] = 30.867706328507756;
-
-  noteFreq[1]["C"] = 32.703195662574829;
-  noteFreq[1]["C#"] = 34.647828872109012;
-  noteFreq[1]["D"] = 36.708095989675945;
-  noteFreq[1]["D#"] = 38.890872965260113;
-  noteFreq[1]["E"] = 41.203444614108741;
-  noteFreq[1]["F"] = 43.653528929125485;
-  noteFreq[1]["F#"] = 46.249302838954299;
-  noteFreq[1]["G"] = 48.999429497718661;
-  noteFreq[1]["G#"] = 51.913087197493142;
-  noteFreq[1]["A"] = 55.000000000000000;
-  noteFreq[1]["A#"] = 58.270470189761239;
-  noteFreq[1]["B"] = 61.735412657015513;
-
- -

... várias oitavas não mostradas para manter breve ...

- - - -
  noteFreq[7]["C"] = 2093.004522404789077;
-  noteFreq[7]["C#"] = 2217.461047814976769;
-  noteFreq[7]["D"] = 2349.318143339260482;
-  noteFreq[7]["D#"] = 2489.015869776647285;
-  noteFreq[7]["E"] = 2637.020455302959437;
-  noteFreq[7]["F"] = 2793.825851464031075;
-  noteFreq[7]["F#"] = 2959.955381693075191;
-  noteFreq[7]["G"] = 3135.963487853994352;
-  noteFreq[7]["G#"] = 3322.437580639561108;
-  noteFreq[7]["A"] = 3520.000000000000000;
-  noteFreq[7]["A#"] = 3729.310092144719331;
-  noteFreq[7]["B"] = 3951.066410048992894;
-
-  noteFreq[8]["C"] = 4186.009044809578154;
-  return noteFreq;
-}
-
- -

O resultado é uma matriz, noteFreq, com um objeto para cada oitava. Cada objeto de oitava tem propriedades nomeadas nela onde a propriedade é o nome da nota com a notação em inglês (Como "C" para representar "dó") e o valor da propriedade é a frequência da nota em Hertz.. o objeto resultando se parece com isso:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OctaveNotes
0"A" ⇒ 27.5"A#" ⇒ 29.14"B" ⇒ 30.87
1"C" ⇒ 32.70"C#" ⇒ 34.65"D" ⇒ 36.71"D#" ⇒ 38.89"E" ⇒ 41.20"F" ⇒ 43.65"F#" ⇒ 46.25"G" ⇒ 49"G#" ⇒ 51.9"A" ⇒ 55"A#" ⇒ 58.27"B" ⇒ 61.74
2. . .
- -

Com esta tabela no lugar, podemos descobrir a frequência para uma dada nota em uma oitava particular relativamente fácil. Se queremos a frequência pra nota G# na primeira oitava, nós simplesmente usamos  noteFreq[1]["G#"] e conseguimos o valor 51.9 como resultado.

- -
-

Os valores na tabela de exemplo acima foram arredondados para duas casas decimais.

-
- - - -

Construindo o teclado

- -

A função setup() é responsavel por construir o teclado e preparar a aplicação para tocar a música.

- -
function setup() {
-  noteFreq = createNoteTable();
-
-  volumeControl.addEventListener("change", changeVolume, false);
-
-  masterGainNode = audioContext.createGain();
-  masterGainNode.connect(audioContext.destination);
-  masterGainNode.gain.value = volumeControl.value;
-
-  // Create the keys; skip any that are sharp or flat; for
-  // our purposes we don't need them. Each octave is inserted
-  // into a <div> of class "octave".
-
-  noteFreq.forEach(function(keys, idx) {
-    let keyList = Object.entries(keys);
-    let octaveElem = document.createElement("div");
-    octaveElem.className = "octave";
-
-    keyList.forEach(function(key) {
-      if (key[0].length == 1) {
-        octaveElem.appendChild(createKey(key[0], idx, key[1]));
-      }
-    });
-
-    keyboard.appendChild(octaveElem);
-  });
-
-  document.querySelector("div[data-note='B'][data-octave='5']").scrollIntoView(false);
-
-  sineTerms = new Float32Array([0, 0, 1, 0, 1]);
-  cosineTerms = new Float32Array(sineTerms.length);
-  customWaveform = audioContext.createPeriodicWave(cosineTerms, sineTerms);
-
-  for (i=0; i<9; i++) {
-      oscList[i] = {};
-  }
-}
-
-setup();
- -
    -
  1. A tabela que mapeia o nome e oitavas das notas para suas respectivas frequências é criado ao chamar createNoteTable().
    2. -
  2. Um manipulador de eventos é estabelecido ao chamar nosso velho amigo {{domxref("EventTarget.addEventListener", "addEventListener()")}} para cuidar dos eventos do {{event("change")}} no controle de ganho geral. Isso vai simplesmente atualizar o módulo de ganho de volume para o novo valor.
    3. -
  3. Em seguida, nós replicamos cada oitava na tabela de frequências das notas. Para cada oitava, usamos {{jsxref("Object.entries()")}} para conseguir uma lista de notas daquela oitava.
    4. -
  4. Criar um {{HTMLElement("div")}} para contar as notas daquela oitava (para ter um pouco de espaço entre as oitavas), e mudar o nome de classe para "octave".
    5. -
  5. Para cada tecla na oitava, checamos para ver se o nome daquela nota há mais de um caractere. Nós pulamos essas, pois estamos deixando notas sustenidas de fora deste exemplo. Do contrário, chamamos createKey(), especificando uma string, oitava, e frequência. O elemento retornado é anexado na elemento da oitava criada no passo 4.
    6. -
  6. Quando o elemento da oitava é construido, é então anexada ao teclado.
    7. -
  7. Uma vez que o teclado foi construido, nós rolamos para nota "B" na quinta oitava; isso tem o efeito de garantir que o C médio é visivel junto das notas ao redor.
    8. -
  8. Então uma forma de onda customizada é construida usando {{domxref("AudioContext.createPeriodicWave()")}}. Essa forma de onda será usada toda vez que o usuário selecionar "Custom" da seleção de formas de onda.
    9. -
  9. Enfim, a lista de osciladores é iniciada para garantir que está pronta para receber informação identificando quais osciladores estão associados com que teclas.
    10. -
- -

Criando uma tecla

- -

A função createKey()  é chamada toda vez que queremos que uma tecla seja apresentada no nosso teclado virtual. Ela cria elementos da tecla e seu rótulo, adiciona informação dos atributos ao elemento para uso posterior, e coloca modificadores de eventos para os eventos que nos importam.

- -
function createKey(note, octave, freq) {
-  let keyElement = document.createElement("div");
-  let labelElement = document.createElement("div");
-
-  keyElement.className = "key";
-  keyElement.dataset["octave"] = octave;
-  keyElement.dataset["note"] = note;
-  keyElement.dataset["frequency"] = freq;
-
-  labelElement.innerHTML = note + "<sub>" + octave + "</sub>";
-  keyElement.appendChild(labelElement);
-
-  keyElement.addEventListener("mousedown", notePressed, false);
-  keyElement.addEventListener("mouseup", noteReleased, false);
-  keyElement.addEventListener("mouseover", notePressed, false);
-  keyElement.addEventListener("mouseleave", noteReleased, false);
-
-  return keyElement;
-}
-
- -

Após criar  os elementos representando as teclas e seus rótulos, nós configuramos o elemento das teclas ao configurar sua classe para "key" (Que estabelece a aparência). Então adicionamos atributos {{htmlattrxref("data-*")}}  que contém a string da oitava da nota (attribute data-octave), representando a nota a ser tocada (attribute data-note), e frequência (attribute data-frequency) em Hertz. Isso irá nos permitir facilmente pegar informação conforme necessário ao cuidar de eventos.

- -

Fazendo música

- -

Tocando um tom

- -

O trabalho da função playTone() é tocar um tom em uma dada frequência. Isso será usado pelo modificador para eventos acionados nas teclas do teclado, para que toquem as notas apropriadas.

- -
function playTone(freq) {
-  let osc = audioContext.createOscillator();
-  osc.connect(masterGainNode);
-
-  let type = wavePicker.options[wavePicker.selectedIndex].value;
-
-  if (type == "custom") {
-    osc.setPeriodicWave(customWaveform);
-  } else {
-    osc.type = type;
-  }
-
-  osc.frequency.value = freq;
-  osc.start();
-
-  return osc;
-}
-
- -

O playTone() começa criando um novo {{domxref("OscillatorNode")}} ao chamar o método {{domxref("AudioContext.createOscillator()")}}. Então conectamos ele para o módulo de ganha geral ao chamar o novo método de osciladores {{domxref("OscillatorNode.connect()")}} method;, Que determina ao oscilador onde ele irá mandar seu output. Ao fazer isso, mudar o valor do ganho do módulo de ganho geral irá mudar o volume de todos os toms gerados.

- -

Então conseguimos o tipo de forma de onda para usar ao checar o valor do controle de seleção de formas de onda na barra de opções. Se o usuário estiver colocado como "custom", chamamos {{domxref("OscillatorNode.setPeriodicWave()")}} para configurar os osciladores para usar nossa forma de onda customizada. Fazer isso automáticamente coloca o {{domxref("OscillatorNode.type", "type")}} do oscilador como custom. Se qualquer outro tipo de forma de onda é selecionado na seleção de formas de ondas, nós simplesmente colocamos os tipos de osciladores no valor da seleção, esse valor será um entre sine, square, triangle, e sawtooth.

- -

A frequência do oscilador é colocada no valor especificado no paramêtro freq ao colocar o valor dos objetos {{domxref("Oscillator.frequency")}} {{domxref("AudioParam")}} . Então, enfim, o oscilador é iniciado e começa a produzir sons ao chamar o método {{domxref("AudioScheduledSourceNode.start()")}} .

- -

Tocando um tom

- -

Quando o evento {{event("mousedown")}} ou {{domxref("mouseover")}} ocorre em uma tecla, queremos que toque a nota correspondente. A função notePressed() é usada como o modificador de eventos para esses eventos.

- -
function notePressed(event) {
-  if (event.buttons & 1) {
-    let dataset = event.target.dataset;
-
-    if (!dataset["pressed"]) {
-      let octave = +dataset["octave"];
-      oscList[octave][dataset["note"]] = playTone(dataset["frequency"]);
-      dataset["pressed"] = "yes";
-    }
-  }
-}
-
- -

Começamos checando se o botão esquerdo do mouse é pressionado, por dois motivos. Primeiro, queremos que apenas o botão esquerdo acione as notas. Segundo, e mais importante, estamos usando isso para cuidar do {{event("mouseover")}} para casos onde o usuário arrasta de tecla a tecla, e só queremos tocar uma nota se o mouse estiver pressionado quando entrar no elemento.

- -

Se o botão do mouse estiver de fato sendo pressionado, recebemos o atributo de tecla pressionada {{htmlattrxref("dataset")}} ; isso torna fácil o acesso das informações de atributo customizadas no elemento. Procuramos por um atributo data-pressed ; caso não haja um(o que indica que a nota não está tocando ainda), chamamos playTone() para começar a tocar a nota, passando no valor dos elementos do atributo data-frequency. O valor retornado do oscilador é guardado no oscList para refêrencia futura, e data-pressed é colocado como yes para indicar que a nota está tocando para que não iniciemos novamente na próxima vez que isso for chamado.

- -

Parando um tom

- -

A função noteReleased() é o modificador de eventos chamado quando o usuário solta o botão do mouse ou move o mouse para fora da tecla que ele está tocando.

- -
function noteReleased(event) {
-  let dataset = event.target.dataset;
-
-  if (dataset && dataset["pressed"]) {
-    let octave = +dataset["octave"];
-    oscList[octave][dataset["note"]].stop();
-    delete oscList[octave][dataset["note"]];
-    delete dataset["pressed"];
-  }
-}
-
- -

noteReleased() usa os atributos customizados data-octave and data-note  para procurar os osciladores das teclas, e então chama o método de oscilador {{domxref("AudioScheduledSourceNode.stop", "stop()")}} para parar de tocar a nota. Finalmente, a entrada oscList para nota é limpa e o atributo data-pressed é removido do elemento da tecla (como identificado pelo {{domxref("event.target")}}), para indicar que a nota não está tocando no momento.

- -

Mudando o volume geral

- -

A barra de rolagem do volume na barra de opções dá uma simples interface para mudar o valor do ganho no módulo de ganho geral, então mudando o volume de todas as notas sendo tocadas. O metódo changeVolume() é o modificador do evento {{event("change")}} na barra de rolagem.

- -
function changeVolume(event) {
-  masterGainNode.gain.value = volumeControl.value
-}
-
- -

Isso simplesmente coloca o valor do módulo de ganho geral gain {{domxref("AudioParam")}} para o novo valor na barra de rolagem.

- -

Resultado

- -

Coloque tudo junto, o resultado é um simples e funcional teclado virtual que funciona com o clique:

- -

{{ EmbedLiveSample('The_video_keyboard', 680, 200) }}

- -

Veja também

- - diff --git a/files/pt-br/web/api/audiocontext/currenttime/index.html b/files/pt-br/web/api/audiocontext/currenttime/index.html deleted file mode 100644 index 71f3c9c894..0000000000 --- a/files/pt-br/web/api/audiocontext/currenttime/index.html +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: AudioContext.currentTime -slug: Web/API/AudioContext/currentTime -tags: - - API - - AudioContext - - Propriedade - - Referencia - - Web Audio API - - currentTime -translation_of: Web/API/BaseAudioContext/currentTime ---- -

{{ APIRef("Web Audio API") }}

- -
-

The currentTime read-only property of the {{ domxref("AudioContext") }} interface returns a double representing an ever-increasing hardware timestamp in seconds that can be used for scheduling audio playback, visualizing timelines, etc. It starts at 0.

-
- -

Syntax

- -
var audioCtx = new AudioContext();
-console.log(audioCtx.currentTime);
-
- -

Exemplo:

- -
var AudioContext = window.AudioContext || window.webkitAudioContext;
-var audioCtx = new AudioContext();
-// Older webkit/blink browsers require a prefix
-
-...
-
-console.log(audioCtx.currentTime);
-
- -

Especificações:

- - - - - - - - - - - - - - -
Especificações:StatusComentario
{{SpecName('Web Audio API', '#widl-AudioContext-currentTime', 'currentTime')}}{{Spec2('Web Audio API')}} 
- -

Compatibilidade:

- -
{{CompatibilityTable}}
- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support{{CompatChrome(10.0)}}{{property_prefix("webkit")}}{{CompatGeckoDesktop(25.0)}} {{CompatNo}}15.0{{property_prefix("webkit")}}
- 22 (unprefixed)		6.0{{property_prefix("webkit")}}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)Firefox OSIE MobileOpera MobileSafari MobileChrome for Android
Basic support{{CompatUnknown}}26.01.2{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}33.0
- -

 

-
- -

Veja também:

- - diff --git a/files/pt-br/web/api/baseaudiocontext/currenttime/index.html b/files/pt-br/web/api/baseaudiocontext/currenttime/index.html new file mode 100644 index 0000000000..71f3c9c894 --- /dev/null +++ b/files/pt-br/web/api/baseaudiocontext/currenttime/index.html @@ -0,0 +1,114 @@ +--- +title: AudioContext.currentTime +slug: Web/API/AudioContext/currentTime +tags: + - API + - AudioContext + - Propriedade + - Referencia + - Web Audio API + - currentTime +translation_of: Web/API/BaseAudioContext/currentTime +--- +

{{ APIRef("Web Audio API") }}

+ +
+

The currentTime read-only property of the {{ domxref("AudioContext") }} interface returns a double representing an ever-increasing hardware timestamp in seconds that can be used for scheduling audio playback, visualizing timelines, etc. It starts at 0.

+
+ +

Syntax

+ +
var audioCtx = new AudioContext();
+console.log(audioCtx.currentTime);
+
+ +

Exemplo:

+ +
var AudioContext = window.AudioContext || window.webkitAudioContext;
+var audioCtx = new AudioContext();
+// Older webkit/blink browsers require a prefix
+
+...
+
+console.log(audioCtx.currentTime);
+
+ +

Especificações:

+ + + + + + + + + + + + + + +
Especificações:StatusComentario
{{SpecName('Web Audio API', '#widl-AudioContext-currentTime', 'currentTime')}}{{Spec2('Web Audio API')}} 
+ +

Compatibilidade:

+ +
{{CompatibilityTable}}
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support{{CompatChrome(10.0)}}{{property_prefix("webkit")}}{{CompatGeckoDesktop(25.0)}} {{CompatNo}}15.0{{property_prefix("webkit")}}
+ 22 (unprefixed)		6.0{{property_prefix("webkit")}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)Firefox OSIE MobileOpera MobileSafari MobileChrome for Android
Basic support{{CompatUnknown}}26.01.2{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}33.0
+ +

 

+
+ +

Veja também:

+ + diff --git a/files/pt-br/web/api/battery_status_api/index.html b/files/pt-br/web/api/battery_status_api/index.html new file mode 100644 index 0000000000..603750f72c --- /dev/null +++ b/files/pt-br/web/api/battery_status_api/index.html @@ -0,0 +1,58 @@ +--- +title: Battery Status API +slug: WebAPI/Battery_Status +tags: + - API + - Apps + - Batería + - Firefox OS + - Guia(2) + - Guía + - Mobile + - Obsoleto +translation_of: Web/API/Battery_Status_API +--- +
{{obsolete_header}}
+ +
{{DefaultAPISidebar("Battery API")}}
+ +

A API Battery Status, mais conhecida como Battery API, fornece informações sobre o nível de carga da bateria presente no sistema e permite que você seja notificado por eventos que são enviados quando os níveis sofrem alterações. Isto pode ser usado para ajustar a utilização de recursos do seu aplicativo, reduzindo a quantidade de energia drenada por ele quando a bateria estiver em nível baixo, ou ainda para salvar mudanças antes da bateria acabar, prevenindo a perda de dados.

+ +

A API Battery Status API estende {{domxref("Window.navigator")}} com uma propriedade {{domxref("Navigator.battery")}} que é um objeto {{domxref("BatteryManager")}},  e adiciona alguns novos eventos que você pode receber para monitorar o status da bateria.

+ +

Exemplo

+ +

Neste exemplo, nós observamos as mudanças em ambos os status de carregamento (se estamos ou não conectados e carregando) e para mudanças no nível da bateria. Isto é feito escutando pelos eventos {{event("chargingchange")}} e {{event("levelchange")}}, respectivamente.

+ +
var battery = navigator.battery || navigator.mozBattery || navigator.webkitBattery;
+
+function updateBatteryStatus() {
+  console.log("Status da bateria: " + battery.level * 100 + " %");
+
+  if (battery.charging) {
+    console.log("A bateria está carregando");
+  }
+}
+
+battery.addEventListener("chargingchange", updateBatteryStatus);
+battery.addEventListener("levelchange", updateBatteryStatus);
+updateBatteryStatus();
+
+ +

Veja também o exemplo na especificação.

+ +

Especificações

+ +

{{page("/pt-BR/docs/Web/API/BatteryManager","Specifications")}}

+ +

Compatibilidade entre navegadores

+ +

{{page("/pt-BR/docs/Web/API/BatteryManager","Browser_compatibility")}}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/batterymanager/ondischargingtimechange/index.html b/files/pt-br/web/api/batterymanager/ondischargingtimechange/index.html new file mode 100644 index 0000000000..4f5c402588 --- /dev/null +++ b/files/pt-br/web/api/batterymanager/ondischargingtimechange/index.html @@ -0,0 +1,35 @@ +--- +title: BatteryManager.ondischargingtimechange +slug: Web/API/BatteryManager/ondischargintimechange +tags: + - API + - Battery API + - Event Handler + - Propriedade + - Referencia +translation_of: Web/API/BatteryManager/ondischargingtimechange +--- +

{{APIRef("Battery API")}}

+ +

Especifica um event listener para receber eventos {{event("dischargingtimechange")}}. Esses eventos ocorrem quando a propriedade {{domxref("BatteryManager.dischargingTime","dischargingTime")}} (tempo de descarregamento) da bateria é atualizada.

+ +

Sintaxe

+ +
navigator.battery.ondischargingtimechange = funcRef
+ +

Onde funcRef é uma função para ser chamada quando o evento {{event("dischargingtimechange")}} ocorre.

+ +

Especificações

+ +

{{page("/pt-BR/docs/Web/API/BatteryManager","Specifications")}}

+ +

Compatibilidade entre navegadores

+ +

{{page("/pt-BR/docs/Web/API/BatteryManager","Browser_compatibility")}}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/batterymanager/ondischargintimechange/index.html b/files/pt-br/web/api/batterymanager/ondischargintimechange/index.html deleted file mode 100644 index 4f5c402588..0000000000 --- a/files/pt-br/web/api/batterymanager/ondischargintimechange/index.html +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: BatteryManager.ondischargingtimechange -slug: Web/API/BatteryManager/ondischargintimechange -tags: - - API - - Battery API - - Event Handler - - Propriedade - - Referencia -translation_of: Web/API/BatteryManager/ondischargingtimechange ---- -

{{APIRef("Battery API")}}

- -

Especifica um event listener para receber eventos {{event("dischargingtimechange")}}. Esses eventos ocorrem quando a propriedade {{domxref("BatteryManager.dischargingTime","dischargingTime")}} (tempo de descarregamento) da bateria é atualizada.

- -

Sintaxe

- -
navigator.battery.ondischargingtimechange = funcRef
- -

Onde funcRef é uma função para ser chamada quando o evento {{event("dischargingtimechange")}} ocorre.

- -

Especificações

- -

{{page("/pt-BR/docs/Web/API/BatteryManager","Specifications")}}

- -

Compatibilidade entre navegadores

- -

{{page("/pt-BR/docs/Web/API/BatteryManager","Browser_compatibility")}}

- -

Veja também

- - diff --git a/files/pt-br/web/api/canvas_api/a_basic_ray-caster/index.html b/files/pt-br/web/api/canvas_api/a_basic_ray-caster/index.html new file mode 100644 index 0000000000..ca188eb6f9 --- /dev/null +++ b/files/pt-br/web/api/canvas_api/a_basic_ray-caster/index.html @@ -0,0 +1,76 @@ +--- +title: A basic ray-caster +slug: Web/HTML/Canvas/A_basic_ray-caster +translation_of: Web/API/Canvas_API/A_basic_ray-caster +--- +
{{CanvasSidebar}}
+ +
+

Esse artigo disponibiliza um exemplo interessante do mundo real do uso do elemento {{HTMLElement("canvas")}} para fazer renderização via software de um ambiente em 3D utilizando ray-casting.

+
+ +

{{EmbedGHLiveSample("canvas-raycaster/index.html", 900, 300)}}

+ +

Abrir em uma nova janela

+ +

Porquê?

+ +

Depois de perceber, para meu deleite, que o elemento <canvas> que eu estava lendo sobre ele não estava apenas próximo de ser suportado pelo Firefox, mas que já estava com suporte na versão atual do Safari, eu tinha que tentar que fazer um pequeno teste.

+ +

A visão geral do canvas e o tutorial que eu encontrei no MDN são incríveis, mas ninguém havia escrito sobre animação, então eu pensei que poderia portar um exemplo de raycaster básico que eu havia trabalhado um tempo atrás, e ver e ver que tipo de performance nós podemos esperar te um pixel buffer controlado por JavaScript.

+ +

 

+ +

Como?

+ +

A ideia básica é usar o {{domxref("window.setInterval","setInterval()")}} com um delay arbitrário que corresponda a uma taxa de atualização desejada. Depois de cada intervalo uma função de atualização irá redesenhar o canvas mostrando a view atual. Eu sei que poderia ter iniciado com um exemplo mais simples, mas estou certo que o tutorial do canvas vai fazê-lo, e eu queria verificar se poderia fazer isso.

+ +

Sendo assim, a cada atualização, o raycaster verifica se você pressionou qualquer tecla por último, para conservar os cálculos não fazendo casting caso você esteja ocioso. Se você tiver pressionado, então o canvas é limpo, o solo e o céu são desenhados, a posição da câmera e/ou a orientação são atualizados, e os raios são feitos. Como os raios se cruzam paredes, então eles tornam uma tira de tela vertical na cor da parede que eles atingiram, misturado com uma versão mais escura da cor de acordo com a distância para a parede. A altura da fita também é modulada pela distância da câmera para a parede, e é desenhada centrada sobre a linha do horizonte.
+
+ O código que eu acabei com é um amálgama regurgitado dos capítulos de raycaster de um velho André LaMotheTricks do livro de Gurus de Programação de Jogos (ISBN: 0672305070), e um jaspe raycaster que encontrei online, filtrado através da minha compulsão de renomear tudo para que faça sentido Para mim, e todos os ajustes que tinham que ser feitos para fazer as coisas funcionarem bem.

+ +

 

+ +

Resultados

+ +

 

+ +


+ A tela no Safari 2.0.1 apresentou surpreendentemente bem. Com o fator de bloqueio criado para produzir slivers 8 pixels de largura, eu posso executar uma janela de 320 x 240 em 24 fps no meu Apple mini. Firefox 1.5 Beta 1 é ainda mais rápido; Eu posso executar 320 x 240 em 24 fps com 4 pixel slivers. Não exatamente um novo membro da família de software de ID, mas bastante decente considerando que é um ambiente totalmente interpretado, e eu não tenho que se preocupar com a alocação de memória ou modos de vídeo ou rotinas internas de codificação em assembler ou qualquer coisa. O código tenta ser muito eficiente, usando pesquisas de matrizes de valores pré-calculados, mas não sou um guru de otimização, então as coisas provavelmente poderiam ser escritas mais rapidamente.
+
+ Além disso, deixa muito a desejar em termos de tentar ser qualquer tipo de motor de jogo - não há texturas de parede, não sprites, sem portas, nem mesmo teleportadores para chegar a outro nível. Mas estou bastante confiante de que todas essas coisas poderiam ser adicionadas com tempo suficiente. A API de tela aceita a cópia de pixels de imagens, portanto, as texturas parecem possíveis. Vou deixar isso para outro artigo, provavelmente de outra pessoa. =)

+ +

 

+ +

O ray-caster

+ +

 

+ +


+ As pessoas agradáveis ​​aqui têm copiado manualmente meus arquivos para que você possa dar uma olhada, e para o seu prazer de hacking eu postei o conteúdo do arquivo individual como listagem de código (veja abaixo).
+
+ Então você está lá, o fogo até Safari 1.3 ou Firefox 1.5 ou outro navegador que suporta o elemento <canvas> e divirta-se!
+
+ input.js | Level.js | Player.js | RayCaster.html | RayCaster.js | trace.css | trace.js

+ +

 

+ +

 

+ +

 

+ +

 

+ +

See also

+ + diff --git a/files/pt-br/web/api/canvas_api/index.html b/files/pt-br/web/api/canvas_api/index.html new file mode 100644 index 0000000000..821909e726 --- /dev/null +++ b/files/pt-br/web/api/canvas_api/index.html @@ -0,0 +1,134 @@ +--- +title: Canvas +slug: Web/HTML/Canvas +tags: + - API + - Canvas + - Referência(2) +translation_of: Web/API/Canvas_API +--- +

{{CanvasSidebar}}

+ +

A Canvas API provê maneiras de desenhar gráficos via JavaScript e via elemento HTML {{HtmlElement("canvas")}}. Entre outras coisas, ele pode ser utilizado para animação, gráficos de jogos, visualização de dados, manipulação de fotos e processamento de vídeo em tempo real.

+ +

A Canvas API foca amplamente em gráficos 2D. A WebGL API, que também usa o elemento <canvas>, desenha gráficos 2D e 3D acelerados por hardware.

+ +

Exemplo básico

+ +

Este exemplo simples desenha um retângulo verde para um canvas.

+ +

HTML

+ +
<canvas id="canvas"></canvas>
+
+ +

JavaScript

+ +

O método {{domxref("Document.getElementById()")}} pega uma referência para o elemento HTML <canvas>. Em seguida, o método {{domxref("HTMLCanvasElement.getContext()")}} pega o contexto daquele elemento - a coisa sobre a qual o desenho será renderizado.

+ +

O desenho atual é feito usando a interface {{domxref("CanvasRenderingContext2D")}}. A propriedade {{domxref("CanvasRenderingContext2D.fillStyle", "fillStyle")}} faz o retângulo verde. O método {{domxref("CanvasRenderingContext2D.fillRect()", "fillRect()")}} coloca seu canto superior direito em (10, 10) e dá a ele o tamanho de 150 unidades de largura e 100 de altura.

+ +
const canvas = document.getElementById('canvas');
+const ctx = canvas.getContext('2d');
+
+ctx.fillStyle = 'green';
+ctx.fillRect(10, 10, 150, 100);
+
+ +

Resultado

+ +

{{ EmbedLiveSample('Exemplo_básico', 700, 180) }}

+ +

Referência

+ + + +
+

Nota: As interfaces relacionadas ao WebGLRenderingContext são referenciadas sob WebGL.

+
+ +

{{domxref("CanvasCaptureMediaStream")}} é uma interface relacionada.

+ +

Guias e Tutoriais

+ +
+
+
Tutorial Canvas
+
Um tutorial compreensivo abordando o uso básico da API de Canvas e suas funcionalidades avançadas.
+
Mergulhando no Canvas HTML5
+
Uma introdução prática e extensa à API Canvas e WebGL.
+
Guia Canvas
+
Uma referência acessível para a API Canvas.
+
Demonstração: Um ray-caster básico 
+
Uma demonstração de animação ray-tracing usando canvas.
+
Manipulando vídeos usando canvas
+
Combinando {{HTMLElement("video")}} e {{HTMLElement("canvas")}} para manipular dados de vídeo em tempo real.
+
+ +

Bibliotecas

+ +

A API Canvas é extremamente poderosa, mas nem sempre é simples de usar. As bibliotecas listadas abaixo podem fazer a criação de projetos baseados em canvas mais rápida e fácil.

+ + + +
+

Nota: Veja a WebGL API para bibliotecas 2D e 3D que usam WebGL.

+
+ +

Especificações

+ +
+ + + + + + + + + + + + + + + +
EspecificaçõesEstadoComentário
{{SpecName('HTML WHATWG', '#2dcontext', 'the 2D rendering context')}}{{Spec2('HTML WHATWG')}}
+
+ +

Compatibilidade de navegador

+ +

Aplicações Mozilla ganharam suporte para <canvas> a partir do Gecko 1.8 (Firefox 1.5). O elemento foi originalmente introduzido pela Apple para o Dashboard OS X e Safari. O Internet Explorer suporta <canvas> quando inclui-se um script do projeto Explorer Canvas, da google. Google Chrome e Opera 9 também suportam <canvas>.

+ +

Ver também

+ + diff --git a/files/pt-br/web/api/canvas_api/tutorial/advanced_animations/index.html b/files/pt-br/web/api/canvas_api/tutorial/advanced_animations/index.html new file mode 100644 index 0000000000..23f072420e --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/advanced_animations/index.html @@ -0,0 +1,386 @@ +--- +title: Advanced animations +slug: Web/Guide/HTML/Canvas_tutorial/Advanced_animations +tags: + - Animation + - Animations + - Canvas + - animated + - efeitos em animações +translation_of: Web/API/Canvas_API/Tutorial/Advanced_animations +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_animations", "Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas")}}
+ +
+

No último capítulo nós fizemos algumas animações básicas  e fomos conhecer caminhos para conseguir com que as coisas se movessem. Nesta parte prestaremos mais atenção nos movimentos e vamos adicionar algumas físicas para fazer nossas animações mais avançadas.

+
+ +

Desenhe uma bola

+ +

Nós estamos indo usar uma bola para nossa animação estudada. Então vamos pintar aquela bola desenhada no canvas. O seguinte código configurará.

+ +
<canvas id="canvas" width="600" height="300"></canvas>
+
+ +

 Como usual, nós precisamos de um contexto de desenho primeiro. Para desenhar a bola, nós criaremos um objeto bola ao qual contém propriedades e um método draw() para pintar no canvas.

+ +
var canvas = document.getElementById('canvas');
+var ctx = canvas.getContext('2d');
+
+var ball = {
+  x: 100,
+  y: 100,
+  radius: 25,
+  color: 'blue',
+  draw: function() {
+    ctx.beginPath();
+    ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true);
+    ctx.closePath();
+    ctx.fillStyle = this.color;
+    ctx.fill();
+  }
+};
+
+ball.draw();
+ +

Nada de especial aqui, a bola é atualmente um simples círculos e desenha com ajuda de 

+ +

{{domxref("CanvasRenderingContext2D.arc()", "arc()")}} method.

+ +

Adicionando velocidade

+ +

Agora que você tem a bola, Nós estamos prontos para adicionar uma animação como nós temos aprendido no último capítulo deste tutorial. Denovo, {{domxref("window.requestAnimationFrame()")}} ajuda-nos a controlar a animação. a bola pega o movimento adicionando um vetor de velocidade para a posição. Para cada frame, N[ós também {{domxref("CanvasRenderingContext2D.clearRect", "clear", "", 1)}}o canvas para remover velhor círculos da prioridade dos frames.

+ +
var canvas = document.getElementById('canvas');
+var ctx = canvas.getContext('2d');
+var raf;
+
+var ball = {
+  x: 100,
+  y: 100,
+  vx: 5,
+  vy: 2,
+  radius: 25,
+  color: 'blue',
+  draw: function() {
+    ctx.beginPath();
+    ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true);
+    ctx.closePath();
+    ctx.fillStyle = this.color;
+    ctx.fill();
+  }
+};
+
+function draw() {
+  ctx.clearRect(0,0, canvas.width, canvas.height);
+  ball.draw();
+  ball.x += ball.vx;
+  ball.y += ball.vy;
+  raf = window.requestAnimationFrame(draw);
+}
+
+canvas.addEventListener('mouseover', function(e) {
+  raf = window.requestAnimationFrame(draw);
+});
+
+canvas.addEventListener('mouseout', function(e) {
+  window.cancelAnimationFrame(raf);
+});
+
+ball.draw();
+
+ +

Limites

+ +

Sem um teste de limite de colisão nossa bola correria para fora do canvas rapidamente. Nós precisamos checar se a posição x e y da bola está fora das dimensões do canvas e invertida a direção do vetor de velocidade. Para fazer isto, Nós adicionamos a seguinte checagem para o método draw():

+ +
if (ball.y + ball.vy > canvas.height || ball.y + ball.vy < 0) {
+  ball.vy = -ball.vy;
+}
+if (ball.x + ball.vx > canvas.width || ball.x + ball.vx < 0) {
+  ball.vx = -ball.vx;
+}
+ +

Primeira demonstração

+ +

Deixe-me ver como isto fica em ação até agora. Mova seu mouse dentro do canvas para iniciar a animação.

+ + + +

{{EmbedLiveSample("First_demo", "610", "310")}}

+ +

Aceleração

+ +

Para fazer o movimento tão real, você para jogar com a velocidade como isto, por exemplo:

+ +
ball.vy *= .99;
+ball.vy += .25;
+ +

Esta diminuição da velocidade vertical para cada frame. Assim que a bola somente saltar no chão no final.

+ + + +

{{EmbedLiveSample("Second_demo", "610", "310")}}

+ +

Efeito de arrastar

+ +

Até agora nós temos feito uso do {{domxref("CanvasRenderingContext2D.clearRect", "clearRect")}} méthodo quando limpar as prioridades do frame.Se você substituir este método com um semi-transparente {{domxref("CanvasRenderingContext2D.fillRect", "fillRect")}}, você pode fácilmente criar um efeito de arrastar.

+ +
ctx.fillStyle = 'rgba(255, 255, 255, 0.3)';
+ctx.fillRect(0, 0, canvas.width, canvas.height);
+ + + +

{{EmbedLiveSample("Third_demo", "610", "310")}}

+ +

Adicione um controle de mouse

+ +

 

+ +

Para conseguir alguns controles sobre a bola, nós podemos fazer isto seguindo nosso mouse usando o evento mouseover, por exemplo. O clique por exemplo. O evento clique que libera a bola e deixa seu limite de novo.

+ + + +
var canvas = document.getElementById('canvas');
+var ctx = canvas.getContext('2d');
+var raf;
+var running = false;
+
+var ball = {
+  x: 100,
+  y: 100,
+  vx: 5,
+  vy: 1,
+  radius: 25,
+  color: 'blue',
+  draw: function() {
+    ctx.beginPath();
+    ctx.arc(this.x, this.y, this.radius, 0, Math.PI * 2, true);
+    ctx.closePath();
+    ctx.fillStyle = this.color;
+    ctx.fill();
+  }
+};
+
+function clear() {
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.3)';
+  ctx.fillRect(0,0,canvas.width,canvas.height);
+}
+
+function draw() {
+  clear();
+  ball.draw();
+  ball.x += ball.vx;
+  ball.y += ball.vy;
+
+  if (ball.y + ball.vy > canvas.height || ball.y + ball.vy < 0) {
+    ball.vy = -ball.vy;
+  }
+  if (ball.x + ball.vx > canvas.width || ball.x + ball.vx < 0) {
+    ball.vx = -ball.vx;
+  }
+
+  raf = window.requestAnimationFrame(draw);
+}
+
+canvas.addEventListener('mousemove', function(e) {
+  if (!running) {
+    clear();
+    ball.x = e.clientX;
+    ball.y = e.clientY;
+    ball.draw();
+  }
+});
+
+canvas.addEventListener('click', function(e) {
+  if (!running) {
+    raf = window.requestAnimationFrame(draw);
+    running = true;
+  }
+});
+
+canvas.addEventListener('mouseout', function(e) {
+  window.cancelAnimationFrame(raf);
+  running = false;
+});
+
+ball.draw();
+
+ +

Mova a bola usando seu mouse e libere - o com um clique.

+ +

{{EmbedLiveSample("Adding_mouse_control", "610", "310")}}

+ +

Sair

+ +

Este curto capítulo somente explica algumas técnicas para criar as mais avançadas animações. Há muito mais! Como adicionar um paddle, alguns bricks, e tornar este demo dentro de um jogo Breakout? Cheque a nossa área de Desenvolvimento de jogos para mais artigos de jogos.

+ +

Veja também:

+ + + +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_animations", "Web/API/Canvas_API/Tutorial/Pixel_manipulation_with_canvas")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html b/files/pt-br/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html new file mode 100644 index 0000000000..f711570b9f --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/applying_styles_and_colors/index.html @@ -0,0 +1,725 @@ +--- +title: Aplicando estilos e cores +slug: Web/Guide/HTML/Canvas_tutorial/Applying_styles_and_colors +translation_of: Web/API/Canvas_API/Tutorial/Applying_styles_and_colors +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Drawing_shapes", "Web/API/Canvas_API/Tutorial/Drawing_text")}}
+ +
+

No capítulo sobre desenhando formas com canvas, usamos apenas os estilos padrões de preenchimento e linha. Aqui vamos explorar as opções do canvas que temos à nossa disposição para tornar nossos desenhos um pouco mais atraentes. Você aprenderá a adicionar cores diferentes, estilos de linhas, gradientes, padrões e sombras aos seus desenhos.

+
+ +

Cores

+ +

Até agora só vimos métodos do contexto de desenho. Se quisermos aplicar cores a uma forma, existem duas propriedades importantes que podemos utilizar: fillStyle e strokeStyle.

+ +
+
{{domxref("CanvasRenderingContext2D.fillStyle", "fillStyle = color")}}
+
Define o estilo usado ao preencher (fill) formas.
+
{{domxref("CanvasRenderingContext2D.strokeStyle", "strokeStyle = color")}}
+
Define o estilo para os contornos (strokes) das formas.
+
+ +

color é uma string que representa um CSS {{cssxref("<color>")}}, um objeto gradiente, ou um objeto padrão. Examinaremos sobre objetos de gradiente e padrão mais tarde. Por padrão, a cor do contorno (stroke color) e a cor de preenchimento (fill color) estão definidos como preto (valor de cor no CSS é #000000).

+ +
+

Nota: Quando você definir as propriedades strokeStyle e/ou fillStyle , o novo valor será o padrão para todas as formas desenhadas a partir de então.  Para toda forma que você quiser uma cor diferente, você vai precisar alterar o valor da propriedade fillStyle ou strokeStyle.

+
+ +

As strings validas que você pode inserir devem, de acordo com a especificação ser valores CSS {{cssxref("<color>")}}. Cada um dos exemplos a seguir, descrevem a mesma cor.

+ +
// these all set the fillStyle to 'orange'
+
+ctx.fillStyle = 'orange';
+ctx.fillStyle = '#FFA500';
+ctx.fillStyle = 'rgb(255, 165, 0)';
+ctx.fillStyle = 'rgba(255, 165, 0, 1)';
+
+ +

Um fillStyle exemplo

+ +

Neste exemplo, nós vamos mais uma vez utilizar dois for loops para desenhar uma grade de retângulos, cada um com uma cor diferente. A imagem do resultado, deve parecer como a captura de tela. Não existe nada de muito espetacular acontecendo aqui. Nós usamos as duas variéveis i and j para gerar uma única cor em RGB para cada quadrado, e apenas modificando os valores vermelho e verde. O canal azul possui um valor fixo. Modificando os canais, você pode gerar todos os tipos de paletas. Aumentando os passos, você pode alcançar algo que se parece com a paleta de cores dos usuários de Photoshop.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  for (var i = 0; i < 6; i++) {
+    for (var j = 0; j < 6; j++) {
+      ctx.fillStyle = 'rgb(' + Math.floor(255 - 42.5 * i) + ',' +
+                       Math.floor(255 - 42.5 * j) + ',0)';
+      ctx.fillRect(j * 25, i * 25, 25, 25);
+    }
+  }
+}
+ + + +

O resultado se parece com isto:

+ +

{{EmbedLiveSample("A_fillStyle_example", 160, 160, "https://mdn.mozillademos.org/files/5417/Canvas_fillstyle.png")}}

+ +

Um strokeStyle exemplo

+ +

Este exemplo é similar com o anterior, porém utiliza a propriedade strokeStyle para alterar a cor de contorno das formas. Nós usamos o método arc()  para desenhar círculos ao invés de quadrados.

+ +
  function draw() {
+    var ctx = document.getElementById('canvas').getContext('2d');
+    for (var i = 0; i < 6; i++) {
+      for (var j = 0; j < 6; j++) {
+        ctx.strokeStyle = 'rgb(0,' + Math.floor(255 - 42.5 * i) + ',' +
+                         Math.floor(255 - 42.5 * j) + ')';
+        ctx.beginPath();
+        ctx.arc(12.5 + j * 25, 12.5 + i * 25, 10, 0, Math.PI * 2, true);
+        ctx.stroke();
+      }
+    }
+  }
+
+ + + +

O resultado se parece com isto:

+ +

{{EmbedLiveSample("A_strokeStyle_example", "180", "180", "https://mdn.mozillademos.org/files/253/Canvas_strokestyle.png")}}

+ +
Transparência
+ Além de desenhar formas opacas na tela, também podemos desenhar formas semi-transparentes (ou translúcidas). Isso é feito definindo a propriedade globalAlpha ou atribuindo uma cor semitransparente ao estilo de stroke e / ou fill style.
+ +
+
+
{{domxref("CanvasRenderingContext2D.globalAlpha", "globalAlpha = transparencyValue")}}
+
+
+

Aplica o valor de transparência especificado a todas as formas futuras desenhadas na tela. O valor deve estar entre 0,0 (totalmente transparente) e 1,0 (totalmente opaco). Este valor é 1.0 (totalmente opaco) por padrão.
+ A propriedade globalAlpha pode ser útil se você quiser desenhar muitas formas na tela com transparência semelhante, mas, caso contrário, geralmente é mais útil definir a transparência em formas individuais ao definir suas cores.

+ +

Como as propriedades strokeStyle e fillStyle aceitam os valores de cor CSS rgba, podemos usar a notação a seguir para atribuir uma cor transparente a eles.

+
+
+ +
// Assigning transparent colors to stroke and fill style
+
+ctx.strokeStyle = 'rgba(255, 0, 0, 0.5)';
+ctx.fillStyle = 'rgba(255, 0, 0, 0.5)';
+
+ +

A função rgba () é semelhante à função rgb (), mas possui um parâmetro extra. O último parâmetro define o valor da transparência dessa cor específica. O intervalo válido é novamente entre 0,0 (totalmente transparente) e 1,0 (totalmente opaco).

+ +

Um exemplo globalAlpha

+ +

Neste exemplo, desenharemos um plano de fundo de quatro quadrados coloridos diferentes. Além disso, desenharemos um conjunto de círculos semi-transparentes. A propriedade globalAlpha é configurada em 0.2, que será usada para todas as formas a partir desse ponto. Cada passo no loop for desenha um conjunto de círculos com um raio crescente. O resultado final é um gradiente radial. Ao sobrepor cada vez mais círculos um sobre o outro, reduzimos efetivamente a transparência dos círculos que já foram desenhados. Ao aumentar a contagem de etapas e, com efeito, desenhar mais círculos, o plano de fundo desapareceria completamente do centro da imagem.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  // draw background
+  ctx.fillStyle = '#FD0';
+  ctx.fillRect(0, 0, 75, 75);
+  ctx.fillStyle = '#6C0';
+  ctx.fillRect(75, 0, 75, 75);
+  ctx.fillStyle = '#09F';
+  ctx.fillRect(0, 75, 75, 75);
+  ctx.fillStyle = '#F30';
+  ctx.fillRect(75, 75, 75, 75);
+  ctx.fillStyle = '#FFF';
+
+  // set transparency value
+  ctx.globalAlpha = 0.2;
+
+  // Draw semi transparent circles
+  for (i = 0; i < 7; i++) {
+    ctx.beginPath();
+    ctx.arc(75, 75, 10 + 10 * i, 0, Math.PI * 2, true);
+    ctx.fill();
+  }
+}
+ + + +

{{EmbedLiveSample("A_globalAlpha_example", "180", "180", "https://mdn.mozillademos.org/files/232/Canvas_globalalpha.png")}}

+ +

Um exemplo usando o rgba()

+ +

Neste segundo exemplo, fazemos algo semelhante ao anterior, mas em vez de desenhar círculos uns sobre os outros, desenhei pequenos retângulos com crescente opacidade. O uso de rgba () oferece um pouco mais de controle e flexibilidade, pois podemos definir o estilo de preenchimento e traçado/stroke individualmente.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  // Draw background
+  ctx.fillStyle = 'rgb(255, 221, 0)';
+  ctx.fillRect(0, 0, 150, 37.5);
+  ctx.fillStyle = 'rgb(102, 204, 0)';
+  ctx.fillRect(0, 37.5, 150, 37.5);
+  ctx.fillStyle = 'rgb(0, 153, 255)';
+  ctx.fillRect(0, 75, 150, 37.5);
+  ctx.fillStyle = 'rgb(255, 51, 0)';
+  ctx.fillRect(0, 112.5, 150, 37.5);
+
+  // Draw semi transparent rectangles
+  for (var i = 0; i < 10; i++) {
+    ctx.fillStyle = 'rgba(255, 255, 255, ' + (i + 1) / 10 + ')';
+    for (var j = 0; j < 4; j++) {
+      ctx.fillRect(5 + i * 14, 5 + j * 37.5, 14, 27.5);
+    }
+  }
+}
+ + + +

{{EmbedLiveSample("An_example_using_rgba()", "180", "180", "https://mdn.mozillademos.org/files/246/Canvas_rgba.png")}}

+ +

Line styles

+ +

Existem várias propriedades que permitem estilizar linhas.

+ +
+
{{domxref("CanvasRenderingContext2D.lineWidth", "lineWidth = value")}}
+
Define a largura das linhas desenhadas no futuro.
+
{{domxref("CanvasRenderingContext2D.lineCap", "lineCap = type")}}
+
Define a aparência dos fins das linhas.
+
{{domxref("CanvasRenderingContext2D.lineJoin", "lineJoin = type")}}
+
Define a aparência dos "cantos" onde as linhas se encontram.
+
{{domxref("CanvasRenderingContext2D.miterLimit", "miterLimit = value")}}
+
Estabelece um limite na mitra quando duas linhas se juntam em um ângulo agudo, para permitir controlar a espessura da junção.
+
{{domxref("CanvasRenderingContext2D.getLineDash", "getLineDash()")}}
+
Retorna a matriz de padrão de traço de linha atual que contém um número par de números não negativos
+
{{domxref("CanvasRenderingContext2D.setLineDash", "setLineDash(segments)")}}
+
Define o padrão de traço da linha atual.
+
{{domxref("CanvasRenderingContext2D.lineDashOffset", "lineDashOffset = value")}}
+
Especifica onde iniciar uma matriz de traços em uma linha.
+
+ +

Você entenderá melhor o que eles fazem observando os exemplos abaixo.

+ +

Um exemplo lineWidth

+ +

A largura da linha é a espessura do traçado centralizado no caminho especificado. Em outras palavras, a área desenhada se estende até a metade da largura da linha em ambos os lados do caminho.

+ +

  Como as coordenadas da tela não fazem referência direta aos pixels, deve-se tomar cuidado especial para obter linhas horizontais e verticais nítidas.

+ +

No exemplo abaixo, 10 linhas retas são desenhadas com larguras de linhas crescentes. A linha na extrema esquerda tem 1,0 unidades de largura. No entanto, as linhas de espessura à esquerda e todas as outras linhas com número inteiro ímpar não aparecem nítidas, devido ao posicionamento do caminho.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  for (var i = 0; i < 10; i++) {
+    ctx.lineWidth = 1 + i;
+    ctx.beginPath();
+    ctx.moveTo(5 + i * 14, 5);
+    ctx.lineTo(5 + i * 14, 140);
+    ctx.stroke();
+  }
+}
+
+ + + +

{{EmbedLiveSample("A_lineWidth_example", "180", "180", "https://mdn.mozillademos.org/files/239/Canvas_linewidth.png")}}

+ +

A obtenção de linhas nítidas requer a compreensão de como os caminhos são traçados. Nas imagens abaixo, a grade representa a grade de coordenadas da tela. Os quadrados entre as linhas de grade são pixels reais na tela. Na primeira imagem da grade abaixo, um retângulo de (2,1) a (5,5) é preenchido. A área inteira entre eles (vermelho claro) cai nos limites dos pixels, portanto, o retângulo preenchido resultante terá bordas nítidas.
+

+ +

Se você considerar um caminho de (3,1) a (3,5) com uma espessura de linha de 1,0, você terminará com a situação na segunda imagem. A área real a ser preenchida (azul escuro) se estende apenas até a metade dos pixels dos dois lados do caminho. Uma aproximação disso deve ser renderizada, o que significa que esses pixels são sombreados apenas parcialmente e resultam em toda a área (azul claro e azul escuro) sendo preenchida com uma cor apenas metade da escuridão da cor real do traço. É o que acontece com a linha de largura 1.0 no código de exemplo anterior.

+ +

Para corrigir isso, você precisa ser muito preciso na criação do seu caminho. Sabendo que uma linha de largura 1,0 estenderá meia unidade para ambos os lados do caminho, criar o caminho de (3,5,1) a (3,5,5) resulta na situação da terceira imagem - a largura da linha 1,0 termina completamente e preenchendo com precisão uma única linha vertical de pixel.
+  

+ +
+

Nota: Esteja ciente de que, no nosso exemplo de linha vertical, a posição Y ainda faz referência a uma posição de linha de grade inteira - se não tivesse, veríamos pixels com meia cobertura nos pontos de extremidade (mas observe também que esse comportamento depende do estilo lineCap atual cujo valor padrão é butt; você pode calcular traçados consistentes com coordenadas de meio pixel para linhas de largura ímpar, configurando o estilo lineCap como quadrado, para que a borda externa do traçado ao redor do ponto de extremidade seja estendida automaticamente para cobrir o pixel inteiro exatamente).

+ +

Observe também que apenas os pontos de extremidade inicial e final de um caminho são afetados: se um caminho for fechado com closePath (), não haverá ponto inicial e final; em vez disso, todos os pontos de extremidade no caminho são conectados ao segmento anterior e ao próximo anexado usando a configuração atual do estilo lineJoin, cujo valor padrão é mitra, com o efeito de estender automaticamente as bordas externas dos segmentos conectados ao seu ponto de interseção. que o traçado renderizado cobrirá exatamente os pixels completos centralizados em cada ponto final se esses segmentos conectados forem horizontais e / ou verticais). Veja as próximas duas seções para demonstrações desses estilos de linha adicionais.

+
+ +

Para linhas de largura uniforme, cada metade acaba sendo uma quantidade inteira de pixels, portanto, você deseja um caminho entre pixels (ou seja, (3,1) a (3,5)), em vez de no meio dos pixels .

+ +

Embora seja um pouco doloroso ao trabalhar inicialmente com gráficos 2D escalonáveis, prestar atenção à grade de pixels e à posição dos caminhos garante que seus desenhos pareçam corretos, independentemente da escala ou de qualquer outra transformação envolvida. Uma linha vertical de 1,0 largura desenhada na posição correta se tornará uma linha nítida de 2 pixels quando aumentada em 2 e aparecerá na posição correta.

+ +

Exemplo lineCap.

+ +

A propriedade lineCap determina como os pontos finais de cada linha são desenhados. Existem três valores possíveis para essa propriedade e são: bunda, redondo e quadrado. Por padrão, essa propriedade está configurada para butt.

+ +
+
butt
+
As extremidades das linhas são quadradas nos pontos finais.
+
round
+
As extremidades das linhas são arredondadas.
+ arredondadas.
+
square
+
As extremidades das linhas são ajustadas ao quadrado, adicionando uma caixa com a mesma largura e metade da altura da espessura da linha.
+
+ +

Neste exemplo, desenharemos três linhas, cada uma com um valor diferente para a propriedade lineCap. Também adicionei dois guias para ver as diferenças exatas entre os três. Cada uma dessas linhas começa e termina exatamente nesses guias.

+ +

A linha à esquerda usa a opção de topo padrão. Você notará que está desenhado completamente alinhado com as guias. O segundo está definido para usar a opção redonda. Isso adiciona um semicírculo ao final que tem um raio com metade da largura da linha. A linha à direita usa a opção quadrada. Isso adiciona uma caixa com largura igual e metade da altura da espessura da linha.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  var lineCap = ['butt', 'round', 'square'];
+
+  // Draw guides
+  ctx.strokeStyle = '#09f';
+  ctx.beginPath();
+  ctx.moveTo(10, 10);
+  ctx.lineTo(140, 10);
+  ctx.moveTo(10, 140);
+  ctx.lineTo(140, 140);
+  ctx.stroke();
+
+  // Draw lines
+  ctx.strokeStyle = 'black';
+  for (var i = 0; i < lineCap.length; i++) {
+    ctx.lineWidth = 15;
+    ctx.lineCap = lineCap[i];
+    ctx.beginPath();
+    ctx.moveTo(25 + i * 50, 10);
+    ctx.lineTo(25 + i * 50, 140);
+    ctx.stroke();
+  }
+}
+
+ + + +

{{EmbedLiveSample("A_lineCap_example", "180", "180", "https://mdn.mozillademos.org/files/236/Canvas_linecap.png")}}

+ +

Um exemplo de lineJoin

+ +

A propriedade lineJoin determina como dois segmentos de conexão (de linhas, arcos ou curvas) com comprimentos diferentes de zero em uma forma são unidos (segmentos degenerados com comprimentos zero, cujos pontos finais e pontos de controle especificados são exatamente na mesma posição, são ignorados) .

+ +

Existem três valores possíveis para essa propriedade: round, chanfro e mitra. Por padrão, essa propriedade está configurada para mitra. Observe que a configuração lineJoin não terá efeito se os dois segmentos conectados tiverem a mesma direção, porque nenhuma área de junção será adicionada neste caso.

+ +
+
round
+
Arredonda os cantos de uma forma preenchendo um setor adicional de disco centralizado no ponto final comum dos segmentos conectados. O raio desses cantos arredondados é igual à metade da largura da linha.
+
bevel
+
Preenche uma área triangular adicional entre o ponto final comum dos segmentos conectados e os cantos retangulares externos separados de cada segmento.
+
miter
+
Os segmentos conectados são unidos estendendo suas bordas externas para se conectarem em um único ponto, com o efeito de preencher uma área adicional em forma de losango. Essa configuração é efetuada pela propriedade miterLimit, explicada abaixo.
+
+ +

O exemplo abaixo desenha três caminhos diferentes, demonstrando cada uma dessas três configurações de propriedade lineJoin; a saída é mostrada acima.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  var lineJoin = ['round', 'bevel', 'miter'];
+  ctx.lineWidth = 10;
+  for (var i = 0; i < lineJoin.length; i++) {
+    ctx.lineJoin = lineJoin[i];
+    ctx.beginPath();
+    ctx.moveTo(-5, 5 + i * 40);
+    ctx.lineTo(35, 45 + i * 40);
+    ctx.lineTo(75, 5 + i * 40);
+    ctx.lineTo(115, 45 + i * 40);
+    ctx.lineTo(155, 5 + i * 40);
+    ctx.stroke();
+  }
+}
+
+ + + +

{{EmbedLiveSample("A_lineJoin_example", "180", "180", "https://mdn.mozillademos.org/files/237/Canvas_linejoin.png")}}

+ +

Uma demonstração da propriedade miterLimit

+ +

Como você viu no exemplo anterior, ao unir duas linhas com a opção de esquadria, as bordas externas das duas linhas de junção são estendidas até o ponto em que elas se encontram. Para linhas com ângulos amplos entre si, esse ponto não está longe do ponto de conexão interno. No entanto, à medida que os ângulos entre cada linha diminuem, a distância (comprimento da mitra) entre esses pontos aumenta exponencialmente.

+ +

A propriedade miterLimit determina a que distância o ponto de conexão externo pode ser colocado do ponto de conexão interno. Se duas linhas excederem esse valor, uma junção de chanfro será desenhada. Observe que o comprimento máximo da esquadria é o produto da largura da linha medida no sistema de coordenadas atual, pelo valor dessa propriedade miterLimit (cujo valor padrão é 10.0 no HTML {{HTMLElement ("canvas")}}}), portanto, o O miterLimit pode ser definido independentemente da escala de exibição atual ou de quaisquer transformações afins de caminhos: apenas influencia a forma efetivamente renderizada das arestas da linha.

+ +

Mais exatamente, o limite da mitra é a proporção máxima permitida do comprimento da extensão (na tela HTML, é medida entre o canto externo das arestas unidas da linha e o ponto de extremidade comum dos segmentos de conexão especificados no caminho) pela metade do espessura da linha. Pode ser definido de maneira equivalente como a proporção máxima permitida da distância entre os pontos interno e externo da junção das arestas e a largura total da linha. Em seguida, é igual ao coecante da metade do ângulo interno mínimo dos segmentos de conexão abaixo dos quais nenhuma junção de esquadria será renderizada, mas apenas uma junção de chanfro:

+ + + +

Aqui está uma pequena demonstração na qual você pode definir o mitreLimit dinamicamente e ver como isso afeta as formas na tela. As linhas azuis mostram onde estão os pontos inicial e final de cada uma das linhas no padrão em zigue-zague.

+ +

Se você especificar um valor de miterLimite abaixo de 4.2 nesta demonstração, nenhum dos cantos visíveis poderá ser uma extensão de mitra, mas apenas com um pequeno canal próximo às linhas azuis; com um limite máximo acima de 10, a maioria dos cantos nesta demonstração deve ser levada a uma meia-esquadria das linhas azuis e a altura está diminuindo entre os cantos da esquerda para a direita porque eles estão conectados com ângulos crescentes; com valores intermediários, os cantos do lado esquerdo ou apenas um canto próximo às linhas azuis e os cantos do lado direito com uma extensão de esquadria (também com uma altura decrescente).

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  // Clear canvas
+  ctx.clearRect(0, 0, 150, 150);
+
+  // Draw guides
+  ctx.strokeStyle = '#09f';
+  ctx.lineWidth   = 2;
+  ctx.strokeRect(-5, 50, 160, 50);
+
+  // Set line styles
+  ctx.strokeStyle = '#000';
+  ctx.lineWidth = 10;
+
+  // check input
+  if (document.getElementById('miterLimit').value.match(/\d+(\.\d+)?/)) {
+    ctx.miterLimit = parseFloat(document.getElementById('miterLimit').value);
+  } else {
+    alert('Value must be a positive number');
+  }
+
+  // Draw lines
+  ctx.beginPath();
+  ctx.moveTo(0, 100);
+  for (i = 0; i < 24 ; i++){
+    var dy = i % 2 == 0 ? 25 : -25 ;
+    ctx.lineTo(Math.pow(i, 1.5) * 2, 75 + dy);
+  }
+  ctx.stroke();
+  return false;
+}
+
+ + + +

{{EmbedLiveSample("A_demo_of_the_miterLimit_property", "400", "180", "https://mdn.mozillademos.org/files/240/Canvas_miterlimit.png")}}

+ +

Usando linhas tracejadas

+ +

O método setLineDash e a propriedade lineDashOffset especificam o padrão de traço para as linhas. O método setLineDash aceita uma lista de números que especificam distâncias para desenhar alternadamente entre uma linha e uma lacuna. Já a propriedade lineDashOffset define a distância até onde se deve iniciar a linha.

+ +

Neste exemplo, criaremos um efeito de formigas caminhando. É uma técnica de animação frequentemente usada em computação gráfica, pois ajuda o usuário a fazer uma distinção entre a borda e o plano de fundo animando a borda. Mais tarde neste tutorial, você aprenderá como fazer animações básicas.

+ + + +
var ctx = document.getElementById('canvas').getContext('2d');
+var offset = 0;
+
+function draw() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  ctx.setLineDash([4, 2]);
+  ctx.lineDashOffset = -offset;
+  ctx.strokeRect(10, 10, 100, 100);
+}
+
+function march() {
+  offset++;
+  if (offset > 16) {
+    offset = 0;
+  }
+  draw();
+  setTimeout(march, 20);
+}
+
+march();
+ +

{{EmbedLiveSample("Using_line_dashes", "120", "120", "https://mdn.mozillademos.org/files/9853/marching-ants.png")}}

+ +

Gradients

+ +

Just like any normal drawing program, we can fill and stroke shapes using linear and radial gradients. We create a {{domxref("CanvasGradient")}} object by using one of the following methods. We can then assign this object to the fillStyle or strokeStyle properties.

+ +
+
{{domxref("CanvasRenderingContext2D.createLinearGradient", "createLinearGradient(x1, y1, x2, y2)")}}
+
Creates a linear gradient object with a starting point of (x1, y1) and an end point of (x2, y2).
+
{{domxref("CanvasRenderingContext2D.createRadialGradient", "createRadialGradient(x1, y1, r1, x2, y2, r2)")}}
+
Creates a radial gradient. The parameters represent two circles, one with its center at (x1, y1) and a radius of r1, and the other with its center at (x2, y2) with a radius of r2.
+
+ +

For example:

+ +
var lineargradient = ctx.createLinearGradient(0, 0, 150, 150);
+var radialgradient = ctx.createRadialGradient(75, 75, 0, 75, 75, 100);
+
+ +

Once we've created a CanvasGradient object we can assign colors to it by using the addColorStop() method.

+ +
+
{{domxref("CanvasGradient.addColorStop", "gradient.addColorStop(position, color)")}}
+
Creates a new color stop on the gradient object. The position is a number between 0.0 and 1.0 and defines the relative position of the color in the gradient, and the color argument must be a string representing a CSS {{cssxref("<color>")}}, indicating the color the gradient should reach at that offset into the transition.
+
+ +

You can add as many color stops to a gradient as you need. Below is a very simple linear gradient from white to black.

+ +
var lineargradient = ctx.createLinearGradient(0, 0, 150, 150);
+lineargradient.addColorStop(0, 'white');
+lineargradient.addColorStop(1, 'black');
+
+ +

A createLinearGradient example

+ +

In this example, we'll create two different gradients. As you can see here, both the strokeStyle and fillStyle properties can accept a canvasGradient object as valid input.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  // Create gradients
+  var lingrad = ctx.createLinearGradient(0, 0, 0, 150);
+  lingrad.addColorStop(0, '#00ABEB');
+  lingrad.addColorStop(0.5, '#fff');
+  lingrad.addColorStop(0.5, '#26C000');
+  lingrad.addColorStop(1, '#fff');
+
+  var lingrad2 = ctx.createLinearGradient(0, 50, 0, 95);
+  lingrad2.addColorStop(0.5, '#000');
+  lingrad2.addColorStop(1, 'rgba(0, 0, 0, 0)');
+
+  // assign gradients to fill and stroke styles
+  ctx.fillStyle = lingrad;
+  ctx.strokeStyle = lingrad2;
+
+  // draw shapes
+  ctx.fillRect(10, 10, 130, 130);
+  ctx.strokeRect(50, 50, 50, 50);
+
+}
+
+ + + +

The first is a background gradient. As you can see, we assigned two colors at the same position. You do this to make very sharp color transitions—in this case from white to green. Normally, it doesn't matter in what order you define the color stops, but in this special case, it does significantly. If you keep the assignments in the order you want them to appear, this won't be a problem.

+ +

In the second gradient, we didn't assign the starting color (at position 0.0) since it wasn't strictly necessary, because it will automatically assume the color of the next color stop. Therefore, assigning the black color at position 0.5 automatically makes the gradient, from the start to this stop, black.

+ +

{{EmbedLiveSample("A_createLinearGradient_example", "180", "180", "https://mdn.mozillademos.org/files/235/Canvas_lineargradient.png")}}

+ +

A createRadialGradient example

+ +

In this example, we'll define four different radial gradients. Because we have control over the start and closing points of the gradient, we can achieve more complex effects than we would normally have in the "classic" radial gradients we see in, for instance, Photoshop (that is, a gradient with a single center point where the gradient expands outward in a circular shape).

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  // Create gradients
+  var radgrad = ctx.createRadialGradient(45, 45, 10, 52, 50, 30);
+  radgrad.addColorStop(0, '#A7D30C');
+  radgrad.addColorStop(0.9, '#019F62');
+  radgrad.addColorStop(1, 'rgba(1, 159, 98, 0)');
+
+  var radgrad2 = ctx.createRadialGradient(105, 105, 20, 112, 120, 50);
+  radgrad2.addColorStop(0, '#FF5F98');
+  radgrad2.addColorStop(0.75, '#FF0188');
+  radgrad2.addColorStop(1, 'rgba(255, 1, 136, 0)');
+
+  var radgrad3 = ctx.createRadialGradient(95, 15, 15, 102, 20, 40);
+  radgrad3.addColorStop(0, '#00C9FF');
+  radgrad3.addColorStop(0.8, '#00B5E2');
+  radgrad3.addColorStop(1, 'rgba(0, 201, 255, 0)');
+
+  var radgrad4 = ctx.createRadialGradient(0, 150, 50, 0, 140, 90);
+  radgrad4.addColorStop(0, '#F4F201');
+  radgrad4.addColorStop(0.8, '#E4C700');
+  radgrad4.addColorStop(1, 'rgba(228, 199, 0, 0)');
+
+  // draw shapes
+  ctx.fillStyle = radgrad4;
+  ctx.fillRect(0, 0, 150, 150);
+  ctx.fillStyle = radgrad3;
+  ctx.fillRect(0, 0, 150, 150);
+  ctx.fillStyle = radgrad2;
+  ctx.fillRect(0, 0, 150, 150);
+  ctx.fillStyle = radgrad;
+  ctx.fillRect(0, 0, 150, 150);
+}
+
+ + + +

In this case, we've offset the starting point slightly from the end point to achieve a spherical 3D effect. It's best to try to avoid letting the inside and outside circles overlap because this results in strange effects which are hard to predict.

+ +

The last color stop in each of the four gradients uses a fully transparent color. If you want to have a nice transition from this to the previous color stop, both colors should be equal. This isn't very obvious from the code because it uses two different CSS color methods as a demonstration, but in the first gradient #019F62 = rgba(1,159,98,1).

+ +

{{EmbedLiveSample("A_createRadialGradient_example", "180", "180", "https://mdn.mozillademos.org/files/244/Canvas_radialgradient.png")}}

+ +

Patterns

+ +

In one of the examples on the previous page, we used a series of loops to create a pattern of images. There is, however, a much simpler method: the createPattern() method.

+ +
+
{{domxref("CanvasRenderingContext2D.createPattern", "createPattern(image, type)")}}
+
Creates and returns a new canvas pattern object. image is a {{domxref("CanvasImageSource")}} (that is, an {{domxref("HTMLImageElement")}}, another canvas, a {{HTMLElement("video")}} element, or the like. type is a string indicating how to use the image.
+
+ +

The type specifies how to use the image in order to create the pattern, and must be one of the following string values:

+ +
+
repeat
+
Tiles the image in both vertical and horizontal directions.
+
repeat-x
+
Tiles the image horizontally but not vertically.
+
repeat-y
+
Tiles the image vertically but not horizontally.
+
no-repeat
+
Doesn't tile the image. It's used only once.
+
+ +

We use this method to create a {{domxref("CanvasPattern")}} object which is very similar to the gradient methods we've seen above. Once we've created a pattern, we can assign it to the fillStyle or strokeStyle properties. For example:

+ +
var img = new Image();
+img.src = 'someimage.png';
+var ptrn = ctx.createPattern(img, 'repeat');
+
+ +
+

Note: Like with the drawImage() method, you must make sure the image you use is loaded before calling this method or the pattern may be drawn incorrectly.

+
+ +

A createPattern example

+ +

In this last example, we'll create a pattern to assign to the fillStyle property. The only thing worth noting is the use of the image's onload handler. This is to make sure the image is loaded before it is assigned to the pattern.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  // create new image object to use as pattern
+  var img = new Image();
+  img.src = 'https://mdn.mozillademos.org/files/222/Canvas_createpattern.png';
+  img.onload = function() {
+
+    // create pattern
+    var ptrn = ctx.createPattern(img, 'repeat');
+    ctx.fillStyle = ptrn;
+    ctx.fillRect(0, 0, 150, 150);
+
+  }
+}
+
+ + + +

{{EmbedLiveSample("A_createPattern_example", "180", "180", "https://mdn.mozillademos.org/files/222/Canvas_createpattern.png")}}

+ +

Shadows

+ +

Using shadows involves just four properties:

+ +
+
{{domxref("CanvasRenderingContext2D.shadowOffsetX", "shadowOffsetX = float")}}
+
Indicates the horizontal distance the shadow should extend from the object. This value isn't affected by the transformation matrix. The default is 0.
+
{{domxref("CanvasRenderingContext2D.shadowOffsetY", "shadowOffsetY = float")}}
+
Indicates the vertical distance the shadow should extend from the object. This value isn't affected by the transformation matrix. The default is 0.
+
{{domxref("CanvasRenderingContext2D.shadowBlur", "shadowBlur = float")}}
+
Indicates the size of the blurring effect; this value doesn't correspond to a number of pixels and is not affected by the current transformation matrix. The default value is 0.
+
{{domxref("CanvasRenderingContext2D.shadowColor", "shadowColor = color")}}
+
A standard CSS color value indicating the color of the shadow effect; by default, it is fully-transparent black.
+
+ +

The properties shadowOffsetX and shadowOffsetY indicate how far the shadow should extend from the object in the X and Y directions; these values aren't affected by the current transformation matrix. Use negative values to cause the shadow to extend up or to the left, and positive values to cause the shadow to extend down or to the right. These are both 0 by default.

+ +

The shadowBlur property indicates the size of the blurring effect; this value doesn't correspond to a number of pixels and is not affected by the current transformation matrix. The default value is 0.

+ +

The shadowColor property is a standard CSS color value indicating the color of the shadow effect; by default, it is fully-transparent black.

+ +
+

Note: Shadows are only drawn for source-over compositing operations.

+
+ +

A shadowed text example

+ +

This example draws a text string with a shadowing effect.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  ctx.shadowOffsetX = 2;
+  ctx.shadowOffsetY = 2;
+  ctx.shadowBlur = 2;
+  ctx.shadowColor = 'rgba(0, 0, 0, 0.5)';
+
+  ctx.font = '20px Times New Roman';
+  ctx.fillStyle = 'Black';
+  ctx.fillText('Sample String', 5, 30);
+}
+
+ + + +

{{EmbedLiveSample("A_shadowed_text_example", "180", "100", "https://mdn.mozillademos.org/files/2505/shadowed-string.png")}}

+ +

We will look at the font property and fillText method in the next chapter about drawing text.

+ +

Canvas fill rules

+ +

When using fill (or {{domxref("CanvasRenderingContext2D.clip", "clip")}} and {{domxref("CanvasRenderingContext2D.isPointInPath", "isPointinPath")}}) you can optionally provide a fill rule algorithm by which to determine if a point is inside or outside a path and thus if it gets filled or not. This is useful when a path intersects itself or is nested.
+
+ Two values are possible:

+ + + +

In this example we are using the evenodd rule.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  ctx.beginPath();
+  ctx.arc(50, 50, 30, 0, Math.PI * 2, true);
+  ctx.arc(50, 50, 15, 0, Math.PI * 2, true);
+  ctx.fill('evenodd');
+}
+ + + +

{{EmbedLiveSample("Canvas_fill_rules", "110", "110", "https://mdn.mozillademos.org/files/9855/fill-rule.png")}}

+ +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Drawing_shapes", "Web/API/Canvas_API/Tutorial/Drawing_text")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/basic_animations/index.html b/files/pt-br/web/api/canvas_api/tutorial/basic_animations/index.html new file mode 100644 index 0000000000..125e0874a7 --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/basic_animations/index.html @@ -0,0 +1,331 @@ +--- +title: Basic animations +slug: Web/Guide/HTML/Canvas_tutorial/Basic_animations +translation_of: Web/API/Canvas_API/Tutorial/Basic_animations +--- +

Já que estamos usando JavaScript para controlar {{HTMLElement("canvas")}} elementos, também é muito fácil criar animações interativas. Fazer animações mais complexas pode levar um tempo extra; esperamos introduzir um novo artigo para auxiliar sobre isso em breve.

+ +

Provavelmente a maior limitação é que uma vez que uma forma é desenhada, ela permanece assim. Se precisarmos mover, temos que redesenhar-lá e tudo que foi desenhado antes. Demora muito tempo pra redesenhar frames complexos e a desempenho depende altamente da velocidade do computador em que está rodando.

+ +

Passos para animação básica

+ +

Estes são os passos que você precisa para desenhar um frame:

+ +
    +
  1. Limpe o canvas
    + A menos que a forma que você vai desenhar preencha o canvas completo(por exemplo, uma imagem de fundo), você precisa limpar todas as formas que foram desenhadas anteriormente. O caminho mais fácil para fazer isso é usando o método clearRect().
    2. +
  2. Salve o estado da tela
    + Se você estiver mudando alguma configuração(como estilos, transformações, etc.) que afete o estado do canvas e você quer garantir que o estado original seja usado sempre que um quadro é desenhado, você precisa salvar esse estado original.
    3. +
  3. Desenhe formas animadas
    + A etapa em que você faz a renderização real do quadro.
    4. +
  4. Restaure o estado do canvas
    + Se você salvou o estado, restaure-o antes de desenhar um novo quadro.
    5. +
+ +

Controlando uma animação

+ +

Formas são desenhos na tela usando os canvas métodos diretamente ou chamando personalizadas. Em circunstancias normais, nós somente vemos esses resultados aparecerem na tela quando o script termina de ser executado. Por exemplo, não é possível fazer uma animação dentro de um loop for.

+ +

Isso significa que precisamos de um jeito para executar nossas funções de desenho durante um período de tempo. Existem dois jeitos para controlar uma animação como essa.

+ +

Atualizações agendadas

+ +

Primeiramente há as funções {{domxref("window.setInterval()")}} e {{domxref("window.setTimeout()")}}, que podem ser usadas para chamar uma função específica durante um certo período definido de tempo.

+ +
+

Nota: O método {{domxref("window.requestAnimationFrame()")}} agora é a maneira recomendada de programar animações. Vamos atualizar esse tutorial para abortar isso em breve.

+
+ +
+
setInterval(função,atraso)
+
Inicia repetidamente executando a função específica pela função a cada milissegundo de atraso.
+
setTimeout(função,atraso)
+
Executa a função especificada pela função em milissegundos de atraso.
+
+ +

Se você não quer nenhuma interação do usuário, é melhor usar a função setInterval() que executa repeditamente o código fornecido.

+ +

Atualizar na interação do usuário

+ +

O segundo método que nós podemos usar para controlar uma animação é a entrada do usuário. Se nós quiséssimos criar um jogo, nós poderiamos usar os eventos do teclado ou mouse para controlar a animação. Ao definir {{domxref("EventListener")}}s, nós pegamos qualquer interação do usuário e executamos nossas funções da animação. 

+ +

Se você quer a interação do usuário, você pode usar uma versão menor ou a versão principal do nosso framework pra animação:

+ +
var myAnimation = new MiniDaemon(null, animateShape, 500, Infinity);
+ +

ou

+ +
var myAnimation = new Daemon(null, animateShape, 500, Infinity);
+ +

Nos exemplos abaixo, no entanto, usamos o método {{domxref("window.setInterval()")}} para controlar a animação. Na parte inferior dessa página há alguns links de exemplos que usam {{domxref("window.setTimeout()")}}.

+ +

Um sistema solar animado

+ +

Esse exemplo anima um pequeno modelo do nosso sistema solar.

+ +
var sun = new Image();
+var moon = new Image();
+var earth = new Image();
+function init(){
+  sun.src = 'https://mdn.mozillademos.org/files/1456/Canvas_sun.png';
+  moon.src = 'https://mdn.mozillademos.org/files/1443/Canvas_moon.png';
+  earth.src = 'https://mdn.mozillademos.org/files/1429/Canvas_earth.png';
+  setInterval(draw,100);
+}
+
+function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+
+  ctx.globalCompositeOperation = 'destination-over';
+  ctx.clearRect(0,0,300,300); // clear canvas
+
+  ctx.fillStyle = 'rgba(0,0,0,0.4)';
+  ctx.strokeStyle = 'rgba(0,153,255,0.4)';
+  ctx.save();
+  ctx.translate(150,150);
+
+  // Earth
+  var time = new Date();
+  ctx.rotate( ((2*Math.PI)/60)*time.getSeconds() + ((2*Math.PI)/60000)*time.getMilliseconds() );
+  ctx.translate(105,0);
+  ctx.fillRect(0,-12,50,24); // Shadow
+  ctx.drawImage(earth,-12,-12);
+
+  // Moon
+  ctx.save();
+  ctx.rotate( ((2*Math.PI)/6)*time.getSeconds() + ((2*Math.PI)/6000)*time.getMilliseconds() );
+  ctx.translate(0,28.5);
+  ctx.drawImage(moon,-3.5,-3.5);
+  ctx.restore();
+
+  ctx.restore();
+
+  ctx.beginPath();
+  ctx.arc(150,150,105,0,Math.PI*2,false); // Earth orbit
+  ctx.stroke();
+
+  ctx.drawImage(sun,0,0,300,300);
+}
+
+ + + +

{{EmbedLiveSample("An_animated_solar_system", "310", "310", "https://mdn.mozillademos.org/files/202/Canvas_animation1.png")}}

+ +

Um relógio animado

+ +

Esse exemplos desenha um relógio animado, mostrando sua hora atual.

+ +
function init(){
+  clock();
+  setInterval(clock,1000);
+}
+
+function clock(){
+  var now = new Date();
+  var ctx = document.getElementById('canvas').getContext('2d');
+  ctx.save();
+  ctx.clearRect(0,0,150,150);
+  ctx.translate(75,75);
+  ctx.scale(0.4,0.4);
+  ctx.rotate(-Math.PI/2);
+  ctx.strokeStyle = "black";
+  ctx.fillStyle = "white";
+  ctx.lineWidth = 8;
+  ctx.lineCap = "round";
+
+  // Hour marks
+  ctx.save();
+  for (var i=0;i<12;i++){
+    ctx.beginPath();
+    ctx.rotate(Math.PI/6);
+    ctx.moveTo(100,0);
+    ctx.lineTo(120,0);
+    ctx.stroke();
+  }
+  ctx.restore();
+
+  // Minute marks
+  ctx.save();
+  ctx.lineWidth = 5;
+  for (i=0;i<60;i++){
+    if (i%5!=0) {
+      ctx.beginPath();
+      ctx.moveTo(117,0);
+      ctx.lineTo(120,0);
+      ctx.stroke();
+    }
+    ctx.rotate(Math.PI/30);
+  }
+  ctx.restore();
+
+  var sec = now.getSeconds();
+  var min = now.getMinutes();
+  var hr  = now.getHours();
+  hr = hr>=12 ? hr-12 : hr;
+
+  ctx.fillStyle = "black";
+
+  // write Hours
+  ctx.save();
+  ctx.rotate( hr*(Math.PI/6) + (Math.PI/360)*min + (Math.PI/21600)*sec )
+  ctx.lineWidth = 14;
+  ctx.beginPath();
+  ctx.moveTo(-20,0);
+  ctx.lineTo(80,0);
+  ctx.stroke();
+  ctx.restore();
+
+  // write Minutes
+  ctx.save();
+  ctx.rotate( (Math.PI/30)*min + (Math.PI/1800)*sec )
+  ctx.lineWidth = 10;
+  ctx.beginPath();
+  ctx.moveTo(-28,0);
+  ctx.lineTo(112,0);
+  ctx.stroke();
+  ctx.restore();
+
+  // Write seconds
+  ctx.save();
+  ctx.rotate(sec * Math.PI/30);
+  ctx.strokeStyle = "#D40000";
+  ctx.fillStyle = "#D40000";
+  ctx.lineWidth = 6;
+  ctx.beginPath();
+  ctx.moveTo(-30,0);
+  ctx.lineTo(83,0);
+  ctx.stroke();
+  ctx.beginPath();
+  ctx.arc(0,0,10,0,Math.PI*2,true);
+  ctx.fill();
+  ctx.beginPath();
+  ctx.arc(95,0,10,0,Math.PI*2,true);
+  ctx.stroke();
+  ctx.fillStyle = "rgba(0,0,0,0)";
+  ctx.arc(0,0,3,0,Math.PI*2,true);
+  ctx.fill();
+  ctx.restore();
+
+  ctx.beginPath();
+  ctx.lineWidth = 14;
+  ctx.strokeStyle = '#325FA2';
+  ctx.arc(0,0,142,0,Math.PI*2,true);
+  ctx.stroke();
+
+  ctx.restore();
+}
+ + + +

{{EmbedLiveSample("An_animated_clock", "180", "180", "https://mdn.mozillademos.org/files/203/Canvas_animation2.png")}}

+ +

Um panorama  em loop

+ +

Nesse exemplos, um panorama é rolado da esquerda pra direita. Nós estamos usando uma imagem do Parque Nacional de Yosemite que tiramos da Wikipedia, mas você pode usar qualquer imagem que fosse maior que a tela.

+ +
var img = new Image();
+
+// User Variables - customize these to change the image being scrolled, its
+// direction, and the speed.
+
+img.src = 'https://mdn.mozillademos.org/files/4553/Capitan_Meadows,_Yosemite_National_Park.jpg';
+var CanvasXSize = 800;
+var CanvasYSize = 200;
+var speed = 30; //lower is faster
+var scale = 1.05;
+var y = -4.5; //vertical offset
+
+// Main program
+
+var dx = 0.75;
+var imgW;
+var imgH;
+var x = 0;
+var clearX;
+var clearY;
+var ctx;
+
+img.onload = function() {
+    imgW = img.width*scale;
+    imgH = img.height*scale;
+    if (imgW > CanvasXSize) { x = CanvasXSize-imgW; } // image larger than canvas
+    if (imgW > CanvasXSize) { clearX = imgW; } // image larger than canvas
+    else { clearX = CanvasXSize; }
+    if (imgH > CanvasYSize) { clearY = imgH; } // image larger than canvas
+    else { clearY = CanvasYSize; }
+    //Get Canvas Element
+    ctx = document.getElementById('canvas').getContext('2d');
+    //Set Refresh Rate
+    return setInterval(draw, speed);
+}
+
+function draw() {
+    //Clear Canvas
+    ctx.clearRect(0,0,clearX,clearY);
+    //If image is <= Canvas Size
+    if (imgW <= CanvasXSize) {
+        //reset, start from beginning
+        if (x > (CanvasXSize)) { x = 0; }
+        //draw aditional image
+        if (x > (CanvasXSize-imgW)) { ctx.drawImage(img,x-CanvasXSize+1,y,imgW,imgH); }
+    }
+    //If image is > Canvas Size
+    else {
+        //reset, start from beginning
+        if (x > (CanvasXSize)) { x = CanvasXSize-imgW; }
+        //draw aditional image
+        if (x > (CanvasXSize-imgW)) { ctx.drawImage(img,x-imgW+1,y,imgW,imgH); }
+    }
+    //draw image
+    ctx.drawImage(img,x,y,imgW,imgH);
+    //amount to move
+    x += dx;
+}
+
+ +

Abaixo é o {{HTMLElement("canvas")}} em que a imagem é rolada. Note que a largura e a altura especificadas aqui devem corresponder aos valores das variáveis ​​CanvasXZSize e CanvasYSize no código JavaScript. 

+ +
<canvas id="canvas" width="800" height="200"></canvas>
+ +

Live sample

+ +

{{EmbedLiveSample("A_looping_panorama", "830", "230")}}

+ +

Outros exemplos

+ +
+
Gartic
+
Jogo de desenho para multiplayers.
+
Canvascape
+
Um jogo de aventura 3D (tiro em primeira pessoa).
+
A basic ray-caster
+
Um bom exemplo de como fazer animações usando os controles do teclado.
+
canvas adventure
+
Outro bom exemplo que usa controles de teclado.
+
An interactive Blob
+
Divirta-se com Blob.
+
Flying through a starfield
+
Voe através de estrelas, círculos ou quadrados.
+
iGrapher
+
Um exemplo que ilustra os dados do mercado de ações.
+
+ +

Veja também

+ + + +

{{PreviousNext("Web/Guide/HTML/Canvas_tutorial/Compositing", "Web/Guide/HTML/Canvas_tutorial/Optimizing_canvas")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/basic_usage/index.html b/files/pt-br/web/api/canvas_api/tutorial/basic_usage/index.html new file mode 100644 index 0000000000..767a5ff97c --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/basic_usage/index.html @@ -0,0 +1,153 @@ +--- +title: Utilização básica do Canvas +slug: Web/Guide/HTML/Canvas_tutorial/Utilizacao_basica +tags: + - Canvas + - HTML + - Intermediário + - Tutorial + - graficos +translation_of: Web/API/Canvas_API/Tutorial/Basic_usage +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial", "Web/API/Canvas_API/Tutorial/Drawing_shapes")}}
+ +
Vamos começar este tutorial olhando para o elemento {{HTMLElement("canvas")}} {{Glossary("HTML")}} em si. No final desta página, você saberá como configurar um contexto de canvas 2D e desenhar um primeiro exemplo em seu navegador.
+ +

O elemento <canvas>

+ +

Vamos começar esse tutorial olhando o elemento  {{HTMLElement("canvas")}} em si.

+ +
<canvas id="tutorial" width="150" height="150"></canvas>
+
+ +

Se parece muito com o elemento <img> com a diferença de não possuir os atributos src e alt. O elemento <canvas> tem apenas dois atributos - width e height. Ambos são opcionais e podem ser aplicados utilizando as propriedades DOM respectivas. Se não forem especificados, o canvas será iniciado com 300 pixels de largura por 150 pixels de altura. O elemento pode ser redimensionado por CSS, mas durante a renderização a imagem é escalonada para caber no tamanho do layout.

+ +
+

Nota: Se as suas renderizações parecerem distorcidas, tente especificar os atributos width e height no <canvas> e não usando CSS.

+
+ +

O atributo id não é específico do elemento <canvas> mas um dos atributos padrão do HTML que pode ser aplicado em (quase) todos os elementos HTML (como o class por exemplo). É sempre uma boa ideia inserir um id pois fica muito mais fácil de capturar o elemento no seu script.

+ +

O elemento <canvas> pode ser estilizado como qualquer imagem (margem, borda, fundo, etc). Contudo, essas regras não afetarão o desenho no canvas. Nós veremos como isso é feito a seguir nesse tutorial. Quando nenhuma regra de estilo for aplicada, o canvas iniciará totalmente transparente.

+ +
+

Conteúdo alternativo

+ +

Uma vez que alguns navegadores mais antigos (em particular, versões do Internet Explorer anteriores a 9) não suportam o elemento {{HTMLElement("canvas")}}, você precisará prover um conteúdo alternativo para ser mostrado nesses navegadores.

+ +

Isto é muito simples: basta inserir o conteúdo alternativo dentro do elemento <canvas>. Navegadores que não suportam o <canvas> irão renderizar o conteúdo alternativo. Já os navegadores que suportam <canvas> irão ignorar o conteúdo alternativo, renderizando o canvas normalmente.

+ +

Por exemplo, podemos prover um texto descritivo do canvas ou uma imagem estática do conteúdo. Algo como isto:

+ +
<canvas id="stockGraph" width="150" height="150">
+  preço das ações: $3.15 +0.15
+</canvas>
+
+<canvas id="clock" width="150" height="150">
+  <img src="images/clock.png" width="150" height="150" alt=""/>
+</canvas>
+
+ +

Tag </canvas> é necessária

+ +

Ao contrário do elemento {{HTMLElement("img")}}, o elemento {{HTMLElement("canvas")}} a tag de fechamento (</canvas>) é necessária.

+ +
+

Nota: Embora as primeiras versões do navegador Safari da Apple não exijam a tag de fechamento, a especificação indica que ela é necessária para que haja maior compatibilidade, portanto não se esqueça de incluí-la. Essas versões do Safari (antes da versão 2.0) irão processar o conteúdo do alternativo, além da própria tela, a menos que você use o CSS para mascará-lo. Felizmente, os usuários dessas versões do Safari são raros hoje em dia.

+
+ +

Se o conteúdo alternativo não for necessário, um simples <canvas id="foo" ...></canvas> é totalmente compatível com todos os navegadores que suportam canvas.

+ +

O contexto de renderização

+ +

{{HTMLElement("canvas")}} cria uma superfície de desenho de tamanho fixo que expõe um ou mais contextos de renderização, que são usados ​​para criar e manipular o conteúdo mostrado. Vamos nos concentrar no contexto de renderização 2D. Outros contextos podem fornecer diferentes tipos de renderização; por exemplo, WebGL usa um contexto 3D ("experimental-WebGL") baseado em OpenGL ES.

+ +

Incialmente o canvas é branco. Para mostrar alguma coisa, primeiro um script precisa acessar o contexto de renderização e desenhar sobre ele. O elemento {{HTMLElement("canvas")}} tem um método chamado getContext(), usado para obter o contexto de renderização e suas funções de desenho. getContext() recebe o tipo de contexto como parâmetro. Para gráficos 2D, que serão abrangidos nesse tutorial, deverá ser especificado "2d".

+ +
var canvas = document.getElementById('tutorial');
+var ctx = canvas.getContext('2d');
+
+ +

A primeira linha recupera o nó DOM do elemento {{HTMLElement ("canvas")}} chamando o método {{domxref ("document.getElementById()")}}. Depois de ter o nó do elemento, podemos acessar o contexto de desenho usando o método getContext().

+ +
+

Verificação de suporte

+ +

O conteúdo alternativo é mostrado nos navegadores que não suportam o elemento {{HTMLElement("canvas")}}, mas essa checagem pode ser feita através de um script simplesmente testando a presença do método getContext():

+ +
var canvas = document.getElementById('tutorial');
+
+if (canvas.getContext){
+  var ctx = canvas.getContext('2d');
+  // codigo de desenho aqui
+} else {
+  // codigo para quando o canvas nao for suportado aqui
+}
+
+
+
+ +

Um modelo de estrutura

+ +

Aqui, um modelo minimalista, que vamos usar como ponto de partida para os exemplos posteriores:

+ +
+

Nota: não é uma boa prática incorporar um script dentro do HTML. Nós fazemos isso aqui para manter o exemplo conciso.

+
+ +
<html>
+  <head>
+    <title>Canvas tutorial</title>
+    <script type="text/javascript">
+      function draw(){
+        var canvas = document.getElementById('tutorial');
+        if (canvas.getContext){
+          var ctx = canvas.getContext('2d');
+        }
+      }
+    </script>
+    <style type="text/css">
+      canvas { border: 1px solid black; }
+    </style>
+  </head>
+  <body onload="draw();">
+    <canvas id="tutorial" width="150" height="150"></canvas>
+  </body>
+</html>
+
+ +

O script inclui a função chamada draw(), que é executada uma vez ao término do carregamento da página; este exemplo usa o evento onload do documento. Essa função, ou uma parecida, poderia usar {{domxref("window.setTimeout()")}}, {{domxref("window.setInterval()")}}, ou qualquer outro manipulador de evento, contanto que a página tenha sido carregada primeiro.

+ +

{{EmbedLiveSample("Um_modelo_de_estrutura", 160, 160)}}

+ +

Um simples exemplo

+ +

Para começar, vamos dar uma olhada num exemplo simples que desenha a interseção de dois retângulos, dos quais um deles tem uma transparência. Exploraremos em mais detalhes o funcionamento nos exemplos posteriores.

+ +
<html>
+ <head>
+  <script type="application/javascript">
+    function draw() {
+      var canvas = document.getElementById("canvas");
+      if (canvas.getContext) {
+        var ctx = canvas.getContext("2d");
+
+        ctx.fillStyle = "rgb(200,0,0)";
+        ctx.fillRect (10, 10, 55, 50);
+
+        ctx.fillStyle = "rgba(0, 0, 200, 0.5)";
+        ctx.fillRect (30, 30, 55, 50);
+      }
+    }
+  </script>
+ </head>
+ <body onload="draw();">
+   <canvas id="canvas" width="150" height="150"></canvas>
+ </body>
+</html>
+ +

Este exemplo parece assim:

+ +

{{EmbedLiveSample("Um_simples_exemplo", 160, 160, "https://mdn.mozillademos.org/files/228/canvas_ex1.png")}}

+ +

{{PreviousNext("Web/Guide/HTML/Canvas_tutorial", "Web/Guide/HTML/Canvas_tutorial/Drawing_shapes")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/compositing/example/index.html b/files/pt-br/web/api/canvas_api/tutorial/compositing/example/index.html new file mode 100644 index 0000000000..87de5aa19d --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/compositing/example/index.html @@ -0,0 +1,294 @@ +--- +title: Exemplo de Composição +slug: Web/Guide/HTML/Canvas_tutorial/Compositing/Exemplo +tags: + - Canvas + - Example + - HTML5 + - Tutorial +translation_of: Web/API/Canvas_API/Tutorial/Compositing/Example +--- +
{{CanvasSidebar}}
+ +

Esse exemplo demonstra várias operações de composição. A saída se parece assim:

+ +

{{ EmbedLiveSample('Exemplo_de_composição', '', '7240px', '', 'Web/Guide/HTML/Canvas_tutorial/Compositing/Exemplo') }}

+ +

Exemplo de composição

+ +

Este código configura os valores globais usados pelo restante do programa.

+ +
var canvas1 = document.createElement("canvas");
+var canvas2 = document.createElement("canvas");
+var gco = [ 'Source-over','Source-in','Source-out','Source-atop',
+            'Destination-over','Destination-in','Destination-out','Destination-atop',
+            'Lighter', 'Copy','XOR', 'Multiply', 'Screen', 'Overlay', 'Darken',
+            'Lighten', 'Color-dodge', 'Color-burn', 'Hard-light', 'Soft-light',
+            'Difference', 'Exclusion', 'HUE', 'Saturation', 'Color', 'Luminosity'
+          ].reverse();
+var gcoText = [
+'Essa é a configuração padrão e desenha novas formas sobre o conteúdo da tela (canvas) existente.',
+'A nova forma é desenhada apenas onde a nova forma e a tela (canvas) de destino se sobrepõem. Todo o resto é transparente. ',
+'A nova forma é desenhada onde ela não sobrepõe o conteúdo da tela (canvas) existente.',
+'A nova forma é somente desenahda onde ela sobrepõe o conteúdo da tela (canvas) existente.',
+'Novas formas são desenhadas por trás do conteúdo da tela (canvas) existente.',
+'O conteúdo da tela (canvas) existente é mantido onde ambos, a nova forma e o conteúdo da tela (canvas) existente, se sobrepõe. Todo o resto é transparente.',
+'O conteúdo existente é mantido onde ele não sobrepõe a nova forma.',
+'A tela (canvas) existente só é mantida onde ela sobrepõe a nova forma. A nova forma é desenahda por trás do conteúdo canvas.',
+'Onde ambas formas se sebrepõem a cor é determinada adicionando seus respectivos valores de cores.',
+'Somente a nova forma é mostrada.',
+'Formas são feitas transparentes onde ambos se sobrepõem e todo o resto é desenhado normalmente.',
+'Os pixels da camada superior são multiplicados pelo pixel correspondente da camada inferior. Uma imagem mais escura é o resultado. ',
+'Os pixels são invertidos, multiplicados e invertidos novamente. Uma imagem mais clara é o resultado (oposto de multiplicar)',
+'Uma combinação de multiplicação e tela. As partes escuras na camada base tornam-se mais escuras e as partes claras tornam-se mais claras.',
+'Mantêm os pixels mais escuro de ambas camadas.',
+'Mantêm os pixels mais claro de ambas camadas.',
+'Divide a camada inferior pela camada superior invertida.',
+'Divide a camada inferior invertida pela camada superior e, em seguida, inverte o resultado.',
+'Uma combinação de multiplicação e tela como sobreposição, mas com a camada superior e inferior trocada.',
+'Uma versão mais suave da luz. Preto ou branco puro não resulta em preto ou branco puro.',
+'Subtrai a camada inferior da camada superior ou vice-versa para obter sempre um valor positivo.',
+'Como diferença, mas com menor contraste.',
+'Preserva o luma e o croma da camada inferior, enquanto adota a tonalidade da camada superior.',
+'Preserva o luma e a tonalidade da camada inferior, enquanto adota o croma da camada superior.',
+'Preserva a luma da camada inferior, enquanto adota a tonalidade e o croma da camada superior.',
+'Preserva a tonalidade e o croma da camada inferior, enquanto adota a luma da camada superior.'
+          ].reverse();
+var width = 320;
+var height = 340;
+ +

Programa principal

+ +

Quando a página é carregada, esse código é executado para configurar e executar o exemplo:

+ +
window.onload = function() {
+    // lum em sRGB
+    var lum = {
+        r: 0.33,
+        g: 0.33,
+        b: 0.33
+    };
+    // redimensiona canvas
+    canvas1.width = width;
+    canvas1.height = height;
+    canvas2.width = width;
+    canvas2.height = height;
+    lightMix();
+    colorSphere();
+    runComposite();
+    return;
+};
+
+ +

E esse código, runComposite (), manipula a maior parte do trabalho, contando com várias funções utilitárias para fazer as partes difíceis.

+ +
function createCanvas() {
+    var canvas = document.createElement("canvas");
+    canvas.style.background = "url("+op_8x8.data+")";
+    canvas.style.border = "1px solid #000";
+    canvas.style.margin = "5px";
+    canvas.width = width/2;
+    canvas.height = height/2;
+    return canvas;
+}
+
+function runComposite() {
+    var dl = document.createElement("dl");
+    document.body.appendChild(dl);
+    while(gco.length) {
+        var pop = gco.pop();
+        var dt = document.createElement("dt");
+        dt.textContent = pop;
+        dl.appendChild(dt);
+        var dd = document.createElement("dd");
+        var p = document.createElement("p");
+        p.textContent = gcoText.pop();
+        dd.appendChild(p);
+
+        var canvasToDrawOn = createCanvas();
+        var canvasToDrawFrom = createCanvas();
+        var canvasToDrawResult = createCanvas();
+
+        var ctx = canvasToDrawResult.getContext('2d');
+        ctx.clearRect(0, 0, width, height)
+        ctx.save();
+        ctx.drawImage(canvas1, 0, 0, width/2, height/2);
+        ctx.globalCompositeOperation = pop;
+        ctx.drawImage(canvas2, 0, 0, width/2, height/2);
+        ctx.globalCompositeOperation = "source-over";
+        ctx.fillStyle = "rgba(0,0,0,0.8)";
+        ctx.fillRect(0, height/2 - 20, width/2, 20);
+        ctx.fillStyle = "#FFF";
+        ctx.font = "14px arial";
+        ctx.fillText(pop, 5, height/2 - 5);
+        ctx.restore();
+
+        var ctx = canvasToDrawOn.getContext('2d');
+        ctx.clearRect(0, 0, width, height)
+        ctx.save();
+        ctx.drawImage(canvas1, 0, 0, width/2, height/2);
+        ctx.fillStyle = "rgba(0,0,0,0.8)";
+        ctx.fillRect(0, height/2 - 20, width/2, 20);
+        ctx.fillStyle = "#FFF";
+        ctx.font = "14px arial";
+        ctx.fillText('Conteúdo existente', 5, height/2 - 5);
+        ctx.restore();
+
+        var ctx = canvasToDrawFrom.getContext('2d');
+        ctx.clearRect(0, 0, width, height)
+        ctx.save();
+        ctx.drawImage(canvas2, 0, 0, width/2, height/2);
+        ctx.fillStyle = "rgba(0,0,0,0.8)";
+        ctx.fillRect(0, height/2 - 20, width/2, 20);
+        ctx.fillStyle = "#FFF";
+        ctx.font = "14px arial";
+        ctx.fillText('Novo conteúdo', 5, height/2 - 5);
+        ctx.restore();
+
+        dd.appendChild(canvasToDrawOn);
+        dd.appendChild(canvasToDrawFrom);
+        dd.appendChild(canvasToDrawResult);
+
+        dl.appendChild(dd);
+    }
+};
+
+ +

Funções Utilitárias

+ +

O programa depende de várias funções utilitárias.

+ +
var lightMix = function() {
+    var ctx = canvas2.getContext("2d");
+    ctx.save();
+    ctx.globalCompositeOperation = "lighter";
+    ctx.beginPath();
+    ctx.fillStyle = "rgba(255,0,0,1)";
+    ctx.arc(100, 200, 100, Math.PI*2, 0, false);
+    ctx.fill()
+    ctx.beginPath();
+    ctx.fillStyle = "rgba(0,0,255,1)";
+    ctx.arc(220, 200, 100, Math.PI*2, 0, false);
+    ctx.fill()
+    ctx.beginPath();
+    ctx.fillStyle = "rgba(0,255,0,1)";
+    ctx.arc(160, 100, 100, Math.PI*2, 0, false);
+    ctx.fill();
+    ctx.restore();
+    ctx.beginPath();
+    ctx.fillStyle = "#f00";
+    ctx.fillRect(0,0,30,30)
+    ctx.fill();
+};
+
+ +
var colorSphere = function(element) {
+    var ctx = canvas1.getContext("2d");
+    var width = 360;
+    var halfWidth = width / 2;
+    var rotate = (1 / 360) * Math.PI * 2; // per degree
+    var offset = 0; // scrollbar offset
+    var oleft = -20;
+    var otop = -20;
+    for (var n = 0; n <= 359; n ++) {
+        var gradient = ctx.createLinearGradient(oleft + halfWidth, otop, oleft + halfWidth, otop + halfWidth);
+        var color = Color.HSV_RGB({ H: (n + 300) % 360, S: 100, V: 100 });
+        gradient.addColorStop(0, "rgba(0,0,0,0)");
+        gradient.addColorStop(0.7, "rgba("+color.R+","+color.G+","+color.B+",1)");
+        gradient.addColorStop(1, "rgba(255,255,255,1)");
+        ctx.beginPath();
+        ctx.moveTo(oleft + halfWidth, otop);
+        ctx.lineTo(oleft + halfWidth, otop + halfWidth);
+        ctx.lineTo(oleft + halfWidth + 6, otop);
+        ctx.fillStyle = gradient;
+        ctx.fill();
+        ctx.translate(oleft + halfWidth, otop + halfWidth);
+        ctx.rotate(rotate);
+        ctx.translate(-(oleft + halfWidth), -(otop + halfWidth));
+    }
+    ctx.beginPath();
+    ctx.fillStyle = "#00f";
+    ctx.fillRect(15,15,30,30)
+    ctx.fill();
+    return ctx.canvas;
+};
+
+ +
// HSV (1978) = H: Hue (tom)
+//              S: Saturation (Saturação)
+//              V: Value (Valor)
+Color = {};
+Color.HSV_RGB = function (o) {
+    var H = o.H / 360,
+        S = o.S / 100,
+        V = o.V / 100,
+        R, G, B;
+    var A, B, C, D;
+    if (S == 0) {
+        R = G = B = Math.round(V * 255);
+    } else {
+        if (H >= 1) H = 0;
+        H = 6 * H;
+        D = H - Math.floor(H);
+        A = Math.round(255 * V * (1 - S));
+        B = Math.round(255 * V * (1 - (S * D)));
+        C = Math.round(255 * V * (1 - (S * (1 - D))));
+        V = Math.round(255 * V);
+        switch (Math.floor(H)) {
+            case 0:
+                R = V;
+                G = C;
+                B = A;
+                break;
+            case 1:
+                R = B;
+                G = V;
+                B = A;
+                break;
+            case 2:
+                R = A;
+                G = V;
+                B = C;
+                break;
+            case 3:
+                R = A;
+                G = B;
+                B = V;
+                break;
+            case 4:
+                R = C;
+                G = A;
+                B = V;
+                break;
+            case 5:
+                R = V;
+                G = A;
+                B = B;
+                break;
+        }
+    }
+    return {
+        R: R,
+        G: G,
+        B: B
+    };
+};
+
+var createInterlace = function (size, color1, color2) {
+    var proto = document.createElement("canvas").getContext("2d");
+    proto.canvas.width = size * 2;
+    proto.canvas.height = size * 2;
+    proto.fillStyle = color1; // top-left
+    proto.fillRect(0, 0, size, size);
+    proto.fillStyle = color2; // top-right
+    proto.fillRect(size, 0, size, size);
+    proto.fillStyle = color2; // bottom-left
+    proto.fillRect(0, size, size, size);
+    proto.fillStyle = color1; // bottom-right
+    proto.fillRect(size, size, size, size);
+    var pattern = proto.createPattern(proto.canvas, "repeat");
+    pattern.data = proto.canvas.toDataURL();
+    return pattern;
+};
+
+var op_8x8 = createInterlace(8, "#FFF", "#eee");
diff --git a/files/pt-br/web/api/canvas_api/tutorial/compositing/index.html b/files/pt-br/web/api/canvas_api/tutorial/compositing/index.html new file mode 100644 index 0000000000..6d9ff5c33d --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/compositing/index.html @@ -0,0 +1,112 @@ +--- +title: Compositing and clipping +slug: Web/Guide/HTML/Canvas_tutorial/Compositing +translation_of: Web/API/Canvas_API/Tutorial/Compositing +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Transformations", "Web/API/Canvas_API/Tutorial/Basic_animations")}}
+ +
+

Em todo os nossos exemplos prévios, formas estavam sempre desenhadas uma em cima das outras. Este é mais do que adequado para a maioria das situações, mas é limita a ordem no qual a composição das formas são construídas.

+ +

Nós podemos, no entanto, mudar este comportamento por configurar a propriedade globalCompositeOperation. Além disto, a propriedade clipe permite-nos esconder indesejáveis partes da forma.

+
+ +

globalCompositeOperation

+ +

Nós podemos somente desenhar novas formas atrás das existentes formas mas nós podemos também usar isto para mascarar certas áreas, limpar seções do canvas(não limitado para retângulos como o {{domxref("CanvasRenderingContext2D.clearRect", "clearRect()")}} métodos faz) e mais.

+ +
+
{{domxref("CanvasRenderingContext2D.globalCompositeOperation", "globalCompositeOperation = type")}}
+
Este conjunto de operações compostas para aplicar quando desenha novas formas, onde type é uma string identificando quais das 12 operações compostas usar.
+
+ +

Veja os seguintes exemplos de composição para o código dos seguintes exemplos.

+ +

{{ EmbedLiveSample('Exemplo_de_composição', '', '', '', 'Web/Guide/HTML/Canvas_tutorial/Compositing/Exemplo') }}

+ +

Caminhos de recorte (Clipping path)

+ +

Um caminho de recorte (Clipping path) é como uma forma normal canvas mas isto age como uma máscara para esconder indesejáveis partes de formas. Isto é visualizado na imagem na direita. A forma da estrela vermelha é nosso caminho de recorte. Tudo que cai do lado de fora deste caminho não sai desenhado no canvas.

+ +

Se nós compararmos caminho de recorte para a propriedade globalCompositeOperation nós temos visto acima, nós veremos dois modelos de composição que alcança mais ou menos o mesmo efeito no source-in e source-atop. A mais importante diferença entre os dois é que o caminho de recorte nunca desenha algo na tela e o caminho de recorte nunca afeta por adicionar novas formas. Isto faz o caminho do recorte ideal para desenhar múltiplos na área restrita.

+ +

No capítulo sobre formas de desenho (drawing shapes) eu somente mencionei os métodos stroke() e fill(), mas há um método que nós podemos usar com caminhos chamado clip().

+ +
+
{{domxref("CanvasRenderingContext2D.clip", "clip()")}}
+
Volta o caminho atualmente sendo construído no caminho de recorte atual.
+
+ +

Você usou clip() em vez de closePath() para fechar um caminho e voltar para dentro de um caminho de recorte em vez de contornar (stroking) ou completar (filling) o caminho.

+ +

Por padrão o elemento {{HTMLElement("canvas")}} tem um caminho de recorte que é exatamente o mesmo tamanho do canvas em si. Em outras palavras, nenhum recorte ocorreu.

+ +

Um exemplo do recorte

+ +

Neste exemplo, Nós usaremos um recorte circular para restringir o desenho do conjunto de inícios randômicos para uma região particular

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  ctx.fillRect(0, 0, 150, 150);
+  ctx.translate(75, 75);
+
+  // Create a circular clipping path
+  ctx.beginPath();
+  ctx.arc(0, 0, 60, 0, Math.PI * 2, true);
+  ctx.clip();
+
+  // draw background
+  var lingrad = ctx.createLinearGradient(0, -75, 0, 75);
+  lingrad.addColorStop(0, '#232256');
+  lingrad.addColorStop(1, '#143778');
+
+  ctx.fillStyle = lingrad;
+  ctx.fillRect(-75, -75, 150, 150);
+
+  // draw stars
+  for (var j = 1; j < 50; j++) {
+    ctx.save();
+    ctx.fillStyle = '#fff';
+    ctx.translate(75 - Math.floor(Math.random() * 150),
+                  75 - Math.floor(Math.random() * 150));
+    drawStar(ctx, Math.floor(Math.random() * 4) + 2);
+    ctx.restore();
+  }
+
+}
+
+function drawStar(ctx, r) {
+  ctx.save();
+  ctx.beginPath();
+  ctx.moveTo(r, 0);
+  for (var i = 0; i < 9; i++) {
+    ctx.rotate(Math.PI / 5);
+    if (i % 2 === 0) {
+      ctx.lineTo((r / 0.525731) * 0.200811, 0);
+    } else {
+      ctx.lineTo(r, 0);
+    }
+  }
+  ctx.closePath();
+  ctx.fill();
+  ctx.restore();
+}
+
+ + + +

Nas primeiras linhas de código, nós desenhamos um retângulo negro do tamanho do canvas como um pano de fundo, então traduzido da origem para o centro. Próximo, nós criamos o recorte circular do caminho recortado para desenhar um arco e chamá-lo clip(). Caminho de recortes são também parte do canvas com estado salvo. Se nós procuramos guardar o caminho do recorte original nós podemos ter salvo o estado do canvas antes de criar mais um.

+ +

Tudo que for desenhado depois de criado o caminho de recorte somente aparecerá dentro daquele caminho. Você pode ver isto claramente no gradiente linear que está desenhado adiante. Depois deste conjunto de de 50 randomicamente posicionadas e escaladas estrelas for desenhada. Usando a função customizada drawStar(). De novo as estrelas somente aparecerão dentro do caminho de recorte definido.

+ +

Um exemplo de recorte:

+ +

+ +

{{EmbedLiveSample("A_clip_example", "180", "180", "https://mdn.mozillademos.org/files/208/Canvas_clip.png")}}

+ +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Transformations", "Web/API/Canvas_API/Tutorial/Basic_animations")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/drawing_shapes/index.html b/files/pt-br/web/api/canvas_api/tutorial/drawing_shapes/index.html new file mode 100644 index 0000000000..f54fca780e --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/drawing_shapes/index.html @@ -0,0 +1,581 @@ +--- +title: Desenhando formas com canvas +slug: Web/Guide/HTML/Canvas_tutorial/Drawing_shapes +tags: + - Canvas + - Gráficos(2) + - HTML + - HTML Canvas + - HTML5 + - Intermediário + - Tutorial +translation_of: Web/API/Canvas_API/Tutorial/Drawing_shapes +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_usage", "Web/API/Canvas_API/Tutorial/Applying_styles_and_colors")}}
+ +
+

Agora que criamos nosso ambiente em canvas, podemos entrar nos detalhes de como desenhar no canvas. No final deste artigo, você terá aprendido a desenhar retângulos, triângulos, linhas, arcos e curvas, proporcionando familiaridade com algumas das formas básicas. Trabalhar com caminhos (shapes) é essencial ao desenhar objetos na tela e veremos como isso pode ser feito.

+
+ +

A grade

+ +

Antes que possamos começar a desenhar, precisamos falar sobre a grade de tela ou espaço de coordenadas. O modelo HTML na página anterior tinha um elemento canvas de 150 pixels de largura e 150 pixels de altura. À direita, você verá este canvas com a grade padrão sobreposta. Normalmente 1 unidade na grade corresponde a um pixel na tela. A origem desta grade está posicionada no canto superior esquerdo (coordenadas (0,0)). Todos os elementos são colocados em relação a esta origem. Assim, a posição do canto superior esquerdo do quadrado azul, se torna x pixels dos pixels da esquerda e y a partir do topo (coordenadas (x,y)). Mais tarde nesse tutorial vamos ver como podemos traduzir a origem para uma posição diferente, girar a grade e até mesmo escaloná-la. Por enquanto vamos ficar com o padrão.

+ +

Desenhando retângulos

+ +

Diferente do {{Glossary("SVG")}} , o {{HTMLElement("canvas")}} suporta somente formas primitivas: retângulos. Todas as outras formas são criadas a partir da combinação de um ou mais caminhos (paths), lista de pontos conectados por uma linha. Felizmente, temos uma variedade de funções de desenho que tornam possíveis criar formas muito complexas.

+ +

Primeiramente vamos olhar o retângulo. Aqui está listado três funções para desenhar retângulos pelo canvas:

+ +
+
{{domxref("CanvasRenderingContext2D.fillRect", "fillRect(x, y, width, height)")}}
+
Desenha um retângulo preenchido.
+
{{domxref("CanvasRenderingContext2D.strokeRect", "strokeRect(x, y, width, height)")}}
+
Desenha a borda do retângulo.
+
{{domxref("CanvasRenderingContext2D.clearRect", "clearRect(x, y, width, height)")}}
+
Limpa um retângulo específico, tornando-o totalmente transparente.
+
+ +

Cada umas das funções recebem os mesmos parâmetros. x e y determinam a posição no canvas (em relação a origem) no canto superior esquerdo do retângulo. O width (largura) e o height (altura) definem o tamanho do retângulo.

+ +

Abaixo esta listado a função draw() da página anterior, porém utilizando as três funções.

+ +

Exemplo de forma retangular

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext) {
+    var ctx = canvas.getContext('2d');
+
+    ctx.fillRect(25, 25, 100, 100);
+    ctx.clearRect(45, 45, 60, 60);
+    ctx.strokeRect(50, 50, 50, 50);
+  }
+}
+ +

O resultado desse exemplo é mostrado abaixo.

+ +

{{EmbedLiveSample('Exemplo_de_forma_retangular', 160, 160, "https://mdn.mozillademos.org/files/245/Canvas_rect.png")}}

+ +

A função fillRect() desenha um grande quadrado preto de 100 pixels. A função clearRect() por sua vez apaga um quadrado de 60x60 pixels a partir do centro, por fim, a função strokeRect() é chamada para criar uma borda de 50x50 pixels em volta do quadrado apagado.

+ +

Posteriormente veremos duas alternativas à função clearRect(), nós também aprenderemos como alterar a cor e o estilo das linhas nas camadas renderizadas.

+ +

Ao contrário das funções de paths que veremos na próxima seção, todas as três funções de retângulo desenham imediatamente no canvas.

+ +

Desenhando caminhos/regiões (paths)

+ +

Para criar uma camada usando caminhos (regiões ou paths) é necessário alguns passos extras. Primeiro, cria-se a região de desenho. Depois usa-se comandos de desenho para desenhar nesta região. Por fim, você limita a região (path). Uma vez que a região de desenho está criada, você pode traçar ou preencher o caminho para que seja renderizado. Aqui estão as funções utilizadas para isso:

+ +
+
{{domxref("CanvasRenderingContext2D.beginPath", "beginPath()")}}
+
Cria um novo path. Uma vez criado, futuros comandos de desenho são direcionados do path atual para a construção de um novo path no canvas.
+
+ +
+
Métodos de Caminhos (Path)
+
Métodos para manipuliar diferentes paths para objetos.
+
+ +
+
{{domxref("CanvasRenderingContext2D.closePath", "closePath()")}}
+
Finaliza o path para futuros comandos de desenho, fazendo com que voltem a ser direcionados ao contexto.
+
{{domxref("CanvasRenderingContext2D.stroke", "stroke()")}}
+
Desenha uma borda na camada.
+
{{domxref("CanvasRenderingContext2D.fill", "fill()")}}
+
Desenha uma forma sólida através de preenchimento.
+
+ +

O primeiro passo para criar um caminho é chamar o beginPath(). Internamente, caminhos são armazenados como uma lista de sub-caminhos (linhas, arcos, etc.) que juntos formam uma forma (shape). Sempre que esse método é chamado, a lista é redefinida e podemos começar a desenhar novas formas.

+ +
Nota: Quando o caminho atual está vazio, assim como imediatamente depois de chamar beginPath(), ou em uma tela recém-criada, o primeiro comando de construção de caminho é sempre tratado como um moveTo(), independentemente do que ele seja realmente. Por essa razão, você quase sempre vai precisar definir especificamente sua posição inicial após redefinir um caminho.
+ +

A segunda etapa é chamar os métodos que realmente especificam os caminhos a serem desenhados. Vamos ver isso em breve.

+ +


+ O terceiro, e um passo opcional, é chamar closePath(). Este método tenta fechar a forma desenhando uma linha reta do ponto atual para o início. Se a forma (shape) já foi fechada ou existe apenas um ponto na lista, esta função não faz nada.

+ +
Nota: Quando você chama fill(), todas as formas abertas são fechadas automaticamente, assim você não precisa chamar closePath(). Isso não acontece quando você chamar stroke().
+ +

Desenhando um triângulo

+ +

Por exemplo, o código para desenhar um triângulo seria algo parecido com isto:

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext){
+    var ctx = canvas.getContext('2d');
+
+    ctx.beginPath();
+    ctx.moveTo(75,50);
+    ctx.lineTo(100,75);
+    ctx.lineTo(100,25);
+    ctx.fill();
+  }
+}
+
+ +

O resultado se parece com isso:

+ +

{{EmbedLiveSample('Desenhando_um_triângulo', 160, 160, "https://mdn.mozillademos.org/files/9847/triangle.png")}}

+ +

Desenhando

+ +

Uma função muito útil, que na verdade não desenha nada, mas torna-se parte da lista de caminhos descritos acima, é a função moveTo(). Você provavelmente pode imaginar melhor isso como se fosse o levantar uma caneta ou lápis de um ponto em um pedaço de papel e colocá-lo no próximo ponto.

+ +
+
{{domxref("CanvasRenderingContext2D.moveTo", "moveTo(x, y)")}}
+
Move a caneta (pen) para as coordenadas especificadas por x e y.
+
+ +

Quando o canvas é inicializado ou beginPath() é chamado, você normalmente vai querer usar a função moveTo() para colocar o ponto inicial em outro lugar. Poderíamos também usar moveTo() para desenhar caminhos não conectados. Dê uma olhada no rosto sorridente abaixo. Eu marquei os lugares onde eu usei o método moveTo() (as linhas vermelhas).

+ +

Caso queira tentar fazer isso, você pode usar o snippet de código abaixo. Basta colá-lo na função draw() que vimos anteriormente.

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext) {
+    var ctx = canvas.getContext('2d');
+
+    ctx.beginPath();
+    ctx.arc(75, 75, 50, 0, Math.PI * 2, true); // Círculo exterior
+    ctx.moveTo(110, 75);
+    ctx.arc(75, 75, 35, 0, Math.PI, false);  // Boca (sentido horário)
+    ctx.moveTo(65, 65);
+    ctx.arc(60, 65, 5, 0, Math.PI * 2, true);  // Olho esquerdo
+    ctx.moveTo(95, 65);
+    ctx.arc(90, 65, 5, 0, Math.PI * 2, true);  // Olho direito
+    ctx.stroke();
+  }
+}
+
+ +

O resultado aparece como:

+ +

{{EmbedLiveSample("Desenhando", 160, 160, "https://mdn.mozillademos.org/files/252/Canvas_smiley.png")}}

+ +

Se você não gosta de ver linhas conectadas, você pode remover as linhas que chamam a função moveTo().

+ +
+

Nota: Para aprender mais sobre a função arc(), veja sobre {{anch("Arcos")}}.

+
+ +

Linhas

+ +

Para desenhar linhas retas, use o método lineTo().

+ +
+
{{domxref("CanvasRenderingContext2D.lineTo", "lineTo(x, y)")}}
+
Desenha uma linha do ponto atual a até a posição especificada por x e y.
+
+ +

Esse método recebe dois argumentos, x e y, que são as coordenadas do ponto final da linha. O ponto inicial é dependente de caminhos previamente desenhados, onde o ponto final do caminho anterior é o ponto inicial para o seguinte, e assim por diante. O ponto inicial também pode ser alterado usando o método moveTo().
+
+ O exemplo abaixo desenha dois triângulos, um preenchido e um delineado.

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext){
+    var ctx = canvas.getContext('2d');
+
+    // Filled triangle
+    ctx.beginPath();
+    ctx.moveTo(25,25);
+    ctx.lineTo(105,25);
+    ctx.lineTo(25,105);
+    ctx.fill();
+
+    // Stroked triangle
+    ctx.beginPath();
+    ctx.moveTo(125,125);
+    ctx.lineTo(125,45);
+    ctx.lineTo(45,125);
+    ctx.closePath();
+    ctx.stroke();
+  }
+}
+
+ +

Isso começa chamando o método beginPath() para iniciar um novo shape path. Em seguida, usamos o método moveTo() para mover o ponto inicial para a posição desejada. Logo abaixo, duas linhas, que compõem os dois lados do triângulo, são desenhadas.

+ +

{{EmbedLiveSample("Linhas", 160, 160, "https://mdn.mozillademos.org/files/238/Canvas_lineTo.png")}}

+ +

Você notará a diferença entre o triângulo preenchido (filled) e não prenchido (stroked). Isto ocorre, como mencionado acima, porque as formas são automaticamente fechadas quando um caminho é preenchido, mas não quando são não preenchidos. Se deixássemos de fora o closePath() para os triângulos não preenchidos, apenas duas linhas teriam sido desenhadas, não um triângulo completo.

+ +

Arcos

+ +

Para desenhar arcos, nós usamos os métodos arc() ou arcTo().

+ +
+
{{domxref("CanvasRenderingContext2D.arc", "arc(x, y, radius, startAngle, endAngle, anticlockwise)")}}
+
Desenha um arco centralizado na posição (x, y) com um raio r iniciando em startAngle e terminando em endAngle apontando na direção indicada pelo sentido anti-horário (padronizando para o sentido horário).
+
{{domxref("CanvasRenderingContext2D.arcTo", "arcTo(x1, y1, x2, y2, radius)")}}
+
Desenha um arco com os pontos de controle e raio, conectados ao ponto anterior por uma linha reta.
+
+ +

Vamos dar uma olhada mais detalhada sobre o método arc, que tem seis parâmetros: x e y são as coordenadas do centro do círculo em que o arco deve ser desenhado. radius é o raio. Os parâmetros startAngle e endAngle definem os pontos inicial e final do arco em radianos, ao longo da curva do círculo. Estes são medidos a partir do eixo x. O parâmetro anticlockwise é um valor Booleano que, quando verdadeiro, desenha o arco no sentido anti-horário; Caso contrário, o arco é desenhado no sentido horário.

+ +
+

Nota: Os ângulos na função arc são medidos em radianos, não em graus. Para converter graus em radianos você pode usar a seguinte expressão JavaScript: radians = (Math.PI/180)*degrees.

+
+ +

O exemplo a seguir é um pouco mais complexo do que os que vimos anteriormente. Ele desenha 12 arcos diferentes, todos com diferentes ângulos e preenchimentos.

+ +

Os dois laços for são para iterar através das linhas e colunas de arcos. Para cada arco, é criado um novo caminho chamando beginPath(). No código, cada um dos parâmetros para o arco estão em uma variável somente para demonstração, assim você não precisa fazer isso na vida real.

+ +

As coordenadas x e y devem ser suficientemente claras. O parâmetros radius e startAngle são fixos. O endAngle começa em 180 graus (metade de um círculo) na primeira coluna e aumenta gradualmente em 90 graus, culminando em um círculo completo na última coluna.

+ +

A manipulação do parâmetro clockwise faz com que a primeira e terceira linhas sejam desenhadas como arcos no sentido horário, e a segunda e quarta linhas como arcos no sentido anti-horário. Finalmente, a instrução if faz com que a metade superior dos arcos não sejam preenchidos e a metade inferior dos arcos sejam.

+ +
+

Note: Este exemplo requer um canvas um pouco maior que as outras desta página: 150 x 200 pixels.

+
+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext){
+    var ctx = canvas.getContext('2d');
+
+    for(var i=0;i<4;i++){
+      for(var j=0;j<3;j++){
+        ctx.beginPath();
+        var x              = 25+j*50;               // coordenada x
+        var y              = 25+i*50;               // coordenada y
+        var radius         = 20;                    // Raio do Arco
+        var startAngle     = 0;                     // Ponto inicial no círculo
+        var endAngle       = Math.PI+(Math.PI*j)/2; // Ponto final no círculo
+        var anticlockwise  = i%2==0 ? false : true; // horário ou anti-horário
+
+        ctx.arc(x, y, radius, startAngle, endAngle, anticlockwise);
+
+        if (i>1){
+          ctx.fill();
+        } else {
+          ctx.stroke();
+        }
+      }
+    }
+  }
+}
+
+ +

{{EmbedLiveSample("Arcos", 160, 210, "https://mdn.mozillademos.org/files/204/Canvas_arc.png")}}

+ +

Curvas de Bézier Cúbicas e Quadráticas

+ +

O próximo tipo de caminhos disponíveis são as Curvas de Bézier, disponíveis nas variedades cubícas e quadráticas. Elas são geralmente usadas para desenhar complexas formas orgânicas.

+ +
+
{{domxref("CanvasRenderingContext2D.quadraticCurveTo", "quadraticCurveTo(cp1x, cp1y, x, y)")}}
+
Desenha uma curva de Bézier quadrática da posição atual indicada pelo cursor, até a posição final especificada por x e y, usando o controle de pontos guiados por cp1x e cp1y.
+
{{domxref("CanvasRenderingContext2D.bezierCurveTo", "bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)")}}
+
Desenha uma curva de Bézier cúbica partindo da posição atual indicada pelo cursor, até a posição final especificada por x e y, usando o controle de pontos guiados por (cp1x, cp1y) e (cp2x, cp2y).
+
+ +

A diferença entre estes métodos pode ser descrita de forma melhor usando a imagem à direita. Uma curva quadrática de Bézier tem um ponto inicial e final (pontos azuis) e apenas um ponto de controle (indicado pelo ponto vermelho) enquanto que uma curva cúbica de Bézier utiliza dois pontos de controles.

+ +

Os parâmetros x e y em ambos os métodos são as coordenadas do ponto final. cp1x e cp1y são as coordenadas do primeiro ponto de controle, e cp2x e cp2y são as coordenadas do segundo ponto de controle.

+ +

Usando curvas de Bézier quadráticas e cúbicas pode ser algo bastante desafiador, porque ao contrário de um software de desenho vetorial, como o Adobe Illustrator, não temos resultados visuais imediatos sobre o que estamos fazendo. Isso torna bastante difícil desenhar formas complexas. No exemplo a seguir, vamos desenhar algumas formas orgânicas simples, mas se você tiver tempo e, acima de tudo, paciência, formas muito mais complexas podem ser criadas.

+ +

Não há nada muito difícil nestes exemplos. Em ambos os casos vemos uma sucessão de curvas sendo desenhadas, resultando no fim, em uma forma (shape) completa.

+ +

Curvas de Bézier Quadráticas

+ +

Este exemplo usa múltiplas curvas de Bézier quadráticas para renderizar um balão de fala.

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext) {
+    var ctx = canvas.getContext('2d');
+
+    // Exemplo de curvas de Bézier quadráticas
+    ctx.beginPath();
+    ctx.moveTo(75,25);
+    ctx.quadraticCurveTo(25,25,25,62.5);
+    ctx.quadraticCurveTo(25,100,50,100);
+    ctx.quadraticCurveTo(50,120,30,125);
+    ctx.quadraticCurveTo(60,120,65,100);
+    ctx.quadraticCurveTo(125,100,125,62.5);
+    ctx.quadraticCurveTo(125,25,75,25);
+    ctx.stroke();
+  }
+}
+
+ +

{{EmbedLiveSample('Curvas_de_Bézier_Quadráticas', 160, 160, "https://mdn.mozillademos.org/files/243/Canvas_quadratic.png")}}

+ +

Curvas de Bézier Cúbicas

+ +

Este exemplo desenha um coração usando curvas de Bézier cúbicas.

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext){
+    var ctx = canvas.getContext('2d');
+
+    // Exemplo de curvas de Bézier cúbicas
+    ctx.beginPath();
+    ctx.moveTo(75,40);
+    ctx.bezierCurveTo(75,37,70,25,50,25);
+    ctx.bezierCurveTo(20,25,20,62.5,20,62.5);
+    ctx.bezierCurveTo(20,80,40,102,75,120);
+    ctx.bezierCurveTo(110,102,130,80,130,62.5);
+    ctx.bezierCurveTo(130,62.5,130,25,100,25);
+    ctx.bezierCurveTo(85,25,75,37,75,40);
+    ctx.fill();
+  }
+}
+
+ +

{{EmbedLiveSample('Curvas_de_Bézier_Cúbicas', 160, 160, "https://mdn.mozillademos.org/files/207/Canvas_bezier.png")}}

+ +

Retângulos

+ +

Além dos três métodos que vimos em {{anch("Desenhando retângulos")}}, que desenham formas retangulares diretamente no canvas, há também o método rect(), que adiciona uma forma retangular a um caminho (path) atualmente aberto.

+ +
+
{{domxref("CanvasRenderingContext2D.rect", "rect(x, y, width, height)")}}
+
+

Desenha um retângulo cujo canto superior esquerdo é especificado por (x, y) com base em uma largura (width) e uma altura (height).

+
+
+ +

Quando este método é executado, o método moveTo() é automaticamente chamado com os parâmetros (0,0). Em outras palavras, a posição atual do cursor é automaticamente redefinida para as coordenadas padrões.

+ +

Combinando Elementos

+ +

Até agora, em cada exemplo dessa página foi usada apenas um tipo de função de caminho (path) para cada forma (shape). No entanto, não há nenhuma limitação para o número ou tipos de caminhos que você pode usar para criar um shape. Então, neste exemplo final, vamos combinar todas as funções de caminho para fazer um conjunto de personagens de jogo muito conhecido.

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext){
+    var ctx = canvas.getContext('2d');
+
+    roundedRect(ctx,12,12,150,150,15);
+    roundedRect(ctx,19,19,150,150,9);
+    roundedRect(ctx,53,53,49,33,10);
+    roundedRect(ctx,53,119,49,16,6);
+    roundedRect(ctx,135,53,49,33,10);
+    roundedRect(ctx,135,119,25,49,10);
+
+    ctx.beginPath();
+    ctx.arc(37,37,13,Math.PI/7,-Math.PI/7,false);
+    ctx.lineTo(31,37);
+    ctx.fill();
+
+    for(var i=0;i<8;i++){
+      ctx.fillRect(51+i*16,35,4,4);
+    }
+
+    for(i=0;i<6;i++){
+      ctx.fillRect(115,51+i*16,4,4);
+    }
+
+    for(i=0;i<8;i++){
+      ctx.fillRect(51+i*16,99,4,4);
+    }
+
+    ctx.beginPath();
+    ctx.moveTo(83,116);
+    ctx.lineTo(83,102);
+    ctx.bezierCurveTo(83,94,89,88,97,88);
+    ctx.bezierCurveTo(105,88,111,94,111,102);
+    ctx.lineTo(111,116);
+    ctx.lineTo(106.333,111.333);
+    ctx.lineTo(101.666,116);
+    ctx.lineTo(97,111.333);
+    ctx.lineTo(92.333,116);
+    ctx.lineTo(87.666,111.333);
+    ctx.lineTo(83,116);
+    ctx.fill();
+
+    ctx.fillStyle = "white";
+    ctx.beginPath();
+    ctx.moveTo(91,96);
+    ctx.bezierCurveTo(88,96,87,99,87,101);
+    ctx.bezierCurveTo(87,103,88,106,91,106);
+    ctx.bezierCurveTo(94,106,95,103,95,101);
+    ctx.bezierCurveTo(95,99,94,96,91,96);
+    ctx.moveTo(103,96);
+    ctx.bezierCurveTo(100,96,99,99,99,101);
+    ctx.bezierCurveTo(99,103,100,106,103,106);
+    ctx.bezierCurveTo(106,106,107,103,107,101);
+    ctx.bezierCurveTo(107,99,106,96,103,96);
+    ctx.fill();
+
+    ctx.fillStyle = "black";
+    ctx.beginPath();
+    ctx.arc(101,102,2,0,Math.PI*2,true);
+    ctx.fill();
+
+    ctx.beginPath();
+    ctx.arc(89,102,2,0,Math.PI*2,true);
+    ctx.fill();
+  }
+}
+
+// Uma função útil para desenhar um retângulo com cantos arredondados.
+
+function roundedRect(ctx,x,y,width,height,radius){
+  ctx.beginPath();
+  ctx.moveTo(x,y+radius);
+  ctx.lineTo(x,y+height-radius);
+  ctx.quadraticCurveTo(x,y+height,x+radius,y+height);
+  ctx.lineTo(x+width-radius,y+height);
+  ctx.quadraticCurveTo(x+width,y+height,x+width,y+height-radius);
+  ctx.lineTo(x+width,y+radius);
+  ctx.quadraticCurveTo(x+width,y,x+width-radius,y);
+  ctx.lineTo(x+radius,y);
+  ctx.quadraticCurveTo(x,y,x,y+radius);
+  ctx.stroke();
+}
+
+ +

O resultado é:

+ +

{{EmbedLiveSample("Combinando_Elementos", 160, 160, "https://mdn.mozillademos.org/files/9849/combinations.png")}}

+ +

Não vamos discutir isso em detalhes, uma vez que é realmente muito simples. As coisas mais importantes a serem observadas são o uso da propriedade fillStyle no contexto de desenho e o uso de uma função auxiliar (neste caso roundedRect()). Usando funções auxiliares para construir um desenho frequentemente pode ser muito útil, além de reduzir a quantidade de código que você precisa, bem como a sua complexidade.

+ +

Vamos dar uma nova olhada em fillStyle, em mais detalhes, mais adiante neste tutorial. Aqui, tudo o que estamos fazendo é apenas usando-o para alterar sucessivamente a cor de preenchimento dos caminhos (paths) de cor preta (padrão) para branca.

+ +

Path2D

+ +

Como vimos no último exemplo, pode haver uma série de paths e comandos de desenho para desenhar objetos em sua tela. Para simplificar o código e melhorar o desempenho, o objeto {{domxref("Path2D")}}, disponível em versões recentes dos navegadores, permite armazenar em cache ou gravar esses comandos de desenho. Com ele, você pode construir seus paths rapidamente.
+ Vamos ver como podemos construir um objeto de Path2D:

+ +
+
{{domxref("Path2D.Path2D", "Path2D()")}}
+
+

O construtor de Path2D() retorna um objeto Path2D instanciado recentemente, opcionalmente através de um outro objeto Path2D como argumento (cria uma cópia) ou, opcionalmente, com uma string que representam dados de paths em SVG.

+
+
+ +
new Path2D();     // objeto vazio de Path2D
+new Path2D(path); // cópia de outro objeto de Path2D
+new Path2D(d);    // objeto criado a partir de paths em SVG
+ +

Todos os métodos de caminho (path methods) como moveTo, rect, arc ou quadraticCurveTo, etc., que temos de saber acima, estão disponíveis em Path2D.

+ +

A API Path2D também adiciona uma maneira de combinar caminhos usando o método addPath. Isso pode ser útil quando você deseja criar objetos com vários componentes, por exemplo.

+ +
+
{{domxref("Path2D.addPath", "Path2D.addPath(path [, transform])")}}
+
Adiciona um path para o path atual através de uma matriz de transformação opcional.
+
+ +

Exemplo de Path2D

+ +

Neste exemplo, estamos criando um retângulo e um círculo. Ambos são armazenados como um objeto de Path2D, de modo que eles estão disponíveis para uso posterior. Com a nova API Path2D, vários métodos foram atualizados como, por exemplo, opcionalmente usar um objeto Path2D em vez do path atual. Aqui, os métodos stroke e fill são usados, ​​com um argumento de path, para desenhar ambos os objetos na tela, por exemplo.

+ + + +
function draw() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext) {
+    var ctx = canvas.getContext('2d');
+
+    var rectangle = new Path2D();
+    rectangle.rect(10, 10, 50, 50);
+
+    var circle = new Path2D();
+    circle.moveTo(125, 35);
+    circle.arc(100, 35, 25, 0, 2 * Math.PI);
+
+    ctx.stroke(rectangle);
+    ctx.fill(circle);
+  }
+}
+
+ +

{{EmbedLiveSample("Exemplo_de_Path2D", 140, 110, "https://mdn.mozillademos.org/files/9851/path2d.png")}}

+ +

Usando paths em SVG

+ +

Outro recurso poderoso da nova API de Path2D é a utilização de dados de path em SVG para inicializar caminhos (paths) no canvas. Isso permite que você crie dados de paths que possam ser utilizados tanto no SVG como no canvas.

+ +

O caminho se moverá para o ponto (M10 10) e então se moverá horizontalmente 80 pontos para a direita (h 80), depois 80 pontos para baixo (v 80), então 80 pontos para a esquerda (h -80) e, por fim, volta para o início (z). Você pode ver este exemplo na página do construtor do Path2D.

+ +
var p = new Path2D('M10 10 h 80 v 80 h -80 Z');
+ +
{{PreviousNext("Web/API/Canvas_API/Tutorial/Basic_usage", "Web/API/Canvas_API/Tutorial/Applying_styles_and_colors")}}
diff --git a/files/pt-br/web/api/canvas_api/tutorial/drawing_text/index.html b/files/pt-br/web/api/canvas_api/tutorial/drawing_text/index.html new file mode 100644 index 0000000000..550719e627 --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/drawing_text/index.html @@ -0,0 +1,169 @@ +--- +title: Drawing text +slug: Web/Guide/HTML/Canvas_tutorial/Drawing_text +tags: + - Canvas + - Intermediário + - Tutorial + - graficos +translation_of: Web/API/Canvas_API/Tutorial/Drawing_text +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Applying_styles_and_colors", "Web/API/Canvas_API/Tutorial/Using_images")}}
+ +
+

Após entender como aplicar estilos e cores no capítulo anterior, nós veremos agora como desenhar texto dentro do contexto de uma canvas.

+
+ +

Desenhando texto

+ +

O context de renderização da canvas fornece dois métodos para renderização textual: 

+ +
+
{{domxref("CanvasRenderingContext2D.fillText", "fillText(text, x, y [, maxWidth])")}}
+
Preenche com um determinado texto as cordenadas (x,y) recebidas. Opcionalmente com uma largura máxima para o desenho.
+
{{domxref("CanvasRenderingContext2D.strokeText", "strokeText(text, x, y [, maxWidth])")}}
+
Traçeja um determinado texto nas cordenadas (x,y) recebidas. Opcionalmente com uma largura máxima para o desenho.
+
+ +

Um exemplo com fillText

+ +

O texto a seguir é rederizado utilizando fillStyle.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  ctx.font = '48px serif';
+  ctx.fillText('Hello world', 10, 50);
+}
+ + + +

{{EmbedLiveSample("A_fillText_example", 310, 110)}}

+ +

Um exemplo com strokeText

+ +

 

+ +

O texto é preenchido usando o strokeStyle atual.

+ +

 

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  ctx.font = '48px serif';
+  ctx.strokeText('Hello world', 10, 50);
+}
+ + + +

{{EmbedLiveSample("A_strokeText_example", 310, 110)}}

+ +

Estilo de Texto

+ +

Nos exemplos anteriores, já usamos a propriedade font para tornar o texto um pouco maior que o tamanho padrão. Existem mais algumas propriedades que permitem ajustar a maneira como o texto é exibido no canvas:

+ +
+
{{domxref("CanvasRenderingContext2D.font", "font = value")}}
+
The current text style being used when drawing text. This string uses the same syntax as the CSS {{cssxref("font")}} property. The default font is 10px sans-serif.
+
{{domxref("CanvasRenderingContext2D.textAlign", "textAlign = value")}}
+
Text alignment setting. Possible values: start, end, left, right or center. The default value is start.
+
{{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline = value")}}
+
Baseline alignment setting. Possible values: top, hanging, middle, alphabetic, ideographic, bottom. The default value is alphabetic.
+
{{domxref("CanvasRenderingContext2D.direction", "direction = value")}}
+
Directionality. Possible values: ltr, rtl, inherit. The default value is inherit.
+
+ +

Essas propriedades podem ser similares para você, se você trabalhou com CSS antes.

+ +

O diagrama seguinte do WHATWG demonstra as várias baselines suportadas pela propriedade do textBaselineThe top of the em square is +roughly at the top of the glyphs in a font, the hanging baseline is +where some glyphs like आ are anchored, the middle is half-way +between the top of the em square and the bottom of the em square, +the alphabetic baseline is where characters like Á, ÿ, +f, and Ω are anchored, the ideographic baseline is +where glyphs like 私 and 達 are anchored, and the bottom +of the em square is roughly at the bottom of the glyphs in a +font. The top and bottom of the bounding box can be far from these +baselines, due to glyphs extending far outside the em square.

+ +

O exemplo de uma textBaseline

+ +

Edite o código abaixo e veja as atualizações em tempo real no canvas.

+ +
ctx.font = '48px serif';
+ctx.textBaseline = 'hanging';
+ctx.strokeText('Hello world', 0, 100);
+
+ + + +

{{ EmbedLiveSample('Playable_code', 700, 360) }}

+ +

Advanced text measurements

+ +

In the case you need to obtain more details about the text, the following method allows you to measure it.

+ +
+
{{domxref("CanvasRenderingContext2D.measureText", "measureText()")}}
+
Returns a {{domxref("TextMetrics")}} object containing the width, in pixels, that the specified text will be when drawn in the current text style.
+
+ +

The following code snippet shows how you can measure a text and get its width.

+ +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  var text = ctx.measureText('foo'); // TextMetrics object
+  text.width; // 16;
+}
+
+ +

Notas específicas - Gecko

+ +

No Gecko (a engine de renderização do Firefox, Firefox OS e outras aplicações Mozilla), algumas APIs prefixadas foram implementadas em versões anteriores para escrever texto em um canvas. Essas APIs agora estão depreciadas e removidas, e não são mais garantidas para uso.

+ +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Applying_styles_and_colors", "Web/API/Canvas_API/Tutorial/Using_images")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/finale/index.html b/files/pt-br/web/api/canvas_api/tutorial/finale/index.html new file mode 100644 index 0000000000..9cd393b652 --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/finale/index.html @@ -0,0 +1,49 @@ +--- +title: Conclusão +slug: Web/Guide/HTML/Canvas_tutorial/Conclusão +translation_of: Web/API/Canvas_API/Tutorial/Finale +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Optimizing_canvas")}}
+ +
+

Parabéns! Você terminou o Canvas tutorial! Este conhecimento ajudará você a fazer ótimos gráficos 2D na web.

+
+ +

Mais exemplos e tutoriais

+ +

Há uma variedade de demonstrações e mais explicações sobre canvas nesses sites:

+ +
+
Codepen.io
+
Front End Developer Playground & Code Editor no navegador.
+
HTML5CanvasTutorials
+
Exemplos para a maioria das APIs canvas.
+
31 days of Canvas tutorials
+
Uma ótima fundação para codificação visual em JavaScript .
+
Game development
+
O jogo é uma das atividades de computador mais populares. Novas tecnologias estão chegando constantemente para possibilitar o desenvolvimento de jogos melhores e mais poderosos que podem ser executados em qualquer navegador da Web compatível com os padrões.
+
+ +

Outras Web APIs

+ +

Essas APIs podem ser úteis, quando trabalhando mais com canvas e gráficos:

+ +
+
WebGL
+
API para renderização interativa de gráficos 3D.
+
SVG
+
Scalable Vector Graphics permitem que você descreva imagens como conjuntos de vetores (linhas) e formas, a fim de permitir que eles sejam redimensionados sem problemas, independentemente do tamanho em que são desenhados.
+
Web Audio
+
A Web Audio API fornece um sistema poderoso e versátil para controlar o áudio na Web, permitindo que os desenvolvedores escolham fontes de áudio, adicionem efeitos ao áudio, criem visualizações de áudio, apliquem efeitos espaciais (como panning) e muito mais.
+
+ +

Questions

+ +
+
Stackoverflow
+
Perguntas marcadas como "canvas".
+
Comentários sobre esse tutorial – A comunidade MDN de documentação
+
Se você tiver algum comentário sobre este tutorial ou quiser nos agradecer, fique à vontade para entrar em contato conosco!
+
+ +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Optimizing_canvas")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/index.html b/files/pt-br/web/api/canvas_api/tutorial/index.html new file mode 100644 index 0000000000..2f9dbab7df --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/index.html @@ -0,0 +1,56 @@ +--- +title: Canvas tutorial +slug: Web/Guide/HTML/Canvas_tutorial +tags: + - Canvas + - Graphics + - Guide + - HTML + - HTML5 + - Intermediate + - Web +translation_of: Web/API/Canvas_API/Tutorial +--- +

 {{CanvasSidebar}}

+ +

<canvas> é um elemento HTML que pode ser usado para desenhar usando linguagem de "script" (normalmente JavaScript). Isto pode ser usado, por exemplo, para desenhar gráficos, fazer composições de fotos ou simples (e não tão simples) animações. As imagens à direita mostram exemplos de implementações <canvas> que serão parte deste tutorial.

+ +

Este tutorial descreve como utilizar o elemento <canvas> para desenhar gráficos 2D, iniciando com o básico. Os exemplos fornecidos devem lhe trazer algumas ideias claras sobre o que você pode fazer com o canvas e irá fornecer trechos de código que podem lhe ajudar na contrução do seu próprio conteúdo. 

+ +

Introduzido pela primeira vez no WebKit pela Apple para o OS X Dashboard, o <canvas>, desde então, tem sido implementado em navegadores. Hoje, todos os principais navegadores suportam isso.

+ +

Antes de começar

+ +

Usar o elemento <canvas> não é muito difícil, mas você precisa de um conhecimento básico sobre HTML e JavaScript. O elemento <canvas> não é suportado por alguns navegadores antigos, mas é suportado em versões recentes da maioria dos navegadores. O tamanho padrão de um canvas é de 300px * 150px (largura * altura). Porém, tamanhos customizados podem ser definidos usando as propriedades width e height do CSS. Para desenhar gráficos no canvas iremos usar um contexto de objeto JavaScript, o que criará gráficos em tempo real.

+ +

Nesse tutorial

+ + + +

Veja também

+ + + +

Nota dos contribuidores

+ +

Devido a um erro técnico lamentável que ocorreu na semana de 17 de junho de 2013, perdemos parte do histórico deste tutorial, incluindo atribuições a todos os contribuidores anteriores ao seu conteúdo. Pedimos desculpas por isso, e espero que você nos perdoe desse infeliz infortúnio.

+ +
{{ Next("Web/Guide/HTML/Canvas_tutorial/Utilizacao_basica") }}
diff --git a/files/pt-br/web/api/canvas_api/tutorial/optimizing_canvas/index.html b/files/pt-br/web/api/canvas_api/tutorial/optimizing_canvas/index.html new file mode 100644 index 0000000000..d18afddefa --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/optimizing_canvas/index.html @@ -0,0 +1,115 @@ +--- +title: Otimizando canvas +slug: Web/Guide/HTML/Canvas_tutorial/Otimizando_Canvas +tags: + - Canvas + - Gráfico 2D + - Otimização +translation_of: Web/API/Canvas_API/Tutorial/Optimizing_canvas +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility", "Web/API/Canvas_API/Tutorial/Finale")}}
+ +
+

O elemento {{HTMLElement("canvas")}} é um dos padrões mais largamente utilizados para renderização de gráficos 2D na Web. É muito usado em jogos e em visualizações complexas. Porém, quando sítios web e aplicativos utilizam canvas até seus limites, começam a surgir problemas de perda de performance. Este artigo tem o objetivo de prover sugestões de otimização de seu elemento canvas e garantir que seu site ou aplicativo funcione melhor.

+
+ +

Dicas de performance

+ +

O que segue é uma coleção de dicas para melhorar a performance.

+ +

Pre-render similar primitives or repeating objects on an off-screen canvas

+ +

If you find yourself with complex drawing operations on each frame, consider creating an offscreen canvas, draw to it once (or whenever it changes) on the offscreen canvas, then on each frame draw the offscreen canvas.

+ +
myEntity.offscreenCanvas = document.createElement('canvas');
+myEntity.offscreenCanvas.width = myEntity.width;
+myEntity.offscreenCanvas.height = myEntity.height;
+myEntity.offscreenContext = myEntity.offscreenCanvas.getContext('2d');
+
+myEntity.render(myEntity.offscreenContext);
+
+ +

Avoid floating-point coordinates and use integers instead

+ +

Sub-pixel rendering occurs when you render objects on a canvas without whole values.

+ +
ctx.drawImage(myImage, 0.3, 0.5);
+
+ +

This causes the browser to do extra calculations to create the anti-aliasing effect. To avoid this, make sure to round all co-ordinates used in calls to {{domxref("CanvasRenderingContext2D.drawImage", "drawImage()")}} using {{jsxref("Math.floor()")}}, for example.

+ +

Don’t scale images in drawImage

+ +

Cache various sizes of your images on an offscreen canvas when loading as opposed to constantly scaling them in {{domxref("CanvasRenderingContext2D.drawImage", "drawImage()")}}.

+ +

Use multiple layered canvases for complex scenes

+ +

You may find you have some elements that are frequently changing and moving around whereas other things (like UI) never change. An optimization in this situation is to create layers using multiple canvas elements.

+ +

For example you could create a UI layer that sits on top of everything and is only drawn during user input. You could create game layer where the frequently updating entities exist and a background layer for entities that rarely update.

+ +
<div id="stage">
+  <canvas id="ui-layer" width="480" height="320"></canvas>
+  <canvas id="game-layer" width="480" height="320"></canvas>
+  <canvas id="background-layer" width="480" height="320"></canvas>
+</div>
+
+<style>
+  #stage {
+    width: 480px;
+    height: 320px;
+    position: relative;
+    border: 2px solid black
+  }
+  canvas { position: absolute; }
+  #ui-layer { z-index: 3 }
+  #game-layer { z-index: 2 }
+  #background-layer { z-index: 1 }
+</style>
+
+ +

CSS for large background images

+ +

If like most games you have a static background image, use a plain {{HTMLElement("div")}} element with a CSS {{cssxref("background")}} property and position it under the canvas. This will avoid drawing a large image to the canvas on every tick.

+ +

Scaling canvas using CSS transforms

+ +

CSS transforms are faster by using the GPU. Best case is to not scale the canvas or have a smaller canvas and scale up rather than a bigger canvas and scale down. For Firefox OS, target 480 x 320 px.

+ +
var scaleX = window.innerWidth / canvas.width;
+var scaleY = window.innerHeight / canvas.height;
+
+var scaleToFit = Math.min(scaleX, scaleY);
+var scaleToCover = Math.max(scaleX, scaleY);
+
+stage.style.transformOrigin = '0 0'; //scale from top left
+stage.style.transform = 'scale(' + scaleToFit + ')';
+
+ +

Turn off transparency

+ +

If your game uses canvas and doesn’t need to be transparent, set the alpha option to false when creating a drawing context with HTMLCanvasElement.getContext(). This information can be used internally to optimize rendering.

+ +
var ctx = canvas.getContext('2d', { alpha: false });
+ +

More tips

+ + + +

See also

+ + + +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility", "Web/API/Canvas_API/Tutorial/Finale")}}

diff --git a/files/pt-br/web/api/canvas_api/tutorial/using_images/index.html b/files/pt-br/web/api/canvas_api/tutorial/using_images/index.html new file mode 100644 index 0000000000..0b0dcfe7e7 --- /dev/null +++ b/files/pt-br/web/api/canvas_api/tutorial/using_images/index.html @@ -0,0 +1,333 @@ +--- +title: Using images +slug: Web/Guide/HTML/Canvas_tutorial/Using_images +translation_of: Web/API/Canvas_API/Tutorial/Using_images +--- +
{{CanvasSidebar}} {{PreviousNext("Web/API/Canvas_API/Tutorial/Drawing_text", "Web/API/Canvas_API/Tutorial/Transformations" )}}
+ +
+

Até agora nós criamos nossos próprios shapes e aplicamos estilos(applied styles) a eles. Um dos recursos mais interessantes do {{HTMLElement("canvas")}} é a capacidade de usar imagens. Eles podem ser usados para composição dinâmica de fotos ou como pano de fundo de gráficos, como sprites em jogos e assim por diante. Imagens externas podem ser usadas em qualquer formato suportado pelo navegador, tais como PNG, GIF, ou JPEG. Você pode até usar a imagem produzida por outros elementos da tela na mesma página que a fonte!

+
+ +

A importação de imagens para o canvas é basicamente um processo de duas etapas:

+ +
    +
  1. Obter uma referência a um objeto {{domxref("HTMLImageElement")}} ou a outro elemento do canvas como fonte. Também é possível usar imagens fornecendo uma URL.
    2. +
  2. Desenhar a imagem no canvas usando a função drawImage() .
    3. +
+ +

Vamos dar uma olhada em como fazer isso.

+ +

Getting images to draw

+ +

The canvas API is able to use any of the following data types as an image source:

+ +
+
{{domxref("HTMLImageElement")}}
+
These are images created using the Image() constructor, as well as any {{HTMLElement("img")}} element.
+
{{domxref("SVGImageElement")}}
+
These are images embedded using the {{SVGElement("image")}} element.
+
{{domxref("HTMLVideoElement")}}
+
Using an HTML {{HTMLElement("video")}} element as your image source grabs the current frame from the video and uses it as an image.
+
{{domxref("HTMLCanvasElement")}}
+
You can use another {{HTMLElement("canvas")}} element as your image source.
+
+ +

These sources are collectively referred to by the type {{domxref("CanvasImageSource")}}.

+ +

There are several ways to get images for use on a canvas.

+ +

Using images from the same page

+ +

We can obtain a reference to images on the same page as the canvas by using one of:

+ + + +

Using images from other domains

+ +

Using the {{htmlattrxref("crossorigin", "img")}} attribute of an {{HTMLElement("img")}} element (reflected by the {{domxref("HTMLImageElement.crossOrigin")}} property), you can request permission to load an image from another domain for use in your call to drawImage(). If the hosting domain permits cross-domain access to the image, the image can be used in your canvas without tainting it; otherwise using the image will taint the canvas.

+ +

Using other canvas elements

+ +

Just as with normal images, we access other canvas elements using either the {{domxref("document.getElementsByTagName()")}} or {{domxref("document.getElementById()")}} method. Be sure you've drawn something to the source canvas before using it in your target canvas.

+ +

One of the more practical uses of this would be to use a second canvas element as a thumbnail view of the other larger canvas.

+ +

Creating an image from scratch

+ +

Another option is to create new {{domxref("HTMLImageElement")}} objects in our script. To do this, you can use the convenient Image() constructor:

+ +
var img = new Image();   // Create new img element
+img.src = 'myImage.png'; // Set source path
+
+ +

When this script gets executed, the image starts loading.

+ +

If you try to call drawImage() before the image has finished loading, it won't do anything (or, in older browsers, may even throw an exception). So you need to be sure to use the load event so you don't try this before the image has loaded:

+ +
var img = new Image();   // Create new img element
+img.addEventListener('load', function() {
+  // execute drawImage statements here
+}, false);
+img.src = 'myImage.png'; // Set source path
+
+ +

If you're only using one external image this can be a good approach, but once you need to track more than one we need to resort to something more clever. It's beyond the scope of this tutorial to look at image pre-loading tactics, but you should keep that in mind.

+ +

Embedding an image via data: URL

+ +

Another possible way to include images is via the data: url. Data URLs allow you to completely define an image as a Base64 encoded string of characters directly in your code.

+ +
var img = new Image();   // Create new img element
+img.src = 'data:image/gif;base64,R0lGODlhCwALAIAAAAAA3pn/ZiH5BAEAAAEALAAAAAALAAsAAAIUhA+hkcuO4lmNVindo7qyrIXiGBYAOw==';
+
+ +

One advantage of data URLs is that the resulting image is available immediately without another round trip to the server. Another potential advantage is that it is also possible to encapsulate in one file all of your CSS, JavaScript, HTML, and images, making it more portable to other locations.

+ +

Some disadvantages of this method are that your image is not cached, and for larger images the encoded url can become quite long.

+ +

Using frames from a video

+ +

You can also use frames from a video being presented by a {{HTMLElement("video")}} element (even if the video is not visible). For example, if you have a {{HTMLElement("video")}} element with the ID "myvideo", you can do this:

+ +
function getMyVideo() {
+  var canvas = document.getElementById('canvas');
+  if (canvas.getContext) {
+    var ctx = canvas.getContext('2d');
+
+    return document.getElementById('myvideo');
+  }
+}
+
+ +

This returns the {{domxref("HTMLVideoElement")}} object for the video, which, as covered earlier, is one of the objects that can be used as a CanvasImageSource.

+ +

Drawing images

+ +

Once we have a reference to our source image object we can use the drawImage() method to render it to the canvas. As we will see later the drawImage() method is overloaded and has several variants. In its most basic form it looks like this:

+ +
+
{{domxref("CanvasRenderingContext2D.drawImage", "drawImage(image, x, y)")}}
+
Draws the CanvasImageSource specified by the image parameter at the coordinates (x, y).
+
+ +
+

SVG images must specify a width and height in the root <svg> element.

+
+ +

Example: A simple line graph

+ +

In the following example, we will use an external image as the backdrop for a small line graph. Using backdrops can make your script considerably smaller because we can avoid the need for code to generate the background. In this example, we're only using one image, so I use the image object's load event handler to execute the drawing statements. The drawImage() method places the backdrop at the coordinate (0, 0), which is the top-left corner of the canvas.

+ + + +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  var img = new Image();
+  img.onload = function() {
+    ctx.drawImage(img, 0, 0);
+    ctx.beginPath();
+    ctx.moveTo(30, 96);
+    ctx.lineTo(70, 66);
+    ctx.lineTo(103, 76);
+    ctx.lineTo(170, 15);
+    ctx.stroke();
+  };
+  img.src = 'https://mdn.mozillademos.org/files/5395/backdrop.png';
+}
+ +

The resulting graph looks like this:

+ +

{{EmbedLiveSample("Example_A_simple_line_graph", 220, 160, "https://mdn.mozillademos.org/files/206/Canvas_backdrop.png")}}

+ +

Scaling

+ +

The second variant of the drawImage() method adds two new parameters and lets us place scaled images on the canvas.

+ +
+
{{domxref("CanvasRenderingContext2D.drawImage", "drawImage(image, x, y, width, height)")}}
+
This adds the width and height parameters, which indicate the size to which to scale the image when drawing it onto the canvas.
+
+ +

Example: Tiling an image

+ +

In this example, we'll use an image as a wallpaper and repeat it several times on the canvas. This is done simply by looping and placing the scaled images at different positions. In the code below, the first for loop iterates over the rows. The second for loop iterates over the columns. The image is scaled to one third of its original size, which is 50x38 pixels.

+ +
+

Note: Images can become blurry when scaling up or grainy if they're scaled down too much. Scaling is probably best not done if you've got some text in it which needs to remain legible.

+
+ + + +
function draw() {
+  var ctx = document.getElementById('canvas').getContext('2d');
+  var img = new Image();
+  img.onload = function() {
+    for (var i = 0; i < 4; i++) {
+      for (var j = 0; j < 3; j++) {
+        ctx.drawImage(img, j * 50, i * 38, 50, 38);
+      }
+    }
+  };
+  img.src = 'https://mdn.mozillademos.org/files/5397/rhino.jpg';
+}
+ +

The resulting canvas looks like this:

+ +

{{EmbedLiveSample("Example_Tiling_an_image", 160, 160, "https://mdn.mozillademos.org/files/251/Canvas_scale_image.png")}}

+ +

Slicing

+ +

The third and last variant of the drawImage() method has eight parameters in addition to the image source. It lets us cut out a section of the source image, then scale and draw it on our canvas.

+ +
+
{{domxref("CanvasRenderingContext2D.drawImage", "drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)")}}
+
Given an image, this function takes the area of the source image specified by the rectangle whose top-left corner is (sx, sy) and whose width and height are sWidth and sHeight and draws it into the canvas, placing it on the canvas at (dx, dy) and scaling it to the size specified by dWidth and dHeight.
+
+ +

To really understand what this does, it may help to look at the image to the right. The first four parameters define the location and size of the slice on the source image. The last four parameters define the rectangle into which to draw the image on the destination canvas.

+ +

Slicing can be a useful tool when you want to make compositions. You could have all elements in a single image file and use this method to composite a complete drawing. For instance, if you want to make a chart you could have a PNG image containing all the necessary text in a single file and depending on your data could change the scale of your chart fairly easily. Another advantage is that you don't need to load every image individually, which can improve load performance.

+ +

Example: Framing an image

+ +

In this example, we'll use the same rhino as in the previous example, but we'll slice out its head and composite it into a picture frame. The picture frame image is a 24-bit PNG which includes a drop shadow. Because 24-bit PNG images include a full 8-bit alpha channel, unlike GIF and 8-bit PNG images, it can be placed onto any background without worrying about a matte color.

+ +
<html>
+ <body onload="draw();">
+   <canvas id="canvas" width="150" height="150"></canvas>
+   <div style="display:none;">
+     <img id="source" src="https://mdn.mozillademos.org/files/5397/rhino.jpg" width="300" height="227">
+     <img id="frame" src="https://mdn.mozillademos.org/files/242/Canvas_picture_frame.png" width="132" height="150">
+   </div>
+ </body>
+</html>
+
+ +
function draw() {
+  var canvas = document.getElementById('canvas');
+  var ctx = canvas.getContext('2d');
+
+  // Draw slice
+  ctx.drawImage(document.getElementById('source'),
+                33, 71, 104, 124, 21, 20, 87, 104);
+
+  // Draw frame
+  ctx.drawImage(document.getElementById('frame'), 0, 0);
+}
+ +

We took a different approach to loading the images this time. Instead of loading them by creating new {{domxref("HTMLImageElement")}} objects, we included them as {{HTMLElement("img")}} tags directly in our HTML source and retrieved the images from those. The images are hidden from output by setting the CSS property {{cssxref("display")}} to none for those images.

+ +

{{EmbedLiveSample("Example_Framing_an_image", 160, 160, "https://mdn.mozillademos.org/files/226/Canvas_drawimage2.jpg")}}

+ +

The script itself is very simple. Each {{HTMLElement("img")}} is assigned an ID attribute, which makes them easy to select using {{domxref("document.getElementById()")}}. We then simply use drawImage() to slice the rhino out of the first image and scale him onto the canvas, then draw the frame on top using a second drawImage() call.

+ + + +

In the final example of this chapter, we'll build a little art gallery. The gallery consists of a table containing several images. When the page is loaded, a {{HTMLElement("canvas")}}  element is inserted for each image and a frame is drawn around it.

+ +

In this case, every image has a fixed width and height, as does the frame that's drawn around them. You could enhance the script so that it uses the image's width and height to make the frame fit perfectly around it.

+ +

The code below should be self-explanatory. We loop through the {{domxref("document.images")}} container and add new canvas elements accordingly. Probably the only thing to note, for those not so familiar with the DOM, is the use of the {{domxref("Node.insertBefore")}} method. insertBefore() is a method of the parent node (a table cell) of the element (the image) before which we want to insert our new node (the canvas element).

+ +
<html>
+ <body onload="draw();">
+     <table>
+      <tr>
+        <td><img src="https://mdn.mozillademos.org/files/5399/gallery_1.jpg"></td>
+        <td><img src="https://mdn.mozillademos.org/files/5401/gallery_2.jpg"></td>
+        <td><img src="https://mdn.mozillademos.org/files/5403/gallery_3.jpg"></td>
+        <td><img src="https://mdn.mozillademos.org/files/5405/gallery_4.jpg"></td>
+      </tr>
+      <tr>
+        <td><img src="https://mdn.mozillademos.org/files/5407/gallery_5.jpg"></td>
+        <td><img src="https://mdn.mozillademos.org/files/5409/gallery_6.jpg"></td>
+        <td><img src="https://mdn.mozillademos.org/files/5411/gallery_7.jpg"></td>
+        <td><img src="https://mdn.mozillademos.org/files/5413/gallery_8.jpg"></td>
+      </tr>
+     </table>
+     <img id="frame" src="https://mdn.mozillademos.org/files/242/Canvas_picture_frame.png" width="132" height="150">
+ </body>
+</html>
+
+ +

And here's some CSS to make things look nice:

+ +
body {
+  background: 0 -100px repeat-x url(https://mdn.mozillademos.org/files/5415/bg_gallery.png) #4F191A;
+  margin: 10px;
+}
+
+img {
+  display: none;
+}
+
+table {
+  margin: 0 auto;
+}
+
+td {
+  padding: 15px;
+}
+
+ +

Tying it all together is the JavaScript to draw our framed images:

+ +
function draw() {
+
+  // Loop through all images
+  for (var i = 0; i < document.images.length; i++) {
+
+    // Don't add a canvas for the frame image
+    if (document.images[i].getAttribute('id') != 'frame') {
+
+      // Create canvas element
+      canvas = document.createElement('canvas');
+      canvas.setAttribute('width', 132);
+      canvas.setAttribute('height', 150);
+
+      // Insert before the image
+      document.images[i].parentNode.insertBefore(canvas,document.images[i]);
+
+      ctx = canvas.getContext('2d');
+
+      // Draw image to canvas
+      ctx.drawImage(document.images[i], 15, 20);
+
+      // Add frame
+      ctx.drawImage(document.getElementById('frame'), 0, 0);
+    }
+  }
+}
+ +

{{EmbedLiveSample("Art_gallery_example", 725, 400)}}

+ +

Controlling image scaling behavior

+ +

As mentioned previously, scaling images can result in fuzzy or blocky artifacts due to the scaling process. You can use the drawing context's {{domxref("CanvasRenderingContext2D.imageSmoothingEnabled", "imageSmoothingEnabled")}} property to control the use of image smoothing algorithms when scaling images within your context. By default, this is true, meaning images will be smoothed when scaled. You can disable this feature like this:

+ +
ctx.mozImageSmoothingEnabled = false;
+ctx.webkitImageSmoothingEnabled = false;
+ctx.msImageSmoothingEnabled = false;
+ctx.imageSmoothingEnabled = false;
+
+ +

{{PreviousNext("Web/API/Canvas_API/Tutorial/Drawing_text", "Web/API/Canvas_API/Tutorial/Transformations")}}

diff --git a/files/pt-br/web/api/crypto/getrandomvalues/index.html b/files/pt-br/web/api/crypto/getrandomvalues/index.html new file mode 100644 index 0000000000..7e54e933ed --- /dev/null +++ b/files/pt-br/web/api/crypto/getrandomvalues/index.html @@ -0,0 +1,116 @@ +--- +title: RandomSource.getRandomValues() +slug: Web/API/RandomSource/getRandomValues +translation_of: Web/API/Crypto/getRandomValues +--- +

{{APIRef("Web Crypto API")}}

+ +

O método RandomSource.getRandomValues() permite que você obtenha valores criptográficos randômicos. O array passado como parametro é preenchido com números randômicos (randômicos no sentido criptográfico).

+ +

Para garantir performance suficiente, as implementações não estão usando um gerador de número randômico de verdade, mas estão usando um gerador de número pseudo-randômico alimentado com um valor com {{Glossary("entropia")}} suficiente. Os PRNG (pseudo-random number generator - gerador de número pseudo-randômico) usados diferem de uma implementação para a outra, mas são adequadas para usos criptográficos. As implementações precisam ter um valor de alimentação com entropia suficiente, como uma fonte de entropia a nível de sistema.

+ +

Sintaxe

+ +
cryptoObj.getRandomValues(typedArray);
+ +

Parâmetros

+ +
+
typedArray
+
É uma {{jsxref("TypedArray")}} de números inteiros, que pode ser {{jsxref("Int8Array")}}, {{jsxref("Uint8Array")}}, {{jsxref("Uint16Array")}}, {{jsxref("Int32Array")}}, ou {{jsxref("Uint32Array")}}. Todos os elementos no array serão sobrescristos com números randômicos.
+
+ +

Exceções

+ + + +

Exemplo

+ +
/* assumindo que window.crypto.getRandomValues está disponível */
+
+var array = new Uint32Array(10);
+window.crypto.getRandomValues(array);
+
+console.log("Seus números da sorte são:");
+for (var i = 0; i < array.length; i++) {
+    console.log(array[i]);
+}
+
+ +

Especificação

+ + + + + + + + + + + + + + +
EspecificaçãoEstadoComentário
{{SpecName('Web Crypto API', '#RandomSource-method-getRandomValues')}}{{Spec2('Web Crypto API')}}Definição inicial
+ + + +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support11.0 {{ webkitbug("22049") }}21.011.015.03.1
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatNo() }}23.021.011.0{{ CompatNo() }}6
+
+ +

Veja também

+ + diff --git a/files/pt-br/web/api/cryptokey/algorithm/index.html b/files/pt-br/web/api/cryptokey/algorithm/index.html deleted file mode 100644 index d80199a4ed..0000000000 --- a/files/pt-br/web/api/cryptokey/algorithm/index.html +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: CryptoKey.algorithm -slug: Web/API/CryptoKey/algorithm -tags: - - API - - CryptoKey - - Propriedade - - Read-only - - Referencia - - Web Crypto API -translation_of: Web/API/CryptoKey -translation_of_original: Web/API/CryptoKey/algorithm ---- -

{{APIRef("Web Crypto API")}}

- -

A propriedade CryptoKey.algorithm de apenas leitura é um valor opaco contendo todas as informações sobre o algoritmo relacionado à key.

- -

Implementações diferentes tem diferentes tipos de valores opacos para os mesmos: tal objeto não pode ser compartilhado.

- -

Sintaxe

- -
result = key.algorithm
-
- -

Valor de retorno

- - - -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{ SpecName('Web Crypto API', '#dfn-CryptoKey-algorithm', 'CryptoKey.algorithm') }}{{ Spec2('Web Crypto API') }}Definição inicial.
- -

Compatibilidade de Browser

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticaChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico{{ CompatChrome(37) }}{{CompatVersionUnknown}}{{ CompatGeckoDesktop(34) }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - -
CaracterísticaAndroidChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{CompatVersionUnknown}}37{{CompatVersionUnknown}}{{ CompatGeckoMobile(34) }}{{ CompatNo }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -

Veja também

- - - -

Dicionário

- -

"Key" = "Chave"

diff --git a/files/pt-br/web/api/cryptokey/extractable/index.html b/files/pt-br/web/api/cryptokey/extractable/index.html deleted file mode 100644 index 4fe2885cbc..0000000000 --- a/files/pt-br/web/api/cryptokey/extractable/index.html +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: CryptoKey.extractable -slug: Web/API/CryptoKey/extractable -tags: - - API - - CryptoKey - - Propriedade - - Read-only - - Referencia - - Web Crypto API -translation_of: Web/API/CryptoKey -translation_of_original: Web/API/CryptoKey/extractable ---- -

{{APIRef("Web Crypto API")}}

- -

A propriedade de apenas leitura CryptoKey.extractable que indica se a key bruta do material pode ser extraída, para por exemplo arquivá-la.

- -

Sintaxe

- -
result = key.extractable
-
- -

Valor de retorno

- - - -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{ SpecName('Web Crypto API', '#dfn-CryptoKey-extractable', 'CryptoKey.extractable') }}{{ Spec2('Web Crypto API') }}Definição inicial.
- -

Compatibilidade de Browser

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticaChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico{{ CompatChrome(37) }}{{CompatVersionUnknown}}{{ CompatGeckoDesktop(34) }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - -
CaracterísticaAndroidChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{CompatVersionUnknown}}37{{CompatVersionUnknown}}{{ CompatGeckoMobile(34) }}{{ CompatNo }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -

Veja também

- - - -

Dicionário

- -

"Key" = "Chave"

diff --git a/files/pt-br/web/api/cryptokey/type/index.html b/files/pt-br/web/api/cryptokey/type/index.html deleted file mode 100644 index 666de87d23..0000000000 --- a/files/pt-br/web/api/cryptokey/type/index.html +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: CryptoKey.type -slug: Web/API/CryptoKey/type -tags: - - API - - Apenas Leitura - - CryptoKey - - Propriedades - - Referencia - - Web Crypto API -translation_of: Web/API/CryptoKey -translation_of_original: Web/API/CryptoKey/type ---- -

{{APIRef("Web Crypto API")}}

- -

O CryptoKey.type é uma propriedade de apenas leitura que indica o tipo de key: se for uma key para um algoritmo simétrico ("secret") ou, para um algoritmo assimétrico, ("public" ou "private", dependendo do seu propósito).

- -

Sintaxe

- -
result = key.type
-
- -

Valor de retorno

- - - -

Especificações

- - - - - - - - - - - - - - -
EspecificaçõesStatusComentário
{{ SpecName('Web Crypto API', '#dfn-CryptoKey-type', 'CryptoKey.type') }}{{ Spec2('Web Crypto API') }}Definição inicial.
- -

Compatibilidade de Browser

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticasChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico{{ CompatChrome(37) }}{{CompatVersionUnknown}}{{ CompatGeckoDesktop(34) }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - -
CaracterísticasAndroidChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{CompatVersionUnknown}}37{{CompatVersionUnknown}}{{ CompatGeckoMobile(34) }}{{ CompatNo }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -

Veja também

- - - -

Dicionário:

- -

"Key" = "Chave"

diff --git a/files/pt-br/web/api/cryptokey/usages/index.html b/files/pt-br/web/api/cryptokey/usages/index.html deleted file mode 100644 index c74a658a32..0000000000 --- a/files/pt-br/web/api/cryptokey/usages/index.html +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: CryptoKey.usages -slug: Web/API/CryptoKey/usages -tags: - - API - - CryptoKey - - Propriedade - - Read-only - - Referencia - - Web Crypto API -translation_of: Web/API/CryptoKey -translation_of_original: Web/API/CryptoKey/usages ---- -

{{APIRef("Web Crypto API")}}

- -

A propriedade de apenas leitura CryptoKey.usages é um conjunto enumerado que indica os propósitos da key.

- -

Possíveis valores são:

- - - -

Sintaxe

- -
result = key.usages
-
- -

Valor de retorno

- - - -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{ SpecName('Web Crypto API', '#dfn-CryptoKey-usages', 'CryptoKey.usages') }}{{ Spec2('Web Crypto API') }}Definição inicial.
- -

Compatibilidade de Browser

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticaChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico{{ CompatChrome(37) }}{{CompatVersionUnknown}}{{ CompatGeckoDesktop(34) }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -
- - - - - - - - - - - - - - - - - - - - - - - -
CaracterísticaAndroidChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{CompatVersionUnknown}}37{{CompatVersionUnknown}}{{ CompatGeckoMobile(34) }}{{ CompatNo }}{{ CompatUnknown() }}{{ CompatNo }}
-
- -

Veja também

- - - -

Dicionário:

- -

"Key" = "Chave"

diff --git a/files/pt-br/web/api/deviceacceleration/index.html b/files/pt-br/web/api/deviceacceleration/index.html deleted file mode 100644 index e8e5432e4a..0000000000 --- a/files/pt-br/web/api/deviceacceleration/index.html +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: DeviceAcceleration -slug: Web/API/DeviceAcceleration -tags: - - API - - Experimental - - Interface -translation_of: Web/API/DeviceMotionEventAcceleration -translation_of_original: Web/API/DeviceAcceleration ---- -
{{ ApiRef("Device Orientation Events") }}{{SeeCompatTable}}
- -

Um objeto DeviceAcceleration fornece informações sobre a quantidade de aceleração que o dispositivo desempenha ao longo dos três eixos.

- -

Propriedades

- -
-
{{domxref("DeviceAcceleration.x")}} {{readonlyInline}}
-
A quantidade de aceleração ao longo do eixo X. Somente leitura.
-
{{domxref("DeviceAcceleration.y")}} {{readonlyInline}}
-
A quantidade de aceleração ao longo do eixo Y. Somente leitura.
-
{{domxref("DeviceAcceleration.z")}} {{readonlyInline}}
-
A quantidade de aceleração ao longo do eixo Z.Somente leitura.
-
- -

Especificações

- - - - - - - - - - - - - - - - -
EspecificaçõesStatusComentario
{{SpecName("Device Orientation", "#device_acceleration", "DeviceAcceleration")}}{{Spec2("Device Orientation")}}Definição inicial
diff --git a/files/pt-br/web/api/devicemotioneventacceleration/index.html b/files/pt-br/web/api/devicemotioneventacceleration/index.html new file mode 100644 index 0000000000..e8e5432e4a --- /dev/null +++ b/files/pt-br/web/api/devicemotioneventacceleration/index.html @@ -0,0 +1,43 @@ +--- +title: DeviceAcceleration +slug: Web/API/DeviceAcceleration +tags: + - API + - Experimental + - Interface +translation_of: Web/API/DeviceMotionEventAcceleration +translation_of_original: Web/API/DeviceAcceleration +--- +
{{ ApiRef("Device Orientation Events") }}{{SeeCompatTable}}
+ +

Um objeto DeviceAcceleration fornece informações sobre a quantidade de aceleração que o dispositivo desempenha ao longo dos três eixos.

+ +

Propriedades

+ +
+
{{domxref("DeviceAcceleration.x")}} {{readonlyInline}}
+
A quantidade de aceleração ao longo do eixo X. Somente leitura.
+
{{domxref("DeviceAcceleration.y")}} {{readonlyInline}}
+
A quantidade de aceleração ao longo do eixo Y. Somente leitura.
+
{{domxref("DeviceAcceleration.z")}} {{readonlyInline}}
+
A quantidade de aceleração ao longo do eixo Z.Somente leitura.
+
+ +

Especificações

+ + + + + + + + + + + + + + + + +
EspecificaçõesStatusComentario
{{SpecName("Device Orientation", "#device_acceleration", "DeviceAcceleration")}}{{Spec2("Device Orientation")}}Definição inicial
diff --git a/files/pt-br/web/api/devicemotioneventrotationrate/index.html b/files/pt-br/web/api/devicemotioneventrotationrate/index.html new file mode 100644 index 0000000000..872b3c6f25 --- /dev/null +++ b/files/pt-br/web/api/devicemotioneventrotationrate/index.html @@ -0,0 +1,93 @@ +--- +title: DeviceRotationRate +slug: Web/API/DeviceRotationRate +translation_of: Web/API/DeviceMotionEventRotationRate +translation_of_original: Web/API/DeviceRotationRate +--- +

{{ ApiRef("Device Orientation Events") }} {{SeeCompatTable}}

+ +

Um objeto DeviceRotationRate fornece informações sobre a taxa na qual o dispositivo está girando em torno de todos os três eixos.

+ +

Properties

+ +
+
{{ domxref("DeviceRotationRate.alpha") }} {{readonlyInline}}
+
A quantidade de rotação em torno do eixo Z, em graus por segundo.
+
{{ domxref("DeviceRotationRate.beta") }} {{readonlyInline}}
+
A quantidade de rotação em torno do eixo Y, em graus por segundo
+
{{ domxref("DeviceRotationRate.gamma") }} {{readonlyInline}}
+
A quantidade de rotação em torno do eixo X, em graus por segundo
+
+ +

Especificações

+ + + + + + + + + + + + + + + + +
EspecificacõesStatusComentario
{{SpecName('Device Orientation')}}{{Spec2('Device Orientation')}}Definição inicial.
+ + + +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + + + +
CaracterísticasChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
CaracterísticasAndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
+
diff --git a/files/pt-br/web/api/devicerotationrate/index.html b/files/pt-br/web/api/devicerotationrate/index.html deleted file mode 100644 index 872b3c6f25..0000000000 --- a/files/pt-br/web/api/devicerotationrate/index.html +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: DeviceRotationRate -slug: Web/API/DeviceRotationRate -translation_of: Web/API/DeviceMotionEventRotationRate -translation_of_original: Web/API/DeviceRotationRate ---- -

{{ ApiRef("Device Orientation Events") }} {{SeeCompatTable}}

- -

Um objeto DeviceRotationRate fornece informações sobre a taxa na qual o dispositivo está girando em torno de todos os três eixos.

- -

Properties

- -
-
{{ domxref("DeviceRotationRate.alpha") }} {{readonlyInline}}
-
A quantidade de rotação em torno do eixo Z, em graus por segundo.
-
{{ domxref("DeviceRotationRate.beta") }} {{readonlyInline}}
-
A quantidade de rotação em torno do eixo Y, em graus por segundo
-
{{ domxref("DeviceRotationRate.gamma") }} {{readonlyInline}}
-
A quantidade de rotação em torno do eixo X, em graus por segundo
-
- -

Especificações

- - - - - - - - - - - - - - - - -
EspecificacõesStatusComentario
{{SpecName('Device Orientation')}}{{Spec2('Device Orientation')}}Definição inicial.
- - - -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticasChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
-
- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticasAndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
-
diff --git a/files/pt-br/web/api/document/activeelement/index.html b/files/pt-br/web/api/document/activeelement/index.html deleted file mode 100644 index ca10f98461..0000000000 --- a/files/pt-br/web/api/document/activeelement/index.html +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Document.activeElement -slug: Web/API/Document/activeElement -tags: - - API - - Document - - HTML DOM - - Property - - Reference -translation_of: Web/API/DocumentOrShadowRoot/activeElement -translation_of_original: Web/API/Document/activeElement ---- -

{{APIRef("DOM")}}

- -

Retorna o {{ domxref("Element", "elemento") }} atualmente em foco, ou seja, o elemento que receberá os eventos do teclado caso o usuário digite algo. Esse atributo é somente-leitura.

- -

Geralmente retorna um {{ HTMLElement("input") }} ou {{ HTMLElement("textarea") }}, caso esteja com uma seleção de texto ativa. Caso esteja, pode obter mais informações sobre a seleção utilizando as propriedades selectionStart e selectionEnd. Caso o elemento em foco seja um {{ HTMLElement("select") }}(menu) ou {{ HTMLElement("input") }} do tipo button, checkbox ou radio.

- -
Note: No Mac, elementos que nao sejam campos de texto geralmente não recebem foco.
- -

Normalmente o usuário pode navegar entre os elementos que pode receber foco na página com o uso da tecla tab e ativar estes elementos com a tecla espaço (apertar um botão ou selecionar uma opção).

- -

Não confunda foco com uma seleção de texto no documento, que consiste em sua maioria de nódos de texto estáticos. Veja {{ domxref("window.getSelection()") }}.

- -

Quando não há nada selecionado, o activeElement da página é o {{ HTMLElement("body") }} ou null. 

- -
-

Este atributo é parte da seção "Em desenvolvimento" da especificação do HTML 5.

-
- -

Sintaxe

- -
var curElement = document.activeElement;
-
- -

Exemplo

- -
<!DOCTYPE HTML>
-<html>
-<head>
-    <script type="text/javascript" charset="utf-8">
-    function init() {
-
-        function onMouseUp(e) {
-            console.log(e);
-            var outputElement = document.getElementById('output-element');
-            var outputText = document.getElementById('output-text');
-            var selectedTextArea = document.activeElement;
-            var selection = selectedTextArea.value.substring(
-            selectedTextArea.selectionStart, selectedTextArea.selectionEnd);
-            outputElement.innerHTML = selectedTextArea.id;
-            outputText.innerHTML = selection;
-        }
-
-        document.getElementById("ta-example-one").addEventListener("mouseup", onMouseUp, false);
-        document.getElementById("ta-example-two").addEventListener("mouseup", onMouseUp, false);
-    }
-    </script>
-</head>
-<body onload="init()">
-<div>
-    Select some text from one of the Textareas below:
-</div>
-<form id="frm-example" action="#" accept-charset="utf-8">
-<textarea name="ta-example-one" id="ta-example-one" rows="8" cols="40">
-This is Textarea Example One:
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec tincidunt, lorem a porttitor molestie, odio nibh iaculis libero, et accumsan nunc orci eu dui.
-</textarea>
-<textarea name="ta-example-two" id="ta-example-two" rows="8" cols="40">
-This is Textarea Example Two:
-Fusce ullamcorper, nisl ac porttitor adipiscing, urna orci egestas libero, ut accumsan orci lacus laoreet diam. Morbi sed euismod diam.
-</textarea>
-</form>
-Active Element Id: <span id="output-element"></span><br/>
-Selected Text: <span id="output-text"></span>
-
-</body>
-</html>
-
- -

View on JSFiddle

- -

Notas

- -

Originalmente apresentada como extensão DOM proprietária no Internet Explorer 4, esta propriedade também é suportada no Opera e Safari (versão 4 ou maior)

- -

Especificações

- - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('HTML WHATWG', 'interaction.html#dom-document-activeelement', 'activeElement')}}{{Spec2('HTML WHATWG')}} 
- -

Compatibilidade nos navegadores

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support23.04 [1]9.64.0
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}
-
- -

[1]: O IE9 tem um bug que ao tentar acessar o activeElement do {{domxref("window.parent")}} {{domxref("Document")}} de um {{HTMLElement("iframe")}}(i.e. parent.document.activeElement) é lançado um erro

- -

Eventos relacionados

- - diff --git a/files/pt-br/web/api/document/elementfrompoint/index.html b/files/pt-br/web/api/document/elementfrompoint/index.html deleted file mode 100644 index c64d67dd08..0000000000 --- a/files/pt-br/web/api/document/elementfrompoint/index.html +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Document.elementFromPoint() -slug: Web/API/Document/elementFromPoint -tags: - - API - - CSSOM View - - Method - - NeedsMarkupWork - - NeedsMobileBrowserCompatibility - - Reference -translation_of: Web/API/DocumentOrShadowRoot/elementFromPoint -translation_of_original: Web/API/Document/elementFromPoint ---- -
{{APIRef("DOM")}}
- -

O método elementFromPoint() da interface {{domxref("Document")}} retorna o elemento de maior nível nas coordenadas especificadas.

- -

Se o elemento no ponto especificado pertencer à outro documento (por exemplo, um subdocumento em um iframe), será retornado o pai do subdocumento (o próprio iframe). Se o elemento em determinado ponto for anônimo ou for um conteudo gerado por XBL, como por exemplo barras de scroll de caixas de texto, então será retornado o primeiro elemento pai, não-anônimo (por exemplo, a própria caixa de texto).

- -

Se o ponto especificado estiver fora dos limites visíveis do documento ou tiver uma coordenada negativa, o resultado é null.

- -

Se você precisa encontrar uma posição específica dentro do elemento, use {{domxref("Document.caretPositionFromPoint()")}}.

- -

{{Note("Chamados por documentos XUL devem esperar até o evento onload ser acionado antes de chamar este método.")}}

- -

Sintaxe

- -
var element = document.elementFromPoint(x, y);
- -

Parâmetros

- -
-
x
-
Uma posição horizontal dentro do viewport atual.
-
y
-
Uma position vertical dentro do viewport atual.
-
- -

Valor retornado

- -

O objeto de nível mais alto {{domxref("Element")}} dentro das coordenadas declaradas.

- -

Exemplo

- -
<!DOCTYPE html>
-<html lang="en">
-<head>
-<title>exemplo de elementFromPoint</title>
-
-<script>
-function changeColor(newColor) {
-  elem = document.elementFromPoint(2, 2);
-  elem.style.color = newColor;
-}
-</script>
-</head>
-
-<body>
-<p id="para1">Algum texto aqui</p>
-<button onclick="changeColor('blue');">azul</button>
-<button onclick="changeColor('red');">vermelho</button>
-</body>
-</html>
-
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComment
{{SpecName('CSSOM View', '#dom-document-elementfrompoint', 'elementFromPoint')}}{{Spec2('CSSOM View')}}Definição Inicial.
- -

Compatibilidade entre navegadores

- -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - -
FuncionalidadeChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support {{CompatChrome(4.0)}}35.510.50{{CompatVersionUnknown}}
-
- -
- - - - - - - - - - - - - - - - - - - - - -
FuncionalidadeAndroidChrome para AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
-
diff --git a/files/pt-br/web/api/document/elementoregistrado/index.html b/files/pt-br/web/api/document/elementoregistrado/index.html deleted file mode 100644 index bff318b3a9..0000000000 --- a/files/pt-br/web/api/document/elementoregistrado/index.html +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Document.registerElement() -slug: Web/API/Document/ElementoRegistrado -tags: - - DOM - - Document.registerElement() - - ELEMENTO DOM - - Web Components - - registerElement -translation_of: Web/API/Document/registerElement ---- -

{{APIRef("DOM")}}

- -
-

Note:document.registerElement() está depreciado em favor do customElements.define().

-
- -

O método document.registerElement() registra um novo elemento personalizado no browser e returna um construtor para o novo elemento.

- -
-

Nota: Esta é uma tecnologia experimental. O browser você precisa usar suporte à componentes web. Veja Habilitando componentes web no Firefox.

-
- -

Sintaxe

- -
var constructor = document.registerElement(tag-name, options);
- -

Parâmetros

- -
-
tag-name
-
O nome do elemento personalizado. O nome precisa conter um dash (-), por exemplo minha-tag.
-
Opções{{optional_inline}}
-
-

Um projeto com propriedades protótipo como base para o elememento personalizado, e extends, uma existente tag para estender. Ambos são opcionais.

-
-
- -

Exemplo

- -

Aqui é um exemplo muito simples:

- -
var Mytag = document.registerElement('my-tag');
-
- -

Agora as novas tags são registradas no browser.

- -

Uma variável Mytag tem um construtor que você pode usar para criar um elemento my-tag nos documentos como seguem:

- -
document.body.appendChild(new Mytag());
- -

Isto insere um elemento vazio my-tag que será visível se você usar o browser para desenvolvedores. Isto não será visível se você usar a ferramenta visão da capacidade do código fonte do browser. E isto não será visível no browser a menos que você adicione alguns conteúdos para a tag. Aqui está um caminho para adicionar conteúdo a nova tag:

- -
var mytag = document.getElementsByTagName("my-tag")[0];
-mytag.textContent = "I am a my-tag element.";
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoEstadoComentário
{{SpecName('Custom Elements')}}{{Spec2('Custom Elements')}} -

definição inicial

-
- -

Compatibilidade do Browser

- -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - -
CaracterísticaChromeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico3531[1]{{CompatNo}}25{{CompatNo}}
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico4.4.431[1]{{CompatNo}}25{{CompatNo}}
-
- -

[1] Esta API é implementada uma preferência

- -

Veja também

- - diff --git a/files/pt-br/web/api/document/getselection/index.html b/files/pt-br/web/api/document/getselection/index.html deleted file mode 100644 index 2f52375799..0000000000 --- a/files/pt-br/web/api/document/getselection/index.html +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Document.getSelection() -slug: Web/API/Document/getSelection -translation_of: Web/API/DocumentOrShadowRoot/getSelection -translation_of_original: Web/API/Document/getSelection ---- -

{{APIRef("DOM")}}

- -

Esse método funciona de forma idêntica ao método {{domxref("Window.getSelection()")}};  Ele retorna um objeto {{domxref("Selection")}} representando o texto atualmente selecionado no documento.

diff --git a/files/pt-br/web/api/document/readystatechange_event/index.html b/files/pt-br/web/api/document/readystatechange_event/index.html new file mode 100644 index 0000000000..185350cb54 --- /dev/null +++ b/files/pt-br/web/api/document/readystatechange_event/index.html @@ -0,0 +1,83 @@ +--- +title: readystatechange +slug: Web/Events/readystatechange +translation_of: Web/API/Document/readystatechange_event +--- +

{{ApiRef}}

+ +

O evento readystatechange é ativado quando o atributo readyState de um documento é alterado.

+ +

Informações gerais

+ +
+
Especificação
+
HTML5
+
Interface
+
Event
+
Propaga
+
Não
+
Cancelável
+
Não
+
Alvo
+
Document
+
Ação Padrão
+
Nenhuma.
+
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}The event target (the topmost target in the DOM tree).
type {{readonlyInline}}{{domxref("DOMString")}}The type of event.
bubbles {{readonlyInline}}{{jsxref("Boolean")}}Whether the event normally bubbles or not.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}Whether the event is cancellable or not.
+ +

Exemplo

+ +
// alternativa ao DOMContentLoaded
+document.onreadystatechange = function () {
+    if (document.readyState == "interactive") {
+        initApplication();
+    }
+}
+
+ +

Compatibilidade entre Navegadores

+ +

Este evento tem sido suportado pelo Internet Explorer há várias versões, e pode ser usada como uma alternativa para o evento DOMContentLoaded (veja a seção cross-browser fallback).

+ +

Eventos Relacionados

+ + diff --git a/files/pt-br/web/api/document/registerelement/index.html b/files/pt-br/web/api/document/registerelement/index.html new file mode 100644 index 0000000000..bff318b3a9 --- /dev/null +++ b/files/pt-br/web/api/document/registerelement/index.html @@ -0,0 +1,132 @@ +--- +title: Document.registerElement() +slug: Web/API/Document/ElementoRegistrado +tags: + - DOM + - Document.registerElement() + - ELEMENTO DOM + - Web Components + - registerElement +translation_of: Web/API/Document/registerElement +--- +

{{APIRef("DOM")}}

+ +
+

Note:document.registerElement() está depreciado em favor do customElements.define().

+
+ +

O método document.registerElement() registra um novo elemento personalizado no browser e returna um construtor para o novo elemento.

+ +
+

Nota: Esta é uma tecnologia experimental. O browser você precisa usar suporte à componentes web. Veja Habilitando componentes web no Firefox.

+
+ +

Sintaxe

+ +
var constructor = document.registerElement(tag-name, options);
+ +

Parâmetros

+ +
+
tag-name
+
O nome do elemento personalizado. O nome precisa conter um dash (-), por exemplo minha-tag.
+
Opções{{optional_inline}}
+
+

Um projeto com propriedades protótipo como base para o elememento personalizado, e extends, uma existente tag para estender. Ambos são opcionais.

+
+
+ +

Exemplo

+ +

Aqui é um exemplo muito simples:

+ +
var Mytag = document.registerElement('my-tag');
+
+ +

Agora as novas tags são registradas no browser.

+ +

Uma variável Mytag tem um construtor que você pode usar para criar um elemento my-tag nos documentos como seguem:

+ +
document.body.appendChild(new Mytag());
+ +

Isto insere um elemento vazio my-tag que será visível se você usar o browser para desenvolvedores. Isto não será visível se você usar a ferramenta visão da capacidade do código fonte do browser. E isto não será visível no browser a menos que você adicione alguns conteúdos para a tag. Aqui está um caminho para adicionar conteúdo a nova tag:

+ +
var mytag = document.getElementsByTagName("my-tag")[0];
+mytag.textContent = "I am a my-tag element.";
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoEstadoComentário
{{SpecName('Custom Elements')}}{{Spec2('Custom Elements')}} +

definição inicial

+
+ +

Compatibilidade do Browser

+ +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + +
CaracterísticaChromeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico3531[1]{{CompatNo}}25{{CompatNo}}
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico4.4.431[1]{{CompatNo}}25{{CompatNo}}
+
+ +

[1] Esta API é implementada uma preferência

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/document_object_model/events/index.html b/files/pt-br/web/api/document_object_model/events/index.html new file mode 100644 index 0000000000..4d04915450 --- /dev/null +++ b/files/pt-br/web/api/document_object_model/events/index.html @@ -0,0 +1,82 @@ +--- +title: Events and the DOM +slug: DOM/Referencia_do_DOM/Events +translation_of: Web/API/Document_Object_Model/Events +--- +
{{DefaultAPISidebar("DOM")}}
+ +

Introdução

+ +

Este capítulo descreve o Modelo de Eventos do DOM. A interface de Eventos é descrita, assim como a interface para registro de eventos em nodes(ou nódulos) no DOM, e event listeners, e vários outros exemplos que mostram como diversas interfaces de evento se relacionam uma com a outraThere is an excellent diagram that clearly explains the three phases of event flow through the DOM in the DOM Level 3 Events draft.

+ +

Existe um excelente diagrama que explica claramente as três fases do percurso de eventos no DOM em DOM Level 3 Events draft.

+ +

Registrando event listeners

+ +

Existem 3 formas de registrar uma manipulação de eventos para um elemento DOM.

+ +

{{domxref("EventTarget.addEventListener")}}

+ +
// Assuming myButton is a button element
+myButton.addEventListener('click', greet, false)
+function greet(event){
+    // print and have a look at the event object
+    // always print arguments in case of overlooking any other arguments
+    console.log('greet:', arguments)
+    alert('hello world')
+}
+
+ +

Este é o método que você deve usar em páginas web modernas.

+ +
+

Nota: Internet Explorer 6–8 não suportavam este método, oferecendo uma API {{domxref("EventTarget.attachEvent")}} parecida no lugar. Para compatibilidade cross-browser, use uma das muitas bibliotecas JavaScript disponíveis.

+
+ +

Mais detalhes podem encontrada na página de referência {{domxref("EventTarget.addEventListener")}}.

+ +

atributo HTML

+ +
<button onclick="alert('Hello world!')">
+
+ +

O código JavaScript no atributo é passado para o objeto Evento através do parâmetro event . O valor return é tratado de uma maneira especial, descrita na especificação HTML.

+ +
+

Cuidado: Este método deve ser evitado! Ele suja a marcação, e a faz menos legível. Preocupações com o conteúdo/estrutura e comportamento não são bem separadas, tornando mais díficil encontrar um bug.

+
+ +

DOM element properties

+ +
// Supondo que myButton seja um elemento button
+myButton.onclick = function(event){alert('Hello world')}
+
+ +

A função pode ser definida para receber um parâmetro event . O valor return é tratado de maneira especial, descrita na especificação HTML.

+ +

O problema deste método é que apenas uma manipulação pode ser definida por elemento e por evento.

+ +

Acessando interfaces doEvento

+ +

Manipulações do Evento podem ser atribuídas a vários objetos (incluindo elementos DOM, documentos, o {{domxref("window")}} object, etc.). Quando um evento ocorre, o objeto do evento é criado e passado sequencialmente ao event listeners.

+ +

A interface {{domxref("Event")}} é acessível de dentro da função manipuladora, atrás do objeto evento passado como primeiro argumento. O seguinte exemplo simples mostra como um objeto evento é passado á função manipuladora do evento, e pode usado de dentro de tal função.

+ +
function print(evt) {
+  // the evt parameter is automatically assigned the event object
+  // take care of the differences between console.log & alert
+  console.log('print:', evt)
+  alert(evt)
+}
+// any function should have an appropriate name, that's what called semantic
+table_el.onclick = print
+
+ + + + diff --git a/files/pt-br/web/api/document_object_model/examples/index.html b/files/pt-br/web/api/document_object_model/examples/index.html new file mode 100644 index 0000000000..87ec3601e2 --- /dev/null +++ b/files/pt-br/web/api/document_object_model/examples/index.html @@ -0,0 +1,376 @@ +--- +title: Examples of web and XML development using the DOM +slug: DOM/Referencia_do_DOM/Examples +translation_of: Web/API/Document_Object_Model/Examples +--- +

Este capítulo fornece exemplos mais longos de desenvolvimento de Web e XML usando o DOM. Sempre que possível, os exemplos usam APIs, truques e padrões comuns no JavaScript para manipular o objeto de documento.

+ +

Exemplo 1: altura e largura

+ +

O exemplo a seguir mostra o uso das propriedades de altura e largura ao lado de imagens de dimensões variáveis:

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>width/height example</title>
+<script>
+function init() {
+  var arrImages = new Array(3);
+
+  arrImages[0] = document.getElementById("image1");
+  arrImages[1] = document.getElementById("image2");
+  arrImages[2] = document.getElementById("image3");
+
+  var objOutput = document.getElementById("output");
+  var strHtml = "<ul>";
+
+  for (var i = 0; i < arrImages.length; i++) {
+    strHtml += "<li>image" + (i+1) +
+            ": height=" + arrImages[i].height +
+            ", width=" + arrImages[i].width +
+            ", style.height=" + arrImages[i].style.height +
+            ", style.width=" + arrImages[i].style.width +
+            "<\/li>";
+  }
+
+  strHtml += "<\/ul>";
+
+  objOutput.innerHTML = strHtml;
+}
+</script>
+</head>
+<body onload="init();">
+
+<p>Image 1: no height, width, or style
+  <img id="image1" src="http://www.mozilla.org/images/mozilla-banner.gif">
+</p>
+
+<p>Image 2: height="50", width="500", but no style
+  <img id="image2"
+       src="http://www.mozilla.org/images/mozilla-banner.gif"
+       height="50" width="500">
+</p>
+
+<p>Image 3: no height, width, but style="height: 50px; width: 500px;"
+  <img id="image3"
+       src="http://www.mozilla.org/images/mozilla-banner.gif"
+       style="height: 50px; width: 500px;">
+</p>
+
+<div id="output"> </div>
+</body>
+</html>
+
+ +

Exemplo 2: Atributos de Imagem

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>Modifying an image border</title>
+
+<script>
+function setBorderWidth(width) {
+  document.getElementById("img1").style.borderWidth = width + "px";
+}
+</script>
+</head>
+
+<body>
+<p>
+  <img id="img1"
+       src="image1.gif"
+       style="border: 5px solid green;"
+       width="100" height="100" alt="border test">
+</p>
+
+<form name="FormName">
+  <input type="button" value="Make border 20px-wide" onclick="setBorderWidth(20);" />
+  <input type="button" value="Make border 5px-wide"  onclick="setBorderWidth(5);" />
+</form>
+
+</body>
+</html>
+
+ +

Exemplo 3: Manipulando Estilos

+ +

Neste exemplo simples, algumas propriedades de estilo básicas de um elemento de parágrafo HTML são acessadas usando o objeto de estilo no elemento e as propriedades de estilo CSS do objeto, que podem ser recuperadas e definidas a partir do DOM. Neste caso, você está manipulando os estilos individuais diretamente. No próximo exemplo (veja Exemplo 4), você pode usar folhas de estilo e suas regras para alterar estilos para documentos inteiros.

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>Changing color and font-size example</title>
+
+<script>
+function changeText() {
+  var p = document.getElementById("pid");
+
+  p.style.color = "blue"
+  p.style.fontSize = "18pt"
+}
+</script>
+</head>
+<body>
+
+<p id="pid" onclick="window.location.href = 'http://www.cnn.com/';">linker</p>
+
+<form>
+  <p><input value="rec" type="button" onclick="changeText();" /></p>
+</form>
+
+</body>
+</html>
+
+ +

Exemplo 4: Usando folhas de estilo

+ +

A propriedade styleSheets no objeto de documento retorna uma lista das folhas de estilo que foram carregadas nesse documento. Você pode acessar essas folhas de estilo e suas regras individualmente usando os objetos stylesheet, style e CSSRule, como demonstrado neste exemplo, que imprime todos os seletores de regras de estilo para o console.

+ +
var ss = document.styleSheets;
+
+for(var i = 0; i < ss.length; i++) {
+  for(var j = 0; j < ss[i].cssRules.length; j++) {
+    dump( ss[i].cssRules[j].selectorText + "\n" );
+  }
+}
+ +

Para um documento com uma única folha de estilo na qual as três regras a seguir são definidas:

+ +
body { background-color: darkblue; }
+p { font-face: Arial; font-size: 10pt; margin-left: .125in; }
+#lumpy { display: none; }
+
+ +

Este script produz o seguinte:

+ +
BODY
+P
+#LUMPY
+
+ +

 

+ +

Exemplo 5: Propagação de Eventos

+ +

Este exemplo demonstra como eventos disparar e são tratados no DOM de uma forma muito simples. Quando o corpo deste documento HTML é carregado, um ouvinte de evento é registrado com a linha superior da tabela. O ouvinte de eventos processa o evento executando a função stopEvent, que altera o valor na célula inferior da tabela.

+ +

No entanto, stopEvent também chama um método de objeto de evento, {{domxref ("event.stopPropagation")}}, que mantém o evento de borbulhar mais para cima no DOM. Observe que a própria tabela possui um manipulador de eventos {{domxref ("element.onclick", "onclick")}} que deve exibir uma mensagem quando a tabela é clicada. Mas o método stopEvent interrompeu a propagação e, portanto, após a atualização dos dados na tabela, a fase de evento é efetivamente encerrada e uma caixa de alerta é exibida para confirmar isso.

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>Event Propagation</title>
+
+<style>
+#t-daddy { border: 1px solid red }
+#c1 { background-color: pink; }
+</style>
+
+<script>
+function stopEvent(ev) {
+  c2 = document.getElementById("c2");
+  c2.innerHTML = "hello";
+
+  // this ought to keep t-daddy from getting the click.
+  ev.stopPropagation();
+  alert("event propagation halted.");
+}
+
+function load() {
+  elem = document.getElementById("tbl1");
+  elem.addEventListener("click", stopEvent, false);
+}
+</script>
+</head>
+
+<body onload="load();">
+
+<table id="t-daddy" onclick="alert('hi');">
+  <tr id="tbl1">
+    <td id="c1">one</td>
+  </tr>
+  <tr>
+    <td id="c2">two</td>
+  </tr>
+</table>
+
+</body>
+</html>
+
+ +

Exemplo 6: getComputedStyle

+ +

Este exemplo demonstra como o método {{domxref ("window.getComputedStyle")}} pode ser usado para obter os estilos de um elemento que não são definidos usando o atributo de estilo ou com JavaScript (por exemplo, elt.style.backgroundColor = "rgb (173, 216, 230) "). Estes últimos tipos de estilos podem ser recuperados com a propriedade {{domxref ("element.style", "elt.style")}} mais direta, cujas propriedades estão listadas na Lista de Propriedades do DOM CSS.

+ +

GetComputedStyle() retorna um objeto ComputedCSSStyleDeclaration, cujas propriedades de estilo individuais podem ser referenciadas com o método getPropertyValue() desse objeto, como mostra o seguinte exemplo de documento.

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+
+<title>getComputedStyle example</title>
+
+<script>
+function cStyles() {
+  var RefDiv = document.getElementById("d1");
+  var txtHeight = document.getElementById("t1");
+  var h_style = document.defaultView.getComputedStyle(RefDiv, null).getPropertyValue("height");
+
+  txtHeight.value = h_style;
+
+  var txtWidth = document.getElementById("t2");
+  var w_style = document.defaultView.getComputedStyle(RefDiv, null).getPropertyValue("width");
+
+  txtWidth.value = w_style;
+
+  var txtBackgroundColor = document.getElementById("t3");
+  var b_style = document.defaultView.getComputedStyle(RefDiv, null).getPropertyValue("background-color");
+
+  txtBackgroundColor.value = b_style;
+}
+</script>
+
+<style>
+#d1 {
+  margin-left: 10px;
+  background-color: rgb(173, 216, 230);
+  height: 20px;
+  max-width: 20px;
+}
+</style>
+
+</head>
+
+<body>
+
+<div id="d1">&nbsp;</div>
+
+<form action="">
+  <p>
+    <button type="button" onclick="cStyles();">getComputedStyle</button>
+    height<input id="t1" type="text" value="1" />
+    max-width<input id="t2" type="text" value="2" />
+    bg-color<input id="t3" type="text" value="3" />
+  </p>
+</form>
+
+</body>
+</html>
+
+ +

Exemplo 7: Exibindo Propriedades de Evento do Objeto

+ +

Este exemplo usa métodos DOM para exibir todas as propriedades do objeto {{domxref ("window.onload")}} {{domxref ("evento")}} e seus valores em uma tabela. Ele também mostra uma técnica útil de usar um laço para iterar sobre as propriedades de um objeto para obter seus valores.

+ +

As propriedades dos objetos de evento diferem muito entre os navegadores, o WHATWG DOM Standard lista as propriedades padrão, porém muitos navegadores estenderam muito esses valores.

+ +

Coloque o seguinte código em um arquivo de texto em branco e carregue-o em uma variedade de navegadores, você ficará surpreso com o número diferente e nomes de propriedades. Você também pode querer adicionar alguns elementos na página e chamar essa função de manipuladores de eventos diferentes.

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>Show Event properties</title>
+
+<style>
+table { border-collapse: collapse; }
+thead { font-weight: bold; }
+td { padding: 2px 10px 2px 10px; }
+
+.odd { background-color: #efdfef; }
+.even { background-color: #ffffff; }
+</style>
+
+<script>
+
+function showEventProperties(e) {
+  function addCell(row, text) {
+    var cell = row.insertCell(-1);
+    cell.appendChild(document.createTextNode(text));
+  }
+
+  var e = e || window.event;
+  document.getElementById('eventType').innerHTML = e.type;
+
+  var table = document.createElement('table');
+  var thead = table.createTHead();
+  var row = thead.insertRow(-1);
+  var lableList = ['#', 'Property', 'Value'];
+  var len = lableList.length;
+
+  for (var i=0; i<len; i++) {
+    addCell(row, lableList[i]);
+  }
+
+  var tbody = document.createElement('tbody');
+  table.appendChild(tbody);
+
+  for (var p in e) {
+    row = tbody.insertRow(-1);
+    row.className = (row.rowIndex % 2)? 'odd':'even';
+    addCell(row, row.rowIndex);
+    addCell(row, p);
+    addCell(row, e[p]);
+  }
+
+  document.body.appendChild(table);
+}
+
+window.onload = function(event){
+  showEventProperties(event);
+}
+</script>
+</head>
+
+<body>
+<h1>Properties of the DOM <span id="eventType"></span> Event Object</h1>
+</body>
+
+</html>
+
+ +

Exemplo 8: Usando a interface de tabela  do DOM

+ +

A interface DOM HTMLTableElement fornece alguns métodos de conveniência para criar e manipular tabelas. Dois métodos usados com freqüência são {{domxref ("HTMLTableElement.insertRow")}} e {{domxref ("tableRow.insertCell")}}.

+ +

Para adicionar uma linha e algumas células a uma tabela existente:

+ +
<table id="table0">
+ <tr>
+  <td>Row 0 Cell 0</td>
+  <td>Row 0 Cell 1</td>
+ </tr>
+</table>
+
+<script>
+var table = document.getElementById('table0');
+var row = table.insertRow(-1);
+var cell,
+    text;
+
+for (var i = 0; i < 2; i++) {
+  cell = row.insertCell(-1);
+  text = 'Row ' + row.rowIndex + ' Cell ' + i;
+  cell.appendChild(document.createTextNode(text));
+}
+</script>
+
+ +


+ Notas

+ + + + + + diff --git a/files/pt-br/web/api/document_object_model/how_to_create_a_dom_tree/index.html b/files/pt-br/web/api/document_object_model/how_to_create_a_dom_tree/index.html new file mode 100644 index 0000000000..e6dd923fb5 --- /dev/null +++ b/files/pt-br/web/api/document_object_model/how_to_create_a_dom_tree/index.html @@ -0,0 +1,145 @@ +--- +title: How to create a DOM tree +slug: DOM/Referencia_do_DOM/How_to_create_a_DOM_tree +translation_of: Web/API/Document_object_model/How_to_create_a_DOM_tree +--- +

{{draft}}

+ +

Esta página descreve como usar DOM Core API DOM em JavaScript para criar e modificar objetos do DOM. Aplica-se a todas as aplicações baseadas em Gecko (como o Firefox), tanto em código privilegiado (extensões) como em código não privilegiado (páginas web)

+ +

Criando uma árvore DOM dinamicamente

+ +

Considere o seguinte documento XML:

+ +
<?xml version="1.0"?>
+<people>
+  <person first-name="eric" middle-initial="H" last-name="jung">
+    <address street="321 south st" city="denver" state="co" country="usa"/>
+    <address street="123 main st" city="arlington" state="ma" country="usa"/>
+  </person>
+
+  <person first-name="jed" last-name="brown">
+    <address street="321 north st" city="atlanta" state="ga" country="usa"/>
+    <address street="123 west st" city="seattle" state="wa" country="usa"/>
+    <address street="321 south avenue" city="denver" state="co" country="usa"/>
+  </person>
+</people>
+
+ +

A W3C DOM API, suportada pelo Mozilla, pode ser usada para criar uma representação na memória deste documento, da seguinte forma:

+ +
var doc = document.implementation.createDocument("", "", null);
+var peopleElem = doc.createElement("people");
+
+var personElem1 = doc.createElement("person");
+personElem1.setAttribute("first-name", "eric");
+personElem1.setAttribute("middle-initial", "h");
+personElem1.setAttribute("last-name", "jung");
+
+var addressElem1 = doc.createElement("address");
+addressElem1.setAttribute("street", "321 south st");
+addressElem1.setAttribute("city", "denver");
+addressElem1.setAttribute("state", "co");
+addressElem1.setAttribute("country", "usa");
+personElem1.appendChild(addressElem1);
+
+var addressElem2 = doc.createElement("address");
+addressElem2.setAttribute("street", "123 main st");
+addressElem2.setAttribute("city", "arlington");
+addressElem2.setAttribute("state", "ma");
+addressElem2.setAttribute("country", "usa");
+personElem1.appendChild(addressElem2);
+
+var personElem2 = doc.createElement("person");
+personElem2.setAttribute("first-name", "jed");
+personElem2.setAttribute("last-name", "brown");
+
+var addressElem3 = doc.createElement("address");
+addressElem3.setAttribute("street", "321 north st");
+addressElem3.setAttribute("city", "atlanta");
+addressElem3.setAttribute("state", "ga");
+addressElem3.setAttribute("country", "usa");
+personElem2.appendChild(addressElem3);
+
+var addressElem4 = doc.createElement("address");
+addressElem4.setAttribute("street", "123 west st");
+addressElem4.setAttribute("city", "seattle");
+addressElem4.setAttribute("state", "wa");
+addressElem4.setAttribute("country", "usa");
+personElem2.appendChild(addressElem4);
+
+var addressElem5 = doc.createElement("address");
+addressElem5.setAttribute("street", "321 south avenue");
+addressElem5.setAttribute("city", "denver");
+addressElem5.setAttribute("state", "co");
+addressElem5.setAttribute("country", "usa");
+personElem2.appendChild(addressElem5);
+
+peopleElem.appendChild(personElem1);
+peopleElem.appendChild(personElem2);
+doc.appendChild(peopleElem);
+
+ +

Veja também o capítulo DOM chapter of the XUL Tutorial.

+ +

Você pode automatizar a criação de uma árvore DOM usando um algoritmo reverso JXON em associação com a seguinte representação JSON:

+ +
{
+  "people": {
+    "person": [{
+      "address": [{
+        "@street": "321 south st",
+        "@city": "denver",
+        "@state": "co",
+        "@country": "usa"
+      }, {
+        "@street": "123 main st",
+        "@city": "arlington",
+        "@state": "ma",
+        "@country": "usa"
+      }],
+      "@first-name": "eric",
+      "@middle-initial": "H",
+      "@last-name": "jung"
+    }, {
+      "address": [{
+        "@street": "321 north st",
+        "@city": "atlanta",
+        "@state": "ga",
+        "@country": "usa"
+      }, {
+        "@street": "123 west st",
+        "@city": "seattle",
+        "@state": "wa",
+        "@country": "usa"
+      }, {
+        "@street": "321 south avenue",
+        "@city": "denver",
+        "@state": "co",
+        "@country": "usa"
+      }],
+      "@first-name": "jed",
+      "@last-name": "brown"
+    }]
+  }
+}
+
+ +

E daí?

+ +

As árvores DOM podem ser consultadas usando expressões XPath, convertidas em strings ou gravadas em arquivos locais ou remotos usando XMLSerializer (sem ter que primeiro converter para uma string), POSTed para um servidor web (via XMLHttpRequest), transformado usando XSLT, XLink, convertido para um objeto JavaScript através de um algoritmo JXON, etc.

+ +

Você pode usar árvores DOM para modelar dados que não são adequados para RDF (ou talvez você simplesmente não goste de RDF). Outra aplicação é que, uma vez que XUL é XML, a UI de sua aplicação pode ser manipulada, baixada, carregada, salva, carregada, convertida ou transformada de forma bastante fácil.

+ +

Veja também

+ + + +

{{ languages( { "fr": "fr/Comment_cr\u00e9er_un_arbre_DOM", "ja": "ja/How_to_create_a_DOM_tree", "zh-cn": "zh-cn/How_to_create_a_DOM_tree" } ) }}

diff --git a/files/pt-br/web/api/document_object_model/index.html b/files/pt-br/web/api/document_object_model/index.html new file mode 100644 index 0000000000..b0ae4420a6 --- /dev/null +++ b/files/pt-br/web/api/document_object_model/index.html @@ -0,0 +1,379 @@ +--- +title: Modelo de Objeto de Documento (DOM) +slug: DOM/Referencia_do_DOM +translation_of: Web/API/Document_Object_Model +--- +

{{DefaultAPISidebar("DOM")}}

+ +

O Modelo de Objeto de Documento  (DOM) é uma interface de programação para documentos HTML, XML e SVG . Ele fornece uma representação estruturada do documento como uma árvore. O DOM define métodos que permitem acesso à árvore, para que eles possam alterar a estrutura, estilo e conteúdo do documento. O DOM fornece uma representação do documento como um grupo estruturado de nós e objetos, possuindo várias propriedades e métodos. Os nós também podem ter manipuladores de eventos que lhe são inerentes, e uma vez que um evento é acionado, os manipuladores de eventos são executados. Essencialmente, ele conecta páginas web a scripts ou linguagens de programação.

+ +

Embora o DOM seja frequentemente acessado usando JavaScript, não é uma parte da linguagem JavaScript. Ele também pode ser acessado por outras linguagens.

+ +

Uma introdução ao DOM está disponível.

+ +

DOM interfaces

+ +
+ +
+ +

Interfaces DOM obsoletas

+ +

O Modelo de Objeto de Documento foi altamente simplificado. Para conseguir isso, as seguintes interfaces presentes na especificação DOM nível 3 ou especificação anterior foi removida. Ainda não está muito claro se alguns podem ser reintroduzidos ou não, mas por enquanto eles têm que ser considerados obsoletos e devem ser evitados:

+ +
+ +
+ +

Interfaces HTML

+ +

Um documento contendo HTML é descrito usando o {{domxref("HTMLDocument")}} interface. Nota-se que a especificação HTML também se extende a {{domxref("Document")}} interface.

+ +

Um objeto HTMLDocument também da acesso á vários recursos de navegadores como a aba ou janela, em que uma página é desenhada usando {{domxref("Window")}} interface, o {{domxref("window.style", "Style")}} associado a ele (normalmente CSS), a história do navegador relativa ao contexto, {{domxref("window.history", "History")}}. Eventualmente, {{domxref("Selection")}} é feito no documento.

+ +

HTML elemento interfaces

+ +
+ +
+ +

Outras interfaces

+ +
+ +
+ +

Obsoleto HTML interfaces

+ +
+ +
+ +

SVG interfaces

+ +

SVG elemento  interfaces

+ +
+ +
+ +

SVG data type interfaces

+ +

Aqui estão a DOM API para tipos de dados utilizados nas definições de propriedades SVG e atributos.

+ +
+

Nota: Starting in {{Gecko("5.0")}}, the following SVG-related DOM interfaces representing lists of objects are now indexable and can be accessed ; in addition, they have a length property indicating the number of items in the lists: {{domxref("SVGLengthList")}}, {{domxref("SVGNumberList")}}, {{domxref("SVGPathSegList")}}, and {{domxref("SVGPointList")}}.

+
+ +

Static type

+ +
+ +
+ +

Animated type

+ +
+ +
+ + + +
+ +
+ +

Other SVG interfaces

+ +
+ +
+ +

Veja também

+ + diff --git a/files/pt-br/web/api/document_object_model/introduction/index.html b/files/pt-br/web/api/document_object_model/introduction/index.html new file mode 100644 index 0000000000..010a5ecd54 --- /dev/null +++ b/files/pt-br/web/api/document_object_model/introduction/index.html @@ -0,0 +1,251 @@ +--- +title: Introdução ao DOM +slug: DOM/Referencia_do_DOM/Introdução +translation_of: Web/API/Document_Object_Model/Introduction +--- +

O DOM (Document Object Model) é a representação de dados dos objetos que compõem a estrutura e o conteúdo de um documento na Web. Neste guia, apresentaremos brevemente o DOM. Veremos como o DOM representa um documento {{Glossary ("HTML")}} ou {{Glossary ("XML")}} na memória e como você usa APIs para criar aplicativos e conteúdo da Web.

+ +

O que é o DOM?

+ +

O Document Object Model (DOM) é uma interface de programação para os documentos HTML e XML. Representa a página de forma que os programas possam alterar a estrutura do documento, alterar o estilo e conteúdo. O DOM representa o documento com nós e objetos, dessa forma, as linguagens de programação podem se conectar à página.

+ +

Uma página da Web é um documento. Este documento pode ser exibido na janela do navegador ou como a fonte HTML. Mas é o mesmo documento nos dois casos. O DOM (Document Object Model) representa o mesmo documento para que possa ser manipulado. O DOM é uma representação orientada a objetos da página da web, que pode ser modificada com uma linguagem de script como JavaScript.

+ +

Os padrões W3C DOM e WHATWG DOM são implementados na maioria dos navegadores modernos. Muitos navegadores estendem o padrão; portanto, é necessário ter cuidado ao usá-los na Web, onde os documentos podem ser acessados por vários navegadores com diferentes DOMs.

+ +

Por exemplo, o DOM padrão especifica que o método getElementsByTagName no código abaixo deve retornar uma lista de todos os elementos <p> no documento:

+ +
var paragraphs = document.getElementsByTagName("p");
+// paragraphs[0] is the first <p> element
+// paragraphs[1] is the second <p> element, etc.
+alert(paragraphs[0].nodeName);
+
+ +

Todas as propriedades, métodos e eventos disponíveis para manipular e criar páginas da Web são organizados em objetos (por exemplo, o objeto de document que representa o próprio documento, o objeto de table que implementa a Interface especial DOM {{domxref ("HTMLTableElement")}}}}  para acessar tabelas HTML e assim por diante). Esta documentação fornece uma referência objeto a objeto ao DOM.

+ +

O DOM moderno é construído usando várias APIs que trabalham juntas. O DOM principal define os objetos que descrevem fundamentalmente um documento e os objetos dentro dele. Isso é expandido conforme necessário por outras APIs que adicionam novos recursos e capacidades ao DOM. Por exemplo, a HTML DOM API adiciona suporte para representar documentos HTML no DOM principal.

+ +

DOM e JavaScript

+ +

O pequeno exemplo acima, como quase todos os exemplos nesta referência, é {{glossary ("JavaScript")}}. Ou seja, está escrito em JavaScript, mas usa o DOM para acessar o documento e seus elementos. O DOM não é uma linguagem de programação, mas sem ela, a linguagem JavaScript não teria nenhum modelo ou noção de páginas da web, documentos HTML, documentos XML e suas partes componentes (por exemplo, elementos). Cada elemento de um documento - o documento como um todo, o cabeçalho, as tabelas do documento, os cabeçalhos da tabela, o texto nas células da tabela - faz parte do modelo de objeto do documento desse documento, para que todos possam ser acessados e manipulados usando o método DOM e uma linguagem de script como JavaScript.

+ +

No início, o JavaScript e o DOM estavam fortemente interligados, mas, eventualmente, evoluíram para entidades separadas. O conteúdo da página é armazenado no DOM e pode ser acessado e manipulado via JavaScript, para que possamos escrever esta equação aproximada:

+ +

API (página HTML ou XML) = DOM + JS (linguagem de script)

+ +

O DOM foi projetado para ser independente de qualquer linguagem de programação específica, disponibilizando a representação estrutural do documento a partir de uma única API consistente. Embora nos concentremos exclusivamente no JavaScript nesta documentação de referência, as implementações do DOM podem ser construídas para qualquer idioma, como este exemplo em Python demonstra:

+ +
# exemplo de DOM com Python
+import xml.dom.minidom as m
+doc = m.parse(r"C:\Projects\Py\chap1.xml")
+doc.nodeName # propriedade do objeto de documento DOM
+p_list = doc.getElementsByTagName("para")
+
+ +

Para obter mais informações sobre quais tecnologias estão envolvidas na criação de JavaScript na Web, consulte JavaScript technologies overview.

+ +

Acessando o DOM

+ +

Você não precisa fazer nada de especial para começar a usar o DOM. Navegadores diferentes têm implementações diferentes do DOM, e essas implementações exibem graus variados de conformidade com o padrão DOM real (um assunto que tentamos evitar nesta documentação), mas todo navegador usa um modelo de objeto de documento para tornar as páginas da web acessíveis via JavaScript.

+ +

Quando você cria um script - seja embutido em um elemento(tag) <script> ou incluído na página da web por meio de uma instrução de carregamento de script - você pode começar imediatamente a usar a API para o {{domxref ("document")}} ou { {domxref ("Window", "window")}} elementos para manipular o próprio documento ou obter os filhos desse documento, que são os vários elementos na página da web. Sua programação DOM pode ser algo tão simples quanto o exemplo seguinte, que exibe uma mensagem de alerta usando a função {{domxref ("window.alert", "alert()")}} da função {{domxref ("Window", " window ")}} ou pode usar métodos DOM mais sofisticados para criar realmente novo conteúdo, como no extenso exemplo abaixo.

+ +

O JavaScript a seguir exibirá um alerta quando o documento for carregado (e quando todo o DOM estiver disponível para uso):

+ +
<body onload="window.alert('Welcome to my home page!');">
+
+ +

Outro exemplo. Esta função cria um novo elemento H1, adiciona texto a esse elemento e, em seguida, adiciona o H1 à árvore deste documento:

+ +
<html>
+  <head>
+    <script>
+       // run this function when the document is loaded
+       window.onload = function() {
+
+         // create a couple of elements in an otherwise empty HTML page
+         var heading = document.createElement("h1");
+         var heading_text = document.createTextNode("Big Head!");
+         heading.appendChild(heading_text);
+         document.body.appendChild(heading);
+      }
+    </script>
+  </head>
+  <body>
+  </body>
+</html>
+
+ +

Tipos de dados fundamentais

+ +

Esta referência tenta descrever os vários objetos e tipos em termos simples. Mas há vários tipos de dados diferentes sendo transmitidos pela API que você deve conhecer.

+ +
+

Nota: Como a grande maioria do código que usa o DOM gira em torno da manipulação de documentos HTML, é comum sempre se referir aos nós no DOM como elementos, pois em um documento HTML, cada nó é um elemento. Apesar de não ser estritamente precisa, a documentação que você encontrará no MDN frequentemente fará a mesma coisa, por causa de quão comum é essa suposição.

+
+ +

A tabela a seguir descreve brevemente esses tipos de dados.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Tipos de dados (Interface)Descrição
{{domxref("Document")}}Quando um membro retorna um objeto do tipo document (por exemplo, a propriedade ownerDocument de um elemento retorna o document ao qual ele pertence),esse objeto é o próprio objeto de  document raiz. O capítulo DOM document Reference descreve o objeto do document .
{{domxref("Node")}}Todo objeto localizado em um documento é um nó de algum tipo. Em um documento HTML, um objeto pode ser um nó de elemento, mas também um nó de texto ou atributo.
{{domxref("Element")}} +

O tipo do element é baseado em node. Isso se refere a um elemento ou um nó do tipo element retornado por um membro do DOM API. Ao invés de dizer, por exemplo, que o método {{domxref("document.createElement()")}}  retorna um objeto de referência para um nó, nós apenas dizemos que esse método retorna o element que acabou de ser criado no DOM. Os objetos do element  implementam a interface DOM Element e também a mais básica interface Node, sendo ambas incluídas juntas nessa referência. Em um documento HTML, elementos são ainda mais aprimorados pelas APIs HTML DOM. A interface {{domxref("HTMLElement")}} bem como outras interfaces descrevem capacidades de tipos especifícos de elementos (por exemlo, {{domxref("HTMLTableElement")}} para elementos {{HTMLElement("table")}}).

+
{{domxref("NodeList")}}Uma nodeList é um array de elementos comos os que são retornados pelo método {{domxref("document.getElementsByTagName()")}}. Itens numa nodeList são acessados por índices em uma das duas formas: +
    +
  • list.item(1)
    • +
  • list[1]
    • +
+ Esses dois são equivalentes. No primeiro, item() é o método único no objeto da nodeList. O último  usa uma sintaxe típica de array para buscar o segundo item na lista.
{{domxref("Attribute")}}Quando um attribute é retornado por um membro (por exemplo, pelo método createAttribute()), é um objeto de referência que expõe uma interface especial (embora pequena) para atributos. Atributos são nós no DOM bem como elementos, mesmo que raramente você possa usá-los como tal.
{{domxref("NamedNodeMap")}} +

 é como um array, mas os itens são acessados por nome ou índice, embora este último caso seja meramente uma conveniência para enumeração, já que eles não estão em uma ordem específica na lista. Um namedNodeMap possui um método item () para esse propósito, e você também pode adicionar e remover itens de um namedNodeMap.

+ +

Um namedNodeMap é como um array, mas os itens são acessados por nome ou índice, embora este último caso seja meramente uma conveniência para enumeração, já que eles não estão em uma ordem específica na lista. O namedNodeMap possui um método item() para esse propósito, e você também pode adicionar e remover itens de um namedNodeMap.

+
+ +

Tenha em mente algumas considerações de terminologia comuns que existem. É comum referir-se a qualquer nó {{domxref("Attribute")}} simplesmente como um attribute, por exemplo, e referir-se a um array de nós DOM como um nodeList. Você encontrará esses termos e outros a serem introduzidos e usados em toda a documentação.

+ +

DOM interfaces

+ +

Esse guia é sobre os objetos e o que você pode usar ao manipular a hierarquia do DOM. Há muitos aspectos que tornam entender como eles funcionam confuso. Por exemplo, o objeto representando o elemento HTML form pega a propriedade name da interface do HTMLFormElement mas a sua propriedade className vem da interface HTMLElement. Em ambos os casos, a propriedade que você quer está naquele objeto do formulário.

+ +

Mas o relacionamento entre objetos e interfaces que são implementadas no DOM pode ser confuso, então essa seção busca mostrar um pouco sobre as interfaces na especificação do DOM e como elas são disponibilizadas.

+ +

Interfaces e Objetos

+ +

Muitos objetos pegam emprestados de várias interfaces diferentes. O objeto table por exemplo implementa uma interface especializada {{domxref("HTMLTableElement")}}, que inclui métodos como createCaption e insertRow. Mas como é também um elemento HTML, table implementa a interface Element descrita no capítulo DOM {{domxref("Element")}} Reference. E finalmente, já que um elemento HTML é também, no que diz respeito ao DOM, um nó na árvore de nós que fazem o modelo de objeto para uma página HTML ou XML, o objeto table também implementa a interface Node mais básica, de onde deriva Element.

+ +

Quando você pegar a referência para um objeto table, como no exemplo a seguir, você rotineiramente usa todas as três interfaces de forma intercambiável no objeto, talvez sem saber.

+ +
var tabela = document.getElementById("table");
+var atributosTabela = tabela.attributes; // interface Node/Element
+for (var i = 0; i < atributosTabela.length; i++) {
+  // interface HTMLTableElement: atributo border
+  if (atributosTabela[i].nodeName.toLowerCase() == "border")
+    tabela.border = "1";
+}
+// interface HTMLTableElement: atributo summary
+table.summary = "nota: aumento de borda";
+
+ +

Interfaces Core no DOM

+ +

Essa seção lista algumas das interfaces mais utilizadas no DOM. A ideia não é descrever o que essas APIs fazem aqui mas para te dar uma ideia de que tipos de métodos e propriedades você verá bastante conforme for usando o DOM. Essas APIs são usadas nos exemplos mais extensos no capítulo de DOM Examples ao fim desse livro.

+ +

Objetos Document e window são os objetos cujas interfaces você geralmente utiliza mais frequentemente em programação DOM. De forma simples, o objeto window representa algo como o browser, e o objeto document é a raiz de todo o documento em si. Element herda dessa interface Node genérica, e juntamente com essas duas interfaces fornecem muitos dos métodos e propriedades que você utiliza em elementos individuais. Esses elementos podem também ter interfaces específicas para lidar com o tipo de dado que esses elementos contêm, como no exemplo do objeto table na seção anterior.

+ +

A seguir uma lista breve de APIs comuns em scripting de páginas web e XML usando o DOM.

+ + + +

Testando a DOM API

+ +

Esse documento fornece amostras para cada interface que você pode usar ao desenvolver. Em alguns casos, as amostras são páginas completas em HTML, com o acesso ao DOM em um elemento <script>, a interface (ex. botões) necessária para ativar o script num formulário, e os elementos HTML pelo qual o DOM opera listados também. Quando esse é o caso, você pode copiar e colar o exemplo em um novo documento HTML, salvar e rodar o exemplo pelo browser.

+ +

Há alguns casos, porém, que os exemplos são mais concisos. Para rodar exemplos que apenas demonstram o relacionamento básico da interface para os elementos HTML, você pode criar uma página teste em que as interfaces podem ser fácilmente acessadas por scripts. A simples página web a seguir fornece um elemento <script> no header em que você pode colocar funções para testar a interface, alguns elementos HTML com atributos que você consegue buscar, definir ou manipular, e a interface web do usuário necessária para chamar essas funções pelo broswer.

+ +

Você pode usar essa página teste ou criar uma similar para testar as interfaces DOM que quiser e ver como elas funcionam numa plataforma broswer. Você pode alterar os conteúdos da função test() como achar necessário, criar mais botões ou adicionar elementos se necessário.

+ +
<html>
+  <head>
+    <title>Testes DOM</title>
+    <script type="application/javascript">
+    function setBodyAttr(attr, value){
+      if (document.body) eval('document.body.'+attr+'="'+value+'"');
+      else notSupported();
+    }
+    </script>
+  </head>
+  <body>
+    <div style="margin: .5in; height: 400;">
+      <p><b><tt>text</tt></b></p>
+      <form>
+        <select onChange="setBodyAttr('text',
+        this.options[this.selectedIndex].value);">
+          <option value="black">preto
+          <option value="darkblue">azul escuro
+        </select>
+        <p><b><tt>bgColor</tt></b></p>
+        <select onChange="setBodyAttr('bgColor',
+        this.options[this.selectedIndex].value);">
+          <option value="white">branco
+          <option value="lightgrey">cinza
+        </select>
+        <p><b><tt>link</tt></b></p>
+        <select onChange="setBodyAttr('link',
+        this.options[this.selectedIndex].value);">
+          <option value="blue">azul
+          <option value="green">verde
+        </select>  <small>
+        <a href="http://algum.website.tld/pagina.html" id="amostra">
+        (link)</a></small><br>
+      </form>
+      <form>
+        <input type="button" value="version" onclick="ver()" />
+      </form>
+    </div>
+  </body>
+</html>
+
+ +

Para testar várias interfaces numa única página - por exemplo, um conjunto de propriedades que afete as cores de uma página web - você pode criar uma página de teste similar com um console inteiro de botões, textfields e outros elementos HTML. A screenshot a seguir te dá uma ideia de como interfaces podem ser agrupadas para testes.

+ +
+
Figura 0.1 Página de Teste DOM
+Image:DOM_Ref_Introduction_to_the_DOM.gif
+ +

Nesse exemplo, os menus drop-down atualizam dinamicamente os aspectos acessáveis pelo DOM na página web como o fundo (bgColor), a cor dos hiperlinks (aLink), e a cor do texto (text). Porém, ao desenhar suas páginas de teste, testar as interfaces conforme for lendo sobre elas é uma parte importante para aprender a usar o DOM de forma efetiva.

+ + + + + +
{{DefaultAPISidebar("DOM")}}
diff --git a/files/pt-br/web/api/document_object_model/whitespace/index.html b/files/pt-br/web/api/document_object_model/whitespace/index.html new file mode 100644 index 0000000000..f4bebc3678 --- /dev/null +++ b/files/pt-br/web/api/document_object_model/whitespace/index.html @@ -0,0 +1,227 @@ +--- +title: Whitespace no DOM +slug: DOM/Referencia_do_DOM/Whitespace_in_the_DOM +tags: + - DOM + - Intermediário +translation_of: Web/API/Document_Object_Model/Whitespace +--- +

O problema

+ +

A presença de espaço branco no DOM pode dificultar a manipulação da árvore de conteúdo de formas imprevisíveis. No Mozilla, todo o espaço branco no conteúdo de texto do documento original é representado no DOM (isso não inclui whitespace entre tags). (Isso é necessário internamente para que o editor possa preservar a formatação de documentos e também que white-space: pre irá funcionar em CSS). Isso significa que:

+ + + +

Em outras palavras, a árvore do DOM para o documento seguinte irá parecer como a imagem abaixo (usando "\n" para representar novas linhas):

+ +
<!-- Meu documento -->
+<html>
+<head>
+  <title>Meu documento</title>
+</head>
+<body>
+  <h1>Cabeçalho</h1>
+  <p>
+    Parágrafo
+  </p>
+</body>
+</html>
+
+ +

+ +

Isto pode fazer as coisas um pouco difíceis para qualquer usuário do DOM que quer iterar através do conteúdo, excluindo o whitespace.

+ +

Facilitando as coisas

+ +

É possível formatar o código como mostrado abaixo para contornar o problema:

+ +
<!-- Impressão bonita convencional
+     com espaços brancos (whitespaces) entre as tags:
+ -->
+<div>
+ <ul>
+  <li>Posição 1</li>
+  <li>Posição 2</li>
+  <li>Posição 3</li>
+ </ul>
+</div>
+
+<!-- Impressão bonita ajustada ao problema:
+ -->
+<div
+ ><ul
+  ><li>Posição 1</li
+  ><li>Posição 2</li
+  ><li>Posição 3</li
+ ></ul
+></div>
+
+ +


+ O código Javascript abaixo define funções diversas que fazem a manipulação de whitespace no DOM mais fácil.

+ +
/**
+ * Em todo, o whitespace é definido como um dos caracteres
+ *  "\t" TAB \u0009
+ *  "\n" LF  \u000A
+ *  "\r" CR  \u000D
+ *  " "  SPC \u0020
+ *
+ * Isto não usa o "\s" do Javascript porque inclui espaços
+ * que não quebram (e alguns outros caracteres).
+ */
+
+
+/**
+ * Determina se um conteúdo de texto do nó é inteiramente whitespace.
+ *
+ * @param nod  Um nó implementando a interface |CharacterData| (por exemplo:
+ *             |Text|, |Comment|, ou nó |CDATASection|
+ * @return     Verdadeiro se todo conteúdo de texto de |nod| é whitespace,
+ *             de outra forma é falso.
+ */
+function is_all_ws( nod )
+{
+  // Usa as características do ECMA-262 Edition 3 String e RegExp
+  return !(/[^\t\n\r ]/.test(nod.textContent));
+}
+
+
+/**
+ * Determina se um nó deve ser ignorado pela função de iterador.
+ *
+ * @param nod  Um objeto implementando a interface DOM1 |Node|.
+ * @return     verdadeiro se o nó é:
+ *                1) Um nó |Text| que é todo whitespace
+ *                2) Um nó |Comment|
+ *             do contrário é falso.
+ */
+
+function is_ignorable( nod )
+{
+  return ( nod.nodeType == 8) || // Um nó de comentário
+         ( (nod.nodeType == 3) && is_all_ws(nod) ); // um nó de texto, todo whitespace
+}
+
+/**
+ * Versão de |previousSibling| que pula nós que são inteiramente
+ * whitespace ou comentários.  (Normalmente |previousSibling| é uma propriedade
+ * de todos os nós do DOM que dá o nó irmão, o nó que é
+ * um filho do mesmo parente, que ocorre imediatamente antes do
+ * nó de referência.)
+ *
+ * @param sib  O nó de referência.
+ * @return     Ou:
+ *               1) O irmão mais próximo do |sib| que não é
+ *                  ignorável de acordo com |is_ignorable|, ou
+ *               2) nulo se tal nó não existe.
+ */
+function node_before( sib )
+{
+  while ((sib = sib.previousSibling)) {
+    if (!is_ignorable(sib)) return sib;
+  }
+  return null;
+}
+
+/**
+ * Versão de |nextSibling| que pula nós que são inteiramente
+ * whitespace ou comentários.
+ *
+ * @param sib  O nó de referência.
+ * @return     Ou:
+ *               1) O irmão mais próximo do |sib| que não é
+ *                  ignorável de acordo com |is_ignorable|, ou
+ *               2) nulo se tal nó não existe.
+ */
+function node_after( sib )
+{
+  while ((sib = sib.nextSibling)) {
+    if (!is_ignorable(sib)) return sib;
+  }
+  return null;
+}
+
+/**
+ * Versão de  |lastChild| que pula nós que são inteiramente
+ * whitespace ou comentários.  (Normalmente |lastChild| é uma propriedade
+ * de todos os nós do DOM que dá o último dos nós contidos
+ * diretamente no nó de referência.)
+ *
+ * @param sib  O nó de referência.
+ * @return     Ou:
+ *               1) O último filho do |sib| que não é
+ *                  ignorável de acordo com |is_ignorable|, ou
+ *               2) nulo se tal nó não existe.
+ */
+function last_child( par )
+{
+  var res=par.lastChild;
+  while (res) {
+    if (!is_ignorable(res)) return res;
+    res = res.previousSibling;
+  }
+  return null;
+}
+
+/**
+ * Versão de |firstChild| que pula nós que são inteiramente
+ * whitespace ou comentários.
+ *
+ * @param sib  O nó de referência.
+ * @return     Ou:
+ *               1) O primeiro nó do |sib| que não é
+ *                  ignorável de acordo com |is_ignorable|, ou
+ *               2) nulo se tal nó não existe.
+ */
+function first_child( par )
+{
+  var res=par.firstChild;
+  while (res) {
+    if (!is_ignorable(res)) return res;
+    res = res.nextSibling;
+  }
+  return null;
+}
+
+/**
+ * Versão de |data| que não inclui whitespace no início
+ * e final e normaliza todos whitespaces para um espaço individual.  (Normalmente
+ * |data| é uma propriedade de nós de texto que dá o texto do nó.)
+ *
+ * @param txt  O nó de texto do qual data deve ser retornado
+ * @return     Uma string dando os conteúdos de um nó de texto com
+ *             whitespace colapsado.
+ */
+function data_of( txt )
+{
+  var data = txt.textContent;
+  // Usa características do ECMA-262 Edition 3 String e RegExp
+  data = data.replace(/[\t\n\r ]+/g, " ");
+  if (data.charAt(0) == " ")
+    data = data.substring(1, data.length);
+  if (data.charAt(data.length - 1) == " ")
+    data = data.substring(0, data.length - 1);
+  return data;
+}
+
+ +

Exemplo

+ +

O código seguinte demonstra o uso das funções acima. Ele itera através dos filhos de um elemento (dos quais filhos são todos os elementos) para encontrar aquele cujo o texto seja "Este é o terceiro parágrafo", e então muda o atributo da classe e os conteúdos daquele parágrafo.

+ +
var cur = first_child(document.getElementById("teste"));
+while (cur)
+{
+  if (data_of(cur.firstChild) == "Este é o terceiro parágrafo.")
+  {
+      cur.className = "mágica";
+      cur.firstChild.textContent = "Este é o parágrafo mágico";
+  }
+  cur = node_after(cur);
+}
+
diff --git a/files/pt-br/web/api/documentorshadowroot/activeelement/index.html b/files/pt-br/web/api/documentorshadowroot/activeelement/index.html new file mode 100644 index 0000000000..ca10f98461 --- /dev/null +++ b/files/pt-br/web/api/documentorshadowroot/activeelement/index.html @@ -0,0 +1,165 @@ +--- +title: Document.activeElement +slug: Web/API/Document/activeElement +tags: + - API + - Document + - HTML DOM + - Property + - Reference +translation_of: Web/API/DocumentOrShadowRoot/activeElement +translation_of_original: Web/API/Document/activeElement +--- +

{{APIRef("DOM")}}

+ +

Retorna o {{ domxref("Element", "elemento") }} atualmente em foco, ou seja, o elemento que receberá os eventos do teclado caso o usuário digite algo. Esse atributo é somente-leitura.

+ +

Geralmente retorna um {{ HTMLElement("input") }} ou {{ HTMLElement("textarea") }}, caso esteja com uma seleção de texto ativa. Caso esteja, pode obter mais informações sobre a seleção utilizando as propriedades selectionStart e selectionEnd. Caso o elemento em foco seja um {{ HTMLElement("select") }}(menu) ou {{ HTMLElement("input") }} do tipo button, checkbox ou radio.

+ +
Note: No Mac, elementos que nao sejam campos de texto geralmente não recebem foco.
+ +

Normalmente o usuário pode navegar entre os elementos que pode receber foco na página com o uso da tecla tab e ativar estes elementos com a tecla espaço (apertar um botão ou selecionar uma opção).

+ +

Não confunda foco com uma seleção de texto no documento, que consiste em sua maioria de nódos de texto estáticos. Veja {{ domxref("window.getSelection()") }}.

+ +

Quando não há nada selecionado, o activeElement da página é o {{ HTMLElement("body") }} ou null. 

+ +
+

Este atributo é parte da seção "Em desenvolvimento" da especificação do HTML 5.

+
+ +

Sintaxe

+ +
var curElement = document.activeElement;
+
+ +

Exemplo

+ +
<!DOCTYPE HTML>
+<html>
+<head>
+    <script type="text/javascript" charset="utf-8">
+    function init() {
+
+        function onMouseUp(e) {
+            console.log(e);
+            var outputElement = document.getElementById('output-element');
+            var outputText = document.getElementById('output-text');
+            var selectedTextArea = document.activeElement;
+            var selection = selectedTextArea.value.substring(
+            selectedTextArea.selectionStart, selectedTextArea.selectionEnd);
+            outputElement.innerHTML = selectedTextArea.id;
+            outputText.innerHTML = selection;
+        }
+
+        document.getElementById("ta-example-one").addEventListener("mouseup", onMouseUp, false);
+        document.getElementById("ta-example-two").addEventListener("mouseup", onMouseUp, false);
+    }
+    </script>
+</head>
+<body onload="init()">
+<div>
+    Select some text from one of the Textareas below:
+</div>
+<form id="frm-example" action="#" accept-charset="utf-8">
+<textarea name="ta-example-one" id="ta-example-one" rows="8" cols="40">
+This is Textarea Example One:
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec tincidunt, lorem a porttitor molestie, odio nibh iaculis libero, et accumsan nunc orci eu dui.
+</textarea>
+<textarea name="ta-example-two" id="ta-example-two" rows="8" cols="40">
+This is Textarea Example Two:
+Fusce ullamcorper, nisl ac porttitor adipiscing, urna orci egestas libero, ut accumsan orci lacus laoreet diam. Morbi sed euismod diam.
+</textarea>
+</form>
+Active Element Id: <span id="output-element"></span><br/>
+Selected Text: <span id="output-text"></span>
+
+</body>
+</html>
+
+ +

View on JSFiddle

+ +

Notas

+ +

Originalmente apresentada como extensão DOM proprietária no Internet Explorer 4, esta propriedade também é suportada no Opera e Safari (versão 4 ou maior)

+ +

Especificações

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('HTML WHATWG', 'interaction.html#dom-document-activeelement', 'activeElement')}}{{Spec2('HTML WHATWG')}} 
+ +

Compatibilidade nos navegadores

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support23.04 [1]9.64.0
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}
+
+ +

[1]: O IE9 tem um bug que ao tentar acessar o activeElement do {{domxref("window.parent")}} {{domxref("Document")}} de um {{HTMLElement("iframe")}}(i.e. parent.document.activeElement) é lançado um erro

+ +

Eventos relacionados

+ + diff --git a/files/pt-br/web/api/documentorshadowroot/elementfrompoint/index.html b/files/pt-br/web/api/documentorshadowroot/elementfrompoint/index.html new file mode 100644 index 0000000000..c64d67dd08 --- /dev/null +++ b/files/pt-br/web/api/documentorshadowroot/elementfrompoint/index.html @@ -0,0 +1,133 @@ +--- +title: Document.elementFromPoint() +slug: Web/API/Document/elementFromPoint +tags: + - API + - CSSOM View + - Method + - NeedsMarkupWork + - NeedsMobileBrowserCompatibility + - Reference +translation_of: Web/API/DocumentOrShadowRoot/elementFromPoint +translation_of_original: Web/API/Document/elementFromPoint +--- +
{{APIRef("DOM")}}
+ +

O método elementFromPoint() da interface {{domxref("Document")}} retorna o elemento de maior nível nas coordenadas especificadas.

+ +

Se o elemento no ponto especificado pertencer à outro documento (por exemplo, um subdocumento em um iframe), será retornado o pai do subdocumento (o próprio iframe). Se o elemento em determinado ponto for anônimo ou for um conteudo gerado por XBL, como por exemplo barras de scroll de caixas de texto, então será retornado o primeiro elemento pai, não-anônimo (por exemplo, a própria caixa de texto).

+ +

Se o ponto especificado estiver fora dos limites visíveis do documento ou tiver uma coordenada negativa, o resultado é null.

+ +

Se você precisa encontrar uma posição específica dentro do elemento, use {{domxref("Document.caretPositionFromPoint()")}}.

+ +

{{Note("Chamados por documentos XUL devem esperar até o evento onload ser acionado antes de chamar este método.")}}

+ +

Sintaxe

+ +
var element = document.elementFromPoint(x, y);
+ +

Parâmetros

+ +
+
x
+
Uma posição horizontal dentro do viewport atual.
+
y
+
Uma position vertical dentro do viewport atual.
+
+ +

Valor retornado

+ +

O objeto de nível mais alto {{domxref("Element")}} dentro das coordenadas declaradas.

+ +

Exemplo

+ +
<!DOCTYPE html>
+<html lang="en">
+<head>
+<title>exemplo de elementFromPoint</title>
+
+<script>
+function changeColor(newColor) {
+  elem = document.elementFromPoint(2, 2);
+  elem.style.color = newColor;
+}
+</script>
+</head>
+
+<body>
+<p id="para1">Algum texto aqui</p>
+<button onclick="changeColor('blue');">azul</button>
+<button onclick="changeColor('red');">vermelho</button>
+</body>
+</html>
+
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComment
{{SpecName('CSSOM View', '#dom-document-elementfrompoint', 'elementFromPoint')}}{{Spec2('CSSOM View')}}Definição Inicial.
+ +

Compatibilidade entre navegadores

+ +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + +
FuncionalidadeChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support {{CompatChrome(4.0)}}35.510.50{{CompatVersionUnknown}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FuncionalidadeAndroidChrome para AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
+
diff --git a/files/pt-br/web/api/documentorshadowroot/getselection/index.html b/files/pt-br/web/api/documentorshadowroot/getselection/index.html new file mode 100644 index 0000000000..2f52375799 --- /dev/null +++ b/files/pt-br/web/api/documentorshadowroot/getselection/index.html @@ -0,0 +1,9 @@ +--- +title: Document.getSelection() +slug: Web/API/Document/getSelection +translation_of: Web/API/DocumentOrShadowRoot/getSelection +translation_of_original: Web/API/Document/getSelection +--- +

{{APIRef("DOM")}}

+ +

Esse método funciona de forma idêntica ao método {{domxref("Window.getSelection()")}};  Ele retorna um objeto {{domxref("Selection")}} representando o texto atualmente selecionado no documento.

diff --git a/files/pt-br/web/api/element/accesskey/index.html b/files/pt-br/web/api/element/accesskey/index.html deleted file mode 100644 index e0425e3645..0000000000 --- a/files/pt-br/web/api/element/accesskey/index.html +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Element.accessKey -slug: Web/API/Element/accessKey -translation_of: Web/API/HTMLElement/accessKey -translation_of_original: Web/API/Element/accessKey ---- -
{{APIRef("DOM")}}
- -
 
- -

A propriedade Element.accessKey define a tecla pelo qual o usuário pode pressionar para saltar para este elemento.

- -
-

Nota: A propriedade Element.accessKey é raramente usada por causa dos conflitos múltiplos com os atalhos pré-definidos nos navegadores. Para contornar isto, os navegadores implementam o comportamento da tecla de acesso se as teclas são pressionadas com outras teclas "qualificadas" (como Alt + tecla de acesso).

-
- -

 

- -

 

diff --git a/files/pt-br/web/api/element/addeventlistener/index.html b/files/pt-br/web/api/element/addeventlistener/index.html deleted file mode 100644 index fea1e67e7b..0000000000 --- a/files/pt-br/web/api/element/addeventlistener/index.html +++ /dev/null @@ -1,322 +0,0 @@ ---- -title: Element.addEventListener() -slug: Web/API/Element/addEventListener -translation_of: Web/API/EventTarget/addEventListener ---- -

{{apiref("DOM Events")}}

- -

addEventListener() registra uma única espera de evento em um único alvo. O alvo do evento pode ser um único elemento em um documento, o documento em si, uma janela, ou um XMLHttpRequest.

- -

Para registrar mais de uma espera de evento como alvo, chame addEventListener() para o mesmo alvo mas com diferentes tipos de evento ou captura de parâmetros.

- -

Sintaxe

- -
alvo.addEventListener(type,listener[, options]);
-alvo.addEventListener(type,listener[, useCapture, wantUntrusted {{ Non-standard_inline() }}]); // Gecko/Mozilla only
- -
-
type
-
Uma linha de texto que representa o tipo de evento a ser esperado.
-
listener
-
O objeto que recebe uma notificação quando um evento do tipo especificado ocorre. Esse objeto precisa implementar a interface do EventListener, ou simplesmente executar uma função JavaScript.
-
useCapture {{ optional_inline() }}
-
Se true, useCapture indica que o usuário deseja iniciar uma captura. Depois de iniciada a captura, todos os eventos do tipo especificado serão enviados à listener registrada antes de serem enviados à qualquer EventTarget abaixo dela na hierarquia de DOMs. Eventos que borbulharem para cima na hierarquia não acionarão a escuta designada  a usar a captura. Veja Eventos DOM Nível 3 para uma explicação detalhada. Perceba que esse parâmetro não é opcional em todos os navegadores. Se não for especificado, useCapture é false.
-
wantsUntrusted {{ Non-standard_inline() }}
-
Se true, o evento pode ser acionado por conteúdo não-confiável. Veja Interação entre páginas com e sem privilégios.
-
- -
Nota: useCapture tornou-se opcional somente nas versões mais recentes dos principais navegadores; não era opcional antes do Firefox 6, por exemplo. Você deve especificar esse parâmetro para obter uma maior compatibilidade.
- - -

Exemplo

- -
<!DOCTYPE html>
-<html>
-<head>
-<title>Exemplo de Evento DOM</title>
-
-<style>
-#t { border: 1px solid red }
-#t1 { background-color: pink; }
-</style>
-
-<script>
-// Função para mudar o conteúdo de t2
-function modifyText() {
-  var t2 = document.getElementById("t2");
-  t2.firstChild.nodeValue = "three";
-}
-
-// Função para adicionar uma espera de evento em t
-function load() {
-  var el = document.getElementById("t");
-  el.addEventListener("click", modifyText, false);
-}
-
-document.addEventListener("DOMContentLoaded", load, false);
-</script>
-
-</head>
-<body>
-
-<table id="t">
-   <tr><td id="t1">one</td></tr>
-   <tr><td id="t2">two</td></tr>
-</table>
-
-</body>
-</html>
-
- -

View on JSFiddle

- -

No exemplo acima, modifyText() é uma escuta para eventos de click registrados usando addEventListener(). Um clique em qualquer lugar da tabela irá borbulhar para cima até o manipulador e executar modifyText().

- -

Se você deseja passar parâmetros para a função de escuta, você deve usar uma função anônima.

- -
<!DOCTYPE html>
-<html>
-<head>
-<title>Exemplo de Evento DOM</title>
-
-<style>
-#t { border: 1px solid red }
-#t1 { background-color: pink; }
-</style>
-
-<script>
-
-// Função para mudar o conteúdo de t2
-function modifyText(new_text) {
-  var t2 = document.getElementById("t2");
-  t2.firstChild.nodeValue = new_text;
-}
-
-// Função para adicionar uma espera de evento em t
-function load() {
-  var el = document.getElementById("t");
-  el.addEventListener("click", function(){modifyText("four")}, false);
-}
-</script>
-
-</head>
-<body onload="load();">
-
-<table id="t">
-  <tr><td id="t1">one</td></tr>
-  <tr><td id="t2">two</td></tr>
-</table>
-
-</body>
-</html>
-
- -

Notas

- -

Por que usar addEventListener?

- -

addEventListener é a maneira de registrar uma espera de evento como especificada no W3C DOM. Seus benefícios são os seguintes:

- - - -

Existe outra alternativa, uma maneira ultrapassada de registrar esperas de evento.

- -

Adicionando uma espera de evento durante um disparo de evento

- -

Se um EventListener for somado a um EventTarget enquanto está processando um evento, ele não será ativado pelas ações atuais, mas poderá ser ativado em um período posterior no fluxo de eventos, como na fase de borbulha.

- -

Múltiplas esperas de evento idênticas

- -

Se múltiplas esperas de evento idênticas forem registradas no mesmo EventTarget com os mesmos parâmetros, as versões duplicadas serão descartadas. Elas não fazem o EventListener ser disparado mais de uma vez, e, como as duplicatas são descartadas, elas não precisam ser removidas manualmente com o método removeEventListener.

- -

O valor de this no manipulador

- -

É preferível referenciar o elemento do qual a espera de evento foi disparada, como quando é usado um manipulador genérico para uma série de elementos similares. Quando anexar uma função usando addEventListener(), o valor de this é mudado — perceba que o valor de this é passado para uma função a partir do disparador.

- -

Nos exemplos acima, o valor de this em modifyText(), quando disparado pelo evento de clique, é uma referência à tabela 't'. Isso é um contraste do comportamento que acontece se o manipulador é adicionado ao HTML fonte:

- -
<table id="t" onclick="modifyText();">
-  . . .
- -

O valor de this em modifyText(), quando disparado pelo evento de clique no HTML, será uma referência ao objeto global (no caso, a janela).

- -
Nota: JavaScript 1.8.5 introduz o método Function.prototype.bind(), que permite especificar o valor que deve ser usado como this para todas as chamadas à uma determinada função. Isso evita problemas quando não é claro o que this será, dependendo do contexto do qual a sua função for chamada. Perceba, entretanto, que é preciso manter uma referência da escuta à mão, para que depois você possa removê-la.
- -

Este é um exemplo com e sem bind:

- -
var Algo = function(elemento)
-{
-  this.nome = 'Algo bom';
-  this.onclick1 = function(evento) {
-    console.log(this.nome); // indefinido, porque this é a função de escuta do clique
-  };
-  this.onclick2 = function(evento) {
-    console.log(this.nome); // 'Algo bom', porque this está como objeto Algo através do bind
-  };
-  elemento.addEventListener('click', this.onclick1, false);
-  elemento.addEventListener('click', this.onclick2.bind(this), false); // Truque de bind
-}
-
- -

Outra solução é usar uma função especial chamada handleEvent para capturar quaisquer eventos:

- -
var Algo = function(elemento)
-{
-  this.nome = 'Algo bom';
-  this.handleEvent = function(evento) {
-    console.log(this.nome); // 'Algo bom', porque this é o objeto Algo
-    switch(evento.type) {
-      case 'click':
-        // seu codigo aqui...
-        break;
-      case 'dblclick':
-        // seu codigo aqui...
-        break;
-    }
-  };
-  elemento.addEventListener('click', this, false); // Não this.handleEvent, só this
-  elemento.addEventListener('dblclick', this, false); // Não this.handleEvent, só this
-}
-
- -

Internet Explorer antigos e attachEvent

- -

Em versões do Internet Explorer anteriores ao IE9, você precisa usar attachEvent em vez do padrão addEventListener. Para dar suporte ao IE, o exemplo acima pode ser modificado para:

- -
if (el.addEventListener) {
-  el.addEventListener('click', modifyText, false);
-} else if (el.attachEvent)  {
-  el.attachEvent('onclick', modifyText);
-}
-
- -

Existe um porém com attachEvent: o valor de this será a referência ao objeto window em vez do elemento do qual foi disparado.

- -

Uma maneira ultrapassada de registrar esperas de evento

- -

addEventListener() foi introduzido com as especificações de Eventos DOM 2. Antes disso, esperas de evento eram registradas assim:

- -
// Passe uma função de referência — não adicione '()' depois dela, o que chamaria a função!
-el.onclick = modifyText;
-
-// Usando uma expressão de função
-element.onclick = function() {
-    // ... lógica da função ...
-};
-
- -

Esse método substitui as esperar de evento de click no elemento, se houve alguma. Igualmente para outros outros eventos e manipuladores de evento associados, como blur (onblur), keypress (onkeypress), e assim por diante.

- -

Porque era essencialmente uma parte do DOM 0, esse método era largamente suportado e não necessitava de códigos entre-navegadores especiais; logo é normalmente usado para registrar esperas de evento dinâmicamente, a menos que atributos extras do addEventListener() sejam necessários.

- -

Problemas de memória

- -
var i;
-var els = document.getElementsByTagName('*');
-
-// Caso 1
-for(i=0 ; i<els.length ; i++){
-  els[i].addEventListener("click", function(e){/*fazer algo*/}, false});
-}
-
-// Caso 2
-function processarEvento(e){
-  /*fazer algo*/
-}
-
-for(i=0 ; i<els.length ; i++){
-  els[i].addEventListener("click", processarEvento, false});
-}
-
-
- -

No primeiro caso, uma nova função (anônima) é criada em cada turno do loop. No segundo caso, a mesma função previamente declarada é usada como um manipulador de evento. Isso resulta em um consumo menor de memória. Além do mais, no primeiro caso, já que nenhuma referência à função anônima é mantida, não é possível chamar element.removeEventListener porque não há uma referência ao manipulador, enquanto no segundo caso é possível fazer myElement.removeEventListener("click", processEvent, false).

- -

Compatiblidade de navegadores

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
CaracterísticaChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico1.0{{ CompatGeckoDesktop(1.0) }}9.071.0
useCapture é opcional1.06.09.011.60{{ CompatVersionUnknown() }}
-
- -
- - - - - - - - - - - - - - - - - - - -
CaracterísticaAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico1.0{{ CompatGeckoMobile(1.0) }}9.06.01.0
-
- -

Notas Gecko

- - - -

Notas Webkit

- - - -

Veja também

- - - -

Especificação

- - diff --git a/files/pt-br/web/api/element/blur_event/index.html b/files/pt-br/web/api/element/blur_event/index.html new file mode 100644 index 0000000000..7eb9263be2 --- /dev/null +++ b/files/pt-br/web/api/element/blur_event/index.html @@ -0,0 +1,154 @@ +--- +title: blur (evento) +slug: Web/Events/blur +translation_of: Web/API/Element/blur_event +--- +

O evento blur é acionado quando um elemento perde foco. A diferença principal entre este evento e focusout é que apenas o segundo 'borbulha'.

+ +

Informação geral

+ +
+
Especificação
+
DOM L3
+
Interface
+
{{domxref("FocusEvent")}}
+
Borbulha
+
Não
+
Cancelável
+
Não
+
Alvo
+
Elemento
+
Ação padrão
+
Nenhuma
+
+ +

{{NoteStart}}O valor de {{domxref("Document.activeElement")}} varia entre navegadores enquanto este evento é processado ({{bug(452307)}}): O IE10 define-o para o elemento para onde o foco moverá, enquanto Firefox e Chrome muitas vezes definem-o para o body do documento.{{NoteEnd}}

+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}Event target (DOM element)
type {{readonlyInline}}{{domxref("DOMString")}}The type of event.
bubbles {{readonlyInline}}{{jsxref("Boolean")}}Whether the event normally bubbles or not.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}Whether the event is cancellable or not.
relatedTarget {{readonlyInline}}{{domxref("EventTarget")}} (DOM element)null
+ +

Delegação do evento

+ +

Existem duas maneiras de implementar a delegação de eventos para este evento: usando o evento focusout nos navegadores que suportam-o, ou definindo o parâmetro "useCapture" do addEventListener para true:

+ +

Conteúdo HTML 

+ +
<form id="form">
+  <input type="text" placeholder="text input">
+  <input type="password" placeholder="password">
+</form>
+ +

Conteúdo JavaScript

+ +
var form = document.getElementById("form");
+form.addEventListener("focus", function( event ) {
+  event.target.style.background = "pink";
+}, true);
+form.addEventListener("blur", function( event ) {
+  event.target.style.background = "";
+}, true);
+ +

{{EmbedLiveSample('Event_delegation')}}

+ +

Compatibilidade entre navegadores

+ +
{{CompatibilityTable}}
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico5{{CompatVersionUnknown}}{{CompatVersionUnknown}}[1]612.15.1
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome para AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico4.053{{CompatVersionUnknown}}{{CompatUnknown}}10.012.15.1
+
+ +

[1] Antes do Gecko 24 {{geckoRelease(24)}} a interface para este elemento era {{domxref("Event")}}, não {{domxref("FocusEvent")}}. Veja ({{bug(855741)}}).

+ +

Eventos relacionados

+ + diff --git a/files/pt-br/web/api/element/focus_event/index.html b/files/pt-br/web/api/element/focus_event/index.html new file mode 100644 index 0000000000..9f6dd7117d --- /dev/null +++ b/files/pt-br/web/api/element/focus_event/index.html @@ -0,0 +1,137 @@ +--- +title: focus +slug: Web/Events/focus +translation_of: Web/API/Element/focus_event +--- +

O evento focus é acionado assim que um elemento recebe um foco. O grande diferencial entre este evento e o evento focusin, é que esse segundo "borbulha".

+ +

Informações Gerais

+ +
+
Especificação
+
DOM L3
+
Interface
+
{{ domxref("FocusEvent") }}
+
Borbulha
+
Não
+
Cancelável
+
Não
+
Alvo
+
Element
+
Ação Padrão
+
Nenhuma.
+
+ +
Note: The interface was {{ domxref("Event") }} prior to Gecko 24 {{ geckoRelease(24) }}. ({{ bug(855741) }})
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}Event target (DOM element)
type {{readonlyInline}}{{domxref("DOMString")}}The type of event.
bubbles {{readonlyInline}}{{jsxref("Boolean")}}Whether the event normally bubbles or not.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}Whether the event is cancellable or not.
relatedTarget {{readonlyInline}}{{domxref("EventTarget")}} (DOM element)null
+ +

Eventos Delegados

+ +

Existem 2 maneiras diferentes de implementações delegados a partir de um evento: por meio da utilização do evento  focusin que todos os browsers atuais suportam tão tecnologia (todos exceto o Firefox), ou por setando o parâmetro "useCapture" do elemento  addEventListener  como true:

+ +

{{ EmbedLiveSample('Event_delegation', '', '', '', 'Web/Events/blur') }}

+ +

(Exemplo de codigo do evento blur (event))

+ +

Compatibilidade de Browser

+ +
{{CompatibilityTable}}
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{CompatVersionUnknown()}}{{CompatVersionUnknown()}}{{CompatVersionUnknown()}}{{CompatVersionUnknown()}}{{CompatVersionUnknown()}}{{CompatVersionUnknown()}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatUnknown()}}{{CompatUnknown()}}{{CompatUnknown()}}{{CompatUnknown()}}{{CompatUnknown()}}{{CompatUnknown()}}{{CompatUnknown()}}
+
+ +

Eventos Relacionais

+ + diff --git a/files/pt-br/web/api/element/focusin_event/index.html b/files/pt-br/web/api/element/focusin_event/index.html new file mode 100644 index 0000000000..797424de54 --- /dev/null +++ b/files/pt-br/web/api/element/focusin_event/index.html @@ -0,0 +1,125 @@ +--- +title: focusin +slug: Web/Events/focusin +translation_of: Web/API/Element/focusin_event +--- +

O evento focusin é acionado no momento em que o elemento receba o foco. A grande diferença entre esse evento e o evento  focus, é que apenas o focusin delega o seu evento para o elemento pai (conhecido como bubbling ou deletegate).

+ +

Informações Gerais

+ +
+
Especificação
+
DOM L3
+
Interface
+
{{domxref("FocusEvent")}}
+
Borbulha
+
Sim
+
Cancelável
+
Não
+
Alvo
+
Element
+
Ação Padrão
+
Nenhuma.
+
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}Event target losing focus.
type {{readonlyInline}}{{domxref("DOMString")}}The type of event.
bubbles {{readonlyInline}}{{jsxref("Boolean")}}Whether the event normally bubbles or not.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}Whether the event is cancellable or not.
relatedTarget {{readonlyInline}}{{domxref("EventTarget")}} (DOM element)Event target receiving focus.
+ +

Compatibilidade com Demais Navegadores

+ +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoDesktop(52)}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoMobile(52)}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatVersionUnknown}}
+
+ +

Eventos Relacionais

+ + diff --git a/files/pt-br/web/api/element/focusout_event/index.html b/files/pt-br/web/api/element/focusout_event/index.html new file mode 100644 index 0000000000..8f72b211b2 --- /dev/null +++ b/files/pt-br/web/api/element/focusout_event/index.html @@ -0,0 +1,125 @@ +--- +title: focusout +slug: Web/Events/focusout +translation_of: Web/API/Element/focusout_event +--- +

O evento focusout é acionado assim que o elemento perde o foco. A principal diferença entre esse evento e o evento blur, é que esse ultimo não gera "borbulhas".

+ +

Informações Gerais

+ +
+
Especificação
+
DOM L3
+
Interface
+
{{domxref("FocusEvent")}}
+
Borbulha
+
Sim
+
Cancelável
+
Não
+
Alvo
+
Element
+
Ação Padrão
+
Nenhuma.
+
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}Event target losing focus.
type {{readonlyInline}}{{domxref("DOMString")}}The type of event.
bubbles {{readonlyInline}}{{jsxref("Boolean")}}Whether the event normally bubbles or not.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}Whether the event is cancellable or not.
relatedTarget {{readonlyInline}}{{domxref("EventTarget")}} (DOM element)Event target receiving focus.
+ +

Compatibilidade dos Navegadores

+ +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoDesktop(52)}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoMobile(52)}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatVersionUnknown}}
+
+ +

Eventos Relcionados

+ + diff --git a/files/pt-br/web/api/element/name/index.html b/files/pt-br/web/api/element/name/index.html deleted file mode 100644 index 93f5faee9a..0000000000 --- a/files/pt-br/web/api/element/name/index.html +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Element.name -slug: Web/API/Element/name -tags: - - API - - DOM - - Element - - NeedsBrowserCompatibility - - NeedsUpdate - - Property - - Reference - - Web -translation_of: Web/API -translation_of_original: Web/API/Element/name ---- -

{{ APIRef("DOM") }}

- -

Summary

- -

name recebe ou ajusta uma propriedade name de um objeto do DOM; ele se aplica somente aos seguintes elementos: {{ HTMLelement("a") }}, {{ HTMLelement("applet") }}, {{ HTMLelement("button") }}, {{ HTMLelement("form") }}, {{ HTMLelement("frame") }}, {{ HTMLelement("iframe") }}, {{ HTMLelement("img") }}, {{ HTMLelement("input") }}, {{ HTMLelement("map") }}, {{ HTMLelement("meta") }}, {{ HTMLelement("object") }}, {{ HTMLelement("param") }}, {{ HTMLelement("select") }} e {{ HTMLelement("textarea") }}.

- -
-

Nota: A propriedade name não existe para outros elementos; diferente de tagName e nodeName, ela não é uma propriedade das interfaces {{domxref("Node")}}, {{domxref("Element")}} ou {{domxref("HTMLElement")}}.

-
- -

name pode ser usada no método {{ domxref("document.getElementsByName()") }}, em um form ou com uma coleção de elementos de formulário. Ela pode retornar um único elemento ou uma coleção quando usada com um formulário ou elementos de coleção.

- -

Sintaxe

- -
HTMLElement.name = string;
-var elName = HTMLElement.name;
-
-var fControl = HTMLFormElement.elementName;
-var controlCollection = HTMLFormElement.elements.elementName;
-
- -

Exemplo

- -
<form action="" name="formA">
-  <input type="text" value="foo">
-</form>
-
-<script type="text/javascript">
-
-  // Recebe uma referência ao primeiro elemento no formulário
-  var formElement = document.forms['formA'].elements[0];
-
-  // Fornece um name a ele
-  formElement.name = 'inputA';
-
-  // Exibe o valor do input
-  alert(document.forms['formA'].elements['inputA'].value);
-
-</script>
-
- -

Notas

- -

No Internet Explorer (IE), não é possível ajustar ou modificar a propriedade name de objetos do DOM criados com {{ domxref("document.createElement()") }}.

- -

Especificação

- -

Especificação W3C DOM 2 HTML:

- - diff --git a/files/pt-br/web/api/event/comparativo_entre_event_targets/index.html b/files/pt-br/web/api/event/comparativo_entre_event_targets/index.html deleted file mode 100644 index e9b2004719..0000000000 --- a/files/pt-br/web/api/event/comparativo_entre_event_targets/index.html +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Comparativo entre Event Targets -slug: Web/API/Event/Comparativo_entre_Event_Targets -tags: - - DOM - - Event - - event target -translation_of: Web/API/Event/Comparison_of_Event_Targets ---- -
{{ ApiRef() }}
- -

Event targets

- -

É facil se confundir sobre o tipo de alvo (target) que deseja-se examinar ao criar um manipulador de eventos (event handler). Este artigo se propõe a esclarecer o uso da propriedade target.

- -

Há 5 tipos de targets a se considerar:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropriedadeDefinido emObjetivo
event.targetDOM Event Interface -

O elemento do DOM à esquerda da chamada que disparou este evento, por exemplo:

- - 
-element.dispatchEvent(event)
-
-
event.currentTargetDOM Event InterfaceO EventTarget do qual o EventListeners está sendo atualmente processado. Logo que a captura e a subida do evento ocorre a mudança deste valor.
event.relatedTargetDOM MouseEvent InterfaceIdentifica um alvo secundário para o evento.
event.explicitOriginalTarget{{ Source("/dom/public/idl/events/nsIDOMNSEvent.idl", "nsIDOMNSEvent.idl") }}{{ Non-standard_inline() }} Se o evento foi redirecionado por alguma outra razão senão o cruzamento de uma fronteira anônima, este evento será colocado no alvo antes que o redirecionamento ocorra. por exemplo, eventos do mouse são redirecionados à seus elementos pais quando acontecem sobre nós de texto ({{ Bug("185889") }}), e neste caso .target mostrará o nó pai e .explicitOriginalTarget mostrará o nó texto. Diferente de .originalTarget, .explicitOriginalTarget nunca irá conter um conteúdo anônimo.
event.originalTarget{{ Source("/dom/public/idl/events/nsIDOMNSEvent.idl", "nsIDOMNSEvent.idl") }}{{ Non-standard_inline() }} O alvo original do evento, antes de qualquer redirecionamento. Veja Anonymous Content#Event_Flow_and_Targeting para mais detalhes.
- -

Uso de explicitOriginalTarget e originalTarget

- -

TODO: Disponível apensas em navegadores Mozilla-based?

- -

TODO: Adequado apenas para desenvolvedores de extensões?

- -

Exemplos

- -
<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="utf-8">
-    <meta http-equiv="X-UA-Compatible" content="IE=edge">
-    <title>Comparison of Event Targets</title>
-    <style>
-        table {
-            border-collapse: collapse;
-            height: 150px;
-            width: 100%;
-        }
-        td {
-            border: 1px solid #ccc;
-            font-weight: bold;
-            padding: 5px;
-            min-height: 30px;
-        }
-        .standard {
-            background-color: #99ff99;
-        }
-        .non-standard {
-            background-color: #902D37;
-        }
-    </style>
-</head>
-<body>
-    <table>
-    <thead>
-        <tr>
-            <td class="standard">Original target dispatching the event <small>event.target</small></td>
-            <td class="standard">Target who's event listener is being processed <small>event.currentTarget</small></td>
-            <td class="standard">Identify other element (if any) involved in the event <small>event.relatedTarget</small></td>
-            <td class="non-standard">If there was a retargetting of the event for some reason <small> event.explicitOriginalTarget</small> contains the target before retargetting (never contains anonymous targets)</td>
-            <td class="non-standard">If there was a retargetting of the event for some reason <small> event.originalTarget</small> contains the target before retargetting (may contain anonymous targets)</td>
-        </tr>
-    </thead>
-    <tr>
-        <td id="target"></td>
-        <td id="currentTarget"></td>
-        <td id="relatedTarget"></td>
-        <td id="explicitOriginalTarget"></td>
-        <td id="originalTarget"></td>
-    </tr>
-</table>
-<p>Clicking on the text will show the difference between explicitOriginalTarget, originalTarget and target</p>
-<script>
-    function handleClicks(e) {
-        document.getElementById('target').innerHTML = e.target;
-        document.getElementById('currentTarget').innerHTML = e.currentTarget;
-        document.getElementById('relatedTarget').innerHTML = e.relatedTarget;
-        document.getElementById('explicitOriginalTarget').innerHTML = e.explicitOriginalTarget;
-        document.getElementById('originalTarget').innerHTML = e.originalTarget;
-    }
-
-    function handleMouseover(e) {
-        document.getElementById('target').innerHTML = e.target;
-        document.getElementById('relatedTarget').innerHTML = e.relatedTarget;
-    }
-
-    document.addEventListener('click', handleClicks, false);
-    document.addEventListener('mouseover', handleMouseover, false);
-</script>
-</body>
-</html>
- -

Uso de target e relatedTarget

- -

A propriedade relatedTarget do evento de mouseover mantém o nó de onde o mouse estava sobre anteriormente. Para o evento de mouseout, mantém o nó para onde o mouse se moveu.

- - - - - - - - - - - - - - - - - - - -
Tipo de Eventoevent.targetevent.relatedTarget
mouseoverO EventTarget do qual o dispositivo apontador entrou.O EventTarget do qual o dispositivo apontador saiu.
mouseoutO EventTarget do qual o dispositivo apontador saiu.O EventTarget do qual o dispositivo apontador entrou.
- -

TODO: Necessário descrição complemento sobre eventos de dragenter e dragexit.

- -

Exemplo

- -
<hbox id="outer">
-  <hbox id="inner"
-        onmouseover="dump('mouseover ' + event.relatedTarget.id + ' > ' + event.target.id + '\n');"
-        onmouseout="dump('mouseout  ' + event.target.id + ' > ' + event.relatedTarget.id + '\n');"
-        style="margin: 100px; border: 10px solid black; width: 100px; height: 100px;" />
-</hbox>
-
diff --git a/files/pt-br/web/api/event/comparison_of_event_targets/index.html b/files/pt-br/web/api/event/comparison_of_event_targets/index.html new file mode 100644 index 0000000000..e9b2004719 --- /dev/null +++ b/files/pt-br/web/api/event/comparison_of_event_targets/index.html @@ -0,0 +1,167 @@ +--- +title: Comparativo entre Event Targets +slug: Web/API/Event/Comparativo_entre_Event_Targets +tags: + - DOM + - Event + - event target +translation_of: Web/API/Event/Comparison_of_Event_Targets +--- +
{{ ApiRef() }}
+ +

Event targets

+ +

É facil se confundir sobre o tipo de alvo (target) que deseja-se examinar ao criar um manipulador de eventos (event handler). Este artigo se propõe a esclarecer o uso da propriedade target.

+ +

Há 5 tipos de targets a se considerar:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropriedadeDefinido emObjetivo
event.targetDOM Event Interface +

O elemento do DOM à esquerda da chamada que disparou este evento, por exemplo:

+ + 
+element.dispatchEvent(event)
+
+
event.currentTargetDOM Event InterfaceO EventTarget do qual o EventListeners está sendo atualmente processado. Logo que a captura e a subida do evento ocorre a mudança deste valor.
event.relatedTargetDOM MouseEvent InterfaceIdentifica um alvo secundário para o evento.
event.explicitOriginalTarget{{ Source("/dom/public/idl/events/nsIDOMNSEvent.idl", "nsIDOMNSEvent.idl") }}{{ Non-standard_inline() }} Se o evento foi redirecionado por alguma outra razão senão o cruzamento de uma fronteira anônima, este evento será colocado no alvo antes que o redirecionamento ocorra. por exemplo, eventos do mouse são redirecionados à seus elementos pais quando acontecem sobre nós de texto ({{ Bug("185889") }}), e neste caso .target mostrará o nó pai e .explicitOriginalTarget mostrará o nó texto. Diferente de .originalTarget, .explicitOriginalTarget nunca irá conter um conteúdo anônimo.
event.originalTarget{{ Source("/dom/public/idl/events/nsIDOMNSEvent.idl", "nsIDOMNSEvent.idl") }}{{ Non-standard_inline() }} O alvo original do evento, antes de qualquer redirecionamento. Veja Anonymous Content#Event_Flow_and_Targeting para mais detalhes.
+ +

Uso de explicitOriginalTarget e originalTarget

+ +

TODO: Disponível apensas em navegadores Mozilla-based?

+ +

TODO: Adequado apenas para desenvolvedores de extensões?

+ +

Exemplos

+ +
<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <title>Comparison of Event Targets</title>
+    <style>
+        table {
+            border-collapse: collapse;
+            height: 150px;
+            width: 100%;
+        }
+        td {
+            border: 1px solid #ccc;
+            font-weight: bold;
+            padding: 5px;
+            min-height: 30px;
+        }
+        .standard {
+            background-color: #99ff99;
+        }
+        .non-standard {
+            background-color: #902D37;
+        }
+    </style>
+</head>
+<body>
+    <table>
+    <thead>
+        <tr>
+            <td class="standard">Original target dispatching the event <small>event.target</small></td>
+            <td class="standard">Target who's event listener is being processed <small>event.currentTarget</small></td>
+            <td class="standard">Identify other element (if any) involved in the event <small>event.relatedTarget</small></td>
+            <td class="non-standard">If there was a retargetting of the event for some reason <small> event.explicitOriginalTarget</small> contains the target before retargetting (never contains anonymous targets)</td>
+            <td class="non-standard">If there was a retargetting of the event for some reason <small> event.originalTarget</small> contains the target before retargetting (may contain anonymous targets)</td>
+        </tr>
+    </thead>
+    <tr>
+        <td id="target"></td>
+        <td id="currentTarget"></td>
+        <td id="relatedTarget"></td>
+        <td id="explicitOriginalTarget"></td>
+        <td id="originalTarget"></td>
+    </tr>
+</table>
+<p>Clicking on the text will show the difference between explicitOriginalTarget, originalTarget and target</p>
+<script>
+    function handleClicks(e) {
+        document.getElementById('target').innerHTML = e.target;
+        document.getElementById('currentTarget').innerHTML = e.currentTarget;
+        document.getElementById('relatedTarget').innerHTML = e.relatedTarget;
+        document.getElementById('explicitOriginalTarget').innerHTML = e.explicitOriginalTarget;
+        document.getElementById('originalTarget').innerHTML = e.originalTarget;
+    }
+
+    function handleMouseover(e) {
+        document.getElementById('target').innerHTML = e.target;
+        document.getElementById('relatedTarget').innerHTML = e.relatedTarget;
+    }
+
+    document.addEventListener('click', handleClicks, false);
+    document.addEventListener('mouseover', handleMouseover, false);
+</script>
+</body>
+</html>
+ +

Uso de target e relatedTarget

+ +

A propriedade relatedTarget do evento de mouseover mantém o nó de onde o mouse estava sobre anteriormente. Para o evento de mouseout, mantém o nó para onde o mouse se moveu.

+ + + + + + + + + + + + + + + + + + + +
Tipo de Eventoevent.targetevent.relatedTarget
mouseoverO EventTarget do qual o dispositivo apontador entrou.O EventTarget do qual o dispositivo apontador saiu.
mouseoutO EventTarget do qual o dispositivo apontador saiu.O EventTarget do qual o dispositivo apontador entrou.
+ +

TODO: Necessário descrição complemento sobre eventos de dragenter e dragexit.

+ +

Exemplo

+ +
<hbox id="outer">
+  <hbox id="inner"
+        onmouseover="dump('mouseover ' + event.relatedTarget.id + ' > ' + event.target.id + '\n');"
+        onmouseout="dump('mouseout  ' + event.target.id + ' > ' + event.relatedTarget.id + '\n');"
+        style="margin: 100px; border: 10px solid black; width: 100px; height: 100px;" />
+</hbox>
+
diff --git a/files/pt-br/web/api/eventtarget/addeventlistener/index.html b/files/pt-br/web/api/eventtarget/addeventlistener/index.html new file mode 100644 index 0000000000..fea1e67e7b --- /dev/null +++ b/files/pt-br/web/api/eventtarget/addeventlistener/index.html @@ -0,0 +1,322 @@ +--- +title: Element.addEventListener() +slug: Web/API/Element/addEventListener +translation_of: Web/API/EventTarget/addEventListener +--- +

{{apiref("DOM Events")}}

+ +

addEventListener() registra uma única espera de evento em um único alvo. O alvo do evento pode ser um único elemento em um documento, o documento em si, uma janela, ou um XMLHttpRequest.

+ +

Para registrar mais de uma espera de evento como alvo, chame addEventListener() para o mesmo alvo mas com diferentes tipos de evento ou captura de parâmetros.

+ +

Sintaxe

+ +
alvo.addEventListener(type,listener[, options]);
+alvo.addEventListener(type,listener[, useCapture, wantUntrusted {{ Non-standard_inline() }}]); // Gecko/Mozilla only
+ +
+
type
+
Uma linha de texto que representa o tipo de evento a ser esperado.
+
listener
+
O objeto que recebe uma notificação quando um evento do tipo especificado ocorre. Esse objeto precisa implementar a interface do EventListener, ou simplesmente executar uma função JavaScript.
+
useCapture {{ optional_inline() }}
+
Se true, useCapture indica que o usuário deseja iniciar uma captura. Depois de iniciada a captura, todos os eventos do tipo especificado serão enviados à listener registrada antes de serem enviados à qualquer EventTarget abaixo dela na hierarquia de DOMs. Eventos que borbulharem para cima na hierarquia não acionarão a escuta designada  a usar a captura. Veja Eventos DOM Nível 3 para uma explicação detalhada. Perceba que esse parâmetro não é opcional em todos os navegadores. Se não for especificado, useCapture é false.
+
wantsUntrusted {{ Non-standard_inline() }}
+
Se true, o evento pode ser acionado por conteúdo não-confiável. Veja Interação entre páginas com e sem privilégios.
+
+ +
Nota: useCapture tornou-se opcional somente nas versões mais recentes dos principais navegadores; não era opcional antes do Firefox 6, por exemplo. Você deve especificar esse parâmetro para obter uma maior compatibilidade.
+ + +

Exemplo

+ +
<!DOCTYPE html>
+<html>
+<head>
+<title>Exemplo de Evento DOM</title>
+
+<style>
+#t { border: 1px solid red }
+#t1 { background-color: pink; }
+</style>
+
+<script>
+// Função para mudar o conteúdo de t2
+function modifyText() {
+  var t2 = document.getElementById("t2");
+  t2.firstChild.nodeValue = "three";
+}
+
+// Função para adicionar uma espera de evento em t
+function load() {
+  var el = document.getElementById("t");
+  el.addEventListener("click", modifyText, false);
+}
+
+document.addEventListener("DOMContentLoaded", load, false);
+</script>
+
+</head>
+<body>
+
+<table id="t">
+   <tr><td id="t1">one</td></tr>
+   <tr><td id="t2">two</td></tr>
+</table>
+
+</body>
+</html>
+
+ +

View on JSFiddle

+ +

No exemplo acima, modifyText() é uma escuta para eventos de click registrados usando addEventListener(). Um clique em qualquer lugar da tabela irá borbulhar para cima até o manipulador e executar modifyText().

+ +

Se você deseja passar parâmetros para a função de escuta, você deve usar uma função anônima.

+ +
<!DOCTYPE html>
+<html>
+<head>
+<title>Exemplo de Evento DOM</title>
+
+<style>
+#t { border: 1px solid red }
+#t1 { background-color: pink; }
+</style>
+
+<script>
+
+// Função para mudar o conteúdo de t2
+function modifyText(new_text) {
+  var t2 = document.getElementById("t2");
+  t2.firstChild.nodeValue = new_text;
+}
+
+// Função para adicionar uma espera de evento em t
+function load() {
+  var el = document.getElementById("t");
+  el.addEventListener("click", function(){modifyText("four")}, false);
+}
+</script>
+
+</head>
+<body onload="load();">
+
+<table id="t">
+  <tr><td id="t1">one</td></tr>
+  <tr><td id="t2">two</td></tr>
+</table>
+
+</body>
+</html>
+
+ +

Notas

+ +

Por que usar addEventListener?

+ +

addEventListener é a maneira de registrar uma espera de evento como especificada no W3C DOM. Seus benefícios são os seguintes:

+ + + +

Existe outra alternativa, uma maneira ultrapassada de registrar esperas de evento.

+ +

Adicionando uma espera de evento durante um disparo de evento

+ +

Se um EventListener for somado a um EventTarget enquanto está processando um evento, ele não será ativado pelas ações atuais, mas poderá ser ativado em um período posterior no fluxo de eventos, como na fase de borbulha.

+ +

Múltiplas esperas de evento idênticas

+ +

Se múltiplas esperas de evento idênticas forem registradas no mesmo EventTarget com os mesmos parâmetros, as versões duplicadas serão descartadas. Elas não fazem o EventListener ser disparado mais de uma vez, e, como as duplicatas são descartadas, elas não precisam ser removidas manualmente com o método removeEventListener.

+ +

O valor de this no manipulador

+ +

É preferível referenciar o elemento do qual a espera de evento foi disparada, como quando é usado um manipulador genérico para uma série de elementos similares. Quando anexar uma função usando addEventListener(), o valor de this é mudado — perceba que o valor de this é passado para uma função a partir do disparador.

+ +

Nos exemplos acima, o valor de this em modifyText(), quando disparado pelo evento de clique, é uma referência à tabela 't'. Isso é um contraste do comportamento que acontece se o manipulador é adicionado ao HTML fonte:

+ +
<table id="t" onclick="modifyText();">
+  . . .
+ +

O valor de this em modifyText(), quando disparado pelo evento de clique no HTML, será uma referência ao objeto global (no caso, a janela).

+ +
Nota: JavaScript 1.8.5 introduz o método Function.prototype.bind(), que permite especificar o valor que deve ser usado como this para todas as chamadas à uma determinada função. Isso evita problemas quando não é claro o que this será, dependendo do contexto do qual a sua função for chamada. Perceba, entretanto, que é preciso manter uma referência da escuta à mão, para que depois você possa removê-la.
+ +

Este é um exemplo com e sem bind:

+ +
var Algo = function(elemento)
+{
+  this.nome = 'Algo bom';
+  this.onclick1 = function(evento) {
+    console.log(this.nome); // indefinido, porque this é a função de escuta do clique
+  };
+  this.onclick2 = function(evento) {
+    console.log(this.nome); // 'Algo bom', porque this está como objeto Algo através do bind
+  };
+  elemento.addEventListener('click', this.onclick1, false);
+  elemento.addEventListener('click', this.onclick2.bind(this), false); // Truque de bind
+}
+
+ +

Outra solução é usar uma função especial chamada handleEvent para capturar quaisquer eventos:

+ +
var Algo = function(elemento)
+{
+  this.nome = 'Algo bom';
+  this.handleEvent = function(evento) {
+    console.log(this.nome); // 'Algo bom', porque this é o objeto Algo
+    switch(evento.type) {
+      case 'click':
+        // seu codigo aqui...
+        break;
+      case 'dblclick':
+        // seu codigo aqui...
+        break;
+    }
+  };
+  elemento.addEventListener('click', this, false); // Não this.handleEvent, só this
+  elemento.addEventListener('dblclick', this, false); // Não this.handleEvent, só this
+}
+
+ +

Internet Explorer antigos e attachEvent

+ +

Em versões do Internet Explorer anteriores ao IE9, você precisa usar attachEvent em vez do padrão addEventListener. Para dar suporte ao IE, o exemplo acima pode ser modificado para:

+ +
if (el.addEventListener) {
+  el.addEventListener('click', modifyText, false);
+} else if (el.attachEvent)  {
+  el.attachEvent('onclick', modifyText);
+}
+
+ +

Existe um porém com attachEvent: o valor de this será a referência ao objeto window em vez do elemento do qual foi disparado.

+ +

Uma maneira ultrapassada de registrar esperas de evento

+ +

addEventListener() foi introduzido com as especificações de Eventos DOM 2. Antes disso, esperas de evento eram registradas assim:

+ +
// Passe uma função de referência — não adicione '()' depois dela, o que chamaria a função!
+el.onclick = modifyText;
+
+// Usando uma expressão de função
+element.onclick = function() {
+    // ... lógica da função ...
+};
+
+ +

Esse método substitui as esperar de evento de click no elemento, se houve alguma. Igualmente para outros outros eventos e manipuladores de evento associados, como blur (onblur), keypress (onkeypress), e assim por diante.

+ +

Porque era essencialmente uma parte do DOM 0, esse método era largamente suportado e não necessitava de códigos entre-navegadores especiais; logo é normalmente usado para registrar esperas de evento dinâmicamente, a menos que atributos extras do addEventListener() sejam necessários.

+ +

Problemas de memória

+ +
var i;
+var els = document.getElementsByTagName('*');
+
+// Caso 1
+for(i=0 ; i<els.length ; i++){
+  els[i].addEventListener("click", function(e){/*fazer algo*/}, false});
+}
+
+// Caso 2
+function processarEvento(e){
+  /*fazer algo*/
+}
+
+for(i=0 ; i<els.length ; i++){
+  els[i].addEventListener("click", processarEvento, false});
+}
+
+
+ +

No primeiro caso, uma nova função (anônima) é criada em cada turno do loop. No segundo caso, a mesma função previamente declarada é usada como um manipulador de evento. Isso resulta em um consumo menor de memória. Além do mais, no primeiro caso, já que nenhuma referência à função anônima é mantida, não é possível chamar element.removeEventListener porque não há uma referência ao manipulador, enquanto no segundo caso é possível fazer myElement.removeEventListener("click", processEvent, false).

+ +

Compatiblidade de navegadores

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
CaracterísticaChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico1.0{{ CompatGeckoDesktop(1.0) }}9.071.0
useCapture é opcional1.06.09.011.60{{ CompatVersionUnknown() }}
+
+ +
+ + + + + + + + + + + + + + + + + + + +
CaracterísticaAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico1.0{{ CompatGeckoMobile(1.0) }}9.06.01.0
+
+ +

Notas Gecko

+ + + +

Notas Webkit

+ + + +

Veja também

+ + + +

Especificação

+ + diff --git a/files/pt-br/web/api/fetch_api/cross-global_fetch_usage/index.html b/files/pt-br/web/api/fetch_api/cross-global_fetch_usage/index.html new file mode 100644 index 0000000000..c569966b5a --- /dev/null +++ b/files/pt-br/web/api/fetch_api/cross-global_fetch_usage/index.html @@ -0,0 +1,35 @@ +--- +title: Uso de busca Cross-global +slug: Web/API/Fetch_API/Uso_de_busca_Cross-global +translation_of: Web/API/Fetch_API/Cross-global_fetch_usage +--- +

 

+ +

Este artigo explica um "edge case" (um problema ou situação que ocorre apenas em um parâmetro operacional extremo) que ocorre ao utilizar fetch (e potencialmente outras APIs que exibem o mesmo tipo de comportamento de recuperação de recurso). Quando uma busca de cross-origin envolvendo uma URL relativa é iniciada a partir de um {{htmlelement ("iframe")}}, a URL relativa costumava ser resolvida na localização global atual, em vez da localização do iframe.

+ +

O "edge case"

+ +

Muitos sites nunca se deparam com este caso extremo. Para que isso aconteça:

+ + + +

O problema

+ +

No passado, resolveríamos o URL relativo contra o global atual, por exemplo:

+ +
let absolute = new URL(relative, window.location.href)
+ +

Isto não é um problema como tal. É que diferentes APIs que exibem esse tipo de comportamento estavam fazendo isso de maneira inconsistente com o comportamento definido na especificação, o que poderia levar a problemas mais adiante.

+ +

A solução

+ +

No Firefox 60 em diante, o Mozilla resolve a URL relativa contra o global que possui a função fetch() que está sendo usada (veja {{bug (1432272)}}). Portanto, no caso descrito acima, ele é resolvido em relação à localização do iframe:

+ +
let absolute = new URL(relative, frame.contentWindow.location.href)
+ +

Há muita discussão em andamento sobre a obtenção de novas especificações para se alinhar a essa mudança de comportamento, a fim de mitigar possíveis problemas no futuro.

diff --git a/files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html b/files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html deleted file mode 100644 index c569966b5a..0000000000 --- a/files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Uso de busca Cross-global -slug: Web/API/Fetch_API/Uso_de_busca_Cross-global -translation_of: Web/API/Fetch_API/Cross-global_fetch_usage ---- -

 

- -

Este artigo explica um "edge case" (um problema ou situação que ocorre apenas em um parâmetro operacional extremo) que ocorre ao utilizar fetch (e potencialmente outras APIs que exibem o mesmo tipo de comportamento de recuperação de recurso). Quando uma busca de cross-origin envolvendo uma URL relativa é iniciada a partir de um {{htmlelement ("iframe")}}, a URL relativa costumava ser resolvida na localização global atual, em vez da localização do iframe.

- -

O "edge case"

- -

Muitos sites nunca se deparam com este caso extremo. Para que isso aconteça:

- - - -

O problema

- -

No passado, resolveríamos o URL relativo contra o global atual, por exemplo:

- -
let absolute = new URL(relative, window.location.href)
- -

Isto não é um problema como tal. É que diferentes APIs que exibem esse tipo de comportamento estavam fazendo isso de maneira inconsistente com o comportamento definido na especificação, o que poderia levar a problemas mais adiante.

- -

A solução

- -

No Firefox 60 em diante, o Mozilla resolve a URL relativa contra o global que possui a função fetch() que está sendo usada (veja {{bug (1432272)}}). Portanto, no caso descrito acima, ele é resolvido em relação à localização do iframe:

- -
let absolute = new URL(relative, frame.contentWindow.location.href)
- -

Há muita discussão em andamento sobre a obtenção de novas especificações para se alinhar a essa mudança de comportamento, a fim de mitigar possíveis problemas no futuro.

diff --git a/files/pt-br/web/api/geolocation_api/index.html b/files/pt-br/web/api/geolocation_api/index.html new file mode 100644 index 0000000000..b6799afa16 --- /dev/null +++ b/files/pt-br/web/api/geolocation_api/index.html @@ -0,0 +1,227 @@ +--- +title: Usando geolocation +slug: Using_geolocation +tags: + - Geolocation API + - Guia(2) +translation_of: Web/API/Geolocation_API +--- +

A API geolocation permite que o usuário forneça sua localização a aplicativos web se ele desejar. Por questões de privacidade, o usuário é perguntado se permite fornecer informações de localização.

+ +

O objeto geolocation

+ +

O aplicativo de geolocalização é utilizado através de um objeto filho chamado geolocation localizado dentro do objeto navigator.  Se o objeto existe, os serviços de geolocalização estarão disponíveis. Você pode adicionalmente testar a presença da geolocalização:

+ +
if ("geolocation" in navigator) {
+  /* geolocation is available */
+} else {
+  alert("I'm sorry, but geolocation services are not supported by your browser.");
+}
+
+ +

{{ gecko_minversion_header("1.9.2") }}

+ +

Ao iniciar no Gecko 1.9.2 (Firefox 3.6), add-ons podem obter o objeto de geolocalização obtendo a referência para o serviço de geolocaliazação como se ve a seguir:

+ +
var geolocation = Components.classes["@mozilla.org/geolocation;1"]
+                            .getService(Components.interfaces.nsIDOMGeoGeolocation);
+
+ +

Obtendo a posição atual

+ +

Para obter a localização atual do usuário, você pode utiliza o método getCurrentPosition().  Isto inicia uma requisição assíncrona para identificar a posição do usuário, e consulta o hardware de localização para conseguir informações atualizadas. Quando a posição é determinada, uma rotina específica de retorno é executada. Você pode opcionalmente gerar uma segunda rotina de retorno se um erro ocorrer.  Um terceiro, e opcional, parâmetro é a interface "opções" onde você pode configurar o tempo máximo da posição recebida e o tempo a se esperar por uma solicitação.

+ +

Use getCurrentPosition() se você deseja uma única posição rapidamente, independente da precisão.  Dispositivos com GPS, por exemplo, podem levar um minuto ou mais para conseguir a localização, e portanto dados menos precisos (localização do IP location ou rede wifi) podem retornar do método getCurrentPosition().

+ +
navigator.geolocation.getCurrentPosition(function(position) {
+  do_something(position.coords.latitude, position.coords.longitude);
+});
+ +

O exemplo acima irá fazer a função the do_something() executar quando a localização for obtida.

+ +

Verificando a posição atual

+ +
Se os dados de posição mudam (sejam pelo movimento do dispositivo ou se uma informação mais precisa for recebida), se pode configurar um retorno que é feito com esta informação de posição atual. Isto é feito usando a função watchPosition(), a qual tem os mesmos parâmetros de entrada da função getCurrentPosition(). Seu retorno é chamada múltiplas vezes, permitindo que o navegador ou atualize sua posição enquanto você se move, ou forneça uma localização mais precisa enquanto diferentes técnicas são usadas para localizar sua posição. O erro do retorno, o qual é opcional assim como no getCurrentPosition(), é chamado uma única vez, se nenhum resultado válido retornar.
+ +

O watchPosition() pode ser usado sem que não haja a chamada inicial de getCurrentPosition().

+ +
var watchID = navigator.geolocation.watchPosition(function(position) {
+  do_something(position.coords.latitude, position.coords.longitude);
+}
+);
+ +

O método watchPosition() retorna um número de ID que pode ser usado para identificar a posição solicitada; você pode usar esse valor em conjunto com o método clearWatch(), parando a localização do usuário.

+ +
navigator.geolocation.clearWatch(watchID);
+
+
+ +

watchPosition()retorna um callback sucesso e erro (como getCurrentPosition) e um objeto positionObjects, que pode ter três propriedades:

+ + + +

Segue uma chamada para watchPosition:

+ +
var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});
+ +

Exemplo de watchPosition em uso: thedotproduct.org/posts/a-simple-example-of-navigatorgeolocationwatchposition
+ 

+ +

Imprimindo uma posição

+ +

A localização do usuário é impressa usando o objeto Position, que tem os seguintes campos:

+ +
+
timestamp
+
Momento em que a leitura foi feita, como DOMTimeStamp.
+
coords
+
Objecto nsIDOMGeoPositionCoords indicando a localização.
+
address {{ gecko_minversion_inline("1.9.2") }} {{obsolete_inline("14.0")}}
+
{{ interface("nsIDOMGeoPositionAddress") }} objeto especificando o endereço correspondente, se disponível.
+
+ +


+ Manipulação de erros

+ +

Retornando o callback de erro, se fornecido, chamar getCurrentPosition() e watchPosition(), tem a seguinte assinatura:

+ +
function errorCallback(PositionError error);
+
+ +

O PositionError tem a seguinte estrutura de campos:

+ +
+
code
+
Um código de erro numérico dos seguintes procedimentos:
+
UNKNOWN_ERROR (valor numérico 0)
+
O processo de aquisição de localização falhou devido a um erro de qualquer outro código nesta interface.
+
PERMISSION_DENIED (valor numérico 1)
+
O processo de aquisição da localização falhou porque a origem aplicativo não tem permissão para usar a API de Geolocalização.
+
POSITION_UNAVAILABLE (valor numérico 2)
+
A posição do dispositivo não pôde ser determinada. Um ou mais provedores de localização utilizados no processo de aquisição local gerou um erro interno que falou o processo completamente.
+
TIMEOUT (numeric value 3)
+
O comprimento máximo de tempo especificado.
+
message
+
Uma mensagem de erro legível para uso em registros e depuração, mas não para exibir para o usuário.
+
+ +

Compatibilidade do navegador

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NavegadorSuporte BásicoGeolocation Level 2
Internet ExplorerIE9 RC---
Firefox (Gecko)3.5 (1.9.1)---
Opera10.60---
Safari | Chrome | WebKit5 | 5 | 533---
+ +

Solicitando permissão

+ +

Qualquer add-on hospedado em addons.mozilla.org, que faz uso de dados de geolocalização, deve solicitar antes uma permissão. A função a seguir vai solicitar a permissão de um modo semelhante ao prompt. A resposta do usuário será salva no parâmetro pref. A função fornecida no parâmetro de callback será chamado com um valor booleano que indica a resposta do usuário. Se for true, o add-on poderá retornar dados de geolocalização.

+ +
function prompt(window, pref, message, callback) {
+    let branch = Components.classes["@mozilla.org/preferences-service;1"]
+                           .getService(Components.interfaces.nsIPrefBranch);
+
+    if (branch.getPrefType(pref) === branch.PREF_STRING) {
+        switch (branch.getCharPref(pref)) {
+        case "always":
+            return callback(true);
+        case "never":
+            return callback(false);
+        }
+    }
+
+    let done = false;
+
+    function remember(value, result) {
+        return function() {
+            done = true;
+            branch.setCharPref(pref, value);
+            callback(result);
+        }
+    }
+
+    let self = window.PopupNotifications.show(
+        window.gBrowser.selectedBrowser,
+        "geolocation",
+        message,
+        "geo-notification-icon",
+        {
+            label: "Share Location",
+            accessKey: "S",
+            callback: function(notification) {
+                done = true;
+                callback(true);
+            }
+        }, [
+            {
+                label: "Always Share",
+                accessKey: "A",
+                callback: remember("always", true)
+            },
+            {
+                label: "Never Share",
+                accessKey: "N",
+                callback: remember("never", false)
+            }
+        ], {
+            eventCallback: function(event) {
+                if (event === "dismissed") {
+                    if (!done) callback(false);
+                    done = true;
+                    window.PopupNotifications.remove(self);
+                }
+            },
+            persistWhileVisible: true
+        });
+}
+
+prompt(window,
+       "extensions.foo-addon.allowGeolocation",
+       "Foo Add-on wants to know your location.",
+       function callback(allowed) { alert(allowed); });
+
+ +

Veja também

+ + + +
{{ HTML5ArticleTOC() }}
diff --git a/files/pt-br/web/api/history_api/example/index.html b/files/pt-br/web/api/history_api/example/index.html new file mode 100644 index 0000000000..a4dfc4b68f --- /dev/null +++ b/files/pt-br/web/api/history_api/example/index.html @@ -0,0 +1,418 @@ +--- +title: Exemplo de navegação Ajax +slug: Web/API/History_API/Exemplo +tags: + - Exemplo navegação ajax +translation_of: Web/API/History_API/Example +--- +

Esse é um exemplo de um web site em AJAX web site composto por apenas três páginas (first_page.php, second_page.php e third_page.php). Para ver como funciona, crie os arquivos a seguir (ou git clone https://github.com/giabao/mdn-ajax-nav-example.git ):

+ +
Nota: Para integrar completamente os elementos {{HTMLElement("form")}} com esse mecanismo, porfavor dê uma olhada no parágrafo Enviando formulários e enviando arquivos.
+ +

first_page.php:

+ +
+
<?php
+    $page_title = "Primeira página";
+
+    $as_json = false;
+    if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") {
+        $as_json = true;
+        ob_start();
+    } else {
+?>
+<!doctype html>
+<html>
+<head>
+<?php
+        include "include/header.php";
+        echo "<title>" . $page_title . "</title>";
+?>
+</head>
+
+<body>
+
+<?php include "include/before_content.php"; ?>
+
+<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>first_page.php</strong>.</p>
+
+<div id="ajax-content">
+<?php } ?>
+
+    <p>Esse é o conteúdo de <strong>first_page.php</strong>.</p>
+
+<?php
+    if ($as_json) {
+        echo json_encode(array("page" => $page_title, "content" => ob_get_clean()));
+    } else {
+?>
+</div>
+
+<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>first_page.php</strong>.</p>
+
+<?php
+        include "include/after_content.php";
+        echo "</body>\n</html>";
+    }
+?>
+
+
+ +

second_page.php:

+ +
+
<?php
+    $page_title = "Segunda página";
+
+    $as_json = false;
+    if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") {
+        $as_json = true;
+        ob_start();
+    } else {
+?>
+<!doctype html>
+<html>
+<head>
+<?php
+        include "include/header.php";
+        echo "<title>" . $page_title . "</title>";
+?>
+</head>
+
+<body>
+
+<?php include "include/before_content.php"; ?>
+
+<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>second_page.php</strong>.</p>
+
+<div id="ajax-content">
+<?php } ?>
+
+    <p>Esse é o conteúdo de <strong>second_page.php</strong>.</p>
+
+<?php
+    if ($as_json) {
+        echo json_encode(array("page" => $page_title, "content" => ob_get_clean()));
+    } else {
+?>
+</div>
+
+<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>second_page.php</strong>.</p>
+
+<?php
+        include "include/after_content.php";
+        echo "</body>\n</html>";
+    }
+?>
+
+
+ +

third_page.php:

+ +
+
<?php
+    $page_title = "Terceira página";
+    $page_content = "<p>Esse é o conteúdo de <strong>third_page.php</strong>. This content is stored into a php variable.</p>";
+
+    if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") {
+        echo json_encode(array("page" => $page_title, "content" => $page_content));
+    } else {
+?>
+<!doctype html>
+<html>
+<head>
+<?php
+        include "include/header.php";
+        echo "<title>" . $page_title . "</title>";
+?>
+</head>
+
+<body>
+
+<?php include "include/before_content.php"; ?>
+
+<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>third_page.php</strong>.</p>
+
+<div id="ajax-content">
+<?php echo $page_content; ?>
+</div>
+
+<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>third_page.php</strong>.</p>
+
+<?php
+        include "include/after_content.php";
+        echo "</body>\n</html>";
+    }
+?>
+
+
+ +

css/style.css:

+ +
#ajax-loader {
+    position: fixed;
+    display: table;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+}
+
+#ajax-loader > div {
+    display: table-cell;
+    width: 100%;
+    height: 100%;
+    vertical-align: middle;
+    text-align: center;
+    background-color: #000000;
+    opacity: 0.65;
+}
+
+ +

include/after_content.php:

+ +
<p>Esse é o rodapé. Ele é compartilhado entre todas as páginas ajax.</p>
+
+ +

include/before_content.php:

+ +
<p>
+[ <a class="ajax-nav" href="first_page.php">Primeiro exemplo</a>
+| <a class="ajax-nav" href="second_page.php">Segundo exemplo</a>
+| <a class="ajax-nav" href="third_page.php">Terceiro exemplo</a>
+| <a class="ajax-nav" href="unexisting.php">Página inexistente</a> ]
+</p>
+
+
+ +

include/header.php:

+ +
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<script type="text/javascript" src="js/ajax_nav.js"></script>
+<link rel="stylesheet" href="css/style.css" />
+
+ +

js/ajax_nav.js:

+ +

(antes de implementar em um ambiente de trabalho, porfavor leia a nota sobre a compatibilidade de declaração de const)

+ +
+
"use strict";
+
+const ajaxRequest = new (function () {
+
+    function closeReq () {
+        oLoadingBox.parentNode && document.body.removeChild(oLoadingBox);
+        bIsLoading = false;
+    }
+
+    function abortReq () {
+        if (!bIsLoading) { return; }
+        oReq.abort();
+        closeReq();
+    }
+
+    function ajaxError () {
+        alert("Unknown error.");
+    }
+
+    function ajaxLoad () {
+        var vMsg, nStatus = this.status;
+        switch (nStatus) {
+            case 200:
+                vMsg = JSON.parse(this.responseText);
+                document.title = oPageInfo.title = vMsg.page;
+                document.getElementById(sTargetId).innerHTML = vMsg.content;
+                if (bUpdateURL) {
+                    history.pushState(oPageInfo, oPageInfo.title, oPageInfo.url);
+                    bUpdateURL = false;
+                }
+                break;
+            default:
+                vMsg = nStatus + ": " + (oHTTPStatus[nStatus] || "Unknown");
+                switch (Math.floor(nStatus / 100)) {
+                    /*
+                    case 1:
+                        // Informational 1xx
+                        console.log("Information code " + vMsg);
+                        break;
+                    case 2:
+                        // Successful 2xx
+                        console.log("Successful code " + vMsg);
+                        break;
+                    case 3:
+                        // Redirection 3xx
+                        console.log("Redirection code " + vMsg);
+                        break;
+                    */
+                    case 4:
+                        /* Client Error 4xx */
+                        alert("Client Error #" + vMsg);
+                        break;
+                    case 5:
+                        /* Server Error 5xx */
+                        alert("Server Error #" + vMsg);
+                        break;
+                    default:
+                        /* Unknown status */
+                        ajaxError();
+                }
+        }
+        closeReq();
+    }
+
+    function filterURL (sURL, sViewMode) {
+        return sURL.replace(rSearch, "") + ("?" + sURL.replace(rHost, "&").replace(rView, sViewMode ? "&" + sViewKey + "=" + sViewMode : "").slice(1)).replace(rEndQstMark, "");
+    }
+
+    function getPage (sPage) {
+        if (bIsLoading) { return; }
+        oReq = new XMLHttpRequest();
+        bIsLoading = true;
+        oReq.onload = ajaxLoad;
+        oReq.onerror = ajaxError;
+        if (sPage) { oPageInfo.url = filterURL(sPage, null); }
+        oReq.open("get", filterURL(oPageInfo.url, "json"), true);
+        oReq.send();
+        oLoadingBox.parentNode || document.body.appendChild(oLoadingBox);
+    }
+
+    function requestPage (sURL) {
+        if (history.pushState) {
+            bUpdateURL = true;
+            getPage(sURL);
+        } else {
+            /* Ajax navigation is not supported */
+            location.assign(sURL);
+        }
+    }
+
+    function processLink () {
+        if (this.className === sAjaxClass) {
+            requestPage(this.href);
+            return false;
+        }
+        return true;
+    }
+
+    function init () {
+        oPageInfo.title = document.title;
+        history.replaceState(oPageInfo, oPageInfo.title, oPageInfo.url);
+        for (var oLink, nIdx = 0, nLen = document.links.length; nIdx < nLen; document.links[nIdx++].onclick = processLink);
+    }
+
+    const
+
+        /* customizable constants */
+        sTargetId = "ajax-content", sViewKey = "view_as", sAjaxClass = "ajax-nav",
+
+        /* not customizable constants */
+        rSearch = /\?.*$/, rHost = /^[^\?]*\?*&*/, rView = new RegExp("&" + sViewKey + "\\=[^&]*|&*$", "i"), rEndQstMark = /\?$/,
+        oLoadingBox = document.createElement("div"), oCover = document.createElement("div"), oLoadingImg = new Image(),
+        oPageInfo = {
+            title: null,
+            url: location.href
+        }, oHTTPStatus = /* http://www.iana.org/assignments/http-status-codes/http-status-codes.xml */ {
+            100: "Continue",
+            101: "Switching Protocols",
+            102: "Processing",
+            200: "OK",
+            201: "Created",
+            202: "Accepted",
+            203: "Non-Authoritative Information",
+            204: "No Content",
+            205: "Reset Content",
+            206: "Partial Content",
+            207: "Multi-Status",
+            208: "Already Reported",
+            226: "IM Used",
+            300: "Multiple Choices",
+            301: "Moved Permanently",
+            302: "Found",
+            303: "See Other",
+            304: "Not Modified",
+            305: "Use Proxy",
+            306: "Reserved",
+            307: "Temporary Redirect",
+            308: "Permanent Redirect",
+            400: "Bad Request",
+            401: "Unauthorized",
+            402: "Payment Required",
+            403: "Forbidden",
+            404: "Not Found",
+            405: "Method Not Allowed",
+            406: "Not Acceptable",
+            407: "Proxy Authentication Required",
+            408: "Request Timeout",
+            409: "Conflict",
+            410: "Gone",
+            411: "Length Required",
+            412: "Precondition Failed",
+            413: "Request Entity Too Large",
+            414: "Request-URI Too Long",
+            415: "Unsupported Media Type",
+            416: "Requested Range Not Satisfiable",
+            417: "Expectation Failed",
+            422: "Unprocessable Entity",
+            423: "Locked",
+            424: "Failed Dependency",
+            425: "Unassigned",
+            426: "Upgrade Required",
+            427: "Unassigned",
+            428: "Precondition Required",
+            429: "Too Many Requests",
+            430: "Unassigned",
+            431: "Request Header Fields Too Large",
+            500: "Internal Server Error",
+            501: "Not Implemented",
+            502: "Bad Gateway",
+            503: "Service Unavailable",
+            504: "Gateway Timeout",
+            505: "HTTP Version Not Supported",
+            506: "Variant Also Negotiates (Experimental)",
+            507: "Insufficient Storage",
+            508: "Loop Detected",
+            509: "Unassigned",
+            510: "Not Extended",
+            511: "Network Authentication Required"
+        };
+
+    var
+
+        oReq, bIsLoading = false, bUpdateURL = false;
+
+    oLoadingBox.id = "ajax-loader";
+    oCover.onclick = abortReq;
+    oLoadingImg.src = "data:image/gif;base64,R0lGODlhEAAQAPIAAP///wAAAMLCwkJCQgAAAGJiYoKCgpKSkiH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCgAAACwAAAAAEAAQAAADMwi63P4wyklrE2MIOggZnAdOmGYJRbExwroUmcG2LmDEwnHQLVsYOd2mBzkYDAdKa+dIAAAh+QQJCgAAACwAAAAAEAAQAAADNAi63P5OjCEgG4QMu7DmikRxQlFUYDEZIGBMRVsaqHwctXXf7WEYB4Ag1xjihkMZsiUkKhIAIfkECQoAAAAsAAAAABAAEAAAAzYIujIjK8pByJDMlFYvBoVjHA70GU7xSUJhmKtwHPAKzLO9HMaoKwJZ7Rf8AYPDDzKpZBqfvwQAIfkECQoAAAAsAAAAABAAEAAAAzMIumIlK8oyhpHsnFZfhYumCYUhDAQxRIdhHBGqRoKw0R8DYlJd8z0fMDgsGo/IpHI5TAAAIfkECQoAAAAsAAAAABAAEAAAAzIIunInK0rnZBTwGPNMgQwmdsNgXGJUlIWEuR5oWUIpz8pAEAMe6TwfwyYsGo/IpFKSAAAh+QQJCgAAACwAAAAAEAAQAAADMwi6IMKQORfjdOe82p4wGccc4CEuQradylesojEMBgsUc2G7sDX3lQGBMLAJibufbSlKAAAh+QQJCgAAACwAAAAAEAAQAAADMgi63P7wCRHZnFVdmgHu2nFwlWCI3WGc3TSWhUFGxTAUkGCbtgENBMJAEJsxgMLWzpEAACH5BAkKAAAALAAAAAAQABAAAAMyCLrc/jDKSatlQtScKdceCAjDII7HcQ4EMTCpyrCuUBjCYRgHVtqlAiB1YhiCnlsRkAAAOwAAAAAAAAAAAA==";
+    oCover.appendChild(oLoadingImg);
+    oLoadingBox.appendChild(oCover);
+
+    onpopstate = function (oEvent) {
+        bUpdateURL = false;
+        oPageInfo.title = oEvent.state.title;
+        oPageInfo.url = oEvent.state.url;
+        getPage();
+    };
+
+    window.addEventListener ? addEventListener("load", init, false) : window.attachEvent ? attachEvent("onload", init) : (onload = init);
+
+    // Public methods
+
+    this.open = requestPage;
+    this.stop = abortReq;
+    this.rebuildLinks = init;
+
+})();
+
+
+ +
Nota: A atual implementação de const (declaração de constante) não é parte do ECMAScript 5. É suportada no Firefox e no Chrome (V8) e parcialmente suportada no Opera 9+ e no Safari. Ela  não é suportada nas versões do Internet Explorer 6 ao 9, ou na versão preview do Internet Explorer 10. const será definida no ECMAScript 6, mas com semânticas diferentes. Similarmente ao que acontece com variáveis definidas como let, constantes declaradas com const serão block-scoped, limitando seu escopo no bloco. Nós só usamos isso com propósito didático. Se você quer total compatibilidade com os navegadores, substitua todas as declarações const por declarações var.
+ +

Para mais informações, veja: Manipulando o histórico do navegador.

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/history_api/exemplo/index.html b/files/pt-br/web/api/history_api/exemplo/index.html deleted file mode 100644 index a4dfc4b68f..0000000000 --- a/files/pt-br/web/api/history_api/exemplo/index.html +++ /dev/null @@ -1,418 +0,0 @@ ---- -title: Exemplo de navegação Ajax -slug: Web/API/History_API/Exemplo -tags: - - Exemplo navegação ajax -translation_of: Web/API/History_API/Example ---- -

Esse é um exemplo de um web site em AJAX web site composto por apenas três páginas (first_page.php, second_page.php e third_page.php). Para ver como funciona, crie os arquivos a seguir (ou git clone https://github.com/giabao/mdn-ajax-nav-example.git ):

- -
Nota: Para integrar completamente os elementos {{HTMLElement("form")}} com esse mecanismo, porfavor dê uma olhada no parágrafo Enviando formulários e enviando arquivos.
- -

first_page.php:

- -
-
<?php
-    $page_title = "Primeira página";
-
-    $as_json = false;
-    if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") {
-        $as_json = true;
-        ob_start();
-    } else {
-?>
-<!doctype html>
-<html>
-<head>
-<?php
-        include "include/header.php";
-        echo "<title>" . $page_title . "</title>";
-?>
-</head>
-
-<body>
-
-<?php include "include/before_content.php"; ?>
-
-<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>first_page.php</strong>.</p>
-
-<div id="ajax-content">
-<?php } ?>
-
-    <p>Esse é o conteúdo de <strong>first_page.php</strong>.</p>
-
-<?php
-    if ($as_json) {
-        echo json_encode(array("page" => $page_title, "content" => ob_get_clean()));
-    } else {
-?>
-</div>
-
-<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>first_page.php</strong>.</p>
-
-<?php
-        include "include/after_content.php";
-        echo "</body>\n</html>";
-    }
-?>
-
-
- -

second_page.php:

- -
-
<?php
-    $page_title = "Segunda página";
-
-    $as_json = false;
-    if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") {
-        $as_json = true;
-        ob_start();
-    } else {
-?>
-<!doctype html>
-<html>
-<head>
-<?php
-        include "include/header.php";
-        echo "<title>" . $page_title . "</title>";
-?>
-</head>
-
-<body>
-
-<?php include "include/before_content.php"; ?>
-
-<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>second_page.php</strong>.</p>
-
-<div id="ajax-content">
-<?php } ?>
-
-    <p>Esse é o conteúdo de <strong>second_page.php</strong>.</p>
-
-<?php
-    if ($as_json) {
-        echo json_encode(array("page" => $page_title, "content" => ob_get_clean()));
-    } else {
-?>
-</div>
-
-<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>second_page.php</strong>.</p>
-
-<?php
-        include "include/after_content.php";
-        echo "</body>\n</html>";
-    }
-?>
-
-
- -

third_page.php:

- -
-
<?php
-    $page_title = "Terceira página";
-    $page_content = "<p>Esse é o conteúdo de <strong>third_page.php</strong>. This content is stored into a php variable.</p>";
-
-    if (isset($_GET["view_as"]) && $_GET["view_as"] == "json") {
-        echo json_encode(array("page" => $page_title, "content" => $page_content));
-    } else {
-?>
-<!doctype html>
-<html>
-<head>
-<?php
-        include "include/header.php";
-        echo "<title>" . $page_title . "</title>";
-?>
-</head>
-
-<body>
-
-<?php include "include/before_content.php"; ?>
-
-<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>third_page.php</strong>.</p>
-
-<div id="ajax-content">
-<?php echo $page_content; ?>
-</div>
-
-<p>Esse parágrafo só é mostrado quando a navegação começa em <strong>third_page.php</strong>.</p>
-
-<?php
-        include "include/after_content.php";
-        echo "</body>\n</html>";
-    }
-?>
-
-
- -

css/style.css:

- -
#ajax-loader {
-    position: fixed;
-    display: table;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-}
-
-#ajax-loader > div {
-    display: table-cell;
-    width: 100%;
-    height: 100%;
-    vertical-align: middle;
-    text-align: center;
-    background-color: #000000;
-    opacity: 0.65;
-}
-
- -

include/after_content.php:

- -
<p>Esse é o rodapé. Ele é compartilhado entre todas as páginas ajax.</p>
-
- -

include/before_content.php:

- -
<p>
-[ <a class="ajax-nav" href="first_page.php">Primeiro exemplo</a>
-| <a class="ajax-nav" href="second_page.php">Segundo exemplo</a>
-| <a class="ajax-nav" href="third_page.php">Terceiro exemplo</a>
-| <a class="ajax-nav" href="unexisting.php">Página inexistente</a> ]
-</p>
-
-
- -

include/header.php:

- -
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<script type="text/javascript" src="js/ajax_nav.js"></script>
-<link rel="stylesheet" href="css/style.css" />
-
- -

js/ajax_nav.js:

- -

(antes de implementar em um ambiente de trabalho, porfavor leia a nota sobre a compatibilidade de declaração de const)

- -
-
"use strict";
-
-const ajaxRequest = new (function () {
-
-    function closeReq () {
-        oLoadingBox.parentNode && document.body.removeChild(oLoadingBox);
-        bIsLoading = false;
-    }
-
-    function abortReq () {
-        if (!bIsLoading) { return; }
-        oReq.abort();
-        closeReq();
-    }
-
-    function ajaxError () {
-        alert("Unknown error.");
-    }
-
-    function ajaxLoad () {
-        var vMsg, nStatus = this.status;
-        switch (nStatus) {
-            case 200:
-                vMsg = JSON.parse(this.responseText);
-                document.title = oPageInfo.title = vMsg.page;
-                document.getElementById(sTargetId).innerHTML = vMsg.content;
-                if (bUpdateURL) {
-                    history.pushState(oPageInfo, oPageInfo.title, oPageInfo.url);
-                    bUpdateURL = false;
-                }
-                break;
-            default:
-                vMsg = nStatus + ": " + (oHTTPStatus[nStatus] || "Unknown");
-                switch (Math.floor(nStatus / 100)) {
-                    /*
-                    case 1:
-                        // Informational 1xx
-                        console.log("Information code " + vMsg);
-                        break;
-                    case 2:
-                        // Successful 2xx
-                        console.log("Successful code " + vMsg);
-                        break;
-                    case 3:
-                        // Redirection 3xx
-                        console.log("Redirection code " + vMsg);
-                        break;
-                    */
-                    case 4:
-                        /* Client Error 4xx */
-                        alert("Client Error #" + vMsg);
-                        break;
-                    case 5:
-                        /* Server Error 5xx */
-                        alert("Server Error #" + vMsg);
-                        break;
-                    default:
-                        /* Unknown status */
-                        ajaxError();
-                }
-        }
-        closeReq();
-    }
-
-    function filterURL (sURL, sViewMode) {
-        return sURL.replace(rSearch, "") + ("?" + sURL.replace(rHost, "&").replace(rView, sViewMode ? "&" + sViewKey + "=" + sViewMode : "").slice(1)).replace(rEndQstMark, "");
-    }
-
-    function getPage (sPage) {
-        if (bIsLoading) { return; }
-        oReq = new XMLHttpRequest();
-        bIsLoading = true;
-        oReq.onload = ajaxLoad;
-        oReq.onerror = ajaxError;
-        if (sPage) { oPageInfo.url = filterURL(sPage, null); }
-        oReq.open("get", filterURL(oPageInfo.url, "json"), true);
-        oReq.send();
-        oLoadingBox.parentNode || document.body.appendChild(oLoadingBox);
-    }
-
-    function requestPage (sURL) {
-        if (history.pushState) {
-            bUpdateURL = true;
-            getPage(sURL);
-        } else {
-            /* Ajax navigation is not supported */
-            location.assign(sURL);
-        }
-    }
-
-    function processLink () {
-        if (this.className === sAjaxClass) {
-            requestPage(this.href);
-            return false;
-        }
-        return true;
-    }
-
-    function init () {
-        oPageInfo.title = document.title;
-        history.replaceState(oPageInfo, oPageInfo.title, oPageInfo.url);
-        for (var oLink, nIdx = 0, nLen = document.links.length; nIdx < nLen; document.links[nIdx++].onclick = processLink);
-    }
-
-    const
-
-        /* customizable constants */
-        sTargetId = "ajax-content", sViewKey = "view_as", sAjaxClass = "ajax-nav",
-
-        /* not customizable constants */
-        rSearch = /\?.*$/, rHost = /^[^\?]*\?*&*/, rView = new RegExp("&" + sViewKey + "\\=[^&]*|&*$", "i"), rEndQstMark = /\?$/,
-        oLoadingBox = document.createElement("div"), oCover = document.createElement("div"), oLoadingImg = new Image(),
-        oPageInfo = {
-            title: null,
-            url: location.href
-        }, oHTTPStatus = /* http://www.iana.org/assignments/http-status-codes/http-status-codes.xml */ {
-            100: "Continue",
-            101: "Switching Protocols",
-            102: "Processing",
-            200: "OK",
-            201: "Created",
-            202: "Accepted",
-            203: "Non-Authoritative Information",
-            204: "No Content",
-            205: "Reset Content",
-            206: "Partial Content",
-            207: "Multi-Status",
-            208: "Already Reported",
-            226: "IM Used",
-            300: "Multiple Choices",
-            301: "Moved Permanently",
-            302: "Found",
-            303: "See Other",
-            304: "Not Modified",
-            305: "Use Proxy",
-            306: "Reserved",
-            307: "Temporary Redirect",
-            308: "Permanent Redirect",
-            400: "Bad Request",
-            401: "Unauthorized",
-            402: "Payment Required",
-            403: "Forbidden",
-            404: "Not Found",
-            405: "Method Not Allowed",
-            406: "Not Acceptable",
-            407: "Proxy Authentication Required",
-            408: "Request Timeout",
-            409: "Conflict",
-            410: "Gone",
-            411: "Length Required",
-            412: "Precondition Failed",
-            413: "Request Entity Too Large",
-            414: "Request-URI Too Long",
-            415: "Unsupported Media Type",
-            416: "Requested Range Not Satisfiable",
-            417: "Expectation Failed",
-            422: "Unprocessable Entity",
-            423: "Locked",
-            424: "Failed Dependency",
-            425: "Unassigned",
-            426: "Upgrade Required",
-            427: "Unassigned",
-            428: "Precondition Required",
-            429: "Too Many Requests",
-            430: "Unassigned",
-            431: "Request Header Fields Too Large",
-            500: "Internal Server Error",
-            501: "Not Implemented",
-            502: "Bad Gateway",
-            503: "Service Unavailable",
-            504: "Gateway Timeout",
-            505: "HTTP Version Not Supported",
-            506: "Variant Also Negotiates (Experimental)",
-            507: "Insufficient Storage",
-            508: "Loop Detected",
-            509: "Unassigned",
-            510: "Not Extended",
-            511: "Network Authentication Required"
-        };
-
-    var
-
-        oReq, bIsLoading = false, bUpdateURL = false;
-
-    oLoadingBox.id = "ajax-loader";
-    oCover.onclick = abortReq;
-    oLoadingImg.src = "data:image/gif;base64,R0lGODlhEAAQAPIAAP///wAAAMLCwkJCQgAAAGJiYoKCgpKSkiH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCgAAACwAAAAAEAAQAAADMwi63P4wyklrE2MIOggZnAdOmGYJRbExwroUmcG2LmDEwnHQLVsYOd2mBzkYDAdKa+dIAAAh+QQJCgAAACwAAAAAEAAQAAADNAi63P5OjCEgG4QMu7DmikRxQlFUYDEZIGBMRVsaqHwctXXf7WEYB4Ag1xjihkMZsiUkKhIAIfkECQoAAAAsAAAAABAAEAAAAzYIujIjK8pByJDMlFYvBoVjHA70GU7xSUJhmKtwHPAKzLO9HMaoKwJZ7Rf8AYPDDzKpZBqfvwQAIfkECQoAAAAsAAAAABAAEAAAAzMIumIlK8oyhpHsnFZfhYumCYUhDAQxRIdhHBGqRoKw0R8DYlJd8z0fMDgsGo/IpHI5TAAAIfkECQoAAAAsAAAAABAAEAAAAzIIunInK0rnZBTwGPNMgQwmdsNgXGJUlIWEuR5oWUIpz8pAEAMe6TwfwyYsGo/IpFKSAAAh+QQJCgAAACwAAAAAEAAQAAADMwi6IMKQORfjdOe82p4wGccc4CEuQradylesojEMBgsUc2G7sDX3lQGBMLAJibufbSlKAAAh+QQJCgAAACwAAAAAEAAQAAADMgi63P7wCRHZnFVdmgHu2nFwlWCI3WGc3TSWhUFGxTAUkGCbtgENBMJAEJsxgMLWzpEAACH5BAkKAAAALAAAAAAQABAAAAMyCLrc/jDKSatlQtScKdceCAjDII7HcQ4EMTCpyrCuUBjCYRgHVtqlAiB1YhiCnlsRkAAAOwAAAAAAAAAAAA==";
-    oCover.appendChild(oLoadingImg);
-    oLoadingBox.appendChild(oCover);
-
-    onpopstate = function (oEvent) {
-        bUpdateURL = false;
-        oPageInfo.title = oEvent.state.title;
-        oPageInfo.url = oEvent.state.url;
-        getPage();
-    };
-
-    window.addEventListener ? addEventListener("load", init, false) : window.attachEvent ? attachEvent("onload", init) : (onload = init);
-
-    // Public methods
-
-    this.open = requestPage;
-    this.stop = abortReq;
-    this.rebuildLinks = init;
-
-})();
-
-
- -
Nota: A atual implementação de const (declaração de constante) não é parte do ECMAScript 5. É suportada no Firefox e no Chrome (V8) e parcialmente suportada no Opera 9+ e no Safari. Ela  não é suportada nas versões do Internet Explorer 6 ao 9, ou na versão preview do Internet Explorer 10. const será definida no ECMAScript 6, mas com semânticas diferentes. Similarmente ao que acontece com variáveis definidas como let, constantes declaradas com const serão block-scoped, limitando seu escopo no bloco. Nós só usamos isso com propósito didático. Se você quer total compatibilidade com os navegadores, substitua todas as declarações const por declarações var.
- -

Para mais informações, veja: Manipulando o histórico do navegador.

- -

Veja também

- - diff --git a/files/pt-br/web/api/html_drag_and_drop_api/file_drag_and_drop/index.html b/files/pt-br/web/api/html_drag_and_drop_api/file_drag_and_drop/index.html new file mode 100644 index 0000000000..13609ee260 --- /dev/null +++ b/files/pt-br/web/api/html_drag_and_drop_api/file_drag_and_drop/index.html @@ -0,0 +1,91 @@ +--- +title: Arrastar e soltar arquivos +slug: DragDrop/Drag_and_Drop/Arrastar_e_soltar_arquivos +translation_of: Web/API/HTML_Drag_and_Drop_API/File_drag_and_drop +--- +

{{DefaultAPISidebar("HTML Drag and Drop API")}}

+ +

As interfaces HTML Drag and Drop permitem que os aplicativos da Web arrastem e soltem arquivos em uma página da Web. Este documento descreve como um aplicativo pode aceitar um ou mais arquivos que são arrastados do gerenciador de arquivos da plataforma subjacente e soltado s em uma página da Web.

+ +

Os principais passos para o drag and drop é definir a drop zone (ou seja  definir um elemento para a queda dos arquivos) e definir  event handlers para os eventos {{event("drop")}} e {{event("dragover")}} . Essas etapas são descritas abaixo, incluindo exemplos de trechos de código. O codigo fonte esta disponivel em MDN's drag-and-drop repository (pull requests e/ou issues são bem-vindas).

+ +

Nota: {{domxref("HTML_Drag_and_Drop_API","HTML drag and drop")}}Define duas APIs diferentes para suportar arrastar e soltar arquivos. Uma API é a interface {{domxref("DataTransfer")}} e a segunda API é a interface {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}}. Este exemplo ilustra o uso de ambas as APIs (e não usa nehuma interface específica do Gecko).

+ +

Definindo a drop zone

+ +

O elemento de destino do evento {{event("drop")}} precisa de um event handler global  {{domxref("GlobalEventHandlers.ondrop","ondrop")}} O seguinte trecho de código mostra como isso é feito com um elemento: {{HTMLelement("div")}}

+ +
<div id="drop_zone" ondrop="dropHandler(event);">
+  <p>Drag one or more files to this Drop Zone ...</p>
+</div>
+ +

Normalmente, um aplicativo inclui um event handler {{event("dragover")}} no elemento de destino do drop e esse manipulador desativará o comportamento de arraste padrão do navegador. Para adicionar esse handler, você precisa incluir um event handler global {{domxref("GlobalEventHandlers.ondragover","ondragover")}}:

+ +
<div id="drop_zone" ondrop="dropHandler(event);" ondragover="dragOverHandler(event);">
+  <p>Drag one or more files to this Drop Zone ...</p>
+</div>
+
+ +

Por fim, um aplicativo pode querer estilizar o elemento da drop zone para indicar visualmente que o elemento é uma drop zone. Neste exemplo, o elemento da drop zone usa o seguinte estilo:

+ +
#drop_zone {
+  border: 5px solid blue;
+  width:  200px;
+  height: 100px;
+}
+
+ +
+

Nota: Observe que os eventos dragstart e dragend não são acionados ao arrastar um arquivo para o navegador do OS.

+
+ +

Processo de drop

+ +

O evento {{event("drop")}} é acionado quando o usuário solta o(s) arquivo(s)  no drop handler, se o navegador suportar a interface {{domxref("DataTransferItemList")}} o metodo {{domxref("DataTransferItem.getAsFile","getAsFile()")}} será usado para acessar cada arquivo; caso contrário, a interface {{domxref("DataTransfer")}} usara a propriedade {{domxref("DataTransfer.files","files")}} para acessar cada arquivo.

+ +

Este exemplo mostra como escrever o nome de cada arquivo arrastado,  no console. Em um aplicativo real, um aplicativo pode querer processar um arquivo usando o {{domxref("File","File API")}}.

+ +

Observe que neste exemplo, Qualquer item de arrasto que não seja um arquivo é ignorado.

+ +
function dropHandler(ev) {
+  console.log('File(s) dropped');
+
+  // Impedir o comportamento padrão (impedir que o arquivo seja aberto)
+  ev.preventDefault();
+
+  if (ev.dataTransfer.items) {
+    // Use a interface DataTransferItemList para acessar o (s) arquivo (s)
+    for (var i = 0; i < ev.dataTransfer.items.length; i++) {
+      // Se os itens soltos não forem arquivos, rejeite-os
+      if (ev.dataTransfer.items[i].kind === 'file') {
+        var file = ev.dataTransfer.items[i].getAsFile();
+        console.log('... file[' + i + '].name = ' + file.name);
+      }
+    }
+  } else {
+    // Use a interface DataTransfer para acessar o (s) arquivo (s)
+    for (var i = 0; i < ev.dataTransfer.files.length; i++) {
+      console.log('... file[' + i + '].name = ' + ev.dataTransfer.files[i].name);
+    }
+  }
+}
+ +

Impedir o evento de arrastar padrão do navegador

+ +

O seguinte event handler {{event("dragover")}} chama {{domxref("Event.preventDefault","preventDefault()")}} para desativar o manipulador padrão de arrastar e soltar do navegador.

+ +
function dragOverHandler(ev) {
+  console.log('File(s) in drop zone');
+
+  // Impedir o comportamento padrão (impedir que o arquivo seja aberto)
+  ev.preventDefault();
+}
+
+ +

Veja também

+ + diff --git a/files/pt-br/web/api/html_drag_and_drop_api/index.html b/files/pt-br/web/api/html_drag_and_drop_api/index.html new file mode 100644 index 0000000000..10e5592b91 --- /dev/null +++ b/files/pt-br/web/api/html_drag_and_drop_api/index.html @@ -0,0 +1,258 @@ +--- +title: Arrastar e soltar +slug: DragDrop/Drag_and_Drop +tags: + - Avançado + - Guia(2) + - HTML5 + - Visão Geral + - XUL + - arrastar e soltar + - eventos +translation_of: Web/API/HTML_Drag_and_Drop_API +--- +

{{DefaultAPISidebar("HTML Drag and Drop API")}}

+ +

As interfaces de Drag and Drop (arrastar e soltar) habilitam aplicações a usar funcionalidades de arrastar e soltar através do navegador. Por exemplo, com essas funcionalidades, o usuário pode selecionar elementos arrastáveis (draggable) com o mouse, arrastar elementos até um elemento soltável (droppable), e soltar o elemento ao soltar o botão do mouse. Uma representação translúcida de elementos arrastáveis (draggable) seguem o ponteiro do mouse durante a operação de arrastar (drag).

+ +

Para web sites, extensões e aplicações XUL, você pode customizar os tipos de elementos que podem se tornar arrastáveis (draggable) e o tipo de retorno que o elemento arrastável produz, assim como os elementos soltáveis (droppable).

+ +

NT: Para manter a tradução mais precisa e coesa, a partir daqui iremos manter os termos drag e drop e seus variantes conforme texto original. Sendo portanto mantidos também os termos draggable e droppable.

+ +

Este documento é uma visão geral do drag and drop no HTML. Ele inclui uma descrição de suas interfaces, funcionalidades básicas de como permitir a adesão de funcionalidades arrastar e soltar em uma aplicação e um sumário da interoperabilidade entre interfaces.

+ +

Eventos Drag

+ +

O drag and drop em HTML usa o {{domxref("Event","modelo de eventos DOM")}} e os {{domxref("DragEvent","eventos drag")}} são hereditários dos {{domxref("MouseEvent","eventos do mouse")}}. Uma operação típica de drag começa quando o usuário seleciona um elemento arrastável com o mouse, move o mouse até um elemento soltável (droppable) e solta o mouse. Durante as operações, diversos tipos de evento são acionados e alguns podem até ser acionados multiplas vezes (como por exemplo os tipos de evento {{event("drag")}} e {{event("dragover")}}.

+ +

Todos os tipos de evento drag são associados a um manipulador global de eventos. Cada tipo de evento drag e cada atributo drag global tem um documento de referência que o descreve. A tabela a seguir descreve brevemente os tipos de evento e um link de referência para seu documento.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventOn Event HandlerDescription
{{event('drag')}}{{domxref('GlobalEventHandlers.ondrag','ondrag')}}Acionado quando um elemento ou seleção de texto está sendo arrastado.
{{event('dragend')}}{{domxref('GlobalEventHandlers.ondragend','ondragend')}}Acionado quando uma operação de arrastar está terminando (por eexmplo, ao soltar o botão do mouse ou pressionar a tecla esc). (Veja Terminando um evento Drag.)
{{event('dragenter')}}{{domxref('GlobalEventHandlers.ondragenter','ondragenter')}}Acionado quando um elemento arrastável ou seleção de texto entra em um ponto de soltura (drop target). (Veja Determinando Drop Targets.)
{{event('dragexit')}}{{domxref('GlobalEventHandlers.ondragexit','ondragexit')}}Acionado quando um elemento não é mais o ponto de seleção imediata da operação drag.
{{event('dragleave')}}{{domxref('GlobalEventHandlers.ondragleave','ondragleave')}}Acionado quando um elemento arrastável ou seleção de texto abandona um ponto de soltura (drop target) válido.
{{event('dragover')}}{{domxref('GlobalEventHandlers.ondragover','ondragover')}}Acionado quando um elemento ou seleção de texto está sendo arrastado sobre um ponto de soltura válido (a cada aproximadamente 100 milisegundos).
{{event('dragstart')}}{{domxref('GlobalEventHandlers.ondragstart','ondragstart')}}Acionado quando o usuário começa a arrastar um elemento válido ou seleção de texto. (Veja Começando uma Operação Drag.)
{{event('drop')}}{{domxref('GlobalEventHandlers.ondrop','ondrop')}}Acionado quando um elemento ou seleção de texto é solta em um ponto d soltura (drop target) válido. (Veja Realizando um Drop.)
+ +

Note que eventos dragstart e dragend não são acionados ao arrastar um arquivo vindo do sistema operacional para o navegador.

+ +

Interfaces

+ +

A interface HTML drag and drop é composta pelos eventos {{domxref("DragEvent")}}, {{domxref("DataTransfer")}}, {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}}.

+ +

A interface {{domxref("DragEvent")}} consiste de um construtor e uma propriedade, a propriedade {{domxref("DragEvent.dataTransfer","dataTransfer")}} que é um objeto {{domxref("DataTransfer")}}. Os objetos {{domxref("DataTransfer")}} incluem estados do evento drag como o tipo de drag sendo feito (por exemplo copy ou move), os dados do do evento drag (um ou mais itens) e o tipo de cada item drag (um MIME type). Objetos {{domxref("DataTransfer")}} também contém métodos para adicionar itens aos dados do drag e remover um item. As interfaces {{domxref("DragEvent")}} e {{domxref("DataTransfer")}} devem as únicas necessárias para adicionar capacidades de drag and drop para uma aplicação. Entretanto, note que o Firefox provê suporte para apenas algumas {{anch("Gecko specific interfaces","Gecko-specific extensions")}} ao objeto {{domxref("DataTransfer")}}, apesar de entretanto essas extensões funcionarem apenas no Firefox.

+ +

Cada objeto {{domxref("DataTransfer")}} contém uma propriedade {{domxref("DataTransfer.items","items")}} que é uma {{domxref("DataTransferItemList","lista")}} dos objetos {{domxref("DataTransferItem")}}. Cada objeto {{domxref("DataTransferItem")}} representa um único drag item e cada item tem uma propriedade {{domxref("DataTransferItem.kind","kind (tipo)")}} que é o tipo(kind) de data (seja ela string ou file) e uma propriedade {{domxref("DataTransferItem.type","type (tipo)")}} que é o tipo de dado do item (ou seja, MIME type). O objeto {{domxref("DataTransferItem")}} também contém métodos para conseguir dados do item arrastável.

+ +

O objeto {{domxref("DataTransferItemList")}} é uma lista de objetos {{domxref("DataTransferItem")}}. A lista de objetos contém métodos para: adicionar um item para uma lista, remover um item de uma lista e limpar a lista com todos os itens.

+ +

A diferença chave entre das interfaces {{domxref("DataTransfer")}} e {{domxref("DataTransferItem")}} é que a primeira usa o método síncrono {{domxref("DataTransfer.getData","getData()")}} para acessar os dados de um item arrastável, e a segunda usa o método assíncrono {{domxref("DataTransferItem.getAsString","getAsString()")}} para acessá-lo.

+ +

Note: as interfaces {{domxref("DragEvent")}} e a {{domxref("DataTransfer")}} são vastamente interoperáveis com navegadores desktop. Entretanto, as interfaces {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}} tem suporte limitado entre navegadores. Veja {{anch("Interoperabildade")}} para mais informações.

+ +

Interfaces específicas para o Gecko

+ +

A Mozilla e o Firefox suportam algumas funcionalidades fora dos padrões do modelo drag and drop. Elas são cfunções convenientes para facilitar o arraste múltiplo de elementos e a manipulação de dados que não são strings (como arquivos). Para mais informações, veja Dragging and Dropping Multiple Items. Para mais informações, veja a página de referência {{domxref("DataTransfer")}} para todas as propriedades específicas para o Gecko e Métodos específicos para o Gecko.

+ +

O básico

+ +

Esta seção dispõe de um resumo das etapas básicas para adicionar a funcionalidade drag and drop à uma aplicação. Cada seção inclui uma descrição da etapa, um breve exemplo em código, e links para informações adicionais.

+ +

Identificando o que é arrastável (draggable)

+ +

Para fazer um elemento se tornar arrastável, é necessária a adição de um atributo {{htmlattrxref("draggable")}} além da adição do manipulador de eventos global {{domxref("GlobalEventHandlers.ondragstart","ondragstart")}}, conforme descrito no exemplo a seguir

+ +
function dragstart_handler(ev) {
+ console.log("dragStart");
+ // Adiciona o id do elemento em questão ao objeto de transferência de dados (dataTransfer)
+ ev.dataTransfer.setData("text/plain", ev.target.id);
+}
+
+<body>
+ <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">Este elemento é arrastável.</p>
+</body>
+
+ +

Veja a referência do atributo draggable e o Guia de operações drag para mais informações.

+ +

Defina os dados do drag

+ +

A aplicação é livre para incluir qualquer quantidade de dados do item em uma operação drag. Cada dado de um item é uma {{domxref("DOMString","string")}} de um tipo particular, tipicamente um MIME type como por exemplo text/html.

+ +

Cada {{domxref("DragEvent","evento drag")}} tem uma propriedade {{domxref("DragEvent.dataTransfer","dataTransfer")}} que segura os dados do evento. Essa propridade (que é um objeto {{domxref("DataTransfer")}}) também tem um método para gerenciar os dados do arraste (drag). O método {{domxref("DataTransfer.setData","setData()")}} é usado para adicionar um item aos dados do arraste, como demonstrado no exemplo a seguir.

+ +
function dragstart_handler(ev) {
+  // Adiciona os dados do arraste (drag)
+  ev.dataTransfer.setData("text/plain", ev.target.id);
+  ev.dataTransfer.setData("text/html", "<p>Parágrafo de exemplo</p>");
+  ev.dataTransfer.setData("text/uri-list", "http://developer.mozilla.org");
+}
+
+ +

Para uma lista de tipos de dados mais comuns utilizados pelo drag and drop (como texto, HTML, links, e files), veja Tipos recomendados de Drag Types e para mais informações sobre os dados do arraste (drag data), veja Drag Data.

+ +

Defina uma imagem de arraste (drag image)

+ +

Por padrão, o navegador provê uma imagem que aparece por trás do ponteiro do mouse durante uma operação de arraste. Entretanto, uma aplicação pode definir uma imagem customizada utilizando o método {{domxref("DataTransfer.setDragImage","setDragImage()")}} como demonstrado no exemplo a seguir.

+ +
function dragstart_handler(ev) {
+  // Cria uma imagem e então a utiliza como a "drag image".
+  // NOTA: mude "example.gif" como uma imagem existente, caso contrário
+  // ela não será criada e a imagem padrão será utilizada como padrão.
+  var img = new Image();
+  img.src = 'example.gif';
+  ev.dataTransfer.setDragImage(img, 10, 10);
+}
+
+ +

Para aprender mais sobre arrastar imagens de retorno, veja Definindo a imagem de retorno do arraste (Drag).

+ +

Defina o efeito do arraste (Drag effect)

+ +

A propriedade {{domxref("DataTransfer.dropEffect","dropEffect")}} é usada para controlar o retorno (geralmente visual) que é dado ao usuário durante uma operação drag and drop. Ela afeta qual cursor o navegador irá mostrar enquanto o arraste é realizado. Por exemplo, quando o usuário passa sobre (famoso hover) o ponto de soltura (drop target), o cursor do navegador pode indicar o tipo de operação que irá acontecer.

+ +

Três efeitos podem ser definidos: 

+ +

copy indica que os dados sendo arrastados podem ser copiados da localização atual para a localização de destino (localização do drop). 

+ +

move indica que os dados sendo arrastados irá ser movido.

+ +

link indica que alguma forma de relação ou conexão será criada entre a localização de origem (source) e de destino (drop). 

+ +

Durante a operação de arraste, os efeitos do arraste (drag) podem ser modificados para determinar que certos efeitos são permitidos em determinadas localizações. Se permitido, uma soltura (drop) pode ocorrer naquela localização.

+ +

O exemplo a seguir mostra como utilizar essa propriedade.

+ +
function dragstart_handler(ev) {
+  // Determina o efeito de arraste para copy
+  ev.dataTransfer.dropEffect = "copy";
+}
+
+ +

Veja Efeitos do Arraste (Drag Effects) para mais detalhes.

+ +

Defina uma zona de soltura (drop zone)

+ +

Por padrão, o navegador previne tudo que possa acontecer ao soltar alguma coisa em um elemento HTML. Para mudar esse comportamento de forma que um elemento se torne uma zona de soltura (drop zone) ou que seja soltável (droppable), o elemento precisa ter ambos os atributos  {{domxref("GlobalEventHandlers.ondragover","ondragover")}} e {{domxref("GlobalEventHandlers.ondrop","ondrop")}}. O exemplo a seguir mostra como utilizar esses atributos e inclui manipuladores básicos de evento para cada um.

+ +
function dragover_handler(ev) {
+ ev.preventDefault();
+ // Define o dropEffect para ser do tipo move
+ ev.dataTransfer.dropEffect = "move"
+}
+function drop_handler(ev) {
+ ev.preventDefault();
+ // Pega o id do alvo e adiciona o elemento que foi movido para o DOM do alvo
+ var data = ev.dataTransfer.getData("text");
+ ev.target.appendChild(document.getElementById(data));
+}
+<body>
+ <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Zona de Soltura (Drop Zone)</div>
+</body>
+
+ +

Note que cada manipulador chama {{domxref("Event.preventDefault","preventDefault()")}} para previnir o processamento adicional de eventos (como eventos touch ou eventos pointer).

+ +

Para mais informações, veja Especificando pontos de soltura (Drop Targets).

+ +

Manipulando o efeito de soltura (drop)

+ +

O manipulador do evento {{event("drop")}} é livre para processar os dados do arraste (drag) de maneira específica em uma aplicação. Tipicamente, uma aplicação usaria o método {{domxref("DataTransfer.getData","getData()")}} para reter os itens arrastados e processá-los de acordo. A semântica da aplicação pode ser diferente dependendo do valor do {{domxref("DataTransfer.dropEffect","dropEffect")}} e/ou o estado da chave que o modifica.

+ +

O exemplo a seguir mostra o manipulador de soltura (drop handler) pegando o id do elemento de origem atráves dos dados de drag (drag data) e então usando o id para mover o elemento de sua origem para o elemento de soltura (drop element).

+ +
function dragstart_handler(ev) {
+ // Adiciona o id do elemento alvo para o objeto de transferência de dados
+ ev.dataTransfer.setData("text/plain", ev.target.id);
+ ev.dropEffect = "move";
+}
+function dragover_handler(ev) {
+ ev.preventDefault();
+ // Define o dropEffect para ser do tipo move
+ ev.dataTransfer.dropEffect = "move"
+}
+function drop_handler(ev) {
+ ev.preventDefault();
+ // Pega o id do alvo e adiciona o elemento que foi movido para o DOM do alvo
+ var data = ev.dataTransfer.getData("text");
+ ev.target.appendChild(document.getElementById(data));
+}
+<body>
+ <p id="p1" draggable="true" ondragstart="dragstart_handler(event);">Este elemento é arrastável.</p>
+ <div id="target" ondrop="drop_handler(event);" ondragover="dragover_handler(event);">Zona de Soltura (Drop Zone)</div>
+</body>
+
+ +

Para mais informações, veja Realizando uma soltura (Drop).

+ +

Fim da soltura (Drag end)

+ +

No início da operação de arraste (drag), o evento {{event("dragend")}} é acionado no elemento de origem (source) - o elemento que foi o alvo do início do arraste (drag start). Este evento é acionado sempre quando o arraste é completado ou cancelado. O manipulador de eventos {{event("dragend")}} pode verificar o valor da propriedade {{domxref("DataTransfer.dropEffect","dropEffect")}} para determinar se a operação de arraste foi bem sucedida ou não.

+ +

Para mais informações sobre manipular o final de uma operação de arraste, veja Finalizando um arraste (Drag).

+ +

Interoperabilidade

+ +

Como podem ser visto no DataTransferItem interface's Browser Compatibility table, drag-and-drop a interoperabilidade é relativamente ampla emtre ps brpwsers desktop (exceto as interfaces {{domxref("DataTransferItem")}} e {{domxref("DataTransferItemList")}}  que tem o menor suport). Estes dados tambem indica que o suporte ao drag and drop entre browser mobile é muito menor.

+ +

Exemplos e demonstrações

+ + + +

Veja também

+ + diff --git a/files/pt-br/web/api/htmlcontentelement/select/index.html b/files/pt-br/web/api/htmlcontentelement/select/index.html new file mode 100644 index 0000000000..63fae05c69 --- /dev/null +++ b/files/pt-br/web/api/htmlcontentelement/select/index.html @@ -0,0 +1,98 @@ +--- +title: HTMLContentElement.select +slug: Web/API/HTMLContentElement/Seletor +tags: + - API + - HTMLContentElement + - HTMLContentElement.select + - Select +translation_of: Web/API/HTMLContentElement/select +--- +

{{ APIRef("Web Components") }}

+ +

A propriedade HTMLContentElement.select reflete o atributo selecionado. É um {{domxref("DOMString")}} contendo uma lista de spaço-separado de seletores CSS que seleciona o conteúdo para inserir em lugar do elemento <content>.

+ +

Sintaxe

+ +
object.select = "CSSselector CSSselector ...";
+
+ +

Exemplo

+ +
// Select <h1> elements and elements with class="error"
+myContentObject.select = "h1 .error";
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçõesStatusCommentário
{{SpecName('Shadow DOM', '#the-content-element', 'content')}}{{Spec2('Shadow DOM')}} 
+ +

Compatibilidade do browser

+ +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + +
ComponenteChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico35{{CompatGeckoDesktop("28")}} [1]{{CompatNo}}26{{CompatNo}}
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Suporte básico37{{CompatGeckoMobile("28")}} [1]{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}
+
+ +

[1] Se Shadow DOM não estiver habilitado no Firefox, os elementos <content> se comportarão como {{domxref("HTMLUnknownElement")}}. Shadow DOM foi o primeiro implementado no Firefox 28 e está atrás de uma preferência, dom.webcomponents.enabled, ao qual é desabilitado por padrão.

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/htmlcontentelement/seletor/index.html b/files/pt-br/web/api/htmlcontentelement/seletor/index.html deleted file mode 100644 index 63fae05c69..0000000000 --- a/files/pt-br/web/api/htmlcontentelement/seletor/index.html +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: HTMLContentElement.select -slug: Web/API/HTMLContentElement/Seletor -tags: - - API - - HTMLContentElement - - HTMLContentElement.select - - Select -translation_of: Web/API/HTMLContentElement/select ---- -

{{ APIRef("Web Components") }}

- -

A propriedade HTMLContentElement.select reflete o atributo selecionado. É um {{domxref("DOMString")}} contendo uma lista de spaço-separado de seletores CSS que seleciona o conteúdo para inserir em lugar do elemento <content>.

- -

Sintaxe

- -
object.select = "CSSselector CSSselector ...";
-
- -

Exemplo

- -
// Select <h1> elements and elements with class="error"
-myContentObject.select = "h1 .error";
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçõesStatusCommentário
{{SpecName('Shadow DOM', '#the-content-element', 'content')}}{{Spec2('Shadow DOM')}} 
- -

Compatibilidade do browser

- -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - -
ComponenteChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico35{{CompatGeckoDesktop("28")}} [1]{{CompatNo}}26{{CompatNo}}
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Suporte básico37{{CompatGeckoMobile("28")}} [1]{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}
-
- -

[1] Se Shadow DOM não estiver habilitado no Firefox, os elementos <content> se comportarão como {{domxref("HTMLUnknownElement")}}. Shadow DOM foi o primeiro implementado no Firefox 28 e está atrás de uma preferência, dom.webcomponents.enabled, ao qual é desabilitado por padrão.

- -

Veja também

- - diff --git a/files/pt-br/web/api/htmlelement/accesskey/index.html b/files/pt-br/web/api/htmlelement/accesskey/index.html new file mode 100644 index 0000000000..e0425e3645 --- /dev/null +++ b/files/pt-br/web/api/htmlelement/accesskey/index.html @@ -0,0 +1,19 @@ +--- +title: Element.accessKey +slug: Web/API/Element/accessKey +translation_of: Web/API/HTMLElement/accessKey +translation_of_original: Web/API/Element/accessKey +--- +
{{APIRef("DOM")}}
+ +
 
+ +

A propriedade Element.accessKey define a tecla pelo qual o usuário pode pressionar para saltar para este elemento.

+ +
+

Nota: A propriedade Element.accessKey é raramente usada por causa dos conflitos múltiplos com os atalhos pré-definidos nos navegadores. Para contornar isto, os navegadores implementam o comportamento da tecla de acesso se as teclas são pressionadas com outras teclas "qualificadas" (como Alt + tecla de acesso).

+
+ +

 

+ +

 

diff --git a/files/pt-br/web/api/htmlelement/blur/index.html b/files/pt-br/web/api/htmlelement/blur/index.html deleted file mode 100644 index 25a2273aec..0000000000 --- a/files/pt-br/web/api/htmlelement/blur/index.html +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: HTMLElement.blur() -slug: Web/API/HTMLElement/blur -tags: - - API - - DOM HTML - - Foco - - HTMLElement - - Referencia - - metodo -translation_of: Web/API/HTMLOrForeignElement/blur ---- -
{{ APIRef("HTML DOM") }}
- -

O método HTMLElement.blur() remove o foco do teclado no elemento corrente.

- -

Sintaxe

- -
elemento.blur();
- -

Exemplos

- -

Removendo o foco de um input de texto

- -

HTML

- -
<input type="text" id="meuTexto" value="Texto Exemplo">
-<br><br>
-<button type="button" onclick="focusInput()">Clique para definir o foco</button>
-<button type="button" onclick="blurInput()">Clique para remover o foco</button>
- -

JavaScript

- -
function focusInput() {
-  document.getElementById('meuTexto').focus();
-}
-function blurInput() {
-  document.getElementById('meuTexto').blur();
-}
- -

Resultado

- -

{{ EmbedLiveSample('Remove_focus_from_a_text_input') }}

- -

Especificação

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'editing.html#dom-blur', 'blur')}}{{Spec2('HTML WHATWG')}} 
{{SpecName('HTML5.1', 'editing.html#blur()-0', 'blur')}}{{Spec2('HTML5.1')}} 
{{SpecName('HTML5 W3C', 'editing.html#dom-blur', 'blur')}}{{Spec2('HTML5 W3C')}} 
{{SpecName('DOM2 HTML', 'html.html#ID-28216144', 'blur')}}{{Spec2('DOM2 HTML')}} 
- -

Compatibilidade com navegadores

- - - -

{{Compat("api.HTMLElement.blur")}}

- -

Veja também

- - diff --git a/files/pt-br/web/api/htmlelement/dataset/index.html b/files/pt-br/web/api/htmlelement/dataset/index.html deleted file mode 100644 index 2cb4ba63b0..0000000000 --- a/files/pt-br/web/api/htmlelement/dataset/index.html +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: HTMLElement.dataset -slug: Web/API/HTMLElement/dataset -translation_of: Web/API/HTMLOrForeignElement/dataset ---- -

{{ APIRef }}

- -

A propriedade HTMLElement.dataset permite o acesso, em modo de leitura e escrita, a todos os atributos de dados personalizado (data-*) no elemento. Ele é um mapa de DOMString, com uma entrada para cada atributo de dados personalizado.

- -

O nome de um atributo de dados customizado inicia com data-. Ele deve conter somente letras, números e os seguintes caracteres: dash (-), dot (.), collon(:), underscore (_). Além disso, ele não deve conter letras ASCII captalizadas (A à Z).

- -

Um atributo de dados personalizado é transformado em uma chave para uma entrada no {{ domxref("DOMStringMap") }} de acordo com as seguintes regras

- - - -

A transformação oposta, que mapeia uma chave para um nome de atributo, usa as seguintes regras:

- - - -

A restrição nas regras acima garantem que as duas trasnformações são inversa uma da outra.

- -

Por exemplo, o atributo data-abc-def corresponde a chave abcDef.

- -

Sintaxe

- -
string = element.dataset.camelCasedName;
-element.dataset.camelCasedName = string;
- -

Exemplos

- -
<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe
-</div>
-
-var el = document.querySelector('#user');
-
-// el.id == 'user'
-// el.dataset.id === '1234567890'
-// el.dataset.user === 'johndoe'
-// el.dataset.dateOfBirth === ''
-
-el.dataset.dateOfBirth = '1960-10-03'; // set the DOB.
-
-// 'someDataAttr' in el.dataset === false
-
-el.dataset.someDataAttr = 'mydata';
-// 'someDataAttr' in el.dataset === true
-
- -

Especificações

- - - - - - - - - - - - - - - - - - - - - - - - -
EspeficicaçãoStatusComentário
{{SpecName('HTML WHATWG', "dom.html#dom-dataset", "HTMLElement.dataset")}}{{Spec2('HTML WHATWG')}}Sem mudanças desde o último  snapshot, {{SpecName('HTML5.1')}}
{{SpecName('HTML5.1', "dom.html#dom-dataset", "HTMLElement.dataset")}}{{Spec2('HTML5.1')}}Snapshot de {{SpecName('HTML WHATWG')}}, sem mudanças desde {{SpecName('HTML5 W3C')}}
{{SpecName('HTML5 W3C', "dom.html#dom-dataset", "HTMLElement.dataset")}}{{Spec2('HTML5 W3C')}}Snapshot de {{SpecName('HTML WHATWG')}}, definição inicial.
- -

Compatibilidade com Browsers

- - - -

{{Compat("api.HTMLElement.dataset")}}

- -

Veja também

- - diff --git a/files/pt-br/web/api/htmlelement/focus/index.html b/files/pt-br/web/api/htmlelement/focus/index.html deleted file mode 100644 index 8f798b3d86..0000000000 --- a/files/pt-br/web/api/htmlelement/focus/index.html +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: HTMLElement.focus() -slug: Web/API/HTMLElement/focus -translation_of: Web/API/HTMLOrForeignElement/focus ---- -
{{ APIRef("HTML DOM") }}
- -

O método HTMLElement.focus()  seta o foco em um determinado elemento em especifico, caso esse elemento permita ter o foco neste elemento.

- -

Síntaxe

- -
element.focus()
- -

Especificação

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'editing.html#dom-focus', 'focus')}}{{Spec2('HTML WHATWG')}} 
{{SpecName('HTML5.1', 'editing.html#focus()-0', 'focus')}}{{Spec2('HTML5.1')}} 
{{SpecName('HTML5 W3C', 'editing.html#dom-focus', 'focus')}}{{Spec2('HTML5 W3C')}} 
{{SpecName('DOM2 HTML', 'html.html#ID-32130014', 'focus')}}{{Spec2('DOM2 HTML')}} 
{{SpecName('DOM1', 'level-one-html.html#method-focus', 'focus')}}{{Spec2('DOM1')}} 
- -

Notas

- -

Caso você utilize o HTMLElement.focus() por meio da manipulação de um evento mousedown , você deve utilizar o evento event.preventDefault() a fim de o foco não sair do arquivo HTMLElement.

- -

Veja também

- - diff --git a/files/pt-br/web/api/htmlelement/innertext/index.html b/files/pt-br/web/api/htmlelement/innertext/index.html new file mode 100644 index 0000000000..1ab5e81027 --- /dev/null +++ b/files/pt-br/web/api/htmlelement/innertext/index.html @@ -0,0 +1,86 @@ +--- +title: Node.innerText +slug: Web/API/Node/innerText +translation_of: Web/API/HTMLElement/innerText +--- +
{{APIRef("DOM")}}
+ +

Resumo

+ +

Node.innerText é uma propriedade que representa o conteúdo textual "renderizado" de um nó e seus descendentes. Usada como getter, retorna de maneira aproximada o texto que o usuário obteria caso tivesse selecionado o conteúdo e copiado para a área de transferência. Este recurso fora introduzido originalmente pelo Internet Explorer, mas foi oficialmente especificado no padrão HTML apenas em 2016, sendo adotado por todos os principais navegadores a partir de então.

+ +

{{domxref("Node.textContent")}} é uma alternativa similar, embora existam diferenças significativas entre as duas.

+ +

Especificação

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'dom.html#the-innertext-idl-attribute', 'innerText')}}{{Spec2('HTML WHATWG')}}Introduzida, baseado no rascunho da especifição de innerText. Ver whatwg/html#465 e whatwg/compat#5 para histórico.
+ +

Compatibilidade de navegadores

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
RecursoChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico4{{ CompatGeckoDesktop(45) }}69.6 (provavelmente antes)3
+
+ +
+ + + + + + + + + + + + + + + + + + + +
RecursoAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico2.3 (provavelmente antes){{ CompatGeckoMobile(45) }}10 (provavelmente antes)124.1 (provavelmente antes)
+
+ +

Ver também

+ + diff --git a/files/pt-br/web/api/htmlelement/input_event/index.html b/files/pt-br/web/api/htmlelement/input_event/index.html new file mode 100644 index 0000000000..dd69baf988 --- /dev/null +++ b/files/pt-br/web/api/htmlelement/input_event/index.html @@ -0,0 +1,248 @@ +--- +title: input +slug: Web/Events/input +translation_of: Web/API/HTMLElement/input_event +--- +

O evento input do DOM é disparado sincronicamente quando o valor de um elemento {{HTMLElement("input")}}, {{HTMLElement("select")}}, ou {{HTMLElement("textarea")}} é alterado. (Para elementos input com type=checkbox ou type=radio, o evento input não é disparado quando o usuário clica no elemento, porque o valor do atributo não é alterado.) Além disso, o evento é disparado no contenteditable editors quando o seu conteúdo é alterado. Nesse caso, O alvo do evento é o elemento host da edição. Se houver dois ou mais elementos que tenha contenteditable como true, o "host de edição" é o elemento antepassado mais próximo cujo pai não é editável. Similarmente, ele também é disparado no element raiz do designMode editors.

+ +

Informações gerais

+ +
+
Specification
+
HTML5, DOM Level 3 Events
+
Interface
+
{{domxref("Event")}}, {{domxref("InputEvent")}}
+
Bubbles
+
Yes
+
Cancelable
+
No
+
Target
+
Element
+
Default Action
+
The value or the content is modified.
+
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}The event target (the topmost target in the DOM tree).
type {{readonlyInline}}{{domxref("DOMString")}}The type of event.
bubbles {{readonlyInline}}{{jsxref("Boolean")}}Whether the event normally bubbles or not.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}Whether the event is cancellable or not.
+ +

Compatibilidade dos navegadores

+ +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}[1]9[2]{{CompatVersionUnknown}}[3]{{CompatVersionUnknown}}
immediately after compositionupdate{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoDesktop("12")}}{{CompatVersionUnknown}}15{{CompatVersionUnknown}}
on contenteditable element{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoDesktop("14")}}{{CompatNo}}[4] +

 

+ 		15{{CompatVersionUnknown}}
when designMode is "on"{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatGeckoDesktop("14")}}{{CompatNo}}15{{CompatVersionUnknown}}
data{{CompatUnknown}}{{CompatUnknown}}{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
isComposing{{CompatNo}}{{CompatUnknown}}{{CompatGeckoDesktop("31")}}{{CompatNo}}{{CompatNo}}{{CompatNo}}
<select>{{CompatVersionUnknown}}{{CompatNo}}{{CompatGeckoDesktop("49")}}{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatVersionUnknown}}
immediately after compositionupdate{{CompatUnknown}}{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatGeckoMobile("12")}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
on contenteditable element{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatGeckoMobile("14")}}{{CompatUnknown}}{{CompatUnknown}}{{CompatVersionUnknown}}
when designMode is "on"{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatGeckoMobile("14")}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
data{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
isComposing{{CompatNo}}{{CompatNo}}{{CompatUnknown}}{{CompatGeckoMobile("31")}}{{CompatNo}}{{CompatNo}}{{CompatNo}}
<select>{{CompatUnknown}}{{CompatVersionUnknown}}{{CompatUnknown}}{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
+
+ +

[1] Prior to Gecko 12.0 {{geckoRelease("12.0")}}, Gecko didn't fire input events while composition was ongoing using IMEs or when dead keys were used on Mac OS X.

+ +

[2] IE 9 does not fire an input event when the user deletes characters from an input (e.g. by pressing Backspace or Delete, or using the "Cut" operation).

+ +

[3] Prior to Opera 15, Opera did not fire an input event after dropping text in an input field.

+ +

[4] The event target is the innermost element at the caret position.

+ +

Veja também

+ + + +

Also the change event is related. change fires less often than input – it only fires when the changes are committed by the user.

diff --git a/files/pt-br/web/api/htmlmediaelement/abort_event/index.html b/files/pt-br/web/api/htmlmediaelement/abort_event/index.html new file mode 100644 index 0000000000..62243a2762 --- /dev/null +++ b/files/pt-br/web/api/htmlmediaelement/abort_event/index.html @@ -0,0 +1,70 @@ +--- +title: abort +slug: Web/Events/abort +translation_of: Web/API/HTMLMediaElement/abort_event +translation_of_original: Web/Events/abort +--- +

O evento abort é disparado quando o carregamento de um recurso foi interrompido.

+ +

Informações Gerais

+ +
+
Especificação
+
DOM L3
+
Interface
+
{{domxref("UIEvent")}} se gerado a partir da interface do usuário, caso contrário será {{domxref("Event")}}.
+
Bubbles
+
Não
+
Cancelável
+
Não
+
Alvo
+
{{domxref("Element")}}
+
Ação Padrão
+
Nenhuma
+
+ +

Propriedades

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropriedadeTipoDescrição
target {{readOnlyInline}}{{domxref("EventTarget")}}O evento alvo (O mais elevado da árvore DOM).
type {{readOnlyInline}}{{domxref("DOMString")}}O tipo de evento.
bubbles {{readOnlyInline}}{{domxref("Boolean")}}O evento é normalmente bubble?
cancelable {{readOnlyInline}}{{domxref("Boolean")}}É possível cancelar o evento?
view {{readOnlyInline}}{{domxref("WindowProxy")}}{{domxref("document.defaultView")}} (window do documento)
detail {{readOnlyInline}}long (float)0.
+
diff --git a/files/pt-br/web/api/htmlorforeignelement/blur/index.html b/files/pt-br/web/api/htmlorforeignelement/blur/index.html new file mode 100644 index 0000000000..25a2273aec --- /dev/null +++ b/files/pt-br/web/api/htmlorforeignelement/blur/index.html @@ -0,0 +1,89 @@ +--- +title: HTMLElement.blur() +slug: Web/API/HTMLElement/blur +tags: + - API + - DOM HTML + - Foco + - HTMLElement + - Referencia + - metodo +translation_of: Web/API/HTMLOrForeignElement/blur +--- +
{{ APIRef("HTML DOM") }}
+ +

O método HTMLElement.blur() remove o foco do teclado no elemento corrente.

+ +

Sintaxe

+ +
elemento.blur();
+ +

Exemplos

+ +

Removendo o foco de um input de texto

+ +

HTML

+ +
<input type="text" id="meuTexto" value="Texto Exemplo">
+<br><br>
+<button type="button" onclick="focusInput()">Clique para definir o foco</button>
+<button type="button" onclick="blurInput()">Clique para remover o foco</button>
+ +

JavaScript

+ +
function focusInput() {
+  document.getElementById('meuTexto').focus();
+}
+function blurInput() {
+  document.getElementById('meuTexto').blur();
+}
+ +

Resultado

+ +

{{ EmbedLiveSample('Remove_focus_from_a_text_input') }}

+ +

Especificação

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'editing.html#dom-blur', 'blur')}}{{Spec2('HTML WHATWG')}} 
{{SpecName('HTML5.1', 'editing.html#blur()-0', 'blur')}}{{Spec2('HTML5.1')}} 
{{SpecName('HTML5 W3C', 'editing.html#dom-blur', 'blur')}}{{Spec2('HTML5 W3C')}} 
{{SpecName('DOM2 HTML', 'html.html#ID-28216144', 'blur')}}{{Spec2('DOM2 HTML')}} 
+ +

Compatibilidade com navegadores

+ + + +

{{Compat("api.HTMLElement.blur")}}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/htmlorforeignelement/dataset/index.html b/files/pt-br/web/api/htmlorforeignelement/dataset/index.html new file mode 100644 index 0000000000..2cb4ba63b0 --- /dev/null +++ b/files/pt-br/web/api/htmlorforeignelement/dataset/index.html @@ -0,0 +1,97 @@ +--- +title: HTMLElement.dataset +slug: Web/API/HTMLElement/dataset +translation_of: Web/API/HTMLOrForeignElement/dataset +--- +

{{ APIRef }}

+ +

A propriedade HTMLElement.dataset permite o acesso, em modo de leitura e escrita, a todos os atributos de dados personalizado (data-*) no elemento. Ele é um mapa de DOMString, com uma entrada para cada atributo de dados personalizado.

+ +

O nome de um atributo de dados customizado inicia com data-. Ele deve conter somente letras, números e os seguintes caracteres: dash (-), dot (.), collon(:), underscore (_). Além disso, ele não deve conter letras ASCII captalizadas (A à Z).

+ +

Um atributo de dados personalizado é transformado em uma chave para uma entrada no {{ domxref("DOMStringMap") }} de acordo com as seguintes regras

+ + + +

A transformação oposta, que mapeia uma chave para um nome de atributo, usa as seguintes regras:

+ + + +

A restrição nas regras acima garantem que as duas trasnformações são inversa uma da outra.

+ +

Por exemplo, o atributo data-abc-def corresponde a chave abcDef.

+ +

Sintaxe

+ +
string = element.dataset.camelCasedName;
+element.dataset.camelCasedName = string;
+ +

Exemplos

+ +
<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe
+</div>
+
+var el = document.querySelector('#user');
+
+// el.id == 'user'
+// el.dataset.id === '1234567890'
+// el.dataset.user === 'johndoe'
+// el.dataset.dateOfBirth === ''
+
+el.dataset.dateOfBirth = '1960-10-03'; // set the DOB.
+
+// 'someDataAttr' in el.dataset === false
+
+el.dataset.someDataAttr = 'mydata';
+// 'someDataAttr' in el.dataset === true
+
+ +

Especificações

+ + + + + + + + + + + + + + + + + + + + + + + + +
EspeficicaçãoStatusComentário
{{SpecName('HTML WHATWG', "dom.html#dom-dataset", "HTMLElement.dataset")}}{{Spec2('HTML WHATWG')}}Sem mudanças desde o último  snapshot, {{SpecName('HTML5.1')}}
{{SpecName('HTML5.1', "dom.html#dom-dataset", "HTMLElement.dataset")}}{{Spec2('HTML5.1')}}Snapshot de {{SpecName('HTML WHATWG')}}, sem mudanças desde {{SpecName('HTML5 W3C')}}
{{SpecName('HTML5 W3C', "dom.html#dom-dataset", "HTMLElement.dataset")}}{{Spec2('HTML5 W3C')}}Snapshot de {{SpecName('HTML WHATWG')}}, definição inicial.
+ +

Compatibilidade com Browsers

+ + + +

{{Compat("api.HTMLElement.dataset")}}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/htmlorforeignelement/focus/index.html b/files/pt-br/web/api/htmlorforeignelement/focus/index.html new file mode 100644 index 0000000000..8f798b3d86 --- /dev/null +++ b/files/pt-br/web/api/htmlorforeignelement/focus/index.html @@ -0,0 +1,62 @@ +--- +title: HTMLElement.focus() +slug: Web/API/HTMLElement/focus +translation_of: Web/API/HTMLOrForeignElement/focus +--- +
{{ APIRef("HTML DOM") }}
+ +

O método HTMLElement.focus()  seta o foco em um determinado elemento em especifico, caso esse elemento permita ter o foco neste elemento.

+ +

Síntaxe

+ +
element.focus()
+ +

Especificação

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'editing.html#dom-focus', 'focus')}}{{Spec2('HTML WHATWG')}} 
{{SpecName('HTML5.1', 'editing.html#focus()-0', 'focus')}}{{Spec2('HTML5.1')}} 
{{SpecName('HTML5 W3C', 'editing.html#dom-focus', 'focus')}}{{Spec2('HTML5 W3C')}} 
{{SpecName('DOM2 HTML', 'html.html#ID-32130014', 'focus')}}{{Spec2('DOM2 HTML')}} 
{{SpecName('DOM1', 'level-one-html.html#method-focus', 'focus')}}{{Spec2('DOM1')}} 
+ +

Notas

+ +

Caso você utilize o HTMLElement.focus() por meio da manipulação de um evento mousedown , você deve utilizar o evento event.preventDefault() a fim de o foco não sair do arquivo HTMLElement.

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/indexeddb_api/usando_indexeddb/index.html b/files/pt-br/web/api/indexeddb_api/usando_indexeddb/index.html deleted file mode 100644 index da14879b31..0000000000 --- a/files/pt-br/web/api/indexeddb_api/usando_indexeddb/index.html +++ /dev/null @@ -1,1281 +0,0 @@ ---- -title: Usando IndexedDB -slug: Web/API/IndexedDB_API/Usando_IndexedDB -tags: - - API IndexedDB Tutorial Avançado -translation_of: Web/API/IndexedDB_API/Using_IndexedDB ---- -
-

IndexedDB é uma forma de armazenar dados no navegador do usuário. Com ele você pode criar aplicações web com possibilidade de fazer query sem necessidade de conexão, suas aplicações podem funcionar tanto online quanto offline. 

-
- -

Sobre esse documento

- -

Esse tutorial utiliza a API assíncrona do IndexedDB. Se você não está familiarizado com IndexedDB, você pode ler Conceitos básicos sobre IndexedDB.

- -

Para a documentação de referência, veja o artigo sobre API IndexedDB, pois nele contém os tipos de objetos utilizados no IndexedDB,  como também métodos da API, tanto síncrona como assíncrona. 

- -

Padrão básico

- -

O IndexedDB encoraja o uso do seguinte padrão:

- -
    -
  1. Abrir um banco de dados.
    2. -
  2. Criar um ObjectStore ao atualizar o banco. 
    3. -
  3. Iniciar uma transação e e faz um request para fazer alguma operação no banco, como adicionar ou obter dados.
    4. -
  4. -
    Esperar a operação ser completada ouvindo algum evento DOM.
    -
    5. -
  5. -
    Fazer algo com o resultado da query (que pode ser obtida pelo objeto request).
    -
    6. -
- -

OK, então, agora com esses conceitos em mente, nós podemos fazer coisas mais concretas.

- -

Criando e estruturando o banco

- -

Pelo fato  da especificação ainda estar evoluindo, as implementações do IndexedDB tem prefixos de navegadores. Os navegadores podem ter implementações diferentes da API IndexedDB até a especificação ser consolidada. Mas uma vez que tudo chegar a um consenso, os navegadores tirarão seus prefixos. Atualmente, algumas implementações removeram o prefixo: Internet Explorer 10, Firefox 16, Chrome 24. Quando eles usam prefixo, navegadores baseados no Gecko usam o prefixo moz, enquanto os navegadores baseados no WebKit usam o prefixo webkit.

- -

Usando uma versão experimental do IndexedDB

- -

Se você quiser testar seu código em navegadores que usam prefixo, você pode usar o código abaixo:  

- -
// Na linha abaixo, você deve incluir os prefixos do navegador que você vai testar.
-window.indexedDB = window.indexedDB || window.mozIndexedDB || window.webkitIndexedDB || window.msIndexedDB;
-// Não use "var indexedDB = ..." se você não está numa function.
-// Posteriormente, você pode precisar de referências de algum objeto window.IDB*:
-window.IDBTransaction = window.IDBTransaction || window.webkitIDBTransaction || window.msIDBTransaction;
-window.IDBKeyRange = window.IDBKeyRange || window.webkitIDBKeyRange || window.msIDBKeyRange;
-// (Mozilla nunca usou prefixo nesses objetos, então não precisamos window.mozIDB*)
- -

Tome cuidado, implementações prefixadas podem estar com bugs ou implementando especificações antigas. Portanto, não é recomendado usar em produção. É preferível não usar IndexedDB em navegadores antigos:

- -
if (!window.indexedDB) {
-    window.alert("Seu navegador não suporta uma versão estável do IndexedDB. Alguns recursos não estarão disponíveis.");
-}
-
- -

Abrindo um banco

- -

Começamos todo o processo assim:

- -
// Abrindo o banco de dados
-var request = window.indexedDB.open("DBteste", 3);
-
- -

Abrir um banco é como qualquer outra operação — Você tem que "requerer (request)".

- -

A requisição de abertura não abre o banco ou inicia a transação. A chamada da função open() retorna um objeto IDBOpenDBRequest com o resultado (success) ou um erro que você terá que tratar. Muitas outras funções assíncronas no IndexedDB fazem a mesma coisa - retornam um objeto IDBRequest com o resultado ou erro. O resultado para a função open é uma instância de IDBDatabase.

- -

O segundo parâmetro para o método open é a versão do banco. A versão do banco determina seu schema — os registros no banco e sua estrutura. Se o banco não existe ainda, ele é criado pela operação open, então o evento onupgradeneeded é chamado e você cria o schema do banco nesse evento. Se o banco existe mas você está fornecendo um novo número de versão, o evento onupgradeneeded é chamado imediatamente, permitindo você tratar a atualização do schema. Para mais informações sobre isso veja Updating the version of the database.

- -
-

O número de versão é um unsigned long long, o que significa que ele pode ver um inteiro muito grande. Isso também significa que você não pode usar float, pois ele será convertido em um inteiro pequeno e a transação pode não acontecer, ou o evento upgradeneeded pode não ser chamado. Então se você usar 2.4 como versão:

- -
var request = indexedDB.open("DBteste", 2.4); // não faça isso, pois a versão será convertida para 2.
-
- -

Gerenciando handlers

- -

A primeira coisa que você vai querer fazer em quase todos os requests é tratar os casos de success e error:

- -
request.onerror = function(event) {
-  // Fazer algo com request.errorCode!
-};
-request.onsuccess = function(event) {
-  // Fazer algo com request.result!
-};
- -

Qual das duas funções, onsuccess() ou onerror(),  será chamada? Se tudo correr bem, o evento de sucesso (que é um evento DOM event com propriedade type setada "success") é chamado com request como seu target. Uma vez chamado, a função onsuccess() no request é chamada com o evento de sucesso em seu contexto. Por outro lado, se acontecer algum problema, um evento de erro (que é um evento DOM com a propriedade type setada para "error") é chamado no request. Então a função onerror()  com o evento erro em seu contexto.

- -

A API IndexedDB é feita para minimizar a necessidade de manipular erros, então você não fará muitos eventos de erro (ao menos, se você usar a API!) No  caso de abrir um banco, portanto, existe algumas condições comuns para eventos de erro. O problema mais comum é o usuário não dar permissão para criar o banco. Um dos principais objetivos do IndexedDB é permitir muitos dados serem armazenados para uso offline. (Para aprender mais sobre o quanto cada navegador pode armazenar, veja Storage limits).  

- -

Obviamente, navegadores não querem armazenar dados que poluem seu computador, então o navegador mostra uma mensagem ao usuário na primeira vez que um aplicativo tenta abrir o IndexedDB. O usuário pode escolher permitir ou negar acesso. O IndexedDB também é desabilitado no modo privado dos navegadores (ctrl+shift+N no Chrome e ctrl+shift+P no Firefox). Isso acontece porque o intuito do modo privado é não deixar rastros na navegação.

- -

Agora, assumindo que o usuário aprovou seu request para criar o banco, e você recebeu success; Qual é o próximo passo? O request foi gerado com a chamada de indexedDB.open(), e request.result é uma instância de IDBDatabase, e você definitivamente vai querer armazenar isso para usar depois. Veja abaixo:

- -
var db;
-var request = indexedDB.open("DBteste");
-request.onerror = function(event) {
-  alert("Você não habilitou minha web app para usar IndexedDB?!");
-};
-request.onsuccess = function(event) {
-  db = request.result;
-};
-
- -

Tratando Erros

- -

Como mencionado acima, o evento de erro é chamado quando o request dá erro. Se você quer evitar manipuladores de erro a cada request, você pode adicionar um único manipulador de erro no objeto db, como abaixo:

- -
db.onerror = function(event) {
-  // Função genérica para tratar os erros de todos os requests desse banco!
-  alert("Database error: " + event.target.errorCode);
-};
-
- -

Um dos erros mais comuns ao abrir o banco é VER_ERR. Ele indica que a versão do banco existente é maior que a versão que você quer abrir.

- -

Criando ou atualizando a versão do banco

- -

Quando você cria um novo banco ou aumenta sua versão, o evento onupgradeneeded será chamado. No manipulador deste evento, você deve criar o objectStore necessário para a versão do banco:

- -
// Este evento é implementado somente em navegadores mais recentes
-request.onupgradeneeded = function(event) {
-  var db = event.target.result;
-
-  // cria um objectStore para esse banco
-  var objectStore = db.createObjectStore("nome", { keyPath: "minhaChave" });
-};
- -

Neste caso, o banco já terá objectStores de suas versões anteriores, então você não terá que criar esses objectStores de novo. Você somente precisará criar um novo objectStore qualquer, ou deletar objectStores da versão anterior que não serão utilizados. Se você precisa mudar um objectStore existente (mudar o keyPath, por exemplo),  então você precisa deletar o objectStore antigo e criá-lo novamente com as novas opções. (Note que isso irá deletar a informação no objectStore! Se você precisa salvar a informação, você deve ler isso e salvá-lo em algum lugar antes de atualizar o banco.)

- -

Blink/Webkit suporta a versão atual da especificação, nas versões do Chrome 23+ e Opera 17+; IE10+ também suporta. Outros motores e versões antigas não implementam a versão atual da especificação e não suportam a assinatura indexedDB.open(name, version).onupgradeneeded ainda.  Para mais informação sobre como atualizar a versão do banco em Webkit/Blink, veja IDBDatabase reference article.

- -

Estruturando o banco

- -

Agora a estrutura do banco. IndexedDB usa "armazens de objetos" em vez de tabelas, e um único banco de dados pode conter qualquer número de "armazem de objetos". Sempre que um valor é armazenado num objectStore, ele é associado a uma chave. Existe várias maneiras diferentes de uma chave ser mostrada, dependendo do que o objectStore usa, um key path ou key generator.

- -

A tabela abaixo mostra as direfentes chaves suportadas:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Key Path (keyPath)Key Generator (autoIncrement)Description
NãoNãoEste objectStore pode ter qualquer tipo de valor primitivo como número ou string. Você deve suprir uma chave separada sempre que adicionar um novo valor.
SimNãoEste objectStore pode simplesmente armazenar objetos JavaScript. O objeto deve ter uma propriedade com o mesmo nome do key path.
NãoSimEste objectStore pode possuir qualquer tipo de valor. A chave é gerada para você, automaticamente, ou você pode suprir uma chave separada, caso utilize uma chave específica.
SimSimEste objectStore suporta somente objetos JavaScript. Normalmente uma chave é gerada e o valor dela é armazenado no objeto em uma propriedade com o mesmo nome da key path. Portanto, se a propriedade já existe, o valor dela será usado como chave, em vez do valor gerado.
- -

Você também pode criar índices em qualquer objectStore. Um indice deixa você olhar os valores armazenados no objectStore usando o valor de uma propriedade do objectStore, em vez de sua chave.

- -

Adicionalmente, indices tem a habilidade de forçar restrições simples nos dados armazenados. Setando uma flag única quando criar o índice, reforça que dois objetos são armazenados contendo o mesmo valor para o key path do índice. Então, por exemplo, se você tem um objeto armazenado que tem um conjunto de pessoas, e você quer ter certeza que ninguém tera o mesmo e-mail, você pode usar um índice com flag única para forçar isso.

- -

Isso soa meio confuso, mas este exemplo pode iluminar o conceito. Primeiro, vamos definir alguns dados a serem usados no exemplo:

- -
// Isso é o que os dados de nossos clientes será.
-const DadosClientes = [
-  { ssn: "444-44-4444", nome: "Bill", idade: 35, email: "bill@company.com" },
-  { ssn: "555-55-5555", nome: "Donna", idade: 32, email: "donna@home.org" }
-];
-
- -

Agora  vamos ver  ccomo criar um IndexedDB para armazenar nossos dados:

- -
const dbName = "clientes";
-
-var request = indexedDB.open(dbName, 2);
-
-request.onerror = function(event) {
-  // Tratar erros.
-};
-request.onupgradeneeded = function(event) {
-  var db = event.target.result;
-
-  // Cria um objectStore para conter a informação sobre nossos clientes. Nós vamos
-  // usar "ssn" como key path porque sabemos que é único;
-  var objectStore = db.createObjectStore("clientes", { keyPath: "ssn" });
-
-  // Cria um índice para buscar clientes pelo nome. Podemos ter nomes
-  // duplicados, então não podemos usar como índice único.
-  objectStore.createIndex("nome", "nome", { unique: false });
-
-  // Cria um índice para buscar clientes por email. Queremos ter certeza
-  // que não teremos 2 clientes com o mesmo e-mail;
-  objectStore.createIndex("email", "email", { unique: true });
-
-  // Usando transação oncomplete para afirmar que a criação do objectStore
-  // é terminada antes de adicionar algum dado nele.
-  objectStore.transaction.oncomplete = function(event) {
-    // Armazenando valores no novo objectStore.
-    var clientesObjectStore = db.transaction("clientes", "readwrite").objectStore("clientes");
-    for (var i in DadosClientes) {
-      clientesObjectStore.add(DadosClientes[i]);
-    }
-  }
-};
-
- -

Como falamos antes, onupgradeneeded é o único lugar onde você pode alterar a estrutura do banco. Nele você pode criar e deletar objectStores e construir ou remover índices.

- -
Armazens de objetos são criados com uma única chamada de createObjectStore(). O método pega o nome do armazem e um objeto parâmetro. Mesmo que o objeto parâmetro seja opcional, ele é muito importante porque ele deixa você definir propriedades importantes e ajustar tipos de dados que você quer criar. No nosso caso, nós obtemos um objectStore chamado "clientes" e definimos um keyPath, que é a propriedade que faz um objeto individual ser único no banco. Essa propriedade, nesse exemplo, é "ssn", que simboliza o cpf (social security number), que é único. O "ssn" deve ser apresentado em cada objeto armazenado no objectStore. 
- -

Nós também criamos um índice chamado "nome" ligado à propriedade nome. Assim como o createObjectStore(), o createIndex() tem um parâmetro opcional options que cuida do tipo de índice que você quer criar. Adicionando objetos que não tem a propriedade nome terá sucesso, porém esses objetos não aparecerão no índice "nome".

- -

Nós podemos obter os objetos de clientes armazenados usando os ssn da objectStore diretamente, ou usando os nomes usados no índice. Para aprender como isso é feito, veja a seção usando um índice.

- -

Usando um key generator

- -

Setando uma flag autoIncrement ao criar o objectStore habilitará o key generator. Por padrão ele não é setado.

- -

Com o key generator, a chave será gerada automaticamente quando você adicionar algum valor no objectStore. O atual número do key generator é sempre setado 1 quando a primeira key generator do objectStore é criada. Basicamente a próxima chave recebe o incremento de 1. O número atual da key generator nunca decresce,  a não ser se alguma operação do banco for revertida, como numa transação abortada, por exemplo. No entanto, deletar um registro ou limpar todos os registros nunca afeta o key generator dos objectStores.

- -

Nós podemos criar outro objectStore com o key generator como abaixo:

- -
// Abrindo o indexedDB.
-var request = indexedDB.open(dbName, 3);
-
-request.onupgradeneeded = function (event) {
-
-    var db = event.target.result;
-
-    // Criando outro objeto chamado "names" com o autoIncrement setado.
-    var objStore = db.createObjectStore("names", { autoIncrement : true });
-
-    // Porque "names" tem o the key generator, a chave para o nome é gerada automaticamente.
-    // Os registros adicionados serão assim:
-    // key : 1 => value : "Bill"
-    // key : 2 => value : "Donna"
-    for (var i in DadosClientes) {
-        objStore.add(DadosClientes[i].nome);
-    }
-}
- -

Para mais detalhes veja "W3C Key Generators".

- -

Adicionando, obtendo e removendo dados

- -

Antes de fazer qualquer coisa em um novo banco, você precisa iniciar uma transação. Transações estão no objeto database, e você tem que especificar qual objectStore você quer na transaction. Uma vez que você está dentro da transação, você pode acessar os objectStores  com seus dados e fazer os requests. Depois, você precisa decidir se você vai fazer mudanças no banco ou se você simplesmente quer ler esses dados. Transações tem três modos disponíveis: readonly, readwrite, and versionchange.

- -

Para mudar o "schema" ou estrutura do banco — o que envolve criar ou deletar objectStores ou índices — a transação deve ser em modo versionchange. Esta transação é aberta chamando o método {{domxref("IDBFactory.open")}} especificando a  version. (Em navegadores com WebKit que não tem a ultima especificação implementada, o método {{domxref("IDBFactory.open")}} tem apenas um parâmetro, o nome do banco; então você deve chamar {{domxref("IDBVersionChangeRequest.setVersion")}} para estabelecer uma transação versionchange.)

- -

Para ler os registros de um objectStore existente, a transação pode ser tanto readonly quanto readwrite. Para fazer mudanças em um objectStore existente, a transação deve ser em modo readwrite. Você abre essas transações usando {{domxref("IDBDatabase.transaction")}}. O método aceita dois parâmetros: o storeNames (o escopo, definido como um array de objectStores que você quer acessar) e o modo (readonly or readwrite) da transação. O método retorna o objeto detransação contendo o método {{domxref("IDBIndex.objectStore")}}, que você pode usar para acessar seu objectStore. Por padrão, quando nenhum modo é especificado, a transação é aberta no modo readonly.

- -

Você pode deixar o acesso aos dados mais rápido usando o escopo correto e o modo correto de transação. Aqui vai algumas dicas:

- - - -

Adicionando dados no banco

- -

Se você acabou de criar o banco, então você provavelmente quer escrever algo nele. Veja abaixo:

- -
var transaction = db.transaction(["clientes"], "readwrite");
-// Nota: Implementações mais antigas usam uma versão IDBTransaction.READ_WRITE antiga em vez de "readwrite".
-// Então, para suportar versões antigas, escreva:
-// var transaction = db.transaction(["clientes"], IDBTransaction.READ_WRITE);
- -

A função transaction() tem dois argumentos (opcionais) e retorna um objeto de transação. O primeiro argumento é uma lista de objectStores que serão trabalhados na transação. Você pode passar um array vazio se você quer uma transação com todos os objectStores, mas não faça isso pois a especificação diz que um array vazio pode gerar um erro InvalidAccessError. Se você não especificar nada no segundo parâmetro, você tem uma transação read-only. Se você quer escrever no banco, use "readwrite".

- -

Agora que você tem uma transação, você precisa entender seu tempo de uso. Transações são amarradas a um evento. Se você faz uma transação fora de um evento, ela ficará inativa. A única maneira de manter uma transação ativa é fazer um request nela. Quando o request acabar você terá a oportunidade de extender a transação durante o callback. Se você tentar extender uma transação dentro de um evento, então ela tornará inativa. Se existir requests pendentes, a transação continua ativa. O tempo de vida de uma transação é realmente simples mas deve ser usada em um curto espaço de tempo. Outros exemplos poderão ajudá-lo. Se você começar a ver TRANSACTION_INACTIVE_ERR error então você está fazendo algo errado.

- -

Transações podem receber eventos DOM de três tipos diferentes: error, abort, e complete. Nós falamos sobre o error, ou seja, a transação recebe um error sempre que o request gerar erro. Um ponto mais sutil é que o comportamento padrão de um erro é abortar a transação na qual ele estava. A menos que você manipule o erro chamando preventDefault() e fazendo algo depois, a transaçaõ inteira será desfeita. Este design força você a pensar sobre manipulação de erros, mas você pode sempre adicionar um manipulador de todos os erros se a manipulação separada estiver complicada. Se você não tratar o erro ou chamar abort() na transação, então a transação é desfeita (roll back) e o evento abort é chamado. Por outro lado, depois de todo request completado, você tem um evento complete. Se você fazer várias operações no banco, então seguir as operações de transações pode ser um caminho a seguir.

- -

Agora que você tem uma transação, você precisará obter um objectStore dela. Transações somente deixam você obter um objectStore citado na transação. Então você pode adicionar os dados que precisa.

- -
// Faz algo após a inserção dos dados.
-transaction.oncomplete = function(event) {
-  alert("Pronto!");
-};
-
-transaction.onerror = function(event) {
-  // Não esquecer de tratar os erros!
-};
-
-var objectStore = transaction.objectStore("clientes");
-for (var i in DadosClientes) {
-  var request = objectStore.add(DadosClientes[i]);
-  request.onsuccess = function(event) {
-    // event.target.result == DadosClientes[i].ssn;
-  };
-}
- -

O result de um request gerado de uma chamada de add() é a chave do valor  que foi adicionado. Então neste caso, ele deve ser igual ao valor do ssn do objeto que foi adicionado, desde que o objeto use o ssn como key path. Note que a função add() não deixa nenhum objeto ser adicionado com a mesma chave. Se você está tentando modificar um registro existente, você deve usar o put(), como explica a seção  {{ anch("Updating an entry in the database") }}.

- -

Removendo dados do banco

- -

Para remoção o código é parecido:

- -
var request = db.transaction(["clientes"], "readwrite")
-                .objectStore("clientes")
-                .delete("444-44-4444");
-request.onsuccess = function(event) {
-  // Pronto!
-};
- -

Obtendo dados do banco

- -

Agora que o banco tem algumas informações nele, você pode obtê-las de diferentes maneiras. Primeiro, um get() simples. Você precisa informar a chave do valor a ser obtido:

- -
var transaction = db.transaction(["clientes"]);
-var objectStore = transaction.objectStore("clientes");
-var request = objectStore.get("444-44-4444");
-request.onerror = function(event) {
-  // Tratar erro!
-};
-request.onsuccess = function(event) {
-  // Fazer algo com request.result!
-  alert("O nome do SSN 444-44-4444 é " + request.result.name);
-};
- -

Veja agora de maneira resumida:

- -
db.transaction("clientes").objectStore("clientes").get("444-44-4444").onsuccess = function(event) {
-  alert("O nome do SSN 444-44-4444 é " + request.result.name);
-};
- -

Viu como funciona? Desde que exista um objectStore, você pode evitar passar uma lista de objectStores que precisa na transação e passar apenas o nome como string. Você também pode ler do banco, apenas, então não precisará de uma transação "readwrite". Chamando transaction() com nenhum modo especificado, você terá uma transação "readonly". Outra consideração é que você não necessita salvar o request em uma variável. Desde que o evento DOM tenha o target que você precisará para obter a propriedade result.

- -
-

Note: Você pode deixar o acesso aos dados mais rápido limitando o escopo e o modo de transação. Veja algumas dicas:

- - -
- -

Atualizando um registro no banco

- -

Agora que obtemos algum dado, atualizá-ls é inserí-los novamente no IndexedDB é bem simples. Vamos atualizar o exemplo anterior:

- -
var objectStore = db.transaction(["clientes"], "readwrite").objectStore("clientes");
-var request = objectStore.get("444-44-4444");
-request.onerror = function(event) {
-  // Tratar erro
-};
-request.onsuccess = function(event) {
-  // Obter os valores antigos
-  var data = request.result;
-
-  // atualizar algum dado
-  data.age = 42;
-
-  // Atulizar esse dado no banco
-  var requestUpdate = objectStore.put(data);
-   requestUpdate.onerror = function(event) {
-     // Tratar erro
-   };
-   requestUpdate.onsuccess = function(event) {
-     // Sucesso na atualização \o/
-   };
-};
- -

Criamos uma objectStore e obtemos um cliente dele, identificado pelo ssn (444-44-4444). Nós atualizamos o objeto, passando-o como parâmetro de um método put de outro request (requestUpdate) sobrescrevendo o valor antigo.

- -
-

Note que neste caso nós temos que especificar a transação readwrite porque nós queremos escrever no banco, não somente ler os dados dele.

-
- -

Usando um cursor

- -

Ao usar o método get() você precisa saber a chave do objeto que deseja obter. Se você quer passear entre todos os valores do seu objectStore, então você pode usar um cursor. Veja:

- -
var objectStore = db.transaction("cliente").objectStore("cliente");
-
-objectStore.openCursor().onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    alert("O nome do SSN " + cursor.key + " é " + cursor.value.name);
-    cursor.continue();
-  }
-  else {
-    alert("Não existe mais registros!");
-  }
-};
- -

A função openCursor() tem vários argumentos. Primeiro, você pode limitar o número de itens obtidos usando uma chave que veremos logo abaixo. Segundo, você pode especificar a direção que deseja iterar. No exemplo acima, nós estamos iterando em todos os objetos em ordem ascendente. O callback de sucesso para cursor é um pouco especial. O objeto cursor já é o result do request (acima nós usamos event.target.result). Então a chave atual e o valor pode ser encontrado na propriedade key e value do objeto cursor. Se você quer manter adiante, então você usa o método continue(). Quando você chegar ao fim dos dados (ou se não existem registros encontrados no openCursor()) você ainda tem um callback de sucesso, mas a propriedade result fica undefined.

- -

Um padrão comum para cursores é obter todos os objetos em um objectStore e adicioná-los a um array como este:

- -
var clientes = [];
-
-objectStore.openCursor().onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    clientes.push(cursor.value);
-    cursor.continue();
-  }
-  else {
-    alert("Todos os clientes: " + clientes);
-  }
-};
- -
-

Note: Mozilla também implementou o método getAll() para ser usado nesse caso (e getAllKeys(), que está atualmente dentro da preferência do dom.indexedDB.experimental em about:config). Estes métodos não são parte do padrão IndexedDB, então eles podem desaparecer no futuro. Nós adicionamos porque achamos útil. O código abaixo faz o mesmo que o código acima:

- -
objectStore.getAll().onsuccess = function(event) {
-  alert("Todos os clientes: " + event.target.result);
-};
- -

Existe um custo de performance associado com a propriedade value do cursor, porque o objeto é criado de forma lenta. Quando você usa getAll() por exemplo, Gecko deve criar todos os objetos de uma vez. Se você está somente interessado em cada chave, é muito melhor usar o cursor do que usar o getAll(). Se você está tentando obter um array de todos os objetos, então é melhor usar o getAll().

-
- -

Usando um índice

- -

Armazenar dados de um cliente usando o SSN como chave é lógico pois o SSN identifica o cliente de forma única. Se você precisa obter um cliente pelo seu nome, portanto, você precisará iterar todos os registros no banco e comparar os nomes até achar o que você procura. Buscar dessa maneira é algo lento, então criamos um índice.

- -
var index = objectStore.index("nome");
-index.get("John").onsuccess = function(event) {
-  alert("O SSN de John é " + event.target.result.ssn);
-};
- -

O cursor "nome" não é único, então pode existir mais de um registro com o nome igual a "John". Neste caso você sempre obtem o registro com a chave de menor valor.

- -

Se você precisa acessar todos os registros retornados, você pode usar um cursor. Você pode abrir dois tipos de cursores. Um cursor normal mapeia o índice ao objeto na objectStore. Uma cursor-chave mapeia o a propriedade índice à chave usada para armazenar o objeto. As diferenças são ilustradas abaixo:

- -
// Usando um cursor normal para obter todos os objetos
-index.openCursor().onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    // cursor.key é um nome, como "Bill", e cursor.value é o objeto inteiro.
-    alert("Nome: " + cursor.key + ", SSN: " + cursor.value.ssn + ", email: " + cursor.value.email);
-    cursor.continue();
-  }
-};
-
-// Usando um cursor-chave para obter todos os objetos
-index.openKeyCursor().onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    // cursor.key é o nome, como "Bill", e cursor.value é o SSN (chave).
-    // Não tem como obter o resto do objeto
-    alert("Nome: " + cursor.key + ", SSN: " + cursor.value);
-    cursor.continue();
-  }
-};
- -

Especificando o número e a direção dos cursores

- -

Se você gostaria de limitar o número de valores retornados pelo cursor, você pode usar um objeto IDBKeyRange e passar isso como o primeiro argumento ao openCursor() ou openKeyCursor(). Você pode fazer um key range que permite um único valor, ou valores acima ou abaixo do especificado. O limite pode ser fechado (o key range inclui os valores dados) ou aberto (o key range não inclue os valores dados). Veja como funciona:

- -
// Somente se for igual "Donna"
-var singleKeyRange = IDBKeyRange.only("Donna");
-
-// Combinações menores que "Bill", incluindo "Bill"
-var lowerBoundKeyRange = IDBKeyRange.lowerBound("Bill");
-
-// Combinações menores que "Bill", sem incluir "Bill"
-var lowerBoundOpenKeyRange = IDBKeyRange.lowerBound("Bill", true);
-
-// Combinações maiores que Donna, não incluindo "Donna"
-var upperBoundOpenKeyRange = IDBKeyRange.upperBound("Donna", true);
-
-// Combinações entre "Bill" e "Donna", sem incluir "Donna"
-var boundKeyRange = IDBKeyRange.bound("Bill", "Donna", false, true);
-
-// Para usar qualquer um desses key ranges, basta passar como primeiro parâmetro de openCursor()/openKeyCursor()
-index.openCursor(boundKeyRange).onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    // Faz algo com o que encontrar
-    cursor.continue();
-  }
-};
- -

As vezes você pode querer iterar em ordem decrescente, em vez de crescente, alterando o segundo parâmetro de openCursor():

- -
objectStore.openCursor(boundKeyRange, "prev").onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    // Prev indica ordem decrescente
-    cursor.continue();
-  }
-};
- -

Se você apenas quer especificar a ordem sem key range, é só passar null no primeiro parâmetro:

- -
objectStore.openCursor(null, "prev").onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    // Faça algo com os resultados.
-    cursor.continue();
-  }
-};
- -

Uma vez que o índice "nome" não é único, pode existir várias entradas onde o nome é o mesmo. Isso não acontece com objectStores porque a chave deve ser sempre única. Se você deseja filtrar valores duplicados numa iteração do cursor, você pode passar nextunique (ou prevunique se quiser decrescer) como parâmetro de direção. Quando nextunique ou prevunique é usado, o registro com menor chave é retornado.

- -
index.openKeyCursor(null, "nextunique").onsuccess = function(event) {
-  var cursor = event.target.result;
-  if (cursor) {
-    // Faça algo com os registros.
-    cursor.continue();
-  }
-};
- -

Veja "IDBCursor Constants" para parâmetros válidos.

- -

Mudança de versão quando a web app está aberta em outra aba.

- -

Quando sua web app muda a versão você precisa considerar o que vai acontecer se o usuário está na versão antiga em uma aba, e carrega a versão nova na outra. Quando você chamar o open() com a versão mais nova, um evento onblocked  é chamado até que a aba da versão antiga seja fechada ou recarregada. Veja abaixo:

- -
var openReq = mozIndexedDB.open("DBteste", 2);
-
-openReq.onblocked = function(event) {
-  // Se existe outra aba com a versão antiga
-  alert("Existe uma versão antiga da web app aberta em outra aba, feche-a por favor!");
-};
-
-openReq.onupgradeneeded = function(event) {
-  // Se estiver tudo fechado, então faça as devidas alterações
-  db.createObjectStore(/* ... */);
-  useDatabase(db);
-}
-
-openReq.onsuccess = function(event) {
-  var db = event.target.result;
-  useDatabase(db);
-  return;
-}
-
-function useDatabase(db) {
-  // Esteja certo de que adicionou um evento para notificar se a página muda a versão
-  // Nós devemos fechar o banco. Isso permite à outra página ser atualizada
-  // Se você não fizer isso a atualização não acontecerá até fechar as abas.
-  db.onversionchange = function(event) {
-    db.close();
-    alert("Uma nova versão desta web app está pronta. Atualiza, por favor!");
-  };
-
-  // Fazer algo com os bancos
-}
-
- -

Segurança

- -

IndexedDB usa o princípio de mesma origem, o que significa que o banco só será acessado pelo site que o criou.

- -

É importante notar que o IndexedDB não funciona para conteúdo carregado em um frame de outro site (seja {{ HTMLElement("frame") }} ou {{ HTMLElement("iframe") }}. Esta é uma política de segurança e privacidade análoga ao bloqueio de cookies de terceiros. Para mais detalhes, veja {{ bug(595307) }}.

- -

Alerta sobre fechar o navegador

- -

Quando o navegador é fechado, qualquer transação pendente no IndexedDB será abortada (silenciosamente) — ele não vai completar, nem chamar o evento de erro.  Uma vez que o usuário pode sair do navegador, em qualquer momento, isto significa que você não pode confiar em qualquer transação específica para completar ou para saber que ela não foi concluída. Existem várias implicações nesse comportamento.

- -

Primeiro, você deve ter o cuidado de sempre deixar seu banco de dados em um estado consistente, no final de cada transação. Por exemplo, suponha que você está usando IndexedDB para armazenar uma lista de itens que permitem ao usuário editar. Você salvar a lista após a edição, limpando o armazenamento de objetos e, em seguida, escrever a nova lista. Se você limpar o armazenamento de objetos em uma transação e escrever a nova lista em outra transação, há um perigo de que o navegador irá fechar após a limpeza de dados e antes da gravação, deixando-o com um banco de dados vazio. Para evitar isso, você deve combinar tanto a limpeza quanto a gravação em uma única transação.

- -

Em segundo lugar, você nunca deve amarrar as operações de banco de dados ao evento unload. Se o evento unload é acionado pelo fechamento do navegador, todas as transações criadas no unload nunca serão concluídas. Uma abordagem intuitiva para manter algumas informações em sessões do navegador é lê-la a partir do banco de dados quando o navegador (ou uma determinada página) é aberta, atualizá-la assim que o usuário interagir com o navegador, e depois salvá-lo para o banco de dados quando o navegador (ou página) será fechada. No entanto, isso não vai funcionar. As transações de banco de dados será criado no unload, mas como elas são assíncronas, serão abortadas antes que eles possam executar.

- -

De fato, não existe uma maneira de garantir que as transações no IndexedDBserão completadas, mesmo com o fechamento padrão do navegador. Ver {{ bug(870645) }}.

- -

Exemplo de IndexedDB

- -

HTML

- -
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
-
-    <h1>IndexedDB Demo: storing blobs, e-publication example</h1>
-    <div class="note">
-      <p>
-        Works and tested with:
-      </p>
-      <div id="compat">
-      </div>
-    </div>
-
-    <div id="msg">
-    </div>
-
-    <form id="register-form">
-      <table>
-        <tbody>
-          <tr>
-            <td>
-              <label for="pub-title" class="required">
-                Title:
-              </label>
-            </td>
-            <td>
-              <input type="text" id="pub-title" name="pub-title" />
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <label for="pub-biblioid" class="required">
-                Bibliographic ID:<br/>
-                <span class="note">(ISBN, ISSN, etc.)</span>
-              </label>
-            </td>
-            <td>
-              <input type="text" id="pub-biblioid" name="pub-biblioid"/>
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <label for="pub-year">
-                Year:
-              </label>
-            </td>
-            <td>
-              <input type="number" id="pub-year" name="pub-year" />
-            </td>
-          </tr>
-        </tbody>
-        <tbody>
-          <tr>
-            <td>
-              <label for="pub-file">
-                File image:
-              </label>
-            </td>
-            <td>
-              <input type="file" id="pub-file"/>
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <label for="pub-file-url">
-                Online-file image URL:<br/>
-                <span class="note">(same origin URL)</span>
-              </label>
-            </td>
-            <td>
-              <input type="text" id="pub-file-url" name="pub-file-url"/>
-            </td>
-          </tr>
-        </tbody>
-      </table>
-
-      <div class="button-pane">
-        <input type="button" id="add-button" value="Add Publication" />
-        <input type="reset" id="register-form-reset"/>
-      </div>
-    </form>
-
-    <form id="delete-form">
-      <table>
-        <tbody>
-          <tr>
-            <td>
-              <label for="pub-biblioid-to-delete">
-                Bibliographic ID:<br/>
-                <span class="note">(ISBN, ISSN, etc.)</span>
-              </label>
-            </td>
-            <td>
-              <input type="text" id="pub-biblioid-to-delete"
-                     name="pub-biblioid-to-delete" />
-            </td>
-          </tr>
-          <tr>
-            <td>
-              <label for="key-to-delete">
-                Key:<br/>
-                <span class="note">(for example 1, 2, 3, etc.)</span>
-              </label>
-            </td>
-            <td>
-              <input type="text" id="key-to-delete"
-                     name="key-to-delete" />
-            </td>
-          </tr>
-        </tbody>
-      </table>
-      <div class="button-pane">
-        <input type="button" id="delete-button" value="Delete Publication" />
-        <input type="button" id="clear-store-button"
-               value="Clear the whole store" class="destructive" />
-      </div>
-    </form>
-
-    <form id="search-form">
-      <div class="button-pane">
-        <input type="button" id="search-list-button"
-               value="List database content" />
-      </div>
-    </form>
-
-    <div>
-      <div id="pub-msg">
-      </div>
-      <div id="pub-viewer">
-      </div>
-      <ul id="pub-list">
-      </ul>
-    </div>
-
- -

CSS Content

- -
body {
-  font-size: 0.8em;
-  font-family: Sans-Serif;
-}
-
-form {
-  background-color: #cccccc;
-  border-radius: 0.3em;
-  display: inline-block;
-  margin-bottom: 0.5em;
-  padding: 1em;
-}
-
-table {
-  border-collapse: collapse;
-}
-
-input {
-  padding: 0.3em;
-  border-color: #cccccc;
-  border-radius: 0.3em;
-}
-
-.required:after {
-  content: "*";
-  color: red;
-}
-
-.button-pane {
-  margin-top: 1em;
-}
-
-#pub-viewer {
-  float: right;
-  width: 48%;
-  height: 20em;
-  border: solid #d092ff 0.1em;
-}
-#pub-viewer iframe {
-  width: 100%;
-  height: 100%;
-}
-
-#pub-list {
-  width: 46%;
-  background-color: #eeeeee;
-  border-radius: 0.3em;
-}
-#pub-list li {
-  padding-top: 0.5em;
-  padding-bottom: 0.5em;
-  padding-right: 0.5em;
-}
-
-#msg {
-  margin-bottom: 1em;
-}
-
-.action-success {
-  padding: 0.5em;
-  color: #00d21e;
-  background-color: #eeeeee;
-  border-radius: 0.2em;
-}
-
-.action-failure {
-  padding: 0.5em;
-  color: #ff1408;
-  background-color: #eeeeee;
-  border-radius: 0.2em;
-}
-
-.note {
-  font-size: smaller;
-}
-
-.destructive {
-  background-color: orange;
-}
-.destructive:hover {
-  background-color: #ff8000;
-}
-.destructive:active {
-  background-color: red;
-}
-
- -

 

- -

JavaScript Content

- -
(function () {
-  var COMPAT_ENVS = [
-    ['Firefox', ">= 16.0"],
-    ['Google Chrome',
-     ">= 24.0 (you may need to get Google Chrome Canary), NO Blob storage support"]
-  ];
-  var compat = $('#compat');
-  compat.empty();
-  compat.append('<ul id="compat-list"></ul>');
-  COMPAT_ENVS.forEach(function(val, idx, array) {
-    $('#compat-list').append('<li>' + val[0] + ': ' + val[1] + '</li>');
-  });
-
-  const DB_NAME = 'mdn-demo-indexeddb-epublications';
-  const DB_VERSION = 1; // Use a long long for this value (don't use a float)
-  const DB_STORE_NAME = 'publications';
-
-  var db;
-
-  // Used to keep track of which view is displayed to avoid uselessly reloading it
-  var current_view_pub_key;
-
-  function openDb() {
-    console.log("openDb ...");
-    var req = indexedDB.open(DB_NAME, DB_VERSION);
-    req.onsuccess = function (evt) {
-      // Better use "this" than "req" to get the result to avoid problems with
-      // garbage collection.
-      // db = req.result;
-      db = this.result;
-      console.log("openDb DONE");
-    };
-    req.onerror = function (evt) {
-      console.error("openDb:", evt.target.errorCode);
-    };
-
-    req.onupgradeneeded = function (evt) {
-      console.log("openDb.onupgradeneeded");
-      var store = evt.currentTarget.result.createObjectStore(
-        DB_STORE_NAME, { keyPath: 'id', autoIncrement: true });
-
-      store.createIndex('biblioid', 'biblioid', { unique: true });
-      store.createIndex('title', 'title', { unique: false });
-      store.createIndex('year', 'year', { unique: false });
-    };
-  }
-
-  /**
-   * @param {string} store_name
-   * @param {string} mode either "readonly" or "readwrite"
-   */
-  function getObjectStore(store_name, mode) {
-    var tx = db.transaction(store_name, mode);
-    return tx.objectStore(store_name);
-  }
-
-  function clearObjectStore(store_name) {
-    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
-    var req = store.clear();
-    req.onsuccess = function(evt) {
-      displayActionSuccess("Store cleared");
-      displayPubList(store);
-    };
-    req.onerror = function (evt) {
-      console.error("clearObjectStore:", evt.target.errorCode);
-      displayActionFailure(this.error);
-    };
-  }
-
-  function getBlob(key, store, success_callback) {
-    var req = store.get(key);
-    req.onsuccess = function(evt) {
-      var value = evt.target.result;
-      if (value)
-        success_callback(value.blob);
-    };
-  }
-
-  /**
-   * @param {IDBObjectStore=} store
-   */
-  function displayPubList(store) {
-    console.log("displayPubList");
-
-    if (typeof store == 'undefined')
-      store = getObjectStore(DB_STORE_NAME, 'readonly');
-
-    var pub_msg = $('#pub-msg');
-    pub_msg.empty();
-    var pub_list = $('#pub-list');
-    pub_list.empty();
-    // Resetting the iframe so that it doesn't display previous content
-    newViewerFrame();
-
-    var req;
-    req = store.count();
-    // Requests are executed in the order in which they were made against the
-    // transaction, and their results are returned in the same order.
-    // Thus the count text below will be displayed before the actual pub list
-    // (not that it is algorithmically important in this case).
-    req.onsuccess = function(evt) {
-      pub_msg.append('<p>There are <strong>' + evt.target.result +
-                     '</strong> record(s) in the object store.</p>');
-    };
-    req.onerror = function(evt) {
-      console.error("add error", this.error);
-      displayActionFailure(this.error);
-    };
-
-    var i = 0;
-    req = store.openCursor();
-    req.onsuccess = function(evt) {
-      var cursor = evt.target.result;
-
-      // If the cursor is pointing at something, ask for the data
-      if (cursor) {
-        console.log("displayPubList cursor:", cursor);
-        req = store.get(cursor.key);
-        req.onsuccess = function (evt) {
-          var value = evt.target.result;
-          var list_item = $('<li>' +
-                            '[' + cursor.key + '] ' +
-                            '(biblioid: ' + value.biblioid + ') ' +
-                            value.title +
-                            '</li>');
-          if (value.year != null)
-            list_item.append(' - ' + value.year);
-
-          if (value.hasOwnProperty('blob') &&
-              typeof value.blob != 'undefined') {
-            var link = $('<a href="' + cursor.key + '">File</a>');
-            link.on('click', function() { return false; });
-            link.on('mouseenter', function(evt) {
-                      setInViewer(evt.target.getAttribute('href')); });
-            list_item.append(' / ');
-            list_item.append(link);
-          } else {
-            list_item.append(" / No attached file");
-          }
-          pub_list.append(list_item);
-        };
-
-        // Move on to the next object in store
-        cursor.continue();
-
-        // This counter serves only to create distinct ids
-        i++;
-      } else {
-        console.log("No more entries");
-      }
-    };
-  }
-
-  function newViewerFrame() {
-    var viewer = $('#pub-viewer');
-    viewer.empty();
-    var iframe = $('<iframe />');
-    viewer.append(iframe);
-    return iframe;
-  }
-
-  function setInViewer(key) {
-    console.log("setInViewer:", arguments);
-    key = Number(key);
-    if (key == current_view_pub_key)
-      return;
-
-    current_view_pub_key = key;
-
-    var store = getObjectStore(DB_STORE_NAME, 'readonly');
-    getBlob(key, store, function(blob) {
-      console.log("setInViewer blob:", blob);
-      var iframe = newViewerFrame();
-
-      // It is not possible to set a direct link to the
-      // blob to provide a mean to directly download it.
-      if (blob.type == 'text/html') {
-        var reader = new FileReader();
-        reader.onload = (function(evt) {
-          var html = evt.target.result;
-          iframe.load(function() {
-            $(this).contents().find('html').html(html);
-          });
-        });
-        reader.readAsText(blob);
-      } else if (blob.type.indexOf('image/') == 0) {
-        iframe.load(function() {
-          var img_id = 'image-' + key;
-          var img = $('<img id="' + img_id + '"/>');
-          $(this).contents().find('body').html(img);
-          var obj_url = window.URL.createObjectURL(blob);
-          $(this).contents().find('#' + img_id).attr('src', obj_url);
-          window.URL.revokeObjectURL(obj_url);
-        });
-      } else if (blob.type == 'application/pdf') {
-        $('*').css('cursor', 'wait');
-        var obj_url = window.URL.createObjectURL(blob);
-        iframe.load(function() {
-          $('*').css('cursor', 'auto');
-        });
-        iframe.attr('src', obj_url);
-        window.URL.revokeObjectURL(obj_url);
-      } else {
-        iframe.load(function() {
-          $(this).contents().find('body').html("No view available");
-        });
-      }
-
-    });
-  }
-
-  /**
-   * @param {string} biblioid
-   * @param {string} title
-   * @param {number} year
-   * @param {string} url the URL of the image to download and store in the local
-   *   IndexedDB database. The resource behind this URL is subjected to the
-   *   "Same origin policy", thus for this method to work, the URL must come from
-   *   the same origin as the web site/app this code is deployed on.
-   */
-  function addPublicationFromUrl(biblioid, title, year, url) {
-    console.log("addPublicationFromUrl:", arguments);
-
-    var xhr = new XMLHttpRequest();
-    xhr.open('GET', url, true);
-    // Setting the wanted responseType to "blob"
-    // http://www.w3.org/TR/XMLHttpRequest2/#the-response-attribute
-    xhr.responseType = 'blob';
-    xhr.onload = function (evt) {
-                           if (xhr.status == 200) {
-                             console.log("Blob retrieved");
-                             var blob = xhr.response;
-                             console.log("Blob:", blob);
-                             addPublication(biblioid, title, year, blob);
-                           } else {
-                             console.error("addPublicationFromUrl error:",
-                                           xhr.responseText, xhr.status);
-                           }
-                         };
-    xhr.send();
-
-    // We can't use jQuery here because as of jQuery 1.8.3 the new "blob"
-    // responseType is not handled.
-    // http://bugs.jquery.com/ticket/11461
-    // http://bugs.jquery.com/ticket/7248
-    // $.ajax({
-    //   url: url,
-    //   type: 'GET',
-    //   xhrFields: { responseType: 'blob' },
-    //   success: function(data, textStatus, jqXHR) {
-    //     console.log("Blob retrieved");
-    //     console.log("Blob:", data);
-    //     // addPublication(biblioid, title, year, data);
-    //   },
-    //   error: function(jqXHR, textStatus, errorThrown) {
-    //     console.error(errorThrown);
-    //     displayActionFailure("Error during blob retrieval");
-    //   }
-    // });
-  }
-
-  /**
-   * @param {string} biblioid
-   * @param {string} title
-   * @param {number} year
-   * @param {Blob=} blob
-   */
-  function addPublication(biblioid, title, year, blob) {
-    console.log("addPublication arguments:", arguments);
-    var obj = { biblioid: biblioid, title: title, year: year };
-    if (typeof blob != 'undefined')
-      obj.blob = blob;
-
-    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
-    var req;
-    try {
-      req = store.add(obj);
-    } catch (e) {
-      if (e.name == 'DataCloneError')
-        displayActionFailure("This engine doesn't know how to clone a Blob, " +
-                             "use Firefox");
-      throw e;
-    }
-    req.onsuccess = function (evt) {
-      console.log("Insertion in DB successful");
-      displayActionSuccess();
-      displayPubList(store);
-    };
-    req.onerror = function() {
-      console.error("addPublication error", this.error);
-      displayActionFailure(this.error);
-    };
-  }
-
-  /**
-   * @param {string} biblioid
-   */
-  function deletePublicationFromBib(biblioid) {
-    console.log("deletePublication:", arguments);
-    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
-    var req = store.index('biblioid');
-    req.get(biblioid).onsuccess = function(evt) {
-      if (typeof evt.target.result == 'undefined') {
-        displayActionFailure("No matching record found");
-        return;
-      }
-      deletePublication(evt.target.result.id, store);
-    };
-    req.onerror = function (evt) {
-      console.error("deletePublicationFromBib:", evt.target.errorCode);
-    };
-  }
-
-  /**
-   * @param {number} key
-   * @param {IDBObjectStore=} store
-   */
-  function deletePublication(key, store) {
-    console.log("deletePublication:", arguments);
-
-    if (typeof store == 'undefined')
-      store = getObjectStore(DB_STORE_NAME, 'readwrite');
-
-    // As per spec http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation
-    // the result of the Object Store Deletion Operation algorithm is
-    // undefined, so it's not possible to know if some records were actually
-    // deleted by looking at the request result.
-    var req = store.get(key);
-    req.onsuccess = function(evt) {
-      var record = evt.target.result;
-      console.log("record:", record);
-      if (typeof record == 'undefined') {
-        displayActionFailure("No matching record found");
-        return;
-      }
-      // Warning: The exact same key used for creation needs to be passed for
-      // the deletion. If the key was a Number for creation, then it needs to
-      // be a Number for deletion.
-      req = store.delete(key);
-      req.onsuccess = function(evt) {
-        console.log("evt:", evt);
-        console.log("evt.target:", evt.target);
-        console.log("evt.target.result:", evt.target.result);
-        console.log("delete successful");
-        displayActionSuccess("Deletion successful");
-        displayPubList(store);
-      };
-      req.onerror = function (evt) {
-        console.error("deletePublication:", evt.target.errorCode);
-      };
-    };
-    req.onerror = function (evt) {
-      console.error("deletePublication:", evt.target.errorCode);
-      };
-  }
-
-  function displayActionSuccess(msg) {
-    msg = typeof msg != 'undefined' ? "Success: " + msg : "Success";
-    $('#msg').html('<span class="action-success">' + msg + '</span>');
-  }
-  function displayActionFailure(msg) {
-    msg = typeof msg != 'undefined' ? "Failure: " + msg : "Failure";
-    $('#msg').html('<span class="action-failure">' + msg + '</span>');
-  }
-  function resetActionStatus() {
-    console.log("resetActionStatus ...");
-    $('#msg').empty();
-    console.log("resetActionStatus DONE");
-  }
-
-  function addEventListeners() {
-    console.log("addEventListeners");
-
-    $('#register-form-reset').click(function(evt) {
-      resetActionStatus();
-    });
-
-    $('#add-button').click(function(evt) {
-      console.log("add ...");
-      var title = $('#pub-title').val();
-      var biblioid = $('#pub-biblioid').val();
-      if (!title || !biblioid) {
-        displayActionFailure("Required field(s) missing");
-        return;
-      }
-      var year = $('#pub-year').val();
-      if (year != '') {
-        // Better use Number.isInteger if the engine has EcmaScript 6
-        if (isNaN(year))  {
-          displayActionFailure("Invalid year");
-          return;
-        }
-        year = Number(year);
-      } else {
-        year = null;
-      }
-
-      var file_input = $('#pub-file');
-      var selected_file = file_input.get(0).files[0];
-      console.log("selected_file:", selected_file);
-      // Keeping a reference on how to reset the file input in the UI once we
-      // have its value, but instead of doing that we rather use a "reset" type
-      // input in the HTML form.
-      //file_input.val(null);
-      var file_url = $('#pub-file-url').val();
-      if (selected_file) {
-        addPublication(biblioid, title, year, selected_file);
-      } else if (file_url) {
-        addPublicationFromUrl(biblioid, title, year, file_url);
-      } else {
-        addPublication(biblioid, title, year);
-      }
-
-    });
-
-    $('#delete-button').click(function(evt) {
-      console.log("delete ...");
-      var biblioid = $('#pub-biblioid-to-delete').val();
-      var key = $('#key-to-delete').val();
-
-      if (biblioid != '') {
-        deletePublicationFromBib(biblioid);
-      } else if (key != '') {
-        // Better use Number.isInteger if the engine has EcmaScript 6
-        if (key == '' || isNaN(key))  {
-          displayActionFailure("Invalid key");
-          return;
-        }
-        key = Number(key);
-        deletePublication(key);
-      }
-    });
-
-    $('#clear-store-button').click(function(evt) {
-      clearObjectStore();
-    });
-
-    var search_button = $('#search-list-button');
-    search_button.click(function(evt) {
-      displayPubList();
-    });
-
-  }
-
-  openDb();
-  addEventListeners();
-
-})(); // Immediately-Invoked Function Expression (IIFE)
-
- -

{{ LiveSampleLink('Full_IndexedDB_example', "Test the online live demo") }}

- -

Ver também

- -

Uma leitura adicional para você encontrar mais informações.

- -

Refências

- - - -

Guias e tutoriais

- - diff --git a/files/pt-br/web/api/indexeddb_api/using_indexeddb/index.html b/files/pt-br/web/api/indexeddb_api/using_indexeddb/index.html new file mode 100644 index 0000000000..da14879b31 --- /dev/null +++ b/files/pt-br/web/api/indexeddb_api/using_indexeddb/index.html @@ -0,0 +1,1281 @@ +--- +title: Usando IndexedDB +slug: Web/API/IndexedDB_API/Usando_IndexedDB +tags: + - API IndexedDB Tutorial Avançado +translation_of: Web/API/IndexedDB_API/Using_IndexedDB +--- +
+

IndexedDB é uma forma de armazenar dados no navegador do usuário. Com ele você pode criar aplicações web com possibilidade de fazer query sem necessidade de conexão, suas aplicações podem funcionar tanto online quanto offline. 

+
+ +

Sobre esse documento

+ +

Esse tutorial utiliza a API assíncrona do IndexedDB. Se você não está familiarizado com IndexedDB, você pode ler Conceitos básicos sobre IndexedDB.

+ +

Para a documentação de referência, veja o artigo sobre API IndexedDB, pois nele contém os tipos de objetos utilizados no IndexedDB,  como também métodos da API, tanto síncrona como assíncrona. 

+ +

Padrão básico

+ +

O IndexedDB encoraja o uso do seguinte padrão:

+ +
    +
  1. Abrir um banco de dados.
    2. +
  2. Criar um ObjectStore ao atualizar o banco. 
    3. +
  3. Iniciar uma transação e e faz um request para fazer alguma operação no banco, como adicionar ou obter dados.
    4. +
  4. +
    Esperar a operação ser completada ouvindo algum evento DOM.
    +
    5. +
  5. +
    Fazer algo com o resultado da query (que pode ser obtida pelo objeto request).
    +
    6. +
+ +

OK, então, agora com esses conceitos em mente, nós podemos fazer coisas mais concretas.

+ +

Criando e estruturando o banco

+ +

Pelo fato  da especificação ainda estar evoluindo, as implementações do IndexedDB tem prefixos de navegadores. Os navegadores podem ter implementações diferentes da API IndexedDB até a especificação ser consolidada. Mas uma vez que tudo chegar a um consenso, os navegadores tirarão seus prefixos. Atualmente, algumas implementações removeram o prefixo: Internet Explorer 10, Firefox 16, Chrome 24. Quando eles usam prefixo, navegadores baseados no Gecko usam o prefixo moz, enquanto os navegadores baseados no WebKit usam o prefixo webkit.

+ +

Usando uma versão experimental do IndexedDB

+ +

Se você quiser testar seu código em navegadores que usam prefixo, você pode usar o código abaixo:  

+ +
// Na linha abaixo, você deve incluir os prefixos do navegador que você vai testar.
+window.indexedDB = window.indexedDB || window.mozIndexedDB || window.webkitIndexedDB || window.msIndexedDB;
+// Não use "var indexedDB = ..." se você não está numa function.
+// Posteriormente, você pode precisar de referências de algum objeto window.IDB*:
+window.IDBTransaction = window.IDBTransaction || window.webkitIDBTransaction || window.msIDBTransaction;
+window.IDBKeyRange = window.IDBKeyRange || window.webkitIDBKeyRange || window.msIDBKeyRange;
+// (Mozilla nunca usou prefixo nesses objetos, então não precisamos window.mozIDB*)
+ +

Tome cuidado, implementações prefixadas podem estar com bugs ou implementando especificações antigas. Portanto, não é recomendado usar em produção. É preferível não usar IndexedDB em navegadores antigos:

+ +
if (!window.indexedDB) {
+    window.alert("Seu navegador não suporta uma versão estável do IndexedDB. Alguns recursos não estarão disponíveis.");
+}
+
+ +

Abrindo um banco

+ +

Começamos todo o processo assim:

+ +
// Abrindo o banco de dados
+var request = window.indexedDB.open("DBteste", 3);
+
+ +

Abrir um banco é como qualquer outra operação — Você tem que "requerer (request)".

+ +

A requisição de abertura não abre o banco ou inicia a transação. A chamada da função open() retorna um objeto IDBOpenDBRequest com o resultado (success) ou um erro que você terá que tratar. Muitas outras funções assíncronas no IndexedDB fazem a mesma coisa - retornam um objeto IDBRequest com o resultado ou erro. O resultado para a função open é uma instância de IDBDatabase.

+ +

O segundo parâmetro para o método open é a versão do banco. A versão do banco determina seu schema — os registros no banco e sua estrutura. Se o banco não existe ainda, ele é criado pela operação open, então o evento onupgradeneeded é chamado e você cria o schema do banco nesse evento. Se o banco existe mas você está fornecendo um novo número de versão, o evento onupgradeneeded é chamado imediatamente, permitindo você tratar a atualização do schema. Para mais informações sobre isso veja Updating the version of the database.

+ +
+

O número de versão é um unsigned long long, o que significa que ele pode ver um inteiro muito grande. Isso também significa que você não pode usar float, pois ele será convertido em um inteiro pequeno e a transação pode não acontecer, ou o evento upgradeneeded pode não ser chamado. Então se você usar 2.4 como versão:

+ +
var request = indexedDB.open("DBteste", 2.4); // não faça isso, pois a versão será convertida para 2.
+
+ +

Gerenciando handlers

+ +

A primeira coisa que você vai querer fazer em quase todos os requests é tratar os casos de success e error:

+ +
request.onerror = function(event) {
+  // Fazer algo com request.errorCode!
+};
+request.onsuccess = function(event) {
+  // Fazer algo com request.result!
+};
+ +

Qual das duas funções, onsuccess() ou onerror(),  será chamada? Se tudo correr bem, o evento de sucesso (que é um evento DOM event com propriedade type setada "success") é chamado com request como seu target. Uma vez chamado, a função onsuccess() no request é chamada com o evento de sucesso em seu contexto. Por outro lado, se acontecer algum problema, um evento de erro (que é um evento DOM com a propriedade type setada para "error") é chamado no request. Então a função onerror()  com o evento erro em seu contexto.

+ +

A API IndexedDB é feita para minimizar a necessidade de manipular erros, então você não fará muitos eventos de erro (ao menos, se você usar a API!) No  caso de abrir um banco, portanto, existe algumas condições comuns para eventos de erro. O problema mais comum é o usuário não dar permissão para criar o banco. Um dos principais objetivos do IndexedDB é permitir muitos dados serem armazenados para uso offline. (Para aprender mais sobre o quanto cada navegador pode armazenar, veja Storage limits).  

+ +

Obviamente, navegadores não querem armazenar dados que poluem seu computador, então o navegador mostra uma mensagem ao usuário na primeira vez que um aplicativo tenta abrir o IndexedDB. O usuário pode escolher permitir ou negar acesso. O IndexedDB também é desabilitado no modo privado dos navegadores (ctrl+shift+N no Chrome e ctrl+shift+P no Firefox). Isso acontece porque o intuito do modo privado é não deixar rastros na navegação.

+ +

Agora, assumindo que o usuário aprovou seu request para criar o banco, e você recebeu success; Qual é o próximo passo? O request foi gerado com a chamada de indexedDB.open(), e request.result é uma instância de IDBDatabase, e você definitivamente vai querer armazenar isso para usar depois. Veja abaixo:

+ +
var db;
+var request = indexedDB.open("DBteste");
+request.onerror = function(event) {
+  alert("Você não habilitou minha web app para usar IndexedDB?!");
+};
+request.onsuccess = function(event) {
+  db = request.result;
+};
+
+ +

Tratando Erros

+ +

Como mencionado acima, o evento de erro é chamado quando o request dá erro. Se você quer evitar manipuladores de erro a cada request, você pode adicionar um único manipulador de erro no objeto db, como abaixo:

+ +
db.onerror = function(event) {
+  // Função genérica para tratar os erros de todos os requests desse banco!
+  alert("Database error: " + event.target.errorCode);
+};
+
+ +

Um dos erros mais comuns ao abrir o banco é VER_ERR. Ele indica que a versão do banco existente é maior que a versão que você quer abrir.

+ +

Criando ou atualizando a versão do banco

+ +

Quando você cria um novo banco ou aumenta sua versão, o evento onupgradeneeded será chamado. No manipulador deste evento, você deve criar o objectStore necessário para a versão do banco:

+ +
// Este evento é implementado somente em navegadores mais recentes
+request.onupgradeneeded = function(event) {
+  var db = event.target.result;
+
+  // cria um objectStore para esse banco
+  var objectStore = db.createObjectStore("nome", { keyPath: "minhaChave" });
+};
+ +

Neste caso, o banco já terá objectStores de suas versões anteriores, então você não terá que criar esses objectStores de novo. Você somente precisará criar um novo objectStore qualquer, ou deletar objectStores da versão anterior que não serão utilizados. Se você precisa mudar um objectStore existente (mudar o keyPath, por exemplo),  então você precisa deletar o objectStore antigo e criá-lo novamente com as novas opções. (Note que isso irá deletar a informação no objectStore! Se você precisa salvar a informação, você deve ler isso e salvá-lo em algum lugar antes de atualizar o banco.)

+ +

Blink/Webkit suporta a versão atual da especificação, nas versões do Chrome 23+ e Opera 17+; IE10+ também suporta. Outros motores e versões antigas não implementam a versão atual da especificação e não suportam a assinatura indexedDB.open(name, version).onupgradeneeded ainda.  Para mais informação sobre como atualizar a versão do banco em Webkit/Blink, veja IDBDatabase reference article.

+ +

Estruturando o banco

+ +

Agora a estrutura do banco. IndexedDB usa "armazens de objetos" em vez de tabelas, e um único banco de dados pode conter qualquer número de "armazem de objetos". Sempre que um valor é armazenado num objectStore, ele é associado a uma chave. Existe várias maneiras diferentes de uma chave ser mostrada, dependendo do que o objectStore usa, um key path ou key generator.

+ +

A tabela abaixo mostra as direfentes chaves suportadas:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key Path (keyPath)Key Generator (autoIncrement)Description
NãoNãoEste objectStore pode ter qualquer tipo de valor primitivo como número ou string. Você deve suprir uma chave separada sempre que adicionar um novo valor.
SimNãoEste objectStore pode simplesmente armazenar objetos JavaScript. O objeto deve ter uma propriedade com o mesmo nome do key path.
NãoSimEste objectStore pode possuir qualquer tipo de valor. A chave é gerada para você, automaticamente, ou você pode suprir uma chave separada, caso utilize uma chave específica.
SimSimEste objectStore suporta somente objetos JavaScript. Normalmente uma chave é gerada e o valor dela é armazenado no objeto em uma propriedade com o mesmo nome da key path. Portanto, se a propriedade já existe, o valor dela será usado como chave, em vez do valor gerado.
+ +

Você também pode criar índices em qualquer objectStore. Um indice deixa você olhar os valores armazenados no objectStore usando o valor de uma propriedade do objectStore, em vez de sua chave.

+ +

Adicionalmente, indices tem a habilidade de forçar restrições simples nos dados armazenados. Setando uma flag única quando criar o índice, reforça que dois objetos são armazenados contendo o mesmo valor para o key path do índice. Então, por exemplo, se você tem um objeto armazenado que tem um conjunto de pessoas, e você quer ter certeza que ninguém tera o mesmo e-mail, você pode usar um índice com flag única para forçar isso.

+ +

Isso soa meio confuso, mas este exemplo pode iluminar o conceito. Primeiro, vamos definir alguns dados a serem usados no exemplo:

+ +
// Isso é o que os dados de nossos clientes será.
+const DadosClientes = [
+  { ssn: "444-44-4444", nome: "Bill", idade: 35, email: "bill@company.com" },
+  { ssn: "555-55-5555", nome: "Donna", idade: 32, email: "donna@home.org" }
+];
+
+ +

Agora  vamos ver  ccomo criar um IndexedDB para armazenar nossos dados:

+ +
const dbName = "clientes";
+
+var request = indexedDB.open(dbName, 2);
+
+request.onerror = function(event) {
+  // Tratar erros.
+};
+request.onupgradeneeded = function(event) {
+  var db = event.target.result;
+
+  // Cria um objectStore para conter a informação sobre nossos clientes. Nós vamos
+  // usar "ssn" como key path porque sabemos que é único;
+  var objectStore = db.createObjectStore("clientes", { keyPath: "ssn" });
+
+  // Cria um índice para buscar clientes pelo nome. Podemos ter nomes
+  // duplicados, então não podemos usar como índice único.
+  objectStore.createIndex("nome", "nome", { unique: false });
+
+  // Cria um índice para buscar clientes por email. Queremos ter certeza
+  // que não teremos 2 clientes com o mesmo e-mail;
+  objectStore.createIndex("email", "email", { unique: true });
+
+  // Usando transação oncomplete para afirmar que a criação do objectStore
+  // é terminada antes de adicionar algum dado nele.
+  objectStore.transaction.oncomplete = function(event) {
+    // Armazenando valores no novo objectStore.
+    var clientesObjectStore = db.transaction("clientes", "readwrite").objectStore("clientes");
+    for (var i in DadosClientes) {
+      clientesObjectStore.add(DadosClientes[i]);
+    }
+  }
+};
+
+ +

Como falamos antes, onupgradeneeded é o único lugar onde você pode alterar a estrutura do banco. Nele você pode criar e deletar objectStores e construir ou remover índices.

+ +
Armazens de objetos são criados com uma única chamada de createObjectStore(). O método pega o nome do armazem e um objeto parâmetro. Mesmo que o objeto parâmetro seja opcional, ele é muito importante porque ele deixa você definir propriedades importantes e ajustar tipos de dados que você quer criar. No nosso caso, nós obtemos um objectStore chamado "clientes" e definimos um keyPath, que é a propriedade que faz um objeto individual ser único no banco. Essa propriedade, nesse exemplo, é "ssn", que simboliza o cpf (social security number), que é único. O "ssn" deve ser apresentado em cada objeto armazenado no objectStore. 
+ +

Nós também criamos um índice chamado "nome" ligado à propriedade nome. Assim como o createObjectStore(), o createIndex() tem um parâmetro opcional options que cuida do tipo de índice que você quer criar. Adicionando objetos que não tem a propriedade nome terá sucesso, porém esses objetos não aparecerão no índice "nome".

+ +

Nós podemos obter os objetos de clientes armazenados usando os ssn da objectStore diretamente, ou usando os nomes usados no índice. Para aprender como isso é feito, veja a seção usando um índice.

+ +

Usando um key generator

+ +

Setando uma flag autoIncrement ao criar o objectStore habilitará o key generator. Por padrão ele não é setado.

+ +

Com o key generator, a chave será gerada automaticamente quando você adicionar algum valor no objectStore. O atual número do key generator é sempre setado 1 quando a primeira key generator do objectStore é criada. Basicamente a próxima chave recebe o incremento de 1. O número atual da key generator nunca decresce,  a não ser se alguma operação do banco for revertida, como numa transação abortada, por exemplo. No entanto, deletar um registro ou limpar todos os registros nunca afeta o key generator dos objectStores.

+ +

Nós podemos criar outro objectStore com o key generator como abaixo:

+ +
// Abrindo o indexedDB.
+var request = indexedDB.open(dbName, 3);
+
+request.onupgradeneeded = function (event) {
+
+    var db = event.target.result;
+
+    // Criando outro objeto chamado "names" com o autoIncrement setado.
+    var objStore = db.createObjectStore("names", { autoIncrement : true });
+
+    // Porque "names" tem o the key generator, a chave para o nome é gerada automaticamente.
+    // Os registros adicionados serão assim:
+    // key : 1 => value : "Bill"
+    // key : 2 => value : "Donna"
+    for (var i in DadosClientes) {
+        objStore.add(DadosClientes[i].nome);
+    }
+}
+ +

Para mais detalhes veja "W3C Key Generators".

+ +

Adicionando, obtendo e removendo dados

+ +

Antes de fazer qualquer coisa em um novo banco, você precisa iniciar uma transação. Transações estão no objeto database, e você tem que especificar qual objectStore você quer na transaction. Uma vez que você está dentro da transação, você pode acessar os objectStores  com seus dados e fazer os requests. Depois, você precisa decidir se você vai fazer mudanças no banco ou se você simplesmente quer ler esses dados. Transações tem três modos disponíveis: readonly, readwrite, and versionchange.

+ +

Para mudar o "schema" ou estrutura do banco — o que envolve criar ou deletar objectStores ou índices — a transação deve ser em modo versionchange. Esta transação é aberta chamando o método {{domxref("IDBFactory.open")}} especificando a  version. (Em navegadores com WebKit que não tem a ultima especificação implementada, o método {{domxref("IDBFactory.open")}} tem apenas um parâmetro, o nome do banco; então você deve chamar {{domxref("IDBVersionChangeRequest.setVersion")}} para estabelecer uma transação versionchange.)

+ +

Para ler os registros de um objectStore existente, a transação pode ser tanto readonly quanto readwrite. Para fazer mudanças em um objectStore existente, a transação deve ser em modo readwrite. Você abre essas transações usando {{domxref("IDBDatabase.transaction")}}. O método aceita dois parâmetros: o storeNames (o escopo, definido como um array de objectStores que você quer acessar) e o modo (readonly or readwrite) da transação. O método retorna o objeto detransação contendo o método {{domxref("IDBIndex.objectStore")}}, que você pode usar para acessar seu objectStore. Por padrão, quando nenhum modo é especificado, a transação é aberta no modo readonly.

+ +

Você pode deixar o acesso aos dados mais rápido usando o escopo correto e o modo correto de transação. Aqui vai algumas dicas:

+ + + +

Adicionando dados no banco

+ +

Se você acabou de criar o banco, então você provavelmente quer escrever algo nele. Veja abaixo:

+ +
var transaction = db.transaction(["clientes"], "readwrite");
+// Nota: Implementações mais antigas usam uma versão IDBTransaction.READ_WRITE antiga em vez de "readwrite".
+// Então, para suportar versões antigas, escreva:
+// var transaction = db.transaction(["clientes"], IDBTransaction.READ_WRITE);
+ +

A função transaction() tem dois argumentos (opcionais) e retorna um objeto de transação. O primeiro argumento é uma lista de objectStores que serão trabalhados na transação. Você pode passar um array vazio se você quer uma transação com todos os objectStores, mas não faça isso pois a especificação diz que um array vazio pode gerar um erro InvalidAccessError. Se você não especificar nada no segundo parâmetro, você tem uma transação read-only. Se você quer escrever no banco, use "readwrite".

+ +

Agora que você tem uma transação, você precisa entender seu tempo de uso. Transações são amarradas a um evento. Se você faz uma transação fora de um evento, ela ficará inativa. A única maneira de manter uma transação ativa é fazer um request nela. Quando o request acabar você terá a oportunidade de extender a transação durante o callback. Se você tentar extender uma transação dentro de um evento, então ela tornará inativa. Se existir requests pendentes, a transação continua ativa. O tempo de vida de uma transação é realmente simples mas deve ser usada em um curto espaço de tempo. Outros exemplos poderão ajudá-lo. Se você começar a ver TRANSACTION_INACTIVE_ERR error então você está fazendo algo errado.

+ +

Transações podem receber eventos DOM de três tipos diferentes: error, abort, e complete. Nós falamos sobre o error, ou seja, a transação recebe um error sempre que o request gerar erro. Um ponto mais sutil é que o comportamento padrão de um erro é abortar a transação na qual ele estava. A menos que você manipule o erro chamando preventDefault() e fazendo algo depois, a transaçaõ inteira será desfeita. Este design força você a pensar sobre manipulação de erros, mas você pode sempre adicionar um manipulador de todos os erros se a manipulação separada estiver complicada. Se você não tratar o erro ou chamar abort() na transação, então a transação é desfeita (roll back) e o evento abort é chamado. Por outro lado, depois de todo request completado, você tem um evento complete. Se você fazer várias operações no banco, então seguir as operações de transações pode ser um caminho a seguir.

+ +

Agora que você tem uma transação, você precisará obter um objectStore dela. Transações somente deixam você obter um objectStore citado na transação. Então você pode adicionar os dados que precisa.

+ +
// Faz algo após a inserção dos dados.
+transaction.oncomplete = function(event) {
+  alert("Pronto!");
+};
+
+transaction.onerror = function(event) {
+  // Não esquecer de tratar os erros!
+};
+
+var objectStore = transaction.objectStore("clientes");
+for (var i in DadosClientes) {
+  var request = objectStore.add(DadosClientes[i]);
+  request.onsuccess = function(event) {
+    // event.target.result == DadosClientes[i].ssn;
+  };
+}
+ +

O result de um request gerado de uma chamada de add() é a chave do valor  que foi adicionado. Então neste caso, ele deve ser igual ao valor do ssn do objeto que foi adicionado, desde que o objeto use o ssn como key path. Note que a função add() não deixa nenhum objeto ser adicionado com a mesma chave. Se você está tentando modificar um registro existente, você deve usar o put(), como explica a seção  {{ anch("Updating an entry in the database") }}.

+ +

Removendo dados do banco

+ +

Para remoção o código é parecido:

+ +
var request = db.transaction(["clientes"], "readwrite")
+                .objectStore("clientes")
+                .delete("444-44-4444");
+request.onsuccess = function(event) {
+  // Pronto!
+};
+ +

Obtendo dados do banco

+ +

Agora que o banco tem algumas informações nele, você pode obtê-las de diferentes maneiras. Primeiro, um get() simples. Você precisa informar a chave do valor a ser obtido:

+ +
var transaction = db.transaction(["clientes"]);
+var objectStore = transaction.objectStore("clientes");
+var request = objectStore.get("444-44-4444");
+request.onerror = function(event) {
+  // Tratar erro!
+};
+request.onsuccess = function(event) {
+  // Fazer algo com request.result!
+  alert("O nome do SSN 444-44-4444 é " + request.result.name);
+};
+ +

Veja agora de maneira resumida:

+ +
db.transaction("clientes").objectStore("clientes").get("444-44-4444").onsuccess = function(event) {
+  alert("O nome do SSN 444-44-4444 é " + request.result.name);
+};
+ +

Viu como funciona? Desde que exista um objectStore, você pode evitar passar uma lista de objectStores que precisa na transação e passar apenas o nome como string. Você também pode ler do banco, apenas, então não precisará de uma transação "readwrite". Chamando transaction() com nenhum modo especificado, você terá uma transação "readonly". Outra consideração é que você não necessita salvar o request em uma variável. Desde que o evento DOM tenha o target que você precisará para obter a propriedade result.

+ +
+

Note: Você pode deixar o acesso aos dados mais rápido limitando o escopo e o modo de transação. Veja algumas dicas:

+ + +
+ +

Atualizando um registro no banco

+ +

Agora que obtemos algum dado, atualizá-ls é inserí-los novamente no IndexedDB é bem simples. Vamos atualizar o exemplo anterior:

+ +
var objectStore = db.transaction(["clientes"], "readwrite").objectStore("clientes");
+var request = objectStore.get("444-44-4444");
+request.onerror = function(event) {
+  // Tratar erro
+};
+request.onsuccess = function(event) {
+  // Obter os valores antigos
+  var data = request.result;
+
+  // atualizar algum dado
+  data.age = 42;
+
+  // Atulizar esse dado no banco
+  var requestUpdate = objectStore.put(data);
+   requestUpdate.onerror = function(event) {
+     // Tratar erro
+   };
+   requestUpdate.onsuccess = function(event) {
+     // Sucesso na atualização \o/
+   };
+};
+ +

Criamos uma objectStore e obtemos um cliente dele, identificado pelo ssn (444-44-4444). Nós atualizamos o objeto, passando-o como parâmetro de um método put de outro request (requestUpdate) sobrescrevendo o valor antigo.

+ +
+

Note que neste caso nós temos que especificar a transação readwrite porque nós queremos escrever no banco, não somente ler os dados dele.

+
+ +

Usando um cursor

+ +

Ao usar o método get() você precisa saber a chave do objeto que deseja obter. Se você quer passear entre todos os valores do seu objectStore, então você pode usar um cursor. Veja:

+ +
var objectStore = db.transaction("cliente").objectStore("cliente");
+
+objectStore.openCursor().onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    alert("O nome do SSN " + cursor.key + " é " + cursor.value.name);
+    cursor.continue();
+  }
+  else {
+    alert("Não existe mais registros!");
+  }
+};
+ +

A função openCursor() tem vários argumentos. Primeiro, você pode limitar o número de itens obtidos usando uma chave que veremos logo abaixo. Segundo, você pode especificar a direção que deseja iterar. No exemplo acima, nós estamos iterando em todos os objetos em ordem ascendente. O callback de sucesso para cursor é um pouco especial. O objeto cursor já é o result do request (acima nós usamos event.target.result). Então a chave atual e o valor pode ser encontrado na propriedade key e value do objeto cursor. Se você quer manter adiante, então você usa o método continue(). Quando você chegar ao fim dos dados (ou se não existem registros encontrados no openCursor()) você ainda tem um callback de sucesso, mas a propriedade result fica undefined.

+ +

Um padrão comum para cursores é obter todos os objetos em um objectStore e adicioná-los a um array como este:

+ +
var clientes = [];
+
+objectStore.openCursor().onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    clientes.push(cursor.value);
+    cursor.continue();
+  }
+  else {
+    alert("Todos os clientes: " + clientes);
+  }
+};
+ +
+

Note: Mozilla também implementou o método getAll() para ser usado nesse caso (e getAllKeys(), que está atualmente dentro da preferência do dom.indexedDB.experimental em about:config). Estes métodos não são parte do padrão IndexedDB, então eles podem desaparecer no futuro. Nós adicionamos porque achamos útil. O código abaixo faz o mesmo que o código acima:

+ +
objectStore.getAll().onsuccess = function(event) {
+  alert("Todos os clientes: " + event.target.result);
+};
+ +

Existe um custo de performance associado com a propriedade value do cursor, porque o objeto é criado de forma lenta. Quando você usa getAll() por exemplo, Gecko deve criar todos os objetos de uma vez. Se você está somente interessado em cada chave, é muito melhor usar o cursor do que usar o getAll(). Se você está tentando obter um array de todos os objetos, então é melhor usar o getAll().

+
+ +

Usando um índice

+ +

Armazenar dados de um cliente usando o SSN como chave é lógico pois o SSN identifica o cliente de forma única. Se você precisa obter um cliente pelo seu nome, portanto, você precisará iterar todos os registros no banco e comparar os nomes até achar o que você procura. Buscar dessa maneira é algo lento, então criamos um índice.

+ +
var index = objectStore.index("nome");
+index.get("John").onsuccess = function(event) {
+  alert("O SSN de John é " + event.target.result.ssn);
+};
+ +

O cursor "nome" não é único, então pode existir mais de um registro com o nome igual a "John". Neste caso você sempre obtem o registro com a chave de menor valor.

+ +

Se você precisa acessar todos os registros retornados, você pode usar um cursor. Você pode abrir dois tipos de cursores. Um cursor normal mapeia o índice ao objeto na objectStore. Uma cursor-chave mapeia o a propriedade índice à chave usada para armazenar o objeto. As diferenças são ilustradas abaixo:

+ +
// Usando um cursor normal para obter todos os objetos
+index.openCursor().onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    // cursor.key é um nome, como "Bill", e cursor.value é o objeto inteiro.
+    alert("Nome: " + cursor.key + ", SSN: " + cursor.value.ssn + ", email: " + cursor.value.email);
+    cursor.continue();
+  }
+};
+
+// Usando um cursor-chave para obter todos os objetos
+index.openKeyCursor().onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    // cursor.key é o nome, como "Bill", e cursor.value é o SSN (chave).
+    // Não tem como obter o resto do objeto
+    alert("Nome: " + cursor.key + ", SSN: " + cursor.value);
+    cursor.continue();
+  }
+};
+ +

Especificando o número e a direção dos cursores

+ +

Se você gostaria de limitar o número de valores retornados pelo cursor, você pode usar um objeto IDBKeyRange e passar isso como o primeiro argumento ao openCursor() ou openKeyCursor(). Você pode fazer um key range que permite um único valor, ou valores acima ou abaixo do especificado. O limite pode ser fechado (o key range inclui os valores dados) ou aberto (o key range não inclue os valores dados). Veja como funciona:

+ +
// Somente se for igual "Donna"
+var singleKeyRange = IDBKeyRange.only("Donna");
+
+// Combinações menores que "Bill", incluindo "Bill"
+var lowerBoundKeyRange = IDBKeyRange.lowerBound("Bill");
+
+// Combinações menores que "Bill", sem incluir "Bill"
+var lowerBoundOpenKeyRange = IDBKeyRange.lowerBound("Bill", true);
+
+// Combinações maiores que Donna, não incluindo "Donna"
+var upperBoundOpenKeyRange = IDBKeyRange.upperBound("Donna", true);
+
+// Combinações entre "Bill" e "Donna", sem incluir "Donna"
+var boundKeyRange = IDBKeyRange.bound("Bill", "Donna", false, true);
+
+// Para usar qualquer um desses key ranges, basta passar como primeiro parâmetro de openCursor()/openKeyCursor()
+index.openCursor(boundKeyRange).onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    // Faz algo com o que encontrar
+    cursor.continue();
+  }
+};
+ +

As vezes você pode querer iterar em ordem decrescente, em vez de crescente, alterando o segundo parâmetro de openCursor():

+ +
objectStore.openCursor(boundKeyRange, "prev").onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    // Prev indica ordem decrescente
+    cursor.continue();
+  }
+};
+ +

Se você apenas quer especificar a ordem sem key range, é só passar null no primeiro parâmetro:

+ +
objectStore.openCursor(null, "prev").onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    // Faça algo com os resultados.
+    cursor.continue();
+  }
+};
+ +

Uma vez que o índice "nome" não é único, pode existir várias entradas onde o nome é o mesmo. Isso não acontece com objectStores porque a chave deve ser sempre única. Se você deseja filtrar valores duplicados numa iteração do cursor, você pode passar nextunique (ou prevunique se quiser decrescer) como parâmetro de direção. Quando nextunique ou prevunique é usado, o registro com menor chave é retornado.

+ +
index.openKeyCursor(null, "nextunique").onsuccess = function(event) {
+  var cursor = event.target.result;
+  if (cursor) {
+    // Faça algo com os registros.
+    cursor.continue();
+  }
+};
+ +

Veja "IDBCursor Constants" para parâmetros válidos.

+ +

Mudança de versão quando a web app está aberta em outra aba.

+ +

Quando sua web app muda a versão você precisa considerar o que vai acontecer se o usuário está na versão antiga em uma aba, e carrega a versão nova na outra. Quando você chamar o open() com a versão mais nova, um evento onblocked  é chamado até que a aba da versão antiga seja fechada ou recarregada. Veja abaixo:

+ +
var openReq = mozIndexedDB.open("DBteste", 2);
+
+openReq.onblocked = function(event) {
+  // Se existe outra aba com a versão antiga
+  alert("Existe uma versão antiga da web app aberta em outra aba, feche-a por favor!");
+};
+
+openReq.onupgradeneeded = function(event) {
+  // Se estiver tudo fechado, então faça as devidas alterações
+  db.createObjectStore(/* ... */);
+  useDatabase(db);
+}
+
+openReq.onsuccess = function(event) {
+  var db = event.target.result;
+  useDatabase(db);
+  return;
+}
+
+function useDatabase(db) {
+  // Esteja certo de que adicionou um evento para notificar se a página muda a versão
+  // Nós devemos fechar o banco. Isso permite à outra página ser atualizada
+  // Se você não fizer isso a atualização não acontecerá até fechar as abas.
+  db.onversionchange = function(event) {
+    db.close();
+    alert("Uma nova versão desta web app está pronta. Atualiza, por favor!");
+  };
+
+  // Fazer algo com os bancos
+}
+
+ +

Segurança

+ +

IndexedDB usa o princípio de mesma origem, o que significa que o banco só será acessado pelo site que o criou.

+ +

É importante notar que o IndexedDB não funciona para conteúdo carregado em um frame de outro site (seja {{ HTMLElement("frame") }} ou {{ HTMLElement("iframe") }}. Esta é uma política de segurança e privacidade análoga ao bloqueio de cookies de terceiros. Para mais detalhes, veja {{ bug(595307) }}.

+ +

Alerta sobre fechar o navegador

+ +

Quando o navegador é fechado, qualquer transação pendente no IndexedDB será abortada (silenciosamente) — ele não vai completar, nem chamar o evento de erro.  Uma vez que o usuário pode sair do navegador, em qualquer momento, isto significa que você não pode confiar em qualquer transação específica para completar ou para saber que ela não foi concluída. Existem várias implicações nesse comportamento.

+ +

Primeiro, você deve ter o cuidado de sempre deixar seu banco de dados em um estado consistente, no final de cada transação. Por exemplo, suponha que você está usando IndexedDB para armazenar uma lista de itens que permitem ao usuário editar. Você salvar a lista após a edição, limpando o armazenamento de objetos e, em seguida, escrever a nova lista. Se você limpar o armazenamento de objetos em uma transação e escrever a nova lista em outra transação, há um perigo de que o navegador irá fechar após a limpeza de dados e antes da gravação, deixando-o com um banco de dados vazio. Para evitar isso, você deve combinar tanto a limpeza quanto a gravação em uma única transação.

+ +

Em segundo lugar, você nunca deve amarrar as operações de banco de dados ao evento unload. Se o evento unload é acionado pelo fechamento do navegador, todas as transações criadas no unload nunca serão concluídas. Uma abordagem intuitiva para manter algumas informações em sessões do navegador é lê-la a partir do banco de dados quando o navegador (ou uma determinada página) é aberta, atualizá-la assim que o usuário interagir com o navegador, e depois salvá-lo para o banco de dados quando o navegador (ou página) será fechada. No entanto, isso não vai funcionar. As transações de banco de dados será criado no unload, mas como elas são assíncronas, serão abortadas antes que eles possam executar.

+ +

De fato, não existe uma maneira de garantir que as transações no IndexedDBserão completadas, mesmo com o fechamento padrão do navegador. Ver {{ bug(870645) }}.

+ +

Exemplo de IndexedDB

+ +

HTML

+ +
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"></script>
+
+    <h1>IndexedDB Demo: storing blobs, e-publication example</h1>
+    <div class="note">
+      <p>
+        Works and tested with:
+      </p>
+      <div id="compat">
+      </div>
+    </div>
+
+    <div id="msg">
+    </div>
+
+    <form id="register-form">
+      <table>
+        <tbody>
+          <tr>
+            <td>
+              <label for="pub-title" class="required">
+                Title:
+              </label>
+            </td>
+            <td>
+              <input type="text" id="pub-title" name="pub-title" />
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <label for="pub-biblioid" class="required">
+                Bibliographic ID:<br/>
+                <span class="note">(ISBN, ISSN, etc.)</span>
+              </label>
+            </td>
+            <td>
+              <input type="text" id="pub-biblioid" name="pub-biblioid"/>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <label for="pub-year">
+                Year:
+              </label>
+            </td>
+            <td>
+              <input type="number" id="pub-year" name="pub-year" />
+            </td>
+          </tr>
+        </tbody>
+        <tbody>
+          <tr>
+            <td>
+              <label for="pub-file">
+                File image:
+              </label>
+            </td>
+            <td>
+              <input type="file" id="pub-file"/>
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <label for="pub-file-url">
+                Online-file image URL:<br/>
+                <span class="note">(same origin URL)</span>
+              </label>
+            </td>
+            <td>
+              <input type="text" id="pub-file-url" name="pub-file-url"/>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+
+      <div class="button-pane">
+        <input type="button" id="add-button" value="Add Publication" />
+        <input type="reset" id="register-form-reset"/>
+      </div>
+    </form>
+
+    <form id="delete-form">
+      <table>
+        <tbody>
+          <tr>
+            <td>
+              <label for="pub-biblioid-to-delete">
+                Bibliographic ID:<br/>
+                <span class="note">(ISBN, ISSN, etc.)</span>
+              </label>
+            </td>
+            <td>
+              <input type="text" id="pub-biblioid-to-delete"
+                     name="pub-biblioid-to-delete" />
+            </td>
+          </tr>
+          <tr>
+            <td>
+              <label for="key-to-delete">
+                Key:<br/>
+                <span class="note">(for example 1, 2, 3, etc.)</span>
+              </label>
+            </td>
+            <td>
+              <input type="text" id="key-to-delete"
+                     name="key-to-delete" />
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <div class="button-pane">
+        <input type="button" id="delete-button" value="Delete Publication" />
+        <input type="button" id="clear-store-button"
+               value="Clear the whole store" class="destructive" />
+      </div>
+    </form>
+
+    <form id="search-form">
+      <div class="button-pane">
+        <input type="button" id="search-list-button"
+               value="List database content" />
+      </div>
+    </form>
+
+    <div>
+      <div id="pub-msg">
+      </div>
+      <div id="pub-viewer">
+      </div>
+      <ul id="pub-list">
+      </ul>
+    </div>
+
+ +

CSS Content

+ +
body {
+  font-size: 0.8em;
+  font-family: Sans-Serif;
+}
+
+form {
+  background-color: #cccccc;
+  border-radius: 0.3em;
+  display: inline-block;
+  margin-bottom: 0.5em;
+  padding: 1em;
+}
+
+table {
+  border-collapse: collapse;
+}
+
+input {
+  padding: 0.3em;
+  border-color: #cccccc;
+  border-radius: 0.3em;
+}
+
+.required:after {
+  content: "*";
+  color: red;
+}
+
+.button-pane {
+  margin-top: 1em;
+}
+
+#pub-viewer {
+  float: right;
+  width: 48%;
+  height: 20em;
+  border: solid #d092ff 0.1em;
+}
+#pub-viewer iframe {
+  width: 100%;
+  height: 100%;
+}
+
+#pub-list {
+  width: 46%;
+  background-color: #eeeeee;
+  border-radius: 0.3em;
+}
+#pub-list li {
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+  padding-right: 0.5em;
+}
+
+#msg {
+  margin-bottom: 1em;
+}
+
+.action-success {
+  padding: 0.5em;
+  color: #00d21e;
+  background-color: #eeeeee;
+  border-radius: 0.2em;
+}
+
+.action-failure {
+  padding: 0.5em;
+  color: #ff1408;
+  background-color: #eeeeee;
+  border-radius: 0.2em;
+}
+
+.note {
+  font-size: smaller;
+}
+
+.destructive {
+  background-color: orange;
+}
+.destructive:hover {
+  background-color: #ff8000;
+}
+.destructive:active {
+  background-color: red;
+}
+
+ +

 

+ +

JavaScript Content

+ +
(function () {
+  var COMPAT_ENVS = [
+    ['Firefox', ">= 16.0"],
+    ['Google Chrome',
+     ">= 24.0 (you may need to get Google Chrome Canary), NO Blob storage support"]
+  ];
+  var compat = $('#compat');
+  compat.empty();
+  compat.append('<ul id="compat-list"></ul>');
+  COMPAT_ENVS.forEach(function(val, idx, array) {
+    $('#compat-list').append('<li>' + val[0] + ': ' + val[1] + '</li>');
+  });
+
+  const DB_NAME = 'mdn-demo-indexeddb-epublications';
+  const DB_VERSION = 1; // Use a long long for this value (don't use a float)
+  const DB_STORE_NAME = 'publications';
+
+  var db;
+
+  // Used to keep track of which view is displayed to avoid uselessly reloading it
+  var current_view_pub_key;
+
+  function openDb() {
+    console.log("openDb ...");
+    var req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onsuccess = function (evt) {
+      // Better use "this" than "req" to get the result to avoid problems with
+      // garbage collection.
+      // db = req.result;
+      db = this.result;
+      console.log("openDb DONE");
+    };
+    req.onerror = function (evt) {
+      console.error("openDb:", evt.target.errorCode);
+    };
+
+    req.onupgradeneeded = function (evt) {
+      console.log("openDb.onupgradeneeded");
+      var store = evt.currentTarget.result.createObjectStore(
+        DB_STORE_NAME, { keyPath: 'id', autoIncrement: true });
+
+      store.createIndex('biblioid', 'biblioid', { unique: true });
+      store.createIndex('title', 'title', { unique: false });
+      store.createIndex('year', 'year', { unique: false });
+    };
+  }
+
+  /**
+   * @param {string} store_name
+   * @param {string} mode either "readonly" or "readwrite"
+   */
+  function getObjectStore(store_name, mode) {
+    var tx = db.transaction(store_name, mode);
+    return tx.objectStore(store_name);
+  }
+
+  function clearObjectStore(store_name) {
+    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
+    var req = store.clear();
+    req.onsuccess = function(evt) {
+      displayActionSuccess("Store cleared");
+      displayPubList(store);
+    };
+    req.onerror = function (evt) {
+      console.error("clearObjectStore:", evt.target.errorCode);
+      displayActionFailure(this.error);
+    };
+  }
+
+  function getBlob(key, store, success_callback) {
+    var req = store.get(key);
+    req.onsuccess = function(evt) {
+      var value = evt.target.result;
+      if (value)
+        success_callback(value.blob);
+    };
+  }
+
+  /**
+   * @param {IDBObjectStore=} store
+   */
+  function displayPubList(store) {
+    console.log("displayPubList");
+
+    if (typeof store == 'undefined')
+      store = getObjectStore(DB_STORE_NAME, 'readonly');
+
+    var pub_msg = $('#pub-msg');
+    pub_msg.empty();
+    var pub_list = $('#pub-list');
+    pub_list.empty();
+    // Resetting the iframe so that it doesn't display previous content
+    newViewerFrame();
+
+    var req;
+    req = store.count();
+    // Requests are executed in the order in which they were made against the
+    // transaction, and their results are returned in the same order.
+    // Thus the count text below will be displayed before the actual pub list
+    // (not that it is algorithmically important in this case).
+    req.onsuccess = function(evt) {
+      pub_msg.append('<p>There are <strong>' + evt.target.result +
+                     '</strong> record(s) in the object store.</p>');
+    };
+    req.onerror = function(evt) {
+      console.error("add error", this.error);
+      displayActionFailure(this.error);
+    };
+
+    var i = 0;
+    req = store.openCursor();
+    req.onsuccess = function(evt) {
+      var cursor = evt.target.result;
+
+      // If the cursor is pointing at something, ask for the data
+      if (cursor) {
+        console.log("displayPubList cursor:", cursor);
+        req = store.get(cursor.key);
+        req.onsuccess = function (evt) {
+          var value = evt.target.result;
+          var list_item = $('<li>' +
+                            '[' + cursor.key + '] ' +
+                            '(biblioid: ' + value.biblioid + ') ' +
+                            value.title +
+                            '</li>');
+          if (value.year != null)
+            list_item.append(' - ' + value.year);
+
+          if (value.hasOwnProperty('blob') &&
+              typeof value.blob != 'undefined') {
+            var link = $('<a href="' + cursor.key + '">File</a>');
+            link.on('click', function() { return false; });
+            link.on('mouseenter', function(evt) {
+                      setInViewer(evt.target.getAttribute('href')); });
+            list_item.append(' / ');
+            list_item.append(link);
+          } else {
+            list_item.append(" / No attached file");
+          }
+          pub_list.append(list_item);
+        };
+
+        // Move on to the next object in store
+        cursor.continue();
+
+        // This counter serves only to create distinct ids
+        i++;
+      } else {
+        console.log("No more entries");
+      }
+    };
+  }
+
+  function newViewerFrame() {
+    var viewer = $('#pub-viewer');
+    viewer.empty();
+    var iframe = $('<iframe />');
+    viewer.append(iframe);
+    return iframe;
+  }
+
+  function setInViewer(key) {
+    console.log("setInViewer:", arguments);
+    key = Number(key);
+    if (key == current_view_pub_key)
+      return;
+
+    current_view_pub_key = key;
+
+    var store = getObjectStore(DB_STORE_NAME, 'readonly');
+    getBlob(key, store, function(blob) {
+      console.log("setInViewer blob:", blob);
+      var iframe = newViewerFrame();
+
+      // It is not possible to set a direct link to the
+      // blob to provide a mean to directly download it.
+      if (blob.type == 'text/html') {
+        var reader = new FileReader();
+        reader.onload = (function(evt) {
+          var html = evt.target.result;
+          iframe.load(function() {
+            $(this).contents().find('html').html(html);
+          });
+        });
+        reader.readAsText(blob);
+      } else if (blob.type.indexOf('image/') == 0) {
+        iframe.load(function() {
+          var img_id = 'image-' + key;
+          var img = $('<img id="' + img_id + '"/>');
+          $(this).contents().find('body').html(img);
+          var obj_url = window.URL.createObjectURL(blob);
+          $(this).contents().find('#' + img_id).attr('src', obj_url);
+          window.URL.revokeObjectURL(obj_url);
+        });
+      } else if (blob.type == 'application/pdf') {
+        $('*').css('cursor', 'wait');
+        var obj_url = window.URL.createObjectURL(blob);
+        iframe.load(function() {
+          $('*').css('cursor', 'auto');
+        });
+        iframe.attr('src', obj_url);
+        window.URL.revokeObjectURL(obj_url);
+      } else {
+        iframe.load(function() {
+          $(this).contents().find('body').html("No view available");
+        });
+      }
+
+    });
+  }
+
+  /**
+   * @param {string} biblioid
+   * @param {string} title
+   * @param {number} year
+   * @param {string} url the URL of the image to download and store in the local
+   *   IndexedDB database. The resource behind this URL is subjected to the
+   *   "Same origin policy", thus for this method to work, the URL must come from
+   *   the same origin as the web site/app this code is deployed on.
+   */
+  function addPublicationFromUrl(biblioid, title, year, url) {
+    console.log("addPublicationFromUrl:", arguments);
+
+    var xhr = new XMLHttpRequest();
+    xhr.open('GET', url, true);
+    // Setting the wanted responseType to "blob"
+    // http://www.w3.org/TR/XMLHttpRequest2/#the-response-attribute
+    xhr.responseType = 'blob';
+    xhr.onload = function (evt) {
+                           if (xhr.status == 200) {
+                             console.log("Blob retrieved");
+                             var blob = xhr.response;
+                             console.log("Blob:", blob);
+                             addPublication(biblioid, title, year, blob);
+                           } else {
+                             console.error("addPublicationFromUrl error:",
+                                           xhr.responseText, xhr.status);
+                           }
+                         };
+    xhr.send();
+
+    // We can't use jQuery here because as of jQuery 1.8.3 the new "blob"
+    // responseType is not handled.
+    // http://bugs.jquery.com/ticket/11461
+    // http://bugs.jquery.com/ticket/7248
+    // $.ajax({
+    //   url: url,
+    //   type: 'GET',
+    //   xhrFields: { responseType: 'blob' },
+    //   success: function(data, textStatus, jqXHR) {
+    //     console.log("Blob retrieved");
+    //     console.log("Blob:", data);
+    //     // addPublication(biblioid, title, year, data);
+    //   },
+    //   error: function(jqXHR, textStatus, errorThrown) {
+    //     console.error(errorThrown);
+    //     displayActionFailure("Error during blob retrieval");
+    //   }
+    // });
+  }
+
+  /**
+   * @param {string} biblioid
+   * @param {string} title
+   * @param {number} year
+   * @param {Blob=} blob
+   */
+  function addPublication(biblioid, title, year, blob) {
+    console.log("addPublication arguments:", arguments);
+    var obj = { biblioid: biblioid, title: title, year: year };
+    if (typeof blob != 'undefined')
+      obj.blob = blob;
+
+    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
+    var req;
+    try {
+      req = store.add(obj);
+    } catch (e) {
+      if (e.name == 'DataCloneError')
+        displayActionFailure("This engine doesn't know how to clone a Blob, " +
+                             "use Firefox");
+      throw e;
+    }
+    req.onsuccess = function (evt) {
+      console.log("Insertion in DB successful");
+      displayActionSuccess();
+      displayPubList(store);
+    };
+    req.onerror = function() {
+      console.error("addPublication error", this.error);
+      displayActionFailure(this.error);
+    };
+  }
+
+  /**
+   * @param {string} biblioid
+   */
+  function deletePublicationFromBib(biblioid) {
+    console.log("deletePublication:", arguments);
+    var store = getObjectStore(DB_STORE_NAME, 'readwrite');
+    var req = store.index('biblioid');
+    req.get(biblioid).onsuccess = function(evt) {
+      if (typeof evt.target.result == 'undefined') {
+        displayActionFailure("No matching record found");
+        return;
+      }
+      deletePublication(evt.target.result.id, store);
+    };
+    req.onerror = function (evt) {
+      console.error("deletePublicationFromBib:", evt.target.errorCode);
+    };
+  }
+
+  /**
+   * @param {number} key
+   * @param {IDBObjectStore=} store
+   */
+  function deletePublication(key, store) {
+    console.log("deletePublication:", arguments);
+
+    if (typeof store == 'undefined')
+      store = getObjectStore(DB_STORE_NAME, 'readwrite');
+
+    // As per spec http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation
+    // the result of the Object Store Deletion Operation algorithm is
+    // undefined, so it's not possible to know if some records were actually
+    // deleted by looking at the request result.
+    var req = store.get(key);
+    req.onsuccess = function(evt) {
+      var record = evt.target.result;
+      console.log("record:", record);
+      if (typeof record == 'undefined') {
+        displayActionFailure("No matching record found");
+        return;
+      }
+      // Warning: The exact same key used for creation needs to be passed for
+      // the deletion. If the key was a Number for creation, then it needs to
+      // be a Number for deletion.
+      req = store.delete(key);
+      req.onsuccess = function(evt) {
+        console.log("evt:", evt);
+        console.log("evt.target:", evt.target);
+        console.log("evt.target.result:", evt.target.result);
+        console.log("delete successful");
+        displayActionSuccess("Deletion successful");
+        displayPubList(store);
+      };
+      req.onerror = function (evt) {
+        console.error("deletePublication:", evt.target.errorCode);
+      };
+    };
+    req.onerror = function (evt) {
+      console.error("deletePublication:", evt.target.errorCode);
+      };
+  }
+
+  function displayActionSuccess(msg) {
+    msg = typeof msg != 'undefined' ? "Success: " + msg : "Success";
+    $('#msg').html('<span class="action-success">' + msg + '</span>');
+  }
+  function displayActionFailure(msg) {
+    msg = typeof msg != 'undefined' ? "Failure: " + msg : "Failure";
+    $('#msg').html('<span class="action-failure">' + msg + '</span>');
+  }
+  function resetActionStatus() {
+    console.log("resetActionStatus ...");
+    $('#msg').empty();
+    console.log("resetActionStatus DONE");
+  }
+
+  function addEventListeners() {
+    console.log("addEventListeners");
+
+    $('#register-form-reset').click(function(evt) {
+      resetActionStatus();
+    });
+
+    $('#add-button').click(function(evt) {
+      console.log("add ...");
+      var title = $('#pub-title').val();
+      var biblioid = $('#pub-biblioid').val();
+      if (!title || !biblioid) {
+        displayActionFailure("Required field(s) missing");
+        return;
+      }
+      var year = $('#pub-year').val();
+      if (year != '') {
+        // Better use Number.isInteger if the engine has EcmaScript 6
+        if (isNaN(year))  {
+          displayActionFailure("Invalid year");
+          return;
+        }
+        year = Number(year);
+      } else {
+        year = null;
+      }
+
+      var file_input = $('#pub-file');
+      var selected_file = file_input.get(0).files[0];
+      console.log("selected_file:", selected_file);
+      // Keeping a reference on how to reset the file input in the UI once we
+      // have its value, but instead of doing that we rather use a "reset" type
+      // input in the HTML form.
+      //file_input.val(null);
+      var file_url = $('#pub-file-url').val();
+      if (selected_file) {
+        addPublication(biblioid, title, year, selected_file);
+      } else if (file_url) {
+        addPublicationFromUrl(biblioid, title, year, file_url);
+      } else {
+        addPublication(biblioid, title, year);
+      }
+
+    });
+
+    $('#delete-button').click(function(evt) {
+      console.log("delete ...");
+      var biblioid = $('#pub-biblioid-to-delete').val();
+      var key = $('#key-to-delete').val();
+
+      if (biblioid != '') {
+        deletePublicationFromBib(biblioid);
+      } else if (key != '') {
+        // Better use Number.isInteger if the engine has EcmaScript 6
+        if (key == '' || isNaN(key))  {
+          displayActionFailure("Invalid key");
+          return;
+        }
+        key = Number(key);
+        deletePublication(key);
+      }
+    });
+
+    $('#clear-store-button').click(function(evt) {
+      clearObjectStore();
+    });
+
+    var search_button = $('#search-list-button');
+    search_button.click(function(evt) {
+      displayPubList();
+    });
+
+  }
+
+  openDb();
+  addEventListeners();
+
+})(); // Immediately-Invoked Function Expression (IIFE)
+
+ +

{{ LiveSampleLink('Full_IndexedDB_example', "Test the online live demo") }}

+ +

Ver também

+ +

Uma leitura adicional para você encontrar mais informações.

+ +

Refências

+ + + +

Guias e tutoriais

+ + diff --git a/files/pt-br/web/api/network_information_api/index.html b/files/pt-br/web/api/network_information_api/index.html new file mode 100644 index 0000000000..032fc54169 --- /dev/null +++ b/files/pt-br/web/api/network_information_api/index.html @@ -0,0 +1,56 @@ +--- +title: Network Information API +slug: WebAPI/Network_Information +translation_of: Web/API/Network_Information_API +--- +

{{ SeeCompatTable() }}

+ +

A API de Informações de Rede fornece informação sobre a conexão do sistema, assim como a banda atual do dispositivo do usuário ou qualquer conexão que seja medida. Essa pode também ser usada para selecionar conteúdo de alta ou baixa definição baseado na conexão do usuário. Toda a API consiste na adição da interface domxref("Connection") e uma única propriedade a interface {{domxref("Navigator")}}: {{domxref("Navigator.connection")}}.

+ +

Detectando mudanças de conexão

+ +

Este é um exemplo vê mudança na conexão do usuário. Essa é similar a como uma app pode alertar quando o usuário move de uma conexão de alto para baixo custo por exemplo, a fim de reduzir a demanda da banda para previnir que o usuário seja submetido a cargos substanciais.

+ +
var connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
+
+function updateConnectionStatus() {
+  alert("Connection bandwidth: " + connection.bandwidth + " MB/s");
+  if (connection.metered) {
+    alert("The connection is metered!");
+  }
+}
+
+connection.addEventListener("change", updateConnectionStatus);
+updateConnectionStatus();
+
+ +

Especificações

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('Network Information', '', 'Network Information API') }}{{ Spec2('Network Information') }}Initial specification
+ +

Compatibilidade com Navegadores

+ +

{{Page('/en-US/docs/Web/API/window.navigator.connection','Browser compatibility')}}

+ +

Veja também

+ + diff --git "a/files/pt-br/web/api/node/entendendo_o_uso_do_m\303\251todo_appendchild-javascript/index.html" "b/files/pt-br/web/api/node/entendendo_o_uso_do_m\303\251todo_appendchild-javascript/index.html" deleted file mode 100644 index a05abeae88..0000000000 --- "a/files/pt-br/web/api/node/entendendo_o_uso_do_m\303\251todo_appendchild-javascript/index.html" +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Entendendo o uso do método appendChild em javascript -slug: Web/API/Node/Entendendo_o_uso_do_método_AppendChild-javascript ---- -
{{ApiRef("DOM")}}
- -

Resumo

- -

Adiciona um nó ao final da lista de filhos de um nó pai especificado. Se o nó já existir no documento, ele é removido de seu nó pai atual antes de ser adicionado ao novo pai.

- -

Sintaxe

- -
var filho = elemento.appendChild(filho);
- - - -

Descrição

- -

O método appendChild devolve uma referência ao nó adicionado.

- -

Exemplo

- -
// Cria um novo elemento de parágrafo e adiciona-o ao final do documento
-var p = document.createElement("p");
-document.body.appendChild(p);
- -

Notas

- -

Se filho é uma referência a um nó existente no documento, appendChild vai movê-lo de sua posição atual para a nova posição (i.e, não é necessário remover o nó de seu pai atual antes de adicioná-lo a outro nó).

- -

Isso também significa que um nó não pode estar em dois lugares do documento ao mesmo tempo. Assim, se o nó já tem um pai, ele é primeiro removido para, só então, ser adicionado na nova posição.

- -

Você pode usar o método {{domxref("Node.cloneNode")}} para criar uma cópia do nó antes de adicioná-lo ao novo pai. (Note que cópias feitas com o método cloneNode não serão mantidas sincronizadas automaticamente)

- -

Este método não permite mover nós entre documentos diferentes. Se você quiser adicionar um nó de um documento diferente (por exemplo para mostrar o resultado de uma requisição AJAX), você precisa primeiro usar o método {{domxref("document.importNode")}}.

- -

appendChild() é um dos métodos fundamentais da programação para a web usando o DOM. O método appendChild() insere um novo nó na estrutura do DOM de um documento, e é a segunda parte do processo criar-e-adicionar tão importante na construção de páginas web programaticamente.

- -

Especificação

- - - -

Ver também

- - diff --git a/files/pt-br/web/api/node/innertext/index.html b/files/pt-br/web/api/node/innertext/index.html deleted file mode 100644 index 1ab5e81027..0000000000 --- a/files/pt-br/web/api/node/innertext/index.html +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Node.innerText -slug: Web/API/Node/innerText -translation_of: Web/API/HTMLElement/innerText ---- -
{{APIRef("DOM")}}
- -

Resumo

- -

Node.innerText é uma propriedade que representa o conteúdo textual "renderizado" de um nó e seus descendentes. Usada como getter, retorna de maneira aproximada o texto que o usuário obteria caso tivesse selecionado o conteúdo e copiado para a área de transferência. Este recurso fora introduzido originalmente pelo Internet Explorer, mas foi oficialmente especificado no padrão HTML apenas em 2016, sendo adotado por todos os principais navegadores a partir de então.

- -

{{domxref("Node.textContent")}} é uma alternativa similar, embora existam diferenças significativas entre as duas.

- -

Especificação

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'dom.html#the-innertext-idl-attribute', 'innerText')}}{{Spec2('HTML WHATWG')}}Introduzida, baseado no rascunho da especifição de innerText. Ver whatwg/html#465 e whatwg/compat#5 para histórico.
- -

Compatibilidade de navegadores

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - -
RecursoChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico4{{ CompatGeckoDesktop(45) }}69.6 (provavelmente antes)3
-
- -
- - - - - - - - - - - - - - - - - - - -
RecursoAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico2.3 (provavelmente antes){{ CompatGeckoMobile(45) }}10 (provavelmente antes)124.1 (provavelmente antes)
-
- -

Ver também

- - diff --git a/files/pt-br/web/api/notificacoes/index.html b/files/pt-br/web/api/notificacoes/index.html deleted file mode 100644 index 9103aac190..0000000000 --- a/files/pt-br/web/api/notificacoes/index.html +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: Notificações -slug: Web/API/notificacoes -tags: - - API - - Interface - - Notificações -translation_of: Web/API/Notification ---- -

{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}}

- -

A interface da API de Notificações é usada para configurar e exibir notificações  na área de trabalho do usuário. A aparência e algumas funcionalidades específicas das notificações variam entre as plataformas mas geralmente eles fornecem uma forma assíncrona de prover informações para o usuário.

- - -

Construtor

- -
-
{{domxref("Notification.Notification", "Notification()")}}
-
Cria uma nova instancia do objeto {{domxref('Notification')}}.
-
- -

Propriedades

- -

Propriedades estáticas

- -

Estas propriedades estão disponíveis apenas no próprio objeto  Notification.

- -
-
{{domxref("Notification.permission")}} {{readonlyinline}}
-
-
-
-
- -
-
Uma sequência de caracteres que representa a permissão atual para exibir notificações. Valor possíveis são: "denied" (o usuário se recusa a ter notificações exibidas), "granted" (o usuário aceita ter notificações exibidas) ou "default" (a escolha do usuário é desconhecido e, portanto, o navegador irá agir como se o valor foram negados).
-
-
-
- -

Propriedades da instância

- -

Estas propriedades estão disponíveis apenas em instâncias do objeto Notification.

- -
-
{{domxref("Notification.title")}} {{readonlyinline}}
-
Retorna o título da notificação conforme foi definido no parâmetro opções do construtor.
-
{{domxref("Notification.dir")}} {{readonlyinline}}
-
A direção do texto da notificação, conforme especificado no parâmetro opções do construtor.
-
{{domxref("Notification.lang")}} {{readonlyinline}}
-
-
-
O código de idioma da notificação, conforme especificado no parâmetro opções do construtor.
-
-
-
{{domxref("Notification.body")}} {{readonlyinline}}
-
O corpo(mensagem) da notificação, conforme especificado no parâmetro opções do construtor.
-
{{domxref("Notification.tag")}} {{readonlyinline}}
-
O ID da notificação (se houver), conforme especificado no parâmetro opções do construtor.
-
{{domxref("Notification.icon")}} {{readonlyinline}}
-
A URL da imagem usada como um ícone da notificação, conforme especificado no parâmetro opções do construtor.
-
{{domxref("Notification.data")}} {{readonlyinline}}
-
Retorna um clone estruturado de dados da notificação.
-
{{domxref("Notification.silent")}} {{readonlyinline}}
-
-
-
Especifica se a notificação deve ser silenciosa, ou seja, sons ou vibrações não devem ser emitidos, independentemente das configurações do dispositivo.
-
-
-
- -

Propriedades não suportadas

- -

As propriedades a seguir estão listados na especificação mais up-to-date, mas não são suportadas em quaisquer navegadores ainda. É aconselhável manter a verificação de volta regularmente para ver se o status destes actualiza, e deixe-nos saber se você encontrar qualquer informações desatualizadas.

- -
-
{{domxref("Notification.noscreen")}} {{readonlyinline}}
-
-
-
Especifica se o disparo notificação deve permitir que a tela do dispositivo ou não.
-
-
-
{{domxref("Notification.renotify")}} {{readonlyinline}}
-
-
-
Especifica se o usuário deve ser notificado após uma nova notificação substitui um antigo.
-
-
-
{{domxref("Notification.sound")}} {{readonlyinline}}
-
Especifica um recurso de som para reproduzir durante o disparo da notificação, em vez do som de notificação do sistema padrão.
-
{{domxref("Notification.sticky")}} {{readonlyinline}}
-
Especifica se a notificação deve ser "fixa", ou seja, não facilmente eliminável pelo usuário.
-
{{domxref("Notification.vibrate")}} {{readonlyinline}}
-
Especifica um padrão de vibração para dispositivos com hardware de vibração.
-
- -

Manipuladores de Eventos

- -
-
{{domxref("Notification.onclick")}}
-
O manipulador para o evento {{event("click")}} é acionado cada vez que o usuário clica sobre a notificação.
-
{{domxref("Notification.onerror")}}
-
O manipulador para o evento {{event("error")}} é acionado quando a notificação encontra um erro.
-
- -

Manipuladores Obsoletos

- -

Os seguintes manipuladores de eventos ainda são suportados, conforme listado na seção {{anch("browser compatibility")}}. Estes serão listados abaixo, mas não são listados na especificação atual. Saiba que eles são obsoletos, e pode parar de funcionar em versões futuras do navegador.

- -
-
{{domxref("Notification.onclose")}}
-
Manipulador do evento {{event("close")}} é acionado quando a notificação é fechada.
-
{{domxref("Notification.onshow")}}
-
Manipulador do evento {{event("show")}}. é acionado quando a notificação é exibida.
-
- -

Métodos

- -

Métodos Estáticos

- -

Estes métodos estão disponíveis apenas no próprio objeto Notification.

- -
-
{{domxref("Notification.requestPermission()")}}
-
-
-
Solicita a permissão do usuário para exibir notificações.
-
-
-
- -

Métodos de instância

- -

Estas propriedades estão disponíveis apenas no objeto Notification ou através do seu prototype. O objeto de notificação também herda a interface {{domxref("EventTarget")}}.

- -
-
{{domxref("Notification.close()")}}
-
Programaticamente fecha uma notificação.
-
- -

Exemplos

- -

Leve em conta este HTML básico:

- -
<button onclick="notifyMe()">Notifique me!</button>
- -

É possível enviar uma notificação da seguinte forma - aqui nós apresentamos um conjunto bastante detalhado e completo de código que você pode usar se você quiser verificar primeiro se as notificações são suportados, em seguida, verifique se a permissão foi concedida para a origem atual para enviar notificações, em seguida, solicitar permissão, se necessário, antes, em seguida, enviar uma notificação.

- -
function notifyMe() {
-  // Verifica se o browser suporta notificações
-  if (!("Notification" in window)) {
-    alert("Este browser não suporta notificações de Desktop");
-  }
-
-  // Let's check whether notification permissions have already been granted
-  else if (Notification.permission === "granted") {
-    // If it's okay let's create a notification
-    var notification = new Notification("Hi there!");
-  }
-
-  // Otherwise, we need to ask the user for permission
-  else if (Notification.permission !== 'denied') {
-    Notification.requestPermission(function (permission) {
-      // If the user accepts, let's create a notification
-      if (permission === "granted") {
-        var notification = new Notification("Hi there!");
-      }
-    });
-  }
-
-  // At last, if the user has denied notifications, and you
-  // want to be respectful there is no need to bother them any more.
-}
- -

{{EmbedLiveSample('Exemplo', '100%', 30)}}

- -

Em muitos casos, você não precisa estar presente detalhado. Por exemplo, na nosso Emogotchi demo (veja o código fonte), basta simlesmente executar {{domxref("Notification.requestPermission")}} independentemente de se certificar de que pode obter permissão para enviar notificações:

- -
Notification.requestPermission();
- -

Em seguida executar um simples spawnNotification() quando queremos disparar uma notificação — este é passado argumentos para especificar o, ícone corpo e título que queremos, então ele cria as opções necessárias objeto e dispara a notificação usando o construtor {{domxref("Notification.Notification","Notification()")}}.

- -
function spawnNotification(corpo,icone,titulo) {
-  var opcoes = {
-      body: corpo,
-      icon: icone
-  }
-  var n = new Notification(titulo,opcoes);
-}
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoEstadoComentário
{{SpecName('Web Notifications')}}{{Spec2('Web Notifications')}}Living standard
- -

Compatibilidade dos Navegadores

- - - -

{{Compat("api.Notification")}}

-

Veja também

- - diff --git a/files/pt-br/web/api/notification/index.html b/files/pt-br/web/api/notification/index.html new file mode 100644 index 0000000000..9103aac190 --- /dev/null +++ b/files/pt-br/web/api/notification/index.html @@ -0,0 +1,217 @@ +--- +title: Notificações +slug: Web/API/notificacoes +tags: + - API + - Interface + - Notificações +translation_of: Web/API/Notification +--- +

{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}}

+ +

A interface da API de Notificações é usada para configurar e exibir notificações  na área de trabalho do usuário. A aparência e algumas funcionalidades específicas das notificações variam entre as plataformas mas geralmente eles fornecem uma forma assíncrona de prover informações para o usuário.

+ + +

Construtor

+ +
+
{{domxref("Notification.Notification", "Notification()")}}
+
Cria uma nova instancia do objeto {{domxref('Notification')}}.
+
+ +

Propriedades

+ +

Propriedades estáticas

+ +

Estas propriedades estão disponíveis apenas no próprio objeto  Notification.

+ +
+
{{domxref("Notification.permission")}} {{readonlyinline}}
+
+
+
+
+ +
+
Uma sequência de caracteres que representa a permissão atual para exibir notificações. Valor possíveis são: "denied" (o usuário se recusa a ter notificações exibidas), "granted" (o usuário aceita ter notificações exibidas) ou "default" (a escolha do usuário é desconhecido e, portanto, o navegador irá agir como se o valor foram negados).
+
+
+
+ +

Propriedades da instância

+ +

Estas propriedades estão disponíveis apenas em instâncias do objeto Notification.

+ +
+
{{domxref("Notification.title")}} {{readonlyinline}}
+
Retorna o título da notificação conforme foi definido no parâmetro opções do construtor.
+
{{domxref("Notification.dir")}} {{readonlyinline}}
+
A direção do texto da notificação, conforme especificado no parâmetro opções do construtor.
+
{{domxref("Notification.lang")}} {{readonlyinline}}
+
+
+
O código de idioma da notificação, conforme especificado no parâmetro opções do construtor.
+
+
+
{{domxref("Notification.body")}} {{readonlyinline}}
+
O corpo(mensagem) da notificação, conforme especificado no parâmetro opções do construtor.
+
{{domxref("Notification.tag")}} {{readonlyinline}}
+
O ID da notificação (se houver), conforme especificado no parâmetro opções do construtor.
+
{{domxref("Notification.icon")}} {{readonlyinline}}
+
A URL da imagem usada como um ícone da notificação, conforme especificado no parâmetro opções do construtor.
+
{{domxref("Notification.data")}} {{readonlyinline}}
+
Retorna um clone estruturado de dados da notificação.
+
{{domxref("Notification.silent")}} {{readonlyinline}}
+
+
+
Especifica se a notificação deve ser silenciosa, ou seja, sons ou vibrações não devem ser emitidos, independentemente das configurações do dispositivo.
+
+
+
+ +

Propriedades não suportadas

+ +

As propriedades a seguir estão listados na especificação mais up-to-date, mas não são suportadas em quaisquer navegadores ainda. É aconselhável manter a verificação de volta regularmente para ver se o status destes actualiza, e deixe-nos saber se você encontrar qualquer informações desatualizadas.

+ +
+
{{domxref("Notification.noscreen")}} {{readonlyinline}}
+
+
+
Especifica se o disparo notificação deve permitir que a tela do dispositivo ou não.
+
+
+
{{domxref("Notification.renotify")}} {{readonlyinline}}
+
+
+
Especifica se o usuário deve ser notificado após uma nova notificação substitui um antigo.
+
+
+
{{domxref("Notification.sound")}} {{readonlyinline}}
+
Especifica um recurso de som para reproduzir durante o disparo da notificação, em vez do som de notificação do sistema padrão.
+
{{domxref("Notification.sticky")}} {{readonlyinline}}
+
Especifica se a notificação deve ser "fixa", ou seja, não facilmente eliminável pelo usuário.
+
{{domxref("Notification.vibrate")}} {{readonlyinline}}
+
Especifica um padrão de vibração para dispositivos com hardware de vibração.
+
+ +

Manipuladores de Eventos

+ +
+
{{domxref("Notification.onclick")}}
+
O manipulador para o evento {{event("click")}} é acionado cada vez que o usuário clica sobre a notificação.
+
{{domxref("Notification.onerror")}}
+
O manipulador para o evento {{event("error")}} é acionado quando a notificação encontra um erro.
+
+ +

Manipuladores Obsoletos

+ +

Os seguintes manipuladores de eventos ainda são suportados, conforme listado na seção {{anch("browser compatibility")}}. Estes serão listados abaixo, mas não são listados na especificação atual. Saiba que eles são obsoletos, e pode parar de funcionar em versões futuras do navegador.

+ +
+
{{domxref("Notification.onclose")}}
+
Manipulador do evento {{event("close")}} é acionado quando a notificação é fechada.
+
{{domxref("Notification.onshow")}}
+
Manipulador do evento {{event("show")}}. é acionado quando a notificação é exibida.
+
+ +

Métodos

+ +

Métodos Estáticos

+ +

Estes métodos estão disponíveis apenas no próprio objeto Notification.

+ +
+
{{domxref("Notification.requestPermission()")}}
+
+
+
Solicita a permissão do usuário para exibir notificações.
+
+
+
+ +

Métodos de instância

+ +

Estas propriedades estão disponíveis apenas no objeto Notification ou através do seu prototype. O objeto de notificação também herda a interface {{domxref("EventTarget")}}.

+ +
+
{{domxref("Notification.close()")}}
+
Programaticamente fecha uma notificação.
+
+ +

Exemplos

+ +

Leve em conta este HTML básico:

+ +
<button onclick="notifyMe()">Notifique me!</button>
+ +

É possível enviar uma notificação da seguinte forma - aqui nós apresentamos um conjunto bastante detalhado e completo de código que você pode usar se você quiser verificar primeiro se as notificações são suportados, em seguida, verifique se a permissão foi concedida para a origem atual para enviar notificações, em seguida, solicitar permissão, se necessário, antes, em seguida, enviar uma notificação.

+ +
function notifyMe() {
+  // Verifica se o browser suporta notificações
+  if (!("Notification" in window)) {
+    alert("Este browser não suporta notificações de Desktop");
+  }
+
+  // Let's check whether notification permissions have already been granted
+  else if (Notification.permission === "granted") {
+    // If it's okay let's create a notification
+    var notification = new Notification("Hi there!");
+  }
+
+  // Otherwise, we need to ask the user for permission
+  else if (Notification.permission !== 'denied') {
+    Notification.requestPermission(function (permission) {
+      // If the user accepts, let's create a notification
+      if (permission === "granted") {
+        var notification = new Notification("Hi there!");
+      }
+    });
+  }
+
+  // At last, if the user has denied notifications, and you
+  // want to be respectful there is no need to bother them any more.
+}
+ +

{{EmbedLiveSample('Exemplo', '100%', 30)}}

+ +

Em muitos casos, você não precisa estar presente detalhado. Por exemplo, na nosso Emogotchi demo (veja o código fonte), basta simlesmente executar {{domxref("Notification.requestPermission")}} independentemente de se certificar de que pode obter permissão para enviar notificações:

+ +
Notification.requestPermission();
+ +

Em seguida executar um simples spawnNotification() quando queremos disparar uma notificação — este é passado argumentos para especificar o, ícone corpo e título que queremos, então ele cria as opções necessárias objeto e dispara a notificação usando o construtor {{domxref("Notification.Notification","Notification()")}}.

+ +
function spawnNotification(corpo,icone,titulo) {
+  var opcoes = {
+      body: corpo,
+      icon: icone
+  }
+  var n = new Notification(titulo,opcoes);
+}
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoEstadoComentário
{{SpecName('Web Notifications')}}{{Spec2('Web Notifications')}}Living standard
+ +

Compatibilidade dos Navegadores

+ + + +

{{Compat("api.Notification")}}

+

Veja também

+ + diff --git a/files/pt-br/web/api/performance_api/index.html b/files/pt-br/web/api/performance_api/index.html new file mode 100644 index 0000000000..1b6997e293 --- /dev/null +++ b/files/pt-br/web/api/performance_api/index.html @@ -0,0 +1,138 @@ +--- +title: API de Desempenho +slug: Web/API/API_de_Desempenho +translation_of: Web/API/Performance_API +--- +
{{DefaultAPISidebar("High Resolution Time")}}
+ +

The High Resolution Time standard defines a {{domxref("Performance")}} interface that supports client-side latency measurements within applications. The {{domxref("Performance")}} interfaces are considered high resolution because they are accurate to a thousandth of a millisecond (subject to hardware or software constraints). The interfaces support a number of use cases including calculating frame-rates (potentially important in animations) and benchmarking (such as the time to load a resource).

+ +

Since a platform's system clock is subject to various skews (such as NTP adjustments), the interfaces support a monotonic clock i.e. a clock that is always increasing. As such, the Performance API defines a {{domxref("DOMHighResTimeStamp")}} type rather than using the {{jsxref("Date.now","Date.now()")}} interface.

+ +

DOMHighResTimeStamp

+ +

The {{domxref("DOMHighResTimeStamp")}} type, as its name implies, represents a high resolution point in time. This type is a double and is used by the performance interfaces. The value could be a discrete point in time or the difference in time between two discrete points in time.

+ +

The unit of DOMHighResTimeStamp is milliseconds and should be accurate to 5 µs (microseconds). However, If the browser is unable to provide a time value accurate to 5 microseconds (because, for example, due to hardware or software constraints), the browser can represent the value as a time in milliseconds accurate to a millisecond.

+ +

Methods

+ +

The {{domxref("Performance")}} interface has two methods. The {{domxref("Performance.now","now()")}} method returns a {{domxref("DOMHighResTimeStamp")}} whose value that depends on the {{domxref("PerformanceTiming.navigationStart","navigation start")}} and scope. If the scope is a window, the value is the time the browser context was created and if the scope is a {{domxref("Worker","worker")}}, the value is the time the worker was created.

+ +

The {{domxref("Performance.toJSON","toJSON()")}} method returns a serialization of the {{domxref("Performance")}} object, for those attributes that can be serialized.

+ +

Properties

+ +

The {{domxref("Performance")}} interface has two properties. The {{domxref("Performance.timing","timing")}} property returns a {{domxref("PerformanceTiming")}} object containing latency-related performance information such as the start of navigation time, start and end times for redirects, start and end times for responses, etc.

+ +

The {{domxref("Performance.navigation","navigation")}} property returns a {{domxref("PerformanceNavigation")}} object representing the type of navigation that occurs in the given browsing context, such as the page was navigated to from history, the page was navigated to by following a link, etc.

+ +

Interfaces

+ +
+
{{domxref('Performance')}}
+
Provides methods and properties containing timing-related performance information for the given page.
+
{{domxref('PerformanceEntry')}}
+
Provides methods and properties the encapsulate a single performance metric that is part of the performance timeline.
+
{{domxref('PerformanceFrameTiming')}}
+
Provides methods and properties containing frame timing data about the browser's event loop.
+
{{domxref('PerformanceMark')}}
+
An abstract interface for performance entries with an entry type of "mark". Entries of this type are created by calling performance.mark() to add a named DOMHighResTimeStamp (the mark) to the browser's performance timeline.
+
{{domxref('PerformanceMeasure')}}
+
An abstract interface for performance entries with an entry type of "measure". Entries of this type are created by calling performance.measure() to add a namedDOMHighResTimeStamp (the measure) between two marks to the browser's performance timeline.
+
{{domxref('PerformanceNavigationTiming')}}
+
Provides methods and properties to store and retrieve high resolution timestamps or metrics regarding the browser's document navigation events.
+
{{domxref('PerformanceObserver')}}
+
Provides methods and properties used to observe performance measurement events and be notified of new performance entries as they are recorded in the browser's performance timeline.
+
{{domxref('PerformanceResourceTiming')}}
+
Provides methods and properties for retrieving and analyzing detailed network timing data regarding the loading of an application's resources.
+
+ +

Specifications

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('Highres Time')}}{{Spec2('Highres Time')}}Initial definition.
{{SpecName('Highres Time Level 2')}}{{Spec2('Highres Time Level 2')}}Adds performance attribute on Window and WorkerGlobalScope.
{{SpecName('Highres Time Level 3')}}{{Spec2('Highres Time Level 3')}}Add timeOrigin property to Performance interface.
{{SpecName('Frame Timing')}}{{Spec2('Frame Timing')}}Adds PerformanceFrameTiming interface.
{{SpecName('Navigation Timing')}}{{Spec2('Navigation Timing')}}Adds the PerformanceTiming and PerformanceNavigation interfaces. Adds timing and navigation properties to the Performance interface.
{{SpecName('Navigation Timing Level 2')}}{{Spec2('Navigation Timing Level 2')}}Adds the PerformanceNavigationTiming interface. Obsolete's the the PerformanceTiming interface, the PerformanceNavigation interface, as well as the timing and navigation properties to the Performance interface.
{{SpecName('Performance Timeline')}}{{Spec2('Performance Timeline')}}Adds the PerformanceEntry interface, the PerformanceEntryList type, as well as the getEntries(), getEntriesByType(), and getEntriesByName() methods on the Performance interface.
{{SpecName('Performance Timeline Level 2')}}{{Spec2('Performance Timeline Level 2')}}Adds serializer to the PerformanceEntry interface as well as adding the PerformanceObserver interface and callback
{{SpecName('Resource Timing')}}{{Spec2('Resource Timing')}}Adds the PerformanceResourceTiming interface. Adds the clearResourceTimings() method, the setResourceTimingBufferSize() method, and the onresourcetimingbufferfull event handler to the Performance interface. Also adds the Timing-Allow-Origin response header.
{{SpecName('Resource Timing 2')}}{{Spec2('Resource Timing 2')}}Adds the nextHopProtocol, workerStart, transferSize, encodedBodySize, and decodedBodySize properties to the PerformanceResourceTiming interface.
{{SpecName('Resource Timing 3')}}{{Spec2('Resource Timing 3')}}
{{SpecName('User Timing')}}{{Spec2('User Timing')}}Adds mark(), clearMarks(), measure() and clearMeasures() methods to the Performance interface. Adds the PerformanceMark and PeformanceMeasure interfaces.
{{SpecName('User Timing Level 2')}}{{Spec2('User Timing Level 2')}}
+ +

Implementation status

+ +

As shown in the {{domxref("Performance")}} interface's Browser Compatibility table, most of these interfaces are broadly implemented by desktop browsers.

+ +

To test your browser's support for the {{domxref("Performance")}} interface, run the perf-api-support application.

+ +

See Also

+ + diff --git a/files/pt-br/web/api/push_api/best_practices/index.html b/files/pt-br/web/api/push_api/best_practices/index.html new file mode 100644 index 0000000000..9b0fafd2b7 --- /dev/null +++ b/files/pt-br/web/api/push_api/best_practices/index.html @@ -0,0 +1,73 @@ +--- +title: Melhores práticas +slug: Web/API/API_Push/Best_Practices +tags: + - Apps + - Iniciante + - Melhores Práticas + - Notificações + - Push API + - Usabilidade +translation_of: Web/API/Push_API/Best_Practices +--- +

{{draft}}

+ +

Este artigo proporciona um compilado das melhores práticas a serem usadas enquanto estiver desenvolvendo websites e aplicações que usem Notificações push para engajamento de usuários.

+ +
+

“Se feito de uma maneira correta, as notificações ajudam os usuarios, se não, so irritam.” — Conversa entre dois desenvolvedores a respeito da etica das notificações push.

+
+ +

Visão Geral do web push notifications

+ +

Notificações Web Push (criadas usando uma combinação das APIs de Notificações, Push e Service Worker) são parte de um movimento crescente em que desenvolvedores e comerciantes estão usando para conseguir atenção para seus sites. Uma procura rápida pelo termo "web push notifications", irá resultar em vários artigos, em que especialistas em marketing que acreditam que deve-se usar a API de Push para recapturar a atenção de pessoas que saíram de seu site para que possam terminar o que estavam fazendo, por exemplo, uma compra, ou então enviar as últimas notícias e até recomendação de produtos

+ +

O Lado obscuro

+ +

Essa novidade oferece uma oportunidade nova e inexplorada para sites empresariais chegarem aos seus consumidores finais. Seu usuário trocou de aba para responder um email? Consiga-os de volta com uma oferta que expira em um tempo limitado ou oferecendo frete grátis, o qual ele não vai poder ignorar

+ +

Mas sério, qual o melhor uso das notificações push? Ou é apenas uma nova interação dos bons e velhos pop-ups?

+ +
+

“O envio de notificações push não corre o risco de acabar na pasta de spam. Nem pode ser bloqueado por bloqueadores de anúncios. Ele aparece na sua área de trabalho, mesmo quando o site está fechado. No celular, ele aparece na barra de notificações, assim como as notificações por push do aplicativo, mesmo quando o navegador não está em execução.” — um site de marketing anonimo

+
+ +

Bons usos das notificações

+ +

Mas há também um lado bom no que se diz respeito as notificações por push. Digamos que você e sua equipe usem normalmente um programa de bate-papo para se comunicar, mas hoje você está feliz e saltitante trabalhando e surge um problema. Digamos que seu gerente tenha encontrado um problema nas aprovações e queira receber seu feedback sobre algo antes que ela prossiga.

+ +

Neste documento, falaremos sobre o uso correto das notificações por push da web. Às vezes, eles podem eliminar a frustração e o aborrecimento e, às vezes, causá-los. Cabe a você, como desenvolvedor, fazer recomendações (e decisões) sábias sobre o uso de notificações por push.

+ +

O que se espera alcançar com as notificações push?

+ +

Como tudo, com grande poder vem uma grande responsabilidade. Toda notificação push devem ser úteis e sensíveis ao tempo, o usuário sempre deve fornecer a permissão antes de recebe-la primeiro e deve-se oferecer uma maneira fácil de optar por não receber mais no futuro.

+ +

Temos que responder algumas perguntas basicas para verificar se as notificações são necessarias:

+ + + +

Além da questão de saber se uma notificação por push é necessária, existem muitas variedades de notificações por push, variando de casual e efêmera a persistente e exigente.

+ +

Aconselhamos que você use as notificações que exigem uma interação de forma conciente e com moderação, pois estas podem irritar seu usuario e afasta-lo. Suas notificações devem ser acolhedoras, não hostis.

+ +

Gerando confiança

+ +

Alguns estudos mostraram que até 60% das notificações por push não chegam ao usuário final. Permitir que seu usuario receba notificações por push em tempo real exige confiança, por parte do aplicativo. Você pode criar confiança ao ter um site bem projetado que forneça um bom conteúdo e que mostre respeito pelo usuário alem de um valor claro para que o usuario aceite as notificações push.

+ +

Mitigações dos navegadores

+ +

Por causa dos abusos da utilização das notificações por push no passado, os desenvolvedores de navegadores começaram a implementar estratégias para ajudar a mitigar esse problema. Por exemplo, o Safari 12.1 agora exige - e outros navegadores já o fazem ou estão planejando[1] fazer—que o usuário interaja com a página de alguma forma antes que ela possa solicitar permissão para executar notificações por push, assim como já acontece com os popups. Isso pelo menos impede que o usuário receba espontaneamente essa pergunta em páginas da Web que apenas olharam de uma só vez, raramente ou nunca mais.

+ +

[1] No caso do Firefox, veja {{bug(1524619)}}, podemos observar que Firefox 68 implementa isso, desabilitado por padrão, usando a preferência dom.webnotifications.requireuserinteraction.

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/push_api/index.html b/files/pt-br/web/api/push_api/index.html new file mode 100644 index 0000000000..563b711cd8 --- /dev/null +++ b/files/pt-br/web/api/push_api/index.html @@ -0,0 +1,172 @@ +--- +title: API Push +slug: Web/API/API_Push +tags: + - API + - Experimental + - Notificações + - Push + - Referencia + - Service Workers +translation_of: Web/API/Push_API +--- +
{{DefaultAPISidebar("Push API")}}{{SeeCompatTable}}
+ +

A API Push torna possível que aplicações web recebam mensagens enviadas a elas de um servidor, indepententemente de aplicação estar ou não em primeiro plano, ou até mesmo carregada, em um agente de usuário. Isso permite que desenvolvedores entreguem notificações e atualizações assíncronas a usuários que optarem por elas, resultando num melhor engajamento com conteúdo novo oportuno.

+ +
+

Nota: Esta documentação cobre a especificação W3C da API Push; se você procura pela documentação do sistema de notificação proprietária do mecanismo push, veja Simple Push.

+
+ +

Conceitos e uso de Push

+ +

Para uma aplicação receber mensagens push, ela precisa ter um service worker ativo. Quando o service worker está ativo, ele pode se inscrever para utilizar notificações push {{domxref("PushManager.subscribe()")}}.

+ +

O resultado de {{domxref("PushSubscription")}} inclui toda informação que a aplicação precisa para receber uma mensagem push: um endpoint e a chave encriptada necessária para o envio de dados.

+ +

O service worker será iniciado conforme o necessário para lidar com as mensagens recebidas, que são entregues ao manipulador de evento {{domxref("ServiceWorkerGlobalScope.onpush")}} . Isto permite que a aplicação reaja a cada mensagem recebida, por exemplo para exibir a notificação ao usuário (usando {{domxref("ServiceWorkerRegistration.showNotification()")}}.)

+ +

Cada assinatura é única para um service worker.  O endpoint para a assinatura é uma capability URL única: o conhecimento do endpoint é tudo que é necessário para enviar uma mensagem para sua aplicação. A URL do endpoint precisa ser mantida em segredo, ou outras aplicações estranhas poderão enviar mensagens push para a sua aplicação.

+ +

A ativação de um service worker para entregar mensagens push pode resultar em um aumento de uso de recursos, particularmente de bateria. Diferentes navegadores tem diferentes formas para lidar com isso — atualmente não existe uma forma padrão. Firefox permite um número limitado (cota) de mensagens push para serem enviadas para uma aplicação, embora as mensagens Push que gerem notificações são isentas deste limite.  O limite é atualizado a cada site visitado. Numa comparação, Chrome não aplica nenhum limite, mas requer que cada mensagem push exiba uma notificação.

+ +
+

Nota: A partir do Gecko 44, a cota permitida de mensagens push por aplicação não é incrementada quando uma nova notificação é disparada quando outra está visível, por um período de três segundos. Isso lida com casos em que várias notificações são recebidas ao mesmo tempo, mas nem todas estão visíveis.

+
+ +
+

Nota: Chrome atualmente requer que você crie um projeto no Google Cloud Messaging para enviar mensagens push e use um número do projeto e chave da API para o envio de notificações push. Isto também requer um app manifest com alguns parâmetros especiais para usar o serviço. Essa restrição deverá ser removida no futuro.

+
+ +

Interfaces

+ +
+
{{domxref("PushEvent")}}
+
Representa uma ação push enviada para o global scope de um {{domxref("ServiceWorker")}}. Ele contém informações enviadas de uma aplicação para um {{domxref("PushSubscription")}}.
+
{{domxref("PushManager")}}
+
Fornece uma forma de receber notificações de servidor third-party bem como solicitar URL para notificações push. Essa interface substitui a funcionalidade oferecida que está obsoleta {{domxref("PushRegistrationManager")}} interface.
+
{{domxref("PushMessageData")}}
+
Fornece acesso aos dados push enviados por um servidor, e inclui métodos para manipular os dados recebidos.
+
{{domxref("PushSubscription")}}
+
Fornece a URL de assinatura do endpoint e permite o cancelamento da assinatura de um serviço push.
+
+ +

Service worker additions

+ +

As seguintes informações adicionais para a Service Worker API foram especificadas na Push API spec, para fornecer um ponto de entrada para usar mensagens Push, e para monitorar e responder os eventos de envio e assinatura.

+ +
+
{{domxref("ServiceWorkerRegistration.pushManager")}} {{readonlyinline}}
+
Retorna uma referência para a interface {{domxref("PushManager")}} para administrar assinaturas push incluindo subscrever, obter uma assinatura ativa e acessar o status de permissão de envio. Este é o ponto de entrada para usar mensagens Push.
+
{{domxref("ServiceWorkerGlobalScope.onpush")}}
+
Um manipulador de eventos disparado sempre que um evento  {{Event("push")}} ocorre; isto é, sempre que uma mensagem do servidor de envio for recebida.
+
{{domxref("ServiceWorkerGlobalScope.onpushsubscriptionchange")}}
+
Um manipulador de eventos disparado sempre que um evento  {{Event("pushsubscriptionchange")}} ocorre; por exemplo, quando uma assinatura push está inválida, ou está prestes a ser invalidada (ex. quando um serviço push service define um tempo de expiração.)
+
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName("Push API")}}{{Spec2("Push API")}}Definição Inicial
+ +

Compatibilidade em Browsers

+ +
{{CompatibilityTable}}
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
FuncionalidadeChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Suporte básico{{CompatChrome(42.0)}}{{CompatGeckoDesktop(44.0)}}[1]{{CompatNo}}[2]{{CompatUnknown}}{{CompatUnknown}}
{{domxref("PushEvent.data")}},
+ {{domxref("PushMessageData")}}		{{CompatNo}}{{CompatGeckoDesktop(44.0)}}{{CompatNo}}{{CompatNo}}{{CompatNo}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FuncionalidadeAndroidAndroid WebviewFirefox Mobile (Gecko)Firefox OSIE MobileOpera MobileSafari MobileChrome for Android
Suporte básico{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatUnknown}}[2]{{CompatUnknown}}{{CompatUnknown}}{{CompatChrome(42.0)}}
{{domxref("PushEvent.data")}},
+ {{domxref("PushMessageData")}}		{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}{{CompatNo}}
+
+ +

[1] Atualmente disponível apenas nas versões desktop do Firefox; ainda, mensagens push são encaminhadas apenas quando o Firefox está em execução.

+ +

[2] Ainda não implementado. Veja Microsoft Edge status information.

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/randomsource/getrandomvalues/index.html b/files/pt-br/web/api/randomsource/getrandomvalues/index.html deleted file mode 100644 index 7e54e933ed..0000000000 --- a/files/pt-br/web/api/randomsource/getrandomvalues/index.html +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: RandomSource.getRandomValues() -slug: Web/API/RandomSource/getRandomValues -translation_of: Web/API/Crypto/getRandomValues ---- -

{{APIRef("Web Crypto API")}}

- -

O método RandomSource.getRandomValues() permite que você obtenha valores criptográficos randômicos. O array passado como parametro é preenchido com números randômicos (randômicos no sentido criptográfico).

- -

Para garantir performance suficiente, as implementações não estão usando um gerador de número randômico de verdade, mas estão usando um gerador de número pseudo-randômico alimentado com um valor com {{Glossary("entropia")}} suficiente. Os PRNG (pseudo-random number generator - gerador de número pseudo-randômico) usados diferem de uma implementação para a outra, mas são adequadas para usos criptográficos. As implementações precisam ter um valor de alimentação com entropia suficiente, como uma fonte de entropia a nível de sistema.

- -

Sintaxe

- -
cryptoObj.getRandomValues(typedArray);
- -

Parâmetros

- -
-
typedArray
-
É uma {{jsxref("TypedArray")}} de números inteiros, que pode ser {{jsxref("Int8Array")}}, {{jsxref("Uint8Array")}}, {{jsxref("Uint16Array")}}, {{jsxref("Int32Array")}}, ou {{jsxref("Uint32Array")}}. Todos os elementos no array serão sobrescristos com números randômicos.
-
- -

Exceções

- - - -

Exemplo

- -
/* assumindo que window.crypto.getRandomValues está disponível */
-
-var array = new Uint32Array(10);
-window.crypto.getRandomValues(array);
-
-console.log("Seus números da sorte são:");
-for (var i = 0; i < array.length; i++) {
-    console.log(array[i]);
-}
-
- -

Especificação

- - - - - - - - - - - - - - -
EspecificaçãoEstadoComentário
{{SpecName('Web Crypto API', '#RandomSource-method-getRandomValues')}}{{Spec2('Web Crypto API')}}Definição inicial
- - - -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support11.0 {{ webkitbug("22049") }}21.011.015.03.1
-
- -
- - - - - - - - - - - - - - - - - - - - - -
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatNo() }}23.021.011.0{{ CompatNo() }}6
-
- -

Veja também

- - diff --git a/files/pt-br/web/api/randomsource/index.html b/files/pt-br/web/api/randomsource/index.html deleted file mode 100644 index e0dbd0a970..0000000000 --- a/files/pt-br/web/api/randomsource/index.html +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: RandomSource -slug: Web/API/RandomSource -tags: - - API - - Interface - - RandomSource - - Referencia - - Web Crypto API -translation_of: Web/API/Crypto/getRandomValues -translation_of_original: Web/API/RandomSource ---- -

{{APIRef("Web Crypto API")}}

- -

RandomSource representa uma fonte criptografada segura de números aleatórios. É disponível via objeto {{domxref("Crypto")}} do objeto global: {{domxref("Window.crypto")}} em páginas Web, {{domxref("WorkerGlobalScope.crypto")}} em trabalhadores.

- -

RandomSource não é uma interface e nenhum objeto deste tipo pode ser criado.

- -

Propriedades

- -

RandomSource não define ou herda nenhuma propriedade.

- -
-
- -

Métodos

- -
-
{{ domxref("RandomSource.getRandomValues()") }}
-
Completa o {{ domxref("ArrayBufferView") }} com valores aleatoriamente criptografados.
-
- -

Especificação

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('Web Crypto API', '#dfn-RandomSource')}}{{Spec2('Web Crypto API')}}Definição inicial.
- -

Compatibilidade de Browser

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - -
CaracterísticaChromeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico11.0 {{ webkitbug("22049") }}{{CompatGeckoDesktop(21)}} [1]11.015.03.1
-
- -
- - - - - - - - - - - - - - - - - - - - - -
CaracterísticaAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{ CompatNo() }}23{{CompatGeckoMobile(21)}}{{ CompatNo() }}{{ CompatNo() }}6
-
- -

[1] Apesar da RandomSource estar disponível apenas a partir da versão Firefox 26, ela já estava implementada na versão Firefox 21.

- -

Veja também

- - diff --git a/files/pt-br/web/api/selection/index.html b/files/pt-br/web/api/selection/index.html new file mode 100644 index 0000000000..9cac677942 --- /dev/null +++ b/files/pt-br/web/api/selection/index.html @@ -0,0 +1,206 @@ +--- +title: Seleção +slug: Web/API/Seleção +tags: + - API + - Experimental + - Interface + - Referencia + - Seleção +translation_of: Web/API/Selection +--- +
{{ ApiRef("DOM") }}{{SeeCompatTable}}
+ +

Um objeto Selection representa um intervalo do texto selecionado pelo usuário ou a posição atual do cursor. Para obter o objeto Selection para inspecionar ou modificar, use {{DOMxRef("Window.getSelection()")}}.

+ +

O usuário pode fazer a seleção da esquerda para a direita (na orientação do documento) ou da direita para a esquerta (orientação inversa do documento). O atributo anchor (âncora) é onde o usuário iniciou a seleção e o atributo focus (foco) é onde o usuário terminou a seleção. Se você fizer a seleção utilizando um mouse no desktop, o anchor é definido onde você pressionou o botão do mouse e o focus é definido onde você soltou o botão do mouse. Anchor e focus não devem ser confundidos com a posição inicial e final da seleção, pois o anchor pode ser definido antes do focus ou vice versa, dependendo da direção em que você fez sua seleção.

+ +

Propriedades

+ +
+
{{DOMxRef("Selection.anchorNode")}}{{ReadOnlyInline}}
+
Retorna o {{DOMxRef("Node")}} onde a seleção começou.
+
{{DOMxRef("Selection.anchorOffset")}}{{ReadOnlyInline}}
+
Retorna um número representando o deslocamento do anchor dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o anchor (clique inicial da seleção). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o anchor.
+
{{DOMxRef("Selection.focusNode")}}{{ReadOnlyInline}}
+
Retorna o {{DOMxRef("Node")}} onde a seleção termina.
+
{{DOMxRef("Selection.focusOffset")}}{{ReadOnlyInline}}
+
Retorna um número representando o deslocamento do focus dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o focus (posição onde o mouse foi solto). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o focus.
+
{{DOMxRef("Selection.isCollapsed")}}{{ReadOnlyInline}}
+
Retorna um valor booleano indicando se o início e o final da seleção são a mesma posição, ou seja, começou e terminou no mesmo lugar.
+
{{DOMxRef("Selection.rangeCount")}}{{ReadOnlyInline}}
+
Retorna no número de intervalos da seleção.
+
{{DOMxRef("Selection.type")}}{{ReadOnlyInline}}
+
Retorna um {{DOMxRef("DOMString")}} descrevento o tipo da seleção atual.
+
+ +

Métodos

+ +
+
{{DOMxRef("Selection.addRange()")}}
+
Um objeto {{DOMxRef("Range")}} que será adicionado na seleção.
+
{{DOMxRef("Selection.collapse()")}}
+
Colapsa a seleção atual em um único ponto.
+
{{DOMxRef("Selection.collapseToEnd()")}}
+
Colapsa a seleção para o final do último intervalo na seleção.
+
{{DOMxRef("Selection.collapseToStart()")}}
+
Colapsa a seleção para o início do primeiro intervalo na seleção.
+
{{DOMxRef("Selection.containsNode()")}}
+
Indica se um certo nó é parte da seleção.
+
{{DOMxRef("Selection.deleteFromDocument()")}}
+
Apaga o conteúdo da seleção do documento.
+
{{DOMxRef("Selection.empty()")}}
+
Remove todos os intervalos da seleção. Este é um apelido para removeAllRanges() — Veja {{DOMxRef("Selection.removeAllRanges()")}} para mais detalhes.
+
{{DOMxRef("Selection.extend()")}}
+
Move o focus (final da seleção) para um ponto específico.
+
{{DOMxRef("Selection.getRangeAt()")}}
+
Retorna um objeto {{DOMxRef("Range")}} represetando um dos intervalos atualmente selecionados.
+
{{DOMxRef("Selection.modify()")}}{{Non-standard_Inline}}
+
Altera a seleção atual.
+
{{DOMxRef("Selection.removeRange()")}}
+
Remove um intervalo da seleção.
+
{{DOMxRef("Selection.removeAllRanges()")}}
+
Remove todos os intervalos da seleção.
+
{{DOMxRef("Selection.selectAllChildren()")}}
+
Adiciona todos os filhos do nó especificado para a seleção.
+
{{DOMxRef("Selection.setBaseAndExtent()")}}
+
Define que a seleção será um intervalo incluindo todos ou partes dos dois nós DOM especificados, e qualquer conteúdo entre esses nós.
+
{{DOMxRef("Selection.setPosition()")}}
+
Colapsa a seleção atual para um único ponto. Este é um apelido para collapse() — Veja {{DOMxRef("Selection.collapse()")}} para mais detalhes.
+
{{DOMxRef("Selection.toString()")}}
+
Retorna uma string atualmente representada pelo objeto selection, i.e. o texto atualmente selecionado.
+
+ +

Notas

+ +

Representação da seleção em formato de String

+ +

Chamando a função {{DOMxRef("Selection.toString()")}} retorna o texto selecionado, e.g.:

+ +
var selObj = window.getSelection();
+window.alert(selObj);
+
+ +

Perceba que usando um objeto selection como argumento de window.alert executará o metodo toString automaticamente.

+ +

Multiplos intervalos em uma seleção

+ +

Um objeto selection representa os {{DOMxRef("range","intervalos")}} que o usuário selecionou.
+ Normalmente é apenas um intervalo, acessado da seguinte forma:

+ +
+
var selObj = window.getSelection();
+var range  = selObj.getRangeAt(0);
+
+ + + +

Como consta nas Especificações da API de seleção, a API foi inicialmente criada pela Netscape e usados multiplos intervalos, por instância, para permitir ao usuário selecionar uma coluna de uma {{HTMLElement("table")}}. Outros navegadores como Gecko não implementaram multiplos intervalos, e a especificação exige que a seleção sempre tenha um único intervalo.

+ +

Seleção e foco de input

+ +

Seleção e foco de input (indicado por {{DOMxRef("Document.activeElement")}}) tem uma relação complexa, que depende do navegador. Para um código compatível com vários navegadores, o melhor é manter os códigos separados.

+ +

O Safari e o Chrome (ao contrário do Firefox) historicamente foca no elemento contendo a seleção quando a seleção é modificada programaticamente, mas isto pode mudar no futuro (veja W3C bug 14383 e {{WebKitBug("38696")}}).

+ +

Comportamento da API de Seleção em termos de edição e alterações de foco do host

+ +

A API de Seleção tem um comportamento comum (i.e. compartilhado entre navegadores) que define como o comportamento do foco muda para elemento editável, após alguns desses métodos serem executados.

+ +

Os comportamentos são que um elemento editado recebe o foco se anteriormente a seleção estiver fora dele, então um método da API de seleção é executado e causa uma nova seleção que será feita em um único intervalo dentro do elemento sendo editado. O foco então é movido para o final do elemento.

+ +
+

Nota: Os métodos da API de seleção, move o foco apenas para o elemento sendo editado, não para outro elemento que pode receber o foco (e.g. {{HTMLElement("a")}}).

+
+ +

O comportamento acima é aplicado para as seleções feitas usando os seguintes métodos:

+ + + +

e quando o intervalo é modificado usando os seguintes métodos:

+ + + +

Glossário

+ +

Outras palavras chaves usadas nesta seção.

+ +
+
anchor
+
O anchor de uma seleção é o ponto inicial da seleção. Quando a seleção é feita com um mouse, é onde o botão do mouse é inicialmente pressionado. Quando o usuário altera a seleção usando o mouse ou teclado, o anchor não move.
+
Elemento editável
+
Um elemento editável — i.e. um elemento HTML com o atributo {{htmlattrxref("contenteditable")}} definido, ou o HTML filho de um documento estiver com o {{DOMxRef("Document.designMode", "designMode")}} habilitado.
+
foco de uma seleção
+
O foco da seleção é o ponto final da seleção. Quando feita a seleção com um mouse, o focus é onde o botão do mouse foi solto. Quando o usuário muda a seleção usando o mouse ou teclado, o focus é o final da seleção que move. Nota: Não é o mesmo que o elemento selecionado do documento, como retornado em {{DOMxRef("document.activeElement")}}.
+
intervalo
+
Um intervalo é uma parte contínua do documento. Um intervalo pode conter nós inteiros ou partes de nós, como uma parte de um text node. Um usuário normalmente irá selecionar um único intervalo por vez, mas é possível que o usuário selecione multiplos intervalos (e.g. usando a tecla Control). Um intervalo pode ser obtido de uma seleção como um objeto {{DOMxRef("range")}}. Um objeto de intervalo pode ser criado no DOM e programaticamente adicionada ou removida de uma seleção.
+
+ +

Especificações

+ + + + + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName("Selection API", "#selection-interface", "Seleção")}}{{Spec2("Selection API")}}A especificação da API de Seleção é baseada na especificação da API de edição HTML e focada na funcionalidade relacionada à seleção.
{{SpecName("HTML Editing", "#selection", "Seleção")}}{{Spec2("HTML Editing")}}Definição incial (antiga).
+ +

Compatibilidade de navegadores

+ + + +

{{Compat("api.Selection")}}

+ +

Veja também

+ + + +

Notas da Gecko

+ + + +
+
diff --git "a/files/pt-br/web/api/sele\303\247\303\243o/index.html" "b/files/pt-br/web/api/sele\303\247\303\243o/index.html" deleted file mode 100644 index 9cac677942..0000000000 --- "a/files/pt-br/web/api/sele\303\247\303\243o/index.html" +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Seleção -slug: Web/API/Seleção -tags: - - API - - Experimental - - Interface - - Referencia - - Seleção -translation_of: Web/API/Selection ---- -
{{ ApiRef("DOM") }}{{SeeCompatTable}}
- -

Um objeto Selection representa um intervalo do texto selecionado pelo usuário ou a posição atual do cursor. Para obter o objeto Selection para inspecionar ou modificar, use {{DOMxRef("Window.getSelection()")}}.

- -

O usuário pode fazer a seleção da esquerda para a direita (na orientação do documento) ou da direita para a esquerta (orientação inversa do documento). O atributo anchor (âncora) é onde o usuário iniciou a seleção e o atributo focus (foco) é onde o usuário terminou a seleção. Se você fizer a seleção utilizando um mouse no desktop, o anchor é definido onde você pressionou o botão do mouse e o focus é definido onde você soltou o botão do mouse. Anchor e focus não devem ser confundidos com a posição inicial e final da seleção, pois o anchor pode ser definido antes do focus ou vice versa, dependendo da direção em que você fez sua seleção.

- -

Propriedades

- -
-
{{DOMxRef("Selection.anchorNode")}}{{ReadOnlyInline}}
-
Retorna o {{DOMxRef("Node")}} onde a seleção começou.
-
{{DOMxRef("Selection.anchorOffset")}}{{ReadOnlyInline}}
-
Retorna um número representando o deslocamento do anchor dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o anchor (clique inicial da seleção). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o anchor.
-
{{DOMxRef("Selection.focusNode")}}{{ReadOnlyInline}}
-
Retorna o {{DOMxRef("Node")}} onde a seleção termina.
-
{{DOMxRef("Selection.focusOffset")}}{{ReadOnlyInline}}
-
Retorna um número representando o deslocamento do focus dentro do elemento Se o elemento for do tipo text node, o número retornado será o número de caracteres no elemento que precedem o focus (posição onde o mouse foi solto). Se o elemento for do tipo element (qualquer tag html que não seja text node), o número retornado será o número de nós filhos do elemento que precedem o focus.
-
{{DOMxRef("Selection.isCollapsed")}}{{ReadOnlyInline}}
-
Retorna um valor booleano indicando se o início e o final da seleção são a mesma posição, ou seja, começou e terminou no mesmo lugar.
-
{{DOMxRef("Selection.rangeCount")}}{{ReadOnlyInline}}
-
Retorna no número de intervalos da seleção.
-
{{DOMxRef("Selection.type")}}{{ReadOnlyInline}}
-
Retorna um {{DOMxRef("DOMString")}} descrevento o tipo da seleção atual.
-
- -

Métodos

- -
-
{{DOMxRef("Selection.addRange()")}}
-
Um objeto {{DOMxRef("Range")}} que será adicionado na seleção.
-
{{DOMxRef("Selection.collapse()")}}
-
Colapsa a seleção atual em um único ponto.
-
{{DOMxRef("Selection.collapseToEnd()")}}
-
Colapsa a seleção para o final do último intervalo na seleção.
-
{{DOMxRef("Selection.collapseToStart()")}}
-
Colapsa a seleção para o início do primeiro intervalo na seleção.
-
{{DOMxRef("Selection.containsNode()")}}
-
Indica se um certo nó é parte da seleção.
-
{{DOMxRef("Selection.deleteFromDocument()")}}
-
Apaga o conteúdo da seleção do documento.
-
{{DOMxRef("Selection.empty()")}}
-
Remove todos os intervalos da seleção. Este é um apelido para removeAllRanges() — Veja {{DOMxRef("Selection.removeAllRanges()")}} para mais detalhes.
-
{{DOMxRef("Selection.extend()")}}
-
Move o focus (final da seleção) para um ponto específico.
-
{{DOMxRef("Selection.getRangeAt()")}}
-
Retorna um objeto {{DOMxRef("Range")}} represetando um dos intervalos atualmente selecionados.
-
{{DOMxRef("Selection.modify()")}}{{Non-standard_Inline}}
-
Altera a seleção atual.
-
{{DOMxRef("Selection.removeRange()")}}
-
Remove um intervalo da seleção.
-
{{DOMxRef("Selection.removeAllRanges()")}}
-
Remove todos os intervalos da seleção.
-
{{DOMxRef("Selection.selectAllChildren()")}}
-
Adiciona todos os filhos do nó especificado para a seleção.
-
{{DOMxRef("Selection.setBaseAndExtent()")}}
-
Define que a seleção será um intervalo incluindo todos ou partes dos dois nós DOM especificados, e qualquer conteúdo entre esses nós.
-
{{DOMxRef("Selection.setPosition()")}}
-
Colapsa a seleção atual para um único ponto. Este é um apelido para collapse() — Veja {{DOMxRef("Selection.collapse()")}} para mais detalhes.
-
{{DOMxRef("Selection.toString()")}}
-
Retorna uma string atualmente representada pelo objeto selection, i.e. o texto atualmente selecionado.
-
- -

Notas

- -

Representação da seleção em formato de String

- -

Chamando a função {{DOMxRef("Selection.toString()")}} retorna o texto selecionado, e.g.:

- -
var selObj = window.getSelection();
-window.alert(selObj);
-
- -

Perceba que usando um objeto selection como argumento de window.alert executará o metodo toString automaticamente.

- -

Multiplos intervalos em uma seleção

- -

Um objeto selection representa os {{DOMxRef("range","intervalos")}} que o usuário selecionou.
- Normalmente é apenas um intervalo, acessado da seguinte forma:

- -
-
var selObj = window.getSelection();
-var range  = selObj.getRangeAt(0);
-
- - - -

Como consta nas Especificações da API de seleção, a API foi inicialmente criada pela Netscape e usados multiplos intervalos, por instância, para permitir ao usuário selecionar uma coluna de uma {{HTMLElement("table")}}. Outros navegadores como Gecko não implementaram multiplos intervalos, e a especificação exige que a seleção sempre tenha um único intervalo.

- -

Seleção e foco de input

- -

Seleção e foco de input (indicado por {{DOMxRef("Document.activeElement")}}) tem uma relação complexa, que depende do navegador. Para um código compatível com vários navegadores, o melhor é manter os códigos separados.

- -

O Safari e o Chrome (ao contrário do Firefox) historicamente foca no elemento contendo a seleção quando a seleção é modificada programaticamente, mas isto pode mudar no futuro (veja W3C bug 14383 e {{WebKitBug("38696")}}).

- -

Comportamento da API de Seleção em termos de edição e alterações de foco do host

- -

A API de Seleção tem um comportamento comum (i.e. compartilhado entre navegadores) que define como o comportamento do foco muda para elemento editável, após alguns desses métodos serem executados.

- -

Os comportamentos são que um elemento editado recebe o foco se anteriormente a seleção estiver fora dele, então um método da API de seleção é executado e causa uma nova seleção que será feita em um único intervalo dentro do elemento sendo editado. O foco então é movido para o final do elemento.

- -
-

Nota: Os métodos da API de seleção, move o foco apenas para o elemento sendo editado, não para outro elemento que pode receber o foco (e.g. {{HTMLElement("a")}}).

-
- -

O comportamento acima é aplicado para as seleções feitas usando os seguintes métodos:

- - - -

e quando o intervalo é modificado usando os seguintes métodos:

- - - -

Glossário

- -

Outras palavras chaves usadas nesta seção.

- -
-
anchor
-
O anchor de uma seleção é o ponto inicial da seleção. Quando a seleção é feita com um mouse, é onde o botão do mouse é inicialmente pressionado. Quando o usuário altera a seleção usando o mouse ou teclado, o anchor não move.
-
Elemento editável
-
Um elemento editável — i.e. um elemento HTML com o atributo {{htmlattrxref("contenteditable")}} definido, ou o HTML filho de um documento estiver com o {{DOMxRef("Document.designMode", "designMode")}} habilitado.
-
foco de uma seleção
-
O foco da seleção é o ponto final da seleção. Quando feita a seleção com um mouse, o focus é onde o botão do mouse foi solto. Quando o usuário muda a seleção usando o mouse ou teclado, o focus é o final da seleção que move. Nota: Não é o mesmo que o elemento selecionado do documento, como retornado em {{DOMxRef("document.activeElement")}}.
-
intervalo
-
Um intervalo é uma parte contínua do documento. Um intervalo pode conter nós inteiros ou partes de nós, como uma parte de um text node. Um usuário normalmente irá selecionar um único intervalo por vez, mas é possível que o usuário selecione multiplos intervalos (e.g. usando a tecla Control). Um intervalo pode ser obtido de uma seleção como um objeto {{DOMxRef("range")}}. Um objeto de intervalo pode ser criado no DOM e programaticamente adicionada ou removida de uma seleção.
-
- -

Especificações

- - - - - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName("Selection API", "#selection-interface", "Seleção")}}{{Spec2("Selection API")}}A especificação da API de Seleção é baseada na especificação da API de edição HTML e focada na funcionalidade relacionada à seleção.
{{SpecName("HTML Editing", "#selection", "Seleção")}}{{Spec2("HTML Editing")}}Definição incial (antiga).
- -

Compatibilidade de navegadores

- - - -

{{Compat("api.Selection")}}

- -

Veja também

- - - -

Notas da Gecko

- - - -
-
diff --git a/files/pt-br/web/api/svgaelement/svgalement.target/index.html b/files/pt-br/web/api/svgaelement/svgalement.target/index.html deleted file mode 100644 index e197ee81e5..0000000000 --- a/files/pt-br/web/api/svgaelement/svgalement.target/index.html +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: SVGAElement.target -slug: Web/API/SVGAElement/SVGAlement.target -tags: - - Imagem vetorial - - Vetores -translation_of: Web/API/SVGAElement/target -translation_of_original: Web/API/SVGAElement/SVGAlement.target ---- -

{{APIRef("SVGAElement")}}

- -

O SVGAElement.target propriedade somente ler de {{domxref("SVGAElement")}} retorna um objeto {{domxref("SVGAnimatedString")}} que especifica a porção de um alvo sendo ele "window", "frame" ou "pane" no qual um documento será aberto quando o link for acionado.

- -

Esta propriedade é usada quando existem dois ou mais possiveis alvos(destinos) para o documento, por exemplo, quando o documento pai é um arquivo .html ou .xhtml com varias telas (multi-frame).

- -

Sintaxe

- -
myLink.target = 'value';
- -

Valor

- -

Um {{domxref("SVGAnimatedString")}} indica o destino final do recurso que abre o documento assim que o link é acionado.

- -

Valores para {{domxref("target")}} você pode ver aqui.

- -

Exemplo

- -

O código é foi retirado de "SVGAElement example code"

- -
...
-var linkRef = document.querySelector('a');
-linkRef.target ='_blank';
-...
- -

Especificações

- - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('SVG1.1', 'text.html#InterfaceSVGAElement', 'target')}}{{Spec2('SVG1.1')}} 
- -

Compatibilidade com o navegador

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}9.0{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatVersionUnknown() }}{{ CompatUnknown() }}{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}
-
- -

Veja também

- - diff --git a/files/pt-br/web/api/svgaelement/target/index.html b/files/pt-br/web/api/svgaelement/target/index.html new file mode 100644 index 0000000000..e197ee81e5 --- /dev/null +++ b/files/pt-br/web/api/svgaelement/target/index.html @@ -0,0 +1,106 @@ +--- +title: SVGAElement.target +slug: Web/API/SVGAElement/SVGAlement.target +tags: + - Imagem vetorial + - Vetores +translation_of: Web/API/SVGAElement/target +translation_of_original: Web/API/SVGAElement/SVGAlement.target +--- +

{{APIRef("SVGAElement")}}

+ +

O SVGAElement.target propriedade somente ler de {{domxref("SVGAElement")}} retorna um objeto {{domxref("SVGAnimatedString")}} que especifica a porção de um alvo sendo ele "window", "frame" ou "pane" no qual um documento será aberto quando o link for acionado.

+ +

Esta propriedade é usada quando existem dois ou mais possiveis alvos(destinos) para o documento, por exemplo, quando o documento pai é um arquivo .html ou .xhtml com varias telas (multi-frame).

+ +

Sintaxe

+ +
myLink.target = 'value';
+ +

Valor

+ +

Um {{domxref("SVGAnimatedString")}} indica o destino final do recurso que abre o documento assim que o link é acionado.

+ +

Valores para {{domxref("target")}} você pode ver aqui.

+ +

Exemplo

+ +

O código é foi retirado de "SVGAElement example code"

+ +
...
+var linkRef = document.querySelector('a');
+linkRef.target ='_blank';
+...
+ +

Especificações

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('SVG1.1', 'text.html#InterfaceSVGAElement', 'target')}}{{Spec2('SVG1.1')}} 
+ +

Compatibilidade com o navegador

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}9.0{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatVersionUnknown() }}{{ CompatUnknown() }}{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}
+
+ +

Veja também

+ + diff --git a/files/pt-br/web/api/touch_events/index.html b/files/pt-br/web/api/touch_events/index.html new file mode 100644 index 0000000000..df21cdf335 --- /dev/null +++ b/files/pt-br/web/api/touch_events/index.html @@ -0,0 +1,353 @@ +--- +title: Eventos do Toque +slug: Web/Guide/Events/Touch_events +tags: + - Avançado + - DOM + - Evento + - Guía + - Mobile + - Visualização +translation_of: Web/API/Touch_events +--- +

Com a finalidade de fornecer suporte de qualidade para interfaces baseadas em toque (touch), os eventos de touch oferecem a capacidade de interpretar a atividade em telas sensíveis ao toque ou trackpads.

+ +

Definições

+ +
+
Surface
+
A superfície sensível ao toque. Pode ser uma tela ou trackpad.
+
+ +
+
Touch point
+
Um ponto de contato com a superfície. Pode ser um dedo (ou cotovelo, orelha, nariz, o que seja, mas provavelmente, um dedo) ou uma caneta.
+
+ +

Interfaces

+ +
+
{{ domxref("TouchEvent") }}
+
Representa um evento quando ocorre o estado de toque na superfície.
+
{{ domxref("Touch") }}
+
Representa um único ponto de contato entre o usuário e a superfície sensível a toque.
+
{{ domxref("TouchList") }}
+
Representa um grupo de toques, isto é usado quando usuário tem por exemplo, vários dedos ao mesmo tempo sobre a superfície.
+
{{ domxref("DocumentTouch") }}
+
Contém métodos de conveniência para criar {{ domxref("Touch") }} e objetos {{ domxref("TouchList") }} .
+
+ +

Exemplo

+ +

Este exemplo acompanha múltiplos pontos de contato de cada vez, permitindo o usuário desenhe em um {{ HTMLElement("canvas") }} com mais de um dedo por vez. Ele só funcionará em um browser que tenha suporte a eventos de toque.

+ +
Nota: O texto a seguir utiliza o termo "finger" quando descreve o contato com a superfície, mas poderia, é claro, ser também uma caneta ou outro método de contato.
+ +

Crie um canvas

+ +
<canvas id="canvas" width="600" height="600" style="border:solid black 1px;">
+  Seu browser não tem suporte ao elemento canvas.
+</canvas>
+<br>
+<button onclick="startup()">Initialize</button>
+<br>
+Log: <pre id="log" style="border: 1px solid #ccc;"></pre>
+
+ +

Configurado os eventos

+ +

Quando uma página é carregada, a função startup() mostrada abaixo deve ser chamada pelo nosso elemento {{ HTMLElement("body") }} através do atributo onload (Mas no exemplo usamos um botão para adicioná-lo, devido as limitações do MDN live example system).

+ +
function startup() {
+  var el = document.getElementsByTagName("canvas")[0];
+  el.addEventListener("touchstart", handleStart, false);
+  el.addEventListener("touchend", handleEnd, false);
+  el.addEventListener("touchcancel", handleCancel, false);
+  el.addEventListener("touchleave", handleEnd, false);
+  el.addEventListener("touchmove", handleMove, false);
+  log("initialized.");
+}
+
+ +

Define simplesmento todos os ouvintes dos eventos do nosso elemento {{ HTMLElement("canvas") }} para que possamos trabalhar com os eventos de toque quando eles ocorrerem.

+ +

Rastreando novos toques

+ +

Vamos acompanhar os toques em seu progresso.

+ +
var ongoingTouches = new Array; 
+ +

Quando ocorre um evento touchstart, indicando que um novo toque na superfície tenha ocorrido, a função abaixo handleStart() é chamada. 

+ +
function handleStart(evt) {
+  evt.preventDefault();
+  log("touchstart.");
+  var el = document.getElementsByTagName("canvas")[0];
+  var ctx = el.getContext("2d");
+  var touches = evt.changedTouches;
+
+  for (var i=0; i < touches.length; i++) {
+    log("touchstart:"+i+"...");
+    ongoingTouches.push(copyTouch(touches[i]));
+    var color = colorForTouch(touches[i]);
+    ctx.beginPath();
+    ctx.arc(touches[i].pageX, touches[i].pageY, 4, 0,2*Math.PI, false);  // a circle at the start
+    ctx.fillStyle = color;
+    ctx.fill();
+    log("touchstart:"+i+".");
+  }
+}
+
+ +

A chamada {{ domxref("event.preventDefault()") }} mantem o browser a processa o evento de toque ( isso também previne que um mouse event seja despachado). Então, temos o contexto e puxamos a lista de pontos de contato disparados noa propriedade do evento {{ domxref("TouchEvent.changedTouches") }}.

+ +

Depois disso, nós iteramos sobre todos os objetos {{ domxref("Touch") }} da lista e os adicionamos em um array de pontos de contatos ativos e definimos o ponto inicial para desenhar um pequeno circulo; estamos usando um raio de 4 pixels, então um círculo de 4 pixels irá aparecer em nosso canvas.

+ +

Desenhando movimento do toque

+ +

Cada vez que um ou mais dedos se movem, um evento de TouchMove é disparado, assim chamando nossa função handleMove(). A sua responsabilidade neste exemplo é atualizar as informações armazenadas e desenhar uma linha a partir da posição anterior para a atual de cada toque.

+ +
function handleMove(evt) {
+  evt.preventDefault();
+  var el = document.getElementsByTagName("canvas")[0];
+  var ctx = el.getContext("2d");
+  var touches = evt.changedTouches;
+
+  for (var i=0; i < touches.length; i++) {
+    var color = colorForTouch(touches[i]);
+    var idx = ongoingTouchIndexById(touches[i].identifier);
+
+    if(idx >= 0) {
+      log("continuing touch "+idx);
+      ctx.beginPath();
+      log("ctx.moveTo("+ongoingTouches[idx].pageX+", "+ongoingTouches[idx].pageY+");");
+      ctx.moveTo(ongoingTouches[idx].pageX, ongoingTouches[idx].pageY);
+      log("ctx.lineTo("+touches[i].pageX+", "+touches[i].pageY+");");
+      ctx.lineTo(touches[i].pageX, touches[i].pageY);
+      ctx.lineWidth = 4;
+      ctx.strokeStyle = color;
+      ctx.stroke();
+
+      ongoingTouches.splice(idx, 1, copyTouch(touches[i]));  // swap in the new touch record
+      log(".");
+    } else {
+      log("can't figure out which touch to continue");
+    }
+  }
+}
+
+ +

Esta interação sobre os toques também muda, mas parece em cache as  informações em um array para cada toque anterior, a fim de determinar um pont de partida e o destino para o desenho do trajeto. Isto é feito para olhar cada touch da propriedade {{ domxref("Touch.identifier") }}. Esta propriedade é um número inteiro único para cada toque, e mantém-se consistente para cada evento durante o tempo de contato de cada dedo como a superfície.

+ +

Isto permite obter as coordenadas da posição anterior de cada contato e usar os métodos de contexto apropriado para desenhar uma linha que une as duas posições.

+ +

Depois de desenhar a linha, nós chamamos Array.splice() para substituir as informações previas sobre o ponto de toque com a informação atual no array ongoingTouches.

+ +

Gerenciando o final do evento de toque 

+ +

Quando o usuário retira o dedo da superfície , um evento touchend é disparado.  Da mesma forma, se o dedo deslisa para fora do canvas, nós teremos um evento touchleave disparado. Nós tratamos da mesma forma em ambos os casos:  chamamos  a função handleEnd(). A sua missão é desenhar uma linha para o final do ponto de toque e remover o ponto de toque da lista ongoing.

+ +
function handleEnd(evt) {
+  evt.preventDefault();
+  log("touchend/touchleave.");
+  var el = document.getElementsByTagName("canvas")[0];
+  var ctx = el.getContext("2d");
+  var touches = evt.changedTouches;
+
+  for (var i=0; i < touches.length; i++) {
+    var color = colorForTouch(touches[i]);
+    var idx = ongoingTouchIndexById(touches[i].identifier);
+
+    if(idx >= 0) {
+      ctx.lineWidth = 4;
+      ctx.fillStyle = color;
+      ctx.beginPath();
+      ctx.moveTo(ongoingTouches[idx].pageX, ongoingTouches[idx].pageY);
+      ctx.lineTo(touches[i].pageX, touches[i].pageY);
+      ctx.fillRect(touches[i].pageX-4, touches[i].pageY-4, 8, 8);  // and a square at the end
+      ongoingTouches.splice(idx, 1);  // remove it; we're done
+    } else {
+      log("can't figure out which touch to end");
+    }
+  }
+}
+
+ +

Isto é muito semelhante a função anterior, as únicas diferenças reais são o desenho de um pequeno quadrado para marcar o fim e quando chamamos Array.splice(), nós simplesmente removemos a antiga entrada da lista de toque do ongoing, sem adição das informações atualizadas. O resultado é que paramos o tracking do ponto de contato.

+ +

Tratando toques cancelados

+ +

Se o dedo do usuário deslisa em uma UI de um navegador, ou o toque de outra forma precisa ser cancelado, o evento touchcancel é disparado e nos chamamaos a função handleCancel().

+ +
function handleCancel(evt) {
+  evt.preventDefault();
+  log("touchcancel.");
+  var touches = evt.changedTouches;
+
+  for (var i=0; i < touches.length; i++) {
+    ongoingTouches.splice(i, 1);  // remove it; we're done
+  }
+}
+
+ +

Uma vez que a idéia dé cancelar imediatamento o toque, nós simplesmente removemos da lista de ongoing sem desenhar uma linha final.

+ +

Funções de conveniência

+ +

Este exemplo usa duas funções de conveniência que deve ser olhado rapidamente para ajudar a fazer o resto do código mais claro

+ +

Selecionando a cor para cada toque

+ +

A fim de fazer cada toque desenhar com uma cor diferente, a função  colorForTouch()  é usada para escolher uma cor com base em um identificador único do toque, Este identificador é um número opaco, mas pelo menos podemos conta com ele diferindo entre os toques ativos no momento.

+ +
function colorForTouch(touch) {
+  var r = touch.identifier % 16;
+  var g = Math.floor(touch.identifier / 3) % 16;
+  var b = Math.floor(touch.identifier / 7) % 16;
+  r = r.toString(16); // make it a hex digit
+  g = g.toString(16); // make it a hex digit
+  b = b.toString(16); // make it a hex digit
+  var color = "#" + r + g + b;
+  log("color for touch with identifier " + touch.identifier + " = " + color);
+  return color;
+}
+
+ +

O resultado desta função é uma string que pode ser usada ao chamar as funções {{ HTMLElement("canvas") }} para setar a cor do desenho. Por exemplo, para um valor  {{ domxref("Touch.identifier") }} de 10, o resultado será a string "#aaa".

+ +

Copiando touch objects

+ +

Alguns browsers (mobile Safari, por exemplo) re-usa touch objects entre os eventos, por isso é melhor ter cuidado para copiar os bits, em vez de fazer referência a todo objeto.

+ +
function copyTouch(touch) {
+  return { identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY };
+}
+ +

Encontrando um toque ongoing

+ +

A função ongoingTouchIndexById() abaixo verifica através do array ongoingTouches para encontrar o toque correspondente ao indentificador passado, então ele retorna o índice do touch no array.

+ +
function ongoingTouchIndexById(idToFind) {
+  for (var i=0; i < ongoingTouches.length; i++) {
+    var id = ongoingTouches[i].identifier;
+
+    if (id == idToFind) {
+      return i;
+    }
+  }
+  return -1;    // não econtrado
+}
+
+ +

Mostrando o que está acontecendo

+ +
function log(msg) {
+  var p = document.getElementById('log');
+  p.innerHTML = msg + "\n" + p.innerHTML;
+}
+ +

If your browser supports it, you can {{ LiveSampleLink('Example', 'see it live') }}.

+ +

jsFiddle example

+ +

Additional tips

+ +

This section provides additional tips on how to handle touch events in your web application.

+ +

Handling clicks

+ +

Since calling preventDefault() on a touchstart or the first touchmove event of a series prevents the corresponding mouse events from firing, it's common to call preventDefault() on touchmove rather than touchstart. That way, mouse events can still fire and things like links will continue to work. Alternatively, some frameworks have taken to refiring touch events as mouse events for this same purpose. (This example is oversimplified and may result in strange behavior. It is only intended as a guide.)

+ +
function onTouch(evt) {
+  evt.preventDefault();
+  if (evt.touches.length > 1 || (evt.type == "touchend" && evt.touches.length > 0))
+    return;
+
+  var newEvt = document.createEvent("MouseEvents");
+  var type = null;
+  var touch = null;
+  switch (evt.type) {
+    case "touchstart":    type = "mousedown";    touch = evt.changedTouches[0];break;
+    case "touchmove":        type = "mousemove";    touch = evt.changedTouches[0];break;
+    case "touchend":        type = "mouseup";    touch = evt.changedTouches[0];break;
+  }
+  newEvt.initMouseEvent(type, true, true, evt.originalTarget.ownerDocument.defaultView, 0,
+    touch.screenX, touch.screenY, touch.clientX, touch.clientY,
+    evt.ctrlKey, evt.altKey, evt.shirtKey, evt.metaKey, 0, null);
+  evt.originalTarget.dispatchEvent(newEvt);
+}
+
+ +

Calling preventDefault() only on a second touch

+ +

One technique for preventing things like pinchZoom on a page is to call preventDefault() on the second touch in a series. This behavior is not well defined in the touch events spec, and results in different behavior for different browsers (i.e., iOS will prevent zooming but still allow panning with both fingers; Android will allow zooming but not panning; Opera and Firefox currently prevent all panning and zooming.) Currently, it's not recommended to depend on any particular behavior in this case, but rather to depend on meta viewport to prevent zooming.

+ +
+
+ +

Browser compatibility

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatChrome("22.0") }}{{ CompatGeckoDesktop("18.0") }}
+ Disabled with 24 ({{ bug(888304) }})		{{ CompatNo() }}{{ CompatNo() }}{{ CompatNo() }}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatVersionUnknown() }}(Yes){{ CompatGeckoMobile("6.0") }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatVersionUnknown() }}
+
+ +

Gecko notes

+ +

The dom.w3c_touch_events.enabled tri-state preference can be used to disable (0), enable (1), and auto-detect(2) support for standard touch events; by default, they're on auto-detect(2). After changing the preference, you must restart the browser for the changes to take effect.

+ +
+

Prior to {{Gecko("12.0")}}, Gecko did not support multi-touch; only one touch at a time was reported.

+
+ +
+

Note: As of {{Gecko("24.0")}}, the touch events support introduced with {{Gecko("18.0")}} has been disabled on the desktop version of Firefox, as some popular sites including Google and Twitter are not working properly. Once the bug is fixed, the API will be enabled again. To enable it anyway, open about:config and set the dom.w3c_touch_events.enabled pref to 2. The mobile versions including Firefox for Android and Firefox OS are not affected by this change. Also, the API has been enabled on the Metro-style version of Firefox for Windows 8.

+
+ +
Note: Prior to {{Gecko("6.0") }}, Gecko offered a proprietary touch event API. That API is now deprecated; you should switch to this one.
diff --git a/files/pt-br/web/api/web_animations_api/usando_a_web_animations_api/index.html b/files/pt-br/web/api/web_animations_api/usando_a_web_animations_api/index.html deleted file mode 100644 index 2743f68d65..0000000000 --- a/files/pt-br/web/api/web_animations_api/usando_a_web_animations_api/index.html +++ /dev/null @@ -1,358 +0,0 @@ ---- -title: Usando a Web Animations API -slug: Web/API/Web_Animations_API/Usando_a_Web_Animations_API -tags: - - Alice - - Animação - - CSS - - Guía - - Iniciante - - JavaScript - - Timing - - Tutorial - - animar - - duration - - keyframes - - pausar - - pause - - play - - quadro-chave - - reverse - - web animations api -translation_of: Web/API/Web_Animations_API/Using_the_Web_Animations_API ---- -

{{DefaultAPISidebar("Web Animations")}}

- -

A Web Animations API nos possibilita criar animações e controlar sua reprodução pelo JavaScript. Esse artigo vai te demonstrar esses conceitos com demonstrações e tutoriais com o temática de Alice no País das Maravilhas.

- -

Conhecendo a Web Animations API

- -

A Web Animations API abre a engine de animação do browser para os desenvolvedores manipularem via JavaScript. Esta API foi construída para se basear nas implementações das Animações CSS e Transições CSS, e deixam a porta aberta para futuros efeitos de animação. É um dos métodos mais performáticos para se animar na Web, permitindo que o browser faça internamente suas próprias otimizações, sem precisar depender de hacks, coerções ou {{domxref("Window.requestAnimationFrame()")}}.

- -

Com a Web Animations API, podemos transferir as animações interativas das folhas de estilo para o JavaScript, separando comportamento de apresentação. Não vamos precisar mais depender de técnicas muito dependentes do DOM como propriedades do CSS e escopo de classes para controlar a direção da reprodução. E diferente de CSS puro e declarativo, JavaScript também te possibilita definir dinâmicamente valores: de propriedades à duração. Para criar bibilotecas de animação à criar animações interativas, a Web Animations API pode ser a ferramenta perfeita para o trabalho. Vamos ver o que ela pode fazer!

- -

Suporte de Navegadores

- -

O suporte básico para as funcionalidades da Web Animations API discutidas neste artigo estão disponíveis no Firefox 48+, Chrome 36+ e Safari 13.1+. Também existe um polyfill prático que verifica o suporte e adiciona as funcionalidades onde for necessário.

- -

Escrevendo Animações CSS com a Web Animations API

- -

Uma das maneiras mais familiares de abordar a Web Animations API é começar com algo que boa parte dos desenvolvedores web já utilizaram antes: Animações CSS. Animações CSS tem uma sintaxe familiar que funciona bem para nossa demonstração.

- -

A versão CSS

- -

Aqui temos uma animação escrita com CSS mostrando Alice caindo no buraco de coelho que leva ao País das Maravilhas (veja o código completo no Codepen):

- -

Alice Tumbling down the rabbit's hole.

- -

Perceba que o fundo se mexe, a Alice gira e sua cor muda em sincronia com o giro. Nós vamos focar somente na Alice para este tutorial. Segue a versão simplificada do CSS que controla a animação da Alice:

- -
#alice {
-  animation: aliceTumbling infinite 3s linear;
-}
-
-@keyframes aliceTumbling {
-  0% {
-    color: #000;
-    transform: rotate(0) translate3D(-50%, -50%, 0);
-  }
-  30% {
-    color: #431236;
-  }
-  100% {
-    color: #000;
-    transform: rotate(360deg) translate3D(-50%, -50%, 0);
-  }
-}
- -

Isso muda a cor da Alice e a rotação do `transform` por 3 segundos em um ritmo constante (linear) e se repete infinitamente. No bloco do @keyframes podemos ver que em 30% de cada repetição (por volta dos 900ms), a cor da Alice muda de preto para um vinho, e volta para o preto no final do loop.

- -

Mudando para o JavaScript

- -

Agora vamos tentar criar a mesma animação usando a Web Animations API.

- -

Representando keyframes

- -

A primeira coisa que precisamos fazer é criar um Objeto Keyframe correspondente ao nosso bloco @keyframes do CSS:

- -
var aliceTumbling = [
-  { transform: 'rotate(0) translate3D(-50%, -50%, 0)', color: '#000' },
-  { color: '#431236', offset: 0.3},
-  { transform: 'rotate(360deg) translate3D(-50%, -50%, 0)', color: '#000' }
-];
- -

Aqui estávamos utilizando uma array contendo múltiplos objetos. Cada objeto representa uma chave do CSS original. Contudo, diferente do CSS, a Web Animations API não precisa informar explicitamente as porcentagens temporais para cada chave, o JS automaticamente divide a animação em partes iguais baseado no número de chaves que você forneceu. Isso significa que um objeto Keyframe com três chaves vai reproduzir a chave do meio em 50% do tempo de cada loop, exceto se for definido o contrário.

- -

Quando queremos explicitamente definir um timing diferente para essas outras chaves, podemos especificar um offset diretamente no objeto, separado do resto da declaração por uma vírgula. No exemplo acima, para definir que a cor da Alice muda em 30% do tempo (e não 50%), nós definiremos como offset: 0.3.

- -

Atualmente, devem ser definidos pelo menos dois keyframes (representando o início e fim de estado das sequências de animação). Se a sua lista de keyframes somente tem uma entrada, {{domxref("Element.animate()")}} pode disparar uma exceção NotSupportedErro em alguns browsers até eles serem atualizados.

- -

Então recapitulando: as chaves são espaçadas igualmente por padrão, exceto se você definir um offset para uma chave. Útil, não?

- -

Representando propriedades temporais

- -

Nós precisamos criar também um objeto de propriedades temporais (um objeto {{domxref("AnimationEffectTimingProperties")}}) correspondente aos valores da animação da Alice:

- -
var aliceTiming = {
-  duration: 3000,
-  iterations: Infinity
-}
- -

Você pode notar algumas diferenças aqui comparando com os valores equivalentes representados no CSS:

- - - -
-

Existem algumas pequenas diferenças de terminologia entre o CSS Animations e o Web Animations. Por exemplo, Web Animations não usa a string "infinite", e sim a keyword JavaScript Infinity. E no lugar de timing-function, usamos easing. Não estamos citando um valor de easing aqui pois, diferente das Animações CSS onde o valor padrão do animation-timing-function é ease, na Web Animations API o padrão é linear — o que nós já queremos para a animação da Alice.

-
- -

Juntando as peças

- -

Agora vamos juntar o que já fizemos com o método {{domxref("Element.animate()")}}:

- -
document.getElementById("alice").animate(
-  aliceTumbling,
-  aliceTiming
-)
- -

E pronto: a animação começa a tocar (veja a versão final no Codepen).

- -

O método animate() pode ser chamado em qualquer elemento do DOM que pode ser animado com CSS. E pode ser escrito de algumas maneiras. Ao invés de criar objetos para os keyframes e propriedades temporais, podemos passar seus valores diretamentes, tipo:

- -
document.getElementById("alice").animate(
-  [
-    { transform: 'rotate(0) translate3D(-50%, -50%, 0)', color: '#000' },
-    { color: '#431236', offset: 0.3},
-    { transform: 'rotate(360deg) translate3D(-50%, -50%, 0)', color: '#000' }
-  ], {
-    duration: 3000,
-    iterations: Infinity
-  }
-);
- -

E se nós precisarmos somente especificar a duração da animação e não suas iterações (por padrão, a animação roda uma ), podemos passar só os milisegundos após o array:

- -
document.getElementById("alice").animate(
-  [
-    { transform: 'rotate(0) translate3D(-50%, -50%, 0)', color: '#000' },
-    { color: '#431236', offset: 0.3},
-    { transform: 'rotate(360deg) translate3D(-50%, -50%, 0)', color: '#000' }
-  ], 3000);
- -

Controlando a reprodução com play(), pause(), reverse() e updatePlaybackRate()

- -

Por mais que possamos escrever Animações CSS utilizando a Web Animations API, a API realmente mostra seu potencial quando precisamos manipular a reprodução da animação. A Web Animations API fornece vários métodos úteis para controlar a reprodução. Vamos dar uma olhada em como pausar e tocar animações no jogo da Alice Crescendo/Encolhendo (confira o código completo no Codepen):

- -

Playing the growing and shrinking game with Alice.

- -

Nesse jogo, Alice tem uma animação que a encolhe ou aumenta seu tamanho, que controlamos por uma garrafa e um cupcake. Cada um tem sua própria animação.

- -

Pausando e tocando animações

- -

Vamos falar sobre a animação da Alice depois, mas por enquanto, vamos dissecar esta animação do cupcake.

- -
var nommingCake = document.getElementById('eat-me_sprite').animate(
-[
-  { transform: 'translateY(0)' },
-  { transform: 'translateY(-80%)' }
-], {
-  fill: 'forwards',
-  easing: 'steps(4, end)',
-  duration: aliceChange.effect.timing.duration / 2
-});
- -

O método {{domxref("Element.animate()")}} vai rodar imediatamente depois de ser chamado. Para evitar que o bolinho se coma sozinho antes da interação do usuário, chamamos o {{domxref("Animation.pause()")}} imediatamente depois de criar a animação:

- -
nommingCake.pause();
- -

Agora nós podemos usar o método {{domxref("Animation.play()")}} para rodar assim que for o momento:

- -
nommingCake.play();
- -

Especificamente, nós queremos linka-lo à animação da Alice, para ela crescer assim que o cupcake é mordido. Podemos fazer isso com a seguinte função:

- -
var growAlice = function() {
-
-  // Play Alice's animation.
-  aliceChange.play();
-
-  // Play the cake's animation.
-  nommingCake.play();
-
-}
- -

Quando o usuário clicar ou pressionar seu dedo no bolinho em uma tela de toque, podemos chamar a função growAlice para fazer todas as animações tocarem:

- -
cake.addEventListener("mousedown", growAlice, false);
-cake.addEventListener("touchstart", growAlice, false);
- -

Outros métodos úteis

- - - -

Vamos dar uma olhada primeiro no método playbackRate — um valor negativo vai fazer a animação tocar ao contrário. Quando Alice bebe da garrafa, ela encolhe. Isso porque a garrafa muda o playbackRate da animação de 1 para -1:

- -
var shrinkAlice = function() {
-  aliceChange.playbackRate = -1;
-  aliceChange.play();
-}
-
-bottle.addEventListener("mousedown", shrinkAlice, false);
-bottle.addEventListener("touchstart", shrinkAlice, false);
- -

Em Alice Através do Espelho, Alice viaja para um mundo onde ela deve correr para se manter no lugar — e correr com o dobro de velocidade para avançar! No exemplo da Corrida da Rainha Vermelha, Alice e a Rainha Vermelha estão correndo para se manter no lugar (veja o código completo no Codepen):

- -

Alice and the Red Queen race to get to the next square in this game.

- -

Já que crianças pequenas se cansam facilmente, diferente de peças de xadrez autônomas, Alice está constantemente desacelerando. Nós podemos fazer isso definindo uma queda no playbackRate da animação dela. Usamos o updatePlaybackRate() no lugar de definir manualmente o playbackRate, já que isso produz uma atualização mais suave:

- -
setInterval( function() {
-
-  // Make sure the playback rate never falls below .4
-  if (redQueen_alice.playbackRate > .4) {
-    redQueen_alice.updatePlaybackRate(redQueen_alice.playbackRate * .9);
-  }
-
-}, 3000);
- -

Mas impulsioná-las clicando ou tocando na tela aumenta a velocidade delas por multiplicar o playbackRate:

- -
var goFaster = function() {
-  redQueen_alice.updatePlaybackRate(redQueen_alice.playbackRate * 1.1);
-}
-
-document.addEventListener("click", goFaster);
-document.addEventListener("touchstart", goFaster);
- -

Os elementos do fundo também tem playbackRates que também são afetados pelo clique ou toque na tela. O que acontece quando você faz Alice e a Rainha Vermelha correrem com o dobro da velocidade? O que acontece quando você as deixa desacelerar?

- -

Extraindo informação das animações

- -

Imagine outras maneiras de utilizar o playbackRate, como melhorar a acessibilidade para usuários com disfunções vestibulares permitindo que eles desacelerem as animações do site todo. Isso é impossível de fazer via CSS sem recalcular todas as regras, mas com a Web Animations API, podemos utilizar o método {{domxref("document.getAnimations()")}} para iterar todas animações de uma página e dividir pela metade seu playbackRate, como por exemplo:

- -
document.getAnimations().forEach(
-  function (animation) {
-    animation.updatePlaybackRate(animation.playbackRate * .5);
-  }
-);
- -

Com a Web Animations API, você só precisa mudar uma simples propriedade!

- -

Outra coisa que é difícil de fazer somente com Animações CSS é criar dependências de valores fornecidos por outras animações. Por exemplo, no logo Aumentando e Encolhendo Alice, você pode ter notado algo estranho sobre a duração do bolinho:

- -
duration: aliceChange.effect.getComputedTiming().duration / 2
- -

Para entender o que está acontecendo, vamos dar uma olhada na animação da Alice:

- -
var aliceChange = document.getElementById('alice').animate(
-  [
-    { transform: 'translate(-50%, -50%) scale(.5)' },
-    { transform: 'translate(-50%, -50%) scale(2)' }
-  ], {
-    duration: 8000,
-    easing: 'ease-in-out',
-    fill: 'both'
-  });
- -

A animação da Alice a fazia ir de metade de seu tamanho para o dobro em 8 segundos. Então nós a pausamos:

- -
aliceChange.pause();
- -

Se pausassemos no início da animação, ela começaria com metade de seu tamanho original, como se já tivesse bebido a garrafa toda! Então nós precisamos definir o estado inicial da animação no meio. Podemos fazer isso definindo o {{domxref("Animation.currentTime")}} para 4 segundos, como no exemplo abaixo:

- -
aliceChange.currentTime = 4000;
- -

Mas enquanto trabalhamos nessa animação, vamos mudar bastante a duração da Alice. Não seria melhor definir essa currentTime dinamicamente? Assim não precisariamos fazer duas atualizações de uma vez só. Podemos fazer isso referenciando a propriedade {{domxref("Animation.effect")}}, que retorna um objeto que contém todos os detalhes sobre o(s) efeito(s) ativos na Alice:

- -
aliceChange.currentTime = aliceChange.effect.getComputedTiming().duration / 2;
- -

O effect nos permite acessar os keyframes e propriedades temporais da animação — aliceChange.effect.getComputedTiming() aponta para o objeto timing da Alice (cujo tipo é {{domxref("ComputedEffectTiming")}}) — que contem o {{domxref("ComputedEffectTiming.duration")}} dela. Podemos dividir sua duração pela metade para definir a metade da animação para a linha do tempo da animação da Alice, assim ela começaria com o tamanho normal. Então nós podemos reverter e tocar a animação dela em qualquer direção para encolher ou aumentar seu tamanho!

- -

E nós podemos fazer a mesma coisa quando definimos as durações da garrafa e do bolinho:

- -
var drinking = document.getElementById('liquid').animate(
-[
-  { height: '100%' },
-  { height: '0' }
-], {
-  fill: 'forwards',
-  duration: aliceChange.effect.getComputedTiming().duration / 2
-});
-drinking.pause();
- -

Agora todas as três animações estão ligadas por apenas um duration, que pode ser modificado facilmente em um só lugar do código.

- -

Nós também podemos utilizar a Web Animations API para descobrir o quanto da linha do tempo já foi percorrido. O jogo acaba quando o seu bolinho acaba ou você esvazia a garrafa. A vinheta que é apresentada aos jogadores depende do quão longe a Alice estava em sua animação, seja ficando grande demais pra caber na portinha ou pequena demais pra não conseguir mais alcançar a chave para abrir a porta. Podemos descobrir se ela está nesses extremos pegando o currentTime da sua animação e dividir pelo activeDuration:

- -
var endGame = function() {
-
-  // get Alice's timeline's playhead location
-  var alicePlayhead = aliceChange.currentTime;
-  var aliceTimeline = aliceChange.effect.getComputedTiming().activeDuration;
-
-  // stops Alice's and other animations
-  stopPlayingAlice();
-
-  // depending on which third it falls into
-  var aliceHeight = alicePlayhead / aliceTimeline;
-
-  if (aliceHeight <= .333){
-    // Alice got smaller!
-    ...
-
-  } else if (aliceHeight >= .666) {
-    // Alice got bigger!
-    ...
-
-  } else {
-    // Alice didn't change significantly
-    ...
-
-  }
-}
-
- -
-

Nota: getAnimations() e effect não estão disponíveis em todos os browsers no momento em que este artigo foi escrito, mas o polyfill possibilita utilizá-los agora.

-
- -

Callbacks e promises

- -

Animações e Transições CSS tem seus event listeners próprios, que também são possíveis com a Web Animations API:

- - - -

Aqui nós definimos os callbacks para o bolinho, a garrafa e para Alice para disparar a função endGame:

- -
// When the cake or bottle runs out...
-nommingCake.onfinish = endGame;
-drinking.onfinish = endGame;
-
-// ...or Alice reaches the end of her animation
-aliceChange.onfinish = endGame;
-
-
- -

Ainda melhor, a Web Animations API também fornece uma promise finished que será resolvida quando a animação é completada, e rejeitada se for cancelada.

- -

Conclusão

- -

Essas são as funcionalidades básicas da Web Animations API, a maioria delas já estão sendo suportadas pelas últimas versões do Chrome, Firefox e Safari. Agora você está pronto pra "cair na toca do coelho" de animar utilizando o browser e pronto pra escrever e experimentar com sua própria animação! Se você está utilizando a API e deseja compartilha, tente usar a hashtag #WAAPI. Nós estaremos de olho e vamos escrever mais tutoriais para cobrir funcionalidades futuras assim que o suporte aumentar!

- -

Veja também

- - diff --git a/files/pt-br/web/api/web_animations_api/using_the_web_animations_api/index.html b/files/pt-br/web/api/web_animations_api/using_the_web_animations_api/index.html new file mode 100644 index 0000000000..2743f68d65 --- /dev/null +++ b/files/pt-br/web/api/web_animations_api/using_the_web_animations_api/index.html @@ -0,0 +1,358 @@ +--- +title: Usando a Web Animations API +slug: Web/API/Web_Animations_API/Usando_a_Web_Animations_API +tags: + - Alice + - Animação + - CSS + - Guía + - Iniciante + - JavaScript + - Timing + - Tutorial + - animar + - duration + - keyframes + - pausar + - pause + - play + - quadro-chave + - reverse + - web animations api +translation_of: Web/API/Web_Animations_API/Using_the_Web_Animations_API +--- +

{{DefaultAPISidebar("Web Animations")}}

+ +

A Web Animations API nos possibilita criar animações e controlar sua reprodução pelo JavaScript. Esse artigo vai te demonstrar esses conceitos com demonstrações e tutoriais com o temática de Alice no País das Maravilhas.

+ +

Conhecendo a Web Animations API

+ +

A Web Animations API abre a engine de animação do browser para os desenvolvedores manipularem via JavaScript. Esta API foi construída para se basear nas implementações das Animações CSS e Transições CSS, e deixam a porta aberta para futuros efeitos de animação. É um dos métodos mais performáticos para se animar na Web, permitindo que o browser faça internamente suas próprias otimizações, sem precisar depender de hacks, coerções ou {{domxref("Window.requestAnimationFrame()")}}.

+ +

Com a Web Animations API, podemos transferir as animações interativas das folhas de estilo para o JavaScript, separando comportamento de apresentação. Não vamos precisar mais depender de técnicas muito dependentes do DOM como propriedades do CSS e escopo de classes para controlar a direção da reprodução. E diferente de CSS puro e declarativo, JavaScript também te possibilita definir dinâmicamente valores: de propriedades à duração. Para criar bibilotecas de animação à criar animações interativas, a Web Animations API pode ser a ferramenta perfeita para o trabalho. Vamos ver o que ela pode fazer!

+ +

Suporte de Navegadores

+ +

O suporte básico para as funcionalidades da Web Animations API discutidas neste artigo estão disponíveis no Firefox 48+, Chrome 36+ e Safari 13.1+. Também existe um polyfill prático que verifica o suporte e adiciona as funcionalidades onde for necessário.

+ +

Escrevendo Animações CSS com a Web Animations API

+ +

Uma das maneiras mais familiares de abordar a Web Animations API é começar com algo que boa parte dos desenvolvedores web já utilizaram antes: Animações CSS. Animações CSS tem uma sintaxe familiar que funciona bem para nossa demonstração.

+ +

A versão CSS

+ +

Aqui temos uma animação escrita com CSS mostrando Alice caindo no buraco de coelho que leva ao País das Maravilhas (veja o código completo no Codepen):

+ +

Alice Tumbling down the rabbit's hole.

+ +

Perceba que o fundo se mexe, a Alice gira e sua cor muda em sincronia com o giro. Nós vamos focar somente na Alice para este tutorial. Segue a versão simplificada do CSS que controla a animação da Alice:

+ +
#alice {
+  animation: aliceTumbling infinite 3s linear;
+}
+
+@keyframes aliceTumbling {
+  0% {
+    color: #000;
+    transform: rotate(0) translate3D(-50%, -50%, 0);
+  }
+  30% {
+    color: #431236;
+  }
+  100% {
+    color: #000;
+    transform: rotate(360deg) translate3D(-50%, -50%, 0);
+  }
+}
+ +

Isso muda a cor da Alice e a rotação do `transform` por 3 segundos em um ritmo constante (linear) e se repete infinitamente. No bloco do @keyframes podemos ver que em 30% de cada repetição (por volta dos 900ms), a cor da Alice muda de preto para um vinho, e volta para o preto no final do loop.

+ +

Mudando para o JavaScript

+ +

Agora vamos tentar criar a mesma animação usando a Web Animations API.

+ +

Representando keyframes

+ +

A primeira coisa que precisamos fazer é criar um Objeto Keyframe correspondente ao nosso bloco @keyframes do CSS:

+ +
var aliceTumbling = [
+  { transform: 'rotate(0) translate3D(-50%, -50%, 0)', color: '#000' },
+  { color: '#431236', offset: 0.3},
+  { transform: 'rotate(360deg) translate3D(-50%, -50%, 0)', color: '#000' }
+];
+ +

Aqui estávamos utilizando uma array contendo múltiplos objetos. Cada objeto representa uma chave do CSS original. Contudo, diferente do CSS, a Web Animations API não precisa informar explicitamente as porcentagens temporais para cada chave, o JS automaticamente divide a animação em partes iguais baseado no número de chaves que você forneceu. Isso significa que um objeto Keyframe com três chaves vai reproduzir a chave do meio em 50% do tempo de cada loop, exceto se for definido o contrário.

+ +

Quando queremos explicitamente definir um timing diferente para essas outras chaves, podemos especificar um offset diretamente no objeto, separado do resto da declaração por uma vírgula. No exemplo acima, para definir que a cor da Alice muda em 30% do tempo (e não 50%), nós definiremos como offset: 0.3.

+ +

Atualmente, devem ser definidos pelo menos dois keyframes (representando o início e fim de estado das sequências de animação). Se a sua lista de keyframes somente tem uma entrada, {{domxref("Element.animate()")}} pode disparar uma exceção NotSupportedErro em alguns browsers até eles serem atualizados.

+ +

Então recapitulando: as chaves são espaçadas igualmente por padrão, exceto se você definir um offset para uma chave. Útil, não?

+ +

Representando propriedades temporais

+ +

Nós precisamos criar também um objeto de propriedades temporais (um objeto {{domxref("AnimationEffectTimingProperties")}}) correspondente aos valores da animação da Alice:

+ +
var aliceTiming = {
+  duration: 3000,
+  iterations: Infinity
+}
+ +

Você pode notar algumas diferenças aqui comparando com os valores equivalentes representados no CSS:

+ + + +
+

Existem algumas pequenas diferenças de terminologia entre o CSS Animations e o Web Animations. Por exemplo, Web Animations não usa a string "infinite", e sim a keyword JavaScript Infinity. E no lugar de timing-function, usamos easing. Não estamos citando um valor de easing aqui pois, diferente das Animações CSS onde o valor padrão do animation-timing-function é ease, na Web Animations API o padrão é linear — o que nós já queremos para a animação da Alice.

+
+ +

Juntando as peças

+ +

Agora vamos juntar o que já fizemos com o método {{domxref("Element.animate()")}}:

+ +
document.getElementById("alice").animate(
+  aliceTumbling,
+  aliceTiming
+)
+ +

E pronto: a animação começa a tocar (veja a versão final no Codepen).

+ +

O método animate() pode ser chamado em qualquer elemento do DOM que pode ser animado com CSS. E pode ser escrito de algumas maneiras. Ao invés de criar objetos para os keyframes e propriedades temporais, podemos passar seus valores diretamentes, tipo:

+ +
document.getElementById("alice").animate(
+  [
+    { transform: 'rotate(0) translate3D(-50%, -50%, 0)', color: '#000' },
+    { color: '#431236', offset: 0.3},
+    { transform: 'rotate(360deg) translate3D(-50%, -50%, 0)', color: '#000' }
+  ], {
+    duration: 3000,
+    iterations: Infinity
+  }
+);
+ +

E se nós precisarmos somente especificar a duração da animação e não suas iterações (por padrão, a animação roda uma ), podemos passar só os milisegundos após o array:

+ +
document.getElementById("alice").animate(
+  [
+    { transform: 'rotate(0) translate3D(-50%, -50%, 0)', color: '#000' },
+    { color: '#431236', offset: 0.3},
+    { transform: 'rotate(360deg) translate3D(-50%, -50%, 0)', color: '#000' }
+  ], 3000);
+ +

Controlando a reprodução com play(), pause(), reverse() e updatePlaybackRate()

+ +

Por mais que possamos escrever Animações CSS utilizando a Web Animations API, a API realmente mostra seu potencial quando precisamos manipular a reprodução da animação. A Web Animations API fornece vários métodos úteis para controlar a reprodução. Vamos dar uma olhada em como pausar e tocar animações no jogo da Alice Crescendo/Encolhendo (confira o código completo no Codepen):

+ +

Playing the growing and shrinking game with Alice.

+ +

Nesse jogo, Alice tem uma animação que a encolhe ou aumenta seu tamanho, que controlamos por uma garrafa e um cupcake. Cada um tem sua própria animação.

+ +

Pausando e tocando animações

+ +

Vamos falar sobre a animação da Alice depois, mas por enquanto, vamos dissecar esta animação do cupcake.

+ +
var nommingCake = document.getElementById('eat-me_sprite').animate(
+[
+  { transform: 'translateY(0)' },
+  { transform: 'translateY(-80%)' }
+], {
+  fill: 'forwards',
+  easing: 'steps(4, end)',
+  duration: aliceChange.effect.timing.duration / 2
+});
+ +

O método {{domxref("Element.animate()")}} vai rodar imediatamente depois de ser chamado. Para evitar que o bolinho se coma sozinho antes da interação do usuário, chamamos o {{domxref("Animation.pause()")}} imediatamente depois de criar a animação:

+ +
nommingCake.pause();
+ +

Agora nós podemos usar o método {{domxref("Animation.play()")}} para rodar assim que for o momento:

+ +
nommingCake.play();
+ +

Especificamente, nós queremos linka-lo à animação da Alice, para ela crescer assim que o cupcake é mordido. Podemos fazer isso com a seguinte função:

+ +
var growAlice = function() {
+
+  // Play Alice's animation.
+  aliceChange.play();
+
+  // Play the cake's animation.
+  nommingCake.play();
+
+}
+ +

Quando o usuário clicar ou pressionar seu dedo no bolinho em uma tela de toque, podemos chamar a função growAlice para fazer todas as animações tocarem:

+ +
cake.addEventListener("mousedown", growAlice, false);
+cake.addEventListener("touchstart", growAlice, false);
+ +

Outros métodos úteis

+ + + +

Vamos dar uma olhada primeiro no método playbackRate — um valor negativo vai fazer a animação tocar ao contrário. Quando Alice bebe da garrafa, ela encolhe. Isso porque a garrafa muda o playbackRate da animação de 1 para -1:

+ +
var shrinkAlice = function() {
+  aliceChange.playbackRate = -1;
+  aliceChange.play();
+}
+
+bottle.addEventListener("mousedown", shrinkAlice, false);
+bottle.addEventListener("touchstart", shrinkAlice, false);
+ +

Em Alice Através do Espelho, Alice viaja para um mundo onde ela deve correr para se manter no lugar — e correr com o dobro de velocidade para avançar! No exemplo da Corrida da Rainha Vermelha, Alice e a Rainha Vermelha estão correndo para se manter no lugar (veja o código completo no Codepen):

+ +

Alice and the Red Queen race to get to the next square in this game.

+ +

Já que crianças pequenas se cansam facilmente, diferente de peças de xadrez autônomas, Alice está constantemente desacelerando. Nós podemos fazer isso definindo uma queda no playbackRate da animação dela. Usamos o updatePlaybackRate() no lugar de definir manualmente o playbackRate, já que isso produz uma atualização mais suave:

+ +
setInterval( function() {
+
+  // Make sure the playback rate never falls below .4
+  if (redQueen_alice.playbackRate > .4) {
+    redQueen_alice.updatePlaybackRate(redQueen_alice.playbackRate * .9);
+  }
+
+}, 3000);
+ +

Mas impulsioná-las clicando ou tocando na tela aumenta a velocidade delas por multiplicar o playbackRate:

+ +
var goFaster = function() {
+  redQueen_alice.updatePlaybackRate(redQueen_alice.playbackRate * 1.1);
+}
+
+document.addEventListener("click", goFaster);
+document.addEventListener("touchstart", goFaster);
+ +

Os elementos do fundo também tem playbackRates que também são afetados pelo clique ou toque na tela. O que acontece quando você faz Alice e a Rainha Vermelha correrem com o dobro da velocidade? O que acontece quando você as deixa desacelerar?

+ +

Extraindo informação das animações

+ +

Imagine outras maneiras de utilizar o playbackRate, como melhorar a acessibilidade para usuários com disfunções vestibulares permitindo que eles desacelerem as animações do site todo. Isso é impossível de fazer via CSS sem recalcular todas as regras, mas com a Web Animations API, podemos utilizar o método {{domxref("document.getAnimations()")}} para iterar todas animações de uma página e dividir pela metade seu playbackRate, como por exemplo:

+ +
document.getAnimations().forEach(
+  function (animation) {
+    animation.updatePlaybackRate(animation.playbackRate * .5);
+  }
+);
+ +

Com a Web Animations API, você só precisa mudar uma simples propriedade!

+ +

Outra coisa que é difícil de fazer somente com Animações CSS é criar dependências de valores fornecidos por outras animações. Por exemplo, no logo Aumentando e Encolhendo Alice, você pode ter notado algo estranho sobre a duração do bolinho:

+ +
duration: aliceChange.effect.getComputedTiming().duration / 2
+ +

Para entender o que está acontecendo, vamos dar uma olhada na animação da Alice:

+ +
var aliceChange = document.getElementById('alice').animate(
+  [
+    { transform: 'translate(-50%, -50%) scale(.5)' },
+    { transform: 'translate(-50%, -50%) scale(2)' }
+  ], {
+    duration: 8000,
+    easing: 'ease-in-out',
+    fill: 'both'
+  });
+ +

A animação da Alice a fazia ir de metade de seu tamanho para o dobro em 8 segundos. Então nós a pausamos:

+ +
aliceChange.pause();
+ +

Se pausassemos no início da animação, ela começaria com metade de seu tamanho original, como se já tivesse bebido a garrafa toda! Então nós precisamos definir o estado inicial da animação no meio. Podemos fazer isso definindo o {{domxref("Animation.currentTime")}} para 4 segundos, como no exemplo abaixo:

+ +
aliceChange.currentTime = 4000;
+ +

Mas enquanto trabalhamos nessa animação, vamos mudar bastante a duração da Alice. Não seria melhor definir essa currentTime dinamicamente? Assim não precisariamos fazer duas atualizações de uma vez só. Podemos fazer isso referenciando a propriedade {{domxref("Animation.effect")}}, que retorna um objeto que contém todos os detalhes sobre o(s) efeito(s) ativos na Alice:

+ +
aliceChange.currentTime = aliceChange.effect.getComputedTiming().duration / 2;
+ +

O effect nos permite acessar os keyframes e propriedades temporais da animação — aliceChange.effect.getComputedTiming() aponta para o objeto timing da Alice (cujo tipo é {{domxref("ComputedEffectTiming")}}) — que contem o {{domxref("ComputedEffectTiming.duration")}} dela. Podemos dividir sua duração pela metade para definir a metade da animação para a linha do tempo da animação da Alice, assim ela começaria com o tamanho normal. Então nós podemos reverter e tocar a animação dela em qualquer direção para encolher ou aumentar seu tamanho!

+ +

E nós podemos fazer a mesma coisa quando definimos as durações da garrafa e do bolinho:

+ +
var drinking = document.getElementById('liquid').animate(
+[
+  { height: '100%' },
+  { height: '0' }
+], {
+  fill: 'forwards',
+  duration: aliceChange.effect.getComputedTiming().duration / 2
+});
+drinking.pause();
+ +

Agora todas as três animações estão ligadas por apenas um duration, que pode ser modificado facilmente em um só lugar do código.

+ +

Nós também podemos utilizar a Web Animations API para descobrir o quanto da linha do tempo já foi percorrido. O jogo acaba quando o seu bolinho acaba ou você esvazia a garrafa. A vinheta que é apresentada aos jogadores depende do quão longe a Alice estava em sua animação, seja ficando grande demais pra caber na portinha ou pequena demais pra não conseguir mais alcançar a chave para abrir a porta. Podemos descobrir se ela está nesses extremos pegando o currentTime da sua animação e dividir pelo activeDuration:

+ +
var endGame = function() {
+
+  // get Alice's timeline's playhead location
+  var alicePlayhead = aliceChange.currentTime;
+  var aliceTimeline = aliceChange.effect.getComputedTiming().activeDuration;
+
+  // stops Alice's and other animations
+  stopPlayingAlice();
+
+  // depending on which third it falls into
+  var aliceHeight = alicePlayhead / aliceTimeline;
+
+  if (aliceHeight <= .333){
+    // Alice got smaller!
+    ...
+
+  } else if (aliceHeight >= .666) {
+    // Alice got bigger!
+    ...
+
+  } else {
+    // Alice didn't change significantly
+    ...
+
+  }
+}
+
+ +
+

Nota: getAnimations() e effect não estão disponíveis em todos os browsers no momento em que este artigo foi escrito, mas o polyfill possibilita utilizá-los agora.

+
+ +

Callbacks e promises

+ +

Animações e Transições CSS tem seus event listeners próprios, que também são possíveis com a Web Animations API:

+ + + +

Aqui nós definimos os callbacks para o bolinho, a garrafa e para Alice para disparar a função endGame:

+ +
// When the cake or bottle runs out...
+nommingCake.onfinish = endGame;
+drinking.onfinish = endGame;
+
+// ...or Alice reaches the end of her animation
+aliceChange.onfinish = endGame;
+
+
+ +

Ainda melhor, a Web Animations API também fornece uma promise finished que será resolvida quando a animação é completada, e rejeitada se for cancelada.

+ +

Conclusão

+ +

Essas são as funcionalidades básicas da Web Animations API, a maioria delas já estão sendo suportadas pelas últimas versões do Chrome, Firefox e Safari. Agora você está pronto pra "cair na toca do coelho" de animar utilizando o browser e pronto pra escrever e experimentar com sua própria animação! Se você está utilizando a API e deseja compartilha, tente usar a hashtag #WAAPI. Nós estaremos de olho e vamos escrever mais tutoriais para cobrir funcionalidades futuras assim que o suporte aumentar!

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/web_audio_api/index.html b/files/pt-br/web/api/web_audio_api/index.html new file mode 100644 index 0000000000..8f582eb524 --- /dev/null +++ b/files/pt-br/web/api/web_audio_api/index.html @@ -0,0 +1,480 @@ +--- +title: API Web Áudio +slug: Web/API/API_Web_Audio +tags: + - Web Audio API + - api de áudio + - áudio api + - áudio web +translation_of: Web/API/Web_Audio_API +--- +
+

A API de áudio da web disponibiliza um poderoso e versátil sistema de controle de áudio para a Web, permitindo aos desenvolvedores escolher arquivos de áudio, adicionar efeitos a estes arquivos, criar reprodutores de áudio, aplicar spatial effects (como panning) e muito mais.

+
+ +

Web audio: conceitos e uso

+ +

A API de Web audio envolve manipulação de operações com áudio dentro de um contexto de áudio, e foi desenvolvida para permitir o roteamento modular. Operações básicas de áudio são feitas com audio nodes (nós de áudio), que são ligados para formar gráficos de roteamento de áudio. Várias fontes - com diferentes tipos de layout de canal - são suportados mesmo em um único contexto. Este design modular permite flexibilidade para criar funções de áudio complexas com efeitos dinâmicos.

+ +

Audio nodes são ligados pelas suas entradas e saídas, formando uma cadeia que começa com uma ou mais fontes, passa por um ou mais nodes e então acaba em um destino (embora você não tenha que fornecer um destino, por exemplo, se você quiser apenas visualizar alguns dados de áudio). Um fluxo de trabalho simples, com Web áudio, seria algo parecido com isso:

+ +
    +
  1. Crie um contexto de áudio
    2. +
  2. Dentro do contexto, crie fontes de áudio — como <audio>, oscilador, stream
    3. +
  3. Crie efeitos de áudio, como reverb, biquad filter, panner, compressor
    4. +
  4. Escolha o destino final de áudio, por exemplo os auto-falantes de seu sistema
    5. +
  5. Conecte as fontes de áudio com os efeitos, e os efeitos com o destino.
    6. +
+ +

A simple box diagram with an outer box labeled Audio context, and three inner boxes labeled Sources, Effects and Destination. The three inner boxes have arrow between them pointing from left to right, indicating the flow of audio information.

+ +

O sincronismo é controlado com alta precisão e baixa latência, permitindo aos desenvolvedores escrever códigos que respondam com precisão a eventos e capazes de gerar exemplos específicos, mesmo com uma alta taxa de amostragem. Dessa forma, aplicações como baterias eletrônicas e seqüenciadores estarão facilmente ao alcance dos desenvolvedores.

+ +

A API de Web Audio também permite o controle de como o áudio será ordenado. Usando um sistema baseado em um modelo de source-listener, a API permite controlar os painéis de modelo para serem usados e tratados com atenuação de distância induzida ou doppler shift induzido por uma fonte em movimento (ou um ouvinte em movimento).

+ +
+

Nota: Você pode ver mais detalhes sobre a teoria da API de Web Audio em nosso artigo Basic concepts behind Web Audio API.

+
+ +

Web Audio: Interfaces da API

+ +

A API de Web Audio possui um total de 28 interfaces e eventos associados, que nós dividimos e categorizamos em 9 funcionalidades.

+ +

Definições gerais de grafos de áudio (audio graph)

+ +

Definições gerais que moldam os grafos de áudio no uso da API de Web Audio.

+ +
+
{{domxref("AudioContext")}}
+
A interface AudioContext representa um grafo de processamento de áudio construído a partir de módulos de áudio ligados entre si, cada um representado por um {{domxref("AudioNode")}}. Um contexto de áudio (audio context) controla a criação dosnós que ele contém e a execução do processamento de áudio, ou a decodificação. Como tudo acontece dentro de um contexto, você deve criar um AudioContext antes de fazer qualquer outra coisa.
+
{{domxref("AudioNode")}}
+
A interface AudioNode representa um módulo de processamento de áudio como uma fonte de áudio (por exemplo, um HTML {{HTMLElement("áudio")}} ou um elemento {{HTMLElement("vídeo")}}), destino de áudio, módulo de processamento intermediário (por exemplo, um filtro como {{domxref("BiquadFilterNode")}}, ou controle de volume, como {{domxref("GainNode")}}).
+
{{domxref("AudioParam")}}
+
A interface AudioParam representa um parâmetro relacionado ao áudio, como um parâmetro de um {{domxref("AudioNode")}}. Ele pode ser configurado com um valor específico ou uma mudança de valor, e pode ser programado para "acontecer" em um momento específico e seguindo um padrão específico.
+
{{event("ended_(Web_Audio)", "ended")}} (event)
+
O evento ended é disparado quando a reprodução parou porque o fim da mídia foi atingido.
+
+ +

Definindo fontes de áudio

+ +

Interfaces que definem fontes de áudio para uso na API de Web Audio.

+ +
+
{{domxref("OscillatorNode")}}
+
A interface OscillatorNode representa uma onda senoidal. Esta interface é um módulo de processamento de áudio que gera uma onda senoidal com determinada frequência.
+
{{domxref("AudioBuffer")}}
+
A interface AudioBuffer representa uma pequena porção de áudio armazenada na memória, criada a partir de um arquivo de áudio usando o método {{ domxref("AudioContext.decodeAudioData()") }}, ou criado com os dados brutos usando o método {{ domxref("AudioContext.createBuffer()") }}. Uma vez decodificado neste formato o áudio pode ser colocada em um {{ domxref("AudioBufferSourceNode") }}.
+
{{domxref("AudioBufferSourceNode")}}
+
A interface AudioBufferSourceNode representa uma fonte de áudio que consiste em dados de áudio na memória, armazenados em um {{domxref ("AudioBuffer")}}. É um {{domxref ("AudioNode")}} que atua como uma fonte de áudio.
+
{{domxref("MediaElementAudioSourceNode")}}
+
A interface MediaElementAudioSourceNode  representa uma fonte de audio consiste de um HTML5 {{ htmlelement("audio") }} ou {{ htmlelement("video") }} elemento. É uma {{domxref("AudioNode")}} que atua como uma fonte de áudio.
+
{{domxref("MediaStreamAudioSourceNode")}}
+
The MediaStreamAudioSourceNode interface represents an audio source consisting of a WebRTC {{domxref("MediaStream")}} (such as a webcam or microphone.) It is an {{domxref("AudioNode")}} that acts as an audio source.
+
+ +

Definindo filtros de efeitos de áudio

+ +

Interfaces para definição de efeitos que você deseja aplicar em suas fontes de áudio.

+ +
+
{{domxref("BiquadFilterNode")}}
+
The BiquadFilterNode interface represents a simple low-order filter. It is an {{domxref("AudioNode")}} that can represent different kinds of filters, tone control devices or graphic equalizers. A BiquadFilterNode always has exactly one input and one output.
+
{{domxref("ConvolverNode")}}
+
The ConvolverNode interface is an {{domxref("AudioNode")}} that performs a Linear Convolution on a given AudioBuffer, often used to achieve a reverb effect.
+
{{domxref("DelayNode")}}
+
The DelayNode interface represents a delay-line; an {{domxref("AudioNode")}} audio-processing module that causes a delay between the arrival of an input data and its propagation to the output.
+
{{domxref("DynamicsCompressorNode")}}
+
The DynamicsCompressorNode interface provides a compression effect, which lowers the volume of the loudest parts of the signal in order to help prevent clipping and distortion that can occur when multiple sounds are played and multiplexed together at once.
+
{{domxref("GainNode")}}
+
The GainNode interface represents a change in volume. It is an {{domxref("AudioNode")}} audio-processing module that causes a given gain to be applied to the input data before its propagation to the output.
+
{{domxref("WaveShaperNode")}}
+
The WaveShaperNode interface represents a non-linear distorter. It is an {{domxref("AudioNode")}} that use a curve to apply a waveshaping distortion to the signal. Beside obvious distortion effects, it is often used to add a warm feeling to the signal.
+
{{domxref("PeriodicWave")}}
+
Used to define a periodic waveform that can be used to shape the output of an {{ domxref("OscillatorNode") }}.
+
+ +

Definindo destinos de áudio

+ +

Uma vez que você tenha feito o processamento do seu áudio, estas interfaces definirão aonde será a saída do áudio.

+ +
+
{{domxref("AudioDestinationNode")}}
+
The AudioDestinationNode interface represents the end destination of an audio source in a given context — usually the speakers of your device.
+
{{domxref("MediaStreamAudioDestinationNode")}}
+
The MediaElementAudioSourceNode interface represents an audio destination consisting of a WebRTC {{domxref("MediaStream")}} with a single AudioMediaStreamTrack, which can be used in a similar way to a MediaStream obtained from {{ domxref("Navigator.getUserMedia") }}. It is an {{domxref("AudioNode")}} that acts as an audio destination.
+
+ +

Análise dos dados e visualização

+ +

Se você deseja extrair tempo, frequencia e outras informações do seu áudio, o AnalyserNode é o que você necessita.

+ +
+
{{domxref("AnalyserNode")}}
+
The AnalyserNode interface represents a node able to provide real-time frequency and time-domain analysis information, for the purposes of data analysis and visualization.
+
+ +

Dividindo e mesclando canais de áudio

+ +

Para dividir e mesclar canais de áudio, você utilizará essas interfaces.

+ +
+
{{domxref("ChannelSplitterNode")}}
+
The ChannelSplitterNode interface separates the different channels of an audio source out into a set of mono outputs.
+
{{domxref("ChannelMergerNode")}}
+
The ChannelMergerNode interface reunites different mono inputs into a single outputs. Each input will be used to fill a channel of the output.
+
+ +

Audio spatialization

+ +

These interfaces allow you to add audio spatialization panning effects to your audio sources.

+ +
+
{{domxref("AudioListener")}}
+
The AudioListener interface represents the position and orientation of the unique person listening to the audio scene used in audio spatialization.
+
{{domxref("PannerNode")}}
+
The PannerNode interface represents the behavior of a signal in space. It is an {{domxref("AudioNode")}} audio-processing module describing its position with right-hand Cartesian coordinates, its movement using a velocity vector and its directionality using a directionality cone.
+
+ +

Processamento de áudio por JavaScript

+ +

Se você quiser usar um script externo para processar sua fonte de áudio, Node e eventos abaixo tornarão isto possível.

+ +
+
{{domxref("ScriptProcessorNode")}}
+
The ScriptProcessorNode interface allows the generation, processing, or analyzing of audio using JavaScript. It is an {{domxref("AudioNode")}} audio-processing module that is linked to two buffers, one containing the current input, one containing the output. An event, implementing the {{domxref("AudioProcessingEvent")}} interface, is sent to the object each time the input buffer contains new data, and the event handler terminates when it has filled the output buffer with data.
+
{{event("audioprocess")}} (event)
+
The audioprocess event is fired when an input buffer of a Web Audio API {{domxref("ScriptProcessorNode")}} is ready to be processed.
+
{{domxref("AudioProcessingEvent")}}
+
The Web Audio API AudioProcessingEvent represents events that occur when a {{domxref("ScriptProcessorNode")}} input buffer is ready to be processed.
+
+ +

Áudio offline

+ +

Manipular áudio offline é possível com estas interfaces.

+ +
+
{{domxref("OfflineAudioContext")}}
+
The OfflineAudioContext interface is an {{domxref("AudioContext")}} interface representing an audio-processing graph built from linked together {{domxref("AudioNode")}}s. In contrast with a standard AudioContext, an OfflineAudioContext doesn't really render the audio but rather generates it, as fast as it can, in a buffer.
+
{{event("complete")}} (event)
+
The complete event is fired when the rendering of an {{domxref("OfflineAudioContext")}} is terminated.
+
{{domxref("OfflineAudioCompletionEvent")}}
+
The OfflineAudioCompletionEvent represents events that occur when the processing of an {{domxref("OfflineAudioContext")}} is terminated. The {{event("complete")}} event implements this interface.
+
+ +

Interfaces obsoletas

+ +

As interfaces a seguir foram definidas em versões antigas das especificações da API de Web Audio, mas agora elas estão obsoletas e serão substituidas por outras interfaces.

+ +
+
{{domxref("JavaScriptNode")}}
+
Used for direct audio processing via JavaScript. This interface is obsolete, and has been replaced by {{domxref("ScriptProcessorNode")}}.
+
{{domxref("WaveTableNode")}}
+
Used to define a periodic waveform. This interface is obsolete, and has been replaced by {{domxref("PeriodicWave")}}.
+
+ +

Exemplo

+ +

Este exemplo mostra uma grande variedade de funções da API de Web Audio que podem ser utilizadas. Você pode ver este código em ação na demo Voice-change-o-matic (também verificar o código-fonte completo no Github) - esta é uma demonstração de um modificador de voz de brinquedo experimental; aconselhamos manter seus alto-falantes baixo ao utilizá-lo, pelo menos para começar!

+ +

As linhas API de Web Audio estão destacadas; se você quiser encontrar mais informações sobre os diferentes métodos, faça uma busca através das páginas de referência.

+ +
var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); // define audio context
+// Webkit/blink browsers need prefix, Safari won't work without window.
+
+var voiceSelect = document.getElementById("voice"); // select box for selecting voice effect options
+var visualSelect = document.getElementById("visual"); // select box for selecting audio visualization options
+var mute = document.querySelector('.mute'); // mute button
+var drawVisual; // requestAnimationFrame
+
+var analyser = audioCtx.createAnalyser();
+var distortion = audioCtx.createWaveShaper();
+var gainNode = audioCtx.createGain();
+var biquadFilter = audioCtx.createBiquadFilter();
+
+function makeDistortionCurve(amount) { // function to make curve shape for distortion/wave shaper node to use
+  var k = typeof amount === 'number' ? amount : 50,
+    n_samples = 44100,
+    curve = new Float32Array(n_samples),
+    deg = Math.PI / 180,
+    i = 0,
+    x;
+  for ( ; i < n_samples; ++i ) {
+    x = i * 2 / n_samples - 1;
+    curve[i] = ( 3 + k ) * x * 20 * deg / ( Math.PI + k * Math.abs(x) );
+  }
+  return curve;
+};
+
+navigator.getUserMedia (
+  // constraints - only audio needed for this app
+  {
+    audio: true
+  },
+
+  // Success callback
+  function(stream) {
+    source = audioCtx.createMediaStreamSource(stream);
+    source.connect(analyser);
+    analyser.connect(distortion);
+    distortion.connect(biquadFilter);
+    biquadFilter.connect(gainNode);
+    gainNode.connect(audioCtx.destination); // connecting the different audio graph nodes together
+
+    visualize(stream);
+    voiceChange();
+
+  },
+
+  // Error callback
+  function(err) {
+    console.log('The following gUM error occured: ' + err);
+  }
+);
+
+function visualize(stream) {
+  WIDTH = canvas.width;
+  HEIGHT = canvas.height;
+
+  var visualSetting = visualSelect.value;
+  console.log(visualSetting);
+
+  if(visualSetting == "sinewave") {
+    analyser.fftSize = 2048;
+    var bufferLength = analyser.frequencyBinCount; // half the FFT value
+    var dataArray = new Uint8Array(bufferLength); // create an array to store the data
+
+    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);
+
+    function draw() {
+
+      drawVisual = requestAnimationFrame(draw);
+
+      analyser.getByteTimeDomainData(dataArray); // get waveform data and put it into the array created above
+
+      canvasCtx.fillStyle = 'rgb(200, 200, 200)'; // draw wave with canvas
+      canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);
+
+      canvasCtx.lineWidth = 2;
+      canvasCtx.strokeStyle = 'rgb(0, 0, 0)';
+
+      canvasCtx.beginPath();
+
+      var sliceWidth = WIDTH * 1.0 / bufferLength;
+      var x = 0;
+
+      for(var i = 0; i < bufferLength; i++) {
+
+        var v = dataArray[i] / 128.0;
+        var y = v * HEIGHT/2;
+
+        if(i === 0) {
+          canvasCtx.moveTo(x, y);
+        } else {
+          canvasCtx.lineTo(x, y);
+        }
+
+        x += sliceWidth;
+      }
+
+      canvasCtx.lineTo(canvas.width, canvas.height/2);
+      canvasCtx.stroke();
+    };
+
+    draw();
+
+  } else if(visualSetting == "off") {
+    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);
+    canvasCtx.fillStyle = "red";
+    canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);
+  }
+
+}
+
+function voiceChange() {
+  distortion.curve = new Float32Array;
+  biquadFilter.gain.value = 0; // reset the effects each time the voiceChange function is run
+
+  var voiceSetting = voiceSelect.value;
+  console.log(voiceSetting);
+
+  if(voiceSetting == "distortion") {
+    distortion.curve = makeDistortionCurve(400); // apply distortion to sound using waveshaper node
+  } else if(voiceSetting == "biquad") {
+    biquadFilter.type = "lowshelf";
+    biquadFilter.frequency.value = 1000;
+    biquadFilter.gain.value = 25; // apply lowshelf filter to sounds using biquad
+  } else if(voiceSetting == "off") {
+    console.log("Voice settings turned off"); // do nothing, as off option was chosen
+  }
+
+}
+
+// event listeners to change visualize and voice settings
+
+visualSelect.onchange = function() {
+  window.cancelAnimationFrame(drawVisual);
+  visualize(stream);
+}
+
+voiceSelect.onchange = function() {
+  voiceChange();
+}
+
+mute.onclick = voiceMute;
+
+function voiceMute() { // toggle to mute and unmute sound
+  if(mute.id == "") {
+    gainNode.gain.value = 0; // gain set to 0 to mute sound
+    mute.id = "activated";
+    mute.innerHTML = "Unmute";
+  } else {
+    gainNode.gain.value = 1; // gain set to 1 to unmute sound
+    mute.id = "";
+    mute.innerHTML = "Mute";
+  }
+}
+
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('Web Audio API')}}{{Spec2('Web Audio API')}} 
+ +

Compatibilidade de navegadores

+ +
{{CompatibilityTable}}
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support14 {{property_prefix("webkit")}}23{{CompatNo}}15 {{property_prefix("webkit")}}
+ 22 (unprefixed)		6 {{property_prefix("webkit")}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChromeFirefox Mobile (Gecko)Firefox OSIE PhoneOpera MobileSafari Mobile
Basic support{{CompatNo}}28 {{property_prefix("webkit")}}251.2{{CompatNo}}{{CompatNo}}6 {{property_prefix("webkit")}}
+
+ +

 

+ +

Veja também

+ + + + diff --git a/files/pt-br/web/api/web_audio_api/simple_synth/index.html b/files/pt-br/web/api/web_audio_api/simple_synth/index.html new file mode 100644 index 0000000000..b0fdf2a0c4 --- /dev/null +++ b/files/pt-br/web/api/web_audio_api/simple_synth/index.html @@ -0,0 +1,579 @@ +--- +title: 'Tutorial e exemplo: Teclado de Sintetizador Simples' +slug: Web/API/API_Web_Audio/Sintetizador_simples +tags: + - Audio + - Exemplo + - Guía + - Media + - Oscilador + - Piano + - Sintetizador + - Tutorial + - Web Audio API +translation_of: Web/API/Web_Audio_API/Simple_synth +--- +
{{DefaultAPISidebar("Web Audio API")}}
+ +

Este artigo apresenta o código e uma demonstração funcional de um teclado que você pode tocar usando seu mouse. O teclado lhe permite alternar entre formas de onda padrões e customizadas. Esse exemplo utiliza das seguintes interfaces de Web API: {{domxref("AudioContext")}}, {{domxref("OscillatorNode")}}, {{domxref("PeriodicWave")}}, e {{domxref("GainNode")}}.

+ +

Já que {{domxref("OscillatorNode")}} é baseado no {{domxref("AudioScheduledSourceNode")}}, isso até certo ponto também é um exemplo pra isto.

+ +

O Teclado Visual

+ +

HTML

+ +

Existem três componentes primários para o display do nosso teclado virtual. O primeito do qual é o teclado musical em si. Nós extraimos em um par de elementos {{HTMLElement("div")}} aninhados para permitir a rolagem horizontal caso as teclas não encaixem na tela.

+ +

O Teclado

+ +

Primeiro, criamos o espaço no qual construiremos o teclado. Estaremos construindo o teclado programaticamente, considerando que ao fazer desse jeito teremos a flexibilidade de configurar cada tecla conforme determinamos as informações apropriadas para tecla correspondente. No nosso caso, pegamos a frequência de cada tecla através de uma tabela, mas poderia ser calculado de forma algoritmica também.

+ +
<div class="container">
+  <div class="keyboard"></div>
+</div>
+
+ +

O {{HTMLElement("div")}} nomeado de "container" é a barra de rolagem que permite o teclado ser rolado horizontalmente se for largo demais para o espaço disponivel. As teclas em si serão inseridas no bloco de classe "keyboard".

+ +

A barra de opções

+ +

Abaixo do teclado, colocaremos alguns controles para configurar o camada. Por enquanto, teremos dois controles: Um para controlar o volume e outro para selecionar a forma de onda periodica usada ao gerar as notas.

+ +
O controle de volume
+ +

Primeiro criamos o <div> para conter a barra de opções, para ser personalizado conforme preciso. Então estabelecemos uma caixa que será apresentada no lado esquerdo da barra e colocar um rotulo e um elemento {{HTMLElement("input")}} do tipo "range". O elemento range será tipicamente apresentado como o controle da barra de rolagem ; configuramos ele para permitir qualquer valor entre 0.0 e 1.0 em cada posição.

+ +
<div class="settingsBar">
+  <div class="left">
+    <span>Volume: </span>
+    <input type="range" min="0.0" max="1.0" step="0.01"
+        value="0.5" list="volumes" name="volume">
+    <datalist id="volumes">
+      <option value="0.0" label="Mute">
+      <option value="1.0" label="100%">
+    </datalist>
+  </div>
+
+ +

Especificamos um valor padrão de 0.5, e provemos um elemento {{HTMLElement("datalist")}} no qual é conectado ao range usando o atributo {{htmlattrxref("name")}} para achar uma lista de opções cujo ID encaixa; nesse caso, o conjunto de informações é nomeado de "volume". isso nos permite prover um conjunto de valores comuns e strings especiais que o browser pode de forma opcional escolher mostrar de alguma maneira; e então atribuimos nomes aos valores 0.0 ("Mute") e 1.0 ("100%").

+ +
A seleção de forma de onda
+ +

E no lado da barra de configurações, colocamos um rótulo e um elemento {{HTMLElement("select")}} nomeado de "waveform" cujas opções correspondem as formas de onda disponiveis.

+ +
  <div class="right">
+    <span>Current waveform: </span>
+    <select name="waveform">
+      <option value="sine">Sine</option>
+      <option value="square" selected>Square</option>
+      <option value="sawtooth">Sawtooth</option>
+      <option value="triangle">Triangle</option>
+      <option value="custom">Custom</option>
+    </select>
+  </div>
+</div>
+ + + +

JavaScript

+ +

O código em JavaScript começa inicializando algumas váriaveis.

+ +
let audioContext = new (window.AudioContext || window.webkitAudioContext)();
+let oscList = [];
+let masterGainNode = null;
+
+ +
    +
  1. audioContext é colocado para referenciar o objeto global {{domxref("AudioContext")}} (ou webkitAudioContext se  necessário).
    2. +
  2. oscillators está colocado para conter uma lista de todos os osciladores atualmente tocando. Ele começa nulo, afinal não há nenhum oscilador tocando ainda.
    3. +
  3. masterGainNode é colocado como nulo; durante o processo de setup, ele será configurado para contar um {{domxref("GainNode")}} no quall todos os osciladores irão se conectar para permitir o volume geral a ser controlado por apenas uma barra de rolagem.
    4. +
+ +
let keyboard = document.querySelector(".keyboard");
+let wavePicker = document.querySelector("select[name='waveform']");
+let volumeControl = document.querySelector("input[name='volume']");
+
+ +

Referencias aos elementos que precisaremos acessar são obtidas através dp:

+ + + +
let noteFreq = null;
+let customWaveform = null;
+let sineTerms = null;
+let cosineTerms = null;
+
+ +

Enfim, variaveis globais que serão usadas quando as formas de onda são criadas:

+ + + +

Criando a tabela de notas

+ +

A função createNoteTable() constrói a matriz noteFreq para conter uma matriz de objetos representando cada oitava. Cada oitava, possui uma propriedade para cada nota nessa oitava; O nome dessa propriedade é o nome da nota (utilizando da notação em inglês, como "C" para representar "dó"), e o valor é a frequência, em Hertz, daquela nota.

+ +
function createNoteTable() {
+  let noteFreq = [];
+  for (let i=0; i< 9; i++) {
+    noteFreq[i] = [];
+  }
+
+  noteFreq[0]["A"] = 27.500000000000000;
+  noteFreq[0]["A#"] = 29.135235094880619;
+  noteFreq[0]["B"] = 30.867706328507756;
+
+  noteFreq[1]["C"] = 32.703195662574829;
+  noteFreq[1]["C#"] = 34.647828872109012;
+  noteFreq[1]["D"] = 36.708095989675945;
+  noteFreq[1]["D#"] = 38.890872965260113;
+  noteFreq[1]["E"] = 41.203444614108741;
+  noteFreq[1]["F"] = 43.653528929125485;
+  noteFreq[1]["F#"] = 46.249302838954299;
+  noteFreq[1]["G"] = 48.999429497718661;
+  noteFreq[1]["G#"] = 51.913087197493142;
+  noteFreq[1]["A"] = 55.000000000000000;
+  noteFreq[1]["A#"] = 58.270470189761239;
+  noteFreq[1]["B"] = 61.735412657015513;
+
+ +

... várias oitavas não mostradas para manter breve ...

+ + + +
  noteFreq[7]["C"] = 2093.004522404789077;
+  noteFreq[7]["C#"] = 2217.461047814976769;
+  noteFreq[7]["D"] = 2349.318143339260482;
+  noteFreq[7]["D#"] = 2489.015869776647285;
+  noteFreq[7]["E"] = 2637.020455302959437;
+  noteFreq[7]["F"] = 2793.825851464031075;
+  noteFreq[7]["F#"] = 2959.955381693075191;
+  noteFreq[7]["G"] = 3135.963487853994352;
+  noteFreq[7]["G#"] = 3322.437580639561108;
+  noteFreq[7]["A"] = 3520.000000000000000;
+  noteFreq[7]["A#"] = 3729.310092144719331;
+  noteFreq[7]["B"] = 3951.066410048992894;
+
+  noteFreq[8]["C"] = 4186.009044809578154;
+  return noteFreq;
+}
+
+ +

O resultado é uma matriz, noteFreq, com um objeto para cada oitava. Cada objeto de oitava tem propriedades nomeadas nela onde a propriedade é o nome da nota com a notação em inglês (Como "C" para representar "dó") e o valor da propriedade é a frequência da nota em Hertz.. o objeto resultando se parece com isso:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OctaveNotes
0"A" ⇒ 27.5"A#" ⇒ 29.14"B" ⇒ 30.87
1"C" ⇒ 32.70"C#" ⇒ 34.65"D" ⇒ 36.71"D#" ⇒ 38.89"E" ⇒ 41.20"F" ⇒ 43.65"F#" ⇒ 46.25"G" ⇒ 49"G#" ⇒ 51.9"A" ⇒ 55"A#" ⇒ 58.27"B" ⇒ 61.74
2. . .
+ +

Com esta tabela no lugar, podemos descobrir a frequência para uma dada nota em uma oitava particular relativamente fácil. Se queremos a frequência pra nota G# na primeira oitava, nós simplesmente usamos  noteFreq[1]["G#"] e conseguimos o valor 51.9 como resultado.

+ +
+

Os valores na tabela de exemplo acima foram arredondados para duas casas decimais.

+
+ + + +

Construindo o teclado

+ +

A função setup() é responsavel por construir o teclado e preparar a aplicação para tocar a música.

+ +
function setup() {
+  noteFreq = createNoteTable();
+
+  volumeControl.addEventListener("change", changeVolume, false);
+
+  masterGainNode = audioContext.createGain();
+  masterGainNode.connect(audioContext.destination);
+  masterGainNode.gain.value = volumeControl.value;
+
+  // Create the keys; skip any that are sharp or flat; for
+  // our purposes we don't need them. Each octave is inserted
+  // into a <div> of class "octave".
+
+  noteFreq.forEach(function(keys, idx) {
+    let keyList = Object.entries(keys);
+    let octaveElem = document.createElement("div");
+    octaveElem.className = "octave";
+
+    keyList.forEach(function(key) {
+      if (key[0].length == 1) {
+        octaveElem.appendChild(createKey(key[0], idx, key[1]));
+      }
+    });
+
+    keyboard.appendChild(octaveElem);
+  });
+
+  document.querySelector("div[data-note='B'][data-octave='5']").scrollIntoView(false);
+
+  sineTerms = new Float32Array([0, 0, 1, 0, 1]);
+  cosineTerms = new Float32Array(sineTerms.length);
+  customWaveform = audioContext.createPeriodicWave(cosineTerms, sineTerms);
+
+  for (i=0; i<9; i++) {
+      oscList[i] = {};
+  }
+}
+
+setup();
+ +
    +
  1. A tabela que mapeia o nome e oitavas das notas para suas respectivas frequências é criado ao chamar createNoteTable().
    2. +
  2. Um manipulador de eventos é estabelecido ao chamar nosso velho amigo {{domxref("EventTarget.addEventListener", "addEventListener()")}} para cuidar dos eventos do {{event("change")}} no controle de ganho geral. Isso vai simplesmente atualizar o módulo de ganho de volume para o novo valor.
    3. +
  3. Em seguida, nós replicamos cada oitava na tabela de frequências das notas. Para cada oitava, usamos {{jsxref("Object.entries()")}} para conseguir uma lista de notas daquela oitava.
    4. +
  4. Criar um {{HTMLElement("div")}} para contar as notas daquela oitava (para ter um pouco de espaço entre as oitavas), e mudar o nome de classe para "octave".
    5. +
  5. Para cada tecla na oitava, checamos para ver se o nome daquela nota há mais de um caractere. Nós pulamos essas, pois estamos deixando notas sustenidas de fora deste exemplo. Do contrário, chamamos createKey(), especificando uma string, oitava, e frequência. O elemento retornado é anexado na elemento da oitava criada no passo 4.
    6. +
  6. Quando o elemento da oitava é construido, é então anexada ao teclado.
    7. +
  7. Uma vez que o teclado foi construido, nós rolamos para nota "B" na quinta oitava; isso tem o efeito de garantir que o C médio é visivel junto das notas ao redor.
    8. +
  8. Então uma forma de onda customizada é construida usando {{domxref("AudioContext.createPeriodicWave()")}}. Essa forma de onda será usada toda vez que o usuário selecionar "Custom" da seleção de formas de onda.
    9. +
  9. Enfim, a lista de osciladores é iniciada para garantir que está pronta para receber informação identificando quais osciladores estão associados com que teclas.
    10. +
+ +

Criando uma tecla

+ +

A função createKey()  é chamada toda vez que queremos que uma tecla seja apresentada no nosso teclado virtual. Ela cria elementos da tecla e seu rótulo, adiciona informação dos atributos ao elemento para uso posterior, e coloca modificadores de eventos para os eventos que nos importam.

+ +
function createKey(note, octave, freq) {
+  let keyElement = document.createElement("div");
+  let labelElement = document.createElement("div");
+
+  keyElement.className = "key";
+  keyElement.dataset["octave"] = octave;
+  keyElement.dataset["note"] = note;
+  keyElement.dataset["frequency"] = freq;
+
+  labelElement.innerHTML = note + "<sub>" + octave + "</sub>";
+  keyElement.appendChild(labelElement);
+
+  keyElement.addEventListener("mousedown", notePressed, false);
+  keyElement.addEventListener("mouseup", noteReleased, false);
+  keyElement.addEventListener("mouseover", notePressed, false);
+  keyElement.addEventListener("mouseleave", noteReleased, false);
+
+  return keyElement;
+}
+
+ +

Após criar  os elementos representando as teclas e seus rótulos, nós configuramos o elemento das teclas ao configurar sua classe para "key" (Que estabelece a aparência). Então adicionamos atributos {{htmlattrxref("data-*")}}  que contém a string da oitava da nota (attribute data-octave), representando a nota a ser tocada (attribute data-note), e frequência (attribute data-frequency) em Hertz. Isso irá nos permitir facilmente pegar informação conforme necessário ao cuidar de eventos.

+ +

Fazendo música

+ +

Tocando um tom

+ +

O trabalho da função playTone() é tocar um tom em uma dada frequência. Isso será usado pelo modificador para eventos acionados nas teclas do teclado, para que toquem as notas apropriadas.

+ +
function playTone(freq) {
+  let osc = audioContext.createOscillator();
+  osc.connect(masterGainNode);
+
+  let type = wavePicker.options[wavePicker.selectedIndex].value;
+
+  if (type == "custom") {
+    osc.setPeriodicWave(customWaveform);
+  } else {
+    osc.type = type;
+  }
+
+  osc.frequency.value = freq;
+  osc.start();
+
+  return osc;
+}
+
+ +

O playTone() começa criando um novo {{domxref("OscillatorNode")}} ao chamar o método {{domxref("AudioContext.createOscillator()")}}. Então conectamos ele para o módulo de ganha geral ao chamar o novo método de osciladores {{domxref("OscillatorNode.connect()")}} method;, Que determina ao oscilador onde ele irá mandar seu output. Ao fazer isso, mudar o valor do ganho do módulo de ganho geral irá mudar o volume de todos os toms gerados.

+ +

Então conseguimos o tipo de forma de onda para usar ao checar o valor do controle de seleção de formas de onda na barra de opções. Se o usuário estiver colocado como "custom", chamamos {{domxref("OscillatorNode.setPeriodicWave()")}} para configurar os osciladores para usar nossa forma de onda customizada. Fazer isso automáticamente coloca o {{domxref("OscillatorNode.type", "type")}} do oscilador como custom. Se qualquer outro tipo de forma de onda é selecionado na seleção de formas de ondas, nós simplesmente colocamos os tipos de osciladores no valor da seleção, esse valor será um entre sine, square, triangle, e sawtooth.

+ +

A frequência do oscilador é colocada no valor especificado no paramêtro freq ao colocar o valor dos objetos {{domxref("Oscillator.frequency")}} {{domxref("AudioParam")}} . Então, enfim, o oscilador é iniciado e começa a produzir sons ao chamar o método {{domxref("AudioScheduledSourceNode.start()")}} .

+ +

Tocando um tom

+ +

Quando o evento {{event("mousedown")}} ou {{domxref("mouseover")}} ocorre em uma tecla, queremos que toque a nota correspondente. A função notePressed() é usada como o modificador de eventos para esses eventos.

+ +
function notePressed(event) {
+  if (event.buttons & 1) {
+    let dataset = event.target.dataset;
+
+    if (!dataset["pressed"]) {
+      let octave = +dataset["octave"];
+      oscList[octave][dataset["note"]] = playTone(dataset["frequency"]);
+      dataset["pressed"] = "yes";
+    }
+  }
+}
+
+ +

Começamos checando se o botão esquerdo do mouse é pressionado, por dois motivos. Primeiro, queremos que apenas o botão esquerdo acione as notas. Segundo, e mais importante, estamos usando isso para cuidar do {{event("mouseover")}} para casos onde o usuário arrasta de tecla a tecla, e só queremos tocar uma nota se o mouse estiver pressionado quando entrar no elemento.

+ +

Se o botão do mouse estiver de fato sendo pressionado, recebemos o atributo de tecla pressionada {{htmlattrxref("dataset")}} ; isso torna fácil o acesso das informações de atributo customizadas no elemento. Procuramos por um atributo data-pressed ; caso não haja um(o que indica que a nota não está tocando ainda), chamamos playTone() para começar a tocar a nota, passando no valor dos elementos do atributo data-frequency. O valor retornado do oscilador é guardado no oscList para refêrencia futura, e data-pressed é colocado como yes para indicar que a nota está tocando para que não iniciemos novamente na próxima vez que isso for chamado.

+ +

Parando um tom

+ +

A função noteReleased() é o modificador de eventos chamado quando o usuário solta o botão do mouse ou move o mouse para fora da tecla que ele está tocando.

+ +
function noteReleased(event) {
+  let dataset = event.target.dataset;
+
+  if (dataset && dataset["pressed"]) {
+    let octave = +dataset["octave"];
+    oscList[octave][dataset["note"]].stop();
+    delete oscList[octave][dataset["note"]];
+    delete dataset["pressed"];
+  }
+}
+
+ +

noteReleased() usa os atributos customizados data-octave and data-note  para procurar os osciladores das teclas, e então chama o método de oscilador {{domxref("AudioScheduledSourceNode.stop", "stop()")}} para parar de tocar a nota. Finalmente, a entrada oscList para nota é limpa e o atributo data-pressed é removido do elemento da tecla (como identificado pelo {{domxref("event.target")}}), para indicar que a nota não está tocando no momento.

+ +

Mudando o volume geral

+ +

A barra de rolagem do volume na barra de opções dá uma simples interface para mudar o valor do ganho no módulo de ganho geral, então mudando o volume de todas as notas sendo tocadas. O metódo changeVolume() é o modificador do evento {{event("change")}} na barra de rolagem.

+ +
function changeVolume(event) {
+  masterGainNode.gain.value = volumeControl.value
+}
+
+ +

Isso simplesmente coloca o valor do módulo de ganho geral gain {{domxref("AudioParam")}} para o novo valor na barra de rolagem.

+ +

Resultado

+ +

Coloque tudo junto, o resultado é um simples e funcional teclado virtual que funciona com o clique:

+ +

{{ EmbedLiveSample('The_video_keyboard', 680, 200) }}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/web_storage_api/index.html b/files/pt-br/web/api/web_storage_api/index.html new file mode 100644 index 0000000000..f4e16bd9e7 --- /dev/null +++ b/files/pt-br/web/api/web_storage_api/index.html @@ -0,0 +1,139 @@ +--- +title: API de Armazenamento na Web +slug: Web/API/Web_Storage_API_pt_br +translation_of: Web/API/Web_Storage_API +--- +

{{DefaultAPISidebar("Web Storage API")}}

+ +

A  API de armazenamento na web (Web Storage) fornece mecanismos para que os navegadores possam armazenar dados através de chave/valor de uma forma mais eficiente que os cookies.

+ +

Armazenamento na Web conceitos e formas de uso

+ +

A API de Web Storage fornece duas maneiras de armazenar dados:

+ + + +

Esses mecanismos estão disponíveis a partir das seguintes propriedades {{domxref("Window.sessionStorage")}} e {{domxref("Window.localStorage")}} (para um maior suporte, o objeto Window implementa os objetos  Window.LocalStorage e Window.SessionStorage) — ao invocar uma dessas propriedades, é criada uma instância do objeto {{domxref("Storage")}}, que fornece métodos para inserir, recuperar e remover os dados. Sempre será utilizado um objeto diferente para cada origem de sessionStorage e localStorage, dessa forma o controle de ambos é realizado de forma separada.

+ +
+

Nota: O acesso a API de Web storage a partir de IFrames de terceiros é negado se o usuário desabilitou cookies de terceiros (Firefox implementa esse comportamento a partir da versão 43 em diante).

+
+ +
+

Nota: Web Storage não é o mesmo que mozStorage (interface XPCOM da Mozilla para o SQLite) ou Session store API (uma forma de armazenamento XPCOM para uso de extensões).

+
+ +

Interfaces de Armazenamento na Web

+ +
+
{{domxref("Storage")}}
+
Permite que você insira, recupere e remova dados de um domínio no storage(session ou local).
+
{{domxref("Window")}}
+
A API de Web Storage estende o objeto {{domxref("Window")}} com duas novas propriedades — {{domxref("Window.sessionStorage")}} e {{domxref("Window.localStorage")}} —  fornecendo acesso à sessão do domínio atual e local para o objeto {{domxref("Storage")}} respectivamente.
+
{{domxref("StorageEvent")}}
+
+

Um evento de storage é chamado em um objeto window do documento quando ocorre uma mudança no storage.

+
+
+ +

Exemplos

+ +

Para desmonstrar o uso de web storage, nós criamos um exemplo simples, chamado Web Storage Demo. A página da demo landing page oferece funcionalidades que permitem alterar a cor, fonte e imagem que é exibida na página. Quando você escolhe uma opção diferente, a página será atualizada imediatamente. Além disso, sua escolha foi armazenada em localStorage,  para que quando você feche o navegador e abra novamente para acessar a página, suas escolhas sejam lembradas.

+ +

Nós também fornecemos um event output page —  para quando você abrir a página em outra aba,  as informações sejam atualizadas através da chamada de um {{event("StorageEvent")}}.

+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('Web Storage')}}{{Spec2('Web Storage')}}
+ +

Compatibilidade com os Navegadores

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropriedadeChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
localStorage43.5810.504
sessionStorage52810.504
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Suporte básico2.1{{ CompatUnknown }}811iOS 3.2
+
+ +

Todos os navegadores têm espaços de armazenamento diferentes tanto para localStorage quanto para sessionStorage. Veja um resumo detalhado da capacidade de armazenamento de vários navegadores.

+ +
+

Nota: Desde iOS 5.1, o Safari armazena dados móveis de LocalStorage na pasta cache, que está sujeito a limpeza pelo OS, além disso o espaço de armazenamento é curto.

+
+ + + +

Boa parte dos navegadores atuais suportam a opção de privacidade chamada modo de "Navegação privada ou anônima", que basicamente torna a sessão de navegação privada e não deixa rastros depois que o navegador é fechado. Este modo é incompatível com armazenamento na Web por razões óbvias. Os fabricantes de navegadores estão experimentando com diferentes cenários como lidar com essa incompatibilidade.

+ +

A maioria dos navegadores optaram por uma estratégia onde as APIs de armazenamento ainda estão disponíveis e, aparentemente, funcional, com a grande diferença de que todos os dados armazenados é apagado depois que o navegador é fechado. Para estes navegadores ainda existem diferentes interpretações sobre o que deve ser feito com os dados existentes armazenados (a partir de uma sessão de navegação regular). E quanto   a leitura dos dados se o navegador estiver no modo privado? Há alguns navegadores, principalmente Safari, que optaram por uma solução em que o armazenamento está disponível, mas está vazio e tem uma quota de 0 bytes atribuídos, tornando impossível o armazenamento de dados.

+ +

Os desenvolvedores devem estar cientes e considerar as diferentes formas de implementações ao desenvolverem sites dependendo das APIs Web Storage. Para mais informações, leia neste post escrito no blog do WHATWG que lida especificamente com este tópico.

+ +

Veja também

+ +

Usando a API Web Storage

diff --git a/files/pt-br/web/api/web_storage_api/using_the_web_storage_api/index.html b/files/pt-br/web/api/web_storage_api/using_the_web_storage_api/index.html new file mode 100644 index 0000000000..eb9807f0ef --- /dev/null +++ b/files/pt-br/web/api/web_storage_api/using_the_web_storage_api/index.html @@ -0,0 +1,267 @@ +--- +title: Usando a API Web Storage +slug: Web/API/Web_Storage_API_pt_br/Using_the_Web_Storage_API +tags: + - API + - Guía + - Storage + - Web Storage API + - localStorage + - sessionStorage +translation_of: Web/API/Web_Storage_API/Using_the_Web_Storage_API +--- +
{{DefaultAPISidebar("Web Storage API")}}
+ +
+

A API Web Storage fornece mecanismos pelos quais os navegadores podem armazenar pares de chaves/valores de uma maneira muito mais segura e intuitiva do que usar cookies. Este artigo fornece um passo a passo sobre como usar essa tecnologia.

+
+ +

Conceitos básicos

+ +

Objetos Storage são simples conjuntos contendo pares de chave/valor, de forma parecida com objetos, porém eles permanecem intactos mesmo após a página ser recarregada. As chaves e valores são sempre strings (note que chaves cujo nome seja um número inteiro serão automaticamente convertidas par strings, assim como acontece nos objetos). Você pode acessar esses valores como você faria com um objeto ou usando os métodos {{domxref("Storage.getItem()")}} e {{domxref("Storage.setItem()")}}. As três linhas seguintes definem o valor de corDefinida de maneiras diferentes, mas com o mesmo resultado:

+ +
localStorage.corDefinida = '#a4509b';
+localStorage['corDefinida'] = '#a4509b';
+localStorage.setItem('corDefinida', '#a4509b');
+ +
+

Nota: Recomendamos que você utilize a API Web Storage (setItem, getItem, removeItem, key, length) para evitar as armadilhas associadas ao uso de objetos literais como mapas de chave-valor.

+
+ +

Os dois mecanismos presentes na Web Storage são os seguintes:

+ + + +

Esses mecanismos estão disponíveis através das propriedades {{domxref("Window.sessionStorage")}} e {{domxref("Window.localStorage")}} (de forma mais específica, em navegadores compatíveis, o objeto Window implementa os objetos WindowLocalStorage e WindowSessionStorage, aos quais as propriedades localStorage and sessionStorage pertencem, respectivamente) — invocar uma dessas propriedades irá criar uma instância do objeto {{domxref("Storage")}}, através do qual itens de dados podem ser definidos, acessados e removidos. Cada origem recebe objetos Storage diferentes para sessionStorage and localStorage — eles operam e são controlados separadamente.

+ +

Por exemplo, chamar localStorage pela primeira vez em um documento retornará um objeto {{domxref("Storage")}}; chamar sessionStorage em um documento retornará um outro objeto {{domxref("Storage")}}. Ambos podem ser manipulados da mesma maneira, mas de forma isolada.

+ +

Detectando a disponibilidade do localStorage

+ +

Para poder usarmos o localStorage, devemos antes verificar se ele é compatível e está disponível na sessão atual de navegação.

+ +

Testando a disponibilidade

+ +

Navegadores compatíveis com localStorage terão uma propriedade no objeto window chamada localStorage. Contudo, por várias razões, apenas verificar se essa propriedade existe pode gerar erros. Se ela existir, ainda não haverá garantias de que o localStorage está de fato disponível para uso, já que vários navegadores fornecem opções que desativam o localStorage. Dessa forma, um navegador pode ser compatível com o localStorage, mas também pode não torná-lo disponível para os scripts usarem. One example of that is Safari, which in Private Browsing mode gives us an empty localStorage object with a quota of zero, effectively making it unusable. However, we might still get a legitimate QuotaExceededError, which only means that we've used up all available storage space, but storage is actually available. Our feature detect should take these scenarios into account.

+ +

Here is a function that detects whether localStorage is both supported and available:

+ +
function storageAvailable(type) {
+    try {
+        var storage = window[type],
+            x = '__storage_test__';
+        storage.setItem(x, x);
+        storage.removeItem(x);
+        return true;
+    }
+    catch(e) {
+        return e instanceof DOMException && (
+            // everything except Firefox
+            e.code === 22 ||
+            // Firefox
+            e.code === 1014 ||
+            // test name field too, because code might not be present
+            // everything except Firefox
+            e.name === 'QuotaExceededError' ||
+            // Firefox
+            e.name === 'NS_ERROR_DOM_QUOTA_REACHED') &&
+            // acknowledge QuotaExceededError only if there's something already stored
+            storage.length !== 0;
+    }
+}
+ +

And here is how you would use it:

+ +
if (storageAvailable('localStorage')) {
+  // Yippee! We can use localStorage awesomeness
+}
+else {
+  // Too bad, no localStorage for us
+}
+ +

You can test for sessionStorage instead by calling storageAvailable('sessionStorage').

+ +

See here for a brief history of feature-detecting localStorage.

+ +

Example

+ +

To illustrate some typical web storage usage, we have created a simple example, imaginatively called Web Storage Demo. The landing page provides controls that can be used to customize the color, font, and decorative image:

+ +

When you choose different options, the page is instantly updated; in addition, your choices are stored in localStorage, so that when you leave the page and load it again, later on, your choices are remembered.

+ +

We have also provided an event output page — if you load this page in another tab, then make changes to your choices in the landing page, you'll see the updated storage information outputted as a {{domxref("StorageEvent")}} is fired.

+ +

+ +
+

Note: As well as viewing the example pages live using the above links, you can also check out the source code.

+
+ +

Testing whether your storage has been populated

+ +

To start with on main.js, we will test whether the storage object has already been populated (i.e., the page was previously accessed):

+ +
if(!localStorage.getItem('bgcolor')) {
+  populateStorage();
+} else {
+  setStyles();
+}
+ +

The {{domxref("Storage.getItem()")}} method is used to get a data item from storage; in this case, we are testing to see whether the bgcolor item exists; if not, we run populateStorage() to add the existing customization values to the storage. If there are already values there, we run setStyles() to update the page styling with the stored values.

+ +

Note: You could also use {{domxref("Storage.length")}} to test whether the storage object is empty or not.

+ +

Getting values from storage

+ +

As noted above, values can be retrieved from storage using {{domxref("Storage.getItem()")}}. This takes the key of the data item as an argument, and returns the data value. For example:

+ +
function setStyles() {
+  var currentColor = localStorage.getItem('bgcolor');
+  var currentFont = localStorage.getItem('font');
+  var currentImage = localStorage.getItem('image');
+
+  document.getElementById('bgcolor').value = currentColor;
+  document.getElementById('font').value = currentFont;
+  document.getElementById('image').value = currentImage;
+
+  htmlElem.style.backgroundColor = '#' + currentColor;
+  pElem.style.fontFamily = currentFont;
+  imgElem.setAttribute('src', currentImage);
+}
+ +

Here, the first three lines grab the values from local storage. Next, we set the values displayed in the form elements to those values, so that they keep in sync when you reload the page. Finally, we update the styles/decorative image on the page, so your customization options come up again on reload.

+ +

Setting values in storage

+ +

{{domxref("Storage.setItem()")}} is used both to create new data items, and (if the data item already exists) update existing values. This takes two arguments — the key of the data item to create/modify, and the value to store in it.

+ +
function populateStorage() {
+  localStorage.setItem('bgcolor', document.getElementById('bgcolor').value);
+  localStorage.setItem('font', document.getElementById('font').value);
+  localStorage.setItem('image', document.getElementById('image').value);
+
+  setStyles();
+}
+ +

The populateStorage() function sets three items in local storage — the background color, font, and image path. It then runs the setStyles() function to update the page styles, etc.

+ +

We've also included an onchange handler on each form element so that the data and styling are updated whenever a form value is changed:

+ +
bgcolorForm.onchange = populateStorage;
+fontForm.onchange = populateStorage;
+imageForm.onchange = populateStorage;
+ +

Responding to storage changes with the StorageEvent

+ +

The {{domxref("StorageEvent")}} is fired whenever a change is made to the {{domxref("Storage")}} object (note that this event is not fired for sessionStorage changes). This won't work on the same page that is making the changes — it is really a way for other pages on the domain using the storage to sync any changes that are made. Pages on other domains can't access the same storage objects.

+ +

On the events page (see events.js) the only JavaScript is as follows:

+ +
window.addEventListener('storage', function(e) {
+  document.querySelector('.my-key').textContent = e.key;
+  document.querySelector('.my-old').textContent = e.oldValue;
+  document.querySelector('.my-new').textContent = e.newValue;
+  document.querySelector('.my-url').textContent = e.url;
+  document.querySelector('.my-storage').textContent = e.storageArea;
+});
+ +

Here we add an event listener to the window object that fires when the {{domxref("Storage")}} object associated with the current origin is changed. As you can see above, the event object associated with this event has a number of properties containing useful information — the key of the data that changed, the old value before the change, the new value after that change, the URL of the document that changed the storage, and the storage object itself.

+ +

Deleting data records

+ +

Web Storage also provides a couple of simple methods to remove data. We don't use these in our demo, but they are very simple to add to your project:

+ + + +

Specifications

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('HTML WHATWG', 'webstorage.html#webstorage')}}{{Spec2('HTML WHATWG')}} 
+ +

Browser compatibility

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
localStorage43.5810.504
sessionStorage52810.504
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Basic support2.1{{ CompatUnknown }}811iOS 3.2
+
+ +

All browsers have varying capacity levels for both localStorage and sessionStorage. Here is a detailed rundown of all the storage capacities for various browsers.

+ +
+

Note: since iOS 5.1, Safari Mobile stores localStorage data in the cache folder, which is subject to occasional cleanup, at the behest of the OS, typically if space is short.

+
+ +

See also

+ + diff --git a/files/pt-br/web/api/web_storage_api_pt_br/index.html b/files/pt-br/web/api/web_storage_api_pt_br/index.html deleted file mode 100644 index f4e16bd9e7..0000000000 --- a/files/pt-br/web/api/web_storage_api_pt_br/index.html +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: API de Armazenamento na Web -slug: Web/API/Web_Storage_API_pt_br -translation_of: Web/API/Web_Storage_API ---- -

{{DefaultAPISidebar("Web Storage API")}}

- -

A  API de armazenamento na web (Web Storage) fornece mecanismos para que os navegadores possam armazenar dados através de chave/valor de uma forma mais eficiente que os cookies.

- -

Armazenamento na Web conceitos e formas de uso

- -

A API de Web Storage fornece duas maneiras de armazenar dados:

- - - -

Esses mecanismos estão disponíveis a partir das seguintes propriedades {{domxref("Window.sessionStorage")}} e {{domxref("Window.localStorage")}} (para um maior suporte, o objeto Window implementa os objetos  Window.LocalStorage e Window.SessionStorage) — ao invocar uma dessas propriedades, é criada uma instância do objeto {{domxref("Storage")}}, que fornece métodos para inserir, recuperar e remover os dados. Sempre será utilizado um objeto diferente para cada origem de sessionStorage e localStorage, dessa forma o controle de ambos é realizado de forma separada.

- -
-

Nota: O acesso a API de Web storage a partir de IFrames de terceiros é negado se o usuário desabilitou cookies de terceiros (Firefox implementa esse comportamento a partir da versão 43 em diante).

-
- -
-

Nota: Web Storage não é o mesmo que mozStorage (interface XPCOM da Mozilla para o SQLite) ou Session store API (uma forma de armazenamento XPCOM para uso de extensões).

-
- -

Interfaces de Armazenamento na Web

- -
-
{{domxref("Storage")}}
-
Permite que você insira, recupere e remova dados de um domínio no storage(session ou local).
-
{{domxref("Window")}}
-
A API de Web Storage estende o objeto {{domxref("Window")}} com duas novas propriedades — {{domxref("Window.sessionStorage")}} e {{domxref("Window.localStorage")}} —  fornecendo acesso à sessão do domínio atual e local para o objeto {{domxref("Storage")}} respectivamente.
-
{{domxref("StorageEvent")}}
-
-

Um evento de storage é chamado em um objeto window do documento quando ocorre uma mudança no storage.

-
-
- -

Exemplos

- -

Para desmonstrar o uso de web storage, nós criamos um exemplo simples, chamado Web Storage Demo. A página da demo landing page oferece funcionalidades que permitem alterar a cor, fonte e imagem que é exibida na página. Quando você escolhe uma opção diferente, a página será atualizada imediatamente. Além disso, sua escolha foi armazenada em localStorage,  para que quando você feche o navegador e abra novamente para acessar a página, suas escolhas sejam lembradas.

- -

Nós também fornecemos um event output page —  para quando você abrir a página em outra aba,  as informações sejam atualizadas através da chamada de um {{event("StorageEvent")}}.

- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('Web Storage')}}{{Spec2('Web Storage')}}
- -

Compatibilidade com os Navegadores

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
PropriedadeChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
localStorage43.5810.504
sessionStorage52810.504
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Suporte básico2.1{{ CompatUnknown }}811iOS 3.2
-
- -

Todos os navegadores têm espaços de armazenamento diferentes tanto para localStorage quanto para sessionStorage. Veja um resumo detalhado da capacidade de armazenamento de vários navegadores.

- -
-

Nota: Desde iOS 5.1, o Safari armazena dados móveis de LocalStorage na pasta cache, que está sujeito a limpeza pelo OS, além disso o espaço de armazenamento é curto.

-
- - - -

Boa parte dos navegadores atuais suportam a opção de privacidade chamada modo de "Navegação privada ou anônima", que basicamente torna a sessão de navegação privada e não deixa rastros depois que o navegador é fechado. Este modo é incompatível com armazenamento na Web por razões óbvias. Os fabricantes de navegadores estão experimentando com diferentes cenários como lidar com essa incompatibilidade.

- -

A maioria dos navegadores optaram por uma estratégia onde as APIs de armazenamento ainda estão disponíveis e, aparentemente, funcional, com a grande diferença de que todos os dados armazenados é apagado depois que o navegador é fechado. Para estes navegadores ainda existem diferentes interpretações sobre o que deve ser feito com os dados existentes armazenados (a partir de uma sessão de navegação regular). E quanto   a leitura dos dados se o navegador estiver no modo privado? Há alguns navegadores, principalmente Safari, que optaram por uma solução em que o armazenamento está disponível, mas está vazio e tem uma quota de 0 bytes atribuídos, tornando impossível o armazenamento de dados.

- -

Os desenvolvedores devem estar cientes e considerar as diferentes formas de implementações ao desenvolverem sites dependendo das APIs Web Storage. Para mais informações, leia neste post escrito no blog do WHATWG que lida especificamente com este tópico.

- -

Veja também

- -

Usando a API Web Storage

diff --git a/files/pt-br/web/api/web_storage_api_pt_br/using_the_web_storage_api/index.html b/files/pt-br/web/api/web_storage_api_pt_br/using_the_web_storage_api/index.html deleted file mode 100644 index eb9807f0ef..0000000000 --- a/files/pt-br/web/api/web_storage_api_pt_br/using_the_web_storage_api/index.html +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Usando a API Web Storage -slug: Web/API/Web_Storage_API_pt_br/Using_the_Web_Storage_API -tags: - - API - - Guía - - Storage - - Web Storage API - - localStorage - - sessionStorage -translation_of: Web/API/Web_Storage_API/Using_the_Web_Storage_API ---- -
{{DefaultAPISidebar("Web Storage API")}}
- -
-

A API Web Storage fornece mecanismos pelos quais os navegadores podem armazenar pares de chaves/valores de uma maneira muito mais segura e intuitiva do que usar cookies. Este artigo fornece um passo a passo sobre como usar essa tecnologia.

-
- -

Conceitos básicos

- -

Objetos Storage são simples conjuntos contendo pares de chave/valor, de forma parecida com objetos, porém eles permanecem intactos mesmo após a página ser recarregada. As chaves e valores são sempre strings (note que chaves cujo nome seja um número inteiro serão automaticamente convertidas par strings, assim como acontece nos objetos). Você pode acessar esses valores como você faria com um objeto ou usando os métodos {{domxref("Storage.getItem()")}} e {{domxref("Storage.setItem()")}}. As três linhas seguintes definem o valor de corDefinida de maneiras diferentes, mas com o mesmo resultado:

- -
localStorage.corDefinida = '#a4509b';
-localStorage['corDefinida'] = '#a4509b';
-localStorage.setItem('corDefinida', '#a4509b');
- -
-

Nota: Recomendamos que você utilize a API Web Storage (setItem, getItem, removeItem, key, length) para evitar as armadilhas associadas ao uso de objetos literais como mapas de chave-valor.

-
- -

Os dois mecanismos presentes na Web Storage são os seguintes:

- - - -

Esses mecanismos estão disponíveis através das propriedades {{domxref("Window.sessionStorage")}} e {{domxref("Window.localStorage")}} (de forma mais específica, em navegadores compatíveis, o objeto Window implementa os objetos WindowLocalStorage e WindowSessionStorage, aos quais as propriedades localStorage and sessionStorage pertencem, respectivamente) — invocar uma dessas propriedades irá criar uma instância do objeto {{domxref("Storage")}}, através do qual itens de dados podem ser definidos, acessados e removidos. Cada origem recebe objetos Storage diferentes para sessionStorage and localStorage — eles operam e são controlados separadamente.

- -

Por exemplo, chamar localStorage pela primeira vez em um documento retornará um objeto {{domxref("Storage")}}; chamar sessionStorage em um documento retornará um outro objeto {{domxref("Storage")}}. Ambos podem ser manipulados da mesma maneira, mas de forma isolada.

- -

Detectando a disponibilidade do localStorage

- -

Para poder usarmos o localStorage, devemos antes verificar se ele é compatível e está disponível na sessão atual de navegação.

- -

Testando a disponibilidade

- -

Navegadores compatíveis com localStorage terão uma propriedade no objeto window chamada localStorage. Contudo, por várias razões, apenas verificar se essa propriedade existe pode gerar erros. Se ela existir, ainda não haverá garantias de que o localStorage está de fato disponível para uso, já que vários navegadores fornecem opções que desativam o localStorage. Dessa forma, um navegador pode ser compatível com o localStorage, mas também pode não torná-lo disponível para os scripts usarem. One example of that is Safari, which in Private Browsing mode gives us an empty localStorage object with a quota of zero, effectively making it unusable. However, we might still get a legitimate QuotaExceededError, which only means that we've used up all available storage space, but storage is actually available. Our feature detect should take these scenarios into account.

- -

Here is a function that detects whether localStorage is both supported and available:

- -
function storageAvailable(type) {
-    try {
-        var storage = window[type],
-            x = '__storage_test__';
-        storage.setItem(x, x);
-        storage.removeItem(x);
-        return true;
-    }
-    catch(e) {
-        return e instanceof DOMException && (
-            // everything except Firefox
-            e.code === 22 ||
-            // Firefox
-            e.code === 1014 ||
-            // test name field too, because code might not be present
-            // everything except Firefox
-            e.name === 'QuotaExceededError' ||
-            // Firefox
-            e.name === 'NS_ERROR_DOM_QUOTA_REACHED') &&
-            // acknowledge QuotaExceededError only if there's something already stored
-            storage.length !== 0;
-    }
-}
- -

And here is how you would use it:

- -
if (storageAvailable('localStorage')) {
-  // Yippee! We can use localStorage awesomeness
-}
-else {
-  // Too bad, no localStorage for us
-}
- -

You can test for sessionStorage instead by calling storageAvailable('sessionStorage').

- -

See here for a brief history of feature-detecting localStorage.

- -

Example

- -

To illustrate some typical web storage usage, we have created a simple example, imaginatively called Web Storage Demo. The landing page provides controls that can be used to customize the color, font, and decorative image:

- -

When you choose different options, the page is instantly updated; in addition, your choices are stored in localStorage, so that when you leave the page and load it again, later on, your choices are remembered.

- -

We have also provided an event output page — if you load this page in another tab, then make changes to your choices in the landing page, you'll see the updated storage information outputted as a {{domxref("StorageEvent")}} is fired.

- -

- -
-

Note: As well as viewing the example pages live using the above links, you can also check out the source code.

-
- -

Testing whether your storage has been populated

- -

To start with on main.js, we will test whether the storage object has already been populated (i.e., the page was previously accessed):

- -
if(!localStorage.getItem('bgcolor')) {
-  populateStorage();
-} else {
-  setStyles();
-}
- -

The {{domxref("Storage.getItem()")}} method is used to get a data item from storage; in this case, we are testing to see whether the bgcolor item exists; if not, we run populateStorage() to add the existing customization values to the storage. If there are already values there, we run setStyles() to update the page styling with the stored values.

- -

Note: You could also use {{domxref("Storage.length")}} to test whether the storage object is empty or not.

- -

Getting values from storage

- -

As noted above, values can be retrieved from storage using {{domxref("Storage.getItem()")}}. This takes the key of the data item as an argument, and returns the data value. For example:

- -
function setStyles() {
-  var currentColor = localStorage.getItem('bgcolor');
-  var currentFont = localStorage.getItem('font');
-  var currentImage = localStorage.getItem('image');
-
-  document.getElementById('bgcolor').value = currentColor;
-  document.getElementById('font').value = currentFont;
-  document.getElementById('image').value = currentImage;
-
-  htmlElem.style.backgroundColor = '#' + currentColor;
-  pElem.style.fontFamily = currentFont;
-  imgElem.setAttribute('src', currentImage);
-}
- -

Here, the first three lines grab the values from local storage. Next, we set the values displayed in the form elements to those values, so that they keep in sync when you reload the page. Finally, we update the styles/decorative image on the page, so your customization options come up again on reload.

- -

Setting values in storage

- -

{{domxref("Storage.setItem()")}} is used both to create new data items, and (if the data item already exists) update existing values. This takes two arguments — the key of the data item to create/modify, and the value to store in it.

- -
function populateStorage() {
-  localStorage.setItem('bgcolor', document.getElementById('bgcolor').value);
-  localStorage.setItem('font', document.getElementById('font').value);
-  localStorage.setItem('image', document.getElementById('image').value);
-
-  setStyles();
-}
- -

The populateStorage() function sets three items in local storage — the background color, font, and image path. It then runs the setStyles() function to update the page styles, etc.

- -

We've also included an onchange handler on each form element so that the data and styling are updated whenever a form value is changed:

- -
bgcolorForm.onchange = populateStorage;
-fontForm.onchange = populateStorage;
-imageForm.onchange = populateStorage;
- -

Responding to storage changes with the StorageEvent

- -

The {{domxref("StorageEvent")}} is fired whenever a change is made to the {{domxref("Storage")}} object (note that this event is not fired for sessionStorage changes). This won't work on the same page that is making the changes — it is really a way for other pages on the domain using the storage to sync any changes that are made. Pages on other domains can't access the same storage objects.

- -

On the events page (see events.js) the only JavaScript is as follows:

- -
window.addEventListener('storage', function(e) {
-  document.querySelector('.my-key').textContent = e.key;
-  document.querySelector('.my-old').textContent = e.oldValue;
-  document.querySelector('.my-new').textContent = e.newValue;
-  document.querySelector('.my-url').textContent = e.url;
-  document.querySelector('.my-storage').textContent = e.storageArea;
-});
- -

Here we add an event listener to the window object that fires when the {{domxref("Storage")}} object associated with the current origin is changed. As you can see above, the event object associated with this event has a number of properties containing useful information — the key of the data that changed, the old value before the change, the new value after that change, the URL of the document that changed the storage, and the storage object itself.

- -

Deleting data records

- -

Web Storage also provides a couple of simple methods to remove data. We don't use these in our demo, but they are very simple to add to your project:

- - - -

Specifications

- - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('HTML WHATWG', 'webstorage.html#webstorage')}}{{Spec2('HTML WHATWG')}} 
- -

Browser compatibility

- -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
localStorage43.5810.504
sessionStorage52810.504
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Basic support2.1{{ CompatUnknown }}811iOS 3.2
-
- -

All browsers have varying capacity levels for both localStorage and sessionStorage. Here is a detailed rundown of all the storage capacities for various browsers.

- -
-

Note: since iOS 5.1, Safari Mobile stores localStorage data in the cache folder, which is subject to occasional cleanup, at the behest of the OS, typically if space is short.

-
- -

See also

- - diff --git a/files/pt-br/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html b/files/pt-br/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html new file mode 100644 index 0000000000..7b4f6384f6 --- /dev/null +++ b/files/pt-br/web/api/webgl_api/tutorial/adding_2d_content_to_a_webgl_context/index.html @@ -0,0 +1,226 @@ +--- +title: Adicionando conteúdo 2D a um contexto WebGL +slug: Web/API/WebGL_API/Tutorial/Adicionando_conteudo_2D_a_um_contexto_WebGL +tags: + - Tutorial + - WebGL +translation_of: Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context +--- +

{{WebGLSidebar("Tutorial")}} {{PreviousNext("Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL", "Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL")}}

+ +

Uma vez que você tenha  criado um contexto WebGL com sucesso, você pode iniciar a renderizar nele. O mais simples que podemos fazer é desenhar um objeto 2D não texturizado. Então vamos começar por aí, construindo o código necessário para se desenhar um quadrado.

+ +

Desenhando a cena

+ +

A coisa mais importante para se entender antes de começarmos é que, mesmo que estejamos só renderizando um objeto bidimensional nesse exemplo, nós ainda estamos desenhamos em um espaço 3d. Portanto, ainda precisamos estabelecer os shaders que irão criar a cor para a nossa cena simples, assim como desenhar o objeto. Eles irão estabelecer como o quadrado irá aparecer na tela.

+ +

Inicializando os shaders

+ +

Shaders são especificados ao usar a Linguagem de Shading OpenGL ES. Com o intuito de tornar mais fácil para manter e atualizar nosso conteúdo, nós podemos escrever nosso código que carrega os shaders para buscá-los no documento HTML, ao invés de termos de criar tudo em JavaScript. Vamos dar uma olhada na nossa rotina initShaders(), que cuida dessa tarefa:

+ +
function initShaders() {
+  var fragmentShader = getShader(gl, "shader-fs");
+  var vertexShader = getShader(gl, "shader-vs");
+
+  // Cria o progrma shader
+
+  shaderProgram = gl.createProgram();
+  gl.attachShader(shaderProgram, vertexShader);
+  gl.attachShader(shaderProgram, fragmentShader);
+  gl.linkProgram(shaderProgram);
+
+  // Se falhar ao criar o progrma shader, alerta
+
+  if (!gl.getProgramParameter(shaderProgram, gl.LINK_STATUS)) {
+    alert("Não foi possível inicializar o programa shader.");
+  }
+
+  gl.useProgram(shaderProgram);
+
+  vertexPositionAttribute = gl.getAttribLocation(shaderProgram, "aVertexPosition");
+  gl.enableVertexAttribArray(vertexPositionAttribute);
+}
+
+
+ +

Dois programas estão sendo inicializados por essa rotina; o primeiro, fragment shader, é carregado a partir do elemento HTML com o id "shader-fs". O segundo, vertex shader, é carregado pelo elemento HTML com o id "shader-vs". Nós vamos analisar a função getShader() no próximo tutorial; Essa rotina, na verdade, lida com a parte de puxar os programas shader da DOM.

+ +

Então nós criamos o programa shader chamando do objeto WebGL a função createProgram(), anexamos dois shaders nele e fazemos o link com o programa shader. Depois de fazer isso, o parametro LINK_STATUS do objeto g1 é checado para ter certeza de que o link foi criado com sucesso; Se sim, nós ativamos o novo programa shader.

+ +

Carregando os shaders da DOM

+ +

A rotina getShader() busca um programa shader com o nome específico do DOM, retornando o programa shader compilado para o requisitante, ou null se ele não pode ser carregado ou compilado.

+ +
function getShader(gl, id) {
+  var shaderScript, theSource, currentChild, shader;
+
+  shaderScript = document.getElementById(id);
+
+  if (!shaderScript) {
+    return null;
+  }
+
+  theSource = "";
+  currentChild = shaderScript.firstChild;
+
+  while(currentChild) {
+    if (currentChild.nodeType == currentChild.TEXT_NODE) {
+      theSource += currentChild.textContent;
+    }
+
+    currentChild = currentChild.nextSibling;
+  }
+
+ +

Uma vez que o elemento com o ID específico é encontrado, seu texto é lido na variável theSource.

+ +
  if (shaderScript.type == "x-shader/x-fragment") {
+    shader = gl.createShader(gl.FRAGMENT_SHADER);
+  } else if (shaderScript.type == "x-shader/x-vertex") {
+    shader = gl.createShader(gl.VERTEX_SHADER);
+  } else {
+     // Tipo de shader desconhecido
+     return null;
+  }
+ +

Uma vez que o código para o shader tenha sido lido, nós observamos o tipo MIME do objeto shader para determinar se é um sombreamento de vértice (MIME type "x-shader/x-vertex") ou um fragmento de shader (MIME type "x-shader/x-fragment"), em seguinda crie um tipo de shader apropriado para a partir do código fonte recuperado.

+ +
  gl.shaderSource(shader, theSource);
+
+  // Compile o programa shader
+  gl.compileShader(shader);
+
+  // Veja se ele compila com sucesso
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+      alert("Um erro ocorreu ao compilar os shaders: " + gl.getShaderInfoLog(shader));
+      return null;
+  }
+
+  return shader;
+}
+
+ +

Finalmente, a fonte é passada para o shader e compilada. Se um erro ocorrer enquanto o shader estiver compilando, nós mostraremos um alerta e retornaremos null; Caso contrário, o shader recém compilado é retornado para o requisitante.

+ +

Os shaders

+ +

Agora, nós precisamos adicionar os programas shaders ao HTML para descrever nosso documento. Os detalhes sobre como os shaders trabalham estão além do escopo deste artigo, assim como a sintaxe da linguagem do shader.

+ +

Fragmentos shader

+ +

Cada pixel é um poligono chamado de fragmento (fragment) na linguagem GL. O trabalho do fragmento de shader é estabelecer a cor de cada pixel. Ness caso, nós estamos apenas definindo a cor branca para cada pixel.

+ +

g1_FragColor é um construtor de variável GL que é utilizado para a cor do fragmento. Altere seu valor para definir a cor do pixel, como mostrado abaixo.

+ +
<script id="shader-fs" type="x-shader/x-fragment">
+  void main(void) {
+    gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
+  }
+</script>
+
+ +

Vértice do shader

+ +

A vértice (vertex) do shader define a posição e a forma de cada vértice.

+ +
<script id="shader-vs" type="x-shader/x-vertex">
+  attribute vec3 aVertexPosition;
+
+  uniform mat4 uMVMatrix;
+  uniform mat4 uPMatrix;
+
+  void main(void) {
+    gl_Position = uPMatrix * uMVMatrix * vec4(aVertexPosition, 1.0);
+  }
+</script>
+
+ +

Criando um objeto

+ +

Before we can render our square, we need to create the buffer that contains its vertices. We'll do that using a function we call initBuffers(); as we explore more advanced WebGL concepts, this routine will be augmented to create more -- and more complex -- 3D objects.

+ +
var horizAspect = 480.0/640.0;
+
+function initBuffers() {
+  squareVerticesBuffer = gl.createBuffer();
+  gl.bindBuffer(gl.ARRAY_BUFFER, squareVerticesBuffer);
+
+  var vertices = [
+    1.0,  1.0,  0.0,
+    -1.0, 1.0,  0.0,
+    1.0,  -1.0, 0.0,
+    -1.0, -1.0, 0.0
+  ];
+
+  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(vertices), gl.STATIC_DRAW);
+}
+
+ +

This routine is pretty simplistic given the basic nature of the scene in this example. It starts by calling the gl object's createBuffer() method to obtain a buffer into which we'll store the vertices. This is then bound to the context by calling the bindBuffer() method.

+ +

Once that's done, we create a JavaScript array containing the coordinates for each vertex of the square. This is then converted into an array of WebGL floats and passed into the gl object's bufferData() method to establish the vertices for the object.

+ +

Desenhando a cena

+ +

Once the shaders are established and the object constructed, we can actually render the scene. Since we're not animating anything in this example, our drawScene() function is very simple. It uses a few utility routines we'll cover shortly.

+ +
function drawScene() {
+  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+
+  perspectiveMatrix = makePerspective(45, 640.0/480.0, 0.1, 100.0);
+
+  loadIdentity();
+  mvTranslate([-0.0, 0.0, -6.0]);
+
+  gl.bindBuffer(gl.ARRAY_BUFFER, squareVerticesBuffer);
+  gl.vertexAttribPointer(vertexPositionAttribute, 3, gl.FLOAT, false, 0, 0);
+  setMatrixUniforms();
+  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+}
+
+ +

The first step is to clear the context to our background color; then we establish the camera's perspective. We set a field of view of 45°, with a width to height ratio of 640/480 (the dimensions of our canvas). We also specify that we only want objects between 0.1 and 100 units from the camera to be rendered.

+ +

Then we establish the position of the square by loading the identity position and translating away from the camera by 6 units. After that, we bind the square's vertex buffer to the context, configure it, and draw the object by calling the drawArrays() method.

+ +

{{EmbedGHLiveSample('webgl-examples/tutorial/sample2/index.html', 670, 510) }}

+ +

View the complete code | Open this demo on a new page

+ +

Operações úteis da Matrix

+ +

Matrix operations are complicated enough. Nobody really wants to write all the code needed to handle them on their own. Fortunately, there's Sylvester, a very handy library for handling vector and matrix operations from JavaScript.

+ +

The glUtils.js file used by this demo is used by a number of WebGL demos floating around on the Web. Nobody seems entirely clear on where it came from, but it does simplify the use of Sylvester even further by adding methods for building special types of matrices, as well as outputting HTML for displaying them.

+ +

In addition, this demo defines a few helpful routines to interface with these libraries for specific tasks. What exactly they do is beyond the scope of this demo, but there are plenty of good references on matrices available online; see the {{ anch("See also") }} section for a list of a few.

+ +
function loadIdentity() {
+  mvMatrix = Matrix.I(4);
+}
+
+function multMatrix(m) {
+  mvMatrix = mvMatrix.x(m);
+}
+
+function mvTranslate(v) {
+  multMatrix(Matrix.Translation($V([v[0], v[1], v[2]])).ensure4x4());
+}
+
+function setMatrixUniforms() {
+  var pUniform = gl.getUniformLocation(shaderProgram, "uPMatrix");
+  gl.uniformMatrix4fv(pUniform, false, new Float32Array(perspectiveMatrix.flatten()));
+
+  var mvUniform = gl.getUniformLocation(shaderProgram, "uMVMatrix");
+  gl.uniformMatrix4fv(mvUniform, false, new Float32Array(mvMatrix.flatten()));
+}
+
+ +

Ver Também

+ + + +

{{PreviousNext("Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL", "Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL")}}

diff --git a/files/pt-br/web/api/webgl_api/tutorial/adicionando_conteudo_2d_a_um_contexto_webgl/index.html b/files/pt-br/web/api/webgl_api/tutorial/adicionando_conteudo_2d_a_um_contexto_webgl/index.html deleted file mode 100644 index 7b4f6384f6..0000000000 --- a/files/pt-br/web/api/webgl_api/tutorial/adicionando_conteudo_2d_a_um_contexto_webgl/index.html +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Adicionando conteúdo 2D a um contexto WebGL -slug: Web/API/WebGL_API/Tutorial/Adicionando_conteudo_2D_a_um_contexto_WebGL -tags: - - Tutorial - - WebGL -translation_of: Web/API/WebGL_API/Tutorial/Adding_2D_content_to_a_WebGL_context ---- -

{{WebGLSidebar("Tutorial")}} {{PreviousNext("Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL", "Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL")}}

- -

Uma vez que você tenha  criado um contexto WebGL com sucesso, você pode iniciar a renderizar nele. O mais simples que podemos fazer é desenhar um objeto 2D não texturizado. Então vamos começar por aí, construindo o código necessário para se desenhar um quadrado.

- -

Desenhando a cena

- -

A coisa mais importante para se entender antes de começarmos é que, mesmo que estejamos só renderizando um objeto bidimensional nesse exemplo, nós ainda estamos desenhamos em um espaço 3d. Portanto, ainda precisamos estabelecer os shaders que irão criar a cor para a nossa cena simples, assim como desenhar o objeto. Eles irão estabelecer como o quadrado irá aparecer na tela.

- -

Inicializando os shaders

- -

Shaders são especificados ao usar a Linguagem de Shading OpenGL ES. Com o intuito de tornar mais fácil para manter e atualizar nosso conteúdo, nós podemos escrever nosso código que carrega os shaders para buscá-los no documento HTML, ao invés de termos de criar tudo em JavaScript. Vamos dar uma olhada na nossa rotina initShaders(), que cuida dessa tarefa:

- -
function initShaders() {
-  var fragmentShader = getShader(gl, "shader-fs");
-  var vertexShader = getShader(gl, "shader-vs");
-
-  // Cria o progrma shader
-
-  shaderProgram = gl.createProgram();
-  gl.attachShader(shaderProgram, vertexShader);
-  gl.attachShader(shaderProgram, fragmentShader);
-  gl.linkProgram(shaderProgram);
-
-  // Se falhar ao criar o progrma shader, alerta
-
-  if (!gl.getProgramParameter(shaderProgram, gl.LINK_STATUS)) {
-    alert("Não foi possível inicializar o programa shader.");
-  }
-
-  gl.useProgram(shaderProgram);
-
-  vertexPositionAttribute = gl.getAttribLocation(shaderProgram, "aVertexPosition");
-  gl.enableVertexAttribArray(vertexPositionAttribute);
-}
-
-
- -

Dois programas estão sendo inicializados por essa rotina; o primeiro, fragment shader, é carregado a partir do elemento HTML com o id "shader-fs". O segundo, vertex shader, é carregado pelo elemento HTML com o id "shader-vs". Nós vamos analisar a função getShader() no próximo tutorial; Essa rotina, na verdade, lida com a parte de puxar os programas shader da DOM.

- -

Então nós criamos o programa shader chamando do objeto WebGL a função createProgram(), anexamos dois shaders nele e fazemos o link com o programa shader. Depois de fazer isso, o parametro LINK_STATUS do objeto g1 é checado para ter certeza de que o link foi criado com sucesso; Se sim, nós ativamos o novo programa shader.

- -

Carregando os shaders da DOM

- -

A rotina getShader() busca um programa shader com o nome específico do DOM, retornando o programa shader compilado para o requisitante, ou null se ele não pode ser carregado ou compilado.

- -
function getShader(gl, id) {
-  var shaderScript, theSource, currentChild, shader;
-
-  shaderScript = document.getElementById(id);
-
-  if (!shaderScript) {
-    return null;
-  }
-
-  theSource = "";
-  currentChild = shaderScript.firstChild;
-
-  while(currentChild) {
-    if (currentChild.nodeType == currentChild.TEXT_NODE) {
-      theSource += currentChild.textContent;
-    }
-
-    currentChild = currentChild.nextSibling;
-  }
-
- -

Uma vez que o elemento com o ID específico é encontrado, seu texto é lido na variável theSource.

- -
  if (shaderScript.type == "x-shader/x-fragment") {
-    shader = gl.createShader(gl.FRAGMENT_SHADER);
-  } else if (shaderScript.type == "x-shader/x-vertex") {
-    shader = gl.createShader(gl.VERTEX_SHADER);
-  } else {
-     // Tipo de shader desconhecido
-     return null;
-  }
- -

Uma vez que o código para o shader tenha sido lido, nós observamos o tipo MIME do objeto shader para determinar se é um sombreamento de vértice (MIME type "x-shader/x-vertex") ou um fragmento de shader (MIME type "x-shader/x-fragment"), em seguinda crie um tipo de shader apropriado para a partir do código fonte recuperado.

- -
  gl.shaderSource(shader, theSource);
-
-  // Compile o programa shader
-  gl.compileShader(shader);
-
-  // Veja se ele compila com sucesso
-  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
-      alert("Um erro ocorreu ao compilar os shaders: " + gl.getShaderInfoLog(shader));
-      return null;
-  }
-
-  return shader;
-}
-
- -

Finalmente, a fonte é passada para o shader e compilada. Se um erro ocorrer enquanto o shader estiver compilando, nós mostraremos um alerta e retornaremos null; Caso contrário, o shader recém compilado é retornado para o requisitante.

- -

Os shaders

- -

Agora, nós precisamos adicionar os programas shaders ao HTML para descrever nosso documento. Os detalhes sobre como os shaders trabalham estão além do escopo deste artigo, assim como a sintaxe da linguagem do shader.

- -

Fragmentos shader

- -

Cada pixel é um poligono chamado de fragmento (fragment) na linguagem GL. O trabalho do fragmento de shader é estabelecer a cor de cada pixel. Ness caso, nós estamos apenas definindo a cor branca para cada pixel.

- -

g1_FragColor é um construtor de variável GL que é utilizado para a cor do fragmento. Altere seu valor para definir a cor do pixel, como mostrado abaixo.

- -
<script id="shader-fs" type="x-shader/x-fragment">
-  void main(void) {
-    gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
-  }
-</script>
-
- -

Vértice do shader

- -

A vértice (vertex) do shader define a posição e a forma de cada vértice.

- -
<script id="shader-vs" type="x-shader/x-vertex">
-  attribute vec3 aVertexPosition;
-
-  uniform mat4 uMVMatrix;
-  uniform mat4 uPMatrix;
-
-  void main(void) {
-    gl_Position = uPMatrix * uMVMatrix * vec4(aVertexPosition, 1.0);
-  }
-</script>
-
- -

Criando um objeto

- -

Before we can render our square, we need to create the buffer that contains its vertices. We'll do that using a function we call initBuffers(); as we explore more advanced WebGL concepts, this routine will be augmented to create more -- and more complex -- 3D objects.

- -
var horizAspect = 480.0/640.0;
-
-function initBuffers() {
-  squareVerticesBuffer = gl.createBuffer();
-  gl.bindBuffer(gl.ARRAY_BUFFER, squareVerticesBuffer);
-
-  var vertices = [
-    1.0,  1.0,  0.0,
-    -1.0, 1.0,  0.0,
-    1.0,  -1.0, 0.0,
-    -1.0, -1.0, 0.0
-  ];
-
-  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(vertices), gl.STATIC_DRAW);
-}
-
- -

This routine is pretty simplistic given the basic nature of the scene in this example. It starts by calling the gl object's createBuffer() method to obtain a buffer into which we'll store the vertices. This is then bound to the context by calling the bindBuffer() method.

- -

Once that's done, we create a JavaScript array containing the coordinates for each vertex of the square. This is then converted into an array of WebGL floats and passed into the gl object's bufferData() method to establish the vertices for the object.

- -

Desenhando a cena

- -

Once the shaders are established and the object constructed, we can actually render the scene. Since we're not animating anything in this example, our drawScene() function is very simple. It uses a few utility routines we'll cover shortly.

- -
function drawScene() {
-  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
-
-  perspectiveMatrix = makePerspective(45, 640.0/480.0, 0.1, 100.0);
-
-  loadIdentity();
-  mvTranslate([-0.0, 0.0, -6.0]);
-
-  gl.bindBuffer(gl.ARRAY_BUFFER, squareVerticesBuffer);
-  gl.vertexAttribPointer(vertexPositionAttribute, 3, gl.FLOAT, false, 0, 0);
-  setMatrixUniforms();
-  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
-}
-
- -

The first step is to clear the context to our background color; then we establish the camera's perspective. We set a field of view of 45°, with a width to height ratio of 640/480 (the dimensions of our canvas). We also specify that we only want objects between 0.1 and 100 units from the camera to be rendered.

- -

Then we establish the position of the square by loading the identity position and translating away from the camera by 6 units. After that, we bind the square's vertex buffer to the context, configure it, and draw the object by calling the drawArrays() method.

- -

{{EmbedGHLiveSample('webgl-examples/tutorial/sample2/index.html', 670, 510) }}

- -

View the complete code | Open this demo on a new page

- -

Operações úteis da Matrix

- -

Matrix operations are complicated enough. Nobody really wants to write all the code needed to handle them on their own. Fortunately, there's Sylvester, a very handy library for handling vector and matrix operations from JavaScript.

- -

The glUtils.js file used by this demo is used by a number of WebGL demos floating around on the Web. Nobody seems entirely clear on where it came from, but it does simplify the use of Sylvester even further by adding methods for building special types of matrices, as well as outputting HTML for displaying them.

- -

In addition, this demo defines a few helpful routines to interface with these libraries for specific tasks. What exactly they do is beyond the scope of this demo, but there are plenty of good references on matrices available online; see the {{ anch("See also") }} section for a list of a few.

- -
function loadIdentity() {
-  mvMatrix = Matrix.I(4);
-}
-
-function multMatrix(m) {
-  mvMatrix = mvMatrix.x(m);
-}
-
-function mvTranslate(v) {
-  multMatrix(Matrix.Translation($V([v[0], v[1], v[2]])).ensure4x4());
-}
-
-function setMatrixUniforms() {
-  var pUniform = gl.getUniformLocation(shaderProgram, "uPMatrix");
-  gl.uniformMatrix4fv(pUniform, false, new Float32Array(perspectiveMatrix.flatten()));
-
-  var mvUniform = gl.getUniformLocation(shaderProgram, "uMVMatrix");
-  gl.uniformMatrix4fv(mvUniform, false, new Float32Array(mvMatrix.flatten()));
-}
-
- -

Ver Também

- - - -

{{PreviousNext("Web/API/WebGL_API/Tutorial/Getting_started_with_WebGL", "Web/API/WebGL_API/Tutorial/Using_shaders_to_apply_color_in_WebGL")}}

diff --git a/files/pt-br/web/api/webrtc_api/simple_rtcdatachannel_sample/index.html b/files/pt-br/web/api/webrtc_api/simple_rtcdatachannel_sample/index.html new file mode 100644 index 0000000000..72ac37e56a --- /dev/null +++ b/files/pt-br/web/api/webrtc_api/simple_rtcdatachannel_sample/index.html @@ -0,0 +1,272 @@ +--- +title: Uma simples amostra de RTCDataChannel +slug: Web/API/WebRTC_API/Simples_RTCDataChannel_amostra +translation_of: Web/API/WebRTC_API/Simple_RTCDataChannel_sample +--- +

{{WebRTCSidebar}}

+ +

A interface {{domxref("RTCDataChannel")}} é um recurso da WebRTC API que permite abrir um canal entre dois pares sobre os quais você pode enviar e receber dados arbitrários. A API é intencionalmente semelhante à WebSocket API, de modo que o mesmo modelo de programação pode ser usado para ambos.

+ +

Neste exemplo, abriremos um {{domxref("RTCDataChannel")}} para realizar a conexão entre dois elementos na mesma página. Embora seja obviamente um cenário artificial, é útil para demonstrar o fluxo de conexão entre dois pares. Vamos cobrir a mecânica necessária para conectar, transmitir e receber dados, mas vamos deixar para outro exemplo os detalhes sobre como localizar e se conectar a um computador remoto.

+ +

O HTML

+ +

Primeiro, vamos dar uma olhada rápida no HTML que é necessário. Não há nada incrivelmente complicado aqui. Primeiro, temos um par de botões para estabelecer e fechar a conexão:

+ +
<button id="connectButton" name="connectButton" class="buttonleft">
+  Conectar
+</button>
+<button id="disconnectButton" name="disconnectButton" class="buttonright" disabled>
+  Desconectar
+</button>
+ +

Depois, há uma caixa que contém o campo de input no qual o usuário pode digitar uma mensagem para transmitir, com um botão para enviar o texto digitado. Este {{HTMLElement("div")}} será o primeiro ponto (peer) no canal.

+ +
  <div class="messagebox">
+    <label for="message">Insira a mensagem:
+      <input type="text" name="message" id="message" placeholder="Texto da mensagem"
+              inputmode="latin" size=60 maxlength=120 disabled>
+    </label>
+    <button id="sendButton" name="sendButton" class="buttonright" disabled>
+      Enviar
+    </button>
+  </div>
+ +

Finalmente, há uma pequena caixa na qual vamos inserir as mensagens. Este bloco {{HTMLElement("div")}} será o segundo ponto do par (peer).

+ +
<div class="messagebox" id="receivebox">
+  <p>Mensagens recebidas:</p>
+</div>
+ +

O código JavaScript

+ +

Como você pode simplesmente ver o próprio código no GitHub, abaixo, analisaremos as partes do código que fazem o trabalho pesado.

+ +

A WebRTC API faz um intenso uso de {{jsxref("Promise")}}s. Que tornam muito fácil encadear as etapas do processo de conexão; Se você ainda não leu sobre esta funcionalidade do ECMAScript 2015, você deveria ler sobre eles. Da mesma forma, este exemplo usa arrow functions para simplificar a sintaxe.

+ +

Começando

+ +

Quando o script é executado, configuramos um {{event("load")}} ouvinte de eventos (event listener), De modo que, uma vez que a página esteja totalmente carregada, nossa função startup() seja chamada.

+ +
function startup() {
+  connectButton = document.getElementById('connectButton');
+  disconnectButton = document.getElementById('disconnectButton');
+  sendButton = document.getElementById('sendButton');
+  messageInputBox = document.getElementById('message');
+  receiveBox = document.getElementById('receivebox');
+
+  // Define os ouvintes de eventos para os elementos da interface do usuário
+
+  connectButton.addEventListener('click', connectPeers, false);
+  disconnectButton.addEventListener('click', disconnectPeers, false);
+  sendButton.addEventListener('click', sendMessage, false);
+}
+ +

Isso é bastante direto. Pegamos referências de todos os elementos da página que precisaremos acessar e, em seguida, configuramos {{domxref("EventListener", "event listeners")}} nos três botões.

+ +

Estabelecendo uma conexão

+ +

Quando o usuário clica no botão "Conectar", o método connectPeers() é chamado. Para que fique mais claro, iremos quebrar o código em mais partes, e analisar um pouco de cada vez.

+ +
+

Nota: Mesmo que ambas as extremidades da nossa conexão estejam na mesma página, vamos nos referir ao ponto que inicia a conexão como "local", e ao outro como sendo o "remoto".

+
+ +

Configurando o ponto local (local peer)

+ +
localConnection = new RTCPeerConnection();
+
+sendChannel = localConnection.createDataChannel("sendChannel");
+sendChannel.onopen = handleSendChannelStatusChange;
+sendChannel.onclose = handleSendChannelStatusChange;
+
+ +

O primeiro passo é criar o ponto "local" da conexão. Este é o ponto que enviará o pedido de conexão. O próximo passo é criar o {{domxref("RTCDataChannel")}} chamando {{domxref("RTCPeerConnection.createDataChannel()")}} e configurando ouvintes de eventos (event listeners) para monitorar o canal, e para que possamos saber quando ele for aberto e fechado (isto é, quando o canal está conectado ou desconectado dentro dessa conexão entre pares (peer connection)).

+ +

É importante ter em mente que cada extremidade do canal tem seu próprio objeto {{domxref("RTCDataChannel")}} .

+ +

Configurando o ponto remoto (remote peer)

+ +
remoteConnection = new RTCPeerConnection();
+remoteConnection.ondatachannel = receiveChannelCallback;
+ +

O ponto remoto está configurado de forma semelhante, exceto que não precisamos nós mesmos criar explicitamente um {{domxref("RTCDataChannel")}} , uma vez que vamos ser conectados através do canal estabelecido acima. Em vez disso, criamos um {{event("datachannel")}} manipulador de eventos (event handler); Isso será chamado quando o canal de dados (data channel) for aberto; Este manipulador (handler) receberá um objeto RTCDataChannel; você verá isso abaixo.

+ +

Configurando  ICE candidates

+ +

O próximo passo é configurar cada conexão com os ouvintes do ICE que serão chamados quando houver um novo candidato ICE para comunicar com o outro lado.

+ +
+

Nota: Em um cenário do mundo real em que os dois pares não estão sendo executados no mesmo contexto, o processo é um pouco mais complexo; Cada lado fornece, um de cada vez, um sugestão sobre como conectar (por exemplo, UDP, UDP com um relay, TCP, etc.) chamando {{domxref("RTCPeerConnection.addIceCandidate()")}}, e eles vão de um lado para outro até chegarem a um acordo. Mas aqui, acabamos de aceitar a primeira oferta de cada lado, uma vez que não existe uma rede real envolvida.

+
+ +
    localConnection.onicecandidate = e => !e.candidate
+        || remoteConnection.addIceCandidate(e.candidate)
+        .catch(handleAddCandidateError);
+
+    remoteConnection.onicecandidate = e => !e.candidate
+        || localConnection.addIceCandidate(e.candidate)
+        .catch(handleAddCandidateError);
+ +

Configuramos cada {{domxref("RTCPeerConnection")}} para ter um manipulador de eventos (event handler) para o evento {{event("icecandidate")}} .

+ +

Iniciando a tentativa de conexão

+ +

A última coisa que precisamos fazer para começar a conectar nossos pares é criar uma oferta de conexão.

+ +
    localConnection.createOffer()
+    .then(offer => localConnection.setLocalDescription(offer))
+    .then(() => remoteConnection.setRemoteDescription(localConnection.localDescription))
+    .then(() => remoteConnection.createAnswer())
+    .then(answer => remoteConnection.setLocalDescription(answer))
+    .then(() => localConnection.setRemoteDescription(remoteConnection.localDescription))
+    .catch(handleCreateDescriptionError);
+ +

Vamos passar por isto linha por linha e decifrar o que significa.

+ +
    +
  1. Primeiro chamamos {{domxref("RTCPeerConnection.createOffer()")}} método para criar um resumo {{Glossary("SDP")}} (Session Description Protocol) descrevendo a conexão que queremos fazer. Este método aceita, opcionalmente, um objeto com restrições a serem suportadas pela conexão para atender às suas necessidades, como no caso da conexão precisar suportar áudio, vídeo ou ambos. Em nosso exemplo simples, não temos restrições.
    2. +
  2. Se a oferta for criada com sucesso, passamos o resumo junto ao método de conexões locais {{domxref("RTCPeerConnection.setLocalDescription()")}} . Isso configura o ponto local da conexão.
    3. +
  3. O próximo passo é conectar o ponto local ao remoto comunicando ao ponto remoto sobre ele. Isso é feito chamando remoteConnection.{{domxref("RTCPeerConnection.setRemoteDescription()")}}. Agora o remoteConnection conhece a conexão que está sendo construída.
    4. +
  4. Isso significa que é hora do ponto remoto responder. Ele faz isso chamando o método {{domxref("RTCPeerConnection.createAnswer", "createAnswer()")}} . Isso gera um resumo de SDP que descreve a conexão que o ponto remoto está disposto e capaz de estabelecer. Essa configuração está em algum lugar na união das opções que ambos os pares podem suportar.
    5. +
  5. Uma vez que a resposta foi criada, ela é passada para o remoteConnection chamando {{domxref("RTCPeerConnection.setLocalDescription()")}}. Isso estabelece o ponto remoto da conexão (que, para o ponto remoto, é o ponto local. Isso pode parecer confuso, mas você irá se acostumar com isso.
    6. +
  6. Finalmente, a descrição local das conexões remotas está configurada para se referir ao ponto remoto, chamando localConnection's {{domxref("RTCPeerConnection.setRemoteDescription()")}}.
    7. +
  7. O catch() chama uma rotina que lida com os erros que ocorrem.
    8. +
+ +
+

Nota: Mais uma vez, esse processo não é uma implementação do mundo real; No uso normal, há dois pedaços de código executados em duas máquinas, interagindo e negociando a conexão.

+
+ +

Manipulação da conexão de pares bem sucedida

+ +

Como cada lado da conexão peer-to-peer é conectado com sucesso, o evento correspondente {{domxref("RTCPeerConnection")}}'s {{event("icecandidate")}} é disparado. Esses manipuladores podem fazer o que for necessário, mas, neste exemplo, tudo o que precisamos fazer é atualizar a interface do usuário:

+ +
  function handleLocalAddCandidateSuccess() {
+    connectButton.disabled = true;
+  }
+
+  function handleRemoteAddCandidateSuccess() {
+    disconnectButton.disabled = false;
+  }
+ +

A única coisa que fazemos aqui é desativar o botão "Conectar" quando o ponto local estiver conectado e ativar o botão "Desconectar" quando o ponto remoto se conectar.

+ +

Conectando o canal de dados

+ +

Uma vez que o {{domxref("RTCPeerConnection")}} é aberto, o evento {{event("datachannel")}} é enviado para o ponto remoto para completar o processo de abertura do canal de dados; Isso invoca nosso método receiveChannelCallback(), que se parece com isso:

+ +
  function receiveChannelCallback(event) {
+    receiveChannel = event.channel;
+    receiveChannel.onmessage = handleReceiveMessage;
+    receiveChannel.onopen = handleReceiveChannelStatusChange;
+    receiveChannel.onclose = handleReceiveChannelStatusChange;
+  }
+ +

O evento{{event("datachannel")}} inclui, em sua propriedade de canal, uma referência a um {{domxref("RTCDataChannel")}} Representando o ponto remoto do canal. Isso é salvo, e nós configuramos, no canal, ouvintes de eventos para os eventos que queremos manipular. Uma vez feito isso, nosso método handleReceiveMessage() Será chamado cada vez que os dados são recebidos pelo ponto remoto, e o método handleReceiveChannelStatusChange() será chamado sempre que mudar o estado da conexão do canal, para que possamos reagir quando o canal estiver totalmente aberto e quando ele for fechado.

+ +

Lidando com as mudanças de status do canal

+ +

Ambos nossos pontos locais e remotos usam um único método para lidar com eventos que indicam alguma alteração no status da conexão do canal.

+ +

Quando o ponto local experimenta um evento aberto ou fechado, o métodohandleSendChannelStatusChange() é chamado:

+ +
  function handleSendChannelStatusChange(event) {
+    if (sendChannel) {
+      var state = sendChannel.readyState;
+
+      if (state === "open") {
+        messageInputBox.disabled = false;
+        messageInputBox.focus();
+        sendButton.disabled = false;
+        disconnectButton.disabled = false;
+        connectButton.disabled = true;
+      } else {
+        messageInputBox.disabled = true;
+        sendButton.disabled = true;
+        connectButton.disabled = false;
+        disconnectButton.disabled = true;
+      }
+    }
+  }
+ +

Se o estado do canal mudou para "open", isso indica que terminamos de estabelecer o link entre os dois pares. A interface do usuário é atualizada de forma correspondente: ativando o elemento de input de texto para a mensagem a ser enviada, focando este elemento de input para que o usuário comece imediatamente a digitar, habilitando os botões "Enviar" e "Desconectar", que são agora utilizáveis, E desativando o botão "Conectar", uma vez que não é necessário quando a conexão está aberta.

+ +

Se o estado do canal mudou para "closed", ocorre o conjunto oposto de ações: a caixa de entrada de texto e o botão "Enviar" estão desativados, o botão "Conectar" está habilitado para que o usuário possa abrir uma nova conexão se desejar, e o botão "Desconectar" está desativado, uma vez que não é útil quando não existe conexão.

+ +

Nosso exemplo de par remoto, por outro lado, ignora os eventos de alteração de status, exceto para registrar o evento no console:

+ +
  function handleReceiveChannelStatusChange(event) {
+    if (receiveChannel) {
+      console.log("Receive channel's status has changed to " +
+                  receiveChannel.readyState);
+    }
+  }
+ +

O método handleReceiveChannelStatusChange() recebe como parâmetro de entrada o evento que ocorreu; Este será um {{domxref("RTCDataChannelEvent")}}.

+ +

Enviando mensagens

+ +

Quando o usuário pressiona o botão "Enviar", o método sendMessage() que estabelecemos como o manipulador para o evento do botão {{event("click")}} é chamado. Esse método é bastante simples:

+ +
  function sendMessage() {
+    var message = messageInputBox.value;
+    sendChannel.send(message);
+
+    messageInputBox.value = "";
+    messageInputBox.focus();
+  }
+ +

Primeiro, o texto da mensagem é obtido dos atributos do elemento de input {{htmlattrxref("value", "input")}} . Isso é enviado para o ponto remoto, ligando para {{domxref("RTCDataChannel.send", "sendChannel.send()")}}. E está tudo aí! O resto deste método é apenas um pouco de açúcar para experiência do usuário - a caixa de entrada é esvaziada e re-focada para que o usuário comece imediatamente a digitar outra mensagem.

+ +

Recebendo mensagens

+ +

Quando ocorre um evento de "mensagem" no canal remoto, nosso método handleReceiveMessage() é chamado como o manipulador de eventos.

+ +
  function handleReceiveMessage(event) {
+    var el = document.createElement("p");
+    var txtNode = document.createTextNode(event.data);
+
+    el.appendChild(txtNode);
+    receiveBox.appendChild(el);
+  }
+ +

Este método simplesmente executa alguns injeções básicas {{Glossary("DOM")}} ; cria um novo {{HTMLElement("p")}} (paragraph) elemento, então cria um novo nó {{domxref("Text")}} contendo o texto da mensagem, que é recebido na propriedade de dados do evento. Este nó de texto é anexado como um filho do novo elemento, que é então inserido no bloco receiveBox, fazendo com que ele desenhe na janela do navegador.

+ +

Desconectando os pares (peers)

+ +

Quando o usuário clica no botão "Desconectar", o método disconnectPeers() previamente configurado como o manipulador desse botão é chamado.

+ +
  function disconnectPeers() {
+
+    // Close the RTCDataChannels if they're open.
+
+    sendChannel.close();
+    receiveChannel.close();
+
+    // Close the RTCPeerConnections
+
+    localConnection.close();
+    remoteConnection.close();
+
+    sendChannel = null;
+    receiveChannel = null;
+    localConnection = null;
+    remoteConnection = null;
+
+    // Update user interface elements
+
+    connectButton.disabled = false;
+    disconnectButton.disabled = true;
+    sendButton.disabled = true;
+
+    messageInputBox.value = "";
+    messageInputBox.disabled = true;
+  }
+
+ +

Isso começa por fechar cada par {{domxref("RTCDataChannel")}}, então, de forma semelhante, cada um {{domxref("RTCPeerConnection")}}. Então, todas as referências salvas desses objetos são definidas como null para evitar a reutilização acidental, e a interface do usuário é atualizada para refletir o fato de que a conexão foi fechada.

+ +

Próximos passos

+ +

Você poderia tentar este exemplo e dar uma olhada no código fonte webrtc-simple-datachannel, disponível no GitHub.

diff --git a/files/pt-br/web/api/webrtc_api/simples_rtcdatachannel_amostra/index.html b/files/pt-br/web/api/webrtc_api/simples_rtcdatachannel_amostra/index.html deleted file mode 100644 index 72ac37e56a..0000000000 --- a/files/pt-br/web/api/webrtc_api/simples_rtcdatachannel_amostra/index.html +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: Uma simples amostra de RTCDataChannel -slug: Web/API/WebRTC_API/Simples_RTCDataChannel_amostra -translation_of: Web/API/WebRTC_API/Simple_RTCDataChannel_sample ---- -

{{WebRTCSidebar}}

- -

A interface {{domxref("RTCDataChannel")}} é um recurso da WebRTC API que permite abrir um canal entre dois pares sobre os quais você pode enviar e receber dados arbitrários. A API é intencionalmente semelhante à WebSocket API, de modo que o mesmo modelo de programação pode ser usado para ambos.

- -

Neste exemplo, abriremos um {{domxref("RTCDataChannel")}} para realizar a conexão entre dois elementos na mesma página. Embora seja obviamente um cenário artificial, é útil para demonstrar o fluxo de conexão entre dois pares. Vamos cobrir a mecânica necessária para conectar, transmitir e receber dados, mas vamos deixar para outro exemplo os detalhes sobre como localizar e se conectar a um computador remoto.

- -

O HTML

- -

Primeiro, vamos dar uma olhada rápida no HTML que é necessário. Não há nada incrivelmente complicado aqui. Primeiro, temos um par de botões para estabelecer e fechar a conexão:

- -
<button id="connectButton" name="connectButton" class="buttonleft">
-  Conectar
-</button>
-<button id="disconnectButton" name="disconnectButton" class="buttonright" disabled>
-  Desconectar
-</button>
- -

Depois, há uma caixa que contém o campo de input no qual o usuário pode digitar uma mensagem para transmitir, com um botão para enviar o texto digitado. Este {{HTMLElement("div")}} será o primeiro ponto (peer) no canal.

- -
  <div class="messagebox">
-    <label for="message">Insira a mensagem:
-      <input type="text" name="message" id="message" placeholder="Texto da mensagem"
-              inputmode="latin" size=60 maxlength=120 disabled>
-    </label>
-    <button id="sendButton" name="sendButton" class="buttonright" disabled>
-      Enviar
-    </button>
-  </div>
- -

Finalmente, há uma pequena caixa na qual vamos inserir as mensagens. Este bloco {{HTMLElement("div")}} será o segundo ponto do par (peer).

- -
<div class="messagebox" id="receivebox">
-  <p>Mensagens recebidas:</p>
-</div>
- -

O código JavaScript

- -

Como você pode simplesmente ver o próprio código no GitHub, abaixo, analisaremos as partes do código que fazem o trabalho pesado.

- -

A WebRTC API faz um intenso uso de {{jsxref("Promise")}}s. Que tornam muito fácil encadear as etapas do processo de conexão; Se você ainda não leu sobre esta funcionalidade do ECMAScript 2015, você deveria ler sobre eles. Da mesma forma, este exemplo usa arrow functions para simplificar a sintaxe.

- -

Começando

- -

Quando o script é executado, configuramos um {{event("load")}} ouvinte de eventos (event listener), De modo que, uma vez que a página esteja totalmente carregada, nossa função startup() seja chamada.

- -
function startup() {
-  connectButton = document.getElementById('connectButton');
-  disconnectButton = document.getElementById('disconnectButton');
-  sendButton = document.getElementById('sendButton');
-  messageInputBox = document.getElementById('message');
-  receiveBox = document.getElementById('receivebox');
-
-  // Define os ouvintes de eventos para os elementos da interface do usuário
-
-  connectButton.addEventListener('click', connectPeers, false);
-  disconnectButton.addEventListener('click', disconnectPeers, false);
-  sendButton.addEventListener('click', sendMessage, false);
-}
- -

Isso é bastante direto. Pegamos referências de todos os elementos da página que precisaremos acessar e, em seguida, configuramos {{domxref("EventListener", "event listeners")}} nos três botões.

- -

Estabelecendo uma conexão

- -

Quando o usuário clica no botão "Conectar", o método connectPeers() é chamado. Para que fique mais claro, iremos quebrar o código em mais partes, e analisar um pouco de cada vez.

- -
-

Nota: Mesmo que ambas as extremidades da nossa conexão estejam na mesma página, vamos nos referir ao ponto que inicia a conexão como "local", e ao outro como sendo o "remoto".

-
- -

Configurando o ponto local (local peer)

- -
localConnection = new RTCPeerConnection();
-
-sendChannel = localConnection.createDataChannel("sendChannel");
-sendChannel.onopen = handleSendChannelStatusChange;
-sendChannel.onclose = handleSendChannelStatusChange;
-
- -

O primeiro passo é criar o ponto "local" da conexão. Este é o ponto que enviará o pedido de conexão. O próximo passo é criar o {{domxref("RTCDataChannel")}} chamando {{domxref("RTCPeerConnection.createDataChannel()")}} e configurando ouvintes de eventos (event listeners) para monitorar o canal, e para que possamos saber quando ele for aberto e fechado (isto é, quando o canal está conectado ou desconectado dentro dessa conexão entre pares (peer connection)).

- -

É importante ter em mente que cada extremidade do canal tem seu próprio objeto {{domxref("RTCDataChannel")}} .

- -

Configurando o ponto remoto (remote peer)

- -
remoteConnection = new RTCPeerConnection();
-remoteConnection.ondatachannel = receiveChannelCallback;
- -

O ponto remoto está configurado de forma semelhante, exceto que não precisamos nós mesmos criar explicitamente um {{domxref("RTCDataChannel")}} , uma vez que vamos ser conectados através do canal estabelecido acima. Em vez disso, criamos um {{event("datachannel")}} manipulador de eventos (event handler); Isso será chamado quando o canal de dados (data channel) for aberto; Este manipulador (handler) receberá um objeto RTCDataChannel; você verá isso abaixo.

- -

Configurando  ICE candidates

- -

O próximo passo é configurar cada conexão com os ouvintes do ICE que serão chamados quando houver um novo candidato ICE para comunicar com o outro lado.

- -
-

Nota: Em um cenário do mundo real em que os dois pares não estão sendo executados no mesmo contexto, o processo é um pouco mais complexo; Cada lado fornece, um de cada vez, um sugestão sobre como conectar (por exemplo, UDP, UDP com um relay, TCP, etc.) chamando {{domxref("RTCPeerConnection.addIceCandidate()")}}, e eles vão de um lado para outro até chegarem a um acordo. Mas aqui, acabamos de aceitar a primeira oferta de cada lado, uma vez que não existe uma rede real envolvida.

-
- -
    localConnection.onicecandidate = e => !e.candidate
-        || remoteConnection.addIceCandidate(e.candidate)
-        .catch(handleAddCandidateError);
-
-    remoteConnection.onicecandidate = e => !e.candidate
-        || localConnection.addIceCandidate(e.candidate)
-        .catch(handleAddCandidateError);
- -

Configuramos cada {{domxref("RTCPeerConnection")}} para ter um manipulador de eventos (event handler) para o evento {{event("icecandidate")}} .

- -

Iniciando a tentativa de conexão

- -

A última coisa que precisamos fazer para começar a conectar nossos pares é criar uma oferta de conexão.

- -
    localConnection.createOffer()
-    .then(offer => localConnection.setLocalDescription(offer))
-    .then(() => remoteConnection.setRemoteDescription(localConnection.localDescription))
-    .then(() => remoteConnection.createAnswer())
-    .then(answer => remoteConnection.setLocalDescription(answer))
-    .then(() => localConnection.setRemoteDescription(remoteConnection.localDescription))
-    .catch(handleCreateDescriptionError);
- -

Vamos passar por isto linha por linha e decifrar o que significa.

- -
    -
  1. Primeiro chamamos {{domxref("RTCPeerConnection.createOffer()")}} método para criar um resumo {{Glossary("SDP")}} (Session Description Protocol) descrevendo a conexão que queremos fazer. Este método aceita, opcionalmente, um objeto com restrições a serem suportadas pela conexão para atender às suas necessidades, como no caso da conexão precisar suportar áudio, vídeo ou ambos. Em nosso exemplo simples, não temos restrições.
    2. -
  2. Se a oferta for criada com sucesso, passamos o resumo junto ao método de conexões locais {{domxref("RTCPeerConnection.setLocalDescription()")}} . Isso configura o ponto local da conexão.
    3. -
  3. O próximo passo é conectar o ponto local ao remoto comunicando ao ponto remoto sobre ele. Isso é feito chamando remoteConnection.{{domxref("RTCPeerConnection.setRemoteDescription()")}}. Agora o remoteConnection conhece a conexão que está sendo construída.
    4. -
  4. Isso significa que é hora do ponto remoto responder. Ele faz isso chamando o método {{domxref("RTCPeerConnection.createAnswer", "createAnswer()")}} . Isso gera um resumo de SDP que descreve a conexão que o ponto remoto está disposto e capaz de estabelecer. Essa configuração está em algum lugar na união das opções que ambos os pares podem suportar.
    5. -
  5. Uma vez que a resposta foi criada, ela é passada para o remoteConnection chamando {{domxref("RTCPeerConnection.setLocalDescription()")}}. Isso estabelece o ponto remoto da conexão (que, para o ponto remoto, é o ponto local. Isso pode parecer confuso, mas você irá se acostumar com isso.
    6. -
  6. Finalmente, a descrição local das conexões remotas está configurada para se referir ao ponto remoto, chamando localConnection's {{domxref("RTCPeerConnection.setRemoteDescription()")}}.
    7. -
  7. O catch() chama uma rotina que lida com os erros que ocorrem.
    8. -
- -
-

Nota: Mais uma vez, esse processo não é uma implementação do mundo real; No uso normal, há dois pedaços de código executados em duas máquinas, interagindo e negociando a conexão.

-
- -

Manipulação da conexão de pares bem sucedida

- -

Como cada lado da conexão peer-to-peer é conectado com sucesso, o evento correspondente {{domxref("RTCPeerConnection")}}'s {{event("icecandidate")}} é disparado. Esses manipuladores podem fazer o que for necessário, mas, neste exemplo, tudo o que precisamos fazer é atualizar a interface do usuário:

- -
  function handleLocalAddCandidateSuccess() {
-    connectButton.disabled = true;
-  }
-
-  function handleRemoteAddCandidateSuccess() {
-    disconnectButton.disabled = false;
-  }
- -

A única coisa que fazemos aqui é desativar o botão "Conectar" quando o ponto local estiver conectado e ativar o botão "Desconectar" quando o ponto remoto se conectar.

- -

Conectando o canal de dados

- -

Uma vez que o {{domxref("RTCPeerConnection")}} é aberto, o evento {{event("datachannel")}} é enviado para o ponto remoto para completar o processo de abertura do canal de dados; Isso invoca nosso método receiveChannelCallback(), que se parece com isso:

- -
  function receiveChannelCallback(event) {
-    receiveChannel = event.channel;
-    receiveChannel.onmessage = handleReceiveMessage;
-    receiveChannel.onopen = handleReceiveChannelStatusChange;
-    receiveChannel.onclose = handleReceiveChannelStatusChange;
-  }
- -

O evento{{event("datachannel")}} inclui, em sua propriedade de canal, uma referência a um {{domxref("RTCDataChannel")}} Representando o ponto remoto do canal. Isso é salvo, e nós configuramos, no canal, ouvintes de eventos para os eventos que queremos manipular. Uma vez feito isso, nosso método handleReceiveMessage() Será chamado cada vez que os dados são recebidos pelo ponto remoto, e o método handleReceiveChannelStatusChange() será chamado sempre que mudar o estado da conexão do canal, para que possamos reagir quando o canal estiver totalmente aberto e quando ele for fechado.

- -

Lidando com as mudanças de status do canal

- -

Ambos nossos pontos locais e remotos usam um único método para lidar com eventos que indicam alguma alteração no status da conexão do canal.

- -

Quando o ponto local experimenta um evento aberto ou fechado, o métodohandleSendChannelStatusChange() é chamado:

- -
  function handleSendChannelStatusChange(event) {
-    if (sendChannel) {
-      var state = sendChannel.readyState;
-
-      if (state === "open") {
-        messageInputBox.disabled = false;
-        messageInputBox.focus();
-        sendButton.disabled = false;
-        disconnectButton.disabled = false;
-        connectButton.disabled = true;
-      } else {
-        messageInputBox.disabled = true;
-        sendButton.disabled = true;
-        connectButton.disabled = false;
-        disconnectButton.disabled = true;
-      }
-    }
-  }
- -

Se o estado do canal mudou para "open", isso indica que terminamos de estabelecer o link entre os dois pares. A interface do usuário é atualizada de forma correspondente: ativando o elemento de input de texto para a mensagem a ser enviada, focando este elemento de input para que o usuário comece imediatamente a digitar, habilitando os botões "Enviar" e "Desconectar", que são agora utilizáveis, E desativando o botão "Conectar", uma vez que não é necessário quando a conexão está aberta.

- -

Se o estado do canal mudou para "closed", ocorre o conjunto oposto de ações: a caixa de entrada de texto e o botão "Enviar" estão desativados, o botão "Conectar" está habilitado para que o usuário possa abrir uma nova conexão se desejar, e o botão "Desconectar" está desativado, uma vez que não é útil quando não existe conexão.

- -

Nosso exemplo de par remoto, por outro lado, ignora os eventos de alteração de status, exceto para registrar o evento no console:

- -
  function handleReceiveChannelStatusChange(event) {
-    if (receiveChannel) {
-      console.log("Receive channel's status has changed to " +
-                  receiveChannel.readyState);
-    }
-  }
- -

O método handleReceiveChannelStatusChange() recebe como parâmetro de entrada o evento que ocorreu; Este será um {{domxref("RTCDataChannelEvent")}}.

- -

Enviando mensagens

- -

Quando o usuário pressiona o botão "Enviar", o método sendMessage() que estabelecemos como o manipulador para o evento do botão {{event("click")}} é chamado. Esse método é bastante simples:

- -
  function sendMessage() {
-    var message = messageInputBox.value;
-    sendChannel.send(message);
-
-    messageInputBox.value = "";
-    messageInputBox.focus();
-  }
- -

Primeiro, o texto da mensagem é obtido dos atributos do elemento de input {{htmlattrxref("value", "input")}} . Isso é enviado para o ponto remoto, ligando para {{domxref("RTCDataChannel.send", "sendChannel.send()")}}. E está tudo aí! O resto deste método é apenas um pouco de açúcar para experiência do usuário - a caixa de entrada é esvaziada e re-focada para que o usuário comece imediatamente a digitar outra mensagem.

- -

Recebendo mensagens

- -

Quando ocorre um evento de "mensagem" no canal remoto, nosso método handleReceiveMessage() é chamado como o manipulador de eventos.

- -
  function handleReceiveMessage(event) {
-    var el = document.createElement("p");
-    var txtNode = document.createTextNode(event.data);
-
-    el.appendChild(txtNode);
-    receiveBox.appendChild(el);
-  }
- -

Este método simplesmente executa alguns injeções básicas {{Glossary("DOM")}} ; cria um novo {{HTMLElement("p")}} (paragraph) elemento, então cria um novo nó {{domxref("Text")}} contendo o texto da mensagem, que é recebido na propriedade de dados do evento. Este nó de texto é anexado como um filho do novo elemento, que é então inserido no bloco receiveBox, fazendo com que ele desenhe na janela do navegador.

- -

Desconectando os pares (peers)

- -

Quando o usuário clica no botão "Desconectar", o método disconnectPeers() previamente configurado como o manipulador desse botão é chamado.

- -
  function disconnectPeers() {
-
-    // Close the RTCDataChannels if they're open.
-
-    sendChannel.close();
-    receiveChannel.close();
-
-    // Close the RTCPeerConnections
-
-    localConnection.close();
-    remoteConnection.close();
-
-    sendChannel = null;
-    receiveChannel = null;
-    localConnection = null;
-    remoteConnection = null;
-
-    // Update user interface elements
-
-    connectButton.disabled = false;
-    disconnectButton.disabled = true;
-    sendButton.disabled = true;
-
-    messageInputBox.value = "";
-    messageInputBox.disabled = true;
-  }
-
- -

Isso começa por fechar cada par {{domxref("RTCDataChannel")}}, então, de forma semelhante, cada um {{domxref("RTCPeerConnection")}}. Então, todas as referências salvas desses objetos são definidas como null para evitar a reutilização acidental, e a interface do usuário é atualizada para refletir o fato de que a conexão foi fechada.

- -

Próximos passos

- -

Você poderia tentar este exemplo e dar uma olhada no código fonte webrtc-simple-datachannel, disponível no GitHub.

diff --git a/files/pt-br/web/api/websockets_api/index.html b/files/pt-br/web/api/websockets_api/index.html new file mode 100644 index 0000000000..1a24b9d86a --- /dev/null +++ b/files/pt-br/web/api/websockets_api/index.html @@ -0,0 +1,178 @@ +--- +title: WebSockets +slug: WebSockets +tags: + - Referencia + - Sumario + - WebSockets +translation_of: Web/API/WebSockets_API +--- +

WebSockets é uma tecnologia avançada que torna possível abrir uma sessão de comunicação interativa entre o navegador do usuário e um servidor. Com esta API, você pode enviar mensagens para um servidor e receber respostas orientadas a eventos sem ter que consultar o servidor para obter uma resposta.

+ +
+
+

Documentação

+ +
+
Escrevendo aplicações cliente WebSocket
+
Um tutorial para escrever clientes WebSocket para ser executado no browser.
+
Referencias WebSockets
+
Uma referência para a API WebSocket do lado do cliente.
+
(TBD)Escrevendo servidores WebSocket
+
Um guia para escrever código do lado do servidor para lidar com o protocolo WebSocket.
+
+ +

Saiba mais...

+
+ +
+

Ferramentas

+ + + + + + +
+
+ +

Veja Também

+ + + + + +

{{CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CaracterísticasChromeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte a versão 76 {{obsolete_inline}}6{{CompatGeckoDesktop("2.0")}}{{CompatNo}}11.00 (desativado)5.0.1
Protocolo suporta versão 7 {{obsolete_inline}}{{CompatNo}}{{CompatGeckoDesktop("6.0")}}
+ {{property_prefix("Moz")}}		{{CompatNo}}{{CompatNo}}{{CompatNo}}
Protocolo suporta versão 10 {{obsolete_inline}}14{{CompatGeckoDesktop("7.0")}}
+ {{property_prefix("Moz")}}		HTML5 Labs{{CompatUnknown}}{{CompatUnknown}}
Suporte padrão - RFC 645516{{CompatGeckoDesktop("11.0")}}1012.106.0
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CaracterísticasAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte a versão 76 {{obsolete_inline}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
Protocolo suporta versão 7 {{obsolete_inline}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
Protocolo suporta versão 8 (IETF rascunho 10) {{obsolete_inline}}{{CompatUnknown}}{{CompatGeckoMobile("7.0")}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
Suporte padrão - RFC 645516 (Chrome){{CompatGeckoDesktop("11.0")}}{{CompatUnknown}}12.106.0
+
+ +

Notas Gecko

+ +

O suporte a WebSockets no Firefox continua acompanhando as constantes especificações do WebSocket. O Firefox 6 implementa a versão 7 do protocolo subjacente, enquanto o Firefox 7 implementa a versão 8 (conforme especificado pelo rascunho IETF 10). O Firefox móvel recebeu suporte WebSocket no Firefox mobile 7.0.

+ +

Gecko 6.0

+ +

Antes do Gecko 6.0 {{geckoRelease("6.0")}}, estava incorreto, um objeto WebSocket que alguns sites implicavam que os serviços WebSocket não eram prefixados. Este objeto foi renomeado para MozWebSocket.

+ +

Gecko 7.0

+ +

Iniciado no Gecko 7.0 {{geckoRelease("7.0")}}, o network.websocket.max-connections preferencialmente usado para determinar o número máximo de conexões do WebSocket que pode m ser abertas de cada vez. O valor padrão é 200.

+ +

Gecko 8.0

+ +

Iniciado no Gecko 8.0 {{geckoRelease("8.0")}}, a extensão de fluxo de expansão para o protocolo WebSocket foi desativada, por estar obsoleta nas especificações. Isso resolve incompatibilidades com alguns sites.

+ +

Gecko 11.0

+ +

Antes do Gecko 11.0, as mensagens recebidas e enviadas estavam limitadas a 16 MB de tamanho. Agora elas podem ter até 2 GB de tamanho. Note, no entanto, que as limitações de memória (especialmente em dispositivos móveis) tornam isso apenas teoria, não se aplica à prática. Na realidade, as transferências desse tamanho falharão em dispositivos que não possuem memória suficiente.

+ +

Além disso, o ArrayBuffer envia e recebe suporte para dados binários

+ +

Iniciado no Gecko 11.0, a API do WebSocket já não é prefixada.

+ +
Atenção:Entre outras coisas, um motivo chave para o WebSockets estar desativado por padrão no Firefox 4 e 5 é a descoberta de um Problema de segurança no design do protocolo. Isso foi corrigido no Firefox 6 implementando uma versão mais recente do protocolo que corrige o problema.
diff --git a/files/pt-br/web/api/websockets_api/writing_websocket_client_applications/index.html b/files/pt-br/web/api/websockets_api/writing_websocket_client_applications/index.html new file mode 100644 index 0000000000..af608ae641 --- /dev/null +++ b/files/pt-br/web/api/websockets_api/writing_websocket_client_applications/index.html @@ -0,0 +1,182 @@ +--- +title: Escrevendo aplicações cliente WebSocket +slug: WebSockets/Escrevendo_aplicacoes_cliente_WebSocket +tags: + - Cliente + - Exemplo + - Guía + - WebSocket API +translation_of: Web/API/WebSockets_API/Writing_WebSocket_client_applications +--- +

Aplicações cliente usam o WebSocket API para se comunicar com WebSocket servers sob o protocolo WebSocket.

+ +

{{AvailableInWorkers}}

+ +
+

O fragmento de código neste artigo foi tomado de um exemplo de chat usando WebSocket. veja o código, então experimente o exemplo. O exemplo atual possui um bug; ele está tentando usar WebSockets inseguro e precisa ser atualizado para usar WebSocokets seguro. Iremos arrumar isso em breve!

+
+ +

Criando um objeto WebSocket 

+ +

Para se comunicar utilizando o protocolo WebSocket, você precisa criar um objeto WebSocket, que automaticamente tentará abrir a conexão com o servidor.

+ +

O construtor WebSocket aceita dois campos, um obrigatório e um opcional:

+ +
WebSocket WebSocket(
+  in DOMString url,
+  in optional DOMString protocols
+);
+
+ +
+
url
+
A URL para se conectar. Esta deve ser a URL para qual o WebSocket irá responder.
+
protocols {{ optional_inline() }}
+
Uma única string indicando o protocolo ou uma array de strings de protocolos. Estas strings são usadas para indicar sub-protocolos, de forma que um único servidor pode implementar múltiplos sub-protocolos WebSocket (por exemplo, você pode querer que um servidor seja capaz de lidar com diferentes tipos de interações a depender do protocol especificado). Se não especificar uma string de protocolo, uma string vazia é assumida.
+
+ +

O construtor lançará a exceção SECURITY_ERR se o destino não permitir acesso. Isso pode acontecer se você tentar utilizar uma conexão insegura (a maioria dos {{Glossary("user agent", "user agents")}} agora necessitam de um link seguro para todas as conexões WebSocket, a menos que estejam no mesmo dispositivo ou na mesma rede).

+ +
+
+ +

Erros de Conexão

+ +

Se um erro ocorrer durante a tentativa de conexão, primeiro um simpes evento com o nome "error" é enviado ao objeto WebSocket  (invocando, assim, seu manipulador onerror), e então o CloseEvent é enviado ao objeto WebSocket (invocando o manipulador onclose) para indicar a razão pela qual a conexão foi fechada.

+ +

O browser pode exibir uma descrição de erro mais detalhada na saída do console, ou mesmo um código de encerramento conforme definido na RFC 6455, Section 7.4 através do CloseEvent. Está implementado a partir do Firefox 11.

+ +

Exemplos

+ +

Neste simples exemplo, criaremos um novo WebSocket, conectando ao servidor em ws://www.example.com/socketserver. Neste exemplo utilizaremos um protocolo customizado denominado "protocolOne", embora possa ser omitido.

+ +
var exampleSocket = new WebSocket("ws://www.example.com/socketserver", "protocolOne");
+
+ +

No retorno, exampleSocket.readyState está como CONNECTING. O readyState se tornará OPEN quando a conexão estiver pronta para transferir dados.

+ +

Se quiser abrir uma conexão e for flexível quanto aos protocolos suportados, você pode especificar um array de protocolos:

+ +
var exampleSocket = new WebSocket("ws://www.example.com/socketserver", ["protocolOne", "protocolTwo"]);
+
+ +

Uma vez que a conexão for estabelecida (isso é, readyState está OPEN), exampleSocket.protocol informará qual protocolo o servidor selecionou.

+ +

Nos exemplos acima, ws foi substituído por http, de forma similar wss substitui https. Estabelecer uma conexão WebSocket depende do Mecanismo de Aprimoramento HTTP, de forma que o pedido para atualização de protocolo está implícito quando endereçamos o servidor HTTP como ws://www.example.com ou wss://www.example.com.

+ +

Enviando dados ao servidor

+ +

Uma vez a conexão aberta, você pode iniciar a transmisão de dados ao servidor. Para tanto, chame o método send() do WebSocket para cada mensagem que queira enviar:

+ +
exampleSocket.send("Aqui vai algum texto que o servidor esteja aguardando urgentemente!");
+
+ +

Você pode enviar dados como uma string, {{ domxref("Blob") }}, ou um ArrayBuffer.

+ +
Note: Nas versões anteriores à 11, o Firefox suporta apenas o envio de dados como string.
+ +

Visto que estabelecer uma conexão funciona de forma assícrona e, consequentemente, propensa a erros, não há garantia de sucesso ao chamar o método send() imediatamente após criar um objeto WebSocket. Podemos, pelo menos, ter certeza de que a tentativa de envio dos dados apenas ocorre quando uma conexão é estabelecida definindo um manipulador de eventos onopen:

+ +
exampleSocket.onopen = function (event) {
+  exampleSocket.send("Aqui vai algum texto que o servidor esteja aguardando urgentemente!");
+};
+
+ +

Utilizando JSON para transmitir objetos

+ +

Uma forma conveniente é usar JSON para enviar dados razoavelmente complexos ao servidor. Por exemplo, um aplicação de chat pode interagir  com o servidor empregando um protocolo que utilize pacotes de dados  JSON encapsulados:

+ +
// Enviar texto para todos os usuarios atraves do servidor
+function sendText() {
+  // Construir um objeto do tipo msg contendo o dado que o servidor precisa processar a partir do cliente de chat.
+  var msg = {
+    type: "message",
+    text: document.getElementById("text").value,
+    id:   clientID,
+    date: Date.now()
+  };
+
+  // Enviar o objeto msg como um JSON em formato de string.
+  exampleSocket.send(JSON.stringify(msg));
+
+  // Esvaziar o campo input do elemento text, pronto pra receber a próxima linha de texto do usuário.
+  document.getElementById("text").value = "";
+}
+
+ +

Recebendo mensagens do servidor

+ +

A API WebSockets é dirigida por eventos; quando mensagens são recebidas, um evento de "mensagem" é entregue à função onmessage. Para começar a ouvir os dados de entrada, você pode fazer algo conforme o exemplo abaixo:

+ +
exampleSocket.onmessage = function (event) {
+  console.log(event.data);
+}
+
+ +

Recebendo e interpretando objetos JSON

+ +

Vamos considerar que a aplicação cliente de chat remete o envio de dados {{ anch("Utilizando JSON para transmitir objetos") }}. Existem diversos tipos de pacotes de dados que o cliente pode receber, tais como:

+ + + +

O código que interpreta as mensagens de entrada se parecerá com esse:

+ +
exampleSocket.onmessage = function(event) {
+  var f = document.getElementById("chatbox").contentDocument;
+  var text = "";
+  var msg = JSON.parse(event.data);
+  var time = new Date(msg.date);
+  var timeStr = time.toLocaleTimeString();
+
+  switch(msg.type) {
+    case "id":
+      clientID = msg.id;
+      setUsername();
+      break;
+    case "username":
+      text = "<b>User <em>" + msg.name + "</em> signed in at " + timeStr + "</b><br>";
+      break;
+    case "message":
+      text = "(" + timeStr + ") <b>" + msg.name + "</b>: " + msg.text + "<br>";
+      break;
+    case "rejectusername":
+      text = "<b>Seu usuario foi configurado como <em>" + msg.name + "</em> porque o nome que você escolheu está em uso.</b><br>"
+      break;
+    case "userlist":
+      var ul = "";
+      for (i=0; i < msg.users.length; i++) {
+        ul += msg.users[i] + "<br>";
+      }
+      document.getElementById("userlistbox").innerHTML = ul;
+      break;
+  }
+
+  if (text.length) {
+    f.write(text);
+    document.getElementById("chatbox").contentWindow.scrollByPages(1);
+  }
+};
+
+ +

Aqui utilizamos JSON.parse() para conveter o objeto JSON de volta ao objeto original, em seguida, examine e aja de acordo com seu conteúdo.

+ +

Formato de dados de texto

+ +

O formato de Texto recebido através de uma conexão WebSocket está no formato UTF-8.

+ +

Fechando a conexão

+ +

Quando finalizar o uso da conexão WebSocket, invoque o método close():

+ +
exampleSocket.close();
+
+ +

Pode ser útil examinar o atributo bufferedAmount do socket  antes de tentar fechar a conexão para determinar se qualquer dado ainda está pendente de transmissão na rede. 

+ +

Considerações de segurança

+ +

WebSockets não devem ser utilizados em um contexto de um ambiente misto, isto é, você não deveria abrir uma conexão não-segura a partir de uma página previamente carregada utilizando HTTPS, ou vice-versa. A maioria dos browsers atuamente apenas permitem conexões seguras pelo Websocke, e não mais suportam contextos diferentes desse.

diff --git a/files/pt-br/web/api/websockets_api/writing_websocket_server/index.html b/files/pt-br/web/api/websockets_api/writing_websocket_server/index.html new file mode 100644 index 0000000000..553ba11aec --- /dev/null +++ b/files/pt-br/web/api/websockets_api/writing_websocket_server/index.html @@ -0,0 +1,237 @@ +--- +title: 'Escrevendo um servidor WebSocket em C #' +slug: WebSockets/Writing_WebSocket_server +translation_of: Web/API/WebSockets_API/Writing_WebSocket_server +--- +

Introdução

+ +

Se você quiser usar uma API WebSocket, você precisara ter um servidor. Neste artigo vou mostrar como escrever um WebSocket em C#. Você pode fazer isso em qualquer linguagem server-side, mas para manter as coisas simples e mais compreensíveis eu escolhi uma linguagem Microsoft.

+ +

Este servidor está em conformidade com a RFC 6455, por isso irá tratar apenas as conexões com os navegadores Chrome versão 16, Firefox 11, IE 10 ou superior. 

+ +

Primeiros passos

+ +

Os WebSocket´s se comunicam através de uma conexão TCP (Transmission Control Protocol), felizmente o C# possui a classe TcpListener que, como o nome sugere, tem a função de escutar (Listener) as comunicações via TCP. A classe TcpListener está no namespace System.Net.Sockets.

+ +
+

É uma boa idéia usar a palavra chave using para escrever menos. Isso significa que não é preciso você reescrever o namespace toda vez que usar uma classe dele.

+
+ +

TcpListener

+ +

Construtor:

+ +
TcpListener(System.Net.IPAddress localaddr, int port)
+ +

Aqui você define onde o servidor será acessível.

+ +
+

Para setar facilmente o tipo esperado no primeiro parâmetro, use o método estático Parse da classe IPAddress.

+
+ +

Métodos:

+ + + +

Veja como usar o que aprendemos:

+ +
​using System.Net.Sockets;
+using System.Net;
+using System;
+
+class Server {
+    public static void Main() {
+        TcpListener server = new TcpListener(IPAddress.Parse("127.0.0.1"), 80);
+
+        server.Start();
+        Console.WriteLine("Server has started on 127.0.0.1:80.{0}Waiting for a connection...", Environment.NewLine);
+
+        TcpClient client = server.AcceptTcpClient();
+
+        Console.WriteLine("A client connected.");
+    }
+}
+
+ +

TcpClient

+ +

Métodos:

+ + + +

Propriedades:

+ + + +

NetworkStream

+ +

Métodos:

+ +
Write(Byte[] buffer, int offset, int size)
+ +

Grava bytes do buffer, offset e size determinam o tamanho da mensagem.

+ +
Read(Byte[] buffer, int offset, int size)
+ +

Lê bytes para o buffer, offset e size determinam o tamanho da mensagem. 

+ +

Vamos estender nosso exemplo.

+ +
TcpClient client = server.AcceptTcpClient();
+
+Console.WriteLine("A client connected.");
+
+NetworkStream stream = client.GetStream();
+
+//enter to an infinite cycle to be able to handle every change in stream
+while (true) {
+    while (!stream.DataAvailable);
+
+    Byte[] bytes = new Byte[client.Available];
+
+    stream.Read(bytes, 0, bytes.Length);
+}
+ +

Handshaking

+ +

Quando um cliente se conecta a um servidor, ele envia uma solicitação GET para atualizar a conexão com o WebSocket a partir de uma simples requisição HTTP. Isto é conhecido como handshaking (aperto de mão).

+ +
+

Este código tem um defeito. Digamos que a propriedade client.Available retorna o valor 2 porque somente a requisição GET está disponível até agora. a expressão regular iria falhar mesmo que os dados recebidos sejam perfeitamente válidos.

+
+ +
using System.Text;
+using System.Text.RegularExpressions;
+
+Byte[] bytes = new Byte[client.Available];
+
+stream.Read(bytes, 0, bytes.Length);
+
+//translate bytes of request to string
+String data = Encoding.UTF8.GetString(bytes);
+
+if (new Regex("^GET").IsMatch(data)) {
+
+} else {
+
+}
+ +

Criar a resposta é mais fácil do que entender porque você deve fazê-lo desta forma.

+ +

Você deve,

+ +
    +
  1. Obter o valor do cabeçalho da requisição Sec-WebSocket-Key sem qualquer espaço à direita e à esquerda;
    2. +
  2. Concatenar com "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
    3. +
  3. Calcular o código SHA-1 e Base64 dele;
    4. +
  4. Reescreva no cabeçalho de resposta o valor de Sec-WebSocket-Accept como parte de uma resposta HTTP.
    5. +
+ +
if (new Regex("^GET").IsMatch(data)) {
+    Byte[] response = Encoding.UTF8.GetBytes("HTTP/1.1 101 Switching Protocols" + Environment.NewLine
+        + "Connection: Upgrade" + Environment.NewLine
+        + "Upgrade: websocket" + Environment.NewLine
+        + "Sec-WebSocket-Accept: " + Convert.ToBase64String (
+            SHA1.Create().ComputeHash (
+                Encoding.UTF8.GetBytes (
+                    new Regex("Sec-WebSocket-Key: (.*)").Match(data).Groups[1].Value.Trim() + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+                )
+            )
+        ) + Environment.NewLine
+        + Environment.NewLine);
+
+    stream.Write(response, 0, response.Length);
+}
+
+ +

Decodificação de mensagens

+ +

Após um handshake de sucesso o cliente ponde enviar mensagens ao servidor, mas agora estas mensagens são codificadas.

+ +

Se nós enviarmos "MDN", nós obtemos estes bytes:

+ + + + + + + + + + + + + + + +
129131618435611216109
+ +

- 129:

+ + + + + + + + + + + + + + + + + + + + +
FIN (Esta é toda a mensagem?)RSV1RSV2RSV3Opcode
10000x1=0001
+ +

FIN: Você pode enviar sua mensagem em quadros (frames), mas agora as coisas ficaram mais simples.
+ Opcode 0x1 significa que este é um texto. Veja aqui a lista completa de Opcodes.

+ +

- 131:

+ +

Se o segundo byte menos 128 estiver entre 0 e 125, este é o tamanho da mensagem. Se for 126, os 2 bytes seguintes (16-bit inteiro sem sinal) e se 127, os 8 bytes seguintes (64-bit inteiro sem sinal) são o comprimento.

+ +
+

Eu posso escolher 128, porque o primeiro bit sempre será 1.

+
+ +

- 61, 84, 35 e 6 são os bytes de chave para decodificar. Sempre mudam.

+ +

- O restante dos bytes codificados são a mensagem.

+ +

Algoritmo de decodificação

+ +

byte decodificado = [byte codificado XOR (posição do byte codificado MOD 4º byte da chave)]

+ +

Exemplo em C#:

+ +
Byte[] decoded = new Byte[3];
+Byte[] encoded = new Byte[3] {112, 16, 109};
+Byte[] key = Byte[4] {61, 84, 35, 6};
+
+for (int i = 0; i < encoded.Length; i++) {
+    decoded[i] = (Byte)(encoded[i] ^ key[i % 4]);
+}
+ + + + + +
 
diff --git a/files/pt-br/web/api/websockets_api/writing_websocket_servers/index.html b/files/pt-br/web/api/websockets_api/writing_websocket_servers/index.html new file mode 100644 index 0000000000..e493605538 --- /dev/null +++ b/files/pt-br/web/api/websockets_api/writing_websocket_servers/index.html @@ -0,0 +1,263 @@ +--- +title: Escrevendo um servidor WebSocket +slug: WebSockets/Writing_WebSocket_servers +tags: + - Guía + - HTML5 + - Tutorial + - WebSocket + - WebSockets +translation_of: Web/API/WebSockets_API/Writing_WebSocket_servers +--- +

Um servidor de WebSocket  é uma aplicação TCP que escuta uma porta de um servidor que segue um protocolo específico, simples assim. A tarefa de criar um servidor personalizado costuma assustar as pessoas; no entanto, pode ser fácil implementar um simples servidor WebSocket na sua plataforma de escolha. 

+ +

Um servidor WebSocket pode ser escrito em qualquer linguagem de programação server-side  que é capaz de utilizar Berkeley sockets,  tais como C(++) , ou Python, ou mesmo o PHP e o server-side JavaScript. Esse não é um tutorial em uma linguagem de programação específica, mas serve como guia para facilitar a escrita do seu próprio servidor.

+ +

Você precisará saber como o HTTP funciona e ter uma experiência média com programação.

+ +

Dependendo do suporte da linguagem, pode ser necessário o conhecimento sobre soquetes TCP. O escopo deste guia é apresentar o conhecimento mínimo que você precisa para escrever um servidor WebSocket.

+ +
+

Leia a útlima especificação sobre WebSockets, a RFC 6455. As seções 1 e 4-7 são especialmente interessantes para implementadores de servidores. A seção 10 discute assuntos sobre segurança que você definitivamente deveria examinar antes de expor seu servidor.

+
+ +

Um servidor de WebSocket é explicado de maneira bem simples aqui. Servidores de WebSocket geralmente são servidores separados e especializados (para balanceamento de carga ou outras razões práticas), então, geralmente você irá usar um proxy reverso (como um servidor HTTP comum) para detectar a solicitação de handshakes do WebSocket, pré-processá-los e enviar esses clientes para um servidor WebSocket real. Isso significa que você não precisa encher seu código com cookies e manipuladores de autenticação (por exemplo).

+ +

O Handshake ("aperto de mão") do WebSocket

+ +

Primeiro de tudo, o servidor deve ouvir as conexões socket recebidas usando um socket TCP padrão. Dependendo da sua plataforma, isso pode já ter sido tratado previamente. Por exemplo, vamos assumir que seu servidor está ouvindo example.com, porta 8000, e seu servidor socket responde às requisições  GET em /chat.

+ +
+

Aviso: O servidor pode ouvir qualquer porta que escolher, mas se escolher qualquer porta diferente de 80 e 443, podem ocorrer problemas relacionados aos firewalls e/ou proxies. Conexões na porta 443 tendem a ter mais sucesso com mais frequência, isso requer uma conexão segura (TLS/SSL). Também, note que a maioria dos browsers (notavelmente o  Firefox 8+) não permite conexões de servidores WebSocket de páginas seguras.

+
+ +

O handshake é a "Web" no WebSockets. É a ponte do HTTP para o Websocket. No handshake, detalhes da conexão são negociados, e qualquer uma das partes pode voltar antes da conclusão se os termos são desfavoráveis. O servidor deve ser cuidadoso para entender tudo que o cliente perguntar,  caso contrário, serão introduzidas questões de segurança.

+ +

Requisição Handshake do Cliente

+ +

Mesmo que você esteja construindo um servidor, um cliente ainda precisa iniciar o processo de handshake do WebSocket. Então você deve saber como interpretar a requisição do cliente. O cliente vai enviar uma requisição HTTP padrão que é parecida com isso (a versão do HTTP deve ser 1.1 ou maior, e o método deve ser um GET):

+ +
GET /chat HTTP/1.1
+Host: example.com:8000
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
+Sec-WebSocket-Version: 13
+
+
+ +

O cliente pode solicitar extensões e/ou subprotocolos aqui; veja Miscellaneous para mais detalhes. Também, cabeçalhos comuns como User-Agent, Referer, Cookie, ou cabeçalhos de autenticação poderiam estar bem aqui. Faça o que você quiser com eles; eles não pertencem diretamente ao WebSocket. Também é seguro ignora-los. Em muitas configurações comuns, um proxy reverso ja tratou deles.

+ +

Se qualquer cabeçalho não foi entendido ou conter um valor incorreto, o servidor deve enviar um erro "400 Bad Request" e fechar o socket imediatamente. É comum, também dar a razão pelo qual o handshake falhou no body da resposta do HTTP, mas muitas mensages nunca serão mostradas (os browsers não mostram isso). Se o servidor não reconhecer a versão do WebSockets, deve enviar um cabeçalho Sec-WebSocket-Version que contenha a(s) versão(versões) que o mesmo entenda. (Esse guia explica o v13, o mais novo). Agora, vamos continuar para o cabeçalho mais curioso, o Sec-WebSocket-Key.

+ +
+

Dica: Todos os browsers  vão enviar um Origin header. Você pode usar esse cabeçalho por segurança (verifique pelo de mesma origem, whitelisting/ blacklisting, etc.) e envie uma 403 Forbidden se você não gostou do que viu. Sobretanto, fique ciente que os agentes non-browser podem apenas enviar uma falsa Origin. Muitas aplicações vão rejeitar requisições sem cabeçalho.

+
+ +
+

Dica: A request-uri (/chat aqui) não tem significado definido na especificação. Muitas pessoas utilizam habilmente para que servidores lidem com muiltíplas aplicações WebSocket. Por exemplo, example.com/chat deve invocar um app de chat com multiplos usuários, enquanto /game no mesmo servidor poderia invocar um jogo multiplayer.

+
+ +
+

Nota: Regular HTTP status codes podem apenas ser usados antes do handshake. Depois que o handshake sucede, você deve usar um conjunto de códigos diferentes (definidos na seção 7.4 da especificação).

+
+ +

Resposta Handshake do Servidor

+ +

Quanto o servidor receber a requisição de handshake, ele deve enviar um resposta especifica (odd-looking) que indica que o protocolo está sendo alterado de HTTP para WebSocket. Essa resposta se parece com isso (lembre-se cada final do cabeçalho com \r\n e coloque um \r\n extra depois do último):

+ +
HTTP/1.1 101 Switching Protocols
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
+
+
+ +

Adicionalmente, o servidor pode decidir sobre os pedidos de extensão/subprotocolo aqui; veja Miscellaneous para mais detalhes. O Sec-WebSocket-Accept é uma parte interessante. O servidor deve deriva-lo do Sec-WebSocket-Key que o cliente enviou. Para obte-lo, concatene o Sec-WebSocket-Key do cliente e a string "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" juntos (isso é uma "magic string"), pegue o SHA-1 hash do resultado, e retorne o codigo base64 do hash.

+ +
+

FYI: Esse processo, aparentemente complicado existe para que seja óbvio para o cliente se o servidor suporta ou não o WebSockets. Isso é importante por causa de problemas com segurança que aparecem se o servidor aceita a conexão WebSocket mas interpreta que os dados são uma requisição HTTP.

+
+ +

Então se a chave foi "dGhlIHNhbXBsZSBub25jZQ==", o cabeçalho Sec-WebSocket-Accept aceito será "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=". Uma vez que o servidor envie estes cabeçalhos, o handshake esta completo e você pode começar a trocar dados!

+ +
+

O servidor pode enviar outros cabeçalhos como Set-Cookie, ou perguntar por autenticação ou redirecionar via outros códigos de status, antes enviando  a resposta do handshake.

+
+ +

Acompanhamento dos clientes

+ +

Isso não está diretamente relacionado ao protocolo de WebSocket, mas vale apena mencionar aqui: seu servidor terá que acompanhar os soquetes dos clientes para que você não tenho que fazer o handshake novamente com clientes que já concluiram o handshake. O mesmo endereço IP do cliente pode tentar se conectar varias vezes (mas o servidor pode negar se tentarem fazer muitas conexões em razão de se defender de ataques de negação de serviço).

+ +

Trocando Data Frames

+ +

Tanto o cliente quanto o servidor podem enviar mensagens a qualquer momento — essa é a mágia do WebSocket. Entretanto, extrair informações desses chamados "frames" de dados não é um experiencia tão magica assim. Apesar de todos os frames seguirem um mesmo formato, os dados do cliente são enviados criptografados para o servidor, usando criptografia XOR (com uma chave de 32 bits). A seção 5 da especificação do protocolo de WebSocket descreve isso em detalhes.

+ +

Formato

+ +

Cada data frame (do cliente para o servidor ou vice-versa) segue o mesmo formato:

+ +
Frame format:
+​​
+      0                   1                   2                   3
+      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+     +-+-+-+-+-------+-+-------------+-------------------------------+
+     |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
+     |I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
+     |N|V|V|V|       |S|             |   (if payload len==126/127)   |
+     | |1|2|3|       |K|             |                               |
+     +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
+     |     Extended payload length continued, if payload len == 127  |
+     + - - - - - - - - - - - - - - - +-------------------------------+
+     |                               |Masking-key, if MASK set to 1  |
+     +-------------------------------+-------------------------------+
+     | Masking-key (continued)       |          Payload Data         |
+     +-------------------------------- - - - - - - - - - - - - - - - +
+     :                     Payload Data continued ...                :
+     + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
+     |                     Payload Data continued ...                |
+     +---------------------------------------------------------------+
+ +

O bit de MASK simplesmente diz se a mensagem está codificada. Mensagens do cliente devem estar mascaradas, então seu servidor deve esperar que o valor de MASK seja 1. De fato, a seção 5.1 da especificação diz que seu servidor deve se desconectar de um cliente se este cliente enviar mensagens que não estão mascaradas. Quando enviando um frame para o cliente, não mascare a mensagem e não defina o bit MASK. Explicaremos o mascaramento mais tarde.

+ +
+

Você tem que mascarar as mensagens mesmo quando usando secure socket (SSL).
+ Os campos RSV de 1 à 3 do cabeçalho podem ser ignorados, eles são para extenções.

+
+ +

O campo opcode define como interpretar o payload data: 0x0 para continuo, 0x1 para texto (que sempre está codificadao em UTF-8), 0x2 para binário, e outros conhecidos como "control codes" seram discutidos posteriormente. Nessa versão de WebSockets, 0x3, a 0x7 e 0xB a 0xF tem o mesmo significado.

+ +

O bit FIN disso se é a ultima mensagem da serie. Se for 0, então o servidor irá continuar esperando por mair partes da mensagem;  caso contrário, o servidor pode considerar a mensagem como enviada.

+ +

Se falará mais sobre isso depois.

+ +

Decodificando o Payload Length

+ +

Para ler o payload data, você deve saber quando parar de ler. Por isso é importante saber o tamanho do payload (payload length). Infelizmente,  conseguir essa informação é de certa forma complicado. Para obte-lá, seguimos esses passos:

+ +
    +
  1. Ler os bits 9-15 (inclusivo) e interpretar como um unsigned integer. Se o valor for de 125 ou menor, esse é o tamanho; temos a resposta. Se o valor é igual a 126, então vai para o passo 2, ou se for 127, então vai para o passo 3.
    2. +
  2. Ler os próximos 16 bits e interpretar como um unsined integer, esse é o tamanho; temos a resposta
    3. +
  3. Ler os próximos 64 bits e interpretar como um unsigned integer (o bit mais significante DEVE ser 0), esse é o tamanho; temos a resposta.
    4. +
+ +

Lendo e Desmascarando o Dado

+ +

Se o bit MASK for definido (e deve estar, para mensagens cliente-para-servidor), leia os próximos 4 octetos (32 bits); isso é a chave da mascara. Uma vez que o payload length e o masking key são decodificados, você pode seguir em frente e ler o número de bytes do socket.

+ +

Vamos chamar os dados de ENCODED, e a chave de MASK.

+ +

Para conseguir o DECODED, faça um loop sobre os octetos de ENCODED e um XOR do (i módulo 4) ezimo octeto de MASK. Em pseudo-código (isso é para ser valida em JavaScript):

+ +
var DECODED = "";
+for (var i = 0; i < ENCODED.length; i++) {
+    DECODED[i] = ENCODED[i] ^ MASK[i % 4];
+}
+ +

Agora você pode descobrir o que DECODED significa, dependendo da sua aplicação.

+ +

Fragmentação de Mensagens

+ +

Os campos FIN e opcode trabalham juntos para enviar uma mensagens quebradas em mais de um frame. Isso é chamado de fragmentação. Fragmentação está disponível apenas sobre opcode 0x0 a 0x2.

+ +

Lembre que o opcode diz o que o frame deve fazer. Se for 0x1, o payload um é texto. Se for 0x2, o payload são dados binários. Entretanto, se for 0x0, o frame é umframe de continuação. Isso significa que o servidor deve concatenar o frame de payload com o último frame recebido do cliente.

+ +

Aqui está um exemplo, de como o servidor reage a um cliente enviando uma mensagem de texto. A primeira mensagem é enviada em um frame unico, enquanto a segunda mensagem é enviada através de tres frames. Os detalhes de FIN e opcode são mostrados apenas para o cliente:

+ +
Client: FIN=1, opcode=0x1, msg="hello"
+Server: (process complete message immediately) Hi.
+Client: FIN=0, opcode=0x1, msg="and a"
+Server: (listening, new message containing text started)
+Client: FIN=0, opcode=0x0, msg="happy new"
+Server: (listening, payload concatenated to previous message)
+Client: FIN=1, opcode=0x0, msg="year!"
+Server: (process complete message) Happy new year to you too!
+ +

Note que o primeiro frame que contém a mensagem inteira tem o FIN igual a 1 e o opcode igual a 0x1, entao o servidor pode processar ou responder como achar melhor.
+ O segundo frame enviado pelo cliente é uma mensagem de texto com payload opcode igual a 0x1, mas a mensagem inteira ainda não chegou (FIN=0). Todos as partes restantes da mensagem são enviados em frames continuos (opcode=0x0), e o frame final da mensagem é marcado com FIN=1. Seção 5.4 da especificação descreve a fragmentação de mensagens.

+ +

Pings e Pongs: O Heartbeat do WebSockets

+ +

Em qualquer momento do handshake, tanto o cliente quanto o servidor podem enviar um ping para a outra parte. Quando o ping é rescebido, o destinatário deve responder com um pong assim que possível. Você pode usar isso para garantir que o cliente está conectado, por exemplo.

+ +

Um ping ou um pong é um frame comum, entretanto é usado para controle. Pings tem o valor de opcode 0x9, enquanto que pongs tem o opcode 0xA. Quando você recebe um ping, envia de volta um pong com o mesmo exato payload data do ping (para pings e pongs, o payload length máximo é 125). Você também pode ter um pong sem nunca receber um ping; ignore isso caso ocorra.

+ +
+

Se você receber mais de um ping antes de ter a chance de enviar um pong, você envia apenas um pong.

+
+ +

Fechando a conexão

+ +

Para fechar a conexão tanto cliente quanto servidor podem enviar um frame de controle com dados contendo a sequencia de controles especifica para iniciar o fim do handshake (detalhado na seção 5.5.1). Assim que receber esse tipo de frame, a outra parte envia um frame de fechamento em resposta. A primeira parte então fecha a conexão. Quais quer outros dados recebidos depois de fechar a conexão é descartado. 

+ +

Diversos

+ +
+

Códigos WebSocket, extensões, subprotocols, etc. são registrados na IANA WebSocket Protocol Registry.

+
+ +

As extensões e subprotocolos do WebSocket são negociados via headers durante the handshake. Algumas vezes extensões e subprotocolos paracem muito similares para serem coisas diferentes, mas eles tem claras distinções. Extensões controlam os frame do WebSocket e modificam o payload, enquanto os subprotocolos estruturam o payload do WebSocket e nunca modificam nada. Extensões são opcionais e generalizadas (como comporessam); subprotocolos são mandatórios e localizados (como os usados para chat e para jogos MMORPG).

+ +

Extensões

+ +
+

Essa sessão precisa ser mais desenvolvida. Por favor edite se você tiver conhecimento sobre.

+
+ +

Imagine um extensão que comprime um arquivo antes de ser enviado em um e-mail para alguem. Independente do que você faça, está enviando o mesmo dado de formas diferentes. O destinatário eventualmente terá os mesmos dados que a cópia local que você tem, mas foram enviadas de formas diferentes. Isso é o que extensões fazem. WebSockets definem um protocolo e um forma simples de envio de dados, mas uma extensão como um compressor pode enviar o mesmo dado em um formado menor.

+ +
+

Extensões são explicadas nas sessões 5.8, 9, 11.3.2 e 11.4 da especificação.

+
+ +

Subprotocols

+ +

Pense em um subprotocolo como um esquema XML personalizado ou doctype declaration. Você ainda está usando XML e sua sintaxe, mas também é restringido por uma estrutura em que concordou. Os subprotocolo WebSocket são exatamente assim. Eles não apresentam nada sofisticado, apenas estabelecem estrutura. Como um doctype ou esquema, ambas as partes devem concordar com o subprotocolo; diferente de um doctype ou esquema, o subprotocolo é implementado no servidor e não pode ser referenciado externamente pelo cliente.

+ +
+

Subprotocolos são explicados nas sessões 1.9, 4.2, 11.3.4 e 11.5 da especificação.

+
+ +

Um cliente precisa solicitar um subprotocolo específico. Para fazer isso, ele enviará algo como isso como parte do handshake original:

+ +
GET /chat HTTP/1.1
+...
+Sec-WebSocket-Protocol: soap, wamp
+
+
+ +

ou, equivalentemente:

+ +
...
+Sec-WebSocket-Protocol: soap
+Sec-WebSocket-Protocol: wamp
+
+
+ +

Agora, o servidor deve escolher um dos protocolos que o cliente sugeriu e suporta. Se houver mais de um, envie o primeiro que o cliente enviou. Imagine que nosso servidor possa usar soap e wamp. Em seguida, no handshake de resposta, ele enviará:

+ +
Sec-WebSocket-Protocol: soap
+
+
+ +
+

O servidor não pode enviar mais de um cabeçalho Sec-Websocket-Protocol.
+ Se o servidor não quiser usar nenhum subprotocolo, ele não deverá enviar nenhum cabeçalho Sec-WebSocket-Protocol. O envio de um cabeçalho em branco está incorreto.
+ O cliente pode fechar a conexão se não conseguir o subprotocolo desejado.

+
+ +

Se você deseja que seu servidor obedeça a certos subprotocolo, então naturalmente precisará de código extra no servidor. Vamos imaginar que estamos usando um subprotocolo json. Neste subprotocolo, todos os dados são transmitidos como JSON. Se o cliente solicitar esse protocolo e o servidor quiser usá-lo, o servidor precisará ter um analisador JSON. Na prática, isso fará parte de uma biblioteca, mas o servidor precisará transmitir os dados.

+ +
+

Tip: Para evitar o conflito de nomes, recomenda-se que o subprotocolo seja nomeado como parte da string do domínio. Se você está desenvolvendo um aplicativo de bate-papo personalizado que usa um formato proprietário exclusivo da Exemplo Inc., então você pode usar isso: Sec-WebSocket-Protocol: chat.example.com. Note que isso não é necessário, é apenas uma convenção opcional, e você pode usar qualquer string que desejar.

+
+ +

Relacionado

+ + diff --git a/files/pt-br/web/api/window/beforeunload_event/index.html b/files/pt-br/web/api/window/beforeunload_event/index.html new file mode 100644 index 0000000000..6d6034318c --- /dev/null +++ b/files/pt-br/web/api/window/beforeunload_event/index.html @@ -0,0 +1,106 @@ +--- +title: beforeunload +slug: Web/Events/beforeunload +translation_of: Web/API/Window/beforeunload_event +--- +

O evento beforeunload é disparado quando o window, o document e seus recursos estão prestes a ser descarregados.

+ +

Quando uma string é atribuída na propriedade returnValue do Event, uma caixa de díalogo aparecerá solicitando ao usuário uma confirmação para sair da página (veja exemplo abaixo). Quando nenhum valor é fornecido, o evento é processado silenciosamente.

+ + + + + + + + + + + + + + + + + + + + +
BubblesNão
CancelableSim
Target objectsdefaultView
Interface{{domxref("Event")}}
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropriedadeTipoDescrição
target {{readOnlyInline}}{{domxref("EventTarget")}}O evento alvo (the topmost target in the DOM tree).
type {{readOnlyInline}}{{domxref("DOMString")}}O tipo de evento.
bubbles {{readOnlyInline}}{{jsxref("Boolean")}}O evento é normalmente bubble?
cancelable {{readOnlyInline}}{{jsxref("Boolean")}}É possível cancelar o evento?
returnValue{{domxref("DOMString")}}O valor de retorno do evento (a mensagem que será exibida ao usuário).
+ +

Exemplos

+ +
window.addEventListener("beforeunload", function (event) {
+  event.returnValue = "\o/";
+});
+
+// equivalente a
+window.addEventListener("beforeunload", function (event) {
+  event.preventDefault();
+});
+ +

Navegadores baseados no WebKit não seguem a especificação para caixas de diálogo. Um exemplo que funcionaria na maioria dos navegadores seria aproximadamente o seguinte:

+ +
window.addEventListener("beforeunload", function (e) {
+  var confirmationMessage = "\o/";
+
+  e.returnValue = confirmationMessage;     // Gecko, Trident, Chrome 34+
+  return confirmationMessage;              // Gecko, WebKit, Chrome <34
+});
+ +

Notas

+ +

Quando este evento retorna um valor não vazio (non-void), é solicitada ao usuário uma confirmação para descarregar a página. Na maioria dos navegadores o valor retornado no evento é exibido como mensagem nessa confirmação. No Firefox 4 e versões anteriores a string retornada não é exibida para o usuário. Ao invés disso, o Firefox exibe a mensagem "Esta página está perguntanto se você deseja sair - é possível que as alterações feitas não sejam salvas." Veja {{bug("588292")}}.

+ +

Desde 25 de maio de 2011 a especificação HTML5 define que chamadas aos métodos {{domxref("window.alert()")}}, {{domxref("window.confirm()")}} e {{domxref("window.prompt()")}} serão ignoradas durante este evento. Para mais detalhes veja a especificação HTML5 (em inglês).

+ +

Note também que vários navegadores para celular ignoram o resultado deste evento (isso que dizer que eles não solicitam a confirmação do usuário). O Firefox possui uma configuração escondida em about:config que faz o mesmo. Em essência, isto significa que o usuário estará sempre confirmando que o documento pode ser descarregado.

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/window/domcontentloaded_event/index.html b/files/pt-br/web/api/window/domcontentloaded_event/index.html new file mode 100644 index 0000000000..eb54671921 --- /dev/null +++ b/files/pt-br/web/api/window/domcontentloaded_event/index.html @@ -0,0 +1,177 @@ +--- +title: DOMContentLoaded +slug: Web/Events/DOMContentLoaded +translation_of: Web/API/Window/DOMContentLoaded_event +--- +

O evento DOMContentLoaded é acionado quando todo o HTML foi completamente carregado e analisado, sem aguardar pelo CSS, imagens, e subframes para encerrar o carregamento. Um evento muito diferente - load - deve ser usado apenas para detectar uma página completamente carregada. É um engano comum as pessoas usarem load quando DOMContentLoaded seria muito mais apropriado.

+ +
+

Nota: Javascript Síncrono pausa a análise do DOM.

+
+ +

Acelerando

+ +

Se você quer que o DOM seja analisado o mais rápido possível após uma requisição do usuário, você deve usar recursos do javascript assíncrono e otimizar o carregamento de folhas de estilo pois, caso contrário, a página será carregada mais lentamente pois muitos itens serão carregados paralelamente, atrasando a visualização da página.

+ +
+
+ +

Informações gerais

+ +
+
Especificação
+
HTML5
+
Interface
+
Event
+
Propaga
+
Sim
+
Cancelável
+
Sim (embora especificado como evento simples não-cancelável)
+
Alvo
+
Document
+
Ação Default
+
Nenhuma.
+
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}{{domxref("EventTarget")}}Alvo do evento (O topo do DOM).
type {{readonlyInline}}{{domxref("DOMString")}}Tipo de evento
bubbles {{readonlyInline}}{{jsxref("Boolean")}}O evento é por padrão bubbles ou não.
cancelable {{readonlyInline}}{{jsxref("Boolean")}}O evento pode ser cancelado ou não.
+ +

Exemplo

+ +

Básico

+ +
<script>
+  document.addEventListener("DOMContentLoaded", function(event) {
+    console.log("DOM completamente carregado e analisado");
+  });
+</script>
+
+ +

Forçando o atraso do DOMContentLoaded

+ +
<script>
+  document.addEventListener("DOMContentLoaded", function(event) {
+    console.log("DOM completamente carregado e analisado");
+  });
+
+for(var i=0; i<1000000000; i++)
+{} // este script síncrono irá o atrasar carregamento do DOM. Então o evento DOMContentLoaded irá ser ativado mais tarde.
+</script>
+
+ +

 

+ +

Verificando se o carregamento está completo

+ +

DOMContentLoaded pode disparar antes do seu script ser carregado, então é importante validar antes de adicionar um listener.

+ +
function doSomething() {
+  console.info("DOM carregado");
+}
+
+if (document.readyState === "loading") {  // Ainda carregando
+  document.addEventListener("DOMContentLoaded", doSomething);
+} else {  // `DOMContentLoaded` foi disparado
+  doSomething();
+}
+ +

 

+ +

Compatibilidade entre Navegadores

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
CaracterísticaChromeFirefox (Gecko)Internet ExplorerOperaSafari
Suporte básico0.2{{ CompatGeckoDesktop("1") }}9.09.03.1
+
+ +
+ + + + + + + + + + + + + + + + + + + +
CaracterísticaAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Suporte básico{{ CompatVersionUnknown() }}{{ CompatGeckoMobile("1") }}{{ CompatUnknown() }}{{ CompatVersionUnknown() }}{{ CompatVersionUnknown() }}
+
+ +

Propagação para este evento é suportada à partir do Gecko 1.9.2, Chrome 6, e Safari 4.

+ +

Cross-browser fallback

+ +

O Internet Explorer 8 suporta o evento readystatechange, que pode ser usado para detectar quando o DOM está pronto. Em versões anteriores do Internet Explorer, este estado pode ser detectado tentando executar document.documentElement.doScroll("left"); repetidas vezes; este comando dará erro repetidamente, até que o DOM esteja pronto.

+ +

Há também uma abundância de bibliotecas de propósito geral que oferecem métodos cross-browser para detectar se o DOM está pronto.

+ +

Eventos Relacionados

+ + diff --git a/files/pt-br/web/api/window/load_event/index.html b/files/pt-br/web/api/window/load_event/index.html new file mode 100644 index 0000000000..db04b1ecbe --- /dev/null +++ b/files/pt-br/web/api/window/load_event/index.html @@ -0,0 +1,89 @@ +--- +title: load +slug: Web/Events/load +translation_of: Web/API/Window/load_event +--- +
O evento de load é acionado quando um recurso e seus recursos
+dependentes terminaram de carregar.
+ +

Informações Gerais

+ +
+
Especificação
+
DOM L3
+
Interface
+
UIEvent
+
Bubbles
+
Não
+
Cancelavel
+
Não
+
Alvo
+
Window
+
Ação Padrão
+
Nenhuma.
+
+ +

Propriedades

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyTypeDescription
target {{readonlyInline}}EventTargetThe event target (the topmost target in the DOM tree).
type {{readonlyInline}}DOMStringThe type of event.
bubbles {{readonlyInline}}BooleanWhether the event normally bubbles or not.
cancelable {{readonlyInline}}BooleanWhether the event is cancellable or not.
view {{readonlyInline}}WindowProxydocument.defaultView (window of the document)
detail {{readonlyInline}}long (float)0.
+ +

Exemplo

+ +
<script>
+  window.addEventListener("load", function(event) {
+    console.log("Todos os recursos terminaram o carregamento!");
+  });
+</script>
+
+ +

 

+ +

Eventos Relacionados

+ + diff --git a/files/pt-br/web/api/window/localstorage/index.html b/files/pt-br/web/api/window/localstorage/index.html new file mode 100644 index 0000000000..8c7c379435 --- /dev/null +++ b/files/pt-br/web/api/window/localstorage/index.html @@ -0,0 +1,123 @@ +--- +title: Window.localStorage +slug: Web/API/Window/Window.localStorage +tags: + - API + - Armazenamento + - Propriedade + - Referencia + - WindowLocalStorage + - localStorage +translation_of: Web/API/Window/localStorage +--- +

{{APIRef()}}

+ +

A propriedade localStorage permite acessar um objeto {{domxref("Storage")}} local. A localStorage é similar ao sessionStorage. A única diferença é que enquanto os dados armazenados no localStorage não expiram, os dados no sessionStorage tem os seus dados limpos ao expirar a sessão da página — ou seja, quando a página (aba ou janela) é fechada.

+ +

Sintaxe

+ +
meuStorage = localStorage;
+ +

Valor

+ +

Objeto {{domxref("Storage")}}.

+ +

Exemplo

+ +

O seguinte trecho acessa o objeto {{domxref("Storage")}} local do domínio atual e adiciona um item usando o {{domxref("Storage.setItem()")}}.

+ +
localStorage.setItem('meuGato', 'Tom');
+ +
+

Nota: Por favor veja o artigo Using the Web Storage API para um exemplo completo.

+
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('Web Storage', '#dom-localstorage', 'localStorage')}}{{Spec2('Web Storage')}} 
+ + + +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
localStorage43.5810.504
sessionStorage52810.504
+
+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Basic support2.1{{ CompatUnknown }}811iOS 3.2
+
+ +

Cada navegador tem o seu nível de capacidade de armazenamento para localStorage e {{domxref("sessionStorage")}}. Aqui está um teste detalhado de toda a capacidade de armazenamento de vários browsers.

+ +
+

Nota: desde o iOS 5.1, Safari Mobile armazena os dados do localStorage em uma pasta de cache, o que está sujeito a ocasionalmente ser limpa, de acordo com o SO, se houver pouco espaço. O modo de Navegação Privada do Safari Mobile não permite escrever no localStorage de forma alguma.

+
+ +

Veja também

+ + diff --git a/files/pt-br/web/api/window/onscroll/index.html b/files/pt-br/web/api/window/onscroll/index.html deleted file mode 100644 index e5e756482a..0000000000 --- a/files/pt-br/web/api/window/onscroll/index.html +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: window.onscroll -slug: Web/API/Window/onscroll -translation_of: Web/API/GlobalEventHandlers/onscroll -translation_of_original: Web/API/Window/onscroll ---- -

{{ ApiRef() }}

-

Sumário

-

Especifica a função a ser chamada quando é feito o scroll na janela.

-

Sintaxe

-
window.onscroll = funcRef;
-
- -

Exemplos

-

Exemplo 1: Genérico

-
window.onscroll = function (oEvent) {
-  // executa um bloco de código ou funções, quando o scroll é feito na janela.
-}
-
-

Examplo 2: Dectando a rolagem

-

O exemplo a seguir, irá disparar um alerta sempre que o usuário rolar a página .

-
<!doctype html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>onscroll test</title>
-<script type="text/javascript">
-window.onscroll = scroll;
-
-function scroll () {
- alert("evento scroll detectado! " + window.pageXOffset + " " + window.pageYOffset);
- // nota: você pode usar window.innerWidth e window.innerHeight para obter a largura e altura da área de visão.
-}
-</script>
-</head>
-
-<body>
-<p>Redimensione a janela</p>
-<p>para um tamanho pequeno,</p>
-<p>e use a barra de rolagem</p>
-<p>para mover ao redor do conteúdo da página</p>
-<p>na janela.</p>
-</body>
-</html>
-
- -

O exemplo a seguir irá mostrar um link( uma imagem de seta ) no topo da página quando a rolagem vertical atingir 500 pixels

-

 

-
<!doctype html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>MDN Example</title>
-<script type="text/javascript">
-var bAppended = false, oBookmark = document.createElement("div");
-oBookmark.id = "arrowUp";
-oBookmark.innerHTML = "<a href=\"#\" title=\"Top of the page.\">&uarr;<\/a>";
-
-onscroll = function() {
-  var nVScroll = document.documentElement.scrollTop || document.body.scrollTop;
-  bAppended = nVScroll > 500 ?
-    bAppended || (document.body.appendChild(oBookmark), true)
-    : bAppended && (document.body.removeChild(oBookmark), false);
-};
-</script>
-<style type="text/css">
-#arrowUp {
-  position: fixed;
-  height: auto;
-  width: auto;
-  right: 10px;
-  top: 10px;
-  font-size: 48px;
-}
-#arrowUp a {
-  text-decoration: none;
-  color: black;
-  font-weight: bold;
-  font-family: serif;
-}
-</style>
-</head>
-
-<body>
-<p>Conteúdo da página aqui!</p>
-</body>
-
-</html>
-

Notas

-

{{ Bug(189308) }}, nas versões antigas do Gecko, o evento 'onscroll' era executado apenas quando a barra de rolagem era arrastada, não quando utilizada a seta do teclado ou scroll do mouse.
- Esse bug foi corrigido no Gecko 1.8/Firefox 1.5

-

Quando o window.scrollX/scrollY não é 0 -- considerando que o scroll ocorreu por algum script ou uma ação manual -- recarregando a página irá disparar o evento onscroll imediatamente.

-

Especificação

- -

{{ languages( { "zh-cn": "zh-cn/DOM/window.onscroll"} ) }}

diff --git a/files/pt-br/web/api/window/url/index.html b/files/pt-br/web/api/window/url/index.html deleted file mode 100644 index 1dec25bd24..0000000000 --- a/files/pt-br/web/api/window/url/index.html +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Window.URL -slug: Web/API/Window/URL -translation_of: Web/API/URL -translation_of_original: Web/API/Window/URL ---- -

{{ApiRef("Window")}}{{SeeCompatTable}}

- -

A propriedade Window.URL retorna um objeto que fornece métodos estáticos usados para criar e gerenciar URLs de objeto. Também pode ser chamado como um construtor para construir objetos {{domxref("URL")}}.

- -

{{AvailableInWorkers}}

- -

Sintaxe

- -

Chamando um método estático:

- -
img.src = URL.{{domxref("URL.createObjectURL", "createObjectURL")}}(blob);
- -

Construindo um novo objeto:

- -
var url = new {{domxref("URL.URL", "URL")}}("../cats/", "https://www.example.com/dogs/");
- -

Especificação

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('URL', '#dom-url', 'URL')}}{{Spec2('URL')}}Initial definition
- -

Compatibilidade do navegador

- -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support8.0[2]{{CompatGeckoDesktop("2.0")}}[1]
- {{CompatGeckoDesktop("19.0")}}		10.015.0[2]6.0[2]
- 7.0
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatVersionUnknown}}[2]{{CompatGeckoMobile("14.0")}}[1]
- {{CompatGeckoMobile("19.0")}}		{{CompatVersionUnknown}}15.0[2]6.0[2]
-
- -

[1] Do Gecko 2 (Firefox 4) ao Gecko 18 incluído, o Gecko retornou um objeto com o tipo interno nsIDOMMozURLProperty não padrão. Na prática, isso não fez diferença.

- -

[2] Implementado sob o nome não padronizado webkitURL.

- -

Veja também

- - diff --git a/files/pt-br/web/api/window/window.localstorage/index.html b/files/pt-br/web/api/window/window.localstorage/index.html deleted file mode 100644 index 8c7c379435..0000000000 --- a/files/pt-br/web/api/window/window.localstorage/index.html +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Window.localStorage -slug: Web/API/Window/Window.localStorage -tags: - - API - - Armazenamento - - Propriedade - - Referencia - - WindowLocalStorage - - localStorage -translation_of: Web/API/Window/localStorage ---- -

{{APIRef()}}

- -

A propriedade localStorage permite acessar um objeto {{domxref("Storage")}} local. A localStorage é similar ao sessionStorage. A única diferença é que enquanto os dados armazenados no localStorage não expiram, os dados no sessionStorage tem os seus dados limpos ao expirar a sessão da página — ou seja, quando a página (aba ou janela) é fechada.

- -

Sintaxe

- -
meuStorage = localStorage;
- -

Valor

- -

Objeto {{domxref("Storage")}}.

- -

Exemplo

- -

O seguinte trecho acessa o objeto {{domxref("Storage")}} local do domínio atual e adiciona um item usando o {{domxref("Storage.setItem()")}}.

- -
localStorage.setItem('meuGato', 'Tom');
- -
-

Nota: Por favor veja o artigo Using the Web Storage API para um exemplo completo.

-
- -

Especificações

- - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('Web Storage', '#dom-localstorage', 'localStorage')}}{{Spec2('Web Storage')}} 
- - - -

{{ CompatibilityTable() }}

- -
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
localStorage43.5810.504
sessionStorage52810.504
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureAndroidFirefox Mobile (Gecko)IE PhoneOpera MobileSafari Mobile
Basic support2.1{{ CompatUnknown }}811iOS 3.2
-
- -

Cada navegador tem o seu nível de capacidade de armazenamento para localStorage e {{domxref("sessionStorage")}}. Aqui está um teste detalhado de toda a capacidade de armazenamento de vários browsers.

- -
-

Nota: desde o iOS 5.1, Safari Mobile armazena os dados do localStorage em uma pasta de cache, o que está sujeito a ocasionalmente ser limpa, de acordo com o SO, se houver pouco espaço. O modo de Navegação Privada do Safari Mobile não permite escrever no localStorage de forma alguma.

-
- -

Veja também

- - diff --git a/files/pt-br/web/api/windowbase64/atob/index.html b/files/pt-br/web/api/windowbase64/atob/index.html deleted file mode 100644 index cb9058abe5..0000000000 --- a/files/pt-br/web/api/windowbase64/atob/index.html +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: WindowBase64.atob() -slug: Web/API/WindowBase64/atob -tags: - - API - - Referencia - - WindowBase64 - - metodo -translation_of: Web/API/WindowOrWorkerGlobalScope/atob ---- -
{{APIRef("HTML DOM")}}
- -

A função WindowBase64.atob() decodifica uma string de dados que foi codificada através da codificação base-64. Você pode usar o método {{domxref("WindowBase64.btoa","window.btoa()")}} para codificar e transmitir dados que, se não codificados, podem causar problemas de comunicação. Após transmití-los pode-se usar o método window.atob() para decodificar os dados novamente. Por exemplo, você pode codificar, transmitir,  e decodificar caracteres de controle como valores ASCII de 0 a 31.

- -

Para utilizar com strings Unicode ou UTF-8, veja esta nota em Base64 encoding and decoding e essa nota em window.btoa().

- -

Sintaxe

- -
var dadoDecodificado = window.atob(dadoCodificado);
- -

Exemplo

- -
var dadoCodificado = window.btoa("Olá, mundo"); // codifica a string
-var dadoDecodificado = window.atob(dadoCodificado); // decodifica a string
- -

Especificações

- - - - - - - - - - - - - - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', '#dom-windowbase64-atob', 'WindowBase64.atob()')}}{{Spec2('HTML WHATWG')}}Nenhuma mudança desde a última versão, {{SpecName("HTML5.1")}}.
{{SpecName('HTML5.1', '#dom-windowbase64-atob', 'WindowBase64.atob()')}}{{Spec2('HTML5.1')}}Versão de {{SpecName("HTML WHATWG")}}. Nenhuma mudança.
{{SpecName("HTML5 W3C", "#dom-windowbase64-atob", "WindowBase64.atob()")}}{{Spec2('HTML5 W3C')}}Versão de {{SpecName("HTML WHATWG")}}. Criação do WindowBase64 (antes as propriedades ficavam no target).
- -

Compatibilidade de navegadores

- -
{{Compat("api.WindowOrWorkerGlobalScope.atob")}}
- -
- -

[1] atob() também está disponível para os componentes do XPCOM implementado em JavaScript, porém o objeto window não é global nos componentes.

- -

[2] A partir do Firefox 27, atob() ignora todos os caracteres de espaço no argumento para seguir as últimas especificações do HTML5. ({{bug(711180)}})

- -

Veja também

- - diff --git a/files/pt-br/web/api/windowbase64/index.html b/files/pt-br/web/api/windowbase64/index.html deleted file mode 100644 index f51b72c102..0000000000 --- a/files/pt-br/web/api/windowbase64/index.html +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: WindowBase64 -slug: Web/API/WindowBase64 -tags: - - API - - HTML-DOM - - Helper - - NeedsTranslation - - TopicStub - - WindowBase64 -translation_of: Web/API/WindowOrWorkerGlobalScope -translation_of_original: Web/API/WindowBase64 ---- -

{{APIRef("HTML DOM")}}

- -

The WindowBase64 helper contains utility methods to convert data to and from base64, a binary-to-text encoding scheme. For example it is used in data URIs.

- -

There is no object of this type, though the context object, either the {{domxref("Window")}} for regular browsing scope, or the {{domxref("WorkerGlobalScope")}}  for workers, implements it.

- -

Properties

- -

This helper neither defines nor inherits any properties.

- -

Methods

- -

This helper does not inherit any methods.

- -
-
{{domxref("WindowBase64.atob()")}}
-
Decodes a string of data which has been encoded using base-64 encoding.
-
{{domxref("WindowBase64.btoa()")}}
-
Creates a base-64 encoded ASCII string from a string of binary data.
-
- -

Specifications

- - - - - - - - - - - - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('HTML WHATWG', '#windowbase64', 'WindowBase64')}}{{Spec2('HTML WHATWG')}}No change since the latest snapshot, {{SpecName("HTML5.1")}}.
{{SpecName('HTML5.1', '#windowbase64', 'WindowBase64')}}{{Spec2('HTML5.1')}}Snapshot of {{SpecName("HTML WHATWG")}}. No change.
{{SpecName("HTML5 W3C", "#windowbase64", "WindowBase64")}}{{Spec2('HTML5 W3C')}}Snapshot of {{SpecName("HTML WHATWG")}}. Creation of WindowBase64 (properties where on the target before it).
- -

Browser compatibility

- -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureFirefox (Gecko)ChromeInternet ExplorerOperaSafari
Basic support{{CompatGeckoDesktop(1)}} [1]{{CompatVersionUnknown}}10.0{{CompatVersionUnknown}}{{CompatVersionUnknown}}
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureFirefox Mobile (Gecko)AndroidIE MobileOpera MobileSafari Mobile
Basic support{{CompatGeckoMobile(1)}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}
-
- -

[1]  atob() is also available to XPCOM components implemented in JavaScript, even though {{domxref("Window")}} is not the global object in components.

- -

See also

- - diff --git a/files/pt-br/web/api/windoworworkerglobalscope/atob/index.html b/files/pt-br/web/api/windoworworkerglobalscope/atob/index.html new file mode 100644 index 0000000000..cb9058abe5 --- /dev/null +++ b/files/pt-br/web/api/windoworworkerglobalscope/atob/index.html @@ -0,0 +1,72 @@ +--- +title: WindowBase64.atob() +slug: Web/API/WindowBase64/atob +tags: + - API + - Referencia + - WindowBase64 + - metodo +translation_of: Web/API/WindowOrWorkerGlobalScope/atob +--- +
{{APIRef("HTML DOM")}}
+ +

A função WindowBase64.atob() decodifica uma string de dados que foi codificada através da codificação base-64. Você pode usar o método {{domxref("WindowBase64.btoa","window.btoa()")}} para codificar e transmitir dados que, se não codificados, podem causar problemas de comunicação. Após transmití-los pode-se usar o método window.atob() para decodificar os dados novamente. Por exemplo, você pode codificar, transmitir,  e decodificar caracteres de controle como valores ASCII de 0 a 31.

+ +

Para utilizar com strings Unicode ou UTF-8, veja esta nota em Base64 encoding and decoding e essa nota em window.btoa().

+ +

Sintaxe

+ +
var dadoDecodificado = window.atob(dadoCodificado);
+ +

Exemplo

+ +
var dadoCodificado = window.btoa("Olá, mundo"); // codifica a string
+var dadoDecodificado = window.atob(dadoCodificado); // decodifica a string
+ +

Especificações

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', '#dom-windowbase64-atob', 'WindowBase64.atob()')}}{{Spec2('HTML WHATWG')}}Nenhuma mudança desde a última versão, {{SpecName("HTML5.1")}}.
{{SpecName('HTML5.1', '#dom-windowbase64-atob', 'WindowBase64.atob()')}}{{Spec2('HTML5.1')}}Versão de {{SpecName("HTML WHATWG")}}. Nenhuma mudança.
{{SpecName("HTML5 W3C", "#dom-windowbase64-atob", "WindowBase64.atob()")}}{{Spec2('HTML5 W3C')}}Versão de {{SpecName("HTML WHATWG")}}. Criação do WindowBase64 (antes as propriedades ficavam no target).
+ +

Compatibilidade de navegadores

+ +
{{Compat("api.WindowOrWorkerGlobalScope.atob")}}
+ +
+ +

[1] atob() também está disponível para os componentes do XPCOM implementado em JavaScript, porém o objeto window não é global nos componentes.

+ +

[2] A partir do Firefox 27, atob() ignora todos os caracteres de espaço no argumento para seguir as últimas especificações do HTML5. ({{bug(711180)}})

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/windoworworkerglobalscope/cleartimeout/index.html b/files/pt-br/web/api/windoworworkerglobalscope/cleartimeout/index.html new file mode 100644 index 0000000000..f03f43979f --- /dev/null +++ b/files/pt-br/web/api/windoworworkerglobalscope/cleartimeout/index.html @@ -0,0 +1,100 @@ +--- +title: WindowTimers.clearTimeout() +slug: Web/API/WindowTimers/clearTimeout +tags: + - API + - Method + - Window +translation_of: Web/API/WindowOrWorkerGlobalScope/clearTimeout +--- +
+
+
{{APIRef("HTML DOM")}}
+
+
+ +

Sumário

+ +

O método clearTimeout() do escopo {{domxref("WindowOrWorkerGlobalScope")}} cancela um timeout previamente estabelecido pela função {{domxref("WindowOrWorkerGlobalScope.setTimeout", "setTimeout()")}}.

+ +

Síntaxe

+ +
escopo.clearTimeout(timeoutID)
+
+ +

Parâmetros

+ +
+
timeoutID
+
O ID do timeout que você deseja cancelar. Esse ID é o retorno da função setTimeout().
+
+ +

É interessante ressaltar que os conjuntso de IDs usados pelos métodos {{domxref("WindowOrWorkerGlobalScope.setTimeout", "setTimeout()")}} e {{domxref("WindowOrWorkerGlobalScope.setInterval", "setInterval()")}} são compartilhados, o que significa que clearTimeout() e {{domxref("WindowOrWorkerGlobalScope.clearInterval", "clearInterval()")}} podem ser tecnicamente utilizados de forma intercambiável. No entanto, para obter-se maior clareza, isso deve ser evitado.

+ +

Exemplo

+ +

Execute o script abaixo em uma página web e clique na página uma vez. Você verá uma mensagem aparecer um segundo depois. Se você continuar clicando na página várias vezes nesse intervalo de tempo, a mensagem aparecerá uma única vez.

+ +
var alarme = {
+  relembrar: function(aMessage) {
+    alert(aMessage);
+    delete this.timeoutID;
+  },
+
+  setup: function() {
+    if (typeof this.timeoutID === 'number') {
+        this.cancelar();
+    }
+
+    this.timeoutID = window.setTimeout(function(msg) {
+        this.relembrar(msg);
+    }.bind(this), 1000, 'Wake up!');
+  },
+
+  cancelar: function() {
+    window.clearTimeout(this.timeoutID);
+  }
+};
+window.onclick = function() { alarme.setup() };
+ +

Notas

+ +

Passar um ID inválido para clearTimeout não causa nenhum efeito (não lança nenhuma exceção).

+ +

Especificações

+ + + + + + + + + + + + + + + + + + + +
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'webappapis.html#dom-cleartimeout', 'WindowOrWorkerGlobalScope.clearTimeout()')}}{{Spec2("HTML WHATWG")}}Método movido para WindowOrWorkerGlobalScope .
{{SpecName('HTML WHATWG', 'webappapis.html#dom-cleartimeout', 'clearTimeout()')}}{{Spec2('HTML WHATWG')}} 
+ +

Compatibilidade

+ + + +

{{Compat("api.WindowOrWorkerGlobalScope.clearTimeout")}}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/windowtimers/cleartimeout/index.html b/files/pt-br/web/api/windowtimers/cleartimeout/index.html deleted file mode 100644 index f03f43979f..0000000000 --- a/files/pt-br/web/api/windowtimers/cleartimeout/index.html +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: WindowTimers.clearTimeout() -slug: Web/API/WindowTimers/clearTimeout -tags: - - API - - Method - - Window -translation_of: Web/API/WindowOrWorkerGlobalScope/clearTimeout ---- -
-
-
{{APIRef("HTML DOM")}}
-
-
- -

Sumário

- -

O método clearTimeout() do escopo {{domxref("WindowOrWorkerGlobalScope")}} cancela um timeout previamente estabelecido pela função {{domxref("WindowOrWorkerGlobalScope.setTimeout", "setTimeout()")}}.

- -

Síntaxe

- -
escopo.clearTimeout(timeoutID)
-
- -

Parâmetros

- -
-
timeoutID
-
O ID do timeout que você deseja cancelar. Esse ID é o retorno da função setTimeout().
-
- -

É interessante ressaltar que os conjuntso de IDs usados pelos métodos {{domxref("WindowOrWorkerGlobalScope.setTimeout", "setTimeout()")}} e {{domxref("WindowOrWorkerGlobalScope.setInterval", "setInterval()")}} são compartilhados, o que significa que clearTimeout() e {{domxref("WindowOrWorkerGlobalScope.clearInterval", "clearInterval()")}} podem ser tecnicamente utilizados de forma intercambiável. No entanto, para obter-se maior clareza, isso deve ser evitado.

- -

Exemplo

- -

Execute o script abaixo em uma página web e clique na página uma vez. Você verá uma mensagem aparecer um segundo depois. Se você continuar clicando na página várias vezes nesse intervalo de tempo, a mensagem aparecerá uma única vez.

- -
var alarme = {
-  relembrar: function(aMessage) {
-    alert(aMessage);
-    delete this.timeoutID;
-  },
-
-  setup: function() {
-    if (typeof this.timeoutID === 'number') {
-        this.cancelar();
-    }
-
-    this.timeoutID = window.setTimeout(function(msg) {
-        this.relembrar(msg);
-    }.bind(this), 1000, 'Wake up!');
-  },
-
-  cancelar: function() {
-    window.clearTimeout(this.timeoutID);
-  }
-};
-window.onclick = function() { alarme.setup() };
- -

Notas

- -

Passar um ID inválido para clearTimeout não causa nenhum efeito (não lança nenhuma exceção).

- -

Especificações

- - - - - - - - - - - - - - - - - - - -
EspecificaçãoStatusComentário
{{SpecName('HTML WHATWG', 'webappapis.html#dom-cleartimeout', 'WindowOrWorkerGlobalScope.clearTimeout()')}}{{Spec2("HTML WHATWG")}}Método movido para WindowOrWorkerGlobalScope .
{{SpecName('HTML WHATWG', 'webappapis.html#dom-cleartimeout', 'clearTimeout()')}}{{Spec2('HTML WHATWG')}} 
- -

Compatibilidade

- - - -

{{Compat("api.WindowOrWorkerGlobalScope.clearTimeout")}}

- -

Veja também

- - diff --git a/files/pt-br/web/api/windowtimers/index.html b/files/pt-br/web/api/windowtimers/index.html deleted file mode 100644 index 8be6ca7e8b..0000000000 --- a/files/pt-br/web/api/windowtimers/index.html +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: WindowTimers -slug: Web/API/WindowTimers -translation_of: Web/API/WindowOrWorkerGlobalScope -translation_of_original: Web/API/WindowTimers ---- -
{{APIRef("HTML DOM")}}
- -

WindowTimers contains utility methods to set and clear timers.

- -

There is no object of this type, though the context object, either the {{domxref("Window")}} for regular browsing scope, or the {{domxref("WorkerGlobalScope")}}  for workers, implements it.

- -

Properties

- -

This interface do not define any property, nor inherit any.

- -

Methods

- -

This interface do not inherit any method.

- -
-
{{domxref("WindowTimers.clearInterval()")}}
-
Cancels the repeated execution set using {{domxref("WindowTimers.setInterval()")}}.
-
{{domxref("WindowTimers.clearTimeout()")}}
-
Cancels the repeated execution set using {{domxref("WindowTimers.setTimeout()")}}.
-
{{domxref("WindowTimers.setInterval()")}}
-
Schedules the execution of a function each X milliseconds.
-
{{domxref("WindowTimers.setTimeout()")}}
-
Sets a delay for executing a function.
-
- -

Specifications

- - - - - - - - - - - - - - - - - - - - - - - - - - -
SpecificationStatusComment
{{SpecName('HTML WHATWG', '#windowtimers', 'WindowTimers')}}{{Spec2('HTML WHATWG')}}No change since the latest snapshot, {{SpecName("HTML5.1")}}.
{{SpecName('HTML5.1', '#windowtimers', 'WindowTimers')}}{{Spec2('HTML5.1')}}Snapshot of {{SpecName("HTML WHATWG")}}. No change.
{{SpecName("HTML5 W3C", "#windowtimers", "WindowTimers")}}{{Spec2('HTML5 W3C')}}Snapshot of {{SpecName("HTML WHATWG")}}. Creation of WindowBase64 (properties where on the target before it).
- -

Browser compatibility

- -

{{CompatibilityTable}}

- -
- - - - - - - - - - - - - - - - - - - -
FeatureFirefox (Gecko)ChromeInternet ExplorerOperaSafari
Basic support{{CompatGeckoDesktop(1)}}1.04.04.01.0
-
- -
- - - - - - - - - - - - - - - - - - - -
FeatureFirefox Mobile (Gecko)AndroidIE MobileOpera MobileSafari Mobile
Basic support{{CompatGeckoMobile(1)}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}
-
- -

 

- -

See also

- - diff --git a/files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html b/files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html deleted file mode 100644 index 81b8fb8d3e..0000000000 --- a/files/pt-br/web/api/xmlhttprequest/requisicoes_sincronas_e_assincronas/index.html +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: Requisições síncronas e assíncronas -slug: Web/API/XMLHttpRequest/Requisicoes_sincronas_e_assincronas -translation_of: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests ---- -

XMLHttpRequest suporta comunicações síncronas e assíncronas. No geral, entretando, requisições assíncronas devem prevalecer sobre requisições síncronas por questões de performance.

- -

Requisições síncronas podem bloquear a execução do codigo, gerando um "congelamento" da tela, prejudicando a experiência do usuário. 

- -

Requisição assíncrona

- -

Se você usa XMLHttpRequest de uma extensão, você deveria usá-la de forma assíncrona. Neste caso, você recebe um callback quando os dados forem recebidos, o que permite que o browser continue seu trabalho normalmente enquanto sua requisição estiver sendo processada.

- -

Exemplo: envie um arquivo para o console de log

- -

Esse é o exemplo mais simples de uso do XMLHttpRequest assíncrono.

- -
var xhr = new XMLHttpRequest();
-xhr.open("GET", "/bar/foo.txt", true);
-xhr.onload = function (e) {
-  if (xhr.readyState === 4) {
-    if (xhr.status === 200) {
-      console.log(xhr.responseText);
-    } else {
-      console.error(xhr.statusText);
-    }
-  }
-};
-xhr.onerror = function (e) {
-  console.error(xhr.statusText);
-};
-xhr.send(null);
- -

A Linha 2 define o terceiro parâmetro como true, indicando que a requisição deve ser tratada assincronamente.

- -

A Linha 3 cria um objeto função do tipo event handler e atribui ele ao atributo onload da requisição.

- -

Na LInha 4, Este handler verifica o estado da requisição, através da variável readyState, para ver se a transação está completa, e se o status do HTTP é 200. Em caso positivo lê o conteúdo recebido. Se um erro ocorrer, uma mensagem de erro será exibida no console.

- -

A requisição é, de fato, realizada na Linha 15. A rotina de callback é invocada quando o estado da requisição muda.

- -

Exemplo: Criando uma função standard para ler arquivos externos

- -

Em alguns casos, você pode precisar ler muitos arquivos externos. Esta é uma função padrão que utiliza o objeto XMLHttpRequest de forma assíncrona para alternar o conteúdo do arquivo legível para um listener especificado.

- -
function xhrSuccess () { this.callback.apply(this, this.arguments); }
-
-function xhrError () { console.error(this.statusText); }
-
-function loadFile (sURL, fCallback /*, argumentToPass1, argumentToPass2, etc. */) {
-  var oReq = new XMLHttpRequest();
-  oReq.callback = fCallback;
-  oReq.arguments = Array.prototype.slice.call(arguments, 2);
-  oReq.onload = xhrSuccess;
-  oReq.onerror = xhrError;
-  oReq.open("get", sURL, true);
-  oReq.send(null);
-}
-
- -

Uso:

- -
function showMessage (sMsg) {
-  alert(sMsg + this.responseText);
-}
-
-loadFile("message.txt", showMessage, "New message!\n\n");
-
- -

A assinatura da função loadFile declara (i) uma URL de destino que será lida (via HTTP GET), (ii) uma função de callback para executar na conclusão bem-sucedida da instância xhr, e (iii) uma lista opcional de argumentos adicionais que são "passados através" do objeto XHR caso a função de callback seja bem-sucedida.

- -

A linha 1 declara uma função que será invocada quando a operação XHR for completada com sucesso.  Isso, por sua vez, invoca uma função de callback especificada na invocação da função loadFile (neste caso, a função showMessage) que foi atribuída a propriedade do objeto XHR (Linha 7). Os  argumentos adicionais (caso existam) fornecem a invocação da função loadFile são "aplicados" para a execução da função de callback..

- -

A linha 3 declara uma função que será invocada quando a operação XHR não for completada com sucesso.

- -

A linha 7 define no objeto XHR  the success callback function given as the second argument to loadFile.

- -

Line 8 slices the arguments array given to the invocation of loadFile. Starting with the third argument, all remaining arguments are collected, assigned to the arguments property of the variable oReq, passed to the success callback function xhrSuccess., and ultimately supplied to the callback function (in this case, showMessage) which is invoked by function xhrSuccess.

- -

Line 9 designates the function xhrSuccess as the callback to be invoked when the onload event fires, that is, when the XHR sucessfully completes.  

- -

Line 10 designates the function xhrError as the callback to be invoked when the XHR requests fails to complete.

- -

Line 11 specifies true for its third parameter to indicate that the request should be handled asynchronously.

- -

Line 12 actually initiates the request.

- -

Example: using a timeout

- -

You can use a timeout to prevent hanging your code forever while waiting for a read to occur. This is done by setting the value of the timeout property on the XMLHttpRequest object, as shown in the code below:

- -
function loadFile(sUrl, timeout, callback){
-
-    var args = arguments.slice(3);
-    var xhr = new XMLHttpRequest();
-    xhr.ontimeout = function () {
-        console.error("The request for " + url + " timed out.");
-    };
-    xhr.onload = function() {
-        if (xhr.readyState === 4) {
-            if (xhr.status === 200) {
-                callback.apply(xhr, args);
-            } else {
-                console.error(xhr.statusText);
-            }
-        }
-    };
-    xhr.open("GET", url, true);
-    xhr.timeout = timeout;
-    xhr.send(null);
-}
- -

Notice the addition of code to handle the "timeout" event by setting the ontimeout handler.

- -

Usage:

- -
function showMessage (sMsg) {
-  alert(sMsg + this.responseText);
-}
-
-loadFile("message.txt", 2000, showMessage, "New message!\n");
-
- -

Here, we're specifying a timeout of 2000 ms.

- -
-

Note: Support for timeout was added in {{Gecko("12.0")}}.

-
- -

Synchronous request

- -
Note: Starting with Gecko 30.0 {{ geckoRelease("30.0") }}, synchronous requests on the main thread have been deprecated due to the negative effects to the user experience.
- -

Em casos raros, o uso do método síncrono é preferível ao invés do método assíncrono.

- -

Example: HTTP synchronous request

- -

This example demonstrates how to make a simple synchronous request.

- -
var request = new XMLHttpRequest();
-request.open('GET', '/bar/foo.txt', false);  // `false` makes the request synchronous
-request.send(null);
-
-if (request.status === 200) {
-  console.log(request.responseText);
-}
-
- -

Line 3 sends the request.  The null parameter indicates that no body content is needed for the GET request.

- -

Line 5 checks the status code after the transaction is completed.  If the result is 200 -- HTTP's "OK" result -- the document's text content is output to the console.

- -

Example: Synchronous HTTP request from a Worker

- -

One of the few cases in which a synchronous request does not usually block execution is the use of XMLHttpRequest within a Worker.

- -

example.html (the main page):

- -
<!doctype html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>MDN Example</title>
-<script type="text/javascript">
-  var worker = new Worker("myTask.js");
-  worker.onmessage = function(event) {
-    alert("Worker said: " + event.data);
-  };
-
-  worker.postMessage("Hello");
-</script>
-</head>
-<body></body>
-</html>
-
- -

myFile.txt (the target of the synchronous XMLHttpRequest invocation):

- -
Hello World!!
-
- -

myTask.js (the Worker):

- -
self.onmessage = function (event) {
-  if (event.data === "Hello") {
-    var xhr = new XMLHttpRequest();
-    xhr.open("GET", "myFile.txt", false);  // synchronous request
-    xhr.send(null);
-    self.postMessage(xhr.responseText);
-  }
-};
-
- -
Note: The effect, because of the use of the Worker, is however asynchronous.
- -

It could be useful in order to interact in background with the server or to preload some content. See Using web workers for examples and details.

- -

Adapting Sync XHR usecases to the Beacon API

- -

There are some cases in which the synchronous usage of XMLHttpRequest was not replaceable, like during the window.onunload and window.onbeforeunload events.  The navigator.sendBeacon API can support these usecases typically while delivering a good UX.

- -

The following example (from the sendBeacon docs) shows a theoretical analytics code that attempts to submit data to a server by using a synchronous XMLHttpRequest in an unload handler. This results in the unload of the page to be delayed.

- -
window.addEventListener('unload', logData, false);
-
-function logData() {
-    var client = new XMLHttpRequest();
-    client.open("POST", "/log", false); // third parameter indicates sync xhr. :(
-    client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
-    client.send(analyticsData);
-}
-
- -

Using the sendBeacon() method, the data will be transmitted asynchronously to the web server when the User Agent has had an opportunity to do so, without delaying the unload or affecting the performance of the next navigation.

- -

The following example shows a theoretical analytics code pattern that submits data to a server using the by using the sendBeacon() method.

- -
window.addEventListener('unload', logData, false);
-
-function logData() {
-    navigator.sendBeacon("/log", analyticsData);
-}
-
- -

See also

- - - -

{{ languages( {"zh-cn": "zh-cn/DOM/XMLHttpRequest/Synchronous_and_Asynchronous_Requests" } ) }}

diff --git a/files/pt-br/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html b/files/pt-br/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html new file mode 100644 index 0000000000..81b8fb8d3e --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/synchronous_and_asynchronous_requests/index.html @@ -0,0 +1,234 @@ +--- +title: Requisições síncronas e assíncronas +slug: Web/API/XMLHttpRequest/Requisicoes_sincronas_e_assincronas +translation_of: Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests +--- +

XMLHttpRequest suporta comunicações síncronas e assíncronas. No geral, entretando, requisições assíncronas devem prevalecer sobre requisições síncronas por questões de performance.

+ +

Requisições síncronas podem bloquear a execução do codigo, gerando um "congelamento" da tela, prejudicando a experiência do usuário. 

+ +

Requisição assíncrona

+ +

Se você usa XMLHttpRequest de uma extensão, você deveria usá-la de forma assíncrona. Neste caso, você recebe um callback quando os dados forem recebidos, o que permite que o browser continue seu trabalho normalmente enquanto sua requisição estiver sendo processada.

+ +

Exemplo: envie um arquivo para o console de log

+ +

Esse é o exemplo mais simples de uso do XMLHttpRequest assíncrono.

+ +
var xhr = new XMLHttpRequest();
+xhr.open("GET", "/bar/foo.txt", true);
+xhr.onload = function (e) {
+  if (xhr.readyState === 4) {
+    if (xhr.status === 200) {
+      console.log(xhr.responseText);
+    } else {
+      console.error(xhr.statusText);
+    }
+  }
+};
+xhr.onerror = function (e) {
+  console.error(xhr.statusText);
+};
+xhr.send(null);
+ +

A Linha 2 define o terceiro parâmetro como true, indicando que a requisição deve ser tratada assincronamente.

+ +

A Linha 3 cria um objeto função do tipo event handler e atribui ele ao atributo onload da requisição.

+ +

Na LInha 4, Este handler verifica o estado da requisição, através da variável readyState, para ver se a transação está completa, e se o status do HTTP é 200. Em caso positivo lê o conteúdo recebido. Se um erro ocorrer, uma mensagem de erro será exibida no console.

+ +

A requisição é, de fato, realizada na Linha 15. A rotina de callback é invocada quando o estado da requisição muda.

+ +

Exemplo: Criando uma função standard para ler arquivos externos

+ +

Em alguns casos, você pode precisar ler muitos arquivos externos. Esta é uma função padrão que utiliza o objeto XMLHttpRequest de forma assíncrona para alternar o conteúdo do arquivo legível para um listener especificado.

+ +
function xhrSuccess () { this.callback.apply(this, this.arguments); }
+
+function xhrError () { console.error(this.statusText); }
+
+function loadFile (sURL, fCallback /*, argumentToPass1, argumentToPass2, etc. */) {
+  var oReq = new XMLHttpRequest();
+  oReq.callback = fCallback;
+  oReq.arguments = Array.prototype.slice.call(arguments, 2);
+  oReq.onload = xhrSuccess;
+  oReq.onerror = xhrError;
+  oReq.open("get", sURL, true);
+  oReq.send(null);
+}
+
+ +

Uso:

+ +
function showMessage (sMsg) {
+  alert(sMsg + this.responseText);
+}
+
+loadFile("message.txt", showMessage, "New message!\n\n");
+
+ +

A assinatura da função loadFile declara (i) uma URL de destino que será lida (via HTTP GET), (ii) uma função de callback para executar na conclusão bem-sucedida da instância xhr, e (iii) uma lista opcional de argumentos adicionais que são "passados através" do objeto XHR caso a função de callback seja bem-sucedida.

+ +

A linha 1 declara uma função que será invocada quando a operação XHR for completada com sucesso.  Isso, por sua vez, invoca uma função de callback especificada na invocação da função loadFile (neste caso, a função showMessage) que foi atribuída a propriedade do objeto XHR (Linha 7). Os  argumentos adicionais (caso existam) fornecem a invocação da função loadFile são "aplicados" para a execução da função de callback..

+ +

A linha 3 declara uma função que será invocada quando a operação XHR não for completada com sucesso.

+ +

A linha 7 define no objeto XHR  the success callback function given as the second argument to loadFile.

+ +

Line 8 slices the arguments array given to the invocation of loadFile. Starting with the third argument, all remaining arguments are collected, assigned to the arguments property of the variable oReq, passed to the success callback function xhrSuccess., and ultimately supplied to the callback function (in this case, showMessage) which is invoked by function xhrSuccess.

+ +

Line 9 designates the function xhrSuccess as the callback to be invoked when the onload event fires, that is, when the XHR sucessfully completes.  

+ +

Line 10 designates the function xhrError as the callback to be invoked when the XHR requests fails to complete.

+ +

Line 11 specifies true for its third parameter to indicate that the request should be handled asynchronously.

+ +

Line 12 actually initiates the request.

+ +

Example: using a timeout

+ +

You can use a timeout to prevent hanging your code forever while waiting for a read to occur. This is done by setting the value of the timeout property on the XMLHttpRequest object, as shown in the code below:

+ +
function loadFile(sUrl, timeout, callback){
+
+    var args = arguments.slice(3);
+    var xhr = new XMLHttpRequest();
+    xhr.ontimeout = function () {
+        console.error("The request for " + url + " timed out.");
+    };
+    xhr.onload = function() {
+        if (xhr.readyState === 4) {
+            if (xhr.status === 200) {
+                callback.apply(xhr, args);
+            } else {
+                console.error(xhr.statusText);
+            }
+        }
+    };
+    xhr.open("GET", url, true);
+    xhr.timeout = timeout;
+    xhr.send(null);
+}
+ +

Notice the addition of code to handle the "timeout" event by setting the ontimeout handler.

+ +

Usage:

+ +
function showMessage (sMsg) {
+  alert(sMsg + this.responseText);
+}
+
+loadFile("message.txt", 2000, showMessage, "New message!\n");
+
+ +

Here, we're specifying a timeout of 2000 ms.

+ +
+

Note: Support for timeout was added in {{Gecko("12.0")}}.

+
+ +

Synchronous request

+ +
Note: Starting with Gecko 30.0 {{ geckoRelease("30.0") }}, synchronous requests on the main thread have been deprecated due to the negative effects to the user experience.
+ +

Em casos raros, o uso do método síncrono é preferível ao invés do método assíncrono.

+ +

Example: HTTP synchronous request

+ +

This example demonstrates how to make a simple synchronous request.

+ +
var request = new XMLHttpRequest();
+request.open('GET', '/bar/foo.txt', false);  // `false` makes the request synchronous
+request.send(null);
+
+if (request.status === 200) {
+  console.log(request.responseText);
+}
+
+ +

Line 3 sends the request.  The null parameter indicates that no body content is needed for the GET request.

+ +

Line 5 checks the status code after the transaction is completed.  If the result is 200 -- HTTP's "OK" result -- the document's text content is output to the console.

+ +

Example: Synchronous HTTP request from a Worker

+ +

One of the few cases in which a synchronous request does not usually block execution is the use of XMLHttpRequest within a Worker.

+ +

example.html (the main page):

+ +
<!doctype html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<title>MDN Example</title>
+<script type="text/javascript">
+  var worker = new Worker("myTask.js");
+  worker.onmessage = function(event) {
+    alert("Worker said: " + event.data);
+  };
+
+  worker.postMessage("Hello");
+</script>
+</head>
+<body></body>
+</html>
+
+ +

myFile.txt (the target of the synchronous XMLHttpRequest invocation):

+ +
Hello World!!
+
+ +

myTask.js (the Worker):

+ +
self.onmessage = function (event) {
+  if (event.data === "Hello") {
+    var xhr = new XMLHttpRequest();
+    xhr.open("GET", "myFile.txt", false);  // synchronous request
+    xhr.send(null);
+    self.postMessage(xhr.responseText);
+  }
+};
+
+ +
Note: The effect, because of the use of the Worker, is however asynchronous.
+ +

It could be useful in order to interact in background with the server or to preload some content. See Using web workers for examples and details.

+ +

Adapting Sync XHR usecases to the Beacon API

+ +

There are some cases in which the synchronous usage of XMLHttpRequest was not replaceable, like during the window.onunload and window.onbeforeunload events.  The navigator.sendBeacon API can support these usecases typically while delivering a good UX.

+ +

The following example (from the sendBeacon docs) shows a theoretical analytics code that attempts to submit data to a server by using a synchronous XMLHttpRequest in an unload handler. This results in the unload of the page to be delayed.

+ +
window.addEventListener('unload', logData, false);
+
+function logData() {
+    var client = new XMLHttpRequest();
+    client.open("POST", "/log", false); // third parameter indicates sync xhr. :(
+    client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
+    client.send(analyticsData);
+}
+
+ +

Using the sendBeacon() method, the data will be transmitted asynchronously to the web server when the User Agent has had an opportunity to do so, without delaying the unload or affecting the performance of the next navigation.

+ +

The following example shows a theoretical analytics code pattern that submits data to a server using the by using the sendBeacon() method.

+ +
window.addEventListener('unload', logData, false);
+
+function logData() {
+    navigator.sendBeacon("/log", analyticsData);
+}
+
+ +

See also

+ + + +

{{ languages( {"zh-cn": "zh-cn/DOM/XMLHttpRequest/Synchronous_and_Asynchronous_Requests" } ) }}

diff --git a/files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html b/files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html deleted file mode 100644 index b541e64bc1..0000000000 --- a/files/pt-br/web/api/xmlhttprequest/usando_xmlhttprequest/index.html +++ /dev/null @@ -1,688 +0,0 @@ ---- -title: Usando XMLHttpRequest -slug: Web/API/XMLHttpRequest/Usando_XMLHttpRequest -translation_of: Web/API/XMLHttpRequest/Using_XMLHttpRequest ---- -

XMLHttpRequest torna o envio de requisições HTTP muito fácil.  Basta criar uma instância do objeto, abrir uma url e enviar uma requisição. O status HTTP do resultado assim como o seu conteúdo estarão disponíveis quando a transação for completada. Esta página descreve alguns casos comuns de uso desse poderoso objeto JavaScript.

- -
function reqListener () {
-  console.log(this.responseText);
-};
-
-var oReq = new XMLHttpRequest();
-oReq.onload = reqListener;
-oReq.open("get", "yourFile.txt", true);
-oReq.send();
- -

Tipos de Requisições

- -

Uma requisição feita via XMLHttpRequest pode buscar dados de duas maneiras, sícrona e assíncrona. O tipo de requisição é dado pelo argumento async que é opcional (terceiro argumento) e é definido no método XMLHttpRequest open(). Se esse argumento for true ou não especificado, o XMLHttpRequest será processado de maneira assíncrona, caso contrário o processamento será síncrono. Uma discussão detalhada e demonstrações desses dois tipos podem ser encontradas na página requisições síncronas e assíncronas. No geral a melhor prática é a das solicitações assíncronas.

- -

Manipulando Respostas

- -

Existem vários tipos de atributos de resposta definidos pela especificação da W3C para o  XMLHttpRequest.  Eles informam ao cliente que efetuou a requisição XMLHttpRequest informações importantes sobre o status da resposta. Em alguns casos onde se lida com tipos de resposa de não-texto, os tipos de resposta podem envolver alguma manipulação e/ou análise conforme descrito nas seções seguintes.

- -

Analisando e manipulando a propriedade responseXML

- -

Se você utiliza o XMLHttpRequest para obter o conteúdo de um documento XML remoto, a propriedade responseXML será um objeto DOM que contém um documento XML, o que pode dificultar a manipulação e análise.

- -

As cinco formas mais utilizadas para análisar e manipular um arquivo XML são:

- -
    -
  1. Usando XPath para análisar parte deles.
    2. -
  2. Usando JXON para converter em um Objeto JavaScript.
    3. -
  3. Manualmente Parsing and serializing XML para strings ou objetos.
    4. -
  4. Usando XMLSerializer para serializar árvores do DOM para strings ou para arquivos.
    5. -
  5. RegExp pode ser usado se você souber de antemão qual é o conteúdo do XML. Você pode remover quebras de linhas, usando a RegExp para procurar as quebras de linha. No entanto, este é o "último método", caso o código do XML sofra alterações, o método se torna falho.
    6. -
- -

Analisando e manipulando uma propriedade responseText contendo um documento HTML

- -
Nota: A especificação W3C do XMLHttpRequest permite analisar HTML através da propriedade XMLHttpRequest.responseXML . Leia o artigo sobre HTML in XMLHttpRequest para maiores detalhes.
- -

Se você usa o XMLHttpRequest para recuperar o conteúdo de uma página HTML remota, a propriedade responseText será uma string contendo um a "sopa" de todos as tags HTML, o que pode ser difícil de manipular e analizar. Existem três formas básicas para analizar esta sopa de string HTML:

- -
    -
  1. Use a propriedade  XMLHttpRequest.responseXML.
    2. -
  2. Introduza o conteúdo dentro do corpo de um document fragment Através de fragment.body.innerHTML e percorra o fragmento do DOM.
    3. -
  3. RegExp pode se usada se você sempre conhece o conteúdo HTML responseText de que tem em mãos. Você pode quere remover quebras de linha, se você usar RegExp para varrer no que diz respeito a quebra de linhas. Contudo, este método é um "último recurso" uma vez que se o código HTML mudar um pouco, o método provavelmente irá falhar.
    4. -
- -

Manipulação de dados binários

- -

Apesar de XMLHttpRequest ser mais comumente usado para enviar e receber dados textual, ele pode ser utilizado para enviar e receber conteúdo binário. Existem vários métodos bem testados para forçar a resposta de um XMLHttpRequest para o envio de dados binário. Eles envolvem a utilização do método  .overrideMimeType()  sobre o objeto  XMLHttpRequest e é uma solução viável.

- -
var oReq = new XMLHttpRequest();
-oReq.open("GET", url, true);
-// recupera dados não processados como uma string binária
-oReq.overrideMimeType("text/plain; charset=x-user-defined");
-/* ... */
-
- -

A especificação XMLHttpRequest Level 2  adiciona novo responseType attributes que tornam o envio e recebimento de dados muito mais fácil.

- -
var oReq = new XMLHttpRequest();
-
-oReq.open("GET", url, true);
-oReq.responseType = "arraybuffer";
-oReq.onload = function(e) {
-  var arraybuffer = oReq.response; // não é responseText
-  /* ... */
-}
-oReq.send();
-
- -

Para mais exemplos confira a página Sending and Receiving Binary Data.

- -

Monitorando o progresso

- -

XMLHttpRequest fornece a capacidade de ouvir vários eventos que podem ocorrer enquanto o pedido está sendo processado. Isso inclui notificações periódicas de progresso, notificações de erro e assim por diante.

- -

Suporte para evento de progresso DOM monitorando a conexão XMLHttpRequest transfers siga a Web API specification for progress events: estes eventos implementam a interface {{domxref("ProgressEvent")}} .

- -
var oReq = new XMLHttpRequest();
-
-oReq.addEventListener("progress", updateProgress, false);
-oReq.addEventListener("load", transferComplete, false);
-oReq.addEventListener("error", transferFailed, false);
-oReq.addEventListener("abort", transferCanceled, false);
-
-oReq.open();
-
-// ...A transferência foi cancelada pelo usuário
-
-// progresso de transferências do servidor para o cliente (downloads)
-function updateProgress (oEvent) {
-  if (oEvent.lengthComputable) {
-    var percentComplete = oEvent.loaded / oEvent.total;
-    // ...
-  } else {
-    // Não é possível calcular informações de progresso uma vez que a dimensão total é desconhecida
-  }
-}
-
-function transferComplete(evt) {
-  alert("A transferência foi concluída.");
-}
-
-function transferFailed(evt) {
-  alert("Um erro ocorreu durante a transferência do arquivo.");
-}
-
-function transferCanceled(evt) {
-  alert("A transferência foi cancelada pelo usuário.");
-}
- -

Lines 3-6 adiciona receptores de eventos (event listeners) para os vários que são enviados ao executar uma transferência de dados usando XMLHttpRequest.

- -
Nota: Você precisa adicionar os receptores de eventos (event listeners) antes de chamar open() sobre a requisição.  Caso contrário, os eventos de prograsso não dispararão..
- -

O manipulador de evento  de prograsso, especificado pela função updateProgress() neste exemplo, recebe o número total de bytes para transferir, bem como o número de bytes transferidos até o momento em total de eventos e campos  carregados . No entanto, se o campo lengthComputable é false, o comprimento total não é conhecido e será zero..

- -

Eventos de progresso existem para ambos as transferências de download e upload. The download events are fired on the XMLHttpRequest object itself, as shown in the above sample. The upload events are fired on the XMLHttpRequest.upload object, as shown below:

- -
var oReq = new XMLHttpRequest();
-
-oReq.upload.addEventListener("progress", updateProgress, false);
-oReq.upload.addEventListener("load", transferComplete, false);
-oReq.upload.addEventListener("error", transferFailed, false);
-oReq.upload.addEventListener("abort", transferCanceled, false);
-
-oReq.open();
-
- -
Nota: eventos de progresso não estão disponíveis para o arquivo: protocol.
- -
Nota: Atualmente, existem bugs em aberto para o evento de progresso que continua fetando a versão 25 do Firefox sobre OS X e Linux.
- -
-

Nota: Iniciando no {{Gecko("9.0")}}, eventos de progresso agora podem ser invocados a entrar para cada pedaço de dados recebidos, incluindo o último bloco, nos casos em que o último pacote é recebido e a conexão fechada antes do evento progresso ser disparado. Neste caso, o evento de progresso é automaticamente acionado quando o evento load ocorre para esse pacote. Isso permite que você agora acompanhe de forma confiável apenas observando o evento de progresso

-
- -
-

Nota: A partir do {{Gecko("12.0")}}, se o seu evento de progresso e chamado com um responseType de "moz-blob", o valor da resposta será um {{domxref("Blob")}} contendo os dados recebidos até agorar.

-
- -

POde-se também detectar todas as três condições de fim de carga (abort, load, or error) usando o evento loadend:

- -
req.addEventListener("loadend", loadEnd, false);
-
-function loadEnd(e) {
-  alert("A transferência terminou (embora não sabemos se ele conseguiu ou não).");
-}
-
- -

Note que não há nenhuma maneira de ter certeza a partir da informação recebida pelo evento loadend sobre qual condição causou a operação de encerrar; no entanto, você pode usar isso para lidar com tarefas que precisam ser realizadas em todos os cenários de fim-de-transferência.

- -

Submitting forms and uploading files

- -

Instances of XMLHttpRequest can be used to submit forms in two ways:

- - - -

The second way (using the FormData API) is the simplest and the fastest, but has the disadvantage that the data thus collected can not be stringified: they are in every way a blob. It is the best solution for simple cases.
- The first way (pure AJAX) is instead the most complex, but in compensation is also the most flexible and powerful: it lends itself to wider uses and the data thus collected can be stringified and reused for other purposes such as, for example, populating the status object during a manipulation of the browser history, or other.

- -

Using nothing but pure AJAX

- -

Submitting forms without the FormData API does not require other APIs, except that, only if you want to upload one or more files, the FileReader API.

- -

A brief introduction to the submit methods

- -

An html {{ HTMLElement("form") }} can be sent in four ways:

- - - -

Now, consider to submit a form containing only two fields, named foo and baz. If you are using the POST method, the server will receive a string similar to one of the following three ones depending on the encoding type you are using:

- - - -

Instead, if you are using the GET method, a string like the following will be simply added to the URL:

- -
?foo=bar&baz=The%20first%20line.%0AThe%20second%20line.
- -

A little vanilla framework

- -

All these things are done automatically by the web browser whenever you submit a {{ HTMLElement("form") }}. But if you want to do the same things using JavaScript you have to instruct the interpreter about all things. So, how to send forms in pure AJAX is too complex to be explained in detail here. For this reason we posted here a complete (but still didactic) framework, which is able to use all the four ways of submit and, also, to upload files:

- -
-
<!doctype html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>Sending forms with pure AJAX &ndash; MDN</title>
-<script type="text/javascript">
-
-"use strict";
-
-/*\
-|*|
-|*|  :: XMLHttpRequest.prototype.sendAsBinary() Polifyll ::
-|*|
-|*|  https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()
-\*/
-
-if (!XMLHttpRequest.prototype.sendAsBinary) {
-  XMLHttpRequest.prototype.sendAsBinary = function (sData) {
-    var nBytes = sData.length, ui8Data = new Uint8Array(nBytes);
-    for (var nIdx = 0; nIdx < nBytes; nIdx++) {
-      ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff;
-    }
-    /* send as ArrayBufferView...: */
-    this.send(ui8Data);
-    /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */
-  };
-}
-
-/*\
-|*|
-|*|  :: AJAX Form Submit Framework ::
-|*|
-|*|  https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest
-|*|
-|*|  This framework is released under the GNU Public License, version 3 or later.
-|*|  http://www.gnu.org/licenses/gpl-3.0-standalone.html
-|*|
-|*|  Syntax:
-|*|
-|*|   AJAXSubmit(HTMLFormElement);
-\*/
-
-var AJAXSubmit = (function () {
-
-  function ajaxSuccess () {
-    /* console.log("AJAXSubmit - Success!"); */
-    alert(this.responseText);
-    /* you can get the serialized data through the "submittedData" custom property: */
-    /* alert(JSON.stringify(this.submittedData)); */
-  }
-
-  function submitData (oData) {
-    /* the AJAX request... */
-    var oAjaxReq = new XMLHttpRequest();
-    oAjaxReq.submittedData = oData;
-    oAjaxReq.onload = ajaxSuccess;
-    if (oData.technique === 0) {
-      /* method is GET */
-      oAjaxReq.open("get", oData.receiver.replace(/(?:\?.*)?$/, oData.segments.length > 0 ? "?" + oData.segments.join("&") : ""), true);
-      oAjaxReq.send(null);
-    } else {
-      /* method is POST */
-      oAjaxReq.open("post", oData.receiver, true);
-      if (oData.technique === 3) {
-        /* enctype is multipart/form-data */
-        var sBoundary = "---------------------------" + Date.now().toString(16);
-        oAjaxReq.setRequestHeader("Content-Type", "multipart\/form-data; boundary=" + sBoundary);
-        oAjaxReq.sendAsBinary("--" + sBoundary + "\r\n" + oData.segments.join("--" + sBoundary + "\r\n") + "--" + sBoundary + "--\r\n");
-      } else {
-        /* enctype is application/x-www-form-urlencoded or text/plain */
-        oAjaxReq.setRequestHeader("Content-Type", oData.contentType);
-        oAjaxReq.send(oData.segments.join(oData.technique === 2 ? "\r\n" : "&"));
-      }
-    }
-  }
-
-  function processStatus (oData) {
-    if (oData.status > 0) { return; }
-    /* the form is now totally serialized! do something before sending it to the server... */
-    /* doSomething(oData); */
-    /* console.log("AJAXSubmit - The form is now serialized. Submitting..."); */
-    submitData (oData);
-  }
-
-  function pushSegment (oFREvt) {
-    this.owner.segments[this.segmentIdx] += oFREvt.target.result + "\r\n";
-    this.owner.status--;
-    processStatus(this.owner);
-  }
-
-  function plainEscape (sText) {
-    /* how should I treat a text/plain form encoding? what characters are not allowed? this is what I suppose...: */
-    /* "4\3\7 - Einstein said E=mc2" ----> "4\\3\\7\ -\ Einstein\ said\ E\=mc2" */
-    return sText.replace(/[\s\=\\]/g, "\\$&");
-  }
-
-  function SubmitRequest (oTarget) {
-    var nFile, sFieldType, oField, oSegmReq, oFile, bIsPost = oTarget.method.toLowerCase() === "post";
-    /* console.log("AJAXSubmit - Serializing form..."); */
-    this.contentType = bIsPost && oTarget.enctype ? oTarget.enctype : "application\/x-www-form-urlencoded";
-    this.technique = bIsPost ? this.contentType === "multipart\/form-data" ? 3 : this.contentType === "text\/plain" ? 2 : 1 : 0;
-    this.receiver = oTarget.action;
-    this.status = 0;
-    this.segments = [];
-    var fFilter = this.technique === 2 ? plainEscape : escape;
-    for (var nItem = 0; nItem < oTarget.elements.length; nItem++) {
-      oField = oTarget.elements[nItem];
-      if (!oField.hasAttribute("name")) { continue; }
-      sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT";
-      if (sFieldType === "FILE" && oField.files.length > 0) {
-        if (this.technique === 3) {
-          /* enctype is multipart/form-data */
-          for (nFile = 0; nFile < oField.files.length; nFile++) {
-            oFile = oField.files[nFile];
-            oSegmReq = new FileReader();
-            /* (custom properties:) */
-            oSegmReq.segmentIdx = this.segments.length;
-            oSegmReq.owner = this;
-            /* (end of custom properties) */
-            oSegmReq.onload = pushSegment;
-            this.segments.push("Content-Disposition: form-data; name=\"" + oField.name + "\"; filename=\""+ oFile.name + "\"\r\nContent-Type: " + oFile.type + "\r\n\r\n");
-            this.status++;
-            oSegmReq.readAsBinaryString(oFile);
-          }
-        } else {
-          /* enctype is application/x-www-form-urlencoded or text/plain or method is GET: files will not be sent! */
-          for (nFile = 0; nFile < oField.files.length; this.segments.push(fFilter(oField.name) + "=" + fFilter(oField.files[nFile++].name)));
-        }
-      } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) {
-        /* field type is not FILE or is FILE but is empty */
-        this.segments.push(
-          this.technique === 3 ? /* enctype is multipart/form-data */
-            "Content-Disposition: form-data; name=\"" + oField.name + "\"\r\n\r\n" + oField.value + "\r\n"
-          : /* enctype is application/x-www-form-urlencoded or text/plain or method is GET */
-            fFilter(oField.name) + "=" + fFilter(oField.value)
-        );
-      }
-    }
-    processStatus(this);
-  }
-
-  return function (oFormElement) {
-    if (!oFormElement.action) { return; }
-    new SubmitRequest(oFormElement);
-  };
-
-})();
-
-</script>
-</head>
-<body>
-
-<h1>Sending forms with pure AJAX</h1>
-
-<h2>Using the GET method</h2>
-
-<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Registration example</legend>
-    <p>
-      First name: <input type="text" name="firstname" /><br />
-      Last name: <input type="text" name="lastname" />
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-<h2>Using the POST method</h2>
-<h3>Enctype: application/x-www-form-urlencoded (default)</h3>
-
-<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Registration example</legend>
-    <p>
-      First name: <input type="text" name="firstname" /><br />
-      Last name: <input type="text" name="lastname" />
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-<h3>Enctype: text/plain</h3>
-
-<form action="register.php" method="post" enctype="text/plain" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Registration example</legend>
-    <p>
-      Your name: <input type="text" name="user" />
-    </p>
-    <p>
-      Your message:<br />
-      <textarea name="message" cols="40" rows="8"></textarea>
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-<h3>Enctype: multipart/form-data</h3>
-
-<form action="register.php" method="post" enctype="multipart/form-data" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Upload example</legend>
-    <p>
-      First name: <input type="text" name="firstname" /><br />
-      Last name: <input type="text" name="lastname" /><br />
-      Sex:
-      <input id="sex_male" type="radio" name="sex" value="male" /> <label for="sex_male">Male</label>
-      <input id="sex_female" type="radio" name="sex" value="female" /> <label for="sex_female">Female</label><br />
-      Password: <input type="password" name="secret" /><br />
-      What do you prefer:
-      <select name="image_type">
-        <option>Books</option>
-        <option>Cinema</option>
-        <option>TV</option>
-      </select>
-    </p>
-    <p>
-      Post your photos:
-      <input type="file" multiple name="photos[]">
-    </p>
-    <p>
-      <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> <label for="vehicle_bike">I have a bike</label><br />
-      <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> <label for="vehicle_car">I have a car</label>
-    </p>
-    <p>
-      Describe yourself:<br />
-      <textarea name="description" cols="50" rows="8"></textarea>
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-</body>
-</html>
-
- -

To test it, please, create a page named register.php (which is the action attribute of these sample forms) and just put the following minimalistic content:

- -
<?php
-
-  /* register.php */
-
-  header("Content-type: text/plain");
-
-  echo ":: data received via GET ::\n\n";
-  print_r($_GET);
-
-  echo "\n\n:: Data received via POST ::\n\n";
-  print_r($_POST);
-
-  echo "\n\n:: Data received as \"raw\" (text/plain encoding) ::\n\n";
-  if (isset($HTTP_RAW_POST_DATA)) { echo $HTTP_RAW_POST_DATA; }
-
-  echo "\n\n:: Files received ::\n\n";
-  print_r($_FILES);
-
-?>
- -

The syntax of this script is the following:

- -
AJAXSubmit(myForm);
- -
Note: This little vanilla framework uses the FileReader API, which is a recent technique (but only when there are files to upload, the method of the {{ HTMLElement("form") }} is POST and the enctype attribute is setted to multipart/form-data). For this reason, the pure-AJAX upload is to be considered an experimental technique. Instead, if you don't want to upload files, this framework will not use any recent API.
-Note also that the best way to send binary content is using ArrayBuffers or Blobs in conjuncton with the send() method and, possibly, with the readAsArrayBuffer() method of the FileReader API. But, since the aim of this little script is to work with a stringifiable raw data, we used the sendAsBinary() method in conjunction with the readAsBinaryString() method of the FileReader API. So, this is the best solution when working with a relatively few data which must be stringified in order to be reused later. Anyhow, since working with strings instead of typed arrays implies a greater waste of resources, this script makes sense only when you are dealing with small files (like images, documents, mp3, etc.). Otherwise, if you don't want to stringify the submitted or uploaded data, in addition to typed arrays, consider also the use of the FormData API.
- -

Using FormData objects

- -

The FormData constructor lets you compile a set of key/value pairs to send using XMLHttpRequest. Its primarily intended for use in sending form data, but can be used independently from forms in order to transmit keyed data. The transmitted data is in the same format that the form's submit() method would use to send the data if the form's encoding type were set to "multipart/form-data". FormData objects can be utilized in a number of ways with an XMLHttpRequest. For examples and explanations of how one can utilize FormData with XMLHttpRequests see the Using FormData Objects page. For didactic purpose only we post here a translation of the previous example transformed so as to make use of the FormData API. Note the brevity of the code:

- -
-
<!doctype html>
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<title>Sending forms with FormData &ndash; MDN</title>
-<script type="text/javascript">
-"use strict";
-
-function ajaxSuccess () {
-  alert(this.responseText);
-}
-
-function AJAXSubmit (oFormElement) {
-  if (!oFormElement.action) { return; }
-  var oReq = new XMLHttpRequest();
-  oReq.onload = ajaxSuccess;
-  if (oFormElement.method.toLowerCase() === "post") {
-    oReq.open("post", oFormElement.action, true);
-    oReq.send(new FormData(oFormElement));
-  } else {
-    var oField, sFieldType, nFile, sSearch = "";
-    for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) {
-      oField = oFormElement.elements[nItem];
-      if (!oField.hasAttribute("name")) { continue; }
-      sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT";
-      if (sFieldType === "FILE") {
-        for (nFile = 0; nFile < oField.files.length; sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name));
-      } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) {
-        sSearch += "&" + escape(oField.name) + "=" + escape(oField.value);
-      }
-    }
-    oReq.open("get", oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), true);
-    oReq.send(null);
-  }
-}
-</script>
-</head>
-<body>
-
-<h1>Sending forms with FormData</h1>
-
-<h2>Using the GET method</h2>
-
-<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Registration example</legend>
-    <p>
-      First name: <input type="text" name="firstname" /><br />
-      Last name: <input type="text" name="lastname" />
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-<h2>Using the POST method</h2>
-<h3>Enctype: application/x-www-form-urlencoded (default)</h3>
-
-<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Registration example</legend>
-    <p>
-      First name: <input type="text" name="firstname" /><br />
-      Last name: <input type="text" name="lastname" />
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-<h3>Enctype: text/plain</h3>
-
-<p>The text/plain encoding is not supported by the FormData API.</p>
-
-<h3>Enctype: multipart/form-data</h3>
-
-<form action="register.php" method="post" enctype="multipart/form-data" onsubmit="AJAXSubmit(this); return false;">
-  <fieldset>
-    <legend>Upload example</legend>
-    <p>
-      First name: <input type="text" name="firstname" /><br />
-      Last name: <input type="text" name="lastname" /><br />
-      Sex:
-      <input id="sex_male" type="radio" name="sex" value="male" /> <label for="sex_male">Male</label>
-      <input id="sex_female" type="radio" name="sex" value="female" /> <label for="sex_female">Female</label><br />
-      Password: <input type="password" name="secret" /><br />
-      What do you prefer:
-      <select name="image_type">
-        <option>Books</option>
-        <option>Cinema</option>
-        <option>TV</option>
-      </select>
-    </p>
-    <p>
-      Post your photos:
-      <input type="file" multiple name="photos[]">
-    </p>
-    <p>
-      <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> <label for="vehicle_bike">I have a bike</label><br />
-      <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> <label for="vehicle_car">I have a car</label>
-    </p>
-    <p>
-      Describe yourself:<br />
-      <textarea name="description" cols="50" rows="8"></textarea>
-    </p>
-    <p>
-      <input type="submit" value="Submit" />
-    </p>
-  </fieldset>
-</form>
-
-</body>
-</html>
-
- -
Note: As we said, FormData objects are not stringifiable objects. If you want to stringify a submitted data, use the previous pure-AJAX example. Note also that, although in this example there are some file {{ HTMLElement("input") }} fields, when you submit a form through the FormData API you do not need to use the FileReader API also: files are automatically loaded and uploaded.
- -

Cross-site XMLHttpRequest

- -

Modern browsers support cross-site requests by implementing the web applications working group's Access Control for Cross-Site Requests standard.  As long as the server is configured to allow requests from your web application's origin, XMLHttpRequest will work.  Otherwise, an INVALID_ACCESS_ERR exception is thrown.

- -

Bypassing the cache

- -

A, cross-browser compatible approach to bypassing the cache is to append a timestamp to the URL, being sure to include a "?" or "&" as appropriate.  For example:

- -
http://foo.com/bar.html -> http://foo.com/bar.html?12345
-http://foo.com/bar.html?foobar=baz -> http://foo.com/bar.html?foobar=baz&12345
-
- -

Since the local cache is indexed by URL, this causes every request to be unique, thereby bypassing the cache.

- -

You can automatically adjust URLs using the following code:

- -
var oReq = new XMLHttpRequest();
-
-oReq.open("GET", url + ((/\?/).test(url) ? "&" : "?") + (new Date()).getTime(), true);
-oReq.send(null);
- -

Security

- -

{{fx_minversion_note(3, "Versions of Firefox prior to Firefox 3 allowed you to set the preference capability.policy..XMLHttpRequest.open to allAccess to give specific sites cross-site access.  This is no longer supported.")}}

- -

{{fx_minversion_note(5, "Versions of Firefox prior to Firefox 5 could use netscape.security.PrivilegeManager.enablePrivilege(\"UniversalBrowserRead\"); to request cross-site access. This is no longer supported, even though it produces no warning and permission dialog is still presented.")}}

- -

The recommended way to enable cross-site scripting is to use the Access-Control-Allow-Origin HTTP header in the response to the XMLHttpRequest.

- -

XMLHttpRequests being stopped

- -

If you end up with an XMLHttpRequest having status=0 and statusText=null, it means that the request was not allowed to be performed. It was UNSENT. A likely cause for this is when the XMLHttpRequest origin (at the creation of the XMLHttpRequest) has changed when the XMLHttpRequest is then open(). This case can happen for example when one has an XMLHttpRequest that gets fired on an onunload event for a window: the XMLHttpRequest gets in fact created when the window to be closed is still there, and then the request is sent (ie open()) when this window has lost its focus and potentially different window has gained focus. The way to avoid this problem is to set a listener on the new window "activate" event that gets set when the old window has its "unload" event fired.

- -

Using XMLHttpRequest from JavaScript modules / XPCOM components

- -

Instantiating XMLHttpRequest from a JavaScript module or an XPCOM component works a little differently; it can't be instantiated using the XMLHttpRequest() constructor. The constructor is not defined inside components and the code results in an error. The best way to work around this is to use the XPCOM component constructor.

- -
const XMLHttpRequest = Components.Constructor("@mozilla.org/xmlextras/xmlhttprequest;1");
-var oReq = XMLHttpRequest();
- -

Unfortunately in versions of Gecko prior to Gecko 16 there is a bug which can cause requests created this way to be cancelled for no reason.  If you need your code to work on Gecko 15 or earlier, you can get the XMLHttpRequest constructor from the hidden DOM window like so.

- -
const { XMLHttpRequest } = Components.classes["@mozilla.org/appshell/appShellService;1"]
-                                     .getService(Components.interfaces.nsIAppShellService)
-                                     .hiddenDOMWindow;
-var oReq = XMLHttpRequest();
-
- -

See also

- -
    -
  1. MDC AJAX introduction
    2. -
  2. HTTP access control
    3. -
  3. How to check the security state of an XMLHTTPRequest over SSL
    4. -
  4. XMLHttpRequest - REST and the Rich User Experience
    5. -
  5. Microsoft documentation
    6. -
  6. Apple developers' reference
    7. -
  7. "Using the XMLHttpRequest Object" (jibbering.com)
    8. -
  8. The XMLHttpRequest Object: W3C Specification
    9. -
  9. Web Progress Events specification
    10. -
diff --git a/files/pt-br/web/api/xmlhttprequest/using_xmlhttprequest/index.html b/files/pt-br/web/api/xmlhttprequest/using_xmlhttprequest/index.html new file mode 100644 index 0000000000..b541e64bc1 --- /dev/null +++ b/files/pt-br/web/api/xmlhttprequest/using_xmlhttprequest/index.html @@ -0,0 +1,688 @@ +--- +title: Usando XMLHttpRequest +slug: Web/API/XMLHttpRequest/Usando_XMLHttpRequest +translation_of: Web/API/XMLHttpRequest/Using_XMLHttpRequest +--- +

XMLHttpRequest torna o envio de requisições HTTP muito fácil.  Basta criar uma instância do objeto, abrir uma url e enviar uma requisição. O status HTTP do resultado assim como o seu conteúdo estarão disponíveis quando a transação for completada. Esta página descreve alguns casos comuns de uso desse poderoso objeto JavaScript.

+ +
function reqListener () {
+  console.log(this.responseText);
+};
+
+var oReq = new XMLHttpRequest();
+oReq.onload = reqListener;
+oReq.open("get", "yourFile.txt", true);
+oReq.send();
+ +

Tipos de Requisições

+ +

Uma requisição feita via XMLHttpRequest pode buscar dados de duas maneiras, sícrona e assíncrona. O tipo de requisição é dado pelo argumento async que é opcional (terceiro argumento) e é definido no método XMLHttpRequest open(). Se esse argumento for true ou não especificado, o XMLHttpRequest será processado de maneira assíncrona, caso contrário o processamento será síncrono. Uma discussão detalhada e demonstrações desses dois tipos podem ser encontradas na página requisições síncronas e assíncronas. No geral a melhor prática é a das solicitações assíncronas.

+ +

Manipulando Respostas

+ +

Existem vários tipos de atributos de resposta definidos pela especificação da W3C para o  XMLHttpRequest.  Eles informam ao cliente que efetuou a requisição XMLHttpRequest informações importantes sobre o status da resposta. Em alguns casos onde se lida com tipos de resposa de não-texto, os tipos de resposta podem envolver alguma manipulação e/ou análise conforme descrito nas seções seguintes.

+ +

Analisando e manipulando a propriedade responseXML

+ +

Se você utiliza o XMLHttpRequest para obter o conteúdo de um documento XML remoto, a propriedade responseXML será um objeto DOM que contém um documento XML, o que pode dificultar a manipulação e análise.

+ +

As cinco formas mais utilizadas para análisar e manipular um arquivo XML são:

+ +
    +
  1. Usando XPath para análisar parte deles.
    2. +
  2. Usando JXON para converter em um Objeto JavaScript.
    3. +
  3. Manualmente Parsing and serializing XML para strings ou objetos.
    4. +
  4. Usando XMLSerializer para serializar árvores do DOM para strings ou para arquivos.
    5. +
  5. RegExp pode ser usado se você souber de antemão qual é o conteúdo do XML. Você pode remover quebras de linhas, usando a RegExp para procurar as quebras de linha. No entanto, este é o "último método", caso o código do XML sofra alterações, o método se torna falho.
    6. +
+ +

Analisando e manipulando uma propriedade responseText contendo um documento HTML

+ +
Nota: A especificação W3C do XMLHttpRequest permite analisar HTML através da propriedade XMLHttpRequest.responseXML . Leia o artigo sobre HTML in XMLHttpRequest para maiores detalhes.
+ +

Se você usa o XMLHttpRequest para recuperar o conteúdo de uma página HTML remota, a propriedade responseText será uma string contendo um a "sopa" de todos as tags HTML, o que pode ser difícil de manipular e analizar. Existem três formas básicas para analizar esta sopa de string HTML:

+ +
    +
  1. Use a propriedade  XMLHttpRequest.responseXML.
    2. +
  2. Introduza o conteúdo dentro do corpo de um document fragment Através de fragment.body.innerHTML e percorra o fragmento do DOM.
    3. +
  3. RegExp pode se usada se você sempre conhece o conteúdo HTML responseText de que tem em mãos. Você pode quere remover quebras de linha, se você usar RegExp para varrer no que diz respeito a quebra de linhas. Contudo, este método é um "último recurso" uma vez que se o código HTML mudar um pouco, o método provavelmente irá falhar.
    4. +
+ +

Manipulação de dados binários

+ +

Apesar de XMLHttpRequest ser mais comumente usado para enviar e receber dados textual, ele pode ser utilizado para enviar e receber conteúdo binário. Existem vários métodos bem testados para forçar a resposta de um XMLHttpRequest para o envio de dados binário. Eles envolvem a utilização do método  .overrideMimeType()  sobre o objeto  XMLHttpRequest e é uma solução viável.

+ +
var oReq = new XMLHttpRequest();
+oReq.open("GET", url, true);
+// recupera dados não processados como uma string binária
+oReq.overrideMimeType("text/plain; charset=x-user-defined");
+/* ... */
+
+ +

A especificação XMLHttpRequest Level 2  adiciona novo responseType attributes que tornam o envio e recebimento de dados muito mais fácil.

+ +
var oReq = new XMLHttpRequest();
+
+oReq.open("GET", url, true);
+oReq.responseType = "arraybuffer";
+oReq.onload = function(e) {
+  var arraybuffer = oReq.response; // não é responseText
+  /* ... */
+}
+oReq.send();
+
+ +

Para mais exemplos confira a página Sending and Receiving Binary Data.

+ +

Monitorando o progresso

+ +

XMLHttpRequest fornece a capacidade de ouvir vários eventos que podem ocorrer enquanto o pedido está sendo processado. Isso inclui notificações periódicas de progresso, notificações de erro e assim por diante.

+ +

Suporte para evento de progresso DOM monitorando a conexão XMLHttpRequest transfers siga a Web API specification for progress events: estes eventos implementam a interface {{domxref("ProgressEvent")}} .

+ +
var oReq = new XMLHttpRequest();
+
+oReq.addEventListener("progress", updateProgress, false);
+oReq.addEventListener("load", transferComplete, false);
+oReq.addEventListener("error", transferFailed, false);
+oReq.addEventListener("abort", transferCanceled, false);
+
+oReq.open();
+
+// ...A transferência foi cancelada pelo usuário
+
+// progresso de transferências do servidor para o cliente (downloads)
+function updateProgress (oEvent) {
+  if (oEvent.lengthComputable) {
+    var percentComplete = oEvent.loaded / oEvent.total;
+    // ...
+  } else {
+    // Não é possível calcular informações de progresso uma vez que a dimensão total é desconhecida
+  }
+}
+
+function transferComplete(evt) {
+  alert("A transferência foi concluída.");
+}
+
+function transferFailed(evt) {
+  alert("Um erro ocorreu durante a transferência do arquivo.");
+}
+
+function transferCanceled(evt) {
+  alert("A transferência foi cancelada pelo usuário.");
+}
+ +

Lines 3-6 adiciona receptores de eventos (event listeners) para os vários que são enviados ao executar uma transferência de dados usando XMLHttpRequest.

+ +
Nota: Você precisa adicionar os receptores de eventos (event listeners) antes de chamar open() sobre a requisição.  Caso contrário, os eventos de prograsso não dispararão..
+ +

O manipulador de evento  de prograsso, especificado pela função updateProgress() neste exemplo, recebe o número total de bytes para transferir, bem como o número de bytes transferidos até o momento em total de eventos e campos  carregados . No entanto, se o campo lengthComputable é false, o comprimento total não é conhecido e será zero..

+ +

Eventos de progresso existem para ambos as transferências de download e upload. The download events are fired on the XMLHttpRequest object itself, as shown in the above sample. The upload events are fired on the XMLHttpRequest.upload object, as shown below:

+ +
var oReq = new XMLHttpRequest();
+
+oReq.upload.addEventListener("progress", updateProgress, false);
+oReq.upload.addEventListener("load", transferComplete, false);
+oReq.upload.addEventListener("error", transferFailed, false);
+oReq.upload.addEventListener("abort", transferCanceled, false);
+
+oReq.open();
+
+ +
Nota: eventos de progresso não estão disponíveis para o arquivo: protocol.
+ +
Nota: Atualmente, existem bugs em aberto para o evento de progresso que continua fetando a versão 25 do Firefox sobre OS X e Linux.
+ +
+

Nota: Iniciando no {{Gecko("9.0")}}, eventos de progresso agora podem ser invocados a entrar para cada pedaço de dados recebidos, incluindo o último bloco, nos casos em que o último pacote é recebido e a conexão fechada antes do evento progresso ser disparado. Neste caso, o evento de progresso é automaticamente acionado quando o evento load ocorre para esse pacote. Isso permite que você agora acompanhe de forma confiável apenas observando o evento de progresso

+
+ +
+

Nota: A partir do {{Gecko("12.0")}}, se o seu evento de progresso e chamado com um responseType de "moz-blob", o valor da resposta será um {{domxref("Blob")}} contendo os dados recebidos até agorar.

+
+ +

POde-se também detectar todas as três condições de fim de carga (abort, load, or error) usando o evento loadend:

+ +
req.addEventListener("loadend", loadEnd, false);
+
+function loadEnd(e) {
+  alert("A transferência terminou (embora não sabemos se ele conseguiu ou não).");
+}
+
+ +

Note que não há nenhuma maneira de ter certeza a partir da informação recebida pelo evento loadend sobre qual condição causou a operação de encerrar; no entanto, você pode usar isso para lidar com tarefas que precisam ser realizadas em todos os cenários de fim-de-transferência.

+ +

Submitting forms and uploading files

+ +

Instances of XMLHttpRequest can be used to submit forms in two ways:

+ + + +

The second way (using the FormData API) is the simplest and the fastest, but has the disadvantage that the data thus collected can not be stringified: they are in every way a blob. It is the best solution for simple cases.
+ The first way (pure AJAX) is instead the most complex, but in compensation is also the most flexible and powerful: it lends itself to wider uses and the data thus collected can be stringified and reused for other purposes such as, for example, populating the status object during a manipulation of the browser history, or other.

+ +

Using nothing but pure AJAX

+ +

Submitting forms without the FormData API does not require other APIs, except that, only if you want to upload one or more files, the FileReader API.

+ +

A brief introduction to the submit methods

+ +

An html {{ HTMLElement("form") }} can be sent in four ways:

+ + + +

Now, consider to submit a form containing only two fields, named foo and baz. If you are using the POST method, the server will receive a string similar to one of the following three ones depending on the encoding type you are using:

+ + + +

Instead, if you are using the GET method, a string like the following will be simply added to the URL:

+ +
?foo=bar&baz=The%20first%20line.%0AThe%20second%20line.
+ +

A little vanilla framework

+ +

All these things are done automatically by the web browser whenever you submit a {{ HTMLElement("form") }}. But if you want to do the same things using JavaScript you have to instruct the interpreter about all things. So, how to send forms in pure AJAX is too complex to be explained in detail here. For this reason we posted here a complete (but still didactic) framework, which is able to use all the four ways of submit and, also, to upload files:

+ +
+
<!doctype html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<title>Sending forms with pure AJAX &ndash; MDN</title>
+<script type="text/javascript">
+
+"use strict";
+
+/*\
+|*|
+|*|  :: XMLHttpRequest.prototype.sendAsBinary() Polifyll ::
+|*|
+|*|  https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()
+\*/
+
+if (!XMLHttpRequest.prototype.sendAsBinary) {
+  XMLHttpRequest.prototype.sendAsBinary = function (sData) {
+    var nBytes = sData.length, ui8Data = new Uint8Array(nBytes);
+    for (var nIdx = 0; nIdx < nBytes; nIdx++) {
+      ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff;
+    }
+    /* send as ArrayBufferView...: */
+    this.send(ui8Data);
+    /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */
+  };
+}
+
+/*\
+|*|
+|*|  :: AJAX Form Submit Framework ::
+|*|
+|*|  https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest
+|*|
+|*|  This framework is released under the GNU Public License, version 3 or later.
+|*|  http://www.gnu.org/licenses/gpl-3.0-standalone.html
+|*|
+|*|  Syntax:
+|*|
+|*|   AJAXSubmit(HTMLFormElement);
+\*/
+
+var AJAXSubmit = (function () {
+
+  function ajaxSuccess () {
+    /* console.log("AJAXSubmit - Success!"); */
+    alert(this.responseText);
+    /* you can get the serialized data through the "submittedData" custom property: */
+    /* alert(JSON.stringify(this.submittedData)); */
+  }
+
+  function submitData (oData) {
+    /* the AJAX request... */
+    var oAjaxReq = new XMLHttpRequest();
+    oAjaxReq.submittedData = oData;
+    oAjaxReq.onload = ajaxSuccess;
+    if (oData.technique === 0) {
+      /* method is GET */
+      oAjaxReq.open("get", oData.receiver.replace(/(?:\?.*)?$/, oData.segments.length > 0 ? "?" + oData.segments.join("&") : ""), true);
+      oAjaxReq.send(null);
+    } else {
+      /* method is POST */
+      oAjaxReq.open("post", oData.receiver, true);
+      if (oData.technique === 3) {
+        /* enctype is multipart/form-data */
+        var sBoundary = "---------------------------" + Date.now().toString(16);
+        oAjaxReq.setRequestHeader("Content-Type", "multipart\/form-data; boundary=" + sBoundary);
+        oAjaxReq.sendAsBinary("--" + sBoundary + "\r\n" + oData.segments.join("--" + sBoundary + "\r\n") + "--" + sBoundary + "--\r\n");
+      } else {
+        /* enctype is application/x-www-form-urlencoded or text/plain */
+        oAjaxReq.setRequestHeader("Content-Type", oData.contentType);
+        oAjaxReq.send(oData.segments.join(oData.technique === 2 ? "\r\n" : "&"));
+      }
+    }
+  }
+
+  function processStatus (oData) {
+    if (oData.status > 0) { return; }
+    /* the form is now totally serialized! do something before sending it to the server... */
+    /* doSomething(oData); */
+    /* console.log("AJAXSubmit - The form is now serialized. Submitting..."); */
+    submitData (oData);
+  }
+
+  function pushSegment (oFREvt) {
+    this.owner.segments[this.segmentIdx] += oFREvt.target.result + "\r\n";
+    this.owner.status--;
+    processStatus(this.owner);
+  }
+
+  function plainEscape (sText) {
+    /* how should I treat a text/plain form encoding? what characters are not allowed? this is what I suppose...: */
+    /* "4\3\7 - Einstein said E=mc2" ----> "4\\3\\7\ -\ Einstein\ said\ E\=mc2" */
+    return sText.replace(/[\s\=\\]/g, "\\$&");
+  }
+
+  function SubmitRequest (oTarget) {
+    var nFile, sFieldType, oField, oSegmReq, oFile, bIsPost = oTarget.method.toLowerCase() === "post";
+    /* console.log("AJAXSubmit - Serializing form..."); */
+    this.contentType = bIsPost && oTarget.enctype ? oTarget.enctype : "application\/x-www-form-urlencoded";
+    this.technique = bIsPost ? this.contentType === "multipart\/form-data" ? 3 : this.contentType === "text\/plain" ? 2 : 1 : 0;
+    this.receiver = oTarget.action;
+    this.status = 0;
+    this.segments = [];
+    var fFilter = this.technique === 2 ? plainEscape : escape;
+    for (var nItem = 0; nItem < oTarget.elements.length; nItem++) {
+      oField = oTarget.elements[nItem];
+      if (!oField.hasAttribute("name")) { continue; }
+      sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT";
+      if (sFieldType === "FILE" && oField.files.length > 0) {
+        if (this.technique === 3) {
+          /* enctype is multipart/form-data */
+          for (nFile = 0; nFile < oField.files.length; nFile++) {
+            oFile = oField.files[nFile];
+            oSegmReq = new FileReader();
+            /* (custom properties:) */
+            oSegmReq.segmentIdx = this.segments.length;
+            oSegmReq.owner = this;
+            /* (end of custom properties) */
+            oSegmReq.onload = pushSegment;
+            this.segments.push("Content-Disposition: form-data; name=\"" + oField.name + "\"; filename=\""+ oFile.name + "\"\r\nContent-Type: " + oFile.type + "\r\n\r\n");
+            this.status++;
+            oSegmReq.readAsBinaryString(oFile);
+          }
+        } else {
+          /* enctype is application/x-www-form-urlencoded or text/plain or method is GET: files will not be sent! */
+          for (nFile = 0; nFile < oField.files.length; this.segments.push(fFilter(oField.name) + "=" + fFilter(oField.files[nFile++].name)));
+        }
+      } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) {
+        /* field type is not FILE or is FILE but is empty */
+        this.segments.push(
+          this.technique === 3 ? /* enctype is multipart/form-data */
+            "Content-Disposition: form-data; name=\"" + oField.name + "\"\r\n\r\n" + oField.value + "\r\n"
+          : /* enctype is application/x-www-form-urlencoded or text/plain or method is GET */
+            fFilter(oField.name) + "=" + fFilter(oField.value)
+        );
+      }
+    }
+    processStatus(this);
+  }
+
+  return function (oFormElement) {
+    if (!oFormElement.action) { return; }
+    new SubmitRequest(oFormElement);
+  };
+
+})();
+
+</script>
+</head>
+<body>
+
+<h1>Sending forms with pure AJAX</h1>
+
+<h2>Using the GET method</h2>
+
+<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Registration example</legend>
+    <p>
+      First name: <input type="text" name="firstname" /><br />
+      Last name: <input type="text" name="lastname" />
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+<h2>Using the POST method</h2>
+<h3>Enctype: application/x-www-form-urlencoded (default)</h3>
+
+<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Registration example</legend>
+    <p>
+      First name: <input type="text" name="firstname" /><br />
+      Last name: <input type="text" name="lastname" />
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+<h3>Enctype: text/plain</h3>
+
+<form action="register.php" method="post" enctype="text/plain" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Registration example</legend>
+    <p>
+      Your name: <input type="text" name="user" />
+    </p>
+    <p>
+      Your message:<br />
+      <textarea name="message" cols="40" rows="8"></textarea>
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+<h3>Enctype: multipart/form-data</h3>
+
+<form action="register.php" method="post" enctype="multipart/form-data" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Upload example</legend>
+    <p>
+      First name: <input type="text" name="firstname" /><br />
+      Last name: <input type="text" name="lastname" /><br />
+      Sex:
+      <input id="sex_male" type="radio" name="sex" value="male" /> <label for="sex_male">Male</label>
+      <input id="sex_female" type="radio" name="sex" value="female" /> <label for="sex_female">Female</label><br />
+      Password: <input type="password" name="secret" /><br />
+      What do you prefer:
+      <select name="image_type">
+        <option>Books</option>
+        <option>Cinema</option>
+        <option>TV</option>
+      </select>
+    </p>
+    <p>
+      Post your photos:
+      <input type="file" multiple name="photos[]">
+    </p>
+    <p>
+      <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> <label for="vehicle_bike">I have a bike</label><br />
+      <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> <label for="vehicle_car">I have a car</label>
+    </p>
+    <p>
+      Describe yourself:<br />
+      <textarea name="description" cols="50" rows="8"></textarea>
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+</body>
+</html>
+
+ +

To test it, please, create a page named register.php (which is the action attribute of these sample forms) and just put the following minimalistic content:

+ +
<?php
+
+  /* register.php */
+
+  header("Content-type: text/plain");
+
+  echo ":: data received via GET ::\n\n";
+  print_r($_GET);
+
+  echo "\n\n:: Data received via POST ::\n\n";
+  print_r($_POST);
+
+  echo "\n\n:: Data received as \"raw\" (text/plain encoding) ::\n\n";
+  if (isset($HTTP_RAW_POST_DATA)) { echo $HTTP_RAW_POST_DATA; }
+
+  echo "\n\n:: Files received ::\n\n";
+  print_r($_FILES);
+
+?>
+ +

The syntax of this script is the following:

+ +
AJAXSubmit(myForm);
+ +
Note: This little vanilla framework uses the FileReader API, which is a recent technique (but only when there are files to upload, the method of the {{ HTMLElement("form") }} is POST and the enctype attribute is setted to multipart/form-data). For this reason, the pure-AJAX upload is to be considered an experimental technique. Instead, if you don't want to upload files, this framework will not use any recent API.
+Note also that the best way to send binary content is using ArrayBuffers or Blobs in conjuncton with the send() method and, possibly, with the readAsArrayBuffer() method of the FileReader API. But, since the aim of this little script is to work with a stringifiable raw data, we used the sendAsBinary() method in conjunction with the readAsBinaryString() method of the FileReader API. So, this is the best solution when working with a relatively few data which must be stringified in order to be reused later. Anyhow, since working with strings instead of typed arrays implies a greater waste of resources, this script makes sense only when you are dealing with small files (like images, documents, mp3, etc.). Otherwise, if you don't want to stringify the submitted or uploaded data, in addition to typed arrays, consider also the use of the FormData API.
+ +

Using FormData objects

+ +

The FormData constructor lets you compile a set of key/value pairs to send using XMLHttpRequest. Its primarily intended for use in sending form data, but can be used independently from forms in order to transmit keyed data. The transmitted data is in the same format that the form's submit() method would use to send the data if the form's encoding type were set to "multipart/form-data". FormData objects can be utilized in a number of ways with an XMLHttpRequest. For examples and explanations of how one can utilize FormData with XMLHttpRequests see the Using FormData Objects page. For didactic purpose only we post here a translation of the previous example transformed so as to make use of the FormData API. Note the brevity of the code:

+ +
+
<!doctype html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+<title>Sending forms with FormData &ndash; MDN</title>
+<script type="text/javascript">
+"use strict";
+
+function ajaxSuccess () {
+  alert(this.responseText);
+}
+
+function AJAXSubmit (oFormElement) {
+  if (!oFormElement.action) { return; }
+  var oReq = new XMLHttpRequest();
+  oReq.onload = ajaxSuccess;
+  if (oFormElement.method.toLowerCase() === "post") {
+    oReq.open("post", oFormElement.action, true);
+    oReq.send(new FormData(oFormElement));
+  } else {
+    var oField, sFieldType, nFile, sSearch = "";
+    for (var nItem = 0; nItem < oFormElement.elements.length; nItem++) {
+      oField = oFormElement.elements[nItem];
+      if (!oField.hasAttribute("name")) { continue; }
+      sFieldType = oField.nodeName.toUpperCase() === "INPUT" ? oField.getAttribute("type").toUpperCase() : "TEXT";
+      if (sFieldType === "FILE") {
+        for (nFile = 0; nFile < oField.files.length; sSearch += "&" + escape(oField.name) + "=" + escape(oField.files[nFile++].name));
+      } else if ((sFieldType !== "RADIO" && sFieldType !== "CHECKBOX") || oField.checked) {
+        sSearch += "&" + escape(oField.name) + "=" + escape(oField.value);
+      }
+    }
+    oReq.open("get", oFormElement.action.replace(/(?:\?.*)?$/, sSearch.replace(/^&/, "?")), true);
+    oReq.send(null);
+  }
+}
+</script>
+</head>
+<body>
+
+<h1>Sending forms with FormData</h1>
+
+<h2>Using the GET method</h2>
+
+<form action="register.php" method="get" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Registration example</legend>
+    <p>
+      First name: <input type="text" name="firstname" /><br />
+      Last name: <input type="text" name="lastname" />
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+<h2>Using the POST method</h2>
+<h3>Enctype: application/x-www-form-urlencoded (default)</h3>
+
+<form action="register.php" method="post" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Registration example</legend>
+    <p>
+      First name: <input type="text" name="firstname" /><br />
+      Last name: <input type="text" name="lastname" />
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+<h3>Enctype: text/plain</h3>
+
+<p>The text/plain encoding is not supported by the FormData API.</p>
+
+<h3>Enctype: multipart/form-data</h3>
+
+<form action="register.php" method="post" enctype="multipart/form-data" onsubmit="AJAXSubmit(this); return false;">
+  <fieldset>
+    <legend>Upload example</legend>
+    <p>
+      First name: <input type="text" name="firstname" /><br />
+      Last name: <input type="text" name="lastname" /><br />
+      Sex:
+      <input id="sex_male" type="radio" name="sex" value="male" /> <label for="sex_male">Male</label>
+      <input id="sex_female" type="radio" name="sex" value="female" /> <label for="sex_female">Female</label><br />
+      Password: <input type="password" name="secret" /><br />
+      What do you prefer:
+      <select name="image_type">
+        <option>Books</option>
+        <option>Cinema</option>
+        <option>TV</option>
+      </select>
+    </p>
+    <p>
+      Post your photos:
+      <input type="file" multiple name="photos[]">
+    </p>
+    <p>
+      <input id="vehicle_bike" type="checkbox" name="vehicle[]" value="Bike" /> <label for="vehicle_bike">I have a bike</label><br />
+      <input id="vehicle_car" type="checkbox" name="vehicle[]" value="Car" /> <label for="vehicle_car">I have a car</label>
+    </p>
+    <p>
+      Describe yourself:<br />
+      <textarea name="description" cols="50" rows="8"></textarea>
+    </p>
+    <p>
+      <input type="submit" value="Submit" />
+    </p>
+  </fieldset>
+</form>
+
+</body>
+</html>
+
+ +
Note: As we said, FormData objects are not stringifiable objects. If you want to stringify a submitted data, use the previous pure-AJAX example. Note also that, although in this example there are some file {{ HTMLElement("input") }} fields, when you submit a form through the FormData API you do not need to use the FileReader API also: files are automatically loaded and uploaded.
+ +

Cross-site XMLHttpRequest

+ +

Modern browsers support cross-site requests by implementing the web applications working group's Access Control for Cross-Site Requests standard.  As long as the server is configured to allow requests from your web application's origin, XMLHttpRequest will work.  Otherwise, an INVALID_ACCESS_ERR exception is thrown.

+ +

Bypassing the cache

+ +

A, cross-browser compatible approach to bypassing the cache is to append a timestamp to the URL, being sure to include a "?" or "&" as appropriate.  For example:

+ +
http://foo.com/bar.html -> http://foo.com/bar.html?12345
+http://foo.com/bar.html?foobar=baz -> http://foo.com/bar.html?foobar=baz&12345
+
+ +

Since the local cache is indexed by URL, this causes every request to be unique, thereby bypassing the cache.

+ +

You can automatically adjust URLs using the following code:

+ +
var oReq = new XMLHttpRequest();
+
+oReq.open("GET", url + ((/\?/).test(url) ? "&" : "?") + (new Date()).getTime(), true);
+oReq.send(null);
+ +

Security

+ +

{{fx_minversion_note(3, "Versions of Firefox prior to Firefox 3 allowed you to set the preference capability.policy..XMLHttpRequest.open to allAccess to give specific sites cross-site access.  This is no longer supported.")}}

+ +

{{fx_minversion_note(5, "Versions of Firefox prior to Firefox 5 could use netscape.security.PrivilegeManager.enablePrivilege(\"UniversalBrowserRead\"); to request cross-site access. This is no longer supported, even though it produces no warning and permission dialog is still presented.")}}

+ +

The recommended way to enable cross-site scripting is to use the Access-Control-Allow-Origin HTTP header in the response to the XMLHttpRequest.

+ +

XMLHttpRequests being stopped

+ +

If you end up with an XMLHttpRequest having status=0 and statusText=null, it means that the request was not allowed to be performed. It was UNSENT. A likely cause for this is when the XMLHttpRequest origin (at the creation of the XMLHttpRequest) has changed when the XMLHttpRequest is then open(). This case can happen for example when one has an XMLHttpRequest that gets fired on an onunload event for a window: the XMLHttpRequest gets in fact created when the window to be closed is still there, and then the request is sent (ie open()) when this window has lost its focus and potentially different window has gained focus. The way to avoid this problem is to set a listener on the new window "activate" event that gets set when the old window has its "unload" event fired.

+ +

Using XMLHttpRequest from JavaScript modules / XPCOM components

+ +

Instantiating XMLHttpRequest from a JavaScript module or an XPCOM component works a little differently; it can't be instantiated using the XMLHttpRequest() constructor. The constructor is not defined inside components and the code results in an error. The best way to work around this is to use the XPCOM component constructor.

+ +
const XMLHttpRequest = Components.Constructor("@mozilla.org/xmlextras/xmlhttprequest;1");
+var oReq = XMLHttpRequest();
+ +

Unfortunately in versions of Gecko prior to Gecko 16 there is a bug which can cause requests created this way to be cancelled for no reason.  If you need your code to work on Gecko 15 or earlier, you can get the XMLHttpRequest constructor from the hidden DOM window like so.

+ +
const { XMLHttpRequest } = Components.classes["@mozilla.org/appshell/appShellService;1"]
+                                     .getService(Components.interfaces.nsIAppShellService)
+                                     .hiddenDOMWindow;
+var oReq = XMLHttpRequest();
+
+ +

See also

+ +
    +
  1. MDC AJAX introduction
    2. +
  2. HTTP access control
    3. +
  3. How to check the security state of an XMLHTTPRequest over SSL
    4. +
  4. XMLHttpRequest - REST and the Rich User Experience
    5. +
  5. Microsoft documentation
    6. +
  6. Apple developers' reference
    7. +
  7. "Using the XMLHttpRequest Object" (jibbering.com)
    8. +
  8. The XMLHttpRequest Object: W3C Specification
    9. +
  9. Web Progress Events specification
    10. +
-- cgit v1.2.3-54-g00ecf