رویداد های کامپوننت ​

این صفحه فرض می کند که شما از قبل اصول اولیه کامپوننت ها را خوانده اید. اگر در مبحث کامپوننت ها تازه وارد هستید اول آن را مطالعه کنید .

اِمیت کردن و گوش دادن به رویدادها ​

یک کامپوننت می‌تواند رویدادهای سفارشی را مستقیماً در عبارات تمپلیت (مثلاً در کنترل‌کننده «v-on») با استفاده از روش «$emit» نهادینه شده منتشر کند:

<!-- MyComponent -->
<button @click="$emit('someEvent')">click me</button>

export default {
  methods: {
    submit() {
      this.$emit('someEvent')
    }
  }
}

والد بعدا می تواند با استفاده از v-on به آن گوش دهد:

<MyComponent @some-event="callback" />

پیراینده .once در شنوندگان رویداد(event listeners) کامپوننت نیز پشتیبانی می‌شود:

<MyComponent @some-event.once="callback" />

مانند کامپوننت‌ها و پراپ ها، نام رویدادها یک تغییر حالت خودکار را ایجاد می‌کنند. توجه کنید که ما یک رویداد camelCase را منتشر کردیم، اما می‌توانیم آن را با استفاده از شنونده kebab-cased در والد گوش دهیم. مانند props casing، توصیه می‌کنیم از شنونده‌های رویداد kebab-cased در تمپلیت ها استفاده کنید.

آرگومان های رویداد ​

گاهی اوقات انتشار یک مقدار خاص همراه با یک رویداد مفید است. به عنوان مثال، ممکن است بخواهیم کامپوننت <BlogPost> مسئول میزان بزرگ‌نمایی متن باشد. در این موارد، می‌توانیم آرگومان‌های اضافی را به $emit ارسال کنیم تا این مقدار را ارائه کنیم:

<button @click="$emit('increaseBy', 1)">
  Increase by 1
</button>

سپس، هنگامی که به رویداد در والد گوش می دهیم، می توانیم از یک تابع پیکان درون خطی به عنوان شنونده استفاده کنیم که به ما امکان می دهد به آرگومان رویداد دسترسی پیدا کنیم:

<MyButton @increase-by="(n) => count += n" />

یا اگر کنترل کننده رویداد(event handler) یک متد باشد:

<MyButton @increase-by="increaseCount" />

سپس مقدار به عنوان اولین پارامتر آن متد ارسال می شود:

methods: {
  increaseCount(n) {
    this.count += n
  }
}

function increaseCount(n) {
  count.value += n
}

اعلام رویدادهای اِمیت شده ​

یک کامپوننت به صراحت می تواند رویدادهایی را که اِمیت می کند با استفاده از ماکرو defineEmits() اعلام کندگزینه(option) emits اعلام کند:

<script setup>
defineEmits(['inFocus', 'submit'])
</script>

<script setup>
const emit = defineEmits(['inFocus', 'submit'])

function buttonClick() {
  emit('submit')
}
</script>

export default {
  emits: ['inFocus', 'submit'],
  setup(props, ctx) {
    ctx.emit('submit')
  }
}

export default {
  emits: ['inFocus', 'submit'],
  setup(props, { emit }) {
    emit('submit')
  }
}

export default {
  emits: ['inFocus', 'submit']
}

گزینه emits و ماکرو defineEmits()‎ همچنین از syntax شیء پشتیبانی می‌کنند که به ما اجازه می‌دهد payload رویدادهای ارسال شده را در زمان اجرا Validate کنیم:

<script setup>
const emit = defineEmits({
  submit(payload) {
    // مقدار `true` یا `false` را برای نشان دادن
    // اعتبارسنجی موفقیت آمیز / شکست خورده برمی گرداند
  }
})
</script>

<script setup lang="ts">
const emit = defineEmits<{
  (e: 'change', id: number): void
  (e: 'update', value: string): void
}>()
</script>

export default {
  emits: {
    submit(payload) {
      // مقدار `true` یا `false` را برای نشان دادن
      // اعتبارسنجی موفقیت آمیز / شکست خورده برمی گرداند
    }
  }
}

اگر چه اختیاری است، پیشنهاد می شود همه رویدادهای اِمیت شده را تعریف کنید تا نحوه کار یک کامپوننت را بهتر مستند کنید. همچنین به Vue اجازه می دهد شنوندگان (listeners) شناخته شده را از fallthrough attributes حذف کند، از موارد لبه ناشی از رویدادهای DOM که به صورت دستی توسط کد شخص ثالث ارسال می شوند، اجتناب می کند.

اعتبارسنجی رویدادها ​

مشابه اعتبارسنجی نوع prop، یک رویداد اِمیت شده می تواند اعتبار سنجی شود اگر به جای نحو آرایه با نحو شی تعریف شده باشد.

برای افزودن اعتبارسنجی، به رویداد تابعی اختصاص داده می‌شود که آرگومان‌های ارسال شده به فراخوانی this.$emitemit را دریافت می‌کند و برای نشان دادن معتبر بودن یا نبودن رویداد، یک boolean برمی‌گرداند.

<script setup>
const emit = defineEmits({
  // بدون اعتبارسنجی
  click: null,

  // اعتبارسنجی رویداد submit
  submit: ({ email, password }) => {
    if (email && password) {
      return true
    } else {
      console.warn('Invalid submit event payload!')
      return false
    }
  }
})

function submitForm(email, password) {
  emit('submit', { email, password })
}
</script>

export default {
  emits: {
    // بدون اعتبارسنجی
    click: null,

    // اعتبارسنجی رویداد submit
    submit: ({ email, password }) => {
      if (email && password) {
        return true
      } else {
        console.warn('Invalid submit event payload!')
        return false
      }
    }
  },
  methods: {
    submitForm(email, password) {
      this.$emit('submit', { email, password })
    }
  }
}