diff --git a/2-ui/2-events/05-dispatch-events/article.md b/2-ui/2-events/05-dispatch-events/article.md index 1a8e92ef1..946a8a8be 100644 --- a/2-ui/2-events/05-dispatch-events/article.md +++ b/2-ui/2-events/05-dispatch-events/article.md @@ -1,40 +1,40 @@ -# Dispatching custom events +# Envío de eventos personalizados -We can not only assign handlers, but also generate events from JavaScript. +No solo podemos asignar controladores, sino también generar eventos desde JavaScript. -Custom events can be used to create "graphical components". For instance, a root element of our own JS-based menu may trigger events telling what happens with the menu: `open` (menu open), `select` (an item is selected) and so on. Another code may listen for the events and observe what's happening with the menu. +Los eventos personalizados se pueden utilizar para crear "componentes gráficos". Por ejemplo, un elemento raíz de nuestro propio menú basado en JS puede desencadenar eventos que indiquen lo que sucede con el menú: `abrir` (menú abierto),` seleccionar` (se selecciona un elemento) y así sucesivamente. Otro código puede escuchar los eventos y observar lo que sucede con el menú. -We can generate not only completely new events, that we invent for our own purposes, but also built-in ones, such as `click`, `mousedown` etc. That may be helpful for automated testing. +No solo podemos generar eventos completamente nuevos, que inventamos para nuestros propios fines, sino también eventos integrados, como `click`, `mousedown`, etc. Eso puede ser útil para las pruebas automatizadas. -## Event constructor +## Constructor de eventos -Build-in event classes form a hierarchy, similar to DOM element classes. The root is the built-in [Event](http://www.w3.org/TR/dom/#event) class. +Las clases de eventos integradas forman una jerarquía, similar a las clases de elementos DOM. La raíz es la clase incorporada [Event](http://www.w3.org/TR/dom/#event). -We can create `Event` objects like this: +Podemos crear objetos `Event` así: ```js let event = new Event(type[, options]); ``` -Arguments: +Argumentos: -- *type* -- event type, a string like `"click"` or our own like `"my-event"`. -- *options* -- the object with two optional properties: - - `bubbles: true/false` -- if `true`, then the event bubbles. - - `cancelable: true/false` -- if `true`, then the "default action" may be prevented. Later we'll see what it means for custom events. +- *type* -- tipo de event, un string como `"click"` o nuestro propio evento como `"mi-evento"`. +- *options* -- el objeto con 2 propiedades opcionales: + - `bubbles: true/false` -- si es `true`, entonces el evento se propaga. + - `cancelable: true/false` -- si es `true`, entonces la "acción predeterminada" puede ser prevenida. Más adelante veremos qué significa para los eventos personalizados. - By default both are false: `{bubbles: false, cancelable: false}`. + Por defecto, los dos son false: `{bubbles: false, cancelable: false}`. ## dispatchEvent -After an event object is created, we should "run" it on an element using the call `elem.dispatchEvent(event)`. +Después de que se crea un objeto de evento, debemos "ejecutarlo" en un elemento usando la llamada `elem.dispatchEvent(event)`. -Then handlers react on it as if it were a regular browser event. If the event was created with the `bubbles` flag, then it bubbles. +Luego, los controladores reaccionan como si fuera un evento normal del navegador. Si el evento fue creado con la bandera `bubbles`, entonces se propaga. -In the example below the `click` event is initiated in JavaScript. The handler works same way as if the button was clicked: +En el siguiente ejemplo, el evento `click` se inicia en JavaScript. El controlador funciona de la misma manera que si se hiciera clic en el botón: ```html run no-beautify - + ``` -Notes: +Notas: -1. We should use `addEventListener` for our custom events, because `on` only exists for built-in events, `document.onhello` doesn't work. -2. Must set `bubbles:true`, otherwise the event won't bubble up. +1. Debemos usar `addEventListener` para nuestros eventos personalizados, porque `on` solo existe para eventos incorporados, `document.onhello` no funciona. +2. Debes poner `bubbles:true`, de otra manera el evento no se propagará. -The bubbling mechanics is the same for built-in (`click`) and custom (`hello`) events. There are also capturing and bubbling stages. +La mecánica de bubbling es la misma para los eventos integrados (`click`) y personalizados (`hello`). También hay etapas de captura y propagación. -## MouseEvent, KeyboardEvent and others +## MouseEvent, KeyboardEvent y otros -Here's a short list of classes for UI Events from the [UI Event specification](https://www.w3.org/TR/uievents): +Aquí hay una breve lista de clases para eventos UI (interfaz de usuario) de la [especificación de eventos UI](https://www.w3.org/TR/uievents): - `UIEvent` - `FocusEvent` @@ -91,11 +91,11 @@ Here's a short list of classes for UI Events from the [UI Event specification](h - `KeyboardEvent` - ... -We should use them instead of `new Event` if we want to create such events. For instance, `new MouseEvent("click")`. +Deberíamos usarlos en lugar de `new Event` si queremos crear tales eventos. Por ejemplo, `new MouseEvent("click")`. -The right constructor allows to specify standard properties for that type of event. +El constructor correcto permite especificar propiedades estándar para ese tipo de evento. -Like `clientX/clientY` for a mouse event: +Como `clientX/clientY` para un evento de mouse: ```js run let event = new MouseEvent("click", { @@ -110,40 +110,40 @@ alert(event.clientX); // 100 */!* ``` -Please note: the generic `Event` constructor does not allow that. +Tenga en cuenta: el constructor genérico `Event` no lo permite. -Let's try: +Intentemos: ```js run let event = new Event("click", { - bubbles: true, // only bubbles and cancelable - cancelable: true, // work in the Event constructor + bubbles: true, // solo bubbles y cancelable + cancelable: true, // funcionan en el constructor de Event clientX: 100, clientY: 100 }); *!* -alert(event.clientX); // undefined, the unknown property is ignored! +alert(event.clientX); // undefined, se ignora la propiedad desconocida! */!* ``` -Technically, we can work around that by assigning directly `event.clientX=100` after creation. So that's a matter of convenience and following the rules. Browser-generated events always have the right type. +Técnicamente, podemos solucionarlo asignando directamente `event.clientX=100` después de la creación. Entonces eso es una cuestión de conveniencia y de seguir las reglas. Los eventos generados por el navegador siempre tienen el tipo correcto. -The full list of properties for different UI events is in the specification, for instance, [MouseEvent](https://www.w3.org/TR/uievents/#mouseevent). +La lista completa de propiedades para diferentes eventos de UI se encuentra en la especificación, por ejemplo, [MouseEvent](https://www.w3.org/TR/uievents/#mouseevent). -## Custom events +## Eventos personalizados -For our own, completely new events types like `"hello"` we should use `new CustomEvent`. Technically [CustomEvent](https://dom.spec.whatwg.org/#customevent) is the same as `Event`, with one exception. +Para nuestros tipos de eventos completamente nuevos, como `"hello"`, deberíamos usar `new CustomEvent`. Técnicamente, [CustomEvent](https://dom.spec.whatwg.org/#customevent) es lo mismo que `Event`, con una excepción. -In the second argument (object) we can add an additional property `detail` for any custom information that we want to pass with the event. +En el segundo argumento (objeto) podemos agregar una propiedad adicional `detail` para cualquier información personalizada que queramos pasar con el evento. -For instance: +Por ejemplo: ```html run refresh -

Hello for John!

+

Hola para John!

``` -The `detail` property can have any data. Technically we could live without, because we can assign any properties into a regular `new Event` object after its creation. But `CustomEvent` provides the special `detail` field for it to evade conflicts with other event properties. +La propiedad `detail` puede tener cualquier dato. Técnicamente podríamos vivir sin él, porque podemos asignar cualquier propiedad a un objeto `new Event` regular después de su creación. Pero `CustomEvent` proporciona el campo especial `detail` para evitar conflictos con otras propiedades del evento. -Besides, the event class describes "what kind of event" it is, and if the event is custom, then we should use `CustomEvent` just to be clear about what it is. +Además, la clase de evento describe "qué tipo de evento" es, y si el evento es personalizado, entonces deberíamos usar `CustomEvent` solo para tener claro qué es. ## event.preventDefault() -Many browser events have a "default action", such as nagivating to a link, starting a selection, and so on. +Muchos eventos del navegador tienen una "acción predeterminada", como ir a un enlace, iniciar una selección, etc. -For new, custom events, there are definitely no default browser actions, but a code that dispatches such event may have its own plans what to do after triggering the event. +Para eventos nuevos y personalizados, definitivamente no hay acciones predeterminadas del navegador, pero un código que distribuye dicho evento puede tener sus propios planes de qué hacer después de activar el evento. -By calling `event.preventDefault()`, an event handler may send a signal that those actions should be canceled. +Al llamar a `event.preventDefault()`, un controlador de eventos puede enviar una señal de que esas acciones deben cancelarse. -In that case the call to `elem.dispatchEvent(event)` returns `false`. And the code that dispatched it knows that it shouldn't continue. +En ese caso, la llamada a `elem.dispatchEvent(event)` devuelve `false`. Y el código que lo envió sabe que no debería continuar. -Let's see a practical example - a hiding rabbit (could be a closing menu or something else). +Veamos un ejemplo práctico: un conejo escondido (podría ser un menú de cierre u otra cosa). -Below you can see a `#rabbit` and `hide()` function that dispatches `"hide"` event on it, to let all interested parties know that the rabbit is going to hide. +A continuación puede ver una función `#rabbit` y `hide()` que distribuye el evento `"hide"` en él, para que todas las partes interesadas sepan que el conejo se va a esconder. -Any handler can listen for that event with `rabbit.addEventListener('hide',...)` and, if needed, cancel the action using `event.preventDefault()`. Then the rabbit won't disappear: +Cualquier controlador puede escuchar ese evento con `rabbit.addEventListener('hide', ...)` y, si es necesario, cancelar la acción usando `event.preventDefault()`. Entonces el conejo no desaparecerá: ```html run refresh autorun 
@@ -184,44 +184,44 @@ Any handler can listen for that event with `rabbit.addEventListener('hide',...)`
   =\_Y_/=
    {>o<}
- + ``` -Please note: the event must have the flag `cancelable: true`, otherwise the call `event.preventDefault()` is ignored. +Tenga en cuenta: el evento debe tener la bandera `cancelable: true`, de lo contrario, la llamada `event.preventDefault()` se ignora. -## Events-in-events are synchronous +## Los eventos dentro de eventos son sincrónicos -Usually events are processed in a queue. That is: if the browser is processing `onclick` and a new event occurs, e.g. mouse moved, then it's handing is queued up, corresponding `mousemove` handlers will be called after `onclick` processing is finished. +Por lo general, los eventos se procesan en una cola. Es decir: si el navegador está procesando `onclick` y ocurre un nuevo evento, por ejemplo, con el mouse movido, luego su despacho se pone en cola, los controladores correspondientes `mousemove` serán llamados después de que el procesamiento de `onclick` haya terminado. -The notable exception is when one event is initiated from within another one, e.g. using `dispatchEvent`. Such events are processed immediately: the new event handlers are called, and then the current event handling is resumed. +La excepción notable es cuando un evento se inicia desde dentro de otro, por ejemplo, usando `dispatchEvent`. Dichos eventos se procesan inmediatamente: se llaman los nuevos controladores de eventos y luego se reanuda el manejo de eventos actual. -For instance, in the code below the `menu-open` event is triggered during the `onclick`. +Por ejemplo, en el código siguiente, el evento `menu-open` se activa durante el `onclick`. -It's processed immediately, without waiting for `onlick` handler to end: +Se procesa inmediatamente, sin esperar a que termine el controlador `onclick`: ```html run autorun - + ``` -The output order is: 1 -> nested -> 2. +El orden de salida es: 1 -> anidado -> 2. -Please note that the nested event `menu-open` is caught on the `document`. The propagation and handling of the nested event is finished before the processing gets back to the outer code (`onclick`). +Tenga en cuenta que el evento anidado `menu-open` se captura en `document`. La propagación y el manejo del evento anidado finaliza antes de que el procesamiento vuelva al código externo (`onclick`). -That's not only about `dispatchEvent`, there are other cases. If an event handler calls methods that trigger to other events -- they are too processed synchronously, in a nested fashion. +No se trata solo de `dispatchEvent`, hay otros casos. Si un controlador de eventos llama a métodos que desencadenan otros eventos, también se procesan sincrónicamente, de forma anidada. -Let's say we don't like it. We'd want `onclick` to be fully processed first, independently from `menu-open` or any other nested events. +Digamos que no nos gusta. Querríamos que `onclick` se procesara por completo primero, independientemente de `menu-open` o cualquier otro evento anidado. -Then we can either put the `dispatchEvent` (or another event-triggering call) at the end of `onclick` or, maybe better, wrap it in the zero-delay `setTimeout`: +Entonces podemos poner el `dispatchEvent` (u otra llamada de activación de eventos) al final de `onclick` o, mejor aún, envolverlo en el `setTimeout` de retardo cero: ```html run - + ``` -Now `dispatchEvent` runs asynchronously after the current code execution is finished, including `mouse.onclick`, so event handlers are totally separate. +Entonces podemos poner el `dispatchEvent` (u otra llamada de activación de eventos) al final de `onclick` o, mejor aún, envolverlo en el `setTimeout` de retardo cero: -The output order becomes: 1 -> 2 -> nested. +El orden de salida se convierte en: 1 -> 2 -> anidado. -## Summary +## Resumen -To generate an event from code, we first need to create an event object. +Para generar un evento a partir del código, primero necesitamos crear un objeto de evento. -The generic `Event(name, options)` constructor accepts an arbitrary event name and the `options` object with two properties: -- `bubbles: true` if the event should bubble. -- `cancelable: true` if the `event.preventDefault()` should work. +El constructor genérico `Event(name, options)` acepta un nombre de evento arbitrario y el objeto `options` con dos propiedades: +- `bubbles: true` si el evento debe propagarse. +- `cancelable: true` si `event.preventDefault()` debe funcionar. -Other constructors of native events like `MouseEvent`, `KeyboardEvent` and so on accept properties specific to that event type. For instance, `clientX` for mouse events. +Otros constructores de eventos nativos como `MouseEvent`, `KeyboardEvent`, y similares, aceptan propiedades específicas para ese tipo de evento. Por ejemplo, `clientX` para eventos de mouse. -For custom events we should use `CustomEvent` constructor. It has an additional option named `detail`, we should assign the event-specific data to it. Then all handlers can access it as `event.detail`. +Para eventos personalizados deberíamos usar el constructor `CustomEvent`. Este tiene una opción adicional llamada `detail` a la que podemos asignarle los datos específicos del evento. De esta forma, todos los controladores pueden accederlos como `event.detail`. -Despite the technical possibility to generate browser events like `click` or `keydown`, we should use with the great care. +A pesar de la posibilidad técnica de generar eventos del navegador como `click` o `keydown`, debemos usarlo con mucho cuidado. -We shouldn't generate browser events as it's a hacky way to run handlers. That's a bad architecture most of the time. +No deberíamos generar eventos de navegador, ya que es una forma trillada de ejecutar controladores. Esa es una mala arquitectura la mayor parte del tiempo. -Native events might be generated: +Se pueden generar eventos nativos: -- As a dirty hack to make 3rd-party libraries work the needed way, if they don't provide other means of interaction. -- For automated testing, to "click the button" in the script and see if the interface reacts correctly. +- Como un truco sucio para hacer que las bibliotecas de terceros funcionen de la manera necesaria, si es que ellas no proporcionan otros medios de interacción. +- Para pruebas automatizadas, que el script "haga clic en el botón" y vea si la interfaz reacciona correctamente. -Custom events with our own names are often generated for architectural purposes, to signal what happens inside our menus, sliders, carousels etc. +Los eventos personalizados con nuestros propios nombres a menudo se generan con fines arquitectónicos, para señalar lo que sucede dentro de nuestros menús, controles deslizantes, carruseles, etc.