diff --git a/2-ui/2-events/05-dispatch-events/article.md b/2-ui/2-events/05-dispatch-events/article.md index 047413fd3..e95a1c7f0 100644 --- a/2-ui/2-events/05-dispatch-events/article.md +++ b/2-ui/2-events/05-dispatch-events/article.md @@ -1,58 +1,58 @@ -# Dispatching custom events +# Dispatchکردن eventهای شخصی سازی شده -We can not only assign handlers, but also generate events from 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. +از custom events می توان برای ایجاد "مولفه های گرافیکی" استفاده کرد. به عنوان مثال، یک عنصر ریشه از منوی مبتنی بر JS خودمان ممکن است رویدادهایی را ایجاد کند که میگوید چه اتفاقی در منو میافتد: باز کردن (باز کردن منو)، انتخاب (یک مورد انتخاب شده است) و غیره. کد دیگری ممکن است به event ها گوش دهد و آنچه را که در منو اتفاق می افتد مشاهده کند. -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. +ما میتوانیم نه تنها event های کاملاً جدیدی را که برای اهداف خود اختراع میکنیم، بلکه همچنین event های داخلی مانند کلیک، پایین آوردن ماوس و غیره را ایجاد کنیم. ممکن است برای تست خودکار نرم افزار مفید باشد. ## Event constructor -Built-in event classes form a hierarchy, similar to DOM element classes. The root is the built-in [Event](https://dom.spec.whatwg.org/#events) class. +کلاس های event متعلق به زبان یک سلسله مراتب را تشکیل می دهند، مشابه کلاس های عنصر DOM. ریشه آن، کلاس درونساخت [Event](https://dom.spec.whatwg.org/#events) است. -We can create `Event` objects like this: +ما می توانیم اشیاء event را به این صورت ایجاد کنیم: ```js let event = new Event(type[, options]); ``` -Arguments: +پارامتر ها: -- *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*: event type, یک رشته مانند `"click"` . +- *options*: شی ای با دو ویژگی اختیاری. + - *Bubbles*:اگر true بود یعنی bubbled می شود. + - *cancelable (true/false)*: اگر ویزگی مقدار true را داشت عمل پیش فرض آن لغو میشود، + + به صورت پیش فرض: `{bubbles: false, cancelable: false}`. - By default both are false: `{bubbles: false, cancelable: false}`. + ## dispatchEvent -## dispatchEvent +پس از ایجاد یک event، باید آن را روی یک element با استفاده از فراخوانی `elem.dispatchEvent(event)` اجرا کنیم. -After an event object is created, we should "run" it on an element using the call `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. - -In the example below the `click` event is initiated in JavaScript. The handler works same way as if the button was clicked: +سپس هندلر ها به آن واکنش نشان می دهند که گویی یک event معمولی مرورگر است. اگر event با bubble flag ها ایجاد شده باشد، bubbled می شود. +در مثال زیر رویداد `click` در جاوااسکریپت آغاز می شود. هندلر به همان روشی کار می کند که اگر روی دکمه کلیک شده باشد: ```html run no-beautify ``` ```smart header="event.isTrusted" -There is a way to tell a "real" user event from a script-generated one. -The property `event.isTrusted` is `true` for events that come from real user actions and `false` for script-generated events. -``` + راهی برای تشخیص یک user event "واقعی" از event تولید شده توسط اسکریپت وجود دارد. -## Bubbling example + ویژگی 'event.isTrusted' برای رویدادهایی که از اقدامات کاربر واقعی ناشی می شوند 'true' و برای رویدادهای تولید شده توسط اسکریپت 'false' است. +``` +## مثالی از Bubbling -We can create a bubbling event with the name `"hello"` and catch it on `document`. +میتوانیم یک bubbling event با نام `"hello"` ایجاد کنیم و آن را در `document` بگیریم. -All we need is to set `bubbles` to `true`: +تنها چیزی که نیاز داریم این است که `bubbles` را روی `true` تنظیم کنیم: ```html run no-beautify
@@ -206,17 +206,17 @@ Any handler can listen for that event with `rabbit.addEventListener('hide',...)` ``` -Please note: the event must have the flag `cancelable: true`, otherwise the call `event.preventDefault()` is ignored. +نکته: event حتما باید `cancelable: true` را داشته باشد یا اینکه `event.preventDefault()` فراخوانی نمی شود. ## Events-in-events are synchronous -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 its handling is queued up, corresponding `mousemove` handlers will be called after `onclick` processing is finished. +معمولا رویدادها در یک صف پردازش می شوند. یعنی: اگر مرورگر در حال پردازش `onclick` باشد و یک رویداد جدید رخ دهد، به عنوان مثال: ماوس حرکت می کند، سپس handling آن در صف قرار می گیرد، پس از اتمام پردازش `onclick`، کنترل کننده های مربوط به `mousemove` فراخوانی می شوند. -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. +استثنا قابل توجه زمانی است که یک رویداد از درون رویداد دیگری آغاز می شود، به عنوان مثال: با استفاده از `dispatchEvent` چنین رویدادهایی بلافاصله پردازش میشوند: کنترلکنندههای رویداد جدید فراخوانی میشوند و سپس مدیریت رویداد فعلی از سر گرفته میشود. -For instance, in the code below the `menu-open` event is triggered during the `onclick`. +به عنوان مثال، در کد زیر، رویداد `menu-open` در حین `onclick` فعال می شود. -It's processed immediately, without waiting for `onclick` handler to end: +بدون اینکه برای `onclick` هندلر صبر کند تا تمام شود، شروع به پردازش می شود: ```html run autorun @@ -238,15 +238,15 @@ It's processed immediately, without waiting for `onclick` handler to end: ``` -The output order is: 1 -> nested -> 2. +ترتیب خروجی این است: 1 -> تودرتو (nested) -> 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`). +لطفاً توجه داشته باشید که منوی رویداد تودرتو که باز است در `document` وجود دارد. انتشار و مدیریت رویداد تودرتو قبل از اینکه پردازش به کد خارجی بازگردد (`onclick`) به پایان می رسد. -That's not only about `dispatchEvent`, there are other cases. If an event handler calls methods that trigger other events -- they are processed synchronously too, in a nested fashion. +این فقط مربوط به `dispatchEvent` نیست، موارد دیگری نیز وجود دارد. اگر یک کنترل کننده event متدهایی را فراخوانی کند که رویدادهای دیگر را راهاندازی میکنند، آنها نیز به صورت همزمان و به صورت تودرتو پردازش میشوند. -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. +بیایید بگوییم که آن را دوست نداریم. ما می خواهیم ابتدا `onclick` به طور کامل پردازش شود، مستقل از `menu-open` یا هر رویداد تو در تو. -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`: +سپس میتوانیم `dispatchEvent` (یا یک فراخوانی event-triggering) را در انتهای `onclick` قرار دهیم یا، شاید بهتر، آن را در `setTimeout` با تاخیر صفر قرار دهیم: ```html run @@ -266,29 +266,29 @@ Then we can either put the `dispatchEvent` (or another event-triggering call) at ``` -Now `dispatchEvent` runs asynchronously after the current code execution is finished, including `menu.onclick`, so event handlers are totally separate. +حالا `dispatchEvent` یه صورت asynchronously بعد از اینکه اجرای کد فعلی به اتمام رسید، run میشود، که شامل `menu.onclick`. پس event handler ها به صورت جدت و مستقل فعالیت میکنند. -The output order becomes: 1 -> 2 -> nested. +خروجی به این ترتیب خواهد بود: 1 -> 2 -> nested. -## Summary +## خلاصه -To generate an event from code, we first need to create an event object. +برای تولید یک event code، ابتدا باید یک event object ایجاد کنیم. -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. +سازنده `Event(name, options)` یک نام رویداد دلخواه و `options` object را با دو ویژگی میپذیرد: +- `bubbles: true` اگر رویداد باید حباب شود. +- `cancelable: true` اگر `event.preventDefault()` باید کار کند. -Other constructors of native events like `MouseEvent`, `KeyboardEvent` and so on accept properties specific to that event type. For instance, `clientX` for mouse events. +سایر سازندههای native events مانند `MouseEvent`, `KeyboardEvent` و غیره ویژگیهای خاص آن نوع رویداد را میپذیرند. به عنوان مثال، `clientX` برای رویدادهای ماوس. -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`. +برای custom events باید از سازنده `CustomEvent` استفاده کنیم. این یک گزینه اضافی به نام `detail` دارد، ما باید داده های رویداد خاص را به آن اختصاص دهیم. سپس همه کنترل کننده ها می توانند به عنوان `event.detail` به آن دسترسی داشته باشند. -Despite the technical possibility of generating browser events like `click` or `keydown`, we should use them with great care. +علیرغم امکان فنی ایجاد browser events مانند `click` یا `keydown`، ما باید با دقت زیادی از آنها استفاده کنیم. -We shouldn't generate browser events as it's a hacky way to run handlers. That's bad architecture most of the time. +ما نباید browser events را ایجاد کنیم زیرا این یک روش هک برای اجرای کنترلرها است. این معماری در بیشتر مواقع بد است. -Native events might be generated: +هم چنین native events ممکن است ایجاد شوند: -- 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. +- به عنوان یک dirty hack برای اینکه کتابخانه های شخص ثالث به روش مورد نیاز کار کنند، اگر ابزارهای تعامل دیگری را ارائه ندهند. +- برای تست خودکار، روی دکمه "click the button" در اسکریپت و ببینید که آیا رابط به درستی واکنش نشان می دهد. -Custom events with our own names are often generated for architectural purposes, to signal what happens inside our menus, sliders, carousels etc. + همچنین eventهای سفارشی با نام خود ما اغلب برای مقاصد معماری ایجاد می شوند تا نشان دهند که چه اتفاقی در منوها، اسلایدرها و غیره می افتد.