مدیریت رویدادها - Event Handling ​

گوش دادن به رویدادها ​

برای گوش دادن به رویدادهای DOM و اجرای کد جاوا اسکریپت در زمانی‌که آن رویدادها رخ می‌دهند، می‌توانیم از دستور v-on استفاده کنیم که معمولاً آن را به @ خلاصه می‌کنیم. استفاده کردن از آن به صورت v-on:click="handler"‎ یا با میانبر ‎@click="handler"‎ خواهد بود.

مقدار handler می‌تواند یکی از موارد زیر باشد:

1. درون‌خطی (Inline handlers): جاوا اسکریپت درون‌خطی هنگام فراخوانی رویداد اجرا می‌شود (همانند ویژگی onclick در جاوا اسکریپت بومی).

2. متد (Method handlers): نام پراپرتی یا مسیری که به یک متد تعریف شده در کامپوننت اشاره می‌کند.

درون‌خطی (Inline handlers) ​

این روش معمولاً در موارد ساده استفاده می‌شوند، به عنوان مثال:

const count = ref(0)

data() {
  return {
    count: 0
  }
}

<button @click="count++">Add 1</button>
<p>Count is: {{ count }}</p>

متد (Method handlers) ​

منطق بسیاری از کنترل کننده‌های رویداد (event handlers) پیچیده‌تر است و احتمالا با کنترل کننده‌های inline امکان‌پذیر نیست. به همین دلیل v-on همچنین می‌تواند نام یا مسیری از متدِ کامپوننت که می‌خواهید صدا بزنید، بپذیرد.

به عنوان مثال:

const name = ref('Vue.js')

function greet(event) {
  alert(`Hello ${name.value}!`)
  // است DOM رویداد بومی `event`
  if (event) {
    alert(event.target.tagName)
  }
}

data() {
  return {
    name: 'Vue.js'
  }
},
methods: {
  greet(event) {
    // داخل متدها به نمونه کامپوننت فعال کنونی اشاره می‌کند `this`
    alert(`Hello ${this.name}!`)
    // است DOM رویداد بومی `event`
    if (event) {
      alert(event.target.tagName)
    }
  }
}

<!-- نام متد تعریف شده در بالا است `greet` -->
<button @click="greet">Greet</button>

متد کنترل کننده به طور خودکار آبجکت event بومی DOM، که رویداد آن را پاس می‌دهد، دریافت می‌کند - در مثال بالا، ما قادر به دسترسی به نام عنصر ارسال کننده رویداد از طریق event.target هستیم.

Method در مقابل Inline Detection ​

کامپایلر تمپلیت، کنترل کننده‌های متد را با بررسی اینکه آیا مقدار رشته v-on یک شناسه جاوااسکریپت معتبر یا مسیر دسترسی به یک پراپرتی است، تشخیص می‌دهد. به عنوان مثال foo و foo.bar و foo['bar'] به عنوان کنترل کننده‌های متد در نظر گرفته می‌شوند، در حالی که foo()‎ و count++‎ به عنوان کنترل کننده‌های درون خطی در نظر گرفته می‌شوند.

صدا زدن متدها در Inline Handlers ​

به جای اتصال مستقیم به نام متد، ما همچنین می‌توانیم متدها را در یک inline handler صدا بزنیم. این به ما اجازه می‌دهد تا به جای رویداد بومی، آرگومان‌های سفارشی به متد ارسال کنیم:

function say(message) {
  alert(message)
}

methods: {
  say(message) {
    alert(message)
  }
}

<button @click="say('hello')">Say hello</button>
<button @click="say('bye')">Say bye</button>

دسترسی به آرگومان event در Inline Handlers ​

گاهی اوقات ما همچنین نیاز به دسترسی به رویداد DOM اصلی در یک کنترل کننده درون خطی داریم. شما می‌توانید آن را با استفاده از متغیر ویژه ‎$event به یک متد منتقل کنید، یا از یک arrow function تک خطی استفاده کنید:

<!-- $event استفاده از متغیر ویژه --> 
<button @click="warn('Form cannot be submitted yet.', $event)">
  Submit
</button>

<!-- inline arrow function استفاده از  -->
<button @click="(event) => warn('Form cannot be submitted yet.', event)">
  Submit
</button>

function warn(message, event) {
  // اکنون ما دسترسی به رویداد بومی داریم
  if (event) {
    event.preventDefault()
  }
  alert(message)
}

methods: {
  warn(message, event) {
    // اکنون ما دسترسی به رویداد بومی داریم
    if (event) {
      event.preventDefault()
    }
    alert(message)
  }
}

تغییردهنده‌های رویداد - Event Modifiers ​

نیاز بسیار متداولی است که event.preventDefault()‎ یا event.stopPropagation()‎ را در داخل کنترل‌کننده‌های رویداد صدا بزنیم. اگرچه ما می‌توانیم به راحتی این کار را در داخل متدها انجام دهیم، بهتر است متدها به‌طور خاص برای یک عمل طراحی شده باشند و نیازی نباشد با جزئیات رویدادهای DOM سروکار داشته باشند.

برای حل این مشکل، Vue تغییردهنده‌های رویداد (event modifiers) را برای v-on ارائه می‌دهد. به یاد داشته باشید که تغییردهنده‌ها، پسوندهای دایرکتیوها هستند که با یک نقطه مشخص می‌شوند.

• ‎.stop
• ‎.prevent
• ‎.self
• ‎.capture
• ‎.once
• ‎.passive

<!-- the click event's propagation will be stopped -->
<a @click.stop="doThis"></a>

<!-- the submit event will no longer reload the page -->
<form @submit.prevent="onSubmit"></form>

<!-- modifiers can be chained -->
<a @click.stop.prevent="doThat"></a>

<!-- just the modifier -->
<form @submit.prevent></form>

<!-- only trigger handler if event.target is the element itself -->
<!-- i.e. not from a child element -->
<div @click.self="doThat">...</div>

تغییردهنده‌های ‎.capture و ‎.once و ‎.passive نماینده آپشن‌های متد بومی addEventListener هستند:

<!-- استفاده کن capture هنگام اضافه کردن کنترل کننده رویداد از حالت -->
<!--                یعنی رویدادی که یک عنصر داخلی را هدف قرار می‌دهد -->
<!--     قبل از اینکه توسط آن عنصر مدیریت شود در اینجا مدیریت می‌شود -->
<div @click.capture="doThis">...</div>

<!-- رویداد کلیک حداکثر یک بار فعال می شود -->
<a @click.once="doThis"></a>

<!--   رفتار پیش‌فرض رویداد اسکرول (پیمایش) اتفاق می‌افتد  -->
<!-- باشید «onScroll» بلافاصله، به جای اینکه منتظر تکمیل  -->
<!--     باشد «event.preventDefault()» در صورتی که حاوی  -->
<div @scroll.passive="onScroll">...</div>

تغییردهنده‌ ‎.passive معمولاً با کنترل کننده‌های رویداد لمسی برای بهبود عملکرد روی دستگاه‌های موبایل استفاده می‌شود.

Key Modifiers ​

وقتی که می‌خواهیم به رویدادهای صفحه‌کلید گوش دهیم، اغلب باید کلیدهای خاصی را بررسی کنیم. Vue اجازه اضافه کردن modifier های کلید را برای v-on یا @ هنگام گوش دادن به رویدادهای صفحه‌کلید می‌دهد:

<!-- صدا می‌زند `submit` باشد `Enter` ، `key` فقط زمانی که -->
<input @keyup.enter="submit" />

شما می‌توانید مستقیماً از هر نام کلید معتبری که از طریق KeyboardEvent.key در اختیار قرار گرفته است به عنوان تغییردهنده‌ با تبدیل آن‌ها به فرم kebab-case استفاده کنید.

<input @keyup.page-down="onPageDown" />

در مثال بالا، کنترل کننده فقط در صورتی صدا زده خواهد شد که ‎$event.key برابر با 'PageDown' باشد.

Key Aliases ​

Vue میانبرهایی برای پرکاربردترین کلیدها ارائه می‌دهد:

• ‎.enter
• ‎.tab
• ‎.delete (هم کلید «Delete» و هم «Backspace» را شامل می‌شود)
• ‎.esc
• ‎.space
• ‎.up
• ‎.down
• ‎.left
• ‎.right

System Modifier Keys ​

شما می‌توانید از تغییردهنده‌های زیر برای فعال کردن کنترل‌کننده‌های رویداد ماوس یا صفحه‌کلید فقط زمانی‌که کلید مربوطه فشرده شده باشد، استفاده کنید:

• ‎.ctrl
• ‎.alt
• ‎.shift
• ‎.meta

به‌عنوان مثال:

<!-- Alt + Enter -->
<input @keyup.alt.enter="clear" />

<!-- Ctrl + Click -->
<div @click.ctrl="doSomething">Do something</div>

‎.exact Modifier ​

تغییردهنده‌ ‎.exact اجازه کنترل ترکیب دقیق تغییردهنده‌های سیستم مورد نیاز برای فعال سازی یک رویداد را می‌دهد.

<!-- هم فشرده شود اجرا می‌شود Alt یا Shift این حتی اگر -->
<button @click.ctrl="onClick">A</button>

<!-- فشرده شده و هیچ کلید دیگری نباشد اجرا می‌شود Ctrl این فقط هنگامی که فقط  --> 
<button @click.ctrl.exact="onCtrlClick">A</button>

<!-- دیگری فشرده نشده باشد modifier این فقط زمانی اجرا می‌شود که هیچ -->
<button @click.exact="onClick">A</button>

تغییردهنده‌های دکمه ماوس ​

• ‎.left
• ‎.right
• ‎.middle

این تغییردهنده‌ها، کنترل‌کننده را محدود به رویدادهایی می‌کنند که توسط دکمه خاصی از ماوس فعال شده‌اند.

با این حال، توجه داشته باشید که نام‌های تغییر دهنده‌ی ‎.left ، ‎.right و ‎.middle بر اساس چیدمان معمول موس برای افراد راست‌دست تعیین شده‌اند. اما در واقع، این نام‌ها به ترتیب نشان‌دهنده‌ی رویدادهای دستگاه‌های اشاره‌گر یعنی "اصلی"، "فرعی" و "کمکی" هستند و به دکمه‌های فیزیکی مربوط نمی‌شوند. بنابراین، در چیدمان موس چپ‌دست، ممکن است دکمه "اصلی" فیزیکی همان دکمه راست باشد، ولی تغییر دهنده‌ی ‎.left را فعال کند. برای مثال، یک ترک‌پد ممکن است با یک ضربه یک‌انگشتی تغییر دهنده‌ی ‎.left، با یک ضربه دو انگشتی تغییر دهنده‌ی ‎.right و با یک ضربه سه‌انگشتی تغییر دهنده‌ی ‎.middle را فعال کند. به طور مشابه، دستگاه‌ها و منابع رویدادی دیگری که رویدادهای "موس" تولید می‌کنند، ممکن است روش‌های فعال‌سازی داشته باشند که اصلاً به "چپ" و "راست" ربطی نداشته باشند.